@typeberry/lib 0.9.0-3f2c45b → 0.9.0-959889e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeberry/lib",
-  "version": "0.9.0-3f2c45b",
+  "version": "0.9.0-959889e",
   "description": "Typeberry Library",
   "main": "./bin/lib/index.js",
   "types": "./bin/lib/index.d.ts",

package/packages/core/utils/index.d.ts

@@ -18,5 +18,6 @@ export * from "./opaque.js";
 export { name, version } from "./package.js";
 export * from "./result.js";
 export * from "./safe-alloc-uint8array.js";
+export * from "./shutdown.js";
 export * from "./test.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC"}

package/packages/core/utils/index.js

@@ -18,4 +18,5 @@ export * from "./opaque.js";
 export { name, version } from "./package.js";
 export * from "./result.js";
 export * from "./safe-alloc-uint8array.js";
+export * from "./shutdown.js";
 export * from "./test.js";

package/packages/core/utils/shutdown.d.ts

@@ -0,0 +1,18 @@
+export type Closer = () => Promise<void>;
+export interface ShutdownLogger {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+}
+export interface ShutdownOptions {
+    /** Max ms allowed for `close` before forced exit(1). Default 10_000. */
+    timeoutMs?: number;
+    /** Signals to listen for. Default ["SIGTERM", "SIGINT"]. */
+    signals?: readonly NodeJS.Signals[];
+    /** Logger; defaults to a no-op logger. */
+    log?: ShutdownLogger;
+    /** Test hook used instead of process.exit. */
+    exit?: (code: number) => never;
+}
+/** Returns an uninstall function (used by tests). */
+export declare function installShutdownHandlers(close: Closer, options?: ShutdownOptions): () => void;
+//# sourceMappingURL=shutdown.d.ts.map

package/packages/core/utils/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/shutdown.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,MAAM,CAAC,OAAO,EAAE,CAAC;IACpC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AASD,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,IAAI,CAiFhG"}

package/packages/core/utils/shutdown.js

@@ -0,0 +1,80 @@
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+const DEFAULT_TIMEOUT_MS = 10_000;
+function isNodeRuntime() {
+    return typeof process !== "undefined" && typeof process.on === "function" && typeof process.exit === "function";
+}
+/** Returns an uninstall function (used by tests). */
+export function installShutdownHandlers(close, options = {}) {
+    if (!isNodeRuntime()) {
+        return () => { };
+    }
+    const signals = options.signals ?? DEFAULT_SIGNALS;
+    const exit = (options.exit ?? process.exit);
+    const log = options.log;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let state = "idle";
+    const forceExit = (signal) => {
+        log?.error(`Received ${signal} during shutdown, forcing exit.`);
+        try {
+            exit(1);
+        }
+        catch {
+            // test-time exit throws; swallow.
+        }
+    };
+    const handler = (signal) => {
+        if (state === "closing" || state === "done") {
+            forceExit(signal);
+            return;
+        }
+        state = "closing";
+        log?.info(`Received ${signal}, draining...`);
+        void (async () => {
+            const TIMED_OUT = Symbol("timed-out");
+            let timeoutHandle;
+            const timeoutPromise = new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+            });
+            timeoutHandle?.unref?.();
+            let code = 0;
+            try {
+                const outcome = await Promise.race([
+                    close().then(() => "ok", (e) => ({ err: e })),
+                    timeoutPromise,
+                ]);
+                if (outcome === TIMED_OUT) {
+                    code = 1;
+                    log?.error(`Shutdown cleanup exceeded ${timeoutMs}ms timeout, forcing exit.`);
+                }
+                else if (typeof outcome === "object" && "err" in outcome) {
+                    code = 1;
+                    const e = outcome.err;
+                    log?.error(`Shutdown close threw: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
+                }
+                else {
+                    log?.info("Shutdown complete.");
+                }
+            }
+            finally {
+                clearTimeout(timeoutHandle);
+                state = "done";
+            }
+            try {
+                exit(code);
+            }
+            catch {
+                // test-time exit throws; swallow.
+            }
+        })();
+    };
+    // Node passes the signal name to the listener, so a single handler works
+    // for every signal.
+    for (const sig of signals) {
+        process.on(sig, handler);
+    }
+    return () => {
+        for (const sig of signals) {
+            process.off(sig, handler);
+        }
+    };
+}

package/packages/core/utils/shutdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shutdown.test.d.ts.map

package/packages/core/utils/shutdown.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/shutdown.test.ts"],"names":[],"mappings":""}

package/packages/core/utils/shutdown.test.js

@@ -0,0 +1,155 @@
+import assert from "node:assert";
+import { afterEach, describe, it } from "node:test";
+import { installShutdownHandlers } from "./shutdown.js";
+function makeExitRecorder() {
+    let resolveExited;
+    const exited = new Promise((resolve) => {
+        resolveExited = resolve;
+    });
+    const recorder = {
+        exitCode: null,
+        exited,
+        exit: ((code) => {
+            recorder.exitCode = code;
+            resolveExited();
+            // Satisfy `never` and abort the calling promise chain.
+            throw new Error(`__test_exit_${code}`);
+        }),
+    };
+    return recorder;
+}
+const silentLog = { info: () => { }, error: () => { } };
+describe("utils::installShutdownHandlers", () => {
+    const uninstallers = [];
+    afterEach(() => {
+        while (uninstallers.length > 0) {
+            uninstallers.pop()?.();
+        }
+    });
+    it("calls close and exits 0 on first SIGTERM", async () => {
+        const exitRec = makeExitRecorder();
+        let closeCalled = false;
+        uninstallers.push(installShutdownHandlers(async () => {
+            closeCalled = true;
+        }, { exit: exitRec.exit, log: silentLog }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(closeCalled, true);
+        assert.strictEqual(exitRec.exitCode, 0);
+    });
+    it("exits with code 1 when cleanup exceeds timeoutMs", async () => {
+        const exitRec = makeExitRecorder();
+        let closeStarted = false;
+        let errorLogged = null;
+        let releaseClose;
+        const closeReleased = new Promise((resolve) => {
+            releaseClose = resolve;
+        });
+        uninstallers.push(installShutdownHandlers(async () => {
+            closeStarted = true;
+            await closeReleased;
+        }, {
+            exit: exitRec.exit,
+            timeoutMs: 5,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(closeStarted, true, "close should have been invoked");
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected timeout to be logged");
+        assert.match(errorLogged, /timeout|exceed/i);
+        // Allow the in-flight close promise to settle so the test doesn't leak.
+        releaseClose();
+    });
+    it("forces exit 1 when a second signal arrives during cleanup", async () => {
+        const exitRec = makeExitRecorder();
+        let releaseClose;
+        const closeReleased = new Promise((resolve) => {
+            releaseClose = resolve;
+        });
+        let errorLogged = null;
+        uninstallers.push(installShutdownHandlers(async () => {
+            await closeReleased;
+        }, {
+            // Large timeout so this test can't pass via the timeout path.
+            timeoutMs: 60_000,
+            exit: exitRec.exit,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await new Promise((resolve) => setImmediate(resolve));
+        process.emit("SIGINT", "SIGINT");
+        await exitRec.exited;
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected force-exit message to be logged");
+        assert.match(errorLogged, /SIGINT/);
+        releaseClose();
+    });
+    it("does nothing after uninstall", async () => {
+        const exitRec = makeExitRecorder();
+        let closeCalled = false;
+        const uninstall = installShutdownHandlers(async () => {
+            closeCalled = true;
+        }, { exit: exitRec.exit, log: silentLog });
+        uninstall();
+        process.emit("SIGTERM", "SIGTERM");
+        // Give any (incorrectly registered) handler a tick to fire.
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.strictEqual(closeCalled, false);
+        assert.strictEqual(exitRec.exitCode, null);
+    });
+    it("is a no-op in non-Node runtimes", async () => {
+        const originalOn = process.on;
+        const originalExit = process.exit;
+        // Hide the Node-specific surface so installShutdownHandlers takes the no-op branch.
+        process.on = undefined;
+        process.exit = undefined;
+        try {
+            const exitRec = makeExitRecorder();
+            let closeCalled = false;
+            const uninstall = installShutdownHandlers(async () => {
+                closeCalled = true;
+            }, { exit: exitRec.exit, log: silentLog });
+            // The uninstall must be callable without throwing even in the no-op path.
+            uninstall();
+            assert.strictEqual(typeof uninstall, "function");
+            assert.strictEqual(closeCalled, false);
+            assert.strictEqual(exitRec.exitCode, null);
+        }
+        finally {
+            process.on = originalOn;
+            process.exit = originalExit;
+        }
+    });
+    it("exits with code 1 when close rejects", async () => {
+        const exitRec = makeExitRecorder();
+        let errorLogged = null;
+        uninstallers.push(installShutdownHandlers(async () => {
+            throw new Error("boom");
+        }, {
+            exit: exitRec.exit,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected error to be logged");
+        assert.match(errorLogged, /boom/);
+    });
+});

package/packages/extensions/ipc/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../packages/extensions/ipc/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAIrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,4CAA4C;AAC5C,qBAAa,SAAS;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ3C,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM;IAIzB,OAAO;IAEP,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI3B,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,UAAU,cAiFhG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../packages/extensions/ipc/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAIrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,4CAA4C;AAC5C,qBAAa,SAAS;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ3C,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM;IAIzB,OAAO;IAEP,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI3B,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,UAAU,cAuFhG"}

package/packages/extensions/ipc/server.js

@@ -87,6 +87,13 @@ export function startIpcServer(name, newMessageHandler) {
         controller.abort();
         // unrefing
         server.unref();
+        // Windows named pipes are cleaned up by the OS; Unix sockets are not.
+        if (!isWindows) {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
+        }
     };
 }
 /**

package/packages/jam/node/main-fuzz.d.ts

@@ -1,5 +1,6 @@
 import { type FuzzVersion } from "#@typeberry/ext-ipc";
 import { v1 as fuzzV1 } from "#@typeberry/fuzz-proto";
+import { type Closer } from "#@typeberry/utils";
 import type { JamConfig } from "./jam-config.js";
 export type FuzzConfig = {
     version: FuzzVersion;
@@ -24,5 +25,7 @@ export declare function getFuzzDetails(): {
     nodeVersion: fuzzV1.Version;
     gpVersion: fuzzV1.Version;
 };
-export declare function mainFuzz(fuzzConfig: FuzzConfig, withRelPath: (v: string) => string): Promise<() => void>;
+export declare function mainFuzz(fuzzConfig: FuzzConfig, withRelPath: (v: string) => string): Promise<{
+    close: Closer;
+}>;
 //# sourceMappingURL=main-fuzz.d.ts.map

package/packages/jam/node/main-fuzz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAoBF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,uBAuJxF"}
+{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAIrD,OAAO,EAAE,KAAK,MAAM,EAAoC,MAAM,kBAAkB,CAAC;AAGjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAoBF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsKrH"}

package/packages/jam/node/main-fuzz.js

@@ -75,6 +75,9 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
     // every reset, because opening it is the slow part. Only the in-memory blocks
     // and leaf sets are rebuilt for each vector. fjall-hybrid only.
     let fjallSession = null;
+    // Set when close() starts. Guards resetState so a fuzz command arriving
+    // mid-shutdown can't build a fresh node that close() then orphans.
+    let isClosing = false;
     const chainSpec = getChainSpec(config.node.flavor);
     const closeFuzzTarget = startFuzzTarget(fuzzConfig.version, fuzzConfig.socket, {
         ...getFuzzDetails(),
@@ -99,6 +102,9 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
             return runningNode.getStateEntries(hash);
         },
         resetState: async (header, state, ancestry) => {
+            if (isClosing) {
+                return Bytes.zero(HASH_SIZE).asOpaque();
+            }
             if (runningNode !== null) {
                 const finish = runningNode.close();
                 runningNode = null;
@@ -175,20 +181,29 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
             return await runningNode.getBestStateRootHash();
         },
     });
-    return () => {
-        closeFuzzTarget();
-        // Close the reused fjall values session (if any) before wiping its files, so
-        // the keyspace handle is released first.
-        const closed = fjallSession?.close() ?? Promise.resolve();
-        fjallSession = null;
-        if (fuzzDbBase !== undefined) {
-            // best-effort cleanup on shutdown; ignore failures (dir may already be gone).
-            closed
-                .catch(() => { })
-                .finally(() => {
-                wipeFuzzDb(fuzzDbBase).catch(() => { });
-            });
-        }
+    return {
+        close: async () => {
+            isClosing = true;
+            // Stop accepting connections + unlink the socket.
+            closeFuzzTarget();
+            // Drain the active session (flush + close DB). Swallow errors so a
+            // failing close still lets the process exit 0; the db is wiped next.
+            // The node references the shared fjall session, so it must close first.
+            if (runningNode !== null) {
+                const node = runningNode;
+                runningNode = null;
+                await node.close().catch((e) => logger.error `Error closing fuzz node: ${e}`);
+            }
+            // Release the reused fjall values keyspace before wiping its files.
+            if (fjallSession !== null) {
+                const session = fjallSession;
+                fjallSession = null;
+                await session.close().catch((e) => logger.error `Error closing fjall session: ${e}`);
+            }
+            if (fuzzDbBase !== undefined) {
+                await wipeFuzzDb(fuzzDbBase).catch(() => { });
+            }
+        },
     };
 }
 function isValidStateBackend(val) {