Session Recording Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Session Recording Architecture in Warpgate provides a robust system for capturing, storing, and replaying user activity across various supported protocols (SSH, MySQL, PostgreSQL, and HTTP). It is designed to record session data in real-time, allowing administrators to monitor live sessions or review historical recordings via the web admin interface.
The system distinguishes between two primary types of recordings: Terminal recordings, which capture text-based interactions (typically for SSH), and Traffic recordings, which capture raw network data (typically for database protocols). These recordings are stored as files on the host system and indexed in the primary SQLite database for management and retrieval.
Sources: README.md, warpgate-core/src/recordings/mod.rs:56-70, warpgate-db-migrations/src/m00003_create_recording.rs:13-18
Core Components
The architecture is composed of several key modules that handle the lifecycle of a recording, from initialization to playback.
SessionRecordings Manager
The SessionRecordings struct acts as the central coordinator. it manages the recording storage path, handles the creation of new recorders, and maintains a registry of "live" recording senders for real-time streaming to the admin UI.
Sources: warpgate-core/src/recordings/mod.rs:48-54
RecordingWriter
The RecordingWriter is the low-level component responsible for actual I/O. It uses an asynchronous buffer (BufWriter) to write data to the filesystem and concurrently broadcasts data to live subscribers using a broadcast::Sender. It ensures that recording metadata (such as the "ended" timestamp) is updated in the database when the session terminates.
Sources: warpgate-core/src/recordings/writer.rs:18-35
Data Flow for Recording
The following diagram illustrates how data flows from a user session through the recorder into persistent storage and live streams.
Data Models and Storage
Recordings are stored in a dedicated directory (configured during setup) and indexed in the recordings database table.
Recording Database Schema
| Field | Type | Description |
|---|---|---|
id | Uuid | Unique identifier for the recording. |
name | String | Filename/Label of the recording. |
started | DateTime | Timestamp when the recording began. |
ended | Option<DateTime> | Timestamp when the recording finished. |
session_id | Uuid | Reference to the parent session. |
kind | RecordingKind | Either Terminal or Traffic. |
Sources: warpgate-db-migrations/src/m00003_create_recording.rs:21-30
Filesystem Structure
Recordings are organized by session ID to prevent collisions and simplify cleanup.
- Path format:
{data_path}/recordings/{session_id}/{recording_name} - Terminal recordings are typically stored as JSON lines (compatible with AsciiCast).
- Traffic recordings are stored as raw binary data (e.g., tcpdump format).
Sources: warpgate-core/src/recordings/mod.rs:107-109, warpgate-admin/src/api/recordings_detail.rs:114-135
Live Streaming and Playback
Warpgate supports both static replay and live "shadowing" of active sessions.
Live Streaming Logic
When an admin views a live session, the backend uses subscribe_live(id) to hook into a broadcast channel managed by the RecordingWriter.
- The Admin UI opens a WebSocket connection to
/recordings/:id/stream. - The server sends a
startmessage indicating if the session is live. - As bytes are written to the file by the
RecordingWriter, they are simultaneously pushed through the WebSocket.
Sources: warpgate-admin/src/api/recordings_detail.rs:137-175, warpgate-core/src/recordings/writer.rs:83-85
Terminal Player Sequence
The web-based player (TerminalRecordingPlayer.svelte) uses xterm.js to render terminal data.
Configuration and Setup
Recording behavior is primarily controlled via the WarpgateConfig. During the warpgate setup process, users are prompted to enable session recording and specify the storage path.
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
recordings.enable | Boolean | true | Globally enable or disable recording. |
recordings.path | String | data/recordings | Directory where recording files are saved. |
Sources: warpgate/src/commands/setup.rs:194-206
Error Handling
The recording system defines specific error variants to handle I/O and database failures.
pub enum Error {
Io(std::io::Error),
Database(sea_orm::DbErr),
Serialization(serde_json::Error),
Closed, // Writer is no longer active
Disabled, // Recordings are turned off in config
InvalidPath,
}
Sources: warpgate-core/src/recordings/mod.rs:23-44
Summary
The Session Recording Architecture provides a high-fidelity audit trail for all proxied connections. By decoupling the writing logic (RecordingWriter) from the protocol implementations through the Recorder trait, Warpgate ensures that recording is consistent across SSH and database protocols. The integration of live broadcasting allows for real-time oversight, while the use of standard formats like AsciiCast and tcpdump ensures compatibility with external analysis tools.