@giovannijecha/jecode 0.8.4 → 0.8.5

package/dist/sessions/lease.js

@@ -1,83 +1,166 @@
-// A tiny, bounded process lease for one durable conversation.
-import { randomUUID } from "node:crypto";
-import { lstat, open, unlink } from "node:fs/promises";
-const MAX_LEASE_BYTES = 256;
+// A tiny, generation-safe process lease for one durable conversation.
+import { lstat, unlink } from "node:fs/promises";
+import { BoundedFileError, readBoundedText, stableFileExpectation, } from "../bounded-file.js";
+import { fileIdentity, sameFileIdentity } from "../file-identity.js";
+import { createProcessLeaseDirectory, inspectProcessLease, pidIsAlive, ProcessLeaseError, processLease, processLeaseToken, removeProcessLease, tryAcquireProcessLease, } from "../process-lease.js";
+const LEGACY_LEASE_BYTES = 256;
+const sessionLeaseScopes = new WeakMap();
 export function leaseToken() {
-    return `${process.pid}:${randomUUID()}`;
+    return processLeaseToken();
 }
-export function sessionLease(id, file, token) {
+export async function createLeaseDirectory(directory, token) {
+    return createProcessLeaseDirectory(directory, token);
+}
+export async function claimLeaseDirectory(directory, token) {
+    try {
+        return await tryAcquireProcessLease(directory, token, { staleMs: 0, setupGraceMs: 1_000 });
+    }
+    catch (error) {
+        if (error instanceof ProcessLeaseError)
+            throw unsafeLease();
+        throw error;
+    }
+}
+export function leaseFromGeneration(directory, generation) {
+    return processLease(directory, generation);
+}
+export function sessionLease(id, scope, lease) {
     let closed = false;
-    return Object.freeze({
+    const owned = Object.freeze({
         id,
         assertOwned: async () => {
             if (closed)
                 throw new Error("session lease is closed");
-            const current = await readLease(file);
-            if (current !== token)
+            try {
+                await lease.assertOwned();
+            }
+            catch {
                 throw new Error("session lease is no longer owned by this process");
+            }
         },
         close: async () => {
             if (closed)
                 return;
+            const removed = await lease.release();
+            if (!removed)
+                throw new Error("session lease is no longer owned by this process");
             closed = true;
-            try {
-                await removeLease(file, token);
-            }
-            catch {
-                // A recovered, replaced, or already-closed lease is no longer ours.
-            }
         },
     });
+    sessionLeaseScopes.set(owned, { id, scope });
+    return owned;
+}
+export function sessionLeaseOwns(lease, id, scope) {
+    const owner = sessionLeaseScopes.get(lease);
+    return owner?.id === id && owner.scope === scope;
 }
-export async function leaseOwner(file) {
+export async function leaseOwner(directory, hooks = {}) {
     try {
-        const token = await readLease(file);
-        const match = /^([1-9]\d*):/.exec(token.trim());
-        if (match === null)
-            return { pid: 0, token };
-        const pid = Number(match[1]);
-        return { pid: Number.isSafeInteger(pid) ? pid : 0, token };
+        const owner = await inspectProcessLease(directory);
+        return owner === undefined
+            ? undefined
+            : { pid: owner.pid, token: owner.token, legacy: false };
     }
     catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
+        if (error instanceof ProcessLeaseError) {
+            let legacy;
+            try {
+                legacy = await legacyLeaseOwner(directory, hooks);
+            }
+            catch (legacyError) {
+                if (unsafeLegacyRace(legacyError))
+                    throw unsafeLease();
+                throw legacyError;
+            }
+            if (legacy !== undefined)
+                return legacy;
+            throw unsafeLease();
+        }
         throw error;
     }
 }
-export async function removeLease(file, token) {
-    const current = await readLease(file).catch(() => undefined);
-    if (current === token)
-        await unlink(file).catch(() => undefined);
+export async function removeLease(directory, token) {
+    try {
+        return await removeProcessLease(directory, token);
+    }
+    catch (error) {
+        if (error instanceof ProcessLeaseError)
+            throw unsafeLease();
+        throw error;
+    }
 }
-export function pidIsAlive(pid) {
-    if (!Number.isSafeInteger(pid) || pid < 1 || pid > 0x7fff_ffff)
+/** Remove a legacy fixed-file marker only while its session is exclusively owned. */
+export async function removeLegacyLeaseExclusive(file, token, owner) {
+    if (!sessionLeaseScopes.has(owner)) {
+        throw new Error("legacy lease migration requires a Jecode session lease");
+    }
+    await owner.assertOwned();
+    let before;
+    try {
+        before = await lstat(file, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.size > BigInt(LEGACY_LEASE_BYTES)) {
         return false;
+    }
     try {
-        process.kill(pid, 0);
+        const current = await readBoundedText(file, LEGACY_LEASE_BYTES, {
+            label: "legacy session lease",
+            expected: stableFileExpectation(before),
+        });
+        if (current !== token)
+            return false;
+        const after = await lstat(file, { bigint: true });
+        if (!sameFileIdentity(fileIdentity(before), fileIdentity(after)))
+            return false;
+        await owner.assertOwned();
+        await unlink(file);
         return true;
     }
     catch (error) {
-        return error.code !== "ESRCH";
+        if (unsafeLegacyRace(error))
+            return false;
+        throw error;
     }
 }
-async function readLease(file) {
-    const before = await lstat(file);
-    if (before.isSymbolicLink() || !before.isFile() || before.size > MAX_LEASE_BYTES) {
-        throw new Error("session lease is unsafe or too large");
-    }
-    const handle = await open(file, "r");
+export { pidIsAlive };
+function unsafeLease() {
+    return new Error("session lease is unsafe or too large, or invalid");
+}
+async function legacyLeaseOwner(file, hooks) {
+    let details;
     try {
-        const opened = await handle.stat();
-        if (!opened.isFile() || opened.size > MAX_LEASE_BYTES ||
-            opened.dev !== before.dev || opened.ino !== before.ino)
-            throw new Error("session lease changed while opening");
-        const bytes = Buffer.alloc(MAX_LEASE_BYTES + 1);
-        const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
-        if (bytesRead > MAX_LEASE_BYTES)
-            throw new Error("session lease is too large");
-        return bytes.subarray(0, bytesRead).toString("utf8");
+        details = await lstat(file, { bigint: true });
     }
-    finally {
-        await handle.close();
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (details.isSymbolicLink() || !details.isFile() || details.size > BigInt(LEGACY_LEASE_BYTES)) {
+        return undefined;
     }
+    await hooks.afterLegacyStat?.();
+    const token = await readBoundedText(file, LEGACY_LEASE_BYTES, {
+        label: "legacy session lease",
+        expected: stableFileExpectation(details),
+    });
+    const match = /^([1-9]\d*):/.exec(token.trim());
+    const pid = match === null ? 0 : Number(match[1]);
+    return {
+        pid: Number.isSafeInteger(pid) && pid <= 0x7fff_ffff ? pid : 0,
+        token,
+        legacy: true,
+    };
+}
+function unsafeLegacyRace(error) {
+    if (error instanceof BoundedFileError)
+        return true;
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" ||
+        code === "EISDIR" || code === "ENXIO";
 }

package/dist/sessions/runtime.js

@@ -3,36 +3,38 @@
 // One logical conversation keeps one stable session id across every resume.
 // New turns advance that session's tree head; /new is the boundary that starts
 // another durable session.
-import { DurableSessionStore } from "./store.js";
+import { DurableSessionStore, reserveSessionId } from "./store.js";
 export class SessionPersistence {
     #store;
     #sessionId;
+    #conversationId;
     #lease;
     #snapshot;
     #failure;
-    constructor(store, sessionId, lease, snapshot) {
+    constructor(store, sessionId, lease, snapshot, conversationId = sessionId ?? reserveSessionId()) {
         this.#store = store;
         this.#sessionId = sessionId;
+        this.#conversationId = conversationId;
         this.#lease = lease;
         this.#snapshot = snapshot;
     }
     static fresh(store) {
-        return new SessionPersistence(store, null);
+        return new SessionPersistence(store, null, undefined, undefined, reserveSessionId());
     }
     static async resume(store, id) {
         const lease = await store.claim(id);
         try {
-            const snapshot = await store.load(id);
+            const snapshot = await store.load(id, lease);
             const conversation = snapshot.conversation.latestResumable();
             if (conversation === undefined)
                 throw new Error("session has no resumable turn");
             return Object.freeze({
                 conversation,
-                persistence: new SessionPersistence(store, id, lease, snapshot),
+                persistence: new SessionPersistence(store, id, lease, snapshot, id),
             });
         }
         catch (error) {
-            await lease.close();
+            await lease.close().catch(() => undefined);
             throw error;
         }
     }
@@ -45,12 +47,16 @@ export class SessionPersistence {
     get sessionId() {
         return this.#sessionId;
     }
+    /** Reserved before publication so provider cache identity survives resume. */
+    get conversationId() {
+        return this.#conversationId;
+    }
     async checkpoint(conversation) {
         if (this.#failure !== undefined)
             throw this.#failure;
         try {
             if (this.#sessionId === null) {
-                const published = await this.#store.publish(conversation, true);
+                const published = await this.#store.publish(conversation, true, this.#conversationId);
                 this.#lease = published.lease;
                 this.#sessionId = published.meta.id;
                 this.#snapshot = published;
@@ -60,7 +66,7 @@ export class SessionPersistence {
                 throw new Error("session persistence has no verified owner snapshot");
             }
             await this.#lease.assertOwned();
-            this.#snapshot = await this.#store.checkpoint(this.#snapshot, conversation);
+            this.#snapshot = await this.#store.checkpoint(this.#snapshot, conversation, this.#lease);
         }
         catch (error) {
             this.#failure = error;
@@ -71,6 +77,7 @@ export class SessionPersistence {
         await this.#lease?.close();
         this.#lease = undefined;
         this.#sessionId = null;
+        this.#conversationId = reserveSessionId();
         this.#snapshot = undefined;
         this.#failure = undefined;
     }