@niwa-labs/proc 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts ADDED
@@ -0,0 +1,316 @@
1
+ /**
2
+ * The proc module: run a command.
3
+ *
4
+ * - **proc.run** runs a command in a box from `@niwa-labs/sandbox`: it writes its working directory,
5
+ * a temp directory inside it and the places of the profiles it takes, it has no network, and the
6
+ * places of every profile it did not take (a harness's sign-in among them), the user's keys and
7
+ * niwa's own secrets are closed to it. Its environment is `PATH`, the real `HOME`, `TMPDIR` and what
8
+ * the call lists. The box is the host's default (`toolchains`), what the call asks for besides or
9
+ * instead, and nothing a grant does not cover. Because the box holds this, the class of the action
10
+ * is honest for any command: a write in the local world. It never runs without a box: a box that
11
+ * cannot run here, or cannot be held as it was asked, stops the call before a process exists. The
12
+ * result and the record carry the box's manifest: the request, the paths and where each came
13
+ * from, the rules taken and the policy the sandbox reports it applies.
14
+ *
15
+ * - **proc.exec** runs a command with no box. Nothing limits what it writes or reaches, so it is an
16
+ * irreversible action in the external world, and a grant has to name it. It gets `PATH`, `HOME`,
17
+ * what the call lists, and the secrets the call names. A secret is a reference, `secret("name")`; its value
18
+ * is resolved by the host's secret store, handed to the process, and removed from the output before
19
+ * the artifact or the tail is made. Nothing the host holds goes into the environment of the command
20
+ * unless the call lists it.
21
+ *
22
+ * A command ends like this: the output is stored as an artifact of the host before anything points at it, the
23
+ * result has the exit code and a bounded tail, and a `proc.finished` record says how the command
24
+ * ended. A non-zero exit is a result: the caller reads it.
25
+ *
26
+ * A command that was cut off may have done any part of its work, so the recovery contract is
27
+ * `do-not-repeat`.
28
+ *
29
+ * Stopping a command (its time is up, or its call is cancelled) signals the process group it
30
+ * leads. A process that left that group is not reached, and a command still running when the host
31
+ * itself dies is not stopped by it.
32
+ */
33
+
34
+ import type { PluginApi } from "@niwa-labs/plugin";
35
+ import type { PlanInput } from "@niwa-labs/sandbox";
36
+ import { randomUUID } from "node:crypto";
37
+ import { mkdirSync, realpathSync, rmSync, statSync } from "node:fs";
38
+ import { homedir } from "node:os";
39
+ import { isAbsolute, join, resolve } from "node:path";
40
+
41
+ import { RECORD_DATA_LIMIT, action, closedPlacesOf, coveringRule } from "@niwa-labs/core";
42
+ import type { ActionContext } from "@niwa-labs/core";
43
+ import { plugin } from "@niwa-labs/plugin";
44
+ import type { Plugin } from "@niwa-labs/plugin";
45
+ import { BoxRefused, SandboxUnavailable, admit, boxManifest, nono, realPlace, requireSandbox, sandbox as sandboxHost, sandboxOf } from "@niwa-labs/sandbox";
46
+ import type { BoxAccess, BoxSpec, Sandbox, SandboxHost, SandboxManifest } from "@niwa-labs/sandbox";
47
+
48
+ import { OutputCapture } from "./artifact.ts";
49
+ import { ProcRefusal } from "./refusal.ts";
50
+ import { MAX_TAIL_BYTES, ProcFinished, fileTarget, procExec, procRun } from "./records.ts";
51
+ import type { ProcFinishedData, ProcResult } from "./records.ts";
52
+ import { launchPlain, supervise } from "./supervise.ts";
53
+
54
+ export * from "./records.ts";
55
+ export { boxRules } from "./box-rules.ts";
56
+ export { ProcRefusal } from "./refusal.ts";
57
+ export type { ProcRefusalCode } from "./refusal.ts";
58
+
59
+ /** What the module is given. Every field has a default. */
60
+ export interface ProcOptions {
61
+ /**
62
+ * The host's sandbox (`sandbox({ adapter, profiles })` of `@niwa-labs/sandbox`): the adapter of
63
+ * `proc.run` (default nono) and the profiles a run may take, with the installations whose places it
64
+ * keeps closed. Default: the catalog alone.
65
+ */
66
+ readonly sandbox?: SandboxHost;
67
+ /** Trusted host lookup for Git metadata required by a managed checkout. */
68
+ readonly worktreeFor?: (api: Pick<PluginApi, "home" | "journal">, cwd: string) => PlanInput["worktree"];
69
+ /** What a run's box has when the call asks for nothing. Default `{ allow: ["toolchains"] }`. */
70
+ readonly box?: BoxAccess;
71
+ /** The most bytes of output kept in an artifact. Default: 16 MiB. */
72
+ readonly outputLimit?: number;
73
+ /**
74
+ * The bytes of the end of the output a result carries, 0 to 64 KiB. Default: 4 KiB. A tail that
75
+ * would not fit the record of the command, once escaped, is cut to fit.
76
+ */
77
+ readonly tailBytes?: number;
78
+ /** How long a stopped command has to end before it is killed, in milliseconds. Default: 2000. */
79
+ readonly killGraceMs?: number;
80
+ }
81
+
82
+ const DEFAULT_OUTPUT_LIMIT = 16 * 1024 * 1024;
83
+ const DEFAULT_TAIL_BYTES = 4096;
84
+ const DEFAULT_KILL_GRACE_MS = 2000;
85
+ const DRAIN_MS = 1000;
86
+
87
+ /**
88
+ * The directory a call is about, as a grant names it: the real path, so a link cannot name a place
89
+ * the grant does not cover.
90
+ */
91
+ function cwdTarget(cwd: string): string {
92
+ try {
93
+ return realpathSync(cwd);
94
+ } catch {
95
+ return resolve(cwd);
96
+ }
97
+ }
98
+
99
+ /**
100
+ * The directory a command runs in: the real path of an existing directory, and the one the grant
101
+ * was checked against. `authorized` is the real path the call was matched at: if the path now leads
102
+ * somewhere else (a link was moved after the check), the command does not start.
103
+ */
104
+ function directoryOf(cwd: string, authorized: string | undefined): string {
105
+ let real: string;
106
+ try {
107
+ real = realpathSync(cwd);
108
+ } catch {
109
+ throw new ProcRefusal("bad-cwd", `${cwd} does not exist`);
110
+ }
111
+ if (authorized !== undefined && real !== authorized) {
112
+ throw new ProcRefusal("bad-cwd", `${cwd} changed after the call was checked: it was ${authorized}, it is ${real}`);
113
+ }
114
+ if (!statSync(real).isDirectory()) throw new ProcRefusal("bad-cwd", `${cwd} is not a directory`);
115
+ return real;
116
+ }
117
+
118
+ /**
119
+ * The policy a sandbox reports for a run's box, when it keeps the admitted write boundary and reaches no network.
120
+ * A sandbox that does not say what it applies is taken not to keep it.
121
+ */
122
+ function heldPolicy(sandbox: Sandbox, manifest: SandboxManifest, spec: BoxSpec): void {
123
+ const refuse = (why: string): never => {
124
+ throw new BoxRefused([{ code: "adapter", message: why }], sandbox.name);
125
+ };
126
+ if (manifest.policy === undefined) return refuse("it does not say what a box lets a process reach");
127
+ const host = manifest.policy.net[0];
128
+ if (host !== undefined) refuse(`it lets a process reach ${host}, and a run reaches no network`);
129
+ const roots = spec.write.map((path) => realPlace(path));
130
+ for (const path of manifest.policy.write) {
131
+ const place = realPlace(path);
132
+ if (!isAbsolute(path) || !roots.some((root) => root === place || place.startsWith(root.endsWith("/") ? root : root + "/"))) {
133
+ refuse(`it lets a process write ${path} outside the admitted paths`);
134
+ }
135
+ }
136
+ }
137
+
138
+ /**
139
+ * A run's temp directory, inside its cwd, the one place besides the cwd itself its box always lets
140
+ * it write; removed after the run. A cwd it cannot be made in refuses the run.
141
+ */
142
+ function makeTemp(cwd: string, temp: string): void {
143
+ try {
144
+ mkdirSync(temp, { mode: 0o700 });
145
+ } catch (error) {
146
+ throw new ProcRefusal("bad-cwd", `${cwd} cannot be written: a run keeps its temp files there (${(error as Error).message})`);
147
+ }
148
+ }
149
+
150
+ /** The environment every command has before the call adds to it. */
151
+ function baseEnv(): Record<string, string> {
152
+ return { PATH: process.env["PATH"] ?? "/usr/bin:/bin", HOME: homedir() };
153
+ }
154
+
155
+ /**
156
+ * What a sandbox says before any process exists, as the refusal of the call: the command never
157
+ * started, so the caller is told so, and it is not a failure that may have had an effect.
158
+ */
159
+ async function beforeStart<T>(start: () => Promise<T>): Promise<T> {
160
+ try {
161
+ return await start();
162
+ } catch (error) {
163
+ if (error instanceof SandboxUnavailable) throw new ProcRefusal("no-sandbox", error.message);
164
+ if (error instanceof BoxRefused) throw new ProcRefusal("box-refused", error.message);
165
+ throw error;
166
+ }
167
+ }
168
+
169
+ /** An option that is a whole number in a range, or the error that says which one is not. */
170
+ function wholeNumber(name: string, value: number | undefined, fallback: number, least: number, most: number): number {
171
+ const chosen = value ?? fallback;
172
+ if (!Number.isSafeInteger(chosen) || chosen < least || chosen > most) {
173
+ throw new TypeError(`proc option ${name} must be a whole number from ${String(least)} to ${String(most)}, got ${String(chosen)}`);
174
+ }
175
+ return chosen;
176
+ }
177
+
178
+ /** Room left in a record for what is not the tail: names the record's own fields and the escaping of the paths. */
179
+ const RECORD_SLACK = 8 * 1024;
180
+
181
+ /** The result with its tail cut from the front, for as long as the record that carries it would be more than a record holds. */
182
+ function fitted(data: Omit<ProcFinishedData, keyof ProcResult>, result: ProcResult): ProcResult {
183
+ let tail = result.tail;
184
+ while (tail.length > 0 && Buffer.byteLength(JSON.stringify({ ...data, ...result, tail })) > RECORD_DATA_LIMIT - RECORD_SLACK) {
185
+ tail = tail.slice(Math.ceil(tail.length / 2));
186
+ // A cut in the middle of a character leaves half of it.
187
+ if (/^[\uDC00-\uDFFF]/.test(tail)) tail = tail.slice(1);
188
+ }
189
+ return { ...result, tail };
190
+ }
191
+
192
+ /** The proc module. */
193
+ export function proc(options: ProcOptions = {}): Plugin {
194
+ const limit = wholeNumber("outputLimit", options.outputLimit, DEFAULT_OUTPUT_LIMIT, 1, Number.MAX_SAFE_INTEGER);
195
+ const tailBytes = wholeNumber("tailBytes", options.tailBytes, DEFAULT_TAIL_BYTES, 0, MAX_TAIL_BYTES);
196
+ const killGraceMs = wholeNumber("killGraceMs", options.killGraceMs, DEFAULT_KILL_GRACE_MS, 0, Number.MAX_SAFE_INTEGER);
197
+ const boxes = options.sandbox ?? sandboxHost();
198
+ const boxDefault: BoxAccess = options.box ?? { allow: ["toolchains"] };
199
+ // The host reads the target of a call to match its grant, then runs the action with the same
200
+ // input object. The real path the target named is kept here, keyed by that object, so the
201
+ // action starts the command in the directory the grant covered and in no other.
202
+ const authorized = new WeakMap<object, string>();
203
+ const targetOf = (input: { readonly cwd: string }): string => {
204
+ const real = cwdTarget(input.cwd);
205
+ authorized.set(input, real);
206
+ return fileTarget(real);
207
+ };
208
+
209
+ /** The sandbox of a run: the host's, or nono. */
210
+ const runSandbox = async (): Promise<Sandbox> => await requireSandbox(boxes.adapter === undefined ? nono() : sandboxOf(boxes.adapter));
211
+
212
+ return plugin("proc", (api) => {
213
+ api.declare(ProcFinished);
214
+ const home = () => api.home();
215
+
216
+ const finish = async (
217
+ ctx: ActionContext,
218
+ data: Omit<ProcFinishedData, keyof ProcResult>,
219
+ result: ProcResult,
220
+ ): Promise<ProcResult> => {
221
+ const kept = fitted(data, result);
222
+ await ctx.emit(ProcFinished, { ...data, ...kept });
223
+ return kept;
224
+ };
225
+
226
+ api.action(
227
+ action(procRun, {
228
+ recovery: "do-not-repeat",
229
+ // Held in a box that writes only its directory, with no network and no credentials.
230
+ effect: "write",
231
+ world: "local",
232
+ target: (input) => targetOf(input),
233
+ async run(input, ctx) {
234
+ const cwd = directoryOf(input.cwd, authorized.get(input));
235
+ const sandbox = await beforeStart(runSandbox);
236
+ // Cancelled while the sandbox was being found: nothing was started, and nothing will be.
237
+ ctx.signal?.throwIfAborted();
238
+ // The temp files go inside the directory, where the box lets the command write.
239
+ const temp = join(cwd, `.niwa-tmp-${randomUUID()}`);
240
+ const plan = await beforeStart(async () => boxes.plan({
241
+ cwd,
242
+ worktree: options.worktreeFor?.(api, cwd),
243
+ defaults: boxDefault,
244
+ request: input.box,
245
+ writes: [
246
+ { path: cwd, from: "cwd" },
247
+ { path: temp, from: "temp" },
248
+ ],
249
+ closed: [...closedPlacesOf(home()), api.secrets.dir].map((path) => ({ path, from: "niwa" })),
250
+ network: false,
251
+ }));
252
+ const rights = api.rights(ctx.caller);
253
+ const env = { ...baseEnv(), TMPDIR: temp, TMP: temp, TEMP: temp, ...input.env };
254
+ const admitted = await beforeStart(async () =>
255
+ admit(plan, sandbox, (needed) => (rights === "unlimited" ? needed : coveringRule(rights, needed)), { env }),
256
+ );
257
+ await beforeStart(async () => heldPolicy(sandbox, admitted.manifest, admitted.spec));
258
+ const box = boxManifest(plan, admitted.rules, admitted.manifest);
259
+ const data = { action: "proc.run" as const, cwd, program: input.cmd[0] as string, box };
260
+ if (Buffer.byteLength(JSON.stringify(data)) > RECORD_DATA_LIMIT - RECORD_SLACK) {
261
+ throw new ProcRefusal("box-refused", "the box manifest exceeds the space available in the completion record");
262
+ }
263
+ makeTemp(cwd, temp);
264
+ let capture: OutputCapture | undefined;
265
+ try {
266
+ capture = new OutputCapture({ artifacts: api.artifacts, secrets: [], limit, tailBytes });
267
+ const child = await beforeStart(() => sandbox.launch(admitted.spec, input.cmd, { detached: true }));
268
+ const ended = await supervise(child, capture, { timeout: input.timeout, killGraceMs, drainMs: DRAIN_MS, signal: ctx.signal });
269
+ const result = await finish(ctx, data, { ...ended, ...capture.finish() });
270
+ return { ...result, box };
271
+ } catch (error) {
272
+ capture?.discard();
273
+ throw error;
274
+ } finally {
275
+ rmSync(temp, { recursive: true, force: true });
276
+ }
277
+ },
278
+ }),
279
+ );
280
+
281
+ api.action(
282
+ action(procExec, {
283
+ recovery: "do-not-repeat",
284
+ // No box, a network and secrets: nothing says what the command reaches.
285
+ effect: "irreversible",
286
+ world: "external",
287
+ target: (input) => targetOf(input),
288
+ async run(input, ctx) {
289
+ const cwd = directoryOf(input.cwd, authorized.get(input));
290
+ // Every secret is resolved before anything starts: one that cannot be given stops the call.
291
+ const values: string[] = [];
292
+ const env: Record<string, string> = { ...baseEnv() };
293
+ const given = (name: string): string => {
294
+ const value = api.secrets.resolve(name);
295
+ values.push(value);
296
+ return value;
297
+ };
298
+ for (const [name, value] of Object.entries(input.env ?? {})) {
299
+ env[name] = typeof value === "string" ? value : given(value.secret);
300
+ }
301
+ for (const name of input.secrets ?? []) env[name] = given(name);
302
+ const capture = new OutputCapture({ artifacts: api.artifacts, secrets: values, limit, tailBytes });
303
+ try {
304
+ ctx.signal?.throwIfAborted();
305
+ const child = launchPlain(input.cmd, cwd, env);
306
+ const ended = await supervise(child, capture, { timeout: input.timeout, killGraceMs, drainMs: DRAIN_MS, signal: ctx.signal });
307
+ return await finish(ctx, { action: "proc.exec", cwd, program: input.cmd[0] as string }, { ...ended, ...capture.finish() });
308
+ } catch (error) {
309
+ capture.discard();
310
+ throw error;
311
+ }
312
+ },
313
+ }),
314
+ );
315
+ });
316
+ }
package/src/records.ts ADDED
@@ -0,0 +1,184 @@
1
+ /**
2
+ * The records entry of the proc module: the two actions that run a command, the record that says
3
+ * how a command ended, and the schemas they share. It needs the contracts of core, the box schemas
4
+ * of the sandbox and zod, so a script or another plugin can name the actions.
5
+ *
6
+ * - `proc.run` always runs in a box: it writes its working directory and what its box takes, it
7
+ * has no network and no credentials. The box is what makes its class honest, so the class is
8
+ * `write` in `local`.
9
+ * - `proc.exec` runs without a box, so nothing limits what it reaches. It is `irreversible` in
10
+ * `external`, and a grant has to name it.
11
+ *
12
+ * Output is never a field of a record beyond a bounded tail: the whole output is an artifact of the
13
+ * host the record points at. A secret an environment variable takes is a reference, `secret("name")`
14
+ * from core; the host resolves the value where the command starts, and it is never written down.
15
+ */
16
+
17
+ import { ArtifactRefSchema, SecretName, SecretRef, actionRef, record } from "@niwa-labs/core";
18
+ import { BoxAccessSchema, BoxManifestSchema } from "@niwa-labs/sandbox";
19
+ import { z } from "zod";
20
+
21
+ /**
22
+ * An absolute path as the target of a call, the form a rule names: a segment of a target holds no
23
+ * whitespace, `*`, `@`, `:` or brace, so each such character, and `%`, is written as `%` and its
24
+ * hex code (the bytes of its UTF-8, for one that has more than one). A path of plain segments is
25
+ * its own target, so a rule written for it stays valid; one with a space is named as
26
+ * `/work/My%20Project`. `%` is encoded too, so two paths never share a target.
27
+ */
28
+ export function fileTarget(path: string): string {
29
+ const escaped = (char: string): string =>
30
+ [...new TextEncoder().encode(char)].map((byte) => `%${byte.toString(16).toUpperCase().padStart(2, "0")}`).join("");
31
+ return path.replace(/[\s*@:{}%]/g, escaped);
32
+ }
33
+
34
+ /** The most a command may be given to finish, in milliseconds: an hour. */
35
+ export const MAX_TIMEOUT_MS = 3_600_000;
36
+
37
+ /** The most bytes of output a result may carry as its tail. */
38
+ export const MAX_TAIL_BYTES = 64 * 1024;
39
+
40
+ /** The longest working directory or program a call may name: what a path may be, so the record that names them stays small. */
41
+ const MAX_NAMED = 4096;
42
+
43
+ /** The name of an environment variable (the sandbox has its own, for its spec). */
44
+ const EnvName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "not a valid environment variable name");
45
+
46
+ /** The program and its arguments, as they are run. Nothing interprets them: a shell is `["sh", "-c", "…"]`. */
47
+ const Cmd = z
48
+ .array(z.string())
49
+ .min(1)
50
+ .refine((argv) => argv[0] !== undefined && argv[0].length > 0, "the program must not be empty")
51
+ .refine((argv) => argv[0] === undefined || argv[0].length <= MAX_NAMED, `the program must not be longer than ${String(MAX_NAMED)} characters`);
52
+
53
+ const Cwd = z
54
+ .string()
55
+ .max(MAX_NAMED, `the working directory must not be longer than ${String(MAX_NAMED)} characters`)
56
+ .regex(/^\//, "the working directory must be an absolute path");
57
+
58
+ const Timeout = z.number().int().min(1).max(MAX_TIMEOUT_MS);
59
+
60
+ /**
61
+ * How a command ended: it exited on its own, it was stopped for running out of time, or it was
62
+ * stopped because the call was cancelled.
63
+ */
64
+ export const ProcOutcome = z.enum(["exited", "timed-out", "cancelled"]);
65
+ export type ProcOutcome = z.infer<typeof ProcOutcome>;
66
+
67
+ /**
68
+ * What a command did. A command that exits with a failure is a result, not a failed action: the
69
+ * caller reads `exit`.
70
+ */
71
+ export const ProcResult = z.strictObject({
72
+ outcome: ProcOutcome,
73
+ /** The exit code; 128 and more is a signal. Null when the command was stopped, for its time or by a cancel. */
74
+ exit: z.number().int().nullable(),
75
+ durationMs: z.number().int().nonnegative(),
76
+ /** The end of the output, bounded. The rest is in `output`. */
77
+ tail: z.string(),
78
+ /** The output was longer than what is kept: the artifact holds its start and `tail` its end. */
79
+ truncated: z.boolean(),
80
+ /**
81
+ * Reading the output was given up while something the command started, outside its process group,
82
+ * still held the pipes open: what it wrote after that is in neither `output` nor `tail`.
83
+ */
84
+ outputCut: z.boolean(),
85
+ /** The output, stdout and stderr in the order they came, as an artifact of the host. */
86
+ output: ArtifactRefSchema,
87
+ });
88
+ export type ProcResult = z.infer<typeof ProcResult>;
89
+
90
+ export const procRun = actionRef("proc.run", {
91
+ description:
92
+ "Run a command in a box: it writes `cwd` and a temp directory inside it, it has no network and no credentials. " +
93
+ "`cmd` is the program and its arguments, run as they are (a shell is [\"sh\", \"-c\", \"…\"]). " +
94
+ "`timeout` is in milliseconds; a command that runs longer is stopped, with everything it started, as is one whose call is cancelled. " +
95
+ "`env` is the whole environment besides PATH, HOME (the user's own) and a TMPDIR (also TMP and TEMP) inside `cwd` that exists for the run and is removed after it. " +
96
+ "`box` adds to the host's default (`allow`, by default the toolchains: the PATH, Homebrew and the catalog's programs, readable) or replaces it (`only`): a profile by its name (`bun`, `git`, `npm`, `node`, `cargo`, `uv` and the host's), `\"toolchains\"`, or a path (`{ read }`, `{ write }`). " +
97
+ "The places of every profile the run does not take, the user's keys and niwa's own secrets are closed to it. Going beyond the default needs the caller's `box.use@<profile>`, `box.read@<path>` or `box.write@<path>` rule. " +
98
+ "A command that needs credentials or the network is for proc.exec. " +
99
+ "The result has the exit code, the end of the output (`tail`) and the output as an artifact, which keeps its first 16 MiB: with `truncated` the artifact holds the start and `tail` the end. " +
100
+ "A non-zero exit is a result, not an error. A command is stopped with its process group: one that left the group is not reached. " +
101
+ "A grant names the real path of `cwd` (`proc.run@/work/repo`); a space or another character a rule cannot hold is written as % and its hex code (`My%20Project`). " +
102
+ "Class: write, local.",
103
+ input: z.strictObject({
104
+ cmd: Cmd,
105
+ cwd: Cwd,
106
+ timeout: Timeout,
107
+ env: z.record(EnvName, z.string()).optional(),
108
+ box: BoxAccessSchema.optional(),
109
+ }),
110
+ output: ProcResult.extend({ box: BoxManifestSchema }),
111
+ });
112
+
113
+ export const procExec = actionRef("proc.exec", {
114
+ description:
115
+ "Run a command with no box: nothing limits what it writes or reaches. Irreversible and external, so a grant names it. " +
116
+ "`cmd` is the program and its arguments, run as they are; put no secret in it. " +
117
+ "`timeout` is in milliseconds; a command that runs longer is stopped, with everything it started. " +
118
+ "`env` values are text or a secret reference, `secret(\"name\")`; `secrets` lists secrets given to the command as variables of their own names. " +
119
+ "The values are resolved where the command starts and are never written down; known secret values are removed from the output. " +
120
+ "`net` says the command is meant to reach the network: it is for the owner who is asked, nothing enforces it. " +
121
+ "The result has the exit code, the end of the output (`tail`) and the output as an artifact, which keeps its first 16 MiB: with `truncated` the artifact holds the start and `tail` the end. " +
122
+ "A grant names the real path of `cwd` as `proc.exec@/work/repo`, with a space or another character a rule cannot hold written as % and its hex code. Class: irreversible, external.",
123
+ input: z.strictObject({
124
+ cmd: Cmd,
125
+ cwd: Cwd,
126
+ timeout: Timeout,
127
+ env: z.record(EnvName, z.union([z.string(), SecretRef])).optional(),
128
+ net: z.boolean().optional(),
129
+ secrets: z.array(SecretName).optional(),
130
+ }),
131
+ output: ProcResult,
132
+ });
133
+
134
+ /** What a rule of the box answers when it is called: the caller holds it. */
135
+ const Held = z.strictObject({ held: z.literal(true) });
136
+
137
+ export const boxUse = actionRef("box.use", {
138
+ description:
139
+ "A rule, not a tool: `box.use@<profile>` in a grant lets a box take that profile beyond the host's default (`proc.run`, `session.start`). " +
140
+ "Calling it answers that the caller holds the rule for `profile`; a call the grant does not cover is refused. Class: read, local.",
141
+ input: z.strictObject({ profile: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/, "a profile name") }),
142
+ output: Held,
143
+ });
144
+
145
+ export const boxRead = actionRef("box.read", {
146
+ description:
147
+ "A rule, not a tool: `box.read@<path>` in a grant lets a box read that place beyond the host's default; a path a rule cannot hold is written with % and its hex code. " +
148
+ "Calling it answers that the caller holds the rule for `path` (absolute, its real path is taken); a call the grant does not cover is refused. Class: read, local.",
149
+ input: z.strictObject({ path: Cwd }),
150
+ output: Held,
151
+ });
152
+
153
+ export const boxWrite = actionRef("box.write", {
154
+ description:
155
+ "A rule, not a tool: `box.write@<path>` in a grant lets a box write (and read) that place beyond the host's default. " +
156
+ "Calling it answers that the caller holds the rule for `path` (absolute, its real path is taken); a call the grant does not cover is refused. Class: read, local.",
157
+ input: z.strictObject({ path: Cwd }),
158
+ output: Held,
159
+ });
160
+
161
+ export const boxNet = actionRef("box.net", {
162
+ description:
163
+ "A rule, not a tool: `box.net@<host>` in a grant lets a session's box reach that host beyond what its installation and the host's default give (a `proc.run` reaches none). " +
164
+ "Calling it answers that the caller holds the rule for `host`; a call the grant does not cover is refused. Class: read, local.",
165
+ input: z.strictObject({ host: z.string().regex(/^[^\s*@:{}/%]+$/, "a host") }),
166
+ output: Held,
167
+ });
168
+
169
+ /** A command ended. Written by both actions, once the output is stored. */
170
+ export const ProcFinished = record(
171
+ "proc.finished",
172
+ ProcResult.extend({
173
+ action: z.enum(["proc.run", "proc.exec"]),
174
+ cwd: z.string(),
175
+ /** The program, without its arguments: they may say more than a journal should keep. */
176
+ program: z.string(),
177
+ /** The manifest of the box of a `proc.run`; absent for `proc.exec`. */
178
+ box: BoxManifestSchema.optional(),
179
+ }),
180
+ );
181
+ export type ProcFinishedData = z.infer<typeof ProcFinished.schema>;
182
+
183
+ /** Every record type of the proc module. */
184
+ export const PROC_TYPES = [ProcFinished] as const;
package/src/refusal.ts ADDED
@@ -0,0 +1,17 @@
1
+ /** The refusals of the proc module: a call that could not start a command. */
2
+
3
+ import { CatchableError } from "@niwa-labs/core";
4
+
5
+ /** Why a call was refused before a command started. */
6
+ export type ProcRefusalCode = "bad-cwd" | "no-sandbox" | "box-refused" | "not-started";
7
+
8
+ /** A refusal of the module: the caller's to catch, since nothing ran. */
9
+ export class ProcRefusal extends CatchableError {
10
+ override name = "ProcRefusal";
11
+ override readonly code: ProcRefusalCode;
12
+
13
+ constructor(code: ProcRefusalCode, message: string) {
14
+ super(message);
15
+ this.code = code;
16
+ }
17
+ }
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Watching one started command: its output into a capture, its time, and its end.
3
+ *
4
+ * The command leads its own process group, so what it started goes with it. The group is stopped
5
+ * when the time is up, and again when the command itself is over: a background child that
6
+ * outlives its parent holds the output pipes open, and a run waiting for them would never end.
7
+ */
8
+
9
+ import type { LaunchedBox } from "@niwa-labs/sandbox";
10
+
11
+ import type { OutputCapture } from "./artifact.ts";
12
+ import { ProcRefusal } from "./refusal.ts";
13
+ import type { ProcOutcome } from "./records.ts";
14
+
15
+ export interface SuperviseOptions {
16
+ /** How long the command may run, in milliseconds. */
17
+ readonly timeout: number;
18
+ /** How long a stopped group has to end before it is killed, in milliseconds. */
19
+ readonly killGraceMs: number;
20
+ /** How long to wait for the output to be read once the command is over, in milliseconds. */
21
+ readonly drainMs: number;
22
+ /** Aborted when the call is cancelled: the command is stopped like one that ran out of time. */
23
+ readonly signal?: AbortSignal | undefined;
24
+ }
25
+
26
+ /** How the command ended. */
27
+ export interface Ended {
28
+ readonly outcome: ProcOutcome;
29
+ /** The exit code; null when the command was stopped for its time or because the call was cancelled. */
30
+ readonly exit: number | null;
31
+ readonly durationMs: number;
32
+ /**
33
+ * Reading the output was given up while something the command started still held its pipes open
34
+ * (it had left the command's process group), or a pipe failed: what it wrote after that is not in
35
+ * the output.
36
+ */
37
+ readonly outputCut: boolean;
38
+ }
39
+
40
+ /** Signals the group a command leads; a group that is gone is not an error. */
41
+ function signalGroup(pid: number, signal: NodeJS.Signals): void {
42
+ try {
43
+ process.kill(-pid, signal);
44
+ } catch {
45
+ // Nothing is left in the group.
46
+ }
47
+ }
48
+
49
+ /** What the supervisor needs of a stream's reader. */
50
+ interface Reader {
51
+ read(): Promise<{ done: boolean; value?: Uint8Array | undefined }>;
52
+ cancel(): Promise<unknown>;
53
+ }
54
+
55
+ /** What went wrong while the output was read. */
56
+ interface ReadState {
57
+ /** The capture could not keep what it was given: the error is the call's. */
58
+ failure?: { readonly error: unknown };
59
+ /** A pipe failed before it ended. */
60
+ broken: boolean;
61
+ }
62
+
63
+ /** Reads a stream into the capture until it ends, fails or is cancelled. */
64
+ async function pump(reader: Reader, feed: (chunk: Uint8Array) => void, state: ReadState, stop: () => void): Promise<void> {
65
+ try {
66
+ for (;;) {
67
+ const { done, value } = await reader.read();
68
+ if (done) return;
69
+ if (value === undefined || state.failure !== undefined) continue;
70
+ try {
71
+ feed(value);
72
+ } catch (error) {
73
+ // The output cannot be kept: the command is stopped, and the call fails with this.
74
+ state.failure = { error };
75
+ stop();
76
+ }
77
+ }
78
+ } catch {
79
+ state.broken = true;
80
+ }
81
+ }
82
+
83
+ /** Runs a started command to its end, with its output going to the capture. */
84
+ export async function supervise(child: LaunchedBox, capture: OutputCapture, options: SuperviseOptions): Promise<Ended> {
85
+ const started = Date.now();
86
+ child.stdin.end();
87
+ const readers: readonly [Reader, Reader] = [child.stdout.getReader(), child.stderr.getReader()];
88
+ const state: ReadState = { broken: false };
89
+ const stop = () => signalGroup(child.pid, "SIGKILL");
90
+ const reading = Promise.all([
91
+ pump(readers[0], (chunk) => capture.feed("out", chunk), state, stop),
92
+ pump(readers[1], (chunk) => capture.feed("err", chunk), state, stop),
93
+ ]);
94
+
95
+ // The first reason the command is stopped for is the one it ended with.
96
+ let stopped: "timed-out" | "cancelled" | undefined;
97
+ let killer: ReturnType<typeof setTimeout> | undefined;
98
+ const stopFor = (reason: "timed-out" | "cancelled") => {
99
+ if (stopped !== undefined) return;
100
+ stopped = reason;
101
+ signalGroup(child.pid, "SIGTERM");
102
+ killer = setTimeout(() => signalGroup(child.pid, "SIGKILL"), options.killGraceMs);
103
+ };
104
+ const timer = setTimeout(() => stopFor("timed-out"), options.timeout);
105
+ const cancel = () => stopFor("cancelled");
106
+ if (options.signal?.aborted === true) cancel();
107
+ else options.signal?.addEventListener("abort", cancel, { once: true });
108
+
109
+ // The command ends with its process. A box that is slow to clean up, or fails to, after the
110
+ // process is gone has not changed how the command ended: the clean-up is waited for apart.
111
+ const code = await (child.ended ?? child.exited).then(
112
+ (value) => value,
113
+ () => null,
114
+ );
115
+ clearTimeout(timer);
116
+ clearTimeout(killer);
117
+ options.signal?.removeEventListener("abort", cancel);
118
+ signalGroup(child.pid, "SIGKILL");
119
+ let drain: ReturnType<typeof setTimeout> | undefined;
120
+ const drained = await Promise.race([
121
+ reading.then(() => true),
122
+ new Promise<boolean>((resolve) => {
123
+ drain = setTimeout(() => resolve(false), options.drainMs);
124
+ }),
125
+ ]);
126
+ clearTimeout(drain);
127
+ for (const reader of readers) void reader.cancel().catch(() => {});
128
+ await child.exited.catch(() => undefined);
129
+ if (state.failure !== undefined) throw state.failure.error;
130
+
131
+ return { outcome: stopped ?? "exited", exit: stopped === undefined ? code : null, durationMs: Date.now() - started, outputCut: !drained || state.broken };
132
+ }
133
+
134
+ /**
135
+ * Starts a command with no box, leading its own process group, with exactly the environment given.
136
+ * A program that cannot be started is a refusal: nothing ran.
137
+ */
138
+ export function launchPlain(cmd: readonly string[], cwd: string, env: Readonly<Record<string, string>>): LaunchedBox {
139
+ try {
140
+ const child = Bun.spawn([...cmd], { cwd, env: { ...env }, stdin: "pipe", stdout: "pipe", stderr: "pipe", detached: true });
141
+ return {
142
+ pid: child.pid,
143
+ stdin: child.stdin,
144
+ stdout: child.stdout,
145
+ stderr: child.stderr,
146
+ exited: child.exited,
147
+ kill: (signal) => child.kill(signal),
148
+ };
149
+ } catch (error) {
150
+ throw new ProcRefusal("not-started", `cannot start ${cmd[0] ?? "the command"}: ${(error as Error).message}`);
151
+ }
152
+ }