@struktoai/mirage-node 0.0.7 → 0.0.8

package/dist/runtime/sandbox/program.d.ts

@@ -0,0 +1,165 @@
+import { type ChildProcess } from 'node:child_process';
+import type { OutputFn, RunResult, SandboxPipe } from '@struktoai/mirage-core/runtime/types';
+import type { ByteSource } from '@struktoai/mirage-core/io/types';
+import type { ProcessHandle } from '@struktoai/mirage-core/process/handle';
+import type { JsonValue } from '@struktoai/mirage-core/types';
+/**
+ * What a process on this host needs to read the running workspace's system
+ * time (`faketimeEnv`). Empty when the workspace keeps the host's time, and
+ * when this host has no libfaketime, where the process runs on the host's
+ * clock. `env` is the process's environment, whose `LD_PRELOAD` libraries
+ * load after libfaketime. Mirrors Python's `system_time_env`.
+ */
+export declare function systemTimeEnv(env: Record<string, string>): Promise<Record<string, string>>;
+/**
+ * Host folders a kernel mount in this process serves. A child started in
+ * one, or from one, would wait inside its spawn on the loop that answers
+ * for the folder, the very loop spawning it, so it starts outside and
+ * EXEC_PRELUDE takes it in once the spawn has returned. Each name counts the
+ * mounts recording it, so one going down leaves another at its path. Mirrors
+ * Python's `SERVED`.
+ */
+export declare const SERVED: Map<string, number>;
+/**
+ * Record `folder` in `SERVED` under each name a child's path may give it: as
+ * given, made absolute, and with its parent's links resolved. Only the parent
+ * is read, never the mount, so recording it waits on no loop. Returns the
+ * names added, for `unserve` once the mount is gone. Mirrors Python's `serve`.
+ */
+export declare function serve(folder: string): string[];
+/**
+ * Take one mount's names out of `SERVED`; a name another mount still records
+ * stays. Mirrors Python's `unserve`.
+ */
+export declare function unserve(names: string[]): void;
+/**
+ * Where the host's own PATH finds a program, as Python's `shutil.which`
+ * does, as an absolute path: a child's environment may carry no host PATH,
+ * and a relative entry would be read against the child's directory, so the
+ * lookup cannot be left to spawn. Asynchronous, so a PATH entry on a mount
+ * this process serves never blocks the loop that answers it. An empty
+ * entry is the current directory, as for the shell. A name with a slash is
+ * taken as given, and one the PATH lacks too, so spawn reports it missing.
+ * On Windows a name without one of `PATHEXT`'s suffixes is tried with each.
+ */
+export declare function onHostPath(name: string): Promise<string>;
+/**
+ * One process run to its end: its output and its exit status. The child
+ * leads a process group of its own, and an aborted call kills the whole
+ * group and stops reading the pipes: a grandchild left alive, or one that
+ * left the group, holds the output pipes open, so 'close' would wait until
+ * it exited on its own, and the call rejects with an AbortError at once.
+ * When a `kill` stopped the runner with a signal other than KILL, the
+ * group gets that signal first (`endTree`), so the program's handlers get
+ * to run, and a `direct` child that exits on its own then leaves its status
+ * with the runner. A missing executable rejects with `hint` when one is given, else with
+ * spawn's own error. EPIPE means the command exited without draining its
+ * stdin (`head`-like), so it is not an error. An input pull still pending
+ * when the child exits is left to close on its own. One in or from a
+ * `SERVED` folder starts through `EXEC_PRELUDE`. Mirrors Python's
+ * `run_program`.
+ */
+export declare function runProgram(executable: string, hint: string | null, args: string[], stdin: ByteSource | null, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    children?: Set<ChildProcess>;
+    output?: OutputFn;
+    errors?: OutputFn;
+    direct?: boolean;
+}): Promise<RunResult>;
+/**
+ * How another workspace on this host reaches a child `runProgram` started,
+ * which leads its own process group: the host, the PID, and when it
+ * started, so a PID the host reused is never taken for it. `runProgram` adds
+ * `exited_at` once the child exits while what it started may run on. Mirrors
+ * Python's `host_run`.
+ */
+export declare function hostRun(pid: number, argv: readonly string[]): Record<string, JsonValue>;
+/**
+ * Stop a host run a lapsed workspace left: its process group gets `signum`,
+ * then KILL after `STOP_GRACE_SECONDS`. Only a run of this host is reached,
+ * and only while its PID still names a process started when the run did, to
+ * the second `ps` shows, so a PID the host reused is left alone. A PID that
+ * names no process may still name the run's group, whose leader exited
+ * before the programs it started. That group is the run's while one of its
+ * members started by the last time the group was known to be: when the
+ * leader exited (`exited_at`), else when its workspace last vouched for the
+ * run (`seen_at`), with the leader still unreaped. The host gives no new
+ * process the id of a group that has members, and hands a number out again
+ * only after a full round of the others, so a group that took the id later
+ * has only members started since. One none of whose members proves it is not
+ * reached: its members may all have started since, the run's descendants, so
+ * its record stays. A group this workspace may not signal is not reached
+ * while its leader still runs
+ * (macOS answers EPERM for one that only exited unreaped). Answers true once
+ * the run is stopped or gone, false when this workspace cannot reach it.
+ * Mirrors Python's `reap_host_run`.
+ */
+export declare function reapHostRun(run: Readonly<Record<string, JsonValue>>, signum: number): Promise<boolean>;
+/**
+ * The state a sandbox's status command printed as JSON, at `path`: the keys
+ * and indexes down to it. Throws when the command failed or its JSON holds
+ * no state. Mirrors Python's `reported_state`.
+ */
+export declare function reportedState(result: RunResult, command: string, path: readonly (string | number)[]): string;
+/**
+ * A sandbox program's exec arguments, the same for every program that runs a
+ * command in a box: the program's own words (`head`: `exec -i`, smolvm's
+ * `machine exec --name M`), `/` as the working directory and each
+ * variable as `-e`, the target or `--` (`tail`: `--` where the command is
+ * a trailing var arg, so a line starting with a dash is not read as a
+ * flag), then the command.
+ *
+ * A `cwd` runs the command there through the prelude, which exits 126
+ * when the box lacks it, and defers the chdir until the shell starts, so
+ * an agent that blocks on a chdir into a passive sshfs prefix still
+ * serves the mount's pipe. Null runs it from `/` as given, for a helper
+ * pipe. Mirrors Python's `exec_args`.
+ */
+export declare function execArgs(head: readonly string[], tail: readonly string[], env: Record<string, string>, cwd: string | null, argv: readonly string[]): string[];
+/**
+ * Refuse a host program whose working directory this host lacks. The
+ * session cwd is a workspace path; running elsewhere instead would point
+ * a relative path at the wrong files. Mirrors Python's `cwd_refusal`.
+ */
+export declare function cwdRefusal(name: string, cwd: string): Promise<RunResult | null>;
+/**
+ * Signal a child and everything it started: its process group. Windows has
+ * no process group to signal, and no signal but a kill, so only the child
+ * goes there, killed. A group whose members have all exited but are not
+ * yet reaped answers EPERM on macOS where Linux answers ESRCH; either way
+ * nothing in it is left to signal. The group's signal reaches the child
+ * too, so only a KILL also goes through `child.kill`, which marks it
+ * killed: a second gentler signal would reach its handler twice. Mirrors
+ * Python's `kill_tree`.
+ *
+ * @param signum the signal, KILL (9) by default.
+ */
+export declare function killTree(child: ChildProcess, signum?: number): void;
+/**
+ * Signal a child's process group and give the group `STOP_GRACE_SECONDS`
+ * to end. The grace is the group's: a descendant still handling the signal
+ * after the child exited keeps it, unless a KILL reaches the runner first.
+ * What is left after it is the caller's to kill (`stopTree`). Mirrors
+ * Python's `end_tree`.
+ *
+ * @param signum the signal.
+ * @param runner the runner the signal stopped, whose KILL ends the grace.
+ */
+export declare function endTree(child: ChildProcess, signum: number, runner?: ProcessHandle | null): Promise<void>;
+/**
+ * Kill every child still running, so none outlives the workspace, and wait
+ * for each to close. Mirrors Python's `close_children`.
+ */
+export declare function closeChildren(children: Set<ChildProcess>): Promise<void>;
+/**
+ * Hold a byte transport to a sandbox helper until stopped. The tail of what
+ * the helper says on stderr is kept for `diagnostic`, so a mount that fails
+ * can say why. Stopping ends the helper's input; one that has not closed
+ * 100 ms later loses its process group and our ends of its pipes, which
+ * output nobody read would otherwise hold open, exited or not. Mirrors
+ * Python's `open_program_pipe`.
+ */
+export declare function openProgramPipe(executable: string, args: string[]): Promise<SandboxPipe>;
+//# sourceMappingURL=program.d.ts.map

package/dist/runtime/sandbox/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../../src/runtime/sandbox/program.ts"],"names":[],"mappings":"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"}