> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springtail.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Flow Overview

## Overview

The `ClientSession` and `ServerSession` classes in the Springtail project facilitate communication between the client and the database server. This communication is essential for managing queries, state transitions, and failover scenarios.

### ClientSession

* **Manages Client Connections**: Handles incoming client requests and routes them to the appropriate `ServerSession`.
* **State Management**: Tracks the state of the client connection (e.g., STARTUP, READY, QUERY).
* **Failover Handling**: Manages failover notifications and transitions to replica servers when necessary.
* **Query Parsing and Execution**: Processes client queries and forwards them to the `ServerSession`.

### ServerSession

* **Manages Server Connections**: Handles communication with the database server.
* **Batch Processing**: Queues and processes batches of messages from the `ClientSession`.
* **Error Recovery**: Implements mechanisms to recover from errors and maintain session integrity.
* **State Management**: Tracks the state of the server connection (e.g., STARTUP, DEPENDENCIES, QUERY).

## Communication Flow

1. **Client Request Handling**:
   * The `ClientSession` receives a request from the client.
   * It parses the request and determines the appropriate action (e.g., query execution, transaction management).

2. **Server Session Selection**:
   * The `ClientSession` selects or creates a `ServerSession` based on the request type and session state.
   * It may reuse an existing `ServerSession` or create a new one for failover scenarios.

3. **Message Forwarding**:
   * The `ClientSession` forwards the parsed query or command to the `ServerSession`.
   * The `ServerSession` processes the message and communicates with the database server.

4. **Response Handling**:
   * The `ServerSession` receives the response from the database server.
   * It forwards the response back to the `ClientSession`, which sends it to the client.

5. **Error and Failover Management**:
   * If an error occurs, the `ServerSession` attempts to recover and notifies the `ClientSession`.
   * In failover scenarios, the `ClientSession` transitions to a replica server and replays pending state.

## Message Path: Server -> Client Session

This section describes how server-side connections are accepted, scheduled, processed, and how replies are returned to the client.

1. **Connection Acceptance**:
   * Server accepts new TCP connections and wraps them in connection objects
   * Creates an in-memory session to track the socket and connection state
   * Registers the session with the event infrastructure for monitoring

2. **Event Detection**:
   * Main event loop monitors registered sockets for readability
   * When a socket becomes readable, the client session associated with socket is obtained
   * All sockets associated with the client session (the client session and all server session sockets) are removed from the poll set
   * The client session is added to a runnable set; if the server session is in a RESET state, then there is no associated client session and it is added to the runnable set

3. **Worker Processing**
   * Runnable sessions are submitted to a worker pool
   * A worker thread picks up the session and begins processing
   * Worker reads incoming bytes, assembles protocol messages, and processes them

4. **Message Handling**
   * Client session first checks for data on the client session socket, then for data on the server session sockets
   * Client-facing sessions interpret the client protocol
   * Parse message payloads and forward commands to the server-side session
   * Manage transactional state and buffering as required

5. **Reply Delivery**
   * Server-side session receives responses from the database; the server session socket will have data available
   * Prepares outgoing buffers and writes to the client's socket
   * All traffic is logged by the request/response logging subsystem

6. **Session Re-queueing**
   * Worker clears temporary state after processing
   * Re-registers the session with the event loop if connection remains open
   * Performs cleanup if the session is closing or errors occur