@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/kernel/process/tree.js

@@ -0,0 +1,301 @@
+import { sleep } from '../time.js';
+import { isAliveIn, listProcesses, signalIfAlive, snapshotProcesses, } from './identity.js';
+import { commandNamesRoot } from './listing.js';
+/** First sampling gap: short commands fork most of their tree right away. */
+const INITIAL_INTERVAL_MS = 100;
+/** Sampling gap after a tick that learned something. */
+const ACTIVE_INTERVAL_MS = 250;
+/** Sampling gap once the tree is quiet. */
+const QUIET_INTERVAL_MS = 2_000;
+/**
+ * How long group authority survives without seeing a member. Far below a pid
+ * wrap and above the quiet interval plus one slow `ps`, so a stalled host
+ * loses authority rather than keeping stale authority.
+ */
+const GROUP_CONTINUITY_MS = 5_000;
+/** Attempts at the snapshot that a teardown decision depends on. */
+const DECISION_ATTEMPTS = 3;
+const DECISION_RETRY_MS = 200;
+/** Poll gap while waiting for signalled processes to exit. */
+const EXIT_POLL_MS = 100;
+/** How long a SIGKILLed process gets to disappear from the snapshot. */
+const KILL_SETTLE_MS = 500;
+/** Follows one leader's tree. Holds live processes only. */
+class TreeSampler {
+    leaderPid;
+    isLeaderRunning;
+    known = new Map();
+    timer;
+    stopped = false;
+    running;
+    intervalMs = INITIAL_INTERVAL_MS;
+    groupSeenAt = Date.now();
+    leaderSeen = false;
+    constructor(leaderPid, isLeaderRunning) {
+        this.leaderPid = leaderPid;
+        this.isLeaderRunning = isLeaderRunning;
+    }
+    /** Takes the first sample and starts ticking. */
+    async start() {
+        await this.sample();
+        this.schedule();
+    }
+    /** Stops ticking. `sample` stays usable for a final decision. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+    }
+    /** Takes one snapshot that started no earlier than this call and absorbs it. Never rejects. */
+    async sample() {
+        while (this.running !== undefined)
+            await this.running;
+        this.running = this.takeSample();
+        try {
+            return await this.running;
+        }
+        finally {
+            this.running = undefined;
+        }
+    }
+    /** {@link sample}, retrying a transient failure, for a decision that signals. */
+    async sampleForDecision() {
+        for (let attempt = 1;; attempt += 1) {
+            const snapshot = await this.sample();
+            if (snapshot !== undefined || attempt >= DECISION_ATTEMPTS)
+                return snapshot;
+            await sleep(DECISION_RETRY_MS);
+        }
+    }
+    /** The processes known alive as of the last sample. */
+    owned() {
+        return [...this.known.values()];
+    }
+    schedule() {
+        if (this.stopped)
+            return;
+        this.timer = setTimeout(() => {
+            void this.sample().then(() => {
+                this.schedule();
+            });
+        }, this.intervalMs);
+        this.timer.unref();
+    }
+    async takeSample() {
+        const startedAt = Date.now();
+        const leaderRunning = this.isLeaderRunning();
+        const snapshot = await snapshotProcesses().catch(() => undefined);
+        if (snapshot === undefined)
+            return undefined;
+        const learned = this.absorb(snapshot, startedAt, leaderRunning);
+        this.intervalMs = learned
+            ? Math.min(this.intervalMs, ACTIVE_INTERVAL_MS)
+            : Math.min(this.intervalMs * 2, QUIET_INTERVAL_MS);
+        return snapshot;
+    }
+    /** @returns Whether the snapshot showed a process this sampler did not know. */
+    absorb(snapshot, startedAt, leaderRunning) {
+        for (const [pid, entry] of this.known) {
+            const row = snapshot.get(pid);
+            if (row?.start === entry.start)
+                this.known.set(pid, row);
+            else
+                this.known.delete(pid);
+        }
+        let learned = false;
+        const adopt = (row) => {
+            if (this.known.has(row.pid) || row.pid === process.pid)
+                return;
+            this.known.set(row.pid, row);
+            learned = true;
+        };
+        if (!this.leaderSeen && leaderRunning) {
+            const leader = snapshot.get(this.leaderPid);
+            if (leader !== undefined) {
+                adopt(leader);
+                this.leaderSeen = true;
+            }
+        }
+        for (const member of this.continuousGroupMembers(snapshot, startedAt, leaderRunning)) {
+            adopt(member);
+        }
+        const children = new Map();
+        for (const row of snapshot.values()) {
+            const siblings = children.get(row.parent);
+            if (siblings)
+                siblings.push(row);
+            else
+                children.set(row.parent, [row]);
+        }
+        const frontier = [...this.known.keys()];
+        for (let pid = frontier.pop(); pid !== undefined; pid = frontier.pop()) {
+            for (const child of children.get(pid) ?? []) {
+                if (this.known.has(child.pid))
+                    continue;
+                adopt(child);
+                frontier.push(child.pid);
+            }
+        }
+        return learned;
+    }
+    continuousGroupMembers(snapshot, startedAt, leaderRunning) {
+        if (this.groupSeenAt === undefined)
+            return [];
+        const members = [...snapshot.values()].filter((entry) => entry.group === this.leaderPid);
+        if (leaderRunning ||
+            (members.length > 0 && startedAt - this.groupSeenAt <= GROUP_CONTINUITY_MS)) {
+            this.groupSeenAt = Date.now();
+            return members;
+        }
+        this.groupSeenAt = undefined;
+        return [];
+    }
+}
+/**
+ * Splits a live tree by signalling authority: group members are owned, and a
+ * process outside the group only when its command line names an owned root.
+ *
+ * @param group - The leader's group id
+ * @param known - The live tree
+ * @param roots - Absolute directories this run owns
+ */
+async function partitionByAuthority(group, known, roots) {
+    const owned = known.filter((entry) => entry.group === group || entry.pid === group);
+    const others = known.filter((entry) => entry.group !== group && entry.pid !== group);
+    if (others.length === 0)
+        return { owned, detached: [] };
+    const rows = await listProcesses(['pid', 'command'], { pids: others.map((entry) => entry.pid) });
+    const commands = new Map(rows.map((row) => [row.pid, row.command]));
+    const detached = [];
+    for (const entry of others) {
+        const command = commands.get(entry.pid);
+        if (command !== undefined && roots.some((root) => commandNamesRoot(command, root))) {
+            owned.push(entry);
+        }
+        else {
+            detached.push({
+                pid: entry.pid,
+                group: entry.group,
+                ...(command === undefined ? {} : { command }),
+            });
+        }
+    }
+    return { owned, detached };
+}
+/** A direct child that can still take a signal. A failed spawn has no pid to signal. */
+export function signalChild(child, signal) {
+    if (child.pid === undefined ||
+        child.pid <= 1 ||
+        child.exitCode !== null ||
+        child.signalCode !== null) {
+        return false;
+    }
+    try {
+        return child.kill(signal);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Starts observing a spawned detached group leader.
+ *
+ * @param child - The spawned leader
+ * @returns The ownership token, or undefined where there is no group or no pid
+ */
+export function ownProcessTree(child) {
+    const pid = child.pid;
+    if (pid === undefined || process.platform === 'win32')
+        return undefined;
+    const isRunning = () => child.exitCode === null && child.signalCode === null;
+    const sampler = new TreeSampler(pid, isRunning);
+    const roots = [];
+    const partition = () => partitionByAuthority(pid, sampler.owned(), roots);
+    const signalOwned = (snapshot, owned, signal, signalled) => {
+        if (snapshot === undefined)
+            return;
+        for (const entry of owned) {
+            if (signalIfAlive(snapshot, entry, signal) && entry.pid !== pid) {
+                signalled?.set(entry.pid, entry);
+            }
+        }
+    };
+    const waitForExit = async (budgetMs) => {
+        const deadline = Date.now() + budgetMs;
+        for (;;) {
+            const { owned } = await partition();
+            const remaining = deadline - Date.now();
+            if (owned.length === 0 || remaining <= 0)
+                return;
+            await sleep(Math.min(EXIT_POLL_MS, remaining));
+            await sampler.sample();
+        }
+    };
+    const teardown = async (graceMs) => {
+        sampler.stop();
+        const signalled = new Map();
+        const first = await sampler.sampleForDecision();
+        if (first !== undefined) {
+            const { owned } = await partition();
+            if (owned.length > 0) {
+                signalOwned(first, owned, 'SIGTERM', signalled);
+                await waitForExit(graceMs);
+                const afterGrace = await sampler.sampleForDecision();
+                const remaining = await partition();
+                signalOwned(afterGrace, remaining.owned, 'SIGKILL', signalled);
+                if (remaining.owned.length > 0)
+                    await waitForExit(KILL_SETTLE_MS);
+            }
+        }
+        const last = first === undefined ? undefined : await sampler.sampleForDecision();
+        const { owned, detached } = await partition();
+        const base = { signalled: [...signalled.values()], detached };
+        if (last === undefined) {
+            return { ...base, stillAlive: [], uncertain: 'the process table could not be read' };
+        }
+        const stranded = [...last.values()].filter((entry) => entry.group === pid && !owned.some((known) => known.pid === entry.pid));
+        return {
+            ...base,
+            stillAlive: owned.filter((entry) => isAliveIn(last, entry)),
+            ...(stranded.length === 0
+                ? {}
+                : {
+                    uncertain: `group ${pid} still has members it can no longer claim: PID ${stranded.map((entry) => entry.pid).join(', ')}`,
+                }),
+        };
+    };
+    let finished;
+    void sampler.start();
+    return {
+        pid,
+        signal(signal) {
+            // An unreaped leader keeps its pid, so a handle that has not seen the
+            // exit proves the group is this one. Afterwards only exact births may
+            // be signalled, which takes a fresh snapshot.
+            if (isRunning()) {
+                try {
+                    process.kill(-pid, signal);
+                    return;
+                }
+                catch {
+                    if (signalChild(child, signal))
+                        return;
+                }
+            }
+            void sampler.sample().then(async (snapshot) => {
+                signalOwned(snapshot, (await partition()).owned, signal);
+            });
+        },
+        anchorTo(extra) {
+            roots.push(...extra);
+        },
+        async owns(candidate) {
+            await sampler.sample();
+            return sampler.owned().some((entry) => entry.pid === candidate);
+        },
+        finish(graceMs) {
+            finished ??= teardown(graceMs);
+            return finished;
+        },
+    };
+}

package/dist/src/kernel/schema.js

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Combinators that validate an untrusted document and give it a TypeScript
+ * type. A schema is the single description of a document: its type is
+ * inferred with {@link Infer}, every refusal names the full key path, and
+ * {@link describeKeys} enumerates the keys with their documentation.
+ *
+ *     const Config = s.object({
+ *       name: s.string({ min: 1 }).describe('Display name'),
+ *       jobs: s.int({ min: 1, max: 64 }).default(4),
+ *       tags: s.array(s.string()).optional(),
+ *     });
+ *     type Config = Infer<typeof Config>;  // { name: string; jobs: number; tags?: string[] }
+ */
+import { FireForgeError } from './errors.js';
+import { nearest } from './text.js';
+const INVALID = Symbol('invalid');
+function show(value) {
+    const text = value === undefined ? 'undefined' : JSON.stringify(value);
+    return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+function refuse(issues, path, message) {
+    issues.push({ path, message });
+    return INVALID;
+}
+function childPath(path, key) {
+    if (typeof key === 'number')
+        return `${path}[${key}]`;
+    const segment = /^[\w$-]+$/.test(key) ? key : `[${JSON.stringify(key)}]`;
+    return path === '' || segment.startsWith('[') ? `${path}${segment}` : `${path}.${segment}`;
+}
+/**
+ * A validator for one value. `Optional` is a type-level marker that makes the
+ * key optional in an enclosing {@link s.object}.
+ */
+export class Schema {
+    type;
+    check;
+    structure;
+    /** Documentation attached with {@link Schema.describe}. */
+    doc;
+    /** Whether an absent key is accepted. */
+    isOptional;
+    /** The value an absent key takes, when one was given with {@link Schema.default}. */
+    fallback;
+    /** @internal Use the combinators in {@link s}. */
+    constructor(
+    /** What the schema accepts, phrased to follow "must be". */
+    type, 
+    /** @internal */
+    check, 
+    /** @internal */
+    structure = {}, extra = {}) {
+        this.type = type;
+        this.check = check;
+        this.structure = structure;
+        this.doc = extra.doc;
+        this.isOptional = (extra.optional ?? false);
+        this.fallback = extra.fallback;
+    }
+    /** Validates without throwing, collecting every issue in the document. */
+    validate(value) {
+        const issues = [];
+        const checked = this.check(value, '', issues);
+        return checked === INVALID || issues.length > 0
+            ? { ok: false, issues }
+            : { ok: true, value: checked };
+    }
+    /** Validates and returns the typed value, or throws one error listing every issue. */
+    parse(value, options = {}) {
+        const result = this.validate(value);
+        if (result.ok)
+            return result.value;
+        const { source, code, ...details } = options;
+        const lines = result.issues.map((issue) => `${issue.path === '' ? 'The document' : `"${issue.path}"`} ${issue.message}`);
+        const prefix = source === undefined ? '' : `${source}: `;
+        const message = lines.length === 1 ? `${prefix}${lines[0]}` : `${prefix}\n  ${lines.join('\n  ')}`;
+        throw new FireForgeError(code ?? 'document-invalid', message, details);
+    }
+    /** The same schema with a documentation string, shown by {@link describeKeys}. */
+    describe(doc) {
+        return new Schema(this.type, this.check, this.structure, { ...this.extra(), doc });
+    }
+    /** Accepts an absent (or `undefined`) value. In an object the key becomes optional. */
+    optional() {
+        const check = (value, path, issues) => value === undefined ? undefined : this.check(value, path, issues);
+        return new Schema(this.type, check, this.structure, { doc: this.doc, optional: true });
+    }
+    /** Fills in `value` when the key is absent. The result is never undefined. */
+    default(value) {
+        const check = (input, path, issues) => input === undefined ? value : this.check(input, path, issues);
+        return new Schema(this.type, check, this.structure, { doc: this.doc, fallback: { value } });
+    }
+    /**
+     * Adds a constraint the combinators cannot express. `test` returns what is
+     * wrong, phrased to follow the key path ("must name an existing lane"), or
+     * undefined when the value is fine.
+     */
+    refine(test) {
+        const check = (value, path, issues) => {
+            const checked = this.check(value, path, issues);
+            if (checked === INVALID || (checked === undefined && this.isOptional))
+                return checked;
+            const problem = test(checked);
+            return problem === undefined ? checked : refuse(issues, path, problem);
+        };
+        return new Schema(this.type, check, this.structure, this.extra());
+    }
+    extra() {
+        return {
+            doc: this.doc,
+            optional: this.isOptional,
+            ...(this.fallback === undefined ? {} : { fallback: this.fallback }),
+        };
+    }
+}
+function primitive(type, accepts) {
+    return new Schema(type, (value, path, issues) => accepts(value) ? value : refuse(issues, path, `must be ${type} (got ${show(value)})`));
+}
+function range(noun, bounds) {
+    const { min, max } = bounds;
+    if (min !== undefined && max !== undefined)
+        return `${noun} between ${min} and ${max}`;
+    if (min !== undefined)
+        return `${noun} of at least ${min}`;
+    return max !== undefined ? `${noun} of at most ${max}` : noun;
+}
+function numeric(noun, bounds, accepts) {
+    return primitive(range(noun, bounds), (value) => typeof value === 'number' &&
+        accepts(value) &&
+        value >= (bounds.min ?? -Infinity) &&
+        value <= (bounds.max ?? Infinity));
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function object(shape, options = {}) {
+    const known = Object.keys(shape);
+    const check = (value, path, issues) => {
+        if (!isPlainObject(value))
+            return refuse(issues, path, `must be an object (got ${show(value)})`);
+        const result = {};
+        let valid = true;
+        for (const key of Object.keys(value)) {
+            if (Object.hasOwn(shape, key))
+                continue;
+            if (options.unknownKeys === 'keep') {
+                result[key] = value[key];
+                continue;
+            }
+            const suggestion = nearest(key, known);
+            const hint = suggestion === undefined ? '' : ` Did you mean "${suggestion}"?`;
+            refuse(issues, childPath(path, key), `is not a known key.${hint}`);
+            valid = false;
+        }
+        for (const [key, schema] of Object.entries(shape)) {
+            const raw = value[key];
+            if (raw === undefined && !schema.isOptional && schema.fallback === undefined) {
+                refuse(issues, childPath(path, key), 'is required');
+                valid = false;
+                continue;
+            }
+            const checked = schema.check(raw, childPath(path, key), issues);
+            if (checked === INVALID)
+                valid = false;
+            else if (checked !== undefined)
+                result[key] = checked;
+        }
+        return valid ? result : INVALID;
+    };
+    return new Schema('an object', check, { shape });
+}
+function array(item, bounds = {}) {
+    const type = `an array of ${item.type}`;
+    const check = (value, path, issues) => {
+        if (!Array.isArray(value))
+            return refuse(issues, path, `must be ${type} (got ${show(value)})`);
+        if (value.length < (bounds.min ?? 0) || value.length > (bounds.max ?? Infinity)) {
+            return refuse(issues, path, `must have ${range('a length', bounds)} (got ${value.length})`);
+        }
+        const checked = value.map((entry, index) => item.check(entry, childPath(path, index), issues));
+        return checked.includes(INVALID) ? INVALID : checked;
+    };
+    return new Schema(type, check, { element: item });
+}
+function record(value, options = {}) {
+    const check = (input, path, issues) => {
+        if (!isPlainObject(input))
+            return refuse(issues, path, `must be an object (got ${show(input)})`);
+        const result = {};
+        let valid = true;
+        for (const [key, raw] of Object.entries(input)) {
+            const at = childPath(path, key);
+            const keyOk = options.key === undefined || options.key.check(key, at, issues) !== INVALID;
+            const checked = value.check(raw, at, issues);
+            if (!keyOk || checked === INVALID)
+                valid = false;
+            else
+                result[key] = checked;
+        }
+        return valid ? result : INVALID;
+    };
+    return new Schema(`an object of ${value.type}`, check, { element: value });
+}
+function union(...members) {
+    const type = members.map((member) => member.type).join(', or ');
+    const check = (value, path, issues) => {
+        const attempts = [];
+        for (const member of members) {
+            const own = [];
+            const checked = member.check(value, path, own);
+            if (checked !== INVALID && own.length === 0)
+                return checked;
+            attempts.push(own);
+        }
+        // A member that accepted the value's outer type and failed inside it is the
+        // one the author meant, so its issues are the useful ones.
+        const inner = attempts.filter((own) => own.every((issue) => issue.path !== path));
+        const [only] = inner;
+        if (inner.length === 1 && only !== undefined) {
+            issues.push(...only);
+            return INVALID;
+        }
+        return refuse(issues, path, `must be ${type} (got ${show(value)})`);
+    };
+    return new Schema(type, check);
+}
+/** The schema combinators. */
+export const s = {
+    /** A string, optionally bounded in length or matching `pattern` (described by `format`). */
+    string(options = {}) {
+        const bounded = options.min !== undefined || options.max !== undefined;
+        const noun = options.format ??
+            (options.pattern !== undefined
+                ? `a string matching ${String(options.pattern)}`
+                : options.min === 1 && options.max === undefined
+                    ? 'a non-empty string'
+                    : range(bounded ? 'a string with a length' : 'a string', options));
+        return primitive(noun, (value) => typeof value === 'string' &&
+            value.length >= (options.min ?? 0) &&
+            value.length <= (options.max ?? Infinity) &&
+            (options.pattern?.test(value) ?? true));
+    },
+    /** A finite number within optional bounds. */
+    number: (bounds = {}) => numeric('a number', bounds, Number.isFinite),
+    /** A safe integer within optional bounds. */
+    int: (bounds = {}) => numeric('an integer', bounds, Number.isSafeInteger),
+    /** `true` or `false`. */
+    boolean: () => primitive('a boolean', (value) => typeof value === 'boolean'),
+    /** Exactly one value. */
+    literal: (expected) => primitive(show(expected), (value) => value === expected),
+    /** One of a fixed set of strings. */
+    enum: (values) => primitive(`one of: ${values.join(', ')}`, (value) => values.some((candidate) => candidate === value)),
+    /** Anything at all. For a subtree a later reader validates. */
+    unknown: () => new Schema('any value', (value) => value),
+    /**
+     * An object with exactly the keys of `shape`. An unknown key is refused,
+     * naming the nearest known one, unless `unknownKeys: 'keep'` passes it through.
+     */
+    object,
+    /** An array of `item`, optionally bounded in length. */
+    array,
+    /** An object used as a dictionary: any keys (optionally validated), values of one schema. */
+    record,
+    /** The first member that accepts the value. */
+    union,
+};
+/**
+ * Lists every key an object schema declares, depth first, including the
+ * containers. Arrays and dictionaries are values: their inside is not listed.
+ *
+ * @param schema - An object schema
+ * @param prefix - Path of `schema` itself within a larger document
+ */
+export function describeKeys(schema, prefix = '') {
+    const keys = [];
+    for (const [name, child] of Object.entries(schema.structure.shape ?? {})) {
+        const path = childPath(prefix, name);
+        keys.push({
+            path,
+            type: child.type,
+            doc: child.doc,
+            required: !child.isOptional && child.fallback === undefined,
+            container: child.structure.shape !== undefined,
+            schema: child,
+        });
+        keys.push(...describeKeys(child, path));
+    }
+    return keys;
+}
+/**
+ * The schema of the value at a dotted key path, following object keys,
+ * dictionary keys and array indices, or undefined when the path names nothing.
+ *
+ * @param schema - The document's schema
+ * @param path - Dotted path such as `build.targets.0.name`
+ */
+export function schemaAt(schema, path) {
+    let current = schema;
+    for (const segment of path.split('.').filter((part) => part.length > 0)) {
+        if (current === undefined)
+            return undefined;
+        const { shape, element } = current.structure;
+        current =
+            shape === undefined ? element : Object.hasOwn(shape, segment) ? shape[segment] : undefined;
+    }
+    return current;
+}