@parcha/pi-durable-disk 0.1.0-beta.21 → 0.1.0-beta.26

package/dist/run-files.js

@@ -0,0 +1,259 @@
+// A run's own files, read over the disk's control (S3 GET, HEAD and LIST) and nothing else: these calls never mount, never
+// write, and never take or wait on the run's claim, so anyone may read a run another host holds. A read sees what the
+// holder has synced (its last barrier), and a file the holder writes whole (a temp file, then a link or a rename) is never
+// seen half-written. What a file means is the reader's business: disk parses none of them. The one write here,
+// `putRunFile`, creates a file in a run nobody holds (a held run refuses it), for a place's start window.
+//
+// How Archil's S3 API answers, measured on archil 0.8.42: a missing key is 404; a directory is a marker key ending in "/";
+// a symlink is listed as an ordinary zero-byte key, but its HEAD and GET answer 501 NotImplemented, and S3 never follows a
+// link. So a symlink is told on a read's 501, never from a listing.
+import { constants } from "node:fs";
+import { lstat, open, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { runPath } from "./claim.js";
+import { PdaError } from "./errors.js";
+/** A read of a run's files that cannot be answered. Its message names the path, never what a file holds. */
+export class RunFileError extends PdaError {
+    constructor(code, message, options = {}) {
+        super(code, message, options);
+    }
+}
+/**
+ * What is wrong with `path` as a relative path of safe segments inside the run, or null when nothing is. The answer names
+ * the fault only, never the path, which may hold anything a caller passed.
+ */
+function pathFault(path, allowRoot) {
+    if (path === "")
+        return allowRoot ? null : "it is empty";
+    if (path.startsWith("/"))
+        return "it is absolute";
+    const unsafe = path.search(/[^A-Za-z0-9._/-]/);
+    if (unsafe >= 0)
+        return `it has an unsafe character at index ${unsafe}`;
+    const segments = path.split("/");
+    if (segments.includes(""))
+        return "it has an empty segment";
+    if (segments.includes("."))
+        return 'it has a "." segment';
+    if (segments.includes(".."))
+        return 'it has a ".." segment';
+    if (segments[0] === ".archil")
+        return "it is under .archil/";
+    return null;
+}
+/** The segments of `path`, or INVALID_PATH naming what is wrong (never the path). `""` is the run's root where allowed. */
+export function runFileSegments(path, allowRoot) {
+    const fault = pathFault(path, allowRoot);
+    if (fault !== null)
+        throw new RunFileError("INVALID_PATH", `not a relative path of safe segments (letters, digits, ".", "_", "-") inside the run: ${fault}`);
+    return path === "" ? [] : path.split("/");
+}
+/** The run's key prefix and `path` under it, or INVALID_PATH. */
+function keyOf(ref, path, allowRoot) {
+    const run = `${runPath(ref.id)}/`;
+    const segments = runFileSegments(path, allowRoot);
+    return { run, key: segments.length === 0 ? run : `${run}${segments.join("/")}` };
+}
+const statusOf = (error) => error?.status ?? error?.statusCode;
+const missing = (error) => statusOf(error) === 404 || error?.code === "NoSuchKey";
+const notImplemented = (error) => statusOf(error) === 501 || error?.code === "NotImplemented";
+/** `call`, ended at once when `signal` aborts (the request itself may still finish; nothing waits on it). */
+function bounded(call, signal) {
+    signal?.throwIfAborted();
+    // A control that throws before it returns a promise rejects like any other, so the listener below is always removed.
+    const pending = Promise.resolve().then(call);
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        pending.then((v) => (signal.removeEventListener("abort", onAbort), resolve(v)), (e) => (signal.removeEventListener("abort", onAbort), reject(e)));
+    });
+}
+/** A control call; any failure but the ones the caller handles is CONTROL_API_FAILED, an abort stays the caller's. */
+async function ask(what, call, signal) {
+    try {
+        return await bounded(call, signal);
+    }
+    catch (error) {
+        if (signal?.aborted && error === signal.reason)
+            throw error;
+        throw error instanceof RunFileError ? error : new RunFileError("CONTROL_API_FAILED", `${what} over the control failed`, { cause: error });
+    }
+}
+async function runMissing(control, run, ref, signal) {
+    if ((await ask(`reading ${run}`, () => control.headObject(run), signal)) === null)
+        throw new RunFileError("RUN_MISSING", `there is no run ${ref.id} on this disk`);
+}
+/**
+ * The bytes of `path` in the run (`runs/<id>/<path>`), or null when there is no such file yet, so a poller waits. A
+ * directory or a symlink is NOT_A_FILE; a run that does not exist is RUN_MISSING. No polling here: the caller bounds its
+ * own wait, with `signal` and its own retries.
+ */
+export async function readRunFile(control, ref, path, options = {}) {
+    const { signal } = options;
+    const { run, key } = keyOf(ref, path, false);
+    signal?.throwIfAborted();
+    try {
+        return await bounded(() => control.getObject(key), signal);
+    }
+    catch (error) {
+        if (signal?.aborted && error === signal.reason)
+            throw error;
+        if (notImplemented(error))
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${ref.id} is not a regular file (a symlink: the S3 API reads only files)`, { cause: error });
+        if (!missing(error))
+            throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${ref.id} over the control failed`, { cause: error });
+    }
+    // Not there: a directory of that name, no run at all, or a file not written yet.
+    if ((await ask(`reading ${path}/`, () => control.headObject(`${key}/`), signal)) !== null)
+        throw new RunFileError("NOT_A_FILE", `${path} in run ${ref.id} is a directory`);
+    await runMissing(control, run, ref, signal);
+    return null;
+}
+/**
+ * The names directly under `dir` in the run (`""` for the run's root), sorted: files and directories alike, names only,
+ * never a claim about what each one is. A directory not made yet lists nothing; a run that does not exist is RUN_MISSING.
+ */
+export async function listRunFiles(control, ref, dir, options = {}) {
+    const { signal } = options;
+    const { run, key } = keyOf(ref, dir, true);
+    const prefix = key.endsWith("/") ? key : `${key}/`;
+    const listed = await ask(`listing ${dir || "the run"} of run ${ref.id}`, () => control.listObjects(prefix, { recursive: false }), signal);
+    const names = new Set();
+    for (const k of [...listed.objects.map((o) => o.key), ...(listed.commonPrefixes ?? [])]) {
+        if (!k.startsWith(prefix))
+            continue;
+        const name = k.slice(prefix.length).replace(/\/$/, "");
+        if (name !== "" && !name.includes("/"))
+            names.add(name);
+    }
+    if (names.size === 0)
+        await runMissing(control, run, ref, signal);
+    return [...names].sort();
+}
+/** A put Archil refused because a delegation holds the run: exactly 409 OperationAborted, as D2 measured on archil 0.8.42. */
+const windowClosed = (error) => statusOf(error) === 409 && error?.code === "OperationAborted";
+/**
+ * Create `path` in the run (`runs/<id>/<path>`) holding `text`, owned by `owner` with mode 0644, after making each missing
+ * parent directory as a marker `owner` owns, mode 0755 (a directory made by path on a mount refuses later creates).
+ * Create-only: a file or a directory already at `path` is EXISTS and nothing is written. The check is a HEAD before the
+ * PutObject, not a conditional create (Archil's client has none), so it is not exclusive against another writer at the
+ * same moment: claim a shared name where a single writer is certain. Only a run nobody holds takes the write; a held one
+ * answers 409 OperationAborted, which is WINDOW_CLOSED. For non-secret run files: a put file is readable in the run.
+ */
+export async function putRunFile(control, ref, path, text, owner, options = {}) {
+    const { signal } = options;
+    const segments = runFileSegments(path, false);
+    const run = `${runPath(ref.id)}/`;
+    const key = `${run}${segments.join("/")}`;
+    const call = async (what, fn) => {
+        try {
+            return await bounded(fn, signal);
+        }
+        catch (error) {
+            if (signal?.aborted && error === signal.reason)
+                throw error;
+            if (windowClosed(error))
+                throw new RunFileError("WINDOW_CLOSED", `${what} was refused: a delegation holds run ${ref.id} (409 OperationAborted)`, { cause: error });
+            throw new RunFileError("CONTROL_API_FAILED", `${what} over the control failed`, { cause: error });
+        }
+    };
+    if ((await call(`reading ${path}`, () => control.headObject(key))) !== null || (await call(`reading ${path}/`, () => control.headObject(`${key}/`))) !== null) {
+        throw new RunFileError("EXISTS", `${path} is already in run ${ref.id}: a put creates, never replaces`);
+    }
+    for (let i = 1; i < segments.length; i++) {
+        const dir = segments.slice(0, i).join("/");
+        if ((await call(`reading ${dir}/`, () => control.headObject(`${run}${dir}/`))) === null) {
+            await call(`making ${dir}/`, () => control.putObject(`${run}${dir}/`, "", { uid: owner.uid, gid: owner.gid, mode: 0o755 }));
+        }
+    }
+    await call(`writing ${path}`, () => control.putObject(key, text, { uid: owner.uid, gid: owner.gid, mode: 0o644 }));
+}
+// ---- the same reads over a run directory on this machine (localPlace) -------------------------------------------------
+const fsCode = (error) => error?.code;
+async function localRunMissing(root, id) {
+    try {
+        if ((await stat(root)).isDirectory())
+            return;
+    }
+    catch (error) {
+        if (fsCode(error) !== "ENOENT" && fsCode(error) !== "ENOTDIR")
+            throw new RunFileError("CONTROL_API_FAILED", `reading run ${id} failed`, { cause: error });
+    }
+    throw new RunFileError("RUN_MISSING", `there is no run ${id} on this machine`);
+}
+/**
+ * Walk `segments` under `root` with lstat: a symlink anywhere on the way is NOT_A_FILE (never followed, so nothing outside
+ * the run is ever read). Resolves with the last path and what it is, or null when something on the way is not there.
+ */
+async function walk(root, id, path, segments) {
+    let at = root;
+    for (const [i, segment] of segments.entries()) {
+        at = join(at, segment);
+        let st;
+        try {
+            st = await lstat(at);
+        }
+        catch (error) {
+            if (fsCode(error) === "ENOENT" || fsCode(error) === "ENOTDIR")
+                return null;
+            throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${id} failed`, { cause: error });
+        }
+        if (st.isSymbolicLink())
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} goes through a symlink, which is never followed`);
+        if (i < segments.length - 1 && !st.isDirectory())
+            return null;
+        if (i === segments.length - 1)
+            return { at, dir: st.isDirectory() };
+    }
+    return { at, dir: true };
+}
+/**
+ * `readRunFile` over the run directory `root` on this machine: the same path rules and answers. A directory, or a symlink
+ * anywhere on the way, is NOT_A_FILE, and a file swapped for a link after the check is refused, not followed.
+ */
+export async function readLocalRunFile(root, id, path) {
+    const segments = runFileSegments(path, false);
+    await localRunMissing(root, id);
+    const found = await walk(root, id, path, segments);
+    if (!found)
+        return null;
+    if (found.dir)
+        throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is a directory`);
+    let handle;
+    try {
+        handle = await open(found.at, constants.O_RDONLY | constants.O_NOFOLLOW);
+        if (!(await handle.stat()).isFile())
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is not a regular file`);
+        return new Uint8Array(await handle.readFile());
+    }
+    catch (error) {
+        if (error instanceof RunFileError)
+            throw error;
+        if (fsCode(error) === "ELOOP")
+            throw new RunFileError("NOT_A_FILE", `${path} in run ${id} is a symlink, which is never followed`);
+        if (fsCode(error) === "ENOENT")
+            return null;
+        throw new RunFileError("CONTROL_API_FAILED", `reading ${path} in run ${id} failed`, { cause: error });
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/** `listRunFiles` over the run directory `root` on this machine: the same rules; a symlink on the way is NOT_A_FILE. */
+export async function listLocalRunFiles(root, id, dir) {
+    const segments = runFileSegments(dir, true);
+    await localRunMissing(root, id);
+    const found = await walk(root, id, dir, segments);
+    if (!found || !found.dir)
+        return [];
+    try {
+        return (await readdir(found.at)).sort();
+    }
+    catch (error) {
+        if (fsCode(error) === "ENOENT" || fsCode(error) === "ENOTDIR")
+            return [];
+        throw new RunFileError("CONTROL_API_FAILED", `listing ${dir || "the run"} of run ${id} failed`, { cause: error });
+    }
+}

package/dist/supervise.d.ts

@@ -59,6 +59,18 @@ export interface HostDriver {
     readonly kills?: "process" | "box";
     /** Optional, for a driver whose instances get machines of their own: the box `handle`'s instance runs in, as a receipt. */
     box?(handle: HostHandle): HostBox | null;
+    /**
+     * Optional, with `box`: the provider of the boxes this driver makes (its receipts' `provider`), known before a box
+     * exists. A place tells each host box's runner which label to claim by it (`HOST_BOX`).
+     */
+    readonly provider?: string;
+    /**
+     * Optional: the name of the instance `handle` is for, the same for its fresh handle and an adopted one (dockerHost: the
+     * daemon and the container's name), or `undefined` for a handle that is not this driver's or names none. A place keys
+     * the boxes it started by it, so a box adopted again keeps its key. Two handles are one instance only when this names
+     * them both, equally: without it no two handles ever are.
+     */
+    instanceOf?(handle: HostHandle): string | undefined;
 }
 /** The control-plane calls the supervisor uses; an archil `Disk` satisfies it. */
 export interface SupervisorControl extends ControlApi {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.21",
-  "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
+  "version": "0.1.0-beta.26",
+  "description": "The agent is the workspace: its conversation and its files live together in one directory on a disk. Mount it on any Linux host or container, release it, and mount it elsewhere: the agent carries on.",
   "keywords": [
     "pi",
     "pi-durable",
@@ -72,7 +72,7 @@
     "@earendil-works/pi-durable": ">=1.0.4 <1.4.0"
   },
   "dependencies": {
-    "disk": "1.7.0"
+    "disk": "1.9.0"
   },
   "devDependencies": {
     "@earendil-works/chord": "1.1.0",