feat: allow choosing expose bind address

Author: dstoc

README.md

@@ -82,9 +82,14 @@ In short: the agent cannot freely access the network; users can run sandbox comm
   ```bash
   cladding expose 3000
   cladding expose 3000 9000
+  cladding expose 3000 --bind-address 192.168.1.20
+  cladding expose 3000 9000 --bind-address ::1
   ```
 
-  `cladding expose` runs in the foreground. Stop it with Ctrl-C.
+  `cladding expose` runs in the foreground and defaults to listening on
+  `127.0.0.1`. Use `--bind-address` to select a host IP address; `0.0.0.0`
+  or `::` listens on all IPv4 or IPv6 interfaces respectively. Stop it with
+  Ctrl-C.
 
 * Temporarily make one host-reachable TCP endpoint available on agent localhost while the project is running:
 
@@ -215,7 +220,7 @@ cladding check        # verify required paths/images
 cladding ps           # list running cladding projects
 cladding run [--env KEY[=VALUE] ...] [cmd] # run a command in the agent container
 cladding run-with-scissors [--target nw-sandbox|fs-sandbox] [--env KEY[=VALUE] ...] [cmd] # run a command in an enabled sandbox container
-cladding expose <containerport> [hostport] # block while forwarding localhost hostport to agent containerport
+cladding expose <containerport> [hostport] [--bind-address <address>] # block while forwarding host address/port to agent containerport
 cladding inject <host-endpoint> [containerport] # block while forwarding agent localhost containerport to a host-reachable endpoint
 cladding reload-proxy # reconfigure squid after domain-list edits
 cladding logs [agent|proxy|nw-sandbox|fs-sandbox] [podman logs args...] # view container logs

docs/features/current-runtime-summary.md

@@ -38,7 +38,7 @@ The proxy bridge sidecar uses the proxy socket directories. The agent uses the p
 
 ## Blocking `cladding expose`
 - `cladding expose <container-port> [host-port]` runs in the foreground on the host.
-- It binds `127.0.0.1:<host-port>` and forwards through `cladding run socat ...` to `127.0.0.1:<container-port>` inside the agent container.
+- It binds `127.0.0.1:<host-port>` by default, or the address selected with `--bind-address`, and forwards through `cladding run socat ...` to `127.0.0.1:<container-port>` inside the agent container.
 - No persistent expose containers are created.
 
 ## Blocking `cladding inject`

src/cli/args.rs

@@ -1,5 +1,6 @@
 use cladding::config::ExecutionConfig;
 use clap::{ArgAction, Args, Parser, Subcommand, ValueEnum};
+use std::net::IpAddr;
 use std::path::PathBuf;
 
 const VERSION: &str = jj_version::jj_version!(fallback = env!("CARGO_PKG_VERSION"),);
@@ -75,6 +76,9 @@ pub(super) struct ExposeArgs {
     pub(super) container_port: u16,
     #[arg(value_name = "HOSTPORT", value_parser = clap::value_parser!(u16).range(1..=65535))]
     pub(super) host_port: Option<u16>,
+    /// Host IP address on which to listen
+    #[arg(long, value_name = "ADDRESS", default_value = "127.0.0.1")]
+    pub(super) bind_address: IpAddr,
 }
 
 #[derive(Debug, Args)]
@@ -223,6 +227,7 @@ mod tests {
             CommandSpec::Expose(args) => {
                 assert_eq!(args.container_port, 3000);
                 assert_eq!(args.host_port, None);
+                assert_eq!(args.bind_address, "127.0.0.1".parse::<IpAddr>().unwrap());
             }
             other => panic!("unexpected command: {other:?}"),
         }
@@ -235,11 +240,46 @@ mod tests {
             CommandSpec::Expose(args) => {
                 assert_eq!(args.container_port, 3000);
                 assert_eq!(args.host_port, Some(9000));
+                assert_eq!(args.bind_address, "127.0.0.1".parse::<IpAddr>().unwrap());
             }
             other => panic!("unexpected command: {other:?}"),
         }
     }
 
+    #[test]
+    fn expose_bind_address_parses_ipv4_and_ipv6() {
+        let ipv4 = Cli::try_parse_from([
+            "cladding",
+            "expose",
+            "3000",
+            "--bind-address",
+            "192.168.1.20",
+        ])
+        .expect("ipv4 bind address should parse");
+        match ipv4.command.expect("command") {
+            CommandSpec::Expose(args) => {
+                assert_eq!(args.bind_address, "192.168.1.20".parse::<IpAddr>().unwrap());
+            }
+            other => panic!("unexpected command: {other:?}"),
+        }
+
+        let ipv6 = Cli::try_parse_from(["cladding", "expose", "3000", "--bind-address", "::1"])
+            .expect("ipv6 bind address should parse");
+        match ipv6.command.expect("command") {
+            CommandSpec::Expose(args) => {
+                assert_eq!(args.bind_address, "::1".parse::<IpAddr>().unwrap());
+            }
+            other => panic!("unexpected command: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn expose_bind_address_rejects_interface_names() {
+        assert!(
+            Cli::try_parse_from(["cladding", "expose", "3000", "--bind-address", "eth0",]).is_err()
+        );
+    }
+
     #[test]
     fn up_and_down_verbose_flags_parse() {
         let up = Cli::try_parse_from(["cladding", "up", "-v"]).expect("cli parse");

src/cli/expose.rs

@@ -7,6 +7,7 @@ use cladding::error::{Error, Result};
 use cladding::fs_utils::is_executable;
 use cladding::podman::{podman_container_exists, podman_required};
 use std::env;
+use std::net::IpAddr;
 use std::path::Path;
 use std::process::Command;
 
@@ -35,9 +36,14 @@ pub(super) fn cmd_expose(context: &Context, args: &ExposeArgs) -> Result<()> {
     let host_port = args.host_port.unwrap_or(args.container_port);
     let current_exe =
         env::current_exe().with_context(|| "failed to determine current executable")?;
-    let status = build_blocking_expose_command(&current_exe, args.container_port, host_port)
-        .status()
-        .with_context(|| "failed to run socat")?;
+    let status = build_blocking_expose_command(
+        &current_exe,
+        args.container_port,
+        host_port,
+        args.bind_address,
+    )
+    .status()
+    .with_context(|| "failed to run socat")?;
 
     cladding::podman::ensure_success(status, "socat")
 }
@@ -61,10 +67,15 @@ fn build_blocking_expose_command(
     current_exe: &Path,
     container_port: u16,
     host_port: u16,
+    bind_address: IpAddr,
 ) -> Command {
     let mut cmd = Command::new("socat");
+    let listener = match bind_address {
+        IpAddr::V4(_) => "TCP4-LISTEN",
+        IpAddr::V6(_) => "TCP6-LISTEN",
+    };
     cmd.arg(format!(
-        "TCP-LISTEN:{host_port},bind=127.0.0.1,reuseaddr,fork"
+        "{listener}:{host_port},bind={bind_address},reuseaddr,fork"
     ));
     let current_exe = shell_single_quote_path(current_exe);
     cmd.arg(format!(
@@ -95,16 +106,30 @@ mod tests {
             Path::new("/tmp/cladding test/bin's/cladding"),
             5432,
             15432,
+            "127.0.0.1".parse::<IpAddr>().unwrap(),
         );
         let args = command_args(&cmd);
 
         assert_eq!(cmd.get_program().to_string_lossy(), "socat");
         assert_eq!(args.len(), 2);
-        assert_eq!(args[0], "TCP-LISTEN:15432,bind=127.0.0.1,reuseaddr,fork");
+        assert_eq!(args[0], "TCP4-LISTEN:15432,bind=127.0.0.1,reuseaddr,fork");
         assert_eq!(
             args[1],
             "EXEC:'/tmp/cladding test/bin'\\''s/cladding' run socat STDIO TCP\\:127.0.0.1\\:5432"
         );
         assert!(!args.iter().any(|arg| arg.starts_with("--")));
     }
+
+    #[test]
+    fn build_blocking_expose_command_uses_ipv6_listener_for_ipv6_bind() {
+        let cmd = build_blocking_expose_command(
+            Path::new("/usr/local/bin/cladding"),
+            3000,
+            9000,
+            "::1".parse::<IpAddr>().unwrap(),
+        );
+        let args = command_args(&cmd);
+
+        assert_eq!(args[0], "TCP6-LISTEN:9000,bind=::1,reuseaddr,fork");
+    }
 }