Add detached processes and port forwarding to the provider traits

README.md

@@ -177,6 +177,35 @@ Publish a port with `-p`:
 tinybox create --sandbox docker --image nginx -p 8080:80
 ```
 
+## Something that keeps running
+
+`exec` waits for the command, which is right for a build and wrong for a server.
+`spawn` starts one and hands back an identifier instead:
+
+```sh
+tinybox create --sandbox docker --image nginx -p 8080:80
+pid=$(tinybox spawn box-0 -- nginx -g 'daemon off;')
+tinybox ps box-0 "$pid"            # -> running
+tinybox kill box-0 "$pid"          # -> stopped
+```
+
+The process survives between commands, which is what a sandbox declaring
+`Detach` is promising — `tinybox inspect` says which ones do. `passthrough` and
+`docker` do; `namespace` and `microvm` decline rather than background something
+they could not find again.
+
+Publishing puts that port on the machine the box runs on. When that machine is
+somewhere else, `forward` closes the gap:
+
+```sh
+tinybox --host ssh://builder@example.com forward 8080
+# 127.0.0.1:54321                  # ...and the tunnel lasts as long as this runs
+```
+
+Reach was always the `Host`'s question, so a tunnel is answered there too — see
+[ADR 0007](docs/adr/0007-reach-includes-forwarding-and-detachment.md). Nothing
+in `ssh` or `docker` knows about the other, here either.
+
 ## Without a daemon
 
 `namespace` isolates a directory you already have, using Linux namespaces

crates/tinybox-cli/src/command/mod.rs

@@ -8,7 +8,7 @@ use std::sync::Arc;
 use clap::{Parser, Subcommand, ValueEnum};
 use tinybox_core::{
     BoxId, BoxInfo, BoxSpec, Clock, Error, ExecRequest, Host, HostRef, NetworkPolicy,
-    PassthroughSandbox, Placement, PortMapping, Sandbox, SandboxRef, SnapshotId, Store,
+    PassthroughSandbox, Placement, PortMapping, ProcessId, Sandbox, SandboxRef, SnapshotId, Store,
     SystemClock, TemplateName, Templates, WorkspaceSource, passthrough,
 };
 use tinybox_docker::DockerSandbox;
@@ -177,6 +177,47 @@ enum Command {
         #[arg(trailing_var_arg = true, required = true, value_name = "COMMAND")]
         argv: Vec<String>,
     },
+    /// Start a command in a box and leave it running.
+    ///
+    /// Where `exec` waits, this returns a process id as soon as the command is
+    /// started. It is how a server gets into a box; `exec` would never return.
+    Spawn {
+        /// Which box to start it in.
+        id: String,
+        /// The command and its arguments.
+        #[arg(trailing_var_arg = true, required = true, value_name = "COMMAND")]
+        argv: Vec<String>,
+    },
+    /// Report whether a spawned process is still running.
+    Ps {
+        /// Which box it was started in.
+        id: String,
+        /// The process id `spawn` printed.
+        process: String,
+    },
+    /// Stop a spawned process.
+    ///
+    /// Succeeds when it has already exited: stopping something already stopped
+    /// is the outcome the caller wanted.
+    Kill {
+        /// Which box it was started in.
+        id: String,
+        /// The process id `spawn` printed.
+        process: String,
+    },
+    /// Make a port on the box's machine reachable from this one.
+    ///
+    /// Publishing a port (`create -p`) puts it on the machine the box runs on.
+    /// When that is somewhere else, this is what closes the gap. The tunnel
+    /// lasts as long as the command runs, so it holds until interrupted.
+    Forward {
+        /// The port on the box's machine.
+        port: u16,
+        /// The address to reach it at over there. Defaults to loopback, which
+        /// is where a published port lands.
+        #[arg(long, value_name = "IP", default_value = "127.0.0.1")]
+        address: std::net::IpAddr,
+    },
     /// List every box.
     #[command(alias = "list")]
     Ls,
@@ -350,12 +391,11 @@ impl Cli {
                 )?;
                 announce(&sandbox.create(&spec).await?, sandbox.as_ref(), out, err)
             }
-            Command::Exec { id, argv } => {
-                let id = BoxId::new(id)?;
-                let sandbox = build(sandbox_of(&store, &id)?)?;
-                let output = sandbox.exec(&id, &ExecRequest::new(argv)).await?;
-                report(&output, out, err)
-            }
+            Command::Exec { id, argv } => exec(&store, &backends, id, argv, out, err).await,
+            Command::Spawn { id, argv } => spawn(&store, &backends, id, argv, out).await,
+            Command::Ps { id, process } => probe(&store, &backends, id, &process, out).await,
+            Command::Kill { id, process } => kill(&store, &backends, id, &process, out).await,
+            Command::Forward { port, address } => forward(reach.as_ref(), address, port, out).await,
             // Listing is the store's business, not the sandbox's: the store is
             // what owns the set of records.
             Command::Ls => text(out, &render_listing(&store.list()?)),
@@ -570,6 +610,37 @@ fn line(out: &mut dyn Write, value: &str) -> tinybox_core::Result<u8> {
     text(out, &format!("{value}\n"))
 }
 
+/// Open a tunnel to `remote` and hold it until the process is interrupted.
+///
+/// The forward is a guard, so it exists for exactly as long as this function
+/// runs. There is no daemon to hand it to and no state file that could
+/// describe a tunnel this process is no longer holding open, so blocking is
+/// the honest shape: the command running *is* the forward existing.
+///
+/// # Errors
+///
+/// Returns whatever the host reports when the tunnel cannot be opened —
+/// [`Error::Unsupported`] from a host that cannot tunnel at all.
+async fn forward(
+    reach: &dyn Host,
+    address: std::net::IpAddr,
+    port: u16,
+    out: &mut dyn Write,
+) -> tinybox_core::Result<u8> {
+    let forwarded = reach.forward((address, port).into()).await?;
+    line(out, &forwarded.local_addr().to_string())?;
+
+    if forwarded.is_direct() {
+        // Nothing is being held open, so there is nothing to hold *for*.
+        // Blocking here would look like a working tunnel and be a hang.
+        return Ok(0);
+    }
+    // Park until the terminal interrupts us; dropping `forwarded` on the way
+    // out closes the tunnel.
+    std::future::pending::<()>().await;
+    Ok(0)
+}
+
 /// Forward a finished command's output and status to the caller.
 ///
 /// # Errors
@@ -783,6 +854,94 @@ fn render_sync(outcome: &tinybox_sync::Sync) -> String {
 /// Returns [`Error::InvalidIdentifier`] when a Docker namespace is not a valid
 /// identifier.
 /// Destroy one box and print its identifier back.
+/// Run a command in a box, mirroring its output and exit status.
+///
+/// # Errors
+///
+/// Returns whatever the backend reports when the command could not be started.
+/// A command that runs and exits non-zero is **not** an error: its status
+/// becomes this process's.
+async fn exec(
+    store: &Arc<dyn Store>,
+    backends: &Backends<'_>,
+    id: String,
+    argv: Vec<String>,
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+) -> tinybox_core::Result<u8> {
+    let id = BoxId::new(id)?;
+    let sandbox = backends.get(sandbox_of(store, &id)?)?;
+    let output = sandbox.exec(&id, &ExecRequest::new(argv)).await?;
+    report(&output, out, err)
+}
+
+/// Start a command in a box and print the identifier for asking about it.
+///
+/// # Errors
+///
+/// Returns [`Error::Unsupported`] when the box's sandbox cannot host a process
+/// between commands, and whatever the backend reports when the command could
+/// not be started.
+async fn spawn(
+    store: &Arc<dyn Store>,
+    backends: &Backends<'_>,
+    id: String,
+    argv: Vec<String>,
+    out: &mut dyn Write,
+) -> tinybox_core::Result<u8> {
+    let id = BoxId::new(id)?;
+    let sandbox = backends.get(sandbox_of(store, &id)?)?;
+    let process = sandbox.spawn(&id, &ExecRequest::new(argv)).await?;
+    line(out, process.as_ref())
+}
+
+/// Report whether a spawned process is still running.
+///
+/// A process that has exited prints `gone` and exits zero: that it finished is
+/// an answer, and reporting it as a failure would be indistinguishable from an
+/// unreachable box.
+///
+/// # Errors
+///
+/// Returns [`Error::Unsupported`] when the box's sandbox does not track
+/// detached processes, and a backend error when the box cannot be reached.
+async fn probe(
+    store: &Arc<dyn Store>,
+    backends: &Backends<'_>,
+    id: String,
+    process: &str,
+    out: &mut dyn Write,
+) -> tinybox_core::Result<u8> {
+    let id = BoxId::new(id)?;
+    let sandbox = backends.get(sandbox_of(store, &id)?)?;
+    let running = sandbox
+        .is_running(&id, &ProcessId::new(process.to_owned())?)
+        .await?;
+    line(out, if running { "running" } else { "gone" })
+}
+
+/// Stop a spawned process.
+///
+/// # Errors
+///
+/// Returns [`Error::Unsupported`] when the box's sandbox does not track
+/// detached processes, and a backend error when the box cannot be reached. A
+/// process that had already exited is not an error.
+async fn kill(
+    store: &Arc<dyn Store>,
+    backends: &Backends<'_>,
+    id: String,
+    process: &str,
+    out: &mut dyn Write,
+) -> tinybox_core::Result<u8> {
+    let id = BoxId::new(id)?;
+    let sandbox = backends.get(sandbox_of(store, &id)?)?;
+    sandbox
+        .stop(&id, &ProcessId::new(process.to_owned())?)
+        .await?;
+    line(out, "stopped")
+}
+
 async fn remove(
     store: &Arc<dyn Store>,
     backends: &Backends<'_>,

crates/tinybox-cli/src/command/test.rs

@@ -533,13 +533,16 @@ async fn inspect_lists_what_the_sandbox_declares() -> Result<()> {
 
     let inspected = invoke(dir.path(), &["inspect", "box-0"]).await;
 
-    // Passthrough declares nothing, and says that rather than printing an
-    // empty list the reader has to interpret.
+    // Passthrough declares detached processes and nothing else: a box here is
+    // an ordinary directory on this machine, so a backgrounded process really
+    // does survive between commands, but there is no filesystem boundary to
+    // snapshot and no limit it can apply.
     assert!(
-        inspected
-            .out
-            .contains("supports:   nothing beyond running commands")
+        inspected.out.contains("supports:   detached processes"),
+        "{}",
+        inspected.out
     );
+    assert!(!inspected.out.contains("filesystem snapshots"));
     Ok(())
 }
 
@@ -1298,3 +1301,94 @@ fn write_boxes(dir: &Path, boxes: &[(&str, Option<std::time::SystemTime>)]) -> R
     std::fs::write(dir.join("boxes.json"), format!("{{{}}}", records.join(",")))
         .map_err(|error| Error::io("write", &error))
 }
+
+#[tokio::test]
+async fn a_spawned_process_outlives_the_command_that_started_it() -> Result<()> {
+    // The whole point of `spawn` over `exec`: a separate invocation is standing
+    // in for a separate process, and the thing started by the first one is
+    // still there for the second to ask about.
+    let dir = temp_dir()?;
+    invoke(dir.path(), &["create", "--dir", "/tmp"]).await;
+
+    let spawned = invoke(dir.path(), &["spawn", "box-0", "sleep", "30"]).await;
+    assert_eq!(spawned.code, 0);
+    let process = spawned.out.trim().to_owned();
+    assert!(!process.is_empty(), "spawn prints an identifier");
+
+    let running = invoke(dir.path(), &["ps", "box-0", &process]).await;
+    assert_eq!(running.out.trim(), "running");
+
+    let killed = invoke(dir.path(), &["kill", "box-0", &process]).await;
+    assert_eq!(killed.code, 0);
+
+    let gone = invoke(dir.path(), &["ps", "box-0", &process]).await;
+    // `gone` on stdout with a zero exit: the process finishing is an answer,
+    // not a failure, and reporting it as one would be indistinguishable from
+    // an unreachable box.
+    assert_eq!(gone.code, 0);
+    assert_eq!(gone.out.trim(), "gone");
+    Ok(())
+}
+
+#[tokio::test]
+async fn asking_about_a_process_that_was_never_started_answers_gone() -> Result<()> {
+    let dir = temp_dir()?;
+    invoke(dir.path(), &["create", "--dir", "/tmp"]).await;
+
+    let answer = invoke(dir.path(), &["ps", "box-0", "p1-0"]).await;
+
+    assert_eq!(answer.code, 0);
+    assert_eq!(answer.out.trim(), "gone");
+    Ok(())
+}
+
+#[tokio::test]
+async fn killing_a_process_that_has_already_exited_is_not_an_error() -> Result<()> {
+    // Stopping something already stopped is the outcome the caller wanted.
+    let dir = temp_dir()?;
+    invoke(dir.path(), &["create", "--dir", "/tmp"]).await;
+
+    let killed = invoke(dir.path(), &["kill", "box-0", "p1-0"]).await;
+
+    assert_eq!(killed.code, 0);
+    Ok(())
+}
+
+#[tokio::test]
+async fn a_local_forward_reports_the_address_and_returns() -> Result<()> {
+    // Nothing is held open on a local host, so blocking would look like a
+    // working tunnel and be a hang.
+    let dir = temp_dir()?;
+
+    let forwarded = invoke(dir.path(), &["forward", "7788"]).await;
+
+    assert_eq!(forwarded.code, 0);
+    assert_eq!(forwarded.out.trim(), "127.0.0.1:7788");
+    Ok(())
+}
+
+#[tokio::test]
+async fn spawning_into_a_sandbox_that_cannot_detach_is_refused() -> Result<()> {
+    // A namespace box is a record and a bound directory rather than a running
+    // container, so a backgrounded process would not survive to be found. It
+    // says so instead.
+    let dir = temp_dir()?;
+    let created = invoke(
+        dir.path(),
+        &["create", "--sandbox", "namespace", "--dir", "/tmp"],
+    )
+    .await;
+    if created.code != 0 {
+        return Ok(()); // No bubblewrap on this host.
+    }
+
+    let spawned = invoke(dir.path(), &["spawn", "box-0", "sleep", "30"]).await;
+
+    assert_eq!(spawned.code, EXIT_TINYBOX_ERROR);
+    assert!(
+        spawned.err.contains("detached processes"),
+        "{}",
+        spawned.err
+    );
+    Ok(())
+}