adispatchd 0.0.0-stage → 0.1.0

package/dist/executors/process-identity.js

@@ -0,0 +1,283 @@
+/**
+ * Process start identity (Spec §13): PID alone is not enough, PID reuse must
+ * never lead to signalling a foreign process.
+ *
+ * Platform-specific parts are encapsulated in {@link ProcessInspector}:
+ * - Linux: `/proc/<pid>/stat` field 22 (`starttime`, clock ticks since boot)
+ *   plus the boot ID (`/proc/sys/kernel/random/boot_id`); token
+ *   `linux:<boot-id>:<starttime>`.
+ * - macOS: `ps -o pgid=,lstart= -p <pid>` with `LC_ALL=C` and `TZ=UTC` for a
+ *   stable format; token `darwin:<lstart>` (second resolution).
+ *
+ * Rule: whenever the identity cannot be verified, nothing is signalled.
+ */
+import { execFile } from 'node:child_process';
+import { readdir, readFile } from 'node:fs/promises';
+import { systemTimers } from '../core/index.js';
+/**
+ * Parse the content of `/proc/<pid>/stat`. The command name (field 2) may
+ * contain spaces and parentheses, so fields are counted after the last `)`.
+ * Returns process group (field 5) and start time (field 22).
+ */
+export function parseProcStat(content) {
+    const close = content.lastIndexOf(')');
+    if (close === -1)
+        throw new Error('malformed /proc stat: missing ")"');
+    // Fields after comm start with field 3 (state).
+    const fields = content.slice(close + 1).trim().split(/\s+/);
+    const state = fields[0];
+    const pgrp = Number(fields[2]); // field 5
+    const starttime = fields[19]; // field 22
+    if (!state || !Number.isInteger(pgrp) || !starttime || !/^\d+$/.test(starttime)) {
+        throw new Error('malformed /proc stat: unexpected field layout');
+    }
+    return { state, pgrp, starttime };
+}
+/** Linux implementation based on procfs. */
+export function createLinuxInspector(read = (p) => readFile(p, 'utf8'), list = (p) => readdir(p)) {
+    let bootId;
+    return {
+        platform: 'linux',
+        // Zombies (e.g. orphans while PID 1 in a container does not reap) do not count.
+        async groupHasLiveMembers(pgid) {
+            for (const entry of await list('/proc')) {
+                if (!/^\d+$/.test(entry))
+                    continue;
+                try {
+                    const { state, pgrp } = parseProcStat(await read(`/proc/${entry}/stat`));
+                    if (pgrp === pgid && state !== 'Z' && state !== 'X')
+                        return true;
+                }
+                catch {
+                    // Process vanished between listing and reading.
+                }
+            }
+            return false;
+        },
+        async probe(pid) {
+            let stat;
+            try {
+                stat = await read(`/proc/${pid}/stat`);
+            }
+            catch (err) {
+                if (err.code === 'ENOENT' || err.code === 'ESRCH')
+                    return null;
+                throw err;
+            }
+            const { pgrp, starttime } = parseProcStat(stat);
+            bootId ??= (await read('/proc/sys/kernel/random/boot_id')).trim();
+            if (!bootId)
+                throw new Error('empty boot id');
+            return { pgid: pgrp, token: `linux:${bootId}:${starttime}` };
+        },
+    };
+}
+/** Parse the output of `ps -o pgid=,lstart= -p <pid>`. */
+export function parsePsOutput(output) {
+    const line = output.split('\n').find((l) => l.trim() !== '');
+    if (!line)
+        return null;
+    const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (!m?.[1] || !m[2])
+        throw new Error(`unexpected ps output: ${line}`);
+    return { pgid: Number(m[1]), token: `darwin:${m[2].replace(/\s+/g, ' ')}` };
+}
+const defaultRunner = (file, args) => new Promise((resolve, reject) => {
+    execFile(file, args, { env: { PATH: '/bin:/usr/bin', LC_ALL: 'C', TZ: 'UTC' }, timeout: 5000 }, (err, stdout) => {
+        if (err && typeof err.code !== 'number') {
+            reject(err);
+            return;
+        }
+        resolve({ code: err ? Number(err.code) : 0, stdout: String(stdout) });
+    });
+});
+/** macOS implementation based on `ps` (lstart = process start time). */
+export function createDarwinInspector(run = defaultRunner) {
+    return {
+        platform: 'darwin',
+        async probe(pid) {
+            const { code, stdout } = await run('/bin/ps', ['-o', 'pgid=,lstart=', '-p', String(pid)]);
+            const probe = parsePsOutput(stdout);
+            if (code !== 0 || probe === null) {
+                // ps exits 1 with empty output when the PID does not exist.
+                if (stdout.trim() === '')
+                    return null;
+                throw new Error(`ps exited with code ${code}`);
+            }
+            return probe;
+        },
+    };
+}
+/** Inspector for the current platform; probing fails on unsupported platforms. */
+export function defaultProcessInspector(platform = process.platform) {
+    if (platform === 'linux')
+        return createLinuxInspector();
+    if (platform === 'darwin')
+        return createDarwinInspector();
+    return {
+        platform,
+        probe: () => Promise.reject(new Error(`process identity not supported on ${platform}`)),
+    };
+}
+/**
+ * Capture the start identity of `pid`. Returns `undefined` if the process
+ * does not exist (anymore) or the identity cannot be determined.
+ */
+export async function getStartIdentity(pid, inspector = defaultProcessInspector()) {
+    if (!isValidPid(pid))
+        return undefined;
+    try {
+        const probe = await inspector.probe(pid);
+        return probe ? { pid, pgid: probe.pgid, token: probe.token } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Compare the live process `identity.pid` with the persisted identity. */
+export async function checkProcessIdentity(identity, inspector = defaultProcessInspector()) {
+    if (!isValidPid(identity.pid) || !isValidPid(identity.pgid) || !identity.token)
+        return 'unknown';
+    let probe;
+    try {
+        probe = await inspector.probe(identity.pid);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (probe === null)
+        return 'gone';
+    if (probe.token !== identity.token)
+        return 'different';
+    // Same process but it moved to another group: group target is uncertain.
+    if (probe.pgid !== identity.pgid)
+        return 'unknown';
+    return 'same';
+}
+/** True only if `pid` is verifiably the process described by `identity`. */
+export async function isSameProcess(pid, identity, inspector = defaultProcessInspector()) {
+    if (pid !== identity.pid)
+        return false;
+    return (await checkProcessIdentity(identity, inspector)) === 'same';
+}
+const defaultKill = (pid, signal) => {
+    process.kill(pid, signal);
+};
+/**
+ * Send `signal` to process group `pgid`, but only if its leader
+ * (`identity.pid`) is verifiably the same process as recorded in `identity`
+ * (Spec §13). Never signals on doubt.
+ *
+ * Note: if the leader is gone while other group members still run, the group
+ * cannot be verified and is not signalled (reason `gone`); use
+ * {@link processGroupExists} to detect that case and report it.
+ */
+export async function killProcessGroupIfSame(pgid, identity, signal, deps = {}) {
+    if (!isValidPid(pgid) || pgid !== identity.pgid)
+        return { signalled: false, reason: 'pgid_mismatch' };
+    const check = await checkProcessIdentity(identity, deps.inspector ?? defaultProcessInspector());
+    if (check !== 'same')
+        return { signalled: false, reason: check };
+    try {
+        (deps.kill ?? defaultKill)(-pgid, signal);
+        return { signalled: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ESRCH')
+            return { signalled: false, reason: 'gone' };
+        return { signalled: false, reason: 'signal_failed', error: err.message };
+    }
+}
+/** True if at least one process is in group `pgid` (signal 0 probe; EPERM counts as existing). */
+export function processGroupExists(pgid) {
+    if (!isValidPid(pgid))
+        return false;
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * True if group `pgid` still has live (non-zombie) members. Falls back to the
+ * signal-0 probe if the platform has no precise check or it fails.
+ */
+export async function processGroupAlive(pgid, inspector = defaultProcessInspector()) {
+    if (!processGroupExists(pgid))
+        return false;
+    if (!inspector.groupHasLiveMembers)
+        return true;
+    try {
+        return await inspector.groupHasLiveMembers(pgid);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Recovery helper (Spec §13, §14 variant A): verify the start identity of the
+ * group leader, then SIGTERM the group, SIGKILL after `graceMs` and confirm
+ * that no live member remains. Never signals on doubt.
+ */
+export async function terminateProcessGroupIfSame(identity, graceMs, options = {}) {
+    const inspector = options.inspector ?? defaultProcessInspector();
+    const kill = options.kill ?? defaultKill;
+    const timers = options.timers ?? systemTimers;
+    const pgid = identity.pgid;
+    if (!isValidPid(pgid) || !isValidPid(identity.pid))
+        return 'unknown';
+    const check = await checkProcessIdentity(identity, inspector);
+    switch (check) {
+        case 'different':
+            return 'not_same';
+        case 'unknown':
+            return 'unknown';
+        case 'gone':
+            return (await processGroupAlive(pgid, inspector)) ? 'group_alive_unverifiable' : 'gone';
+        case 'same':
+            break;
+    }
+    const send = (signal) => {
+        try {
+            kill(-pgid, signal);
+        }
+        catch (err) {
+            if (err.code !== 'ESRCH')
+                throw err;
+        }
+    };
+    const waitGone = async (ms) => {
+        const step = Math.max(1, options.pollIntervalMs ?? 25);
+        for (let waited = 0;; waited += step) {
+            if (!(await processGroupAlive(pgid, inspector)))
+                return true;
+            if (waited >= ms)
+                return false;
+            await new Promise((resolve) => timers.setTimeout(resolve, Math.min(step, ms - waited)));
+        }
+    };
+    try {
+        send('SIGTERM');
+    }
+    catch {
+        return 'kill_failed';
+    }
+    if (await waitGone(graceMs))
+        return 'terminated';
+    // The group existed continuously since verification, so its PGID cannot have been reused.
+    try {
+        send('SIGKILL');
+    }
+    catch {
+        return 'kill_failed';
+    }
+    return (await waitGone(options.killConfirmMs ?? 5000)) ? 'terminated' : 'kill_failed';
+}
+function isValidPid(pid) {
+    // pid 0/1 and negative values would address the own group, init or all processes.
+    return Number.isInteger(pid) && pid > 1;
+}
+//# sourceMappingURL=process-identity.js.map

package/dist/executors/process-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-identity.js","sourceRoot":"","sources":["../../src/executors/process-identity.ts"],"names":[],"mappings":"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"}

package/dist/executors/shell-executor.d.ts

@@ -0,0 +1,35 @@
+import { type Clock, type ExecutionSpec, type Executor, type Logger, type RunningProcess, type Timers } from '../core/index.js';
+import { type KillFn, type ProcessInspector } from './process-identity.js';
+/** Dependencies and tuning of the {@link ShellExecutor}. */
+export interface ShellExecutorOptions {
+    clock?: Clock;
+    /** Timers for timeouts and polling (default: real timers). */
+    timers?: Timers;
+    logger?: Logger;
+    /** Environment the minimal worker env is picked from (default `process.env`). */
+    baseEnv?: NodeJS.ProcessEnv;
+    /** Platform adapter for start identities (default: current platform). */
+    inspector?: ProcessInspector;
+    /** Signal sender for process groups (default `process.kill`; injectable for tests). */
+    kill?: KillFn;
+    /** How long to wait for the group to vanish after SIGKILL before reporting `kill_failed`. Default 5 s. */
+    killConfirmMs?: number;
+    /** After the leader exited: max wait for stdout/stderr to close before they are destroyed. Default 2 s. */
+    stdioDrainMs?: number;
+    /** Poll interval while waiting for a process group to vanish. Default 25 ms. */
+    pollIntervalMs?: number;
+    /**
+     * `workspace.base_dir`: if set, the working directory must lie strictly
+     * below it (never the base itself); it is created segment by segment with a
+     * real-path check per segment (see `ensureWorkspaceWithin`), so symlinks
+     * cannot redirect creation outside. Violations end the run with `start_error`.
+     */
+    workspaceBaseDir?: string;
+}
+/** Executor for local shell workers (V1). */
+export declare class ShellExecutor implements Executor {
+    readonly type = "shell";
+    private readonly deps;
+    constructor(options?: ShellExecutorOptions);
+    start(spec: ExecutionSpec): Promise<RunningProcess>;
+}