@parcha/pi-durable-disk 0.1.0-beta.18 → 0.1.0-beta.20

package/dist/cli.d.ts

@@ -56,12 +56,14 @@ export interface InstanceLife {
  * 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
+ * `pause` seals it paused. An app that released the run itself (`run.release()`, in `onOpen` or after it) has nothing left to
+ * serve: the instance exits 0 when `onOpen` returns, and a stop after that exits 0 without a drain, since the Harness is
+ * closed and the run's status final. 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>;
+export declare function serveUntilDone(run: Pick<DurableRun, "setStatus" | "release" | "record"> & Partial<Pick<DurableRun, "releasing">>, 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.

package/dist/cli.js

@@ -285,7 +285,9 @@ async function runInstance(values) {
  * 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
+ * `pause` seals it paused. An app that released the run itself (`run.release()`, in `onOpen` or after it) has nothing left to
+ * serve: the instance exits 0 when `onOpen` returns, and a stop after that exits 0 without a drain, since the Harness is
+ * closed and the run's status final. 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).
@@ -305,11 +307,25 @@ export function serveUntilDone(run, onOpen, onSigterm, log, signals = process, l
         let releasing = false;
         let parking;
         const sleeping = (at) => run.setStatus("sleeping", { reason: "drained" }, { wakeAt: at === null ? null : new Date(at).toISOString() });
+        // The app released the run: wait for its release to end (a second `release()` joins it) and leave.
+        const leaveReleased = async (event) => {
+            try {
+                await run.release();
+                log("released", { ...event, record: run.record });
+                done(0);
+            }
+            catch (err) {
+                log("release failed", { code: err.code, message: err.message });
+                done(exitCodeFor(err));
+            }
+        };
         const shutdown = async (signal) => {
             if (releasing)
                 return;
             releasing = true;
             log("draining", { signal, onSigterm, drainMs });
+            if (run.releasing === true)
+                return leaveReleased({ drained: "released" });
             try {
                 if (await parking?.stop())
                     return done(0);
@@ -358,6 +374,12 @@ export function serveUntilDone(run, onOpen, onSigterm, log, signals = process, l
         // onOpen may return at once (work submitted) or run for the instance's life.
         Promise.resolve()
             .then(() => onOpen?.(durable))
+            .then(() => {
+            if (releasing || run.releasing !== true)
+                return;
+            releasing = true;
+            void leaveReleased({ drained: "app" });
+        })
             .catch((err) => {
             if (releasing)
                 return;
@@ -642,6 +664,10 @@ async function forkRun(values) {
 const COMMON = { disk: { type: "string" }, region: { type: "string" }, id: { type: "string" }, "mount-root": { type: "string" }, "api-key-env": { type: "string" }, "host-name": { type: "string" } };
 export async function main(argv) {
     const [command, ...rest] = argv;
+    if (command === "--help" || command === "-h" || command === "help" || (command !== undefined && rest[0] === "--help")) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
     try {
         switch (command) {
             case "run":

package/dist/run.d.ts

@@ -277,6 +277,8 @@ export interface DurableRun {
     /** `run.json` as last written. */
     readonly record: RunRecord;
     readonly fenced: boolean;
+    /** True once `release()` began: the Harness is closed, the status is final, and the instance has nothing left to serve. */
+    readonly releasing: boolean;
     /** Write a status transition. `done` and `failed` run the barrier first, so a terminal status never names workspace files that are not durable. */
     setStatus(status: RunStatus, detail?: JsonValue | null, options?: {
         readonly wakeAt?: string | null;

package/dist/run.js

@@ -754,6 +754,9 @@ class Run {
                 await this.#store.storage.close(this.#context);
         });
     }
+    get releasing() {
+        return this.#releasing !== undefined || this.#released;
+    }
     async setStatus(status, detail = null, options = {}) {
         if (!this.#lease.fenced && (this.#released || this.#releasing))
             throw new RunError("RUN_RELEASED", `run ${this.ref.id} is released`);

package/dist/status.js

@@ -184,8 +184,9 @@ export function parseStartMark(text) {
 // watchdog's is (src/watchdog.ts says why). One refresh at a time, all synchronous: a stop (the message) is handled only
 // between two refreshes, so none is still writing once the thread has exited. It writes only while `dir` is still the
 // directory it first saw (its device and inode, read on this thread, so a stalled mount never holds the caller's): a path
-// that names another (a descriptor number reused) or none is never written, and the keeper stops. Its first failure goes
-// to the main thread, once.
+// that names another (a descriptor number reused) or none is never written, and the keeper stops. A rewrite that fails is
+// checked the same way, so a directory that moved between the check and the write is reported as moved, not as a failed
+// write. Its first failure goes to the main thread, once.
 const KEEPER_SOURCE = `"use strict";
 const fs = require("node:fs");
 const path = require("node:path");
@@ -200,19 +201,23 @@ const report = (message) => {
   reported = true;
   parentPort.postMessage(message);
 };
-function refresh() {
-  if (stopped) return;
+// Why dir is no longer the directory the keeper first saw, or null while it is (the first call records it).
+function moved() {
   let now;
   try {
     now = fs.statSync(dir, { bigint: true });
   } catch (error) {
-    stopped = true;
-    return report("its directory cannot be reached (" + (error.code || error.message) + "), so it is no longer the directory the keeper started on");
+    return "its directory cannot be reached (" + (error.code || error.message) + "), so it is no longer the directory the keeper started on";
   }
   first ??= { dev: now.dev, ino: now.ino };
-  if (now.dev !== first.dev || now.ino !== first.ino) {
+  return now.dev === first.dev && now.ino === first.ino ? null : "its directory is no longer the directory the keeper started on";
+}
+function refresh() {
+  if (stopped) return;
+  const away = moved();
+  if (away) {
     stopped = true;
-    return report("its directory is no longer the directory the keeper started on");
+    return report(away);
   }
   let text;
   try {
@@ -245,6 +250,12 @@ function refresh() {
       fs.closeSync(handle);
     }
   } catch (error) {
+    // The directory may have moved after the check above: then that is the reason, and the keeper stops.
+    const away = moved();
+    if (away) {
+      stopped = true;
+      return report(away);
+    }
     report("rewriting it failed (" + (error.code || error.message) + ")");
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/pi-durable-disk",
-  "version": "0.1.0-beta.18",
+  "version": "0.1.0-beta.20",
   "description": "A durable pi host on a network disk (Archil): one owner per run, a fence, durable commits, and a supervisor.",
   "keywords": [
     "pi",