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

package/dist/status.d.ts

@@ -19,7 +19,7 @@ export type RunStatus = (typeof RUN_STATUSES)[number];
 export interface RunHolder {
     readonly driver: string;
     readonly host: string;
-    /** `/proc/sys/kernel/random/boot_id`; null where the platform has none. */
+    /** `/proc/sys/kernel/random/boot_id` (`kern.bootsessionuuid` on macOS); null where it cannot be read. */
     readonly bootId: string | null;
     readonly pid: number;
     /** When this incarnation claimed the run (ISO 8601). */
@@ -81,12 +81,14 @@ export declare const ARCHIL_FSTYPE = "fuse.archil";
  * A run root held open as a directory for the life of the instance. `at` is `/proc/self/fd/<n>`, a path the kernel
  * resolves through the open directory and never through the root's path (Node has no openat; the magic link stands in
  * for it): a file made, written or renamed under `at` is in the directory opened at acquire, or the call fails (ENOTCONN
- * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away.
+ * once the FUSE daemon is gone). It never lands on the local disk under a mountpoint whose mount went away. macOS has no
+ * such link: there `at` is the root's path (`byPath`), and only the checks below stand between a write and a root that was
+ * replaced.
  */
 export interface ClaimDir {
     /** The root's path, as the claim names it. */
     readonly root: string;
-    /** `/proc/self/fd/<n>`. Throws once closed: the number may then name another file. */
+    /** `/proc/self/fd/<n>`, or the root's path `byPath`. Throws once closed: the number may then name another file. */
     readonly at: string;
     /**
      * Resolves while the root's path still resolves to the directory held open (same device, same inode). A mount that was
@@ -107,6 +109,12 @@ export interface OpenClaimDirOptions {
     readonly fstype?: string | null;
     /** Default `/proc/self/mountinfo`. */
     readonly mountinfo?: string;
+    /**
+     * `at` is the root's path, not `/proc/self/fd/<n>`: the default on macOS, which has none. A write is checked against the
+     * held directory first (`assertMounted`), but a root renamed and replaced between that check and the write gets the
+     * write. For a local directory only.
+     */
+    readonly byPath?: boolean;
 }
 /** `major:minor` of a device number, as `/proc/self/mountinfo` writes it (glibc's encoding). */
 export declare function deviceName(dev: bigint): string;

package/dist/status.js

@@ -2,11 +2,12 @@
 // claim with write-to-temp, fsync, rename, and read by the supervisor (over the S3 API or a local mount). It is a hint
 // for the supervisor, never the source of truth: the store is. Any error writing it is a fence. The instance writes it
 // through its claim directory (`ClaimDir`), never by path, so a write cannot land under a mountpoint whose mount is gone.
-import { constants, readFileSync } from "node:fs";
+import { constants } from "node:fs";
 import { open, readFile, rename, rm, stat } from "node:fs/promises";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+import { thisBoot } from "./process-table.js";
 export const RUN_JSON = "run.json";
 /** The temporary file every write goes through; renamed over `run.json` once it is fsynced. */
 export const RUN_JSON_TEMP = "run.json.tmp";
@@ -204,7 +205,8 @@ export async function openClaimDir(root, options = {}) {
         await handle.close().catch(() => undefined);
         throw error instanceof FencedError ? error : unmounted(`checking the claim root ${root} failed: ${error.message}`, error);
     }
-    const at = `/proc/self/fd/${handle.fd}`;
+    const byPath = options.byPath ?? process.platform === "darwin";
+    const at = byPath ? root : `/proc/self/fd/${handle.fd}`;
     let closed = false;
     const same = (path, now, claims) => {
         if (now.dev === claims.dev && now.ino === claims.ino)
@@ -234,10 +236,18 @@ export async function openClaimDir(root, options = {}) {
         async assertSame(name) {
             if (closed)
                 throw unmounted(`the claim directory of ${root} is closed`);
-            const [byPath, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
+            if (byPath) {
+                // No second way to name the entry: the root must still be the directory held, and the entry on its device.
+                const [dir, entry] = await Promise.all([statOf(root), statOf(join(root, name))]);
+                same(root, dir, held);
+                if (entry.dev !== held.dev)
+                    throw unmounted(`${name} in the claim directory is on device ${deviceName(entry.dev)}, not the claim's ${deviceName(held.dev)}`);
+                return;
+            }
+            const [named, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
             if (inDir.dev !== held.dev)
                 throw unmounted(`${name} in the claim directory is on device ${deviceName(inDir.dev)}, not the claim's ${deviceName(held.dev)}`);
-            same(join(root, name), byPath, inDir);
+            same(join(root, name), named, inDir);
         },
         async close() {
             if (closed)
@@ -247,18 +257,10 @@ export async function openClaimDir(root, options = {}) {
         },
     };
 }
-function bootId() {
-    try {
-        return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * This process as a holder: the host driver's `handle` (default driver `local`, this machine's host name and boot id)
  * with this process's pid and `since`. A handle whose named fields have the wrong type is refused (RunRecordError).
  */
 export function currentHolder(handle = {}, since = new Date()) {
-    return holderOf({ driver: "local", host: hostname(), bootId: bootId(), ...handle, pid: process.pid, since: since.toISOString() });
+    return holderOf({ driver: "local", host: hostname(), bootId: thisBoot(), ...handle, pid: process.pid, since: since.toISOString() });
 }

package/dist/store.d.ts

@@ -39,8 +39,18 @@ export declare const PROFILE_PRAGMAS: {
         readonly mmap_size: 0;
     };
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export declare function assertPragmas(database: SqliteExecutor, profile: Profile): Promise<void>;
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export declare const FULLFSYNC_PRAGMAS: {
+    readonly fullfsync: 1;
+    readonly checkpoint_fullfsync: 1;
+};
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export declare function profilePragmas(profile: Profile, platform?: NodeJS.Platform): Readonly<Record<string, string | number>>;
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export declare function assertPragmas(database: SqliteExecutor, profile: Profile, platform?: NodeJS.Platform): Promise<void>;
 /**
  * The fenced state of one handle. The first error whose result code is in the I/O, full or not-a-database class marks it
  * fenced, runs `onFenced` once (before the error propagates), and from then on every operation fails with the same
@@ -84,6 +94,8 @@ export type OpenOptions = {
     readonly onFenced?: (error: StoreFencedError) => void;
     /** Wraps the raw database inside the fence, for instrumentation and fault injection. */
     readonly decorate?: (database: SqliteDatabase) => SqliteDatabase;
+    /** The platform whose pragmas the store takes (`profilePragmas`); default this one. For tests. */
+    readonly platform?: NodeJS.Platform;
 };
 export type ArchilStore = {
     readonly storage: SqliteStorage;

package/dist/store.js

@@ -64,10 +64,19 @@ export const PROFILE_PRAGMAS = {
     exclusive: { locking_mode: "exclusive", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
     shared: { locking_mode: "normal", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
 };
-/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
-export async function assertPragmas(database, profile) {
+/**
+ * On macOS, fsync does not flush the drive's cache, so a commit FULL syncs could still be lost to a power cut. These make
+ * SQLite sync with F_FULLFSYNC instead, at every commit and every checkpoint.
+ */
+export const FULLFSYNC_PRAGMAS = { fullfsync: 1, checkpoint_fullfsync: 1 };
+/** What `profile` must read back on `platform`: its own pragmas, and on macOS `FULLFSYNC_PRAGMAS` too. */
+export function profilePragmas(profile, platform = process.platform) {
+    return platform === "darwin" ? { ...PROFILE_PRAGMAS[profile], ...FULLFSYNC_PRAGMAS } : PROFILE_PRAGMAS[profile];
+}
+/** Read every pragma of `profile` on `platform` (default this one) back and refuse (StorePragmaError) when any differs. */
+export async function assertPragmas(database, profile, platform = process.platform) {
     const mismatches = [];
-    for (const [pragma, expected] of Object.entries(PROFILE_PRAGMAS[profile])) {
+    for (const [pragma, expected] of Object.entries(profilePragmas(profile, platform))) {
         const row = await database.get(`PRAGMA ${pragma}`);
         const actual = row === undefined ? undefined : Object.values(row)[0];
         if (actual !== expected)
@@ -203,7 +212,10 @@ export async function openArchilStore(file, profile = "exclusive", options = {})
         }
         await database.exec("PRAGMA synchronous = FULL"); // fsync the WAL on every commit
         await database.exec("PRAGMA mmap_size = 0"); // no mmap I/O of the database file on a network filesystem
-        await assertPragmas(database, profile);
+        const platform = options.platform ?? process.platform;
+        for (const pragma of platform === "darwin" ? Object.keys(FULLFSYNC_PRAGMAS) : [])
+            await database.exec(`PRAGMA ${pragma} = ON`);
+        await assertPragmas(database, profile, platform);
         const storage = await SqliteStorage.open(database);
         return { storage, database, profile, file };
     }

package/dist/supervise.d.ts

@@ -241,6 +241,25 @@ export type TokenUser = {
     expiresAt?: string;
     createdAt?: string;
 };
+/** What `archilControl` returns: everything `ensureRunning`, `superviseRuns`, `checkHost`, `fork` and the token janitor use. */
+export type ArchilControl = SupervisorControl & CheckControl & {
+    listUsers(): Promise<TokenUser[]>;
+};
+/** The two calls of the `disk` client (this package's dependency) that `archilControl` makes. */
+export type DiskClient = Pick<typeof import("disk"), "configure" | "getDisk">;
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export declare function archilControl(options: {
+    readonly apiKey: string;
+    readonly disk: string;
+    readonly region: string;
+    readonly client?: DiskClient;
+}): Promise<ArchilControl>;
 export interface TokenSweepOptions {
     /** The disk's token users (`getDisk(id).authorizedUsers`; the list lags by seconds). */
     listUsers(): Promise<TokenUser[]>;

package/dist/supervise.js

@@ -347,6 +347,31 @@ export async function superviseRuns(refs, host, opts) {
     }
     return out;
 }
+/**
+ * One Archil disk's control API from an API key, the object `pi-durable-disk supervise` builds for itself: a library
+ * caller that composes its own supervisor (with `daytonaHost`, or a driver of its own) passes it as `control`. The S3 and
+ * control calls go to the disk the key reaches; `listUsers` reads the disk record again on every call (the list lags by
+ * seconds). `configure` is the `disk` client's process-wide setting, so one process controls disks of one key and region.
+ * `client` replaces the `disk` client (tests).
+ */
+export async function archilControl(options) {
+    const { configure, getDisk } = options.client ?? (await import("disk"));
+    configure({ apiKey: options.apiKey, region: options.region });
+    const disk = await getDisk(options.disk);
+    return {
+        getObject: (key) => disk.getObject(key),
+        headObject: (key) => disk.headObject(key),
+        putObject: (key, body, putOptions) => disk.putObject(key, body, putOptions),
+        addUser: (user) => disk.addUser(user),
+        removeUser: (type, identifier) => disk.removeUser(type, identifier),
+        listDelegations: () => disk.listDelegations(),
+        revokeDelegation: (d) => disk.revokeDelegation(d),
+        exec: (command) => disk.exec(command),
+        listObjects: (prefix, listOptions) => disk.listObjects(prefix, listOptions),
+        deleteObjects: (keys, deleteOptions) => disk.deleteObjects(keys, deleteOptions),
+        listUsers: async () => (await getDisk(options.disk)).authorizedUsers ?? [],
+    };
+}
 const RELEASED = ["paused", "sleeping", "done", "failed"];
 /**
  * Remove mount-token users that no live mount needs. Removing a token user under a live mount makes that mount lose its

package/dist/watchdog.d.ts

@@ -9,6 +9,8 @@ export interface SweepOptions {
     readonly proc?: string;
     readonly sys?: string;
     readonly kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Lists processes with this ps(1) instead of reading `proc`: the default on macOS, which has no /proc, unless `proc` is given. */
+    readonly ps?: (file: string, args: readonly string[]) => string;
 }
 /** One look at the shared state at `now`. True once the lease has lapsed, for good; the first look records the age. */
 export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
@@ -16,7 +18,7 @@ export declare const lapsed: (shared: BigInt64Array, now: bigint) => boolean;
  * SIGKILL the instance's commands: the process group of each direct child (pi starts each command as its own group's
  * leader), or the child alone when it shares the instance's group; with `ownCgroup`, every other process of the cgroup.
  * Never the instance or its group. A process this user may not signal (sudo's archil helpers) is skipped. Returns the
- * number of signals sent. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
  * spaces and parentheses.
  */
 export declare const sweep: (instance: number, options?: SweepOptions) => number;

package/dist/watchdog.js

@@ -1,8 +1,9 @@
 // The lease watchdog on a thread of its own. A store commit is synchronous, so a FUSE daemon that stops
 // answering blocks the instance's main thread inside the kernel, and with it every timer the main thread owns. This
-// thread never touches the mount: it reads a clock reading the main thread shares, /proc and the cgroup, and sends
-// signals. Once the lease has lapsed it kills the instance's commands on every look, until the main thread runs again,
+// thread never touches the mount: it reads a clock reading the main thread shares, /proc and the cgroup (on macOS, one
+// ps listing), and sends signals. Once the lease has lapsed it kills the instance's commands on every look, until the main thread runs again,
 // sees the flag and takes the normal fence path (exit 75).
+import * as child_process from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Worker } from "node:worker_threads";
@@ -49,20 +50,49 @@ function cgroupPids(instance, proc, sys) {
   }
 }
 
-function sweep(instance, options = {}) {
-  const proc = options.proc ?? "/proc";
-  const kill = options.kill ?? ((pid, signal) => process.kill(pid, signal));
+/** The instance's group and its direct children, from /proc. */
+function procTree(instance, proc) {
   const own = stat(proc, instance);
-  if (own === undefined) return 0;
-  const targets = new Set();
+  if (own === undefined) return undefined;
+  const children = [];
   for (const entry of fs.readdirSync(proc)) {
     const pid = Number(entry);
     if (!Number.isInteger(pid) || pid <= 0 || pid === instance) continue;
     const child = stat(proc, pid);
-    if (child === undefined || child.ppid !== instance) continue;
-    targets.add(child.pgrp === own.pgrp || child.pgrp <= 1 ? pid : -child.pgrp);
+    if (child !== undefined && child.ppid === instance) children.push({ pid, pgrp: child.pgrp });
+  }
+  return { pgrp: own.pgrp, children };
+}
+
+/** The same from one ps listing, where there is no /proc (macOS). */
+function psTree(instance, ps) {
+  let text;
+  try {
+    text = ps("/bin/ps", ["-A", "-o", "pid=,ppid=,pgid="]);
+  } catch {
+    return undefined;
+  }
+  const rows = [];
+  for (const line of text.split("\n")) {
+    const f = line.trim().split(/\s+/).map(Number);
+    if (f.length === 3 && f.every(Number.isInteger)) rows.push({ pid: f[0], ppid: f[1], pgrp: f[2] });
   }
-  if (options.ownCgroup) {
+  const own = rows.find((row) => row.pid === instance);
+  if (own === undefined) return undefined;
+  return { pgrp: own.pgrp, children: rows.filter((row) => row.ppid === instance && row.pid > 0 && row.pid !== instance) };
+}
+
+const runPs = (file, args) => child_process.execFileSync(file, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
+
+function sweep(instance, options = {}) {
+  const proc = options.proc ?? "/proc";
+  const kill = options.kill ?? ((pid, signal) => process.kill(pid, signal));
+  const ps = options.ps ?? (options.proc === undefined && process.platform === "darwin" ? runPs : undefined);
+  const tree = ps === undefined ? procTree(instance, proc) : psTree(instance, ps);
+  if (tree === undefined) return 0;
+  const targets = new Set();
+  for (const child of tree.children) targets.add(child.pgrp === tree.pgrp || child.pgrp <= 1 ? child.pid : -child.pgrp);
+  if (options.ownCgroup && ps === undefined) {
     for (const pid of cgroupPids(instance, proc, options.sys ?? "/sys/fs/cgroup")) if (pid !== instance && pid > 0) targets.add(pid);
   }
   let sent = 0;
@@ -78,6 +108,7 @@ function sweep(instance, options = {}) {
 }
 `;
 const WORKER_SOURCE = `"use strict";
+const child_process = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
 const { workerData } = require("node:worker_threads");
@@ -88,14 +119,14 @@ setInterval(() => {
   Atomics.add(shared, SLOT_KILLED, BigInt(sweep(workerData.instance, { ownCgroup: workerData.ownCgroup })));
 }, workerData.checkMs);
 `;
-const compiled = new Function("fs", "path", `"use strict";${LIB}\nreturn { lapsed, sweep };`)(fs, path);
+const compiled = new Function("child_process", "fs", "path", `"use strict";${LIB}\nreturn { lapsed, sweep };`)(child_process, fs, path);
 /** One look at the shared state at `now`. True once the lease has lapsed, for good; the first look records the age. */
 export const lapsed = compiled.lapsed;
 /**
  * SIGKILL the instance's commands: the process group of each direct child (pi starts each command as its own group's
  * leader), or the child alone when it shares the instance's group; with `ownCgroup`, every other process of the cgroup.
  * Never the instance or its group. A process this user may not signal (sudo's archil helpers) is skipped. Returns the
- * number of signals sent. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
+ * number of signals sent. Where there is no /proc (macOS) the processes come from one ps listing, and there is no cgroup. `stat` lines are `pid (comm) state ppid pgrp ...`, read after the last `)` since comm may hold
  * spaces and parentheses.
  */
 export const sweep = compiled.sweep;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.14",
   "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
   "keywords": [
     "pi",
@@ -30,6 +30,10 @@
       "types": "./dist/lease.d.ts",
       "default": "./dist/lease.js"
     },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "default": "./dist/internals.js"
+    },
     "./bin/archil-scoped": "./bin/archil-scoped",
     "./package.json": "./package.json"
   },
@@ -58,12 +62,13 @@
     "test:live:run": "node --test --test-concurrency=1 test/live/run.live.test.ts",
     "test:live:store": "node --test --test-concurrency=1 test/live/store.live.test.ts",
     "test:live:supervise": "node --test --test-concurrency=1 test/live/supervise.live.test.ts",
+    "test:live:supervise-slow": "node --test --test-concurrency=1 test/live/supervise-slow.live.test.ts",
     "test:live:docker": "PDA_LIVE_DOCKER=1 node --test --test-concurrency=1 test/live/docker.live.test.ts test/live/docker-park.live.test.ts",
     "verify:tarball": "node scripts/verify-tarball.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/chord": ">=1.0.4 <1.3.0",
-    "@earendil-works/pi-durable": ">=1.0.4 <1.3.0"
+    "@earendil-works/chord": ">=1.0.4 <1.4.0",
+    "@earendil-works/pi-durable": ">=1.0.4 <1.4.0"
   },
   "dependencies": {
     "disk": "1.7.0"