Document (kaappi process): guide, procedure reference, cookbook recipe - #41
Merged
Conversation
The subprocess library shipped in four phases on core main (KEP-0022) and had no end-user page at all -- Phase 4 (kaappi/kaappi#2417) is what makes it a complete API worth documenting, so this covers the whole surface at once. Three new pages, in the order a reader meets the subject: - guide/subprocesses.md -- why the command is a list and not a command line, what a non-zero exit means versus a failure to start, and the deadlock that makes `run-process` worth having: feed a child's stdin and then read its stdout by hand and you wedge the moment either pipe fills. Other languages answer that with a thread per stream; Kaappi answers it with fibers inside the call. - procedures/processes.md -- the reference for all fourteen procedures, including the `process-timeout` condition and its two accessors, which are the only route to what a killed child managed to produce. - cookbook/external-programs.md -- a worked recipe, ending on the injection contrast pair that is the whole reason the argv list exists. Cross-cutting edits: the conformance table gains a KEP-0022 row, and the sandbox table in guide/security.md gains the row that says a sandboxed script cannot escape by starting a program. The sample sweep gets a `HAVE_PROCESS` probe alongside the existing `HAVE_FFI` one. Released binaries through v0.25.0 have no `(kaappi process)` at all, so without it the weekly sweep would fail every claim on these pages until the next release rather than skipping them -- the same shape, and the same reason, as the FFI probe. Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
conformance.md's extensions table gained a KEP-0006 row on main while this branch added the KEP-0022 one; both rows and both prose cross-references survive. The guide page count in CLAUDE.md was stale before either change (19 for 21 pages) and is corrected to match the tree. Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
POSIX leaves it unspecified whether a failed PATH search fails at posix_spawnp or lets the child exec fail and exit 127; OpenBSD takes the second option, so the guide's blanket 'raises a file error' was not true everywhere. The sample also uses a path now, which is the form that behaves the same on every platform. Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
Two things the core PR settled after these pages were written: `timeout:` now refuses an explicit `new-group: #f` rather than accepting a call it cannot bound, and an `input:` past the 4096-byte pipe buffer hangs on Windows (kaappi/kaappi#2459) until pipe writes move to overlapped handles. Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The end-user half of kaappi/kaappi#2417 (KEP-0022 Phase 4). The core PR is kaappi/kaappi#2455.
The subprocess library shipped in four phases on core
mainand had no end-user page at all. Phase 4 is what makes it a complete API —run-processplus theprocess-timeoutcondition — so this documents the whole surface at once rather than backfilling three pages.Three new pages
guide/subprocesses.md— why the command is a list and not a command line, what a non-zero exit means versus a failure to start, and the deadlock that makesrun-processworth having at all: feed a child's stdin and then read its stdout by hand and you wedge the moment either pipe fills. Other languages answer that with a thread per stream; Kaappi answers it with fibers inside the call.procedures/processes.md— the reference for all fourteen procedures, including theprocess-timeoutcondition and its two accessors (the only route to what a killed child managed to produce), the redirection-spec table, and the Windows signal-folding note.cookbook/external-programs.md— a worked recipe, ending on the injection contrast pair that is the whole reason the argv list exists.Cross-cutting
conformance.mdgains a KEP-0022 row in the extensions table, spelling out that there is deliberately nokaappi-processfeature identifier and that the library is absent on wasm32-wasi and under--sandbox.guide/security.md's sandbox table gains the row that says a sandboxed script cannot escape by starting a program.procedures/index.md(the generated table),cookbook/index.md,guide/index.md, and the page counts inCLAUDE.md.Sample sweep
The sweep gets a
HAVE_PROCESSprobe alongside the existingHAVE_FFIone. Released binaries through v0.25.0 have no(kaappi process), so without it the weekly sweep would fail every claim on these pages until the next release rather than skipping them — same shape and same reason as the FFI probe.sweep_procs.pyskipsprocesses.mdandsweep_cookbook.pyskips the new recipe when the probe is false.Verified against a build of core
main+ kaappi/kaappi#2455:mkdocs build --strict— clean.sweep_procs.py docs/procedures processes— 19 checks, all pass.sweep_cookbook.py—subprocess-runpasses (the six failures in that run are the pre-existing ecosystem-library sections that need libraries not installed on this machine).Both new pages carry an "Availability" note saying the library arrived after v0.25.0, since the site deploys ahead of the release that ships it.
🤖 Generated with Claude Code