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

package/dist/claim.d.ts

@@ -55,7 +55,7 @@ export interface ArchilHost {
         cli?: number;
         staleGrace?: number;
     };
-    /** File access on the mount; replaceable so tests can inject a dead mount (ENOTCONN) or a fence (EIO). */
+    /** File access on the mount; replaceable so tests can inject a dead mount (ENOTCONN, ECONNABORTED) or a fence (EIO). */
     fs?: {
         stat?(path: string): Promise<unknown>;
         persist?(path: string, data: string): Promise<void>;
@@ -143,7 +143,7 @@ export declare function parseTokenNickname(nickname: string, prefix?: string): {
  * whose TTL passes fences its mount the same way at the next refresh, so an instance never outlives its token by more
  * than one refresh. The nickname is given, or built from `run` so the user can be traced back to its run.
  */
-export declare function mintMountToken(control: ControlApi, opts: {
+export declare function mintMountToken(control: Pick<ControlApi, "addUser">, opts: {
     nickname?: string;
     run?: {
         id: string;
@@ -158,7 +158,7 @@ export declare function mintMountToken(control: ControlApi, opts: {
     identifier: string;
     nickname: string;
 }>;
-export declare function removeMountToken(control: ControlApi, identifier: string): Promise<void>;
+export declare function removeMountToken(control: Pick<ControlApi, "removeUser">, identifier: string): Promise<void>;
 /**
  * Delegations on `runs/<id>` and anything under it; never a sibling or a parent. The control API resolves a delegation's
  * path best-effort: it can list one with no path, live or orphaned, on a never-reused run. So when nothing matches by
@@ -205,12 +205,35 @@ export declare function revoke(control: ControlApi, id: string): Promise<Delegat
 export declare function revokeBestEffort(control: Pick<ControlApi, "listDelegations" | "revokeDelegation" | "exec">, id: string): Promise<Delegation[]>;
 /** Revoke through the control API, then mount plainly; if the API path fails, mount with `--force`. */
 export declare function takeOver(control: ControlApi, opts: AcquireOptions): Promise<Claim>;
+/** A path of a disk, as one exclusive mount names it: `runs/<id>` for a run, any safe path for `withClaim`. */
+export type MountTarget = {
+    readonly disk: string;
+    readonly region: string;
+    readonly path: string;
+};
+/**
+ * The errno codes of a stat on a FUSE mount whose daemon is gone: ENOTCONN once its connection is torn down, ECONNABORTED
+ * for a stat already in flight while it is torn down. Codes, never messages: a message is translated by the locale.
+ */
+export declare const DEAD_CONNECTION: ReadonlySet<string>;
 /**
  * Unmount whatever the run has at `mountpoint`: `archil unmount` flushes and checks the delegation in; a dead mount
  * (which `archil unmount` refuses) is cleaned with `fusermount -u`; a live mount refused with ENOENT (Sysbox) is checked
  * in and moved aside. Any other live mount that refuses is never forced.
  */
 export declare function unmountClaim(mountpoint: string, host?: ArchilHost): Promise<Unmounted>;
+/** The most entries of a bare mountpoint the stray check looks at; past it, nothing is moved aside. */
+export declare const STRAY_CHECK_LIMIT = 100000;
+/**
+ * The entries under `dir` written since `since` (ms since the epoch), as paths relative to it, walked without following
+ * links. `unchecked` says why the walk could not look at every entry: more than `limit` of them, or one it could not
+ * read (an entry gone meanwhile is not one). A directory keeps its time when a file in it is rewritten in place, so only
+ * a walk that looked at every entry shows there is none.
+ */
+export declare function writtenSince(dir: string, since: number, limit?: number): Promise<{
+    fresh: string[];
+    unchecked: string | null;
+}>;
 /**
  * Take the run's claim: mount `<disk>:/runs/<id>` exclusively at `<mountRoot>/runs/<id>` and verify it. A live mount of
  * the same run already there is kept (in-place restart); a dead one is cleaned first. With no mount there, a stale archil
@@ -219,4 +242,29 @@ export declare function unmountClaim(mountpoint: string, host?: ArchilHost): Pro
  * verifying write is refused, MOUNTPOINT_NOT_EMPTY when the mountpoint cannot be emptied or archil still finds it not
  * empty, MOUNT_FAILED (exit 1) for a daemon of this host that is still running there.
  */
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export declare const NO_TOKEN = "none";
 export declare function acquire(opts: AcquireOptions): Promise<Claim>;
+/** One exclusive mount of a path, as `withClaim` holds it: its own mountpoint, never reused. */
+export interface ExclusiveMount {
+    readonly root: string;
+    /** `archil sync`; a refusal (the mount was revoked) is a FencedError. */
+    barrier(): Promise<{
+        ms: number;
+    }>;
+    /** `archil unmount` (a dead mount is cleaned), and the mountpoint removed. */
+    unmount(): Promise<Unmounted>;
+}
+/**
+ * Mount `<disk>:/<path>` exclusively at `mountpoint`, a fresh directory of the caller's own, and verify it, with `probe` as
+ * the claim probe's content. Another client's delegation is HeldError CLAIM_HELD (`held` is added to its message); the
+ * rest fails as `acquire` does. Unlike `acquire`, a mount already there is never reused, and nothing is forced.
+ */
+export declare function exclusiveMount(target: MountTarget, mountpoint: string, token: string, options: {
+    readonly host?: ArchilHost;
+    readonly probe: string;
+    readonly held?: string;
+}): Promise<ExclusiveMount>;

package/dist/claim.js

@@ -3,7 +3,7 @@
 // a mount token and uses the archil client: mount, verify, barrier, release, dead-mount cleanup.
 import { spawn } from "node:child_process";
 import { readdirSync, readFileSync } from "node:fs";
-import { mkdir, open, readdir, readFile, rmdir, stat } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, readFile, rmdir, stat } from "node:fs/promises";
 import { basename, isAbsolute, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
@@ -364,18 +364,29 @@ async function mountEntry(host, mountpoint) {
     }
     return found;
 }
-function isOurs(entry, ref) {
-    const base = `${ref.disk}:/${runPath(ref.id)}`;
-    return entry.fstype === "fuse.archil" && (entry.source === base || entry.source === `${base}[${ref.region}]`);
+const targetOf = (ref) => ({ disk: ref.disk, region: ref.region, path: runPath(ref.id) });
+function isOurs(entry, target) {
+    const base = `${target.disk}:/${target.path}`;
+    return entry.fstype === "fuse.archil" && (entry.source === base || entry.source === `${base}[${target.region}]`);
 }
-/** A FUSE mount whose daemon is gone answers stat with ENOTCONN; `archil` refuses it as "not running". */
+/**
+ * The errno codes of a stat on a FUSE mount whose daemon is gone: ENOTCONN once its connection is torn down, ECONNABORTED
+ * for a stat already in flight while it is torn down. Codes, never messages: a message is translated by the locale.
+ */
+export const DEAD_CONNECTION = new Set(["ENOTCONN", "ECONNABORTED"]);
+/**
+ * Whether the FUSE daemon behind a mount is gone, which `archil` reports as "not running". Its connection is torn down,
+ * so a stat fails with ENOTCONN; a stat already in flight while the dying daemon's connection is torn down (right after a
+ * kill -9, while its threads exit) fails with ECONNABORTED instead. Both are the connection's own end: a live daemon,
+ * however slow, answers, and a stopped one keeps the stat waiting.
+ */
 async function isDead(host, mountpoint) {
     try {
         await host.stat(mountpoint);
         return false;
     }
     catch (err) {
-        return err.code === "ENOTCONN";
+        return DEAD_CONNECTION.has(String(err.code));
     }
 }
 // Exit codes of the mount tools are not evidence (a busy mount can report success and stay); the mount table decides.
@@ -402,10 +413,13 @@ async function moveAside(host, mountpoint, code) {
     if (!ok(r))
         throw new ClaimError(code, `${mountpoint} was moved aside but its daemon was not stopped (${detail(r)})`);
 }
+/** The archil client's own directory on the disk, where it keeps its bookkeeping (`client-<n>`, `unlinked`). */
+const ARCHIL_BOOKKEEPING = ".archil";
 /**
  * Release a live mount the kernel will not unmount (Sysbox): `archil checkin` gives the delegation back, the client must
- * then list none on the run, and only then is the mount moved aside and its daemon killed. Any failed step leaves the
- * mount where it is, as UNMOUNT_FAILED: a mount that may still hold the delegation is never abandoned.
+ * then list none on the run (its own bookkeeping under `.archil/` is not the run's), and only then is the mount moved
+ * aside and its daemon killed. Any failed step leaves the mount where it is, as UNMOUNT_FAILED: a mount that may still
+ * hold the delegation is never abandoned.
  */
 async function checkinAndMoveAside(host, mountpoint) {
     const c = await archil(host, ["checkin", mountpoint], host.timeoutMs.unmount);
@@ -419,7 +433,11 @@ async function checkinAndMoveAside(host, mountpoint) {
     catch {
         list = null;
     }
-    const mine = (p) => p === mountpoint || (typeof p === "string" && p.startsWith(`${mountpoint}/`));
+    // The client also lists its own bookkeeping on the disk, `<mp>/.archil/client-<n>` and its `unlinked` (made when a
+    // file under the mount is deleted), which a checkin of the run leaves and none can clear once the mount is read-only.
+    // It is outside the run's tree, so it never holds the run: every other delegation under the mount does.
+    const bookkeeping = (p) => p === `${mountpoint}/${ARCHIL_BOOKKEEPING}` || p.startsWith(`${mountpoint}/${ARCHIL_BOOKKEEPING}/`);
+    const mine = (p) => p === mountpoint || (typeof p === "string" && p.startsWith(`${mountpoint}/`) && !bookkeeping(p));
     const held = !Array.isArray(list) || list.some((x) => x?.state === "Active" && mine(x.path));
     if (held)
         throw new ClaimError("UNMOUNT_FAILED", `${mountpoint} still lists a delegation after archil checkin: ${(ok(d) ? d.stdout : detail(d)).trim().slice(0, 300)}`);
@@ -470,20 +488,23 @@ async function ensureMountpoint(host, dir) {
  * goes to the wrapper as one line on stdin (`bin/archil-scoped`), with or without sudo.
  */
 async function mountRun(host, ref, mountpoint, token, force) {
-    const path = runPath(ref.id);
-    const args = [host.archil, "mount", ...(force ? ["--force"] : []), `${ref.disk}:/${path}`, mountpoint, "--region", ref.region];
+    await mountTarget(host, targetOf(ref), mountpoint, token, force);
+}
+async function mountTarget(host, target, mountpoint, token, force, held = "") {
+    const { path } = target;
+    const args = [host.archil, "mount", ...(force ? ["--force"] : []), `${target.disk}:/${path}`, mountpoint, "--region", target.region];
     const r = await sh(asRoot(host, args), host.timeoutMs.mount, `${token}\n`);
     const entry = await mountEntry(host, mountpoint);
-    if (ok(r) && entry && isOurs(entry, ref))
+    if (ok(r) && entry && isOurs(entry, target))
         return;
     if (entry)
         await unmountWith(host, mountpoint).catch(() => { });
     if (ok(r))
-        throw new ClaimError("MOUNT_FAILED", `archil mount ${path} exited 0 but ${mountpoint} is not an archil mount of the run`);
+        throw new ClaimError("MOUNT_FAILED", `archil mount ${path} exited 0 but ${mountpoint} is not an archil mount of ${path}`);
     if (STALE_MARKER.test(r.stderr))
         throw new ClaimError("MOUNT_FAILED", `an archil daemon of this host still runs for ${mountpoint}: ${detail(r, token)}`);
     if (!force && r.stderr.includes(HELD_MARKER))
-        throw new HeldError("claim", `${path} is held by another client (${detail(r, token)})`);
+        throw new HeldError("claim", `${path} is held by another client${held} (${detail(r, token)})`);
     if (r.stderr.includes(NOT_EMPTY_MARKER) || (MISLEADING_REFUSAL.test(r.stderr) && (await entries(mountpoint)) > 0)) {
         throw new ClaimError("MOUNTPOINT_NOT_EMPTY", `archil mount ${path} refused ${mountpoint}, which is not empty: ${detail(r, token)}`);
     }
@@ -548,6 +569,58 @@ async function clearStaleDaemon(host, ref, mountpoint) {
     process.stderr.write(`${JSON.stringify({ at: new Date().toISOString(), event: "stale archil daemon killed", run: ref.id, pids })}\n`);
     return pids;
 }
+/** The most entries of a bare mountpoint the stray check looks at; past it, nothing is moved aside. */
+export const STRAY_CHECK_LIMIT = 100_000;
+/**
+ * The entries under `dir` written since `since` (ms since the epoch), as paths relative to it, walked without following
+ * links. `unchecked` says why the walk could not look at every entry: more than `limit` of them, or one it could not
+ * read (an entry gone meanwhile is not one). A directory keeps its time when a file in it is rewritten in place, so only
+ * a walk that looked at every entry shows there is none.
+ */
+export async function writtenSince(dir, since, limit = STRAY_CHECK_LIMIT) {
+    const fresh = [];
+    const dirs = [""];
+    let seen = 0;
+    const failed = (error) => {
+        const code = error.code;
+        return code === "ENOENT" ? null : `an entry it cannot read (${code ?? "an unknown error"})`;
+    };
+    for (let i = 0; i < dirs.length; i++) {
+        const rel = dirs[i];
+        let names;
+        try {
+            names = await readdir(join(dir, rel));
+        }
+        catch (error) {
+            const unchecked = failed(error);
+            if (unchecked)
+                return { fresh, unchecked };
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (++seen > limit)
+                return { fresh, unchecked: `more than ${limit} entries` };
+            const path = rel ? `${rel}/${name}` : name;
+            let st;
+            try {
+                st = await lstat(join(dir, path));
+            }
+            catch (error) {
+                const unchecked = failed(error);
+                if (unchecked)
+                    return { fresh, unchecked };
+                continue;
+            }
+            if (st.mtimeMs >= since)
+                fresh.push(path);
+            if (st.isDirectory())
+                dirs.push(path);
+        }
+    }
+    return { fresh, unchecked: null };
+}
+/** The exit of a start refused for the app's own writes before its claim (EX_DATAERR): a restart would write them again. */
+const EXIT_WRITTEN_BEFORE_MOUNT = 65;
 /** How many entries a directory holds; 0 when it cannot be read. */
 const entries = (dir) => readdir(dir).then((names) => names.length, () => 0);
 /**
@@ -556,11 +629,28 @@ const entries = (dir) => readdir(dir).then((names) => names.length, () => 0);
  * directory with its owner and mode: archil refuses to mount over entries, and nothing in them may enter the run. One
  * line on stderr names the run and the count of entries, never a name or a byte of them. An unreadable mountpoint goes
  * to the wrapper too, which looks as root.
+ *
+ * Entries written since this process started are not an earlier incarnation's leftovers but this one's own writes
+ * before its claim mounted (an app's factory writing under ctx.root, which runs before the mount): moving them aside
+ * would lose them silently and the run would later find them gone (ENOENT). The start is refused instead,
+ * MOUNTPOINT_WRITTEN (exit 65, terminal: a restart writes them again), naming the first of them. A mountpoint whose
+ * entries the check cannot all look at (more than STRAY_CHECK_LIMIT, or one this process cannot read) may hide such a
+ * write, so it is refused too, MOUNTPOINT_UNCHECKED (exit 65: someone looks at it), naming none of them.
  */
 async function moveStrayAside(host, ref, mountRoot, mountpoint) {
     const names = await readdir(mountpoint).catch(() => null);
     if (names && names.length === 0)
         return null;
+    if (names) {
+        const { fresh, unchecked } = await writtenSince(mountpoint, performance.timeOrigin);
+        if (fresh.length > 0) {
+            const named = fresh.slice(0, 4).map((p) => `<mp>/${p}`).join(", ");
+            throw new ClaimError("MOUNTPOINT_WRITTEN", `the bare mountpoint <mp> of ${runPath(ref.id)} holds ${fresh.length} entr${fresh.length === 1 ? "y" : "ies"} written since this incarnation started, before its claim mounted: ${named}`.slice(0, 240), { exitCode: EXIT_WRITTEN_BEFORE_MOUNT });
+        }
+        if (unchecked) {
+            throw new ClaimError("MOUNTPOINT_UNCHECKED", `the bare mountpoint <mp> of ${runPath(ref.id)} holds ${unchecked}, so this incarnation cannot rule out its own writes before its claim mounted: nothing is moved aside. Look at it, then move it aside by hand`, { exitCode: EXIT_WRITTEN_BEFORE_MOUNT });
+        }
+    }
     const tag = Date.now().toString(36);
     const r = await archil(host, ["stray", mountpoint, tag]);
     if (!ok(r))
@@ -586,7 +676,10 @@ async function moveStrayAside(host, ref, mountRoot, mountpoint) {
  * the run but not that this mount does.
  */
 async function verify(host, ref, mountpoint) {
-    const path = runPath(ref.id);
+    await verifyTarget(host, runPath(ref.id), mountpoint, `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
+}
+/** `verify` for any path; `probe` is what the claim probe holds. */
+async function verifyTarget(host, path, mountpoint, probe) {
     const r = await archil(host, ["delegations", "--json", mountpoint]);
     if (!ok(r))
         throw new ClaimError("CLAIM_NOT_VERIFIED", `archil delegations ${mountpoint}: ${detail(r)}`);
@@ -602,7 +695,7 @@ async function verify(host, ref, mountpoint) {
     if (!active)
         throw new ClaimError("CLAIM_NOT_VERIFIED", `${mountpoint} holds no Active delegation on ${path}: ${r.stdout.trim().slice(0, 300)}`);
     try {
-        await host.persist(join(mountpoint, CLAIM_PROBE), `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
+        await host.persist(join(mountpoint, CLAIM_PROBE), probe);
     }
     catch (err) {
         throw ownWriteFenced(join(mountpoint, CLAIM_PROBE), err);
@@ -616,6 +709,11 @@ async function verify(host, ref, mountpoint) {
  * verifying write is refused, MOUNTPOINT_NOT_EMPTY when the mountpoint cannot be emptied or archil still finds it not
  * empty, MOUNT_FAILED (exit 1) for a daemon of this host that is still running there.
  */
+/**
+ * The token an instance holds when it was given none (`--token-stdin` read nothing): enough to reuse its live mount, never
+ * to mount. A restart in place gets it from a driver that hands the token to the first incarnation only (localHost).
+ */
+export const NO_TOKEN = "none";
 export async function acquire(opts) {
     const { ref, token } = opts;
     const path = runPath(ref.id);
@@ -631,7 +729,7 @@ export async function acquire(opts) {
     let reused = false;
     const existing = await mountEntry(host, root);
     if (existing) {
-        if (!isOurs(existing, ref))
+        if (!isOurs(existing, targetOf(ref)))
             throw new ClaimError("MOUNTPOINT_BUSY", `${root} already holds ${existing.fstype} ${existing.source}`);
         if (await isDead(host, root))
             await cleanDead(host, root);
@@ -639,6 +737,11 @@ export async function acquire(opts) {
             reused = true;
     }
     let stray = null;
+    // No live mount to reuse and no token to mount with: a restart whose mount went with the failed incarnation. It cannot
+    // hold the run again, so it is fenced (75, terminal) at once, and the next start of the run brings a new token.
+    if (!reused && token === NO_TOKEN) {
+        throw new FencedError(`no live mount of ${path} to reuse at ${root}, and this incarnation was given no mount token: it cannot mount the run again; a new start brings a new token`, { code: "CLAIM_GONE_NO_TOKEN" });
+    }
     if (!reused) {
         await ensureMountpoint(host, root);
         await clearStaleDaemon(host, ref, root);
@@ -720,3 +823,40 @@ class ArchilClaim {
         return { via };
     }
 }
+/**
+ * Mount `<disk>:/<path>` exclusively at `mountpoint`, a fresh directory of the caller's own, and verify it, with `probe` as
+ * the claim probe's content. Another client's delegation is HeldError CLAIM_HELD (`held` is added to its message); the
+ * rest fails as `acquire` does. Unlike `acquire`, a mount already there is never reused, and nothing is forced.
+ */
+export async function exclusiveMount(target, mountpoint, token, options) {
+    if (!token || /[\r\n]/.test(token))
+        throw new ClaimError("INVALID_ARGUMENT", "no mount token, or one with a line break");
+    const host = resolveHost(options.host);
+    if (await mountEntry(host, mountpoint))
+        throw new ClaimError("MOUNTPOINT_BUSY", `${mountpoint} is already a mount`);
+    await ensureMountpoint(host, mountpoint);
+    try {
+        await mountTarget(host, target, mountpoint, token, false, options.held);
+    }
+    catch (err) {
+        await rmdir(mountpoint).catch(() => { });
+        throw err;
+    }
+    try {
+        await verifyTarget(host, target.path, mountpoint, options.probe);
+    }
+    catch (err) {
+        await unmountWith(host, mountpoint).catch(() => { });
+        throw err;
+    }
+    return {
+        root: mountpoint,
+        async barrier() {
+            const r = await archil(host, ["sync", mountpoint], host.timeoutMs.sync);
+            if (ok(r))
+                return { ms: r.ms };
+            throw new FencedError(`archil sync ${mountpoint}: ${detail(r)}`);
+        },
+        unmount: () => unmountWith(host, mountpoint),
+    };
+}

package/dist/cli.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { type Parking } from "./park.js";
 import { type RunServer } from "./serve.js";
+import { type ArchilControl, type DiskClient } from "./supervise.js";
 import { type DurableRun } from "./run.js";
 /** "30s", "500ms", "2m", "1h", or plain milliseconds. */
 /**
@@ -28,6 +29,11 @@ export declare function runUser(spec: string, passwd?: string): {
     home: string;
     name: string;
 };
+/**
+ * The disk's control API for the supervisor (`archilControl`), from the API key in `--api-key-env` (default
+ * ARCHIL_API_KEY) and `--disk` and `--region`. `client` replaces the `disk` client (tests).
+ */
+export declare function cliControl(values: Record<string, unknown>, client?: DiskClient): Promise<ArchilControl>;
 /** 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. */