@parcha/pi-durable-disk 0.0.0-stage → 0.1.0-beta.13

package/dist/cli.d.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { type Parking } from "./park.js";
+import { type RunServer } from "./serve.js";
+import { type DurableRun } from "./run.js";
+/** "30s", "500ms", "2m", "1h", or plain milliseconds. */
+/**
+ * Whether the lease watchdog may kill every other process in the instance's cgroup: only inside its own systemd unit,
+ * whose cgroup holds nothing but the instance and its commands. Elsewhere the cgroup may be shared (a login session, an
+ * agent host's service), so the watchdog kills only the instance's own command groups.
+ *
+ * The holder handle only claims a unit (`mode: "systemd"`, `unit`), and it arrives in an environment variable that any
+ * child inherits, so /proc decides: this process's cgroup v2 path must end in `/<unit>.service`, and its parent's cgroup
+ * must be another (a process that merely inherited the handle shares its parent's cgroup). When the handle claims a
+ * unit that /proc does not confirm, `warning` says why, for one log line.
+ */
+export declare function watchdogOwnsCgroup(holder: Record<string, unknown>, options?: {
+    proc?: string;
+    ppid?: number;
+}): {
+    owns: boolean;
+    warning?: string;
+};
+export declare function parseDuration(text: string): number;
+/** `--run-as NAME|UID[:GID]`: the user the agent's commands run as, with its group and home from /etc/passwd when listed. */
+export declare function runUser(spec: string, passwd?: string): {
+    uid: number;
+    gid: number;
+    home: string;
+    name: string;
+};
+/** What the instance does besides the app between its open and its exit. */
+export interface InstanceLife {
+    /** How long a drain waits for running work before the release; 0 (default) releases at once. */
+    readonly drainMs?: number;
+    /** Park the run when its work allows (`watchParking`); absent, the instance stays up through every wait. */
+    readonly park?: {
+        readonly thresholdMs: number;
+        readonly idleMs?: number;
+    };
+    /** The serve front: its open requests keep the instance up, and a park or a drain stops its submissions. */
+    readonly server?: RunServer;
+    /** The app's wake hook; default run.json `sleeping` with `wakeAt`. */
+    readonly wake?: (run: DurableRun, at: number | null) => Promise<void>;
+    /** Handed the parking watch once it runs. */
+    readonly onParking?: (parking: Parking) => void;
+}
+/**
+ * The instance's life after the run opened: the app's `onOpen` runs; the run parks when `life.park` allows (the wake
+ * written, the run released, exit 0); SIGTERM or SIGINT drains and releases, and the drain's outcome is the exit code.
+ * A drain stops new submissions and waits up to `life.drainMs` for running work; with `resume` it then writes the run
+ * sleeping with its wake (the deadline its work waits for, null when idle and idle parking is on, otherwise now), so
+ * the supervisor starts it again and a deploy never strands it; a wake hook that refuses falls back to a due wake.
+ * `pause` seals it paused. A rejection of `onOpen` is the app failing (exit 1), except once a drain or a park's release
+ * began: closing the Harness under the app makes its work reject ("Session is closed"), and ending the process there
+ * would cut the release before its unmount (a container's FUSE daemon dies with the process, leaving the delegation
+ * orphaned).
+ */
+export declare function serveUntilDone(run: Pick<DurableRun, "setStatus" | "release" | "record">, onOpen: ((run: DurableRun) => void | Promise<void>) | undefined, onSigterm: string | undefined, log: (event: string, extra?: Record<string, unknown>) => void, signals?: Pick<NodeJS.EventEmitter, "once">, life?: InstanceLife): Promise<number>;
+/**
+ * The flags every instance this supervisor starts gets after `run`: `--app MODULE` (made absolute, since the unit's working
+ * directory is not the supervisor's) and any `--run-arg`, in that order.
+ */
+export declare function instanceRunArgs(values: Record<string, unknown>): string[];
+export declare function main(argv: string[]): Promise<number>;