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

package/dist/lease.d.ts

@@ -1,7 +1,10 @@
 export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
-export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunErrorCode, RunLease, StoreHeadSource } from "./run.js";
+export type { LeaseOptions, OpenRunLeaseOptions, OpenStep, ReleaseStep, RunClaim, RunErrorCode, RunLease, RunSeed, RunSeedDir, StoreHeadSource } from "./run.js";
 export * from "./errors.js";
 export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
 export type { ArchilStore, OpenOptions, PragmaMismatch, Profile } from "./store.js";
 export type { AcquireOptions, ArchilHost, Claim, RunRef, Unmounted } from "./claim.js";
 export type { ClaimDir, PersistRecord, RunHolder, RunRecord, RunStatus } from "./status.js";
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";
+export type { BusyState, DrainOptions, Parking, ParkOptions, ParkResult, ParkTarget } from "./park.js";
+export type { DurableRun, RunEnv } from "./run.js";

package/dist/lease.js

@@ -4,3 +4,5 @@
 export { EXIT_DATAERR, EXIT_SOFTWARE, LeaseLapsedError, openRunLease, OWNER_LOCK, RunError, StoreBehindSealError, storeHead, STORE_FILE } from "./run.js";
 export * from "./errors.js";
 export { assertPragmas, Fence, FencedDatabase, openArchilStore, PROFILE_PRAGMAS, StoreBusyError, StoreFencedError, StorePragmaError } from "./store.js";
+// Parking, for a Harness the host opened over `openRunLease` (`leaseParkTarget`).
+export { busyState, drain, leaseParkTarget, watchParking } from "./park.js";

package/dist/local-run.js

@@ -8,8 +8,9 @@
 // store's own commits are made durable by SQLite, and work/ is the operating system's to flush; a power loss can lose what
 // it had not written yet. It refuses once the claim is fenced, as a mount's does.
 //
-// Linux only, for now: the run's root is held open through /proc/self/fd (openClaimDir), and the default environment
-// (`archilEnv`) confines commands with `setpriv` (util-linux) and the file tools through /proc/self/fd. macOS has neither.
+// On macOS, for development: it has no /proc/self/fd and no setpriv, so there the run's root is addressed by its path
+// (openClaimDir's `byPath`), commands keep the user's rights, the file tools are confined by path (confine.ts), and the
+// commands are recorded from ps (process-table.ts). The README's "On macOS" says what that costs.
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { FencedError } from "./errors.js";

package/dist/place.d.ts

@@ -0,0 +1,190 @@
+import type { Delegation } from "disk";
+import { PdaError } from "./errors.js";
+import { type RunRecord } from "./status.js";
+import { type EnsureOptions, type HostDriver, type SupervisorControl } from "./supervise.js";
+export type PlaceKill = "process" | "box";
+/** The run's paths in the place: its id, its directory, and the `work` and `store` under it. */
+export type PlacePaths = {
+    id: string;
+    root: string;
+    work: string;
+    store: string;
+};
+/**
+ * How the run stood when a runner ended: the instance's own report, or `run.json` as it left it. `status` is the run's
+ * word: `complete` when it delivered, else `failed`.
+ */
+export type PlaceOutcome = {
+    status: string;
+    generation: number | null;
+    code?: string | null;
+    message?: string;
+    record?: unknown;
+    storeSha256?: string;
+};
+/** How a runner ended. `exit`: the exit code or signal (local), or the host's status (`stopped`, `failed`, `gone`) or `SIGKILL` when the place killed it (archil). */
+export type PlaceExit = {
+    exit: number | string | null;
+    signal: string | null;
+    outcome?: PlaceOutcome;
+    stderr: string;
+};
+/** One instance of the run in a place. `epoch`: 1 on a plain directory; on a disk, the generation the instance opens. */
+export type PlaceRunner = {
+    epoch: number;
+    pid?: number;
+    exited: Promise<PlaceExit>;
+};
+/** What a runner is handed: its number in the run, its environment, and for a place with a token, the attempt's mount token. */
+export type RunnerOrder = {
+    gen: number;
+    env: Record<string, string>;
+    stdin?: string;
+};
+/** What the place reads of the run, the way it reads it: `run.json`, and on a disk the run's delegations. */
+export type PlaceStatus = {
+    record: RunRecord | null;
+    delegations?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned" | "isPending">[];
+};
+/** What a recovery did. A takeover on a disk lists what it revoked, and `ms` is the whole of it (revoke and start). */
+export type PlaceRecovery = {
+    runner: PlaceRunner;
+    restored?: {
+        checkpoint: string;
+        head: number;
+    };
+    replayed?: {
+        from: number;
+        to: number;
+    };
+    revoked?: Pick<Delegation, "clientId" | "inodeId" | "path" | "isOrphaned">[];
+    ms?: number;
+};
+/**
+ * What a runner announces to its supervisor: a crossing it took, or a request to be killed at one (it parks there until
+ * the kill). `signals-failed` is the place's own last word when it could not read the requests: it ends the iterator,
+ * which never rejects. `code` is the failing read's error code when it has one (CONTROL_API_FAILED for a read that timed
+ * out), else SIGNALS_FAILED.
+ */
+export type PlaceSignal = {
+    kind: "crossing" | "kill-request";
+    crossing: {
+        point: string;
+        n: number;
+        pid?: number;
+        info?: Record<string, unknown>;
+    };
+    /** The attempt's nonce the runner wrote into its request, lifted out of `crossing`: the supervisor honors a kill request only with the nonce it minted for that attempt. */
+    nonce?: string;
+} | {
+    kind: "signals-failed";
+    code: string;
+    message: string;
+};
+/**
+ * What the supervisor hands a place factory: the run's paths as it computed them, how to take the boxes the run made,
+ * and where attempt n's runner writes its kill request (a file of the supervisor's machine).
+ */
+export type PlaceContext = {
+    paths: PlacePaths;
+    self?: string;
+    destroyBoxes?: () => void | Promise<void>;
+    requestFile?: (attempt: number) => string;
+};
+export interface Place {
+    /** `local` or `archil`, for the recording's lines. */
+    readonly name: string;
+    readonly paths: PlacePaths;
+    /** A place whose instance opens a claim mints each attempt's mount token: the supervisor passes it as the runner's stdin, never in argv or env. */
+    token?(attempt: number): string | undefined | Promise<string | undefined>;
+    /** What this place can lose. */
+    readonly kills: ReadonlyArray<PlaceKill>;
+    start(order: RunnerOrder): Promise<PlaceRunner>;
+    /**
+     * Where attempt `attempt`'s runner writes its kill request, as a path in the place (the supervisor puts it in the
+     * runner's order). A place with `signals` has it, and `signals(attempt)` reads what is written there.
+     */
+    requestFile?(attempt: number): string;
+    /**
+     * The kill requests (and crossings) attempt `attempt`'s runner announces. The supervisor stops reading with `return()`
+     * once the runner has exited, and `return()` ends a pending `next()`.
+     */
+    signals?(attempt: number): AsyncIterable<PlaceSignal>;
+    /** Takes the runner away abruptly, as a crash would. Safe on a runner that is already gone. */
+    kill(runner: PlaceRunner, kind: PlaceKill): Promise<void>;
+    status?(): Promise<PlaceStatus>;
+    /** Kills `last` if it still runs, then starts the next runner. */
+    recover(last: PlaceRunner, kind: PlaceKill, order: RunnerOrder): Promise<PlaceRecovery>;
+    checkpoint?(): Promise<{
+        taken: boolean;
+        heldBy?: string;
+    }>;
+    move?(to: Place): Promise<Record<string, unknown>>;
+    /** Lets the run go: stops what still runs (its commands too) and removes what the place made for it (tokens), never the run's directory. */
+    release(): Promise<void>;
+}
+export type PlaceErrorCode = "INVALID_ARGUMENT" | "HELD" | "START_TIMED_OUT" | "STATUS_FAILED" | "KILL_UNSUPPORTED" | "RELEASE_FAILED";
+export declare class PlaceError extends PdaError {
+    constructor(code: PlaceErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface LocalPlaceOptions {
+    /** The app module `run --app` loads. */
+    app: string;
+    /** The run's directory. Default: the context's `paths.root`. */
+    root?: string;
+    /** The instance program; `run` and its flags are appended. Default: this Node and the package's CLI. */
+    command?: string[];
+    /** Extra flags for `run` (heartbeat periods, a park threshold). */
+    runArgs?: string[];
+}
+/**
+ * The run on a directory of this machine: each runner is `pi-durable-disk run --dir <root> --id <id> --app <app>`, a
+ * child in its own process group, with `{ PATH, ...order.env }` and nothing else of this process's environment. No disk,
+ * no key and no token. A process kill is SIGKILL to the group, and the next runner resumes the run from the directory; a
+ * box kill also takes the boxes the run made (`destroyBoxes`), so `kills` has `box` only when the context gives that.
+ * A runner's outcome is the instance's `{"outcome":...}` line on stdout, or, without one, `run.json` as it left it.
+ */
+export declare function localPlace(options: LocalPlaceOptions): (ctx: PlaceContext) => Place;
+export interface ArchilPlaceOptions {
+    disk: string;
+    region: string;
+    /** The disk's control API (`archilControl`). The place holds it; no instance ever does. */
+    control: SupervisorControl;
+    /**
+     * The driver that runs the instance (`localHost`, `dockerHost`, `daytonaHost`), set up with the app the instance runs.
+     * Its `kill` and `kills` are the place's.
+     */
+    host: HostDriver;
+    /** The run's id on the disk. Default: the context's `paths.id`. */
+    id?: string;
+    /** Where the driver mounts runs, for `paths`. Default: the driver's `mountRoot`, else /mnt/archil. */
+    mountRoot?: string;
+    /** More for each start's `ensureRunning`: the run directory's owner (`create`), token prefix and TTL, timeouts. */
+    ensure?: Omit<EnsureOptions, "control" | "demand" | "mountToken">;
+    /** How often a runner's host status is read. Default 1 s. */
+    pollMs?: number;
+    /** How long a start waits on a mount another start has in flight. Default 60 s. */
+    startTimeoutMs?: number;
+    /** How often `signals` reads the attempt's kill request over S3. Default 500 ms (the runner waits at its crossing). */
+    signalPollMs?: number;
+    /**
+     * How long those reads may fail (anything but a missing object) without a break before the iterator yields one
+     * `signals-failed` and ends. Default 60 s.
+     */
+    signalFailMs?: number;
+}
+/**
+ * The run on an Archil disk, its instance run by a host driver. `token(attempt)` mints the attempt's mount token through
+ * the place's control, and the runner it is handed to mounts with it. A start is `ensureRunning` (it creates the run's
+ * directory with `ensure.create` and writes the start mark) with that token and the order's environment. A kill is the
+ * driver's `kill`: `process` or `box`, whichever the driver takes. A recovery is the takeover: the dead holder's
+ * delegations revoked (its lease counts as expired, since the place killed it) and the next instance started, which
+ * `revoked` and `ms` report. A runner writes its kill request in the run's directory (`requestFile`), and `signals` reads
+ * it over S3. A runner ends when the driver no longer reports it running, or when the place killed it; its
+ * outcome is `run.json` read over S3, with `code`, `message`, `record` and `storeSha256` from the detail of the last
+ * status the app set. `release` stops every instance it started and removes every token it minted; the run's directory
+ * stays (`deleteRunTree`).
+ */
+export declare function archilPlace(options: ArchilPlaceOptions): (ctx: PlaceContext) => Place;