Terminal Recording Player
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal Recording Player is a specialized web-based component within the Warpgate admin interface designed to replay and stream SSH terminal sessions. Warpgate acts as a bastion host that records every session, allowing administrators to view live activity or audit historical recordings through the built-in web UI.
Sources: README.md:10-12, README.md:52-54
The player leverages xterm.js for terminal emulation and supports the asciicast format for recording data. It provides a full set of playback controls, including seeking, pausing, and full-screen mode, while also supporting real-time streaming for active sessions via WebSockets.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:4-10, warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:102-120
Architecture and Data Flow
The Terminal Recording Player operates by fetching recording data in a JSON-line format (cast) and optionally connecting to a WebSocket for live updates.
Initialization and Data Loading
When the component mounts, it performs a dual-stage data retrieval:
- Static Fetch: It retrieves the historical session data from the
/castendpoint. This data is parsed line-by-line and added to an internal event buffer. - Live Stream: If the session is active, it opens a WebSocket connection to the
/streamendpoint to receive real-time terminal data and state changes.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:94-123
Event Processing Flow
The player manages three primary types of events:
- DataEvent: Contains terminal output strings to be rendered.
- SizeEvent: Contains terminal dimensions (columns and rows) to trigger resizing of the terminal emulator.
- SnapshotEvent: Created internally during seeking to allow rapid state recovery without replaying the entire stream from the beginning.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:79-81
The following diagram illustrates the flow of terminal data from the server to the rendered UI:
A flowchart showing the data acquisition from the API, event buffering, and final rendering in xterm.js.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:102-156
Components and Logic
Terminal Emulation
The player uses xterm.js alongside the SerializeAddon. The terminal is configured with a custom color theme and specific options like scrollback limits.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:4-5, warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:31-64
Seeking and Snapshots
To enable efficient seeking, the player implements a snapshot mechanism. As the player processes terminal data during a seek operation, it periodically generates snapshots using serializeAddon.serialize(). When a user seeks to a specific timestamp, the player finds the nearest preceding snapshot to minimize the amount of data that must be "replayed" to reach the target state.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:177-227
Implementation Details: Seek Mechanism
A sequence diagram depicting the logic used to move the playback position to a specific time index using snapshots.
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:183-220
Key Dependencies and Data Structures
The player relies on standard web technologies and specific terminal libraries defined in the project configuration.
Technical Stack
| Dependency | Purpose |
|---|---|
@xterm/xterm | Core terminal emulation and rendering. |
@xterm/addon-serialize | Captures terminal state for snapshotting/seeking. |
svelte-fa | FontAwesome icon support for playback controls. |
format-duration | Formatting timestamps (e.g., 00:00). |
Sources: warpgate-web/package.json:63-64, warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:3-8
API Endpoints
The player interacts with the following backend routes:
| Endpoint | Method | Description |
|---|---|---|
/@warpgate/admin/api/recordings/{id}/cast | GET | Fetches the full historical recording in JSONL format. |
wss://.../api/recordings/{id}/stream | WS | Real-time WebSocket stream for live session monitoring. |
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:99-112
Session Context and Integration
Terminal recordings are linked to sessions. Administrators navigate to a specific session (via Session.svelte) to find associated recordings.
Sources: warpgate-web/src/admin/Session.svelte:106-125
- Session Metadata: Includes username, target (SSH host/port), and duration.
- Recording Kind: The player specifically validates that the recording kind is
Terminalbefore initializing. - Storage: Recordings are stored on the host filesystem (default:
/var/lib/warpgate/recordings).
Sources: warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:95-97, warpgate/src/commands/setup.rs:189-191
Conclusion
The Terminal Recording Player provides a robust interface for auditing terminal activity in Warpgate. By combining xterm.js for emulation, a custom snapshotting seek algorithm, and WebSocket integration for live streaming, it ensures that administrators can effectively monitor and review security-sensitive terminal sessions.
Sources: README.md:52-54, warpgate-web/src/admin/player/TerminalRecordingPlayer.svelte:102-120