Module session 

Per-client session state and lifecycle.

Each WebSocket connection (and each MCP client) is wrapped in a Session managed by a SessionManager. Sessions are isolated: open packs in one session aren’t visible from another, and each one owns a dedicated background thread (see crate::background_thread) that processes its commands serially, with its own settings. Sessions start with the settings in the settings file, and clients owning their own settings (the UI) replace them with a session.configure request.

Lifecycle

1. Create. A new session gets a unique SessionId from the manager plus a fresh background thread of its own.
2. Connect / disconnect. Clients increment Session::connect on attach and Session::disconnect on detach. The connection count is what the timeout logic watches.
3. Reconnect. A client can pass its previous session_id back on the next WebSocket handshake to adopt the same session and recover its in-memory state. See SessionManager::get_or_create_session.
4. Timeout. When the connection count drops to zero, the session enters a DEFAULT_SESSION_TIMEOUT_SECS-long grace period. Reconnects cancel the timeout; otherwise the cleanup task removes the session and its background thread exits.
5. Empty manager → process exit. When a WebSocket session is removed and no other session is left, the server process terminates, so no orphaned backend lingers in the background. Removing the MCP session never stops the process.

The MCP session

MCP clients share one session (SessionManager::mcp_session), whatever their protocol version: newer MCP versions have no sessions of their own, and the older ones have no disconnect signal the server can rely on. The MCP session is never counted as connected; instead, the periodic cleanup task removes it once no request has been sent through it for DEFAULT_SESSION_TIMEOUT_SECS, as long as it has no open packs and no unfinished jobs. The next MCP request creates a new one.

Structs

DiagnosticsCheck 🔒

A diagnostics check requested to a session.

ManagedSession 🔒

Internal state for a managed session.

Session

A session represents a single client’s connection state.

SessionManager

Manages all active sessions.

Enums

SessionMessage

A message for a session’s background thread, with where to send its response.

Constants

CLEANUP_INTERVAL 🔒

How often expired sessions are looked for.

DEFAULT_SESSION_TIMEOUT_SECS

Default session timeout in seconds (5 minutes).

SESSION_SENDER_ERROR

Error messages for session communication.

Type Aliases

SessionId

Unique identifier for a session.