feat: replay CLI, TCP backend helper, SVD fields/enums

- Add rsgdb replay JSONL mock backend and replay integration test (#10)
- Extract connect_tcp_backend; drop unused Backend trait stub (#9)
- Index SVD fields with bit overlap; append enum variant names; extend fixture/tests (#11)
- Document replay, SVD annotations, and roadmap in README/CONTRIBUTING
- Clippy: enumerate mock backend loop

Made-with: Cursor

Author: Alex J Lennon

CONTRIBUTING.md

@@ -109,7 +109,7 @@ Work is tracked in [GitHub issues](https://github.com/DynamicDevices/rsgdb/issue
 
 **Status (short):** Part A (**#1–#3**), session recording (**#4**), SVD baseline (**#5**), breakpoint/semihosting spike (**#6**), flash orchestration (**#7**), RTOS decode/log (**#8**) are **closed**. **Phase A/B** (RSP matrix + proxy tests, gdbinit, backend thread reply logging) are in-tree; see README. **CI:** main workflow (**CI**) + optional **Zephyr E2E** (`native_sim`, debug `rsgdb`, west venv + `pyelftools`) — both green on `main`.
 
-**Next roadmap issues (open):** [#9](https://github.com/DynamicDevices/rsgdb/issues/9) native probe backend, [#10](https://github.com/DynamicDevices/rsgdb/issues/10) session replay from JSONL, [#11](https://github.com/DynamicDevices/rsgdb/issues/11) richer SVD (fields/enums).
+**Next roadmap focus (open):** [#9](https://github.com/DynamicDevices/rsgdb/issues/9) native probe / backend beyond TCP. **In-tree:** session replay ([#10](https://github.com/DynamicDevices/rsgdb/issues/10) — `rsgdb replay`), SVD field + enum labels in memory annotations ([#11](https://github.com/DynamicDevices/rsgdb/issues/11) — baseline; correlation with recordings may remain on the issue).
 
 **CI jobs (overview):** Workflow **CI**: `test` (matrix), `fmt`, `clippy`, `docs`, `e2e-gdb-smoke`, `coverage`, `build` (artifacts; upload may use `continue-on-error` for transient infra). Workflow **Zephyr E2E**: west + SDK + `scripts/e2e_zephyr_native_sim.sh` (path / schedule / `workflow_dispatch`).
 
@@ -328,10 +328,10 @@ We welcome contributions in these areas (see **[open issues](https://github.com/
 
 ### High priority (roadmap)
 - [ ] **Native probe / backend abstraction** — [#9](https://github.com/DynamicDevices/rsgdb/issues/9)
-- [ ] **Session replay from JSONL** — [#10](https://github.com/DynamicDevices/rsgdb/issues/10)
+- [x] **Session replay from JSONL** — [#10](https://github.com/DynamicDevices/rsgdb/issues/10) (`rsgdb replay`)
 
 ### Medium priority
-- [ ] **Richer SVD (fields, enums)** — [#11](https://github.com/DynamicDevices/rsgdb/issues/11)
+- [x] **Richer SVD (fields, enum names in annotations)** — [#11](https://github.com/DynamicDevices/rsgdb/issues/11) (value decode / recording correlation still optional follow-ups)
 - [ ] TUI, advanced breakpoints, logging export — open an issue before large changes
 
 ### Always welcome

README.md

@@ -138,7 +138,7 @@ path = "device.svd"
 
 ### SVD labels (read-only)
 
-If `[svd] path` points to a valid CMSIS-SVD file (or use `--svd FILE` / env `RSGDB_SVD`), rsgdb builds a register map and emits **debug** logs for **client** memory packets (`m` read, `M` write) with a human-readable range when the access overlaps known registers — for example `GPIOA.MODER (4 bytes)`. This is **display only**; RSP bytes are unchanged.
+If `[svd] path` points to a valid CMSIS-SVD file (or use `--svd FILE` / env `RSGDB_SVD`), rsgdb builds a register map and emits **debug** logs for **client** memory packets (`m` read, `M` write) with a human-readable range when the access overlaps known registers — for example `GPIOA.MODER (4 bytes)` or, when the SVD lists fields, `GPIOA.MODER (4 bytes); fields: GPIOA.MODER.MODE0 [Input, Output], …`. Enumerated value **names** from the SVD are shown alongside fields; decoding actual register **values** against those enums is not implemented yet. This is **display only**; RSP bytes are unchanged.
 
 Enable the log target with e.g. `RUST_LOG=rsgdb::svd=debug,rsgdb=info` (or `-d` / verbose per your logging setup).
 
@@ -148,7 +148,7 @@ When enabled, each GDB↔backend connection writes one **JSON Lines** file under
 
 **Enable:** `rsgdb --record`, or set `[recording] enabled = true` in config, or `RSGDB_RECORD=1`. Optional directory override: `--record-dir DIR` or `RSGDB_RECORD_DIR`.
 
-**Replay:** There is no built-in replayer yet. Inspect `.jsonl` with your usual tools or `jq`. Work is tracked as [#10](https://github.com/DynamicDevices/rsgdb/issues/10) (mock / automated playback for regression tests).
+**Replay:** `rsgdb replay <FILE.jsonl> [--listen ADDR]` (default `127.0.0.1:3334`) loads an `rsgdb-record` v1 session and listens for TCP; the **first** GDB client connection is served by a mock backend that replays `backend_to_client` / expects `client_to_backend` events in order (for regression tests and inspection). You can still inspect raw `.jsonl` with `jq` or other tools. Tracked as [#10](https://github.com/DynamicDevices/rsgdb/issues/10).
 
 ### Flash orchestration (`rsgdb flash`)
 
@@ -290,9 +290,9 @@ Source of truth for ordering and scope: **[GitHub Issues](https://github.com/Dyn
 | Milestone (docs) | What it means | Issue |
 |------------------|---------------|-------|
 | **Foundation + proxy** | RSP codec, TCP proxy, config, logging, CI (incl. GDB + Zephyr E2E), session record (JSONL), SVD labels, flash orchestration, RTOS decode/log | Closed: [#1–#8](https://github.com/DynamicDevices/rsgdb/issues?q=is%3Aissue+is%3Aclosed) |
-| **Next: native backend** | Probe-facing `Backend` (not only TCP stub) | [#9](https://github.com/DynamicDevices/rsgdb/issues/9) (open) |
-| **Next: replay** | Playback / mock backend from `.jsonl` recordings | [#10](https://github.com/DynamicDevices/rsgdb/issues/10) (open) |
-| **Next: richer SVD** | Fields, enums, correlation with recordings | [#11](https://github.com/DynamicDevices/rsgdb/issues/11) (open) |
+| **Next: native backend** | Probe-facing backend beyond TCP to a stub (see `backends::connect_tcp_backend`) | [#9](https://github.com/DynamicDevices/rsgdb/issues/9) (open) |
+| **Replay** | `rsgdb replay` + mock TCP backend from `.jsonl` | [#10](https://github.com/DynamicDevices/rsgdb/issues/10) (implemented; close when shipped) |
+| **Richer SVD** | Overlapping fields + enum variant names in annotations; value decode / recording correlation follow-ups | [#11](https://github.com/DynamicDevices/rsgdb/issues/11) (baseline in-tree) |
 
 Older versioned bullets (v0.2–v0.4) below are **aspirational**; issue titles supersede them.
 

src/backends/mod.rs

@@ -1,17 +1,9 @@
-//! Backends module
+//! Debug probe backends.
 //!
-//! Debug probe backend implementations (OpenOCD, probe-rs, pyOCD).
+//! Today the proxy uses [`tcp::connect_tcp_backend`] to reach a GDB stub over TCP. A fuller
+//! backend abstraction for native probes is tracked as
+//! [#9](https://github.com/DynamicDevices/rsgdb/issues/9).
 
-/// Backend trait for debug probes
-pub trait Backend {
-    /// Connect to the target
-    fn connect(&mut self) -> anyhow::Result<()>;
+mod tcp;
 
-    /// Disconnect from the target
-    fn disconnect(&mut self) -> anyhow::Result<()>;
-
-    /// Check if connected
-    fn is_connected(&self) -> bool;
-}
-
-// Made with Bob
+pub use tcp::connect_tcp_backend;

src/backends/tcp.rs

@@ -0,0 +1,37 @@
+//! TCP connection to a remote GDB stub (OpenOCD, probe-rs, pyOCD, etc.).
+//!
+//! Native probe backends will plug in alongside this path; see [#9](https://github.com/DynamicDevices/rsgdb/issues/9).
+
+use crate::config::ProxyConfig;
+use crate::error::RsgdbError;
+use crate::protocol::codec::GdbCodec;
+use std::time::Duration;
+use tokio::net::TcpStream;
+use tokio::time::timeout;
+use tokio_util::codec::Framed;
+
+/// Connect to `target_host:target_port` and wrap the stream with [`GdbCodec`].
+pub async fn connect_tcp_backend(
+    config: &ProxyConfig,
+) -> Result<Framed<TcpStream, GdbCodec>, RsgdbError> {
+    let backend_addr = format!("{}:{}", config.target_host, config.target_port);
+    let stream = if config.timeout_secs == 0 {
+        TcpStream::connect(&backend_addr)
+            .await
+            .map_err(RsgdbError::Io)?
+    } else {
+        timeout(
+            Duration::from_secs(config.timeout_secs),
+            TcpStream::connect(backend_addr.clone()),
+        )
+        .await
+        .map_err(|_| {
+            RsgdbError::Timeout(format!(
+                "TCP connect to backend {} exceeded {}s",
+                backend_addr, config.timeout_secs
+            ))
+        })?
+        .map_err(RsgdbError::Io)?
+    };
+    Ok(Framed::new(stream, GdbCodec::new()))
+}

src/lib.rs

@@ -32,6 +32,7 @@ mod logging_setup;
 pub mod protocol;
 pub mod proxy;
 pub mod recorder;
+pub mod replay;
 pub mod rtos;
 pub mod state;
 pub mod svd;

src/main.rs

@@ -26,6 +26,15 @@ struct Cli {
 
 #[derive(Subcommand, Debug)]
 enum Commands {
+    /// Replay a **rsgdb-record v1** JSONL file as a mock TCP backend (issue #10)
+    Replay {
+        /// Session file (`.jsonl`)
+        #[arg(value_name = "FILE")]
+        file: PathBuf,
+        /// Mock backend listen address (point `rsgdb` `--target-host` / `--target-port` here)
+        #[arg(long, default_value = "127.0.0.1:3334", value_name = "ADDR")]
+        listen: String,
+    },
     /// Flash firmware using `[flash].program` in config (orchestrates OpenOCD, probe-rs, etc.)
     Flash {
         /// Firmware image (binary, ELF, or whatever your tool expects)
@@ -90,6 +99,7 @@ async fn main() -> anyhow::Result<()> {
     let cli = Cli::parse();
 
     match cli.command {
+        Some(Commands::Replay { file, listen }) => run_replay(&file, &listen).await,
         Some(Commands::Flash {
             image,
             config,
@@ -100,6 +110,40 @@ async fn main() -> anyhow::Result<()> {
     }
 }
 
+async fn run_replay(file: &Path, listen: &str) -> anyhow::Result<()> {
+    use rsgdb::replay::{load_session, run_mock_backend};
+    use tokio::net::TcpListener;
+
+    let mut config = Config::default();
+    config.merge_env();
+    let _log_guard: LoggingInitGuard = init_from_logging_config(&config.logging, false, false)
+        .map_err(|e| anyhow::anyhow!("logging init: {}", e))?;
+
+    let session = load_session(file).with_context(|| format!("load {}", file.display()))?;
+    let addr: std::net::SocketAddr = listen
+        .parse()
+        .with_context(|| format!("parse listen address {:?}", listen))?;
+    let listener = TcpListener::bind(addr).await?;
+    info!(
+        path = %file.display(),
+        addr = %listener.local_addr()?,
+        events = session.events.len(),
+        "Replay mock backend — connect rsgdb with e.g. --target-host 127.0.0.1 --target-port {}",
+        listener.local_addr()?.port()
+    );
+
+    loop {
+        let (sock, peer) = listener.accept().await?;
+        info!("Replay: backend connection from {}", peer);
+        let events = session.events.clone();
+        tokio::spawn(async move {
+            if let Err(e) = run_mock_backend(sock, events).await {
+                error!("replay session ended: {}", e);
+            }
+        });
+    }
+}
+
 fn run_flash_main(
     image: &Path,
     config_path: Option<&Path>,

src/proxy/server.rs

@@ -2,6 +2,7 @@
 //!
 //! Handles incoming GDB client connections and forwards commands to the backend.
 
+use crate::backends::connect_tcp_backend;
 use crate::config::{ProxyConfig, RecordingConfig};
 use crate::error::RsgdbError;
 use crate::protocol::codec::{GdbCodec, PacketOrAck};
@@ -12,10 +13,8 @@ use crate::svd::SvdIndex;
 use futures::StreamExt;
 use std::net::SocketAddr;
 use std::sync::Arc;
-use std::time::Duration;
 use tokio::net::{TcpListener, TcpStream};
 use tokio::sync::Mutex;
-use tokio::time::timeout;
 use tokio_util::codec::Framed;
 use tracing::{debug, error, info, warn};
 
@@ -89,28 +88,10 @@ async fn handle_connection(
     let peer_addr = client_socket.peer_addr().map_err(RsgdbError::Io)?;
     info!("Handling connection from {}", peer_addr);
 
-    // Connect to the backend
     let backend_addr = format!("{}:{}", config.target_host, config.target_port);
     debug!("Connecting to backend at {}", backend_addr);
 
-    let backend_socket = if config.timeout_secs == 0 {
-        TcpStream::connect(&backend_addr)
-            .await
-            .map_err(RsgdbError::Io)?
-    } else {
-        timeout(
-            Duration::from_secs(config.timeout_secs),
-            TcpStream::connect(backend_addr.clone()),
-        )
-        .await
-        .map_err(|_| {
-            RsgdbError::Timeout(format!(
-                "TCP connect to backend {} exceeded {}s",
-                backend_addr, config.timeout_secs
-            ))
-        })?
-        .map_err(RsgdbError::Io)?
-    };
+    let backend = connect_tcp_backend(&config).await?;
 
     info!("Connected to backend at {}", backend_addr);
 
@@ -127,7 +108,7 @@ async fn handle_connection(
     };
 
     // Create a session to manage the connection
-    let mut session = ProxySession::new(client_socket, backend_socket, config, recorder, svd);
+    let mut session = ProxySession::new(client_socket, backend, config, recorder, svd);
 
     // Run the session
     session.run().await?;
@@ -161,13 +142,12 @@ impl ProxySession {
     /// Create a new proxy session
     fn new(
         client_socket: TcpStream,
-        backend_socket: TcpStream,
+        backend: Framed<TcpStream, GdbCodec>,
         config: ProxyConfig,
         recorder: Option<SessionRecorder>,
         svd: Option<Arc<SvdIndex>>,
     ) -> Self {
         let client = Framed::new(client_socket, GdbCodec::new());
-        let backend = Framed::new(backend_socket, GdbCodec::new());
 
         Self {
             client,

src/recorder/jsonl.rs

@@ -36,7 +36,7 @@ pub enum RecordKind {
     Nack,
 }
 
-#[derive(Debug, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RecordEventV1 {
     pub ts: DateTime<Utc>,
     pub direction: RecordDirection,

src/replay/error.rs

@@ -0,0 +1,35 @@
+//! Errors for session replay.
+
+use crate::protocol::ProtocolError;
+
+/// Replay / mock-backend failures.
+#[derive(Debug, thiserror::Error)]
+pub enum ReplayError {
+    #[error("I/O: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("JSON: {0}")]
+    Json(#[from] serde_json::Error),
+
+    #[error("invalid session header: {0}")]
+    InvalidHeader(String),
+
+    #[error("invalid record event: {0}")]
+    InvalidEvent(String),
+
+    #[error(transparent)]
+    Protocol(#[from] ProtocolError),
+
+    #[error(transparent)]
+    Hex(#[from] hex::FromHexError),
+
+    #[error("replay mismatch at step {step}: expected {expected}, got {got}")]
+    Mismatch {
+        step: usize,
+        expected: String,
+        got: String,
+    },
+
+    #[error("replay ended before mock backend finished (step {step})")]
+    UnexpectedEof { step: usize },
+}

src/replay/jsonl.rs

@@ -0,0 +1,82 @@
+//! Load **rsgdb-record v1** JSONL files for replay.
+
+use std::path::Path;
+
+use crate::recorder::{RecordEventV1, RecordHeaderV1, FORMAT_NAME, FORMAT_VERSION};
+
+use super::ReplayError;
+
+/// Parsed recording: header + ordered events (excluding the header line).
+#[derive(Debug, Clone)]
+pub struct LoadedSession {
+    pub header: RecordHeaderV1,
+    pub events: Vec<RecordEventV1>,
+}
+
+/// Read a `.jsonl` session file; validates format name/version on line 1.
+pub fn load_session(path: &Path) -> Result<LoadedSession, ReplayError> {
+    let text = std::fs::read_to_string(path)?;
+    load_session_str(&text)
+}
+
+fn load_session_str(text: &str) -> Result<LoadedSession, ReplayError> {
+    let mut lines = text.lines();
+    let first = lines
+        .next()
+        .ok_or_else(|| ReplayError::InvalidHeader("empty file".into()))?;
+    let header: RecordHeaderV1 = serde_json::from_str(first)?;
+    if header.format != FORMAT_NAME {
+        return Err(ReplayError::InvalidHeader(format!(
+            "expected format {:?}, got {:?}",
+            FORMAT_NAME, header.format
+        )));
+    }
+    if header.version != FORMAT_VERSION {
+        return Err(ReplayError::InvalidHeader(format!(
+            "expected version {}, got {}",
+            FORMAT_VERSION, header.version
+        )));
+    }
+
+    let mut events = Vec::new();
+    for line in lines {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let ev: RecordEventV1 = serde_json::from_str(line)?;
+        events.push(ev);
+    }
+
+    Ok(LoadedSession { header, events })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::recorder::{RecordDirection, RecordKind};
+    use chrono::Utc;
+
+    #[test]
+    fn load_round_trip() {
+        let h = RecordHeaderV1 {
+            format: FORMAT_NAME.to_string(),
+            version: FORMAT_VERSION,
+            session_id: "t".into(),
+            started_at: Utc::now(),
+        };
+        let ev = RecordEventV1 {
+            ts: Utc::now(),
+            direction: RecordDirection::ClientToBackend,
+            kind: RecordKind::Packet,
+            payload_hex: Some("71737570706f72746564".into()), // "qsupported"
+            payload_len: Some(10),
+        };
+        let mut s = serde_json::to_string(&h).unwrap();
+        s.push('\n');
+        s.push_str(&serde_json::to_string(&ev).unwrap());
+
+        let loaded = load_session_str(&s).expect("load");
+        assert_eq!(loaded.events.len(), 1);
+        assert!(matches!(loaded.events[0].kind, RecordKind::Packet));
+    }
+}