@demlik/tea 0.21.0 → 0.22.0

package/dist/node/index.d.ts

@@ -1,6 +1,6 @@
 import WebSocket from 'ws';
-import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-BPKp2bGo.js';
-import { c as Sub, D as Dispose } from '../core-BKJW1Kmq.js';
+import { M as Migrated, D as DeletableStore, F as FencedStore } from '../runtime-types-CP-ykwgf.js';
+import { c as Sub, D as Dispose } from '../core-DNDAEhO2.js';
 import '@standard-schema/spec';
 
 /**
@@ -79,6 +79,30 @@ interface Journal<R> {
     withLock<A>(stream: string, fx: () => Promise<A>): Promise<A>;
 }
 
+/**
+ * Why a writer could not take a lock:
+ *
+ * - `another-host`: the lock names another host, which may still be writing.
+ * - `live-holder`: its process is alive on this machine, or its old-format id
+ *   names a live process here.
+ * - `unwritten`: the lock is empty and too young to count as a crash.
+ * - `unreadable`: its contents are not a lock this version can read.
+ * - `contended`: no one holder was to blame; other writers kept taking it.
+ */
+type FileLockBlock = "another-host" | "live-holder" | "unwritten" | "unreadable" | "contended";
+/**
+ * A write gave up waiting for a lock file. `lockPath` names the file to clear
+ * and `blockedBy` says why it could not be taken. The write did not happen.
+ */
+declare class FileLockTimeoutError extends Error {
+    readonly lockPath: string;
+    readonly waitedMs: number;
+    readonly blockedBy: FileLockBlock;
+    readonly name = "FileLockTimeoutError";
+    readonly _tag: "file_lock_timeout";
+    constructor(lockPath: string, waitedMs: number, blockedBy: FileLockBlock);
+}
+
 /**
  * @packageDocumentation
  * @demlik/tea/node — Node host adapter for `@demlik/tea`.
@@ -158,6 +182,25 @@ interface FileStoreOptions {
      * that started from the same version is refused with a `StoreConflictError`
      * at its next save. Omit it and the store is exactly as it was — the last
      * writer wins, and single-writer is the caller's precondition to keep.
+     *
+     * A run on a fenced store must be given an `onError`, or it does not compile
+     * (see `StoreAndOnError`). A lost fence can surface with no caller to reject
+     * at, under `"stop-save"` or `"follow-up"`, and the default sink would rethrow
+     * it and end the process. Treat a `StoreConflictError` there as this run having
+     * moved to another process: stop that run, and leave the others alone.
+     *
+     * Each save and `delete()` takes a lock file, `<path>.fence.lock`, and a
+     * writer that dies holding it leaves it behind. The next write steals a lock
+     * whose holder is proven gone: an empty one older than a short grace period,
+     * one from an earlier boot of this machine, or one whose process is dead.
+     *
+     * Any other lock is waited on for up to 10 seconds, and then the write rejects
+     * with a {@link FileLockTimeoutError} naming the file. That includes a lock
+     * from another host, which is never stolen because that host may be live on a
+     * shared volume. So a folder restored onto a new machine can need one clear
+     * step: once the old machine is known to be gone, delete the file. Hosts are
+     * told apart by `os.hostname()`, so give two live hosts on one volume two
+     * names.
      */
     readonly fenced?: true;
 }
@@ -176,12 +219,17 @@ interface FileStoreOptions {
  * O(n) in the stream's length; a durable record log a machine replays is read
  * whole anyway, so the atomic-rewrite guarantee is worth the cost.
  *
- * The ordering key is taken under a `wx` lock file (`<file>.lock`) holding the
- * writer's PID: a second writer racing the same stream blocks on the lock, so
- * `seq` is a single total order across processes. A crashed writer's lock is
- * stolen once its PID proves dead (`process.kill(pid, 0)` → `ESRCH`), so a
- * crash never wedges the stream. This is the lock phoenix spike #6673 proved:
- * its only job is an honest order key, not the win.
+ * The ordering key is taken under a `wx` lock file (`<file>.lock`) naming the
+ * writer's host, boot and PID: a second writer racing the same stream blocks on
+ * the lock, so `seq` is a single total order across processes. This is the lock
+ * phoenix spike #6673 proved: its only job is an honest order key, not the win.
+ *
+ * A leftover lock behaves as it does on a fenced {@link fileStore}: one whose
+ * holder is proven gone is stolen, so a crash on this machine does not wedge the
+ * stream. Any other lock, including one from another host, is waited on for up
+ * to 10 seconds, and then the append rejects with a
+ * {@link FileLockTimeoutError} naming the file. See
+ * {@link FileStoreOptions.fenced} for the cases and the clear step.
  *
  * `changes` fires for appends made through THIS instance; a cross-process
  * append lands on disk but is not broadcast here (that is a polling concern the
@@ -315,4 +363,4 @@ interface NodeSubscribeWithWs<M, Ctx extends NodeSubscribeCtx> extends NodeSubsc
 declare function nodeSubscribe<M>(): NodeSubscribeBase<M>;
 declare function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(opts: NodeSubscribeOpts<M>): NodeSubscribeWithWs<M, Ctx>;
 
-export { type FileStoreOptions, type NodeSignalDeps, type NodeSignalSub, type NodeSub, type NodeSubscribeBase, type NodeSubscribeCtx, type NodeSubscribeOpts, type NodeSubscribeWithWs, type NodeTimerDeps, type NodeTimerSub, type NodeWsDeps, type NodeWsHandlers, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
+export { type FileLockBlock, FileLockTimeoutError, type FileStoreOptions, type NodeSignalDeps, type NodeSignalSub, type NodeSub, type NodeSubscribeBase, type NodeSubscribeCtx, type NodeSubscribeOpts, type NodeSubscribeWithWs, type NodeTimerDeps, type NodeTimerSub, type NodeWsDeps, type NodeWsHandlers, type NodeWsRegistry, type NodeWsSub, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };

package/dist/node/index.js

@@ -1,9 +1,10 @@
-import { dispatchIfPresent } from '../chunk-VHKDUBXC.js';
-import { StoreConflictError } from '../chunk-GAVLND5C.js';
-import { unlink, mkdir, writeFile, rename, open, readFile } from 'fs/promises';
+import { dispatchIfPresent } from '../chunk-BVFS3ICC.js';
+import { StoreConflictError } from '../chunk-A3QPMX5M.js';
+import { mkdir, writeFile, rename, readFile, unlink, open, stat } from 'fs/promises';
 import { createRequire } from 'module';
 import { dirname, join } from 'path';
 import { AsyncLocalStorage } from 'async_hooks';
+import { uptime, hostname } from 'os';
 
 var AsyncLock = class {
   tail = Promise.resolve();
@@ -60,6 +61,172 @@ function makeJournal(backend) {
     }
   };
 }
+var DEFAULT_LIMITS = { waitMs: 1e4, graceMs: 2e3 };
+var SPIN_MS = 10;
+var BOOT_TOLERANCE_MS = 6e4;
+var BLOCK_EXPLAINED = {
+  "another-host": "it was written on another host, which may still be writing, so it is not stolen. If that host is gone, delete the file and try again.",
+  "live-holder": "the process it names is alive. If that process is not a writer here, delete the file and try again.",
+  unwritten: "it is empty and too young to count as a crash.",
+  unreadable: "its contents are not a lock this version can read. If no writer holds it, delete the file and try again.",
+  contended: "other writers kept taking it."
+};
+var FileLockTimeoutError = class extends Error {
+  constructor(lockPath, waitedMs, blockedBy) {
+    super(
+      `@demlik/tea: gave up on lock "${lockPath}" after ${Math.round(waitedMs)} ms: ${BLOCK_EXPLAINED[blockedBy]}`
+    );
+    this.lockPath = lockPath;
+    this.waitedMs = waitedMs;
+    this.blockedBy = blockedBy;
+  }
+  lockPath;
+  waitedMs;
+  blockedBy;
+  name = "FileLockTimeoutError";
+  _tag = "file_lock_timeout";
+};
+function thisMachine() {
+  return {
+    host: hostname(),
+    bootedAtMs: Math.round(Date.now() - uptime() * 1e3)
+  };
+}
+function isValidPid(pid) {
+  return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0;
+}
+function parseStamp(body) {
+  let raw;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (typeof raw !== "object" || raw === null) return { kind: "unreadable" };
+  const { host, bootedAtMs, pid } = raw;
+  if (typeof host !== "string" || typeof bootedAtMs !== "number" || !Number.isFinite(bootedAtMs) || !isValidPid(pid)) {
+    return { kind: "unreadable" };
+  }
+  return { kind: "stamped", host, bootedAtMs, pid };
+}
+function parseHolder(text) {
+  const body = text.trim();
+  if (body === "") return { kind: "unwritten" };
+  if (/^\d+$/.test(body)) {
+    const pid = Number(body);
+    return isValidPid(pid) ? { kind: "pid-only", pid } : { kind: "unreadable" };
+  }
+  return parseStamp(body);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function judgeHolder(holder, ageMs, here, graceMs) {
+  switch (holder.kind) {
+    case "unwritten":
+      return ageMs > graceMs ? "stale" : "unwritten";
+    case "unreadable":
+      return "unreadable";
+    case "pid-only":
+      return isProcessAlive(holder.pid) ? "live-holder" : "stale";
+    case "stamped":
+      if (holder.host !== here.host) return "another-host";
+      if (Math.abs(holder.bootedAtMs - here.bootedAtMs) > BOOT_TOLERANCE_MS) {
+        return "stale";
+      }
+      return isProcessAlive(holder.pid) ? "live-holder" : "stale";
+  }
+}
+async function ageOf(path) {
+  try {
+    return Date.now() - (await stat(path)).mtimeMs;
+  } catch (err) {
+    if (err.code === "ENOENT") return "vanished";
+    throw err;
+  }
+}
+async function inspectLock(lockPath, limits) {
+  let text;
+  try {
+    text = await readFile(lockPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return "vanished";
+    throw err;
+  }
+  const ageMs = await ageOf(lockPath);
+  if (ageMs === "vanished") return "vanished";
+  return judgeHolder(parseHolder(text), ageMs, thisMachine(), limits.graceMs);
+}
+async function createExclusive(path, body) {
+  try {
+    const handle = await open(path, "wx");
+    try {
+      if (body !== "") await handle.writeFile(body);
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch (err) {
+    if (err.code === "EEXIST") return false;
+    throw err;
+  }
+}
+var removeIfPresent = (path) => unlink(path).catch((err) => {
+  if (err.code !== "ENOENT") throw err;
+});
+async function stealIfStillStale(lockPath, limits) {
+  const guardPath = `${lockPath}.steal`;
+  if (!await createExclusive(guardPath, "")) {
+    const age = await ageOf(guardPath);
+    if (age !== "vanished" && age > limits.graceMs) {
+      await removeIfPresent(guardPath);
+    }
+    return false;
+  }
+  try {
+    const verdict = await inspectLock(lockPath, limits);
+    if (verdict === "stale") await removeIfPresent(lockPath);
+    return verdict === "stale" || verdict === "vanished";
+  } finally {
+    await removeIfPresent(guardPath);
+  }
+}
+async function acquireFileLock(dir, lockPath, limits) {
+  await mkdir(dir, { recursive: true });
+  const startedAt = performance.now();
+  let blockedBy = "contended";
+  for (; ; ) {
+    const here = thisMachine();
+    const stamp = JSON.stringify({
+      host: here.host,
+      bootedAtMs: here.bootedAtMs,
+      pid: process.pid
+    });
+    if (await createExclusive(lockPath, stamp)) return;
+    const verdict = await inspectLock(lockPath, limits);
+    if (verdict !== "stale" && verdict !== "vanished") blockedBy = verdict;
+    const freed = verdict === "vanished" || verdict === "stale" && await stealIfStillStale(lockPath, limits);
+    const waitedMs = performance.now() - startedAt;
+    if (waitedMs >= limits.waitMs) {
+      throw new FileLockTimeoutError(lockPath, waitedMs, blockedBy);
+    }
+    if (!freed) await new Promise((resolve) => setTimeout(resolve, SPIN_MS));
+  }
+}
+async function withFileLock(dir, lockPath, fx, limits = DEFAULT_LIMITS) {
+  await acquireFileLock(dir, lockPath, limits);
+  try {
+    return await fx();
+  } finally {
+    await unlink(lockPath).catch(() => {
+    });
+  }
+}
 
 // src/node/index.ts
 function fileStore(path, parse, options = {}) {
@@ -123,9 +290,7 @@ function fenceFileStore(base, path) {
       return { raw: await base.load(), version };
     },
     async saveFenced(state, expectedVersion) {
-      await mkdir(dirname(path), { recursive: true });
-      await acquireFileLock(dirname(path), lockPath);
-      try {
+      return withFileLock(dirname(path), lockPath, async () => {
         const actual = await readVersion();
         if (actual !== expectedVersion) {
           throw new StoreConflictError(expectedVersion, actual);
@@ -136,23 +301,13 @@ function fenceFileStore(base, path) {
         await writeFile(tmp, String(next), "utf8");
         await rename(tmp, fencePath);
         return next;
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      });
     },
     async delete() {
-      await acquireFileLock(dirname(path), lockPath);
-      try {
-        await base.delete();
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      await withFileLock(dirname(path), lockPath, () => base.delete());
     }
   };
 }
-var LOCK_SPIN_MS = 10;
 function fileJournal(dir, parse) {
   const streamPath = (stream) => join(dir, `${encodeURIComponent(stream)}.jsonl`);
   const readEntries = async (stream) => {
@@ -188,58 +343,10 @@ function fileJournal(dir, parse) {
       return entry;
     },
     async lock(stream, fx) {
-      const lockPath = `${streamPath(stream)}.lock`;
-      await acquireFileLock(dir, lockPath);
-      try {
-        return await fx();
-      } finally {
-        await unlink(lockPath).catch(() => {
-        });
-      }
+      return withFileLock(dir, `${streamPath(stream)}.lock`, fx);
     }
   });
 }
-async function acquireFileLock(dir, lockPath) {
-  await mkdir(dir, { recursive: true });
-  for (; ; ) {
-    try {
-      const handle = await open(lockPath, "wx");
-      try {
-        await handle.writeFile(String(process.pid));
-      } finally {
-        await handle.close();
-      }
-      return;
-    } catch (err) {
-      if (err.code !== "EEXIST") throw err;
-      if (await stealIfStale(lockPath)) continue;
-      await new Promise((resolve) => setTimeout(resolve, LOCK_SPIN_MS));
-    }
-  }
-}
-async function stealIfStale(lockPath) {
-  let holder;
-  try {
-    holder = await readFile(lockPath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return true;
-    throw err;
-  }
-  const pid = Number(holder.trim());
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  if (isProcessAlive(pid)) return false;
-  await unlink(lockPath).catch(() => {
-  });
-  return true;
-}
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
-  }
-}
 var cachedWs;
 function loadWebSocket() {
   if (cachedWs) return cachedWs;
@@ -328,6 +435,6 @@ function nodeWsRunner(handlers) {
   };
 }
 
-export { fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
+export { FileLockTimeoutError, fileJournal, fileStore, nodeSubscribe, sendToWebSocket };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map