aussierobots/session-storage-backends

Session Storage Backends — Turul MCP Framework

Session storage persists MCP sessions across requests and manages SSE events for reconnection resumability. Four backends serve different deployment scenarios — choose based on persistence needs and scaling requirements.

Backend Decision Tree

Need session persistence across restarts?
├─ No ──────────────────────────────────────→ InMemory (default, zero config)
└─ Yes
    ├─ Single server instance? ─────────────→ SQLite (file-based, no external deps)
    └─ Multiple instances / horizontal scaling?
        ├─ AWS / serverless? ───────────────→ DynamoDB (managed, auto-scaling)
        └─ Traditional infrastructure? ─────→ PostgreSQL (shared state, optimistic locking)

Config details (feature flags, Cargo.toml patterns, env vars, config struct fields) are in the storage-backend-matrix reference. This skill covers architecture, the trait API, event management, and decision-making.

SessionStorage Trait

The SessionStorage trait has three method groups:

Session Management

| Method | Signature | Purpose | |---|---|---| | create_session | (capabilities) → SessionInfo | Create session with auto-generated UUID v7 | | create_session_with_id | (id, capabilities) → SessionInfo | Create with specific ID (testing only) | | get_session | (id) → Option<SessionInfo> | Look up session by ID | | update_session | (SessionInfo) → () | Update entire session info | | set_session_state | (id, key, value) → () | Set a state key-value pair | | get_session_state | (id, key) → Option<Value> | Get a state value by key | | remove_session_state | (id, key) → Option<Value> | Remove and return a state value | | delete_session | (id) → bool | Delete session completely | | list_sessions | () → Vec<String> | List all session IDs |

Event Management (SSE Resumability)

| Method | Signature | Purpose | |---|---|---| | store_event | (id, SseEvent) → SseEvent | Store event, assigns monotonic ID | | get_events_after | (id, after_event_id) → Vec<SseEvent> | Get events since last seen (for reconnection) | | get_recent_events | (id, limit) → Vec<SseEvent> | Get latest N events (for initial connection) | | delete_events_before | (id, before_event_id) → u64 | Delete old events (cleanup) |

Cleanup

| Method | Signature | Purpose | |---|---|---| | expire_sessions | (older_than) → Vec<String> | Remove expired sessions, return their IDs | | session_count | () → usize | Active session count (monitoring) | | event_count | () → usize | Total event count across all sessions | | maintenance | () → () | Backend-specific maintenance (compaction, etc.) |

Event Management for SSE

SSE reconnection relies on event storage. When a client disconnects and reconnects with Last-Event-ID, the server replays missed events.

Client connects     → GET /mcp (Accept: text/event-stream)
Server sends events → id: 1, id: 2, id: 3  (stored via store_event)
Client disconnects  → network interruption
Client reconnects   → GET /mcp (Last-Event-ID: 2)
Server replays      → get_events_after(session_id, 2) → [event 3, ...]

Key behaviors:

• store_event() assigns monotonic IDs — each event gets an ID higher than the previous
• get_events_after() is exclusive — after_event_id: 2 returns events 3, 4, 5, ...
• max_events_per_session caps storage (default: 1000) — oldest events are evicted
• Keepalive events use SSE comment syntax (: keepalive\n\n) to preserve Last-Event-ID

Backend-Specific Considerations

InMemory

• Zero config — McpServer::builder() uses it by default
• No persistence — data lost on process restart
• Synchronous cleanup — no background task needed; expired sessions removed on access

SQLite

• File-based persistence — single .db file, no external server
• Connection pool — max_connections default: 10
• Background cleanup — uses tokio::time::sleep loop (NOT interval — first-tick race)
• Test gotcha — :memory: with pools gives each connection its own DB. Use file:{uuid}?mode=memory&cache=shared for shared in-memory test databases

PostgreSQL

• Multi-instance safe — multiple servers share the same session state
• Optimistic locking — version column prevents lost updates; ConcurrentModification error on conflict
• Connection tuning — min_connections (default: 2), max_connections (default: 20), statement_timeout_secs (default: 30)
• Background cleanup — same tokio::time::sleep pattern as SQLite

DynamoDB

• AWS-managed — no server to operate, auto-scales
• Native TTL — AWS handles expiration (no background cleanup task needed)
• Short default TTL — session_ttl_minutes: 5 and event_ttl_minutes: 5 — override for production (e.g., 1440 for 24 hours)
• Table verification — verify_tables: true, create_tables: true verifies and creates tables + GSIs on first use. Default is verify_tables: false (skip verification for Lambda deployments)

Error Types

All backends share SessionStorageError as a unified error type, with From conversions from backend-specific errors.

| Variant | When | |---|---| | SessionNotFound(id) | Session ID doesn't exist | | MaxSessionsReached(limit) | InMemory session limit exceeded | | MaxEventsReached(limit) | Event storage limit exceeded | | DatabaseError(msg) | SQLite/PostgreSQL query failure | | SerializationError(msg) | JSON serialization/deserialization failure | | ConnectionError(msg) | Database connection failure | | MigrationError(msg) | Schema migration failure | | AwsError(msg) | DynamoDB SDK error | | AwsConfigurationError(msg) | AWS credential/region configuration issue | | TableNotFound(table) | DynamoDB table doesn't exist | | InvalidData(msg) | Corrupt or unexpected session data | | ConcurrentModification(msg) | PostgreSQL optimistic lock conflict | | Generic(msg) | Catch-all |

Background Cleanup

SQLite and PostgreSQL run background cleanup tasks. DynamoDB uses native TTL. InMemory is synchronous.

// Internal pattern (for reference — you don't write this code)
// SQLite/PostgreSQL cleanup loop:
loop {
    tokio::time::sleep(Duration::from_secs(cleanup_interval_secs)).await;
    storage.expire_sessions(cutoff_time).await?;
    storage.maintenance().await?;  // compaction, vacuum, etc.
}

Why sleep not interval: tokio::time::interval fires immediately on the first tick, which can race with newly-created sessions in tests. sleep defers the first cleanup by the full interval.

Session Expiry Behavior

When a session expires (TTL cleanup) or is terminated (client DELETE), subsequent requests with that session ID receive HTTP 404 Not Found (MCP 2025-11-25 Streamable HTTP). This tells the client to start a fresh initialize handshake — it is not an authentication error (401).

| Session State | HTTP Status | Client Action | |---|---|---| | Active | 200 | Normal operation | | Terminated (DELETE) | 404 | Re-initialize | | Expired (TTL cleanup) | 404 | Re-initialize | | Never existed | 404 | Re-initialize |

This applies to all storage backends equally — the HTTP transport layer checks session existence before dispatching.

Common Mistakes

1. DynamoDB 5-minute TTL in production — Default session_ttl_minutes: 5 is for testing. Production deployments should set 60–1440+ minutes via DynamoDbConfig { session_ttl_minutes: 1440, event_ttl_minutes: 1440, ..Default::default() }.

2. SQLite :memory: with connection pools — Each pool connection gets its own isolated database. For shared test databases, use file:{uuid}?mode=memory&cache=shared as the database path.

3. Forgetting verify_tables: true for first-time setup — All backends default to verify_tables: false (optimized for Lambda). For first-time setup or development, use verify_tables: true, create_tables: true to auto-create tables.

4. Using InMemory in Lambda — Lambda containers recycle unpredictably. Sessions stored in memory are lost. Use DynamoDbSessionStorage for persistence across invocations.

Beyond This Skill

Feature flags, Cargo.toml patterns, config fields? → See the storage-backend-matrix reference for the complete config reference.

Lambda deployment with DynamoDB? → See the lambda-deployment skill for LambdaMcpServerBuilder, cold-start caching, and DynamoDB setup.

Task storage backends? → See the task-patterns skill for TaskStorage trait and backend configuration (mirrors session storage patterns).

Server builder setup? Use McpServer::builder().with_session_storage(storage). See: CLAUDE.md — Basic Server