@openclaw/fs-safe 0.6.0 → 0.7.0

package/dist/json-durable-queue-ownership.js

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { recoverDurableQueueRetirement, retireDurableQueueSource, } from "./json-durable-queue-retirement.js";
+import { withQueueTransferLock } from "./json-durable-queue-transfer-lock.js";
+import { serializePathWrite } from "./write-queue.js";
+function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+export function durableQueueProcessingPath(paths) {
+    if (paths.processingPath)
+        return paths.processingPath;
+    return paths.jsonPath.endsWith(".json")
+        ? `${paths.jsonPath.slice(0, -".json".length)}.processing`
+        : `${paths.jsonPath}.processing`;
+}
+async function lstatOrNull(filePath) {
+    try {
+        return await fs.lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function regularQueueFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new Error(`queue entry is not a regular file: ${filePath}`);
+    }
+    return identity;
+}
+async function withQueueEntryLock(paths, run) {
+    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(path.resolve(paths.jsonPath), run));
+}
+async function claimDurableQueueEntryUnlocked(paths) {
+    const processingPath = durableQueueProcessingPath(paths);
+    await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
+    const existingProcessing = await regularQueueFileIdentity(processingPath);
+    if (existingProcessing) {
+        const pending = await lstatOrNull(paths.jsonPath);
+        if (pending &&
+            !pending.isSymbolicLink() &&
+            pending.isFile() &&
+            sameFileIdentityForCleanup(pending, existingProcessing)) {
+            await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+        }
+        return processingPath;
+    }
+    const pending = await lstatOrNull(paths.jsonPath);
+    if (!pending || pending.isSymbolicLink() || !pending.isFile())
+        return null;
+    if (pending.nlink > 1n || !sameFileIdentityForCleanup(pending, pending)) {
+        throw new FsSafeError("path-mismatch", "queue entry is not exclusively owned");
+    }
+    try {
+        await fs.link(paths.jsonPath, processingPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "EEXIST") {
+            return (await regularQueueFileIdentity(processingPath)) ? processingPath : null;
+        }
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    await syncDirectory(path.dirname(processingPath));
+    const claimed = await regularQueueFileIdentity(processingPath);
+    if (!claimed || claimed.nlink > 2n) {
+        throw new FsSafeError("path-mismatch", "queue claim is not an owned regular file");
+    }
+    await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
+    return processingPath;
+}
+export async function claimDurableQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return null;
+    return await withQueueEntryLock(paths, async () => await claimDurableQueueEntryUnlocked(paths));
+}
+export async function completeDeliveredQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.deliveredPath))))
+        return false;
+    return await withQueueEntryLock(paths, async () => {
+        if (!(await regularQueueFileIdentity(paths.deliveredPath)))
+            return false;
+        if (await regularQueueFileIdentity(durableQueueProcessingPath(paths))) {
+            await fs.unlink(paths.deliveredPath);
+            await syncDirectory(path.dirname(paths.deliveredPath));
+            return false;
+        }
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        return true;
+    });
+}
+export async function acknowledgeDurableQueueEntry(paths) {
+    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+        return;
+    await withQueueEntryLock(paths, async () => {
+        const processingPath = durableQueueProcessingPath(paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const delivered = await regularQueueFileIdentity(paths.deliveredPath);
+        if (!processing) {
+            if (delivered) {
+                await fs.unlink(paths.deliveredPath);
+                await syncDirectory(path.dirname(paths.deliveredPath));
+            }
+            if (await regularQueueFileIdentity(paths.jsonPath)) {
+                throw new FsSafeError("path-mismatch", "queue acknowledgement requires a processing claim");
+            }
+            return;
+        }
+        if (delivered)
+            await fs.unlink(paths.deliveredPath);
+        await fs.rename(processingPath, paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+        await fs.unlink(paths.deliveredPath);
+        await syncDirectory(path.dirname(paths.deliveredPath));
+    });
+}
+export async function moveDurableQueueEntryToFailed(params) {
+    await withQueueEntryLock(params.paths, async () => {
+        const processingPath = durableQueueProcessingPath(params.paths);
+        const processing = await regularQueueFileIdentity(processingPath);
+        const existingFailed = await regularQueueFileIdentity(params.failedPath);
+        if (!processing && existingFailed) {
+            await syncDirectory(path.dirname(params.failedPath));
+            await syncDirectory(path.dirname(processingPath));
+            const recoveredFailed = await regularQueueFileIdentity(params.failedPath);
+            if (!recoveredFailed ||
+                !sameFileIdentityForCleanup(existingFailed, recoveredFailed)) {
+                throw new FsSafeError("path-mismatch", "failed queue destination changed during recovery");
+            }
+            if (await regularQueueFileIdentity(params.paths.jsonPath)) {
+                throw new FsSafeError("already-exists", "failed queue destination already exists");
+            }
+            return;
+        }
+        const sourcePath = processing
+            ? processingPath
+            : await claimDurableQueueEntryUnlocked(params.paths);
+        if (!sourcePath) {
+            throw Object.assign(new Error("queue entry does not exist"), { code: "ENOENT" });
+        }
+        const source = await regularQueueFileIdentity(sourcePath);
+        const failed = await regularQueueFileIdentity(params.failedPath);
+        if (failed) {
+            if (source && sameFileIdentityForCleanup(source, failed)) {
+                await syncDirectory(path.dirname(params.failedPath));
+                await fs.unlink(sourcePath);
+                await syncDirectory(path.dirname(sourcePath));
+                return;
+            }
+            throw new FsSafeError("already-exists", "failed queue destination already exists");
+        }
+        await fs.link(sourcePath, params.failedPath);
+        await syncDirectory(path.dirname(params.failedPath));
+        await fs.unlink(sourcePath);
+        await syncDirectory(path.dirname(sourcePath));
+    });
+}

package/dist/json-durable-queue-retirement.d.ts

@@ -0,0 +1,9 @@
+export declare function recoverDurableQueueRetirement(params: {
+    jsonPath: string;
+    processingPath: string;
+}): Promise<void>;
+export declare function retireDurableQueueSource(params: {
+    jsonPath: string;
+    processingPath: string;
+}): Promise<void>;
+//# sourceMappingURL=json-durable-queue-retirement.d.ts.map

package/dist/json-durable-queue-retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-retirement.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-retirement.ts"],"names":[],"mappings":"AAgFA,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAED,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/json-durable-queue-retirement.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+const RETIREMENT_ROOT_NAME = ".fs-safe-retirements";
+const RETIREMENT_ENTRY_NAME = "entry";
+function getErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+async function lstatOrNull(filePath) {
+    try {
+        return await fs.lstat(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function assertDirectory(identity, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("path-mismatch", `${label} is not an owned directory`);
+    }
+}
+async function regularFileIdentity(filePath) {
+    const identity = await lstatOrNull(filePath);
+    if (!identity)
+        return null;
+    if (identity.isSymbolicLink() || !identity.isFile()) {
+        throw new FsSafeError("path-mismatch", "queue retirement path is not a regular file");
+    }
+    return identity;
+}
+function retirementPaths(jsonPath) {
+    const rootPath = path.join(path.dirname(jsonPath), RETIREMENT_ROOT_NAME);
+    const dirPath = path.join(rootPath, path.basename(jsonPath));
+    return { dirPath, entryPath: path.join(dirPath, RETIREMENT_ENTRY_NAME), rootPath };
+}
+async function inspectRetirementRoot(jsonPath) {
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    const root = await lstatOrNull(rootPath);
+    if (!root)
+        return null;
+    assertDirectory(root, "queue retirement root");
+    return rootPath;
+}
+async function ensureRetirementRoot(jsonPath) {
+    const parentPath = path.dirname(jsonPath);
+    const rootPath = retirementPaths(jsonPath).rootPath;
+    await fs.mkdir(rootPath, { mode: 0o700 }).catch((error) => {
+        if (getErrorCode(error) !== "EEXIST")
+            throw error;
+    });
+    const root = await fs.lstat(rootPath, { bigint: true });
+    assertDirectory(root, "queue retirement root");
+    await syncDirectory(parentPath);
+    return rootPath;
+}
+async function removeRetirementRecord(params) {
+    await fs.rmdir(params.dirPath).catch((error) => {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(params.rootPath);
+}
+export async function recoverDurableQueueRetirement(params) {
+    const rootPath = await inspectRetirementRoot(params.jsonPath);
+    if (!rootPath)
+        return;
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    const dir = await lstatOrNull(dirPath);
+    if (!dir)
+        return;
+    assertDirectory(dir, "queue retirement record");
+    const names = await fs.readdir(dirPath);
+    if (names.length === 0) {
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    if (names.length !== 1 || names[0] !== RETIREMENT_ENTRY_NAME) {
+        throw new FsSafeError("path-mismatch", "queue retirement record is ambiguous");
+    }
+    const entry = await regularFileIdentity(entryPath);
+    const processing = await regularFileIdentity(params.processingPath);
+    if (!entry || !processing) {
+        throw new FsSafeError("path-mismatch", "queue retirement ownership is incomplete");
+    }
+    if (!sameFileIdentityForCleanup(entry, processing)) {
+        const pending = await regularFileIdentity(params.jsonPath);
+        if (!pending) {
+            await fs.link(entryPath, params.jsonPath);
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (sameFileIdentityForCleanup(pending, entry)) {
+            await syncDirectory(path.dirname(params.jsonPath));
+        }
+        else if (pending.nlink > 1n) {
+            throw new FsSafeError("path-mismatch", "queue replacement identity is ambiguous");
+        }
+    }
+    await fs.unlink(entryPath);
+    await syncDirectory(dirPath);
+    await removeRetirementRecord({ dirPath, rootPath });
+}
+export async function retireDurableQueueSource(params) {
+    await recoverDurableQueueRetirement(params);
+    const rootPath = await ensureRetirementRoot(params.jsonPath);
+    const { dirPath, entryPath } = retirementPaths(params.jsonPath);
+    await fs.mkdir(dirPath, { mode: 0o700 });
+    await syncDirectory(rootPath);
+    try {
+        await fs.rename(params.jsonPath, entryPath);
+    }
+    catch (error) {
+        if (getErrorCode(error) !== "ENOENT")
+            throw error;
+        await removeRetirementRecord({ dirPath, rootPath });
+        return;
+    }
+    await syncDirectory(dirPath);
+    await syncDirectory(path.dirname(params.jsonPath));
+    await recoverDurableQueueRetirement(params);
+}

package/dist/json-durable-queue-transfer-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withQueueTransferLock<T>(filePath: string, run: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=json-durable-queue-transfer-lock.d.ts.map

package/dist/json-durable-queue-transfer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-transfer-lock.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-transfer-lock.ts"],"names":[],"mappings":"AAKA,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}

package/dist/json-durable-queue-transfer-lock.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { sha256Hex } from "./file-identity.js";
+import { withSidecarLock } from "./sidecar-lock.js";
+export async function withQueueTransferLock(filePath, run) {
+    const lockPath = path.join(path.dirname(filePath), `.fs-safe-transfer-${sha256Hex(path.basename(filePath)).slice(0, 32)}.lock`);
+    return await withSidecarLock(filePath, {
+        managerKey: "fs-safe.queue-transfer",
+        lockPath,
+        staleMs: 30_000,
+        staleRecovery: "fail-closed",
+        timeoutMs: 45_000,
+        payload: () => ({
+            ownerToken: randomUUID(),
+            createdAt: new Date().toISOString(),
+        }),
+        retry: { retries: 180, minTimeout: 25, maxTimeout: 250, factor: 1.1 },
+    }, run);
+}

package/dist/json-durable-queue.d.ts

@@ -1,6 +1,7 @@
 export type JsonDurableQueueEntryPaths = {
     jsonPath: string;
     deliveredPath: string;
+    processingPath?: string;
 };
 export type JsonDurableQueueReadResult<T> = {
     entry: T;

package/dist/json-durable-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAM5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+KD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAsDD,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"json-durable-queue.d.ts","sourceRoot":"","sources":["../src/json-durable-queue.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AAY3E,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED,wBAAsB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpF;AAmBD,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,0BAA0B,CAO5B;AAED,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAgLD,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AA4ED,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,CAAC,CAAC,CASZ;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,MAAM,EAAE;IACzD,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBpB;AAED,wBAAsB,kCAAkC,CAAC,CAAC,EACxD,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,EAAE,CAAC,CA4Dd;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}

package/dist/json-durable-queue.js

@@ -1,9 +1,13 @@
-import fs from "node:fs";
+import fs, {} from "node:fs";
 import path from "node:path";
-import { sameFileIdentity } from "./file-identity.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { syncQueueDirectoryCreation } from "./json-durable-queue-directory.js";
+import { acknowledgeDurableQueueEntry, claimDurableQueueEntry, completeDeliveredQueueEntry, moveDurableQueueEntryToFailed, } from "./json-durable-queue-ownership.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { replaceFileAtomic } from "./replace-file.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 export const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES = 16 * 1024 * 1024;
 function getErrnoCode(error) {
     return error && typeof error === "object" && "code" in error
@@ -46,6 +50,7 @@ export function resolveJsonDurableQueueEntryPaths(queueDir, id) {
     return {
         jsonPath: path.join(queueDir, `${id}.json`),
         deliveredPath: path.join(queueDir, `${id}.delivered`),
+        processingPath: path.join(queueDir, `${id}.processing`),
     };
 }
 export async function ensureJsonDurableQueueDirs(params) {
@@ -61,6 +66,7 @@ async function ensureJsonDurableQueueDir(dir, validationRoot) {
     await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
     await assertNoSymlinkDirectorySegments(root, dir, false);
     await chmodQueueDirectory(dir);
+    await syncQueueDirectoryCreation(dir, root.path);
 }
 async function assertJsonDurableQueueDir(dir, validationRoot) {
     const root = validationRoot
@@ -208,35 +214,55 @@ export async function writeJsonDurableQueueEntry(params) {
         content: stringifyJsonDocument(params.entry, null, 2),
         mode: 0o600,
         tempPrefix: params.tempPrefix,
+        syncTempFile: true,
+        syncParentDir: true,
     });
 }
-async function readBoundedUtf8File(params) {
-    const initialStat = await fs.promises.lstat(params.filePath);
-    if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
-        throw new Error("queue entry is not a regular file");
-    }
-    if (initialStat.nlink > 1) {
-        throw new Error("queue entry hardlinks are not allowed");
+async function replaceJsonDurableQueueEntry(params) {
+    await replaceFileAtomic({
+        filePath: params.filePath,
+        content: stringifyJsonDocument(params.entry, null, 2),
+        mode: 0o600,
+        tempPrefix: params.tempPrefix,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+}
+async function inspectQueueEntry(inspect, maxBytes, expected) {
+    let inspectionFailed = false;
+    try {
+        return await inspectFileIdentity(async () => {
+            try {
+                const stat = await inspect();
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    throw new Error("queue entry is not a regular file");
+                }
+                if (stat.nlink > 1n)
+                    throw new Error("queue entry hardlinks are not allowed");
+                if (stat.size > maxBytes)
+                    throw new Error(`queue entry exceeds ${maxBytes} bytes`);
+                return stat;
+            }
+            catch (error) {
+                inspectionFailed = true;
+                throw error;
+            }
+        }, expected);
     }
-    if (initialStat.size > params.maxBytes) {
-        throw new Error(`queue entry exceeds ${params.maxBytes} bytes`);
+    catch (error) {
+        // Translate only the identity helper's rejection, never inspection errors.
+        if (inspectionFailed)
+            throw error;
+        throw new Error("queue entry changed during read", { cause: error });
     }
-    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" && process.platform !== "win32"
-        ? fs.constants.O_NOFOLLOW
-        : 0;
-    const handle = await fs.promises.open(params.filePath, fs.constants.O_RDONLY | noFollow);
+}
+async function readBoundedUtf8File(params) {
+    const inspectPath = () => fs.promises.lstat(params.filePath, { bigint: true });
+    const initialStat = await inspectQueueEntry(inspectPath, params.maxBytes);
+    const handle = await fs.promises.open(params.filePath, resolveReadOpenFlags());
     try {
-        const openedStat = await handle.stat();
-        const pathStat = await fs.promises.lstat(params.filePath);
-        if (!openedStat.isFile() ||
-            pathStat.isSymbolicLink() ||
-            !pathStat.isFile() ||
-            openedStat.nlink > 1 ||
-            pathStat.nlink > 1 ||
-            !sameFileIdentity(initialStat, openedStat) ||
-            !sameFileIdentity(pathStat, openedStat)) {
-            throw new Error("queue entry changed during read");
-        }
+        const openedStat = await inspectQueueEntry(() => handle.stat({ bigint: true }), params.maxBytes, initialStat);
+        await inspectQueueEntry(inspectPath, params.maxBytes, openedStat);
         const chunks = [];
         const scratch = Buffer.allocUnsafe(Math.min(64 * 1024, params.maxBytes + 1));
         let total = 0;
@@ -259,35 +285,26 @@ async function readBoundedUtf8File(params) {
 export async function readJsonDurableQueueEntry(filePath, options = {}) {
     return JSON.parse(await readBoundedUtf8File({
         filePath,
-        maxBytes: options.maxBytes ?? DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+        maxBytes: normalizeMaxBytes(options.maxBytes, {
+            defaultValue: DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES,
+        }),
     }));
 }
 export async function ackJsonDurableQueueEntry(paths) {
-    try {
-        await fs.promises.rename(paths.jsonPath, paths.deliveredPath);
-    }
-    catch (error) {
-        if (getErrnoCode(error) === "ENOENT") {
-            await unlinkBestEffort(paths.deliveredPath);
-            return;
-        }
-        throw error;
-    }
-    await unlinkBestEffort(paths.deliveredPath);
+    await acknowledgeDurableQueueEntry(paths);
 }
 export async function loadJsonDurableQueueEntry(params) {
     try {
-        const stat = await fs.promises.lstat(params.paths.jsonPath);
-        if (!stat.isFile()) {
+        const claimedPath = await claimDurableQueueEntry(params.paths);
+        if (!claimedPath)
             return null;
-        }
-        const raw = await readJsonDurableQueueEntry(params.paths.jsonPath, {
+        const raw = await readJsonDurableQueueEntry(claimedPath, {
             maxBytes: params.maxBytes,
         });
         const result = params.read ? await params.read(raw, params.paths.jsonPath) : { entry: raw };
         if (result.migrated) {
-            await writeJsonDurableQueueEntry({
-                filePath: params.paths.jsonPath,
+            await replaceJsonDurableQueueEntry({
+                filePath: claimedPath,
                 entry: result.entry,
                 tempPrefix: params.tempPrefix,
             });
@@ -315,28 +332,41 @@ export async function loadPendingJsonDurableQueueEntries(options) {
     const now = Date.now();
     for (const file of files) {
         if (file.endsWith(".delivered")) {
-            await unlinkBestEffort(path.join(options.queueDir, file));
+            const id = file.slice(0, -".delivered".length);
+            await completeDeliveredQueueEntry(resolveJsonDurableQueueEntryPaths(options.queueDir, id));
         }
         else if (options.cleanupTmpMaxAgeMs !== undefined && file.endsWith(".tmp")) {
             await unlinkStaleTmpBestEffort(path.join(options.queueDir, file), now, options.cleanupTmpMaxAgeMs);
         }
     }
-    const entries = [];
+    const ids = [];
+    const seenIds = new Set();
     for (const file of files) {
-        if (!file.endsWith(".json")) {
+        const suffix = file.endsWith(".processing")
+            ? ".processing"
+            : file.endsWith(".json")
+                ? ".json"
+                : null;
+        if (!suffix)
             continue;
-        }
-        const filePath = path.join(options.queueDir, file);
+        const id = file.slice(0, -suffix.length);
+        if (seenIds.has(id))
+            continue;
+        seenIds.add(id);
+        ids.push(id);
+    }
+    const entries = [];
+    for (const id of ids) {
         try {
-            const stat = await fs.promises.lstat(filePath);
-            if (!stat.isFile()) {
+            const paths = resolveJsonDurableQueueEntryPaths(options.queueDir, id);
+            const claimedPath = await claimDurableQueueEntry(paths);
+            if (!claimedPath)
                 continue;
-            }
-            const raw = await readJsonDurableQueueEntry(filePath, { maxBytes: options.maxBytes });
-            const result = options.read ? await options.read(raw, filePath) : { entry: raw };
+            const raw = await readJsonDurableQueueEntry(claimedPath, { maxBytes: options.maxBytes });
+            const result = options.read ? await options.read(raw, paths.jsonPath) : { entry: raw };
             if (result.migrated) {
-                await writeJsonDurableQueueEntry({
-                    filePath,
+                await replaceJsonDurableQueueEntry({
+                    filePath: claimedPath,
                     entry: result.entry,
                     tempPrefix: options.tempPrefix,
                 });
@@ -354,5 +384,8 @@ export async function moveJsonDurableQueueEntryToFailed(params) {
     const roots = await queueValidationRoots(params.queueDir, params.failedDir);
     await assertJsonDurableQueueDir(params.queueDir, roots.queueRoot);
     await ensureJsonDurableQueueDir(params.failedDir, roots.failedRoot);
-    await fs.promises.rename(path.join(params.queueDir, `${params.id}.json`), path.join(params.failedDir, `${params.id}.json`));
+    await moveDurableQueueEntryToFailed({
+        paths: resolveJsonDurableQueueEntryPaths(params.queueDir, params.id),
+        failedPath: path.join(params.failedDir, `${params.id}.json`),
+    });
 }

package/dist/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"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"}