1 #summary Server code walkthrough

     2 #labels Phase-Implementation,Phase-Design

     3 

     4 = Praise 🦀 =

     5 

     6 == General Structure ==

     7 

     8 The server code consists of the following top level modules (in order of inclusion):

     9   * `core`: contains the types necessary to implement the server logic.

    10   * `protocol`: contains definitions of network protocol messages and code for their (de)serialization.

    11   * `handlers`: acts on parsed protocol messages to modify the server state and generate responses to network clients.

    12   * `server`: contains the code for IO handling.

    13   * `main`: starts the server and runs the main event poll.

    14 

    15 == Important Types ==   

    16   * `core::client::HwClient` and `core::room::HwRoom` structures are where the most of the game-related data is stored. They are often referenced by `core::types::{ClientId, RoomId}` identifiers

    17   * `core::server::HwServer` is a collection `HwClient`s and `HwRoom`s with some additional global server data, and is responsible for maintaining related invariants. For this reason it doesn't provide a public way to retrieve a mutable `HwClient` or `HwRoom` reference.

    18   * `core::anteroom::HwAnteroom` stores clients that did not yet complete the logic procedure. Those clients are represented by `core::anteroom::HwAnteroomClient` structure, that only contains a relevant subset of full client data.

    19   * `core::server::HwRoomControl` can be requested from a `HwServer` to modify a room that the current client is located in. This interface is not directly provided by `HwServer` to avoid constant checks to ensure the client is still in the room.

    20 

    21   * `protocol::messages::HwProtocolMessage` is a parsed representation of a message from a client.

    22   * `protocol::messages::HwServerMessage` is a messaged generated by the server to be deserialized into text protocol and sent to a client.

    23   * `protocol::ProtocolDecoder` is an entry point to the network protocol parser.

    24 

    25   * `handlers::Response` is the structure handlers use for queueing server messages to be sent out, clients to be removed due to server logic, and IO tasks to be performed asynchronously.

    26   * `handlers::IoTask` type represents a task for the IO thread than can be queued using `Response`. The task result will eventually be returned as a `handlers::IoResult` value.

    27 

    28   * `server::io::IoThread` represents the thread for handling all IO processing apart from writing/reading from clients' network sockets.

    29   * `server::network::NetworkClient` is a structure complements a `HwClient` with data relevant to network connection handling. A `NetworkClient` is referenced by the same `ClientId` as the corresponding `HwClient`.

    30   * `server::network::NetworkLayer` is the top level structure that contains an `IoThread`, a `HwAnteroom`, a `HwServer`, and a collection of `NetworkClients`. It handles all the dispatching between all these components.

    31 

    32 == Client Flow ==

    33   * A new client is first created by the `NetworkLayer` when a network connection is established. The relevant network state is stored in a `NetworkClient` structure. 

    34   * If the server is built with TLS support, the client will remain in `server::network` module until the TLS handshake is completed.

    35   * Either way, after the connection is successfully established, a new `HwAnteroomClient` structure is created for the client and stored in the `HwAnteroom`

    36   * From there on, when new data received on client's socked, it's parsed by a `ProtocolDecoder` and the resulting `HwProtocolMessage` is passed into `handlers` module for further dispatching

    37   *  While some general messages are processed directly by `handlers`, the ones only available in a specific context are passed into a specialized submodule: `handlers::inanteroom` for clients located in `HwAnteroom`, `handlers::inroom` for `HwServer` clients that are in a `HwRoom` and `handlers::inlobby` for those that aren't.

    38   * When processing of a `HwProtocolMessage` results in a `HwAnteroomClient` being successfully logged in, it's immediately moved into the `HwServer` and extended to a full `HwClient`.

    39   * If a handler needs complete remove a client, apart from removing it from `HwAnteroom` of `HwServer` it will also queue a request to delete the corresponding `NetworkClient` on it's `Response`.

    40