tobogganSe connecter

louise

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

140 lignes · 7466 octetsBrut · Historique

ADR 0085: std/command runs another program to its end: argv only, nothing inherited, bounded, killed with its process group

Status: Proposed (2026-11-16); needs engineering review (#44).

Context

  • A Louise program cannot run another program. std/process is the actor runtime, std/os has the environment, arguments, exit and signals, and nothing starts an OS process (issue #467).
  • toki2 needs well-known tools it will not rewrite: a page archiver (headless Chromium, monolith), pdftotext, tesseract, yt-dlp, ffmpeg (toki2#57). Several are not libraries, so C bindings are not an option.
  • Running programs from a server is a classic hole: a shell that interprets an argument, an inherited environment that leaks secrets, a program that never ends, output that fills memory, children left behind when the server restarts.
  • The runtime blocks SIGTERM, SIGINT and SIGHUP in every thread and takes them on a signal thread (ADR 0060). A child inherits a blocked mask across exec; ADR 0060 already noted that a child "should reset it".
  • Rust's std::process::Command keeps the parent's mask in the child on both its spawn paths (posix_spawn and fork; toolchain std/src/sys/process/unix/unix.rs). A child started with it ignores SIGTERM, so a timeout could only ever SIGKILL it.
  • The scheduler parks actors on a mio reactor (sockets, net.rs), and a kill wakes an actor parked on it. The blocking pool cannot be woken by a kill (Wait::Blocking), so a run must not wait there.
  • ADR 0084 (capability roots, unmerged) moves files and sockets behind fs and net roots. It excludes OS process powers on purpose.

Decision

std/command.run :: Command -> Result<Output, Error> / <io> runs a program to its end. command.new program args gives the defaults; a field changes with Command(..cmd, field: value).

  • No shell. args reach the program as they are. A program named without a / is looked up in the PATH of env, absolute entries only, never in the caller's.

  • Nothing inherited. The environment is exactly env. Every descriptor the runtime opens is close-on-exec, so the child gets only its three pipes.

  • Bounded.

    • Output past max_stdout or max_stderr (16 MiB and 64 KiB by default) is read and dropped, so the program never blocks on a full pipe. The run says it was cut.
    • At timeout_ms (30 s) the child's process group gets SIGTERM, and SIGKILL grace_ms (2 s) later. TimedOut(signal) names the last one sent.
    • When the program ends, what is left of its group is killed, and the pipes are drained for at most grace_ms: a descendant that left the group with setsid may hold them open.
  • Scratch. Scratch(inputs, outputs, max_file) runs the program in a fresh 0700 directory under the temporary directory:

    • inputs are written with O_EXCL|O_NOFOLLOW;
    • the listed outputs are read back, regular files only, opened O_NOFOLLOW|O_NONBLOCK and at most max_file bytes each (Found, TooLarge, Absent);
    • the directory is then removed.

    A caller that only has bytes thus never touches the file system itself, and std/file needs no directory operations for this.

  • posix_spawn directly (runtime/louise_rt_prims/src/command.rs), not Rust's Command:

    • an empty signal mask, every disposition back to its default, and a process group of the child's own (POSIX_SPAWN_SETSIGMASK, SETSIGDEF, SETPGROUP);
    • the pipes become the child's 0, 1 and 2, and addchdir_np sets its working directory;
    • everything is built before the call, so the child runs no Rust. glibc's posix_spawn uses CLONE_VFORK, so no copy of a large heap is made.
  • Never blocking a scheduler thread.

    • The child's pipes, a pidfd (its exit) and a timerfd (the next deadline) are registered with the reactor under one token, and the actor parks on it as on a socket.
    • Each wake-up does what can be done without waiting: drain the pipes, feed stdin, check the pidfd with waitid(P_PIDFD, WNOHANG), send the signal that is due.
    • Stdin is written with SIGPIPE blocked on the thread, and a pending one taken, so a program that stops reading gives EPIPE, never the end of ours.
    • The interpreter runs the same driver, waiting with poll(2). A run is unrepeatable for the test cache.
  • No zombies, no orphans.

    • A killed actor drops its run, which kills the group and reaps the child. A child that does not die at once (uninterruptible sleep) is reaped by a louise-reaper thread, never an actor's.
    • The runtime keeps the groups still running, and an atexit handler kills them when the program exits, by main's end, os.exit or a signal's default action.
  • <io>, like std/os. Running a program is OS authority, which ADR 0084 leaves out of its roots. A sixth root would also spill past the six value registers of actor entry (0084's MAX_ACTOR_CAPS).

  • commands, an effect for tests. run_command mirrors run; command.natively runs for real and command.scripted answer answers from a function. This is the log package's idiom: code that runs programs is tested without running anything.

  • Raw boundary. One extern, tl_command_run, takes plain values (texts, lists, Bytes, Ints) and answers tuples. std/command builds its own types, so the runtime does not depend on their layout. It is unwinds(), not blocking.

Consequences

  • Linux 5.3 or later (pidfd_open), as the runtime is Linux only (ADR 0011).
  • glibc 2.29 or later for posix_spawn_file_actions_addchdir_np, in programs that use std/command (others drop it at link time).
  • A run holds everything it reads in memory, up to its caps. A program that writes gigabytes writes them to a scratch file, and the caller raises max_file deliberately.
  • Real time. A run takes a reactor token, which switches a native program's clock to real time, as a first socket does (unless LOUISE_VIRTUAL_TIME is set). A program that talks to the outside world cannot be replayed anyway.
  • Concurrency is the caller's. Nothing limits how many programs run at once; a server bounds its tools itself (toki2 with resilience.gate).
  • One test file per backend. tests/run/command.lse runs interpreted and native. crates/louise/tests/command.rs checks what only a real process shows:
    • a killed actor and an exiting program leave no child;
    • a child sees only descriptors 0 to 2;
    • 200 runs leak no descriptor;
    • a subscribed SIGTERM still arrives while children run.

Open questions for the engineering review

  • Capability. Should running programs become a capability once ADR 0084 lands (a command root, or a narrowed os one)? And should remote actors be denied it, as they are files and sockets?
  • PR_SET_PDEATHSIG. Children are killed by the atexit handler, not if the program is SIGKILLed. Parent-death signals need fork (not posix_spawn) and are tied to the spawning thread.
  • closefrom. posix_spawn_file_actions_addclosefrom_np (glibc 2.34) would also close descriptors a C binding opened without O_CLOEXEC. It is left out to keep the glibc floor at 2.29.
  • Streaming. A variant that hands output over as it comes, for programs whose output should not be held in memory.