feat(backends): transport config, BackendStream, connect_backend (#9)

- Add BackendTransport (tcp | native) and connect_backend(proxy, backend_cfg)
- BackendStream enum with Tcp variant; proxy session uses Framed<BackendStream>
- Native returns NotImplemented until probe integration lands
- Relax backend_type validation to non-empty label; CLI --transport; env RSGDB_TRANSPORT
- Re-export connect_backend, BackendTransport; document in README / rsgdb.toml.example

Made-with: Cursor

Author: Alex J Lennon

README.md

@@ -117,8 +117,10 @@ target_host = "localhost"
 target_port = 3334
 
 [backend]
-# Used for logging / future integration; the proxy connects over TCP to target_host:target_port
+# Label for logs (openocd, probe-rs, gdbserver, …)
 backend_type = "openocd"
+# tcp = GDB stub on target_host:target_port; native = reserved (see GitHub #9)
+transport = "tcp"
 
 [logging]
 level = "debug"
@@ -294,7 +296,7 @@ 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 beyond TCP to a stub (see `backends::connect_tcp_backend`) | [#9](https://github.com/DynamicDevices/rsgdb/issues/9) (open) |
+| **Next: native backend** | Implement `BackendTransport::Native`; default `transport = "tcp"` → `connect_backend` (`src/backends/mod.rs`) | [#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) (closed) |
 | **Richer SVD** | Overlapping fields + enum variant names in annotations; value decode / recording correlation follow-ups | [#11](https://github.com/DynamicDevices/rsgdb/issues/11) (baseline closed; follow-ups optional) |
 

rsgdb.toml.example

@@ -50,8 +50,10 @@ enable_named = true
 enable_conditional = true
 
 [backend]
-# Backend type: openocd, probe-rs, pyocd
+# Label for logs / tooling (openocd, probe-rs, gdbserver, …)
 backend_type = "openocd"
+# How to reach the target: tcp = GDB stub on proxy.target_host:target_port; native = reserved (#9)
+transport = "tcp"
 
 # Backend-specific options
 [backend.options]

src/backends/mod.rs

@@ -1,9 +1,55 @@
-//! Debug probe backends.
+//! Debug probe backends: how the proxy reaches the **target** GDB remote.
 //!
-//! 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).
+//! - **[`BackendTransport`]** — `tcp` (default): connect to a GDB stub on `proxy.target_host` /
+//!   `proxy.target_port`. `native` is reserved for direct probe integration ([#9](https://github.com/DynamicDevices/rsgdb/issues/9)).
+//! - **`backend_type`** in [`crate::config::BackendConfig`] is a **label** (openocd, probe-rs, …)
+//!   for logging and future tooling; it does not change the wire path today.
 
+mod stream;
 mod tcp;
 
-pub use tcp::connect_tcp_backend;
+pub use stream::BackendStream;
+pub use tcp::{connect_tcp_backend, connect_tcp_stream};
+
+use crate::config::{BackendConfig, BackendTransport, ProxyConfig};
+use crate::error::RsgdbError;
+use crate::protocol::codec::GdbCodec;
+use tokio_util::codec::Framed;
+
+/// Connect to the configured debug backend and return an RSP-framed stream.
+pub async fn connect_backend(
+    proxy: &ProxyConfig,
+    backend: &BackendConfig,
+) -> Result<Framed<BackendStream, GdbCodec>, RsgdbError> {
+    match backend.transport {
+        BackendTransport::Tcp => {
+            let stream = connect_tcp_stream(proxy).await?;
+            Ok(Framed::new(BackendStream::Tcp(stream), GdbCodec::new()))
+        }
+        BackendTransport::Native => Err(RsgdbError::NotImplemented(
+            "native probe backend is not implemented yet; use [backend] transport = \"tcp\" \
+             (GDB stub on target_host:target_port). See GitHub #9."
+                .to_string(),
+        )),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::BackendConfig;
+
+    #[tokio::test]
+    async fn native_transport_is_not_implemented() {
+        let proxy = ProxyConfig::default();
+        let backend = BackendConfig {
+            transport: BackendTransport::Native,
+            ..Default::default()
+        };
+        let err = connect_backend(&proxy, &backend).await.unwrap_err();
+        match err {
+            RsgdbError::NotImplemented(s) => assert!(s.contains("native")),
+            e => panic!("expected NotImplemented, got {e:?}"),
+        }
+    }
+}

src/backends/stream.rs

@@ -0,0 +1,53 @@
+//! Byte stream to the debug target (TCP stub today; more variants later).
+
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+use tokio::net::TcpStream;
+
+/// Async byte stream used as the GDB remote **target** side of the proxy.
+#[derive(Debug)]
+pub enum BackendStream {
+    /// Remote GDB stub (OpenOCD, probe-rs, gdbserver, …) over TCP.
+    Tcp(TcpStream),
+}
+
+impl AsyncRead for BackendStream {
+    fn poll_read(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        match &mut *self {
+            BackendStream::Tcp(t) => Pin::new(t).poll_read(cx, buf),
+        }
+    }
+}
+
+impl AsyncWrite for BackendStream {
+    fn poll_write(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<Result<usize, io::Error>> {
+        match &mut *self {
+            BackendStream::Tcp(t) => Pin::new(t).poll_write(cx, buf),
+        }
+    }
+
+    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), io::Error>> {
+        match &mut *self {
+            BackendStream::Tcp(t) => Pin::new(t).poll_flush(cx),
+        }
+    }
+
+    fn poll_shutdown(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Result<(), io::Error>> {
+        match &mut *self {
+            BackendStream::Tcp(t) => Pin::new(t).poll_shutdown(cx),
+        }
+    }
+}

src/backends/tcp.rs

@@ -1,6 +1,4 @@
 //! 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;
@@ -10,15 +8,13 @@ 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> {
+/// Establish a TCP connection to `target_host:target_port` (no codec).
+pub async fn connect_tcp_stream(config: &ProxyConfig) -> Result<TcpStream, RsgdbError> {
     let backend_addr = format!("{}:{}", config.target_host, config.target_port);
-    let stream = if config.timeout_secs == 0 {
+    if config.timeout_secs == 0 {
         TcpStream::connect(&backend_addr)
             .await
-            .map_err(RsgdbError::Io)?
+            .map_err(RsgdbError::Io)
     } else {
         timeout(
             Duration::from_secs(config.timeout_secs),
@@ -31,7 +27,14 @@ pub async fn connect_tcp_backend(
                 backend_addr, config.timeout_secs
             ))
         })?
-        .map_err(RsgdbError::Io)?
-    };
+        .map_err(RsgdbError::Io)
+    }
+}
+
+/// 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 stream = connect_tcp_stream(config).await?;
     Ok(Framed::new(stream, GdbCodec::new()))
 }

src/config.rs

@@ -125,13 +125,55 @@ pub struct BreakpointConfig {
     pub enable_conditional: bool,
 }
 
+/// How the proxy reaches the debug target (stub TCP vs future native probe).
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum BackendTransport {
+    /// GDB remote stub on `proxy.target_host`:`proxy.target_port` (OpenOCD, probe-rs GDB port, …).
+    #[default]
+    #[serde(alias = "stub")]
+    Tcp,
+    /// Direct probe / native integration (not implemented; reserved for #9).
+    Native,
+}
+
+impl BackendTransport {
+    /// Parse from config strings (`tcp`, `stub`, `native`).
+    pub fn parse(s: &str) -> ConfigResult<Self> {
+        match s.trim().to_ascii_lowercase().as_str() {
+            "tcp" | "stub" => Ok(Self::Tcp),
+            "native" => Ok(Self::Native),
+            "" => Err(ConfigError::InvalidValue {
+                field: "backend.transport".to_string(),
+                reason: "Cannot be empty".to_string(),
+            }),
+            other => Err(ConfigError::InvalidValue {
+                field: "backend.transport".to_string(),
+                reason: format!("Must be tcp or native, got: {other}"),
+            }),
+        }
+    }
+}
+
+impl std::str::FromStr for BackendTransport {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::parse(s).map_err(|e| e.to_string())
+    }
+}
+
 /// Backend configuration
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BackendConfig {
-    /// Backend type (openocd, probe-rs, pyocd)
+    /// Label for the stub or tool (openocd, probe-rs, pyocd, …) — logging / future use only.
     #[serde(default = "default_backend_type")]
     pub backend_type: String,
 
+    /// Transport to the target (`tcp` = remote stub; `native` reserved).
+    #[serde(default)]
+    pub transport: BackendTransport,
+
     /// Backend-specific options
     #[serde(default)]
     pub options: std::collections::HashMap<String, String>,
@@ -235,6 +277,7 @@ impl Default for BackendConfig {
     fn default() -> Self {
         Self {
             backend_type: default_backend_type(),
+            transport: BackendTransport::default(),
             options: std::collections::HashMap::new(),
         }
     }
@@ -326,12 +369,11 @@ impl Config {
             });
         }
 
-        // Validate backend config
-        let valid_backends = ["openocd", "probe-rs", "pyocd"];
-        if !valid_backends.contains(&self.backend.backend_type.as_str()) {
+        // Backend label is free-form (openocd, probe-rs, custom); must not be empty.
+        if self.backend.backend_type.trim().is_empty() {
             return Err(ConfigError::InvalidValue {
                 field: "backend.backend_type".to_string(),
-                reason: format!("Must be one of: {}", valid_backends.join(", ")),
+                reason: "Cannot be empty".to_string(),
             });
         }
 
@@ -382,6 +424,12 @@ impl Config {
             self.backend.backend_type = backend;
         }
 
+        if let Ok(t) = std::env::var("RSGDB_TRANSPORT") {
+            if let Ok(tr) = BackendTransport::parse(&t) {
+                self.backend.transport = tr;
+            }
+        }
+
         if let Ok(v) = std::env::var("RSGDB_RECORD") {
             let v = v.trim();
             if v == "1" || v.eq_ignore_ascii_case("true") || v.eq_ignore_ascii_case("yes") {

src/lib.rs

@@ -37,12 +37,12 @@ pub mod scaffold;
 pub mod svd;
 
 // Stable names for scaffold submodules (see `scaffold` module docs).
-pub use scaffold::breakpoints;
-pub use scaffold::state;
-pub use scaffold::ui;
+pub use scaffold::{breakpoints, state, ui};
+
+pub use crate::backends::connect_backend;
 
 // Re-export commonly used types
-pub use config::{Config, FlashConfig, SvdConfig};
+pub use config::{BackendConfig, BackendTransport, Config, FlashConfig, SvdConfig};
 pub use error::{Result, RsgdbError};
 pub use logging_setup::{init_from_logging_config, LoggingInitGuard};
 

src/main.rs

@@ -4,7 +4,7 @@
 
 use anyhow::Context;
 use clap::{Parser, Subcommand};
-use rsgdb::config::Config;
+use rsgdb::config::{BackendTransport, Config};
 use rsgdb::flash;
 use rsgdb::proxy::ProxyServer;
 use rsgdb::svd::SvdIndex;
@@ -92,6 +92,10 @@ struct ProxyArgs {
     /// CMSIS-SVD file path (peripheral/register labels for memory RSP in logs)
     #[arg(long, value_name = "FILE")]
     svd: Option<PathBuf>,
+
+    /// Backend transport: `tcp` (GDB stub on target_host:target_port) or `native` (not implemented)
+    #[arg(long, value_name = "tcp|native")]
+    transport: Option<String>,
 }
 
 #[tokio::main]
@@ -195,6 +199,10 @@ async fn run_proxy(args: ProxyArgs) -> anyhow::Result<()> {
     if let Some(backend) = args.backend {
         config.backend.backend_type = backend;
     }
+    if let Some(ref t) = args.transport {
+        config.backend.transport =
+            BackendTransport::parse(t).map_err(|e| anyhow::anyhow!("{}", e))?;
+    }
 
     if args.record {
         config.recording.enabled = true;
@@ -242,13 +250,19 @@ async fn run_proxy(args: ProxyArgs) -> anyhow::Result<()> {
 
     info!(
         backend_type = %config.backend.backend_type,
-        "Configured debug backend (for future integration)"
+        transport = ?config.backend.transport,
+        "Configured debug backend"
     );
 
     info!("Configuration: {:?}", config);
 
-    let mut server =
-        ProxyServer::new(config.proxy.clone(), config.recording.clone(), svd_index).await?;
+    let mut server = ProxyServer::new(
+        config.proxy.clone(),
+        config.backend.clone(),
+        config.recording.clone(),
+        svd_index,
+    )
+    .await?;
 
     info!(
         listen = %server.local_addr()?,