Real-Time Session Replay

Relevant source files

The following files were used as context for generating this wiki page:

• src/replay.rs
• src/config.rs
• src/monitor.rs
• src/plotter.rs
• README.md

Real-Time Session Replay is a core feature of ComChan that allows users to playback previously recorded communication data from .log or .csv files. The system mimics the original timing of the data stream, providing a high-fidelity reconstruction of serial or BLE sessions without requiring the original hardware to be connected.

This feature is integrated into both the raw terminal monitor and the visual plotter, enabling developers to re-examine telemetry, debug transient issues, or demonstrate system behavior using historical data. It supports standard ComChan log formats (prefixed with timestamps) and structured CSV data.
Sources: README.md:144-145, src/replay.rs:9-15

Replay Architecture and Logic

The replay system is encapsulated within the SessionReplayer struct. It operates by reading input files line-by-line and calculating the temporal delta between sequential timestamps to determine when a payload should be emitted to the UI components.

Core Data Structures

The system utilizes a specific state machine and event types to manage the asynchronous nature of file reading and timed emission.

Structure / Enum	Description
SessionReplayer	The primary engine that manages file buffers, timestamp tracking, and event queuing.
ReplayEvent	Enum representing the engine state: Payload(String), Waiting, or Eof.
queued_event	A tuple of (String, Instant) used to store a payload until its scheduled playback time.

Sources: src/replay.rs:7-20

Logic Flow Diagram

The following diagram illustrates the decision logic used by the next_payload function to decide whether to emit data immediately, wait, or terminate.

File Format Support

The replay engine supports two primary file types, determined by the file extension provided in the --replay CLI argument.

1. ComChan Log Files (.log)

The engine looks for lines starting with the prefix RX [. It parses the timestamp contained within the brackets and treats the text following ]: as the data payload.
Sources: src/replay.rs:61-75

2. CSV Files (.csv)

For CSV files, the engine automatically skips the first line (header). It expects the first column to be the timestamp and the second column to be the sensor data or payload.
Sources: src/replay.rs:25-28, src/replay.rs:56-60

Integration with Monitor and Plotter

The replay system acts as a virtual data source, replacing the physical SerialPort or BleEvent receiver.

Monitor Mode Integration

In run_normal_mode, if a replay_file is specified, the monitor loop calls replayer.next_payload(). When a payload is ready, it is written directly to io::stdout. If the replayer returns Eof, the monitor terminates the session.
Sources: src/monitor.rs:309-322

Plotter Mode Integration

In run_plotter_mode, the replayer feeds the ingest_line function. This allows the plotter to reconstruct 2D charts and 3D wireframe telemetry from historical data exactly as if the data were arriving live.
Sources: src/plotter.rs:434-444

Configuration and Usage

The feature is triggered via the global CLI configuration.

Option	Argument	Description
CLI Flag	--replay <FILE>	Path to the .log or .csv file to replay.
Config Field	replay_file	TOML configuration key for persistent replay settings.
Baud Rate	-r / --baud	Ignored during replay; timing is derived from file timestamps.

Sources: src/config.rs:109, src/config.rs:207-210

Implementation Details: Timing Logic

To ensure smooth playback, ComChan implements a maximum delay cap and handles day-roll-over for timestamps.

• Delay Capping: The playback delay between two events is capped at 5000 milliseconds to prevent long periods of inactivity during replays.
• Timestamp Parsing: Timestamps are expected in the %H:%M:%S%.3f format.
• Chronological Correction: If a calculated duration is negative (e.g., a log spanning past midnight), the engine adds 24 hours to the duration to maintain sequence.

Sources: src/replay.rs:77-85

Code Highlight: Delay Calculation

if let Ok(current_time) = NaiveTime::parse_from_str(time_str, "%H:%M:%S%.3f") {
    if let Some(last) = self.last_time {
        let mut ms = current_time.signed_duration_since(last).num_milliseconds();
        if ms < 0 {
            ms += 24 * 60 * 60 * 1000;
        }
        if ms > 0 {
            delay_ms = ms.min(5000) as u64;
        }
    }
    self.last_time = Some(current_time);
}

Sources: src/replay.rs:77-87

The Real-Time Session Replay system provides a critical bridge between live data acquisition and post-hoc analysis. By abstracting the data source through the ReplayEvent interface, ComChan maintains a consistent UI experience whether the data originates from a physical serial port, a BLE stream, or a legacy log file.