changeset 2124 3dfeac5b03db
equal deleted inserted replaced
2123:7df4304efaef 2124:3dfeac5b03db
     1 #summary Server code walkthrough
     2 #labels Phase-Implementation,Phase-Design
     4 = Praise 🦀 =
     6 == General Structure ==
     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.
    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.
    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.
    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.
    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.
    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`.