[Networking] Doxygen

doc/doxygen/extra-pages/developer_documentation/network/protocol/index.md

@@ -0,0 +1,15 @@
+@page developer_reference_protocol Protocol (Overview)
+
+For an overview of the protocol used by the Cockatrice client and server, see:
+
+- @subpage developer_reference_protocol_overview
+- @subpage protocol_game_command
+
+For client → server communication, see:
+
+- @subpage protocol_command_container
+
+For server → client communication, see:
+
+- @subpage protocol_server_message
+- @subpage protocol_response

doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_command_container.md

@@ -0,0 +1,114 @@
+@page protocol_command_container CommandContainer (Protocol Concept)
+
+@section cc_overview Overview
+
+CommandContainer is the client-to-server message envelope used for all
+client requests in the Cockatrice protocol.
+
+Every client-initiated action is transmitted as a CommandContainer.
+The server never sends CommandContainer messages.
+
+This is a protocol-level abstraction and should not be confused with the
+generated protobuf accessors or wire-level encoding.
+
+@section cc_lifecycle Lifetime and Ownership
+
+- CommandContainers are created by clients and consumed by the server.
+- Each container represents one logical request.
+- Containers are processed atomically and in order of arrival.
+
+A container may generate:
+- Exactly one RESPONSE message, and
+- Zero or more EVENT messages.
+
+@section cc_cmd_id Command Identification
+
+The @c cmd_id field is a client-assigned identifier used to correlate
+responses with requests.
+
+Rules:
+- @c cmd_id is optional but strongly recommended
+- The server echoes @c cmd_id only in RESPONSE messages
+- EVENT messages are never associated with a @c cmd_id
+
+The server does not enforce uniqueness of @c cmd_id values.
+
+@section cc_context Command Context
+
+Certain command domains require additional context:
+
+- Room commands require @c room_id
+- Game commands require @c game_id
+
+Context fields are ignored for command domains that do not require them.
+
+If a required context field is missing or invalid, the server responds with
+@c RespContextError.
+
+@section cc_invariants Invariants
+
+The following rules are enforced by the server:
+
+- Exactly one command domain must be populated
+- Commands may be batched only within the same domain
+- Context fields must match the active command domain
+
+Violations of these rules result in @c RespInvalidCommand.
+
+@section cc_domains Command Domains
+
+CommandContainer supports the following mutually exclusive command domains:
+
+- Session commands
+  - Authentication
+  - User discovery
+  - Private messaging
+
+- Room commands
+  - Chat
+  - Game creation
+  - Room membership management
+
+- Game commands
+  - In-game actions
+  - State mutations
+
+- Moderator commands
+  - User moderation
+  - Room moderation
+
+- Admin commands
+  - Server administration
+
+@section cc_batching Command Batching
+
+A CommandContainer may contain multiple commands of the same domain.
+
+Batching guarantees:
+- Commands are processed in the order they appear in the container
+- All commands in the batch share the same context
+
+Partial failure behavior is implementation-defined and may vary by domain.
+
+@section cc_dispatch Dispatch
+
+CommandContainers are dispatched by
+Server_ProtocolHandler::processCommandContainer().
+
+Dispatch is performed by inspecting which command domain is populated.
+Only the first populated domain is considered.
+
+@section cc_errors Error Handling
+
+Common error responses include:
+- @c RespLoginNeeded – client is not authenticated
+- @c RespInvalidCommand – malformed container or invalid domain usage
+- @c RespContextError – missing or invalid room/game context
+
+@section cc_related Related Concepts
+
+- @ref protocol_server_message "ServerMessage"
+- @ref protocol_client_states "Client State Machine"
+
+@see Server_ProtocolHandler::processCommandContainer
+

doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_game_command.md

@@ -0,0 +1,440 @@
+@page protocol_game_command GameCommand (Protocol Concept)
+
+# Game Commands Reference
+
+This document describes game-level commands (`GameCommandType`) and how they are
+handled across the server and client.
+
+Flow overview:
+
+Client
+→ GameCommand
+→ Server_Game::handle*
+→ GameEvent(s)
+→ PlayerEventHandler::event*
+
+## Command Mapping
+
+### `GAME_SAY` (1002)
+
+**Purpose:** Send a chat message during a game.
+
+**Server:**
+- `Server_Game::handleGameSay`
+- Emits `Event_GameSay`
+
+**Client:**
+- `PlayerEventHandler::eventGameSay`
+
+---
+
+### `SHUFFLE` (1003)
+
+**Purpose:** Shuffle a card zone (usually library).
+
+**Server:**
+- `Server_Game::handleShuffle`
+- Reorders cards in zone
+- Emits `Event_Shuffle`
+
+**Client:**
+- `PlayerEventHandler::eventShuffle`
+- Clears revealed top cards
+- Closes affected zone views
+
+---
+
+### `ROLL_DIE` (1005)
+
+**Purpose:** Roll one or more dice.
+
+**Server:**
+- `Server_Game::handleRollDie`
+- Computes random values
+- Emits `Event_RollDie`
+
+**Client:**
+- `PlayerEventHandler::eventRollDie`
+
+---
+
+### `DRAW_CARDS` (1006)
+
+**Purpose:** Draw cards from deck.
+
+**Server:**
+- `Server_Game::handleDrawCards`
+- Moves cards from deck → hand
+- Emits `Event_DrawCards`
+
+**Client:**
+- `PlayerEventHandler::eventDrawCards`
+
+---
+
+### `UNDO_DRAW` (1007)
+
+**Purpose:** Undo a previous draw.
+
+**Server:**
+- `Server_Game::handleUndoDraw`
+- Uses `Context_UndoDraw`
+- Moves card(s) back to deck
+
+**Client:**
+- Handled via `PlayerEventHandler::eventMoveCard`
+- Logged as undo-draw context
+
+---
+
+### `FLIP_CARD` (1008)
+
+**Purpose:** Flip a card face up or face down.
+
+**Server:**
+- `Server_Game::handleFlipCard`
+- Updates card visibility
+- Emits `Event_FlipCard`
+
+**Client:**
+- `PlayerEventHandler::eventFlipCard`
+
+---
+
+### `ATTACH_CARD` (1009)
+
+**Purpose:** Attach one card to another.
+
+**Server:**
+- `Server_Game::handleAttachCard`
+- Updates attachment graph
+- Emits `Event_AttachCard`
+
+**Client:**
+- `PlayerEventHandler::eventAttachCard`
+
+---
+
+### `CREATE_TOKEN` (1010)
+
+**Purpose:** Create a token card.
+
+**Server:**
+- `Server_Game::handleCreateToken`
+- Allocates new card instance
+- Emits `Event_CreateToken`
+
+**Client:**
+- `PlayerEventHandler::eventCreateToken`
+
+---
+
+### `CREATE_ARROW` (1011)
+
+**Purpose:** Create a visual arrow.
+
+**Server:**
+- `Server_Game::handleCreateArrow`
+- Registers arrow ownership
+- Emits `Event_CreateArrow`
+
+**Client:**
+- `PlayerEventHandler::eventCreateArrow`
+
+---
+
+### `DELETE_ARROW` (1012)
+
+**Purpose:** Remove a visual arrow.
+
+**Server:**
+- `Server_Game::handleDeleteArrow`
+- Removes arrow
+- Emits `Event_DeleteArrow`
+
+**Client:**
+- `PlayerEventHandler::eventDeleteArrow`
+
+---
+
+### `SET_CARD_ATTR` (1013)
+
+**Purpose:** Set a card attribute.
+
+**Server:**
+- `Server_Game::handleSetCardAttr`
+- Emits `Event_SetCardAttr`
+
+**Client:**
+- `PlayerEventHandler::eventSetCardAttr`
+
+---
+
+### `SET_CARD_COUNTER` (1014)
+
+**Purpose:** Set a card counter.
+
+**Server:**
+- `Server_Game::handleSetCardCounter`
+- Emits `Event_SetCardCounter`
+
+**Client:**
+- `PlayerEventHandler::eventSetCardCounter`
+
+---
+
+### `INC_CARD_COUNTER` (1015)
+
+**Purpose:** Increment a card counter.
+
+**Server:**
+- `Server_Game::handleIncCardCounter`
+- Normalized to set-counter
+- Emits `Event_SetCardCounter`
+
+**Client:**
+- `PlayerEventHandler::eventSetCardCounter`
+
+---
+
+### `READY_START` (1016)
+
+**Purpose:** Mark player as ready.
+
+**Server:**
+- `Server_Game::handleReadyStart`
+- May call `doStartGameIfReady`
+
+**Client:**
+- Reflected via `Event_GameStateChanged`
+
+---
+
+### `CONCEDE` (1017)
+
+**Purpose:** Concede the game.
+
+**Server:**
+- `Server_Game::handleConcede`
+- Updates player state
+- May end game
+
+**Client:**
+- Reflected via game state events
+
+---
+
+### `INC_COUNTER` (1018)
+
+**Purpose:** Increment a global counter.
+
+**Server:**
+- `Server_Game::handleIncCounter`
+- Emits `Event_SetCounter`
+
+**Client:**
+- `PlayerEventHandler::eventSetCounter`
+
+---
+
+### `CREATE_COUNTER` (1019)
+
+**Purpose:** Create a global counter.
+
+**Server:**
+- `Server_Game::handleCreateCounter`
+- Emits `Event_CreateCounter`
+
+**Client:**
+- `PlayerEventHandler::eventCreateCounter`
+
+---
+
+### `SET_COUNTER` (1020)
+
+**Purpose:** Set a global counter value.
+
+**Server:**
+- `Server_Game::handleSetCounter`
+- Emits `Event_SetCounter`
+
+**Client:**
+- `PlayerEventHandler::eventSetCounter`
+
+---
+
+### `DEL_COUNTER` (1021)
+
+**Purpose:** Delete a global counter.
+
+**Server:**
+- `Server_Game::handleDelCounter`
+- Emits `Event_DelCounter`
+
+**Client:**
+- `PlayerEventHandler::eventDelCounter`
+
+---
+
+### `NEXT_TURN` (1022)
+
+**Purpose:** Advance to the next turn.
+
+**Server:**
+- `Server_Game::handleNextTurn`
+- Emits:
+  - `Event_SetActivePlayer`
+  - `Event_SetActivePhase`
+
+**Client:**
+- Reflected via game state events
+
+---
+
+### `SET_ACTIVE_PHASE` (1023)
+
+**Purpose:** Set active phase.
+
+**Server:**
+- `Server_Game::handleSetActivePhase`
+- Emits `Event_SetActivePhase`
+
+**Client:**
+- Reflected via game state events
+
+---
+
+### `DUMP_ZONE` (1024)
+
+**Purpose:** Dump zone contents.
+
+**Server:**
+- `Server_Game::handleDumpZone`
+- Emits `Event_DumpZone`
+
+**Client:**
+- `PlayerEventHandler::eventDumpZone`
+
+---
+
+### `REVEAL_CARDS` (1026)
+
+**Purpose:** Reveal specific cards.
+
+**Server:**
+- `Server_Game::handleRevealCards`
+- Emits `Event_RevealCards`
+
+**Client:**
+- `PlayerEventHandler::eventRevealCards`
+
+---
+
+### `MOVE_CARD` (1027)
+
+**Purpose:** Move a card between zones.
+
+**Server:**
+- `Server_Game::handleMoveCard`
+- Emits `Event_MoveCard`
+- May emit arrow cleanup events
+
+**Client:**
+- `PlayerEventHandler::eventMoveCard`
+
+---
+
+### `SET_SIDEBOARD_PLAN` (1028)
+
+**Purpose:** Set sideboard configuration.
+
+**Server:**
+- `Server_Game::handleSetSideboardPlan`
+- Stored server-side only
+
+**Client:**
+- Not forwarded as a game event
+
+---
+
+### `DECK_SELECT` (1029)
+
+**Purpose:** Select a deck.
+
+**Server:**
+- `Server_Game::handleDeckSelect`
+
+**Client:**
+- Reflected via lobby / game state
+
+---
+
+### `SET_SIDEBOARD_LOCK` (1030)
+
+**Purpose:** Lock or unlock sideboarding.
+
+**Server:**
+- `Server_Game::handleSetSideboardLock`
+
+**Client:**
+- Reflected via game state
+
+---
+
+### `CHANGE_ZONE_PROPERTIES` (1031)
+
+**Purpose:** Change zone properties.
+
+**Server:**
+- `Server_Game::handleChangeZoneProperties`
+- Emits `Event_ChangeZoneProperties`
+
+**Client:**
+- `PlayerEventHandler::eventChangeZoneProperties`
+
+---
+
+### `UNCONCEDE` (1032)
+
+**Purpose:** Undo a concede.
+
+**Server:**
+- `Server_Game::handleUnconcede`
+
+**Client:**
+- Reflected via game state
+
+---
+
+### `JUDGE` (1033)
+
+**Purpose:** Execute a command on behalf of another player.
+
+**Server:**
+- `Server_Game::handleJudge`
+- Unwraps `Command_Judge`
+- Dispatches embedded `GameCommand`
+
+**Client:**
+- Transparent; handled as normal commands
+
+---
+
+### `REVERSE_TURN` (1034)
+
+**Purpose:** Reverse turn order.
+
+**Server:**
+- `Server_Game::handleReverseTurn`
+- Toggles turn order flag
+
+**Client:**
+- Reflected via subsequent turn events
+
+---
+
+## Notes
+
+- Only commands emitting `GameEvent`s appear in `PlayerEventHandler`
+- Some commands affect game state without direct client events
+- Judge commands are transport-level wrappers, not gameplay primitives

doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_overview.md

@@ -0,0 +1,76 @@
+@page developer_reference_protocol_overview Protocol (Overview)
+
+# Cockatrice Server Protocol – Overview
+
+## Purpose
+
+This document describes the Cockatrice client/server protocol as implemented
+by the Cockatrice server. It is intended for developers implementing clients
+or modifying the server.
+
+The protocol is **stateful**, **event-driven**, and **asynchronous**.
+
+---
+
+## High-Level Properties
+
+- Encoding: Google Protocol Buffers
+- Transport: TCP or WebSocket (transport-agnostic at protocol level)
+- Directionality:
+    - Clients send `CommandContainer`
+    - Server sends `ServerMessage`
+- Responses and events are interleaved
+- Clients must handle unsolicited events at any time
+
+---
+
+## Message Envelopes
+
+### Client → Server: CommandContainer
+
+A `CommandContainer` represents one logical client request.
+
+Protocol invariants:
+- Exactly one command domain may be used per container
+- Multiple commands of the same domain may be batched
+- Context is provided via `room_id` or `game_id` when required
+
+Command domains:
+- Session commands
+- Room commands
+- Game commands
+- Moderator commands
+- Admin commands
+
+---
+
+### Server → Client: ServerMessage
+
+A `ServerMessage` represents either:
+- A response to a command (`RESPONSE`)
+- An unsolicited event (`*_EVENT`)
+
+Protocol invariants:
+- Events may be delivered before or after responses
+- Responses reference the original command via `cmd_id`
+- Events are never correlated to a command
+
+---
+
+## Asynchronous Model
+
+Clients MUST NOT assume request/response ordering.
+
+Example valid sequence:
+
+1. Client sends JOIN_ROOM
+2. Server sends room chat history events
+3. Server sends room join notifications
+4. Server sends JOIN_ROOM response
+
+---
+
+## Versioning
+
+The server reports a protocol version during connection initialization.
+Clients MUST verify compatibility before sending commands.

doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_response.md

@@ -0,0 +1,27 @@
+@page protocol_response Response (Protocol Concept)
+
+## Overview
+
+`Response` is the server-to-client message sent immediately after a command, using the same `cmd_id` to link to the originating command.  
+It provides a `Response::ResponseCode` and optionally a `Response::ResponseType` to guide client handling.
+
+## Fields
+
+- **cmd_id** (`uint64`, required) — Command ID this response corresponds to
+- **response_code** (`Response::ResponseCode`, optional) — Outcome of the command
+
+## Response Codes
+
+All possible outcome codes are defined in Response::ResponseCode
+
+These describe the result of the command, e.g., success, failure, or special conditions like bans or registration requirements.
+
+## Response Types
+
+Responses are routed according to Response::ResponseType
+
+Each `ResponseType` corresponds to a high-level category, like `JOIN_ROOM` or `DECK_UPLOAD`.
+
+## Extensions
+
+- Protobuf extensions from 100 to max are reserved for future use

doc/doxygen/extra-pages/developer_documentation/network/protocol/protocol_server_message.md

@@ -0,0 +1,171 @@
+@page protocol_server_message ServerMessage (Protocol Concept)
+
+## Overview
+
+`ServerMessage` is the server-to-client message envelope used for all
+communication originating from the Cockatrice server.
+
+The server never sends `CommandContainer` messages, and clients never send
+`ServerMessage` messages.
+
+A `ServerMessage` represents either:
+
+- A direct response to a client command, or
+- An unsolicited event emitted by the server
+
+This document describes `ServerMessage` as a protocol-level concept.
+It should not be confused with generated protobuf accessors or wire-level
+encoding details.
+
+---
+
+## Lifetime and Delivery
+
+`ServerMessage` instances are emitted by the server and delivered
+asynchronously to clients.
+
+Delivery guarantees:
+
+- Messages are delivered in the order sent by the server
+- Messages may be delivered at any time
+- Events may be delivered before or after responses
+
+Clients **must** be prepared to handle `ServerMessage` objects at all times,
+regardless of pending requests.
+
+---
+
+## Message Type
+
+Each `ServerMessage` contains **exactly one payload**, identified by the
+`message_type` field.
+
+The following message types are supported:
+
+- `RESPONSE`
+- `SESSION_EVENT`
+- `ROOM_EVENT`
+- `GAME_EVENT_CONTAINER`
+
+A message containing multiple payloads or an unknown type is considered
+malformed.
+
+---
+
+## RESPONSE
+
+`RESPONSE` messages are direct replies to client-issued `CommandContainer`
+messages.
+
+Characteristics:
+
+- Contain a `Response` payload
+- Echo the client-assigned `cmd_id`
+- Indicate success or failure of the request
+
+A single `CommandContainer` results in **at most one** `RESPONSE`.
+
+`RESPONSE` messages may be preceded or followed by event messages.
+
+---
+
+## Events
+
+Event messages are unsolicited notifications emitted by the server.
+
+Event message types include:
+
+- `SESSION_EVENT`
+- `ROOM_EVENT`
+- `GAME_EVENT_CONTAINER`
+
+Event messages:
+
+- Are not correlated to a specific client command
+- Do not include a `cmd_id`
+- May be delivered at any time
+
+Clients **must** process events independently of responses.
+
+---
+
+## Event Scopes
+
+### Session Events
+
+Session events are global to the client session and may include:
+
+- Server notifications
+- Private messages
+- User status updates
+
+---
+
+### Room Events
+
+Room events are scoped to a specific room and are delivered only to clients
+currently present in that room.
+
+---
+
+### Game Events
+
+Game events are scoped to a specific game and are delivered only to
+participating clients.
+
+Game events are grouped within a `GameEventContainer` to allow batching.
+
+---
+
+## Event Batching
+
+Some `ServerMessage` types may contain multiple logical events.
+
+- `GameEventContainer` may batch multiple game events
+- Other event types represent a single logical event
+
+Clients must process all contained events **in order**.
+
+---
+
+## Error Semantics
+
+Errors are communicated **exclusively** via `RESPONSE` messages.
+
+Event messages are never used to signal command failure.
+
+Common error responses include:
+
+- `RespInvalidCommand`
+- `RespLoginNeeded`
+- `RespContextError`
+- `RespChatFlood`
+
+---
+
+## Related Concepts
+
+- CommandContainer
+- Client State Machine
+- Response
+
+---
+
+## Reference Proto Definition
+
+```proto
+message ServerMessage {
+    enum MessageType {
+        RESPONSE = 0;
+        SESSION_EVENT = 1;
+        GAME_EVENT_CONTAINER = 2;
+        ROOM_EVENT = 3;
+    }
+
+    optional MessageType message_type = 1;
+    optional Response response = 2;
+    optional SessionEvent session_event = 3;
+    optional GameEventContainer game_event_container = 4;
+    optional RoomEvent room_event = 5;
+}
+```