boxmaker/docs/plans/M3b/11-brokerd-container.md

# M3b task 11: the Podman runtime

**Branch:** `m3b` (run `git switch m3b`; `git status --short` must be empty, otherwise stop)
**Commit subject:** `brokerd: the Podman runtime`

## Goal

`Podman` implements `Runtime`: each call runs in a fresh container, its arguments go on standard
input, its output is kept up to a cap, and it is stopped at its time limit. Whatever the tool
prints is the result's content, labelled by the grant; every failure is a **fixed sentence**, and
what Podman itself said goes only to `brokerd`'s log. Spec section 6, "One call". `http_fetch`'s
proxy is task 12; in this task every call runs its container with no egress directory.

## Files

- Copy: `crates/brokerd/tests/support/fake_podman.rs`, `crates/brokerd/tests/container.rs`, and
  the **skeleton** `crates/brokerd/src/container.rs` (every signature, the constants, and `todo!()`
  bodies with the steps as comments)
- Fill in: `crates/brokerd/src/container.rs`
- Modify: `crates/brokerd/src/lib.rs` (`pub mod container;`), `docs/implementer-log.md`

## Interfaces

```rust
pub const RUNBOOK: &str = "see docs/runbook.md#runner-unavailable";
pub const COULD_NOT_RUN: &str = "the tool could not run";
pub const CANNOT_START: &str = "the tool runner could not start the container";
pub const KILLED: &str = "the tool was stopped: it ran out of memory or was killed";
pub const TIMED_OUT: &str = "the tool ran past its time limit";
pub const UNEXPECTED: &str = "the tool failed with an unexpected status";
pub const POLL: Duration = Duration::from_millis(50);
pub const STDERR_KEPT: usize = 4096;

pub type Log = Arc<dyn Fn(&str) + Send + Sync>;

pub struct Podman { /* runner: Runner, egress_dir: PathBuf, log: Log, next: AtomicU64 — private */ }
impl Podman {
    /// `egress_dir` is `Config::egress_dir()`; task 12 uses it.
    pub fn new(runner: Runner, egress_dir: PathBuf, log: Log) -> Podman;
    /// Where `http_fetch` calls get their directories. Nothing in this task calls it; it is public,
    /// so the field counts as read and clippy's `dead_code` does not fire. Do not add `#[allow]`.
    pub fn egress_dir(&self) -> &Path;
}
impl Runtime for Podman {
    fn run(&self, spec: &RunSpec) -> Result<RunOutput, RunError>;
}
```

## `run`: every step and exit

1. `n = next.fetch_add(1, SeqCst)`; `name = podman::container_name(spec.session(), spec.call(), n)`.
   The first call of a `Podman` is number 0.
2. `args = podman::tool_args(spec, &runner, &name, None)`;
   `input = spec.arguments().canonical_json()`; `limit = runner.time_limit(spec.tool())`.
3. Spawn `Command::new(&runner.podman).args(args)` with standard input, output and error all
   piped. A failure → log `brokerd: cannot start {podman path}: {e}` + `"\n"` + `RUNBOOK`, and
   return `Err(RunError::Unavailable(CANNOT_START))`.
4. Three threads, so no pipe can block another: one **writes** `input` to standard input and then
   drops it (closing it); one **reads** standard output, keeping the first `output_cap` bytes and
   **reading on past the cap**, throwing the rest away, and remembering that there was more; one
   reads standard error the same way, keeping `STDERR_KEPT` bytes. (Stopping to read would leave
   the tool blocked on a full pipe; closing the pipe would make Podman fail. Both give the wrong
   answer.) Write the reading loop once, as a private function returning `(Vec<u8>, bool)`.
5. Wait with a loop: `child.try_wait()`; if it has ended, go to 6. If `limit` has passed since the
   spawn, **stop the container**: run `podman kill <name>`, then `podman rm -f <name>` (each with
   `.status()`, standard streams null; log a line if one does not succeed, and go on), then
   `child.kill()` and `child.wait()`. Otherwise sleep `POLL` and try again.
6. Join the three threads (a thread that panicked counts as empty output).
7. The answer:

| How it ended | Answer | Log |
|---|---|---|
| past the time limit (step 5) | `Err(RunError::Failed(TIMED_OUT))` | a line naming the container |
| exit 0 or 1 | `Ok(RunOutput { content, truncated })`, content = the kept output decoded with `from_utf8_lossy` | — |
| exit 2 | `Err(RunError::Failed(COULD_NOT_RUN))` | the kept standard error |
| exit 125, 126 or 127 | `Err(RunError::Unavailable(CANNOT_START))` | the kept standard error, then `"\n"` + `RUNBOOK` |
| exit 137 | `Err(RunError::Failed(KILLED))` | — |
| anything else, including killed by a signal | `Err(RunError::Failed(UNEXPECTED))` | the status and the kept standard error |

**The tool's output never goes into a `RunError`**: only the six constants do.

Also add `pub(crate) fn podman(&self, args: &[&str])`, the helper step 5 uses to run a short
`podman` command and log if it fails; task 12 uses it too.

## About the given tests

The tests run `brokerd`'s real `runner::run` against a fake `podman`: a shell script that records
every call's arguments in a file and then does what the test says. As in task 06, every test takes
the `serial()` lock first, because writing a script and running it at once races with other tests'
forks ("Text file busy"). The time-limit test's fake ends with `exec sleep 30`, so killing the
process kills the sleep and nothing keeps the pipes open.

## How to work (read this first)

Three earlier sessions on this task ended without a commit: each tried to plan the whole file
(the third, the whole of `run`) in one turn and ran out of room while still deciding. So:

- **Start from the skeleton.** It compiles. `run` and `run_container` are **already written**: they
  only call the helpers. Replace the `todo!()`s **one function at a time**, in this order:
  `read_capped`, `new`, `egress_dir`, `podman`, `wait`, `spawn` (step 3), `Io::start` (step 4),
  `Io::finish` (step 6), `answer` (step 7, the table). After each, run `cargo check -p brokerd`
  and fix what it says before going on. Each helper is a few lines; none needs the others'
  details beyond its signature.
- **Let the compiler answer API questions.** If you are unsure whether something compiles (how to
  call the log, which trait a type has), write it and run `cargo check`. The log is called as
  `(self.log)(&line)`.
- Keep each turn short: write, check, next. Do not restate the task to yourself.

## Steps

- [ ] **1. Copy.** `git switch m3b`, then
  `cp docs/plans/M3b/files/crates/brokerd/tests/support/fake_podman.rs crates/brokerd/tests/support/`
  and `cp docs/plans/M3b/files/crates/brokerd/tests/container.rs crates/brokerd/tests/`
  and `cp docs/plans/M3b/files/crates/brokerd/src/container.rs crates/brokerd/src/`, then add
  `pub mod container;` to `crates/brokerd/src/lib.rs` after `pub mod config;`.
- [ ] **2. See it fail.** `cargo test -p brokerd --test container`. Expected: it compiles (with
  warnings about unused variables) and all 11 fail on `todo!()`.
- [ ] **3. Fill in `container.rs`** as in "How to work". Delete the skeleton paragraph from the
  module doc. Run `cargo fmt --all`.
- [ ] **4. See it pass.** `cargo test -p brokerd --test container`. Expected: 11 passed. Run it ten
  times; it must pass every time.
- [ ] **5. Walk the table.** Point at the line of your code for each row, and check that no row
  puts output into a `RunError`.
- [ ] **6. Run the gate.** `make gate`. Expected last line: `gate: ok`.
- [ ] **7. Log and commit.** `git add crates/brokerd docs/implementer-log.md Cargo.lock && git commit`

## Done when

- `cargo test -p brokerd --test container` reports 11 passed ten times running; `make gate` prints
  `gate: ok`.

## Stop and report if

- A test hangs, or fails only sometimes: report which, and how often, rather than add sleeps.
- A test wants tool output inside a failure message.