ServerCodeWalkthrough.wiki
author Wuzzy
Mon, 16 Aug 2021 22:41:20 +0200
changeset 2218 eb6eef27205c
parent 2124 3dfeac5b03db
permissions -rw-r--r--
HWPlaySchemeSyntax: Remove "room=", it is not actually supported
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2124
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     1
#summary Server code walkthrough
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     2
#labels Phase-Implementation,Phase-Design
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     3
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     4
= Praise 🦀 =
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     5
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     6
== General Structure ==
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     7
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     8
The server code consists of the following top level modules (in order of inclusion):
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
     9
  * `core`: contains the types necessary to implement the server logic.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    10
  * `protocol`: contains definitions of network protocol messages and code for their (de)serialization.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    11
  * `handlers`: acts on parsed protocol messages to modify the server state and generate responses to network clients.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    12
  * `server`: contains the code for IO handling.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    13
  * `main`: starts the server and runs the main event poll.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    14
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    15
== Important Types ==   
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    20
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    21
  * `protocol::messages::HwProtocolMessage` is a parsed representation of a message from a client.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    22
  * `protocol::messages::HwServerMessage` is a messaged generated by the server to be deserialized into text protocol and sent to a client.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    23
  * `protocol::ProtocolDecoder` is an entry point to the network protocol parser.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    24
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    27
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    28
  * `server::io::IoThread` represents the thread for handling all IO processing apart from writing/reading from clients' network sockets.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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`.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    31
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    32
== Client Flow ==
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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. 
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    34
  * If the server is built with TLS support, the client will remain in `server::network` module until the TLS handshake is completed.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    35
  * Either way, after the connection is successfully established, a new `HwAnteroomClient` structure is created for the client and stored in the `HwAnteroom`
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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`.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    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`.
3dfeac5b03db add server walkthrough
alfadur
parents:
diff changeset
    40