Protocole WebSocket¶

Sources : crates/orapa-server/src/protocol.rs (types), ws.rs (connexion), logic.rs (traitement), et le miroir TypeScript web/src/types/protocol.ts.

Transport¶

• Point d'entrée : GET /ws (upgrade WebSocket), sur la même origine que le client (ws:// ou wss:// selon la page).
• Trames texte contenant un objet JSON. Les autres trames sont ignorées, une trame Close termine la connexion.
• Chaque message porte un champ type égal au nom de la variante (CreateGame, StateUpdate…).
• Les sous-objets BeamOutcome, Violation et HistoryEntry sont discriminés par un champ kind. Les énumérations simples (Phase, GemColor, ResultColor, ProbeOutcome) sont en snake_case.
• Un JSON illisible ou un type inconnu renvoie Error { code: "bad_message" }. La connexion reste ouverte.

Cycle de vie d'une connexion¶

1. Non liée : seuls CreateGame, JoinGame, Reconnect et StartSolo sont acceptés. Tout autre message renvoie Error not_bound.
2. Liée à un couple (partie, index joueur) : les messages de jeu sont routés vers logic.rs. Renvoyer l'un des 4 messages d'établissement donne Error already_bound.
3. Fermeture : le joueur passe connected: false, un StateUpdate est diffusé. La partie reste en mémoire et le jeton permet d'y revenir.

États de partie¶

stateDiagram-v2
  [*] --> lobby: CreateGame
  [*] --> playing: StartSolo
  lobby --> placement: JoinGame du 2e joueur
  placement --> playing: les 2 joueurs prêts
  playing --> finished: proposition décisive
  finished --> placement: RequestRematch des 2 joueurs (duel)
  finished --> playing: RequestRematch (solo)

La mort subite n'est pas une phase : c'est le booléen sudden_death de StateUpdate, levé quand le premier joueur trouve la solution (voir Règles).

Types communs¶

RoomOptions¶

Tous les champs ont une valeur par défaut côté serveur (#[serde(default)]) et peuvent être omis. L'objet options lui-même reste obligatoire dans CreateGame et StartSolo.

Autres structures¶

• actor est l'index du joueur qui a fait l'action (sur la grille de son adversaire).
• Les index de Violation renvoient aux positions dans le tableau pieces soumis.
• Les valeurs de ResultColor sont listées dans Règles › Mélange des couleurs.

Messages client → serveur¶

En solo, FireBeam, Probe et SubmitSolution ne vérifient pas le tour.

Messages serveur → client¶

StateUpdate¶

GameOver¶

• winner : index du gagnant, ou null pour une égalité (duel) ou un échec (solo, plus de vie).
• boards[i] : disposition secrète défendue par le joueur i. En solo, boards[0] est vide et boards[1] contient la disposition générée.

Codes d'erreur¶

Le client affiche message dans un bandeau (un clic le ferme).

Exemple : déroulé d'un duel¶

sequenceDiagram
  participant A as Alice (index 0)
  participant S as Serveur
  participant B as Bob (index 1)
  A->>S: CreateGame
  S-->>A: GameCreated (code, token) + StateUpdate lobby
  B->>S: JoinGame (code)
  S-->>B: Joined (token)
  S-->>A: StateUpdate placement
  S-->>B: StateUpdate placement
  A->>S: SetPlacement + ReadyToPlay
  B->>S: SetPlacement + ReadyToPlay
  S-->>A: StateUpdate playing (current_turn tiré au sort)
  S-->>B: StateUpdate playing
  loop Tours alternés
    A->>S: FireBeam / Probe / SubmitSolution
    S-->>A: BeamResult / ProbeResult / SolutionResult
    S-->>A: StateUpdate
    S-->>B: StateUpdate
  end
  S-->>A: GameOver (winner, boards, history)
  S-->>B: GameOver

Échange minimal (valeurs d'exemple) :

{"type":"CreateGame","pseudo":"Alice","options":{"diamond":false,"black":false,"lives":1,"turn_timer_secs":null,"help_mode":true}}
{"type":"GameCreated","code":"KQXRT","token":"<uuid v4>","player_index":0}
{"type":"FireBeam","entry":"C"}
{"type":"BeamResult","entry":"C","outcome":{"kind":"Exit","point":"14","color":"purple"}}

Reconnexion¶

• Le client renvoie Reconnect { token } à chaque réouverture du socket (voir Architecture). Le serveur remplace l'émetteur du joueur, le repasse connected: true et diffuse un StateUpdate.
• GameCreated / Joined ne sont pas renvoyés : le client ne récupère donc pas le code de partie, absent de StateUpdate.
• your_placement permet de restaurer la grille du joueur, si aucune édition locale n'est en cours.

Sécurité et confiance¶

• Les dispositions secrètes ne quittent le serveur que dans GameOver, dans your_placement (pour son propre auteur) et dans SolutionRevealed (solo uniquement).
• L'identité d'un joueur repose uniquement sur son jeton UUID v4, conservé dans le localStorage du navigateur.
• Le serveur ne valide ni la longueur du pseudo ni la valeur de lives : c'est le client qui limite à 20 caractères et à 1 ou 2 vies.