@rhinestone/service-sdk 0.2.16 → 0.2.17

package/README.md

@@ -2,7 +2,7 @@
 
 Shared TypeScript utilities for Rhinestone backend services — the pieces every service
 needs and none of them should reimplement: OpenTelemetry setup and helpers, chain-aware gas
-fee estimation, and BigInt-safe JSON serialization.
+fee estimation, graceful-shutdown plumbing, and BigInt-safe JSON serialization.
 
 Published to npm and consumed by `orchestrator`, `relayer`, `deposit-service-processor`,
 `route-stats`, `back-office` (api), and `1auth` (passkey, recovery-signer).
@@ -25,6 +25,7 @@ bun add @rhinestone/service-sdk
 |---|---|
 | `@rhinestone/service-sdk` | Re-exports `./serialization` only |
 | `@rhinestone/service-sdk/chains` | Chain-aware gas fee estimation |
+| `@rhinestone/service-sdk/lifecycle` | Termination signals, crashes and explicit aborts as one channel |
 | `@rhinestone/service-sdk/opentelemetry` | SDK setup, tracing/metrics helpers, propagation, integrations |
 | `@rhinestone/service-sdk/serialization` | BigInt-safe JSON serialization |
 
@@ -105,6 +106,50 @@ from the value alone.
 
 ---
 
+## Lifecycle
+
+```ts
+import {
+  installTerminationHandlers,
+  terminationExitCode,
+  describeReason,
+} from '@rhinestone/service-sdk/lifecycle'
+
+const termination = installTerminationHandlers()
+
+const reason = await Promise.race([serve(termination), termination.waitForTermination()])
+
+logger.info(`shutting down: ${describeReason(reason)}`)
+await teardownInOrder()
+process.exit(terminationExitCode(reason))
+```
+
+Folds every way a process can be asked to stop into one channel: `SIGTERM` / `SIGINT`, an
+uncaught exception, an unhandled rejection, and an explicit `terminate(reason)` from code
+that found a broken invariant. `waitForTermination()` resolves once with a discriminated
+`TerminationReason`, so the caller can log it and pick an exit code instead of every call
+site inventing its own.
+
+**The first reason wins; later ones are dropped.** That is the point rather than a detail:
+sockets closing during a shutdown routinely orphan promises, and those rejections must not
+restart the shutdown or flip a clean stop to a failure.
+
+`isTerminating()` is the same state as a synchronous boolean, for the callers that can't
+await — readiness probes returning 503 the instant a signal lands, admission gates refusing
+new work while in-flight work drains.
+
+Two things to know:
+
+- **Registering an `uncaughtException` / `unhandledRejection` listener stops Node exiting on
+  either.** The caller *must* exit once teardown is done, or a crashed process lingers.
+- Nothing is registered at import time, and each install is independent. The install call is
+  the only thing that touches `process`, and `dispose()` removes exactly what it added, so
+  tests get a fresh one and own its disposal.
+
+This module logs nothing itself; reporting is the owner's job, once the promise resolves.
+
+---
+
 ## OpenTelemetry
 
 ### Setup

package/dist/lifecycle.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Process termination as one observable event.
+ *
+ * A shutdown needs two different things, and a bare promise only gives the
+ * first: an *ordered* teardown (release this, then close that), and an
+ * *immediate* answer to "should I still take on new work?" for readiness probes
+ * and admission gates. Handing those callers a promise means each of them keeps
+ * its own boolean in sync with it, which is the bug this shape avoids.
+ *
+ * Every way a process can be asked to stop lands in the same channel:
+ *
+ * - an external signal — SIGTERM from an orchestrator, SIGINT from a terminal
+ * - an uncaught exception or an unhandled rejection
+ * - an explicit `terminate()` from code that found a broken invariant
+ *
+ * The first reason wins; anything after it is dropped. That is what keeps a
+ * crash *during* shutdown from restarting the shutdown or changing its exit
+ * code — orphaned promises rejecting as sockets close is normal, and must not
+ * turn a clean stop into a failed one.
+ *
+ * Nothing is registered at import time. `installTerminationHandlers` is the only
+ * thing that touches `process`, and `dispose()` undoes exactly what it added.
+ */
+/** Why the process was asked to stop. */
+export type TerminationReason = {
+    kind: 'signal';
+    signal: NodeJS.Signals;
+} | {
+    kind: 'uncaughtException';
+    error: Error;
+} | {
+    kind: 'unhandledRejection';
+    reason: unknown;
+} | {
+    kind: 'explicit';
+    reason: string | Error | object;
+};
+export interface Termination {
+    /**
+     * Resolves once, with whatever asked the process to stop. Never rejects, and
+     * safe to await from several places; awaiting after the fact returns the
+     * reason that already settled. Reporting the reason is the owner's job — this
+     * module logs nothing.
+     */
+    waitForTermination(): Promise<TerminationReason>;
+    /**
+     * True from the instant a reason arrives. For readiness gates and admission
+     * checks that must answer synchronously, long before teardown finishes.
+     */
+    isTerminating(): boolean;
+    /**
+     * Ask the process to stop: an invariant broke and it must not keep running.
+     * The reason is carried through to the awaiting caller — an `Error` where
+     * there is one, or a string / context object where the caller has facts
+     * rather than a throw. First caller wins.
+     */
+    terminate(reason: string | Error | object): void;
+    /** Remove the process listeners this install added. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Register the process listeners and return the channel they feed.
+ *
+ * Each call is independent: it installs its own listeners and owns its own
+ * reason, so two installs in one process both fire. That is deliberate — tests
+ * want a fresh one — and it means the caller is responsible for `dispose()`.
+ *
+ * Registering an `uncaughtException` / `unhandledRejection` listener stops Node
+ * from exiting on either, so **the caller must exit itself** once teardown is
+ * done. Use `terminationExitCode` for the code.
+ */
+export declare function installTerminationHandlers(): Termination;
+/**
+ * The exit code to leave with: 0 for a signal, 1 for everything else.
+ *
+ * A handled SIGTERM means the process did what it was asked, so a clean 0 —
+ * exiting non-zero there makes an orderly rollout look like a failed one.
+ */
+export declare function terminationExitCode(reason: TerminationReason): number;
+/** One-line description of a reason, for the owner's shutdown log. */
+export declare function describeReason(reason: TerminationReason): string;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,yCAAyC;AACzC,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;CAAE,CAAA;AAEzD,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAChD;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAA;IACxB;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IAChD,mEAAmE;IACnE,OAAO,IAAI,IAAI,CAAA;CAChB;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,IAAI,WAAW,CA2CxD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAErE;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAWhE"}

package/dist/lifecycle.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installTerminationHandlers = installTerminationHandlers;
+exports.terminationExitCode = terminationExitCode;
+exports.describeReason = describeReason;
+const serialization_1 = require("./serialization");
+/** SIGTERM from orchestrators, SIGINT from terminals. */
+const SIGNALS = ['SIGTERM', 'SIGINT'];
+/**
+ * Register the process listeners and return the channel they feed.
+ *
+ * Each call is independent: it installs its own listeners and owns its own
+ * reason, so two installs in one process both fire. That is deliberate — tests
+ * want a fresh one — and it means the caller is responsible for `dispose()`.
+ *
+ * Registering an `uncaughtException` / `unhandledRejection` listener stops Node
+ * from exiting on either, so **the caller must exit itself** once teardown is
+ * done. Use `terminationExitCode` for the code.
+ */
+function installTerminationHandlers() {
+    let settledReason;
+    let resolve;
+    const reasonPromise = new Promise((r) => {
+        resolve = r;
+    });
+    const accept = (next) => {
+        if (settledReason !== undefined)
+            return;
+        settledReason = next;
+        resolve(next);
+    };
+    const onSignal = (signal) => {
+        accept({ kind: 'signal', signal });
+    };
+    const onUncaughtException = (error) => {
+        accept({ kind: 'uncaughtException', error });
+    };
+    const onUnhandledRejection = (reason) => {
+        accept({ kind: 'unhandledRejection', reason });
+    };
+    for (const signal of SIGNALS) {
+        process.on(signal, onSignal);
+    }
+    process.on('uncaughtException', onUncaughtException);
+    process.on('unhandledRejection', onUnhandledRejection);
+    return {
+        waitForTermination: () => reasonPromise,
+        isTerminating: () => settledReason !== undefined,
+        terminate: (reason) => {
+            accept({ kind: 'explicit', reason });
+        },
+        dispose: () => {
+            for (const signal of SIGNALS) {
+                process.off(signal, onSignal);
+            }
+            process.off('uncaughtException', onUncaughtException);
+            process.off('unhandledRejection', onUnhandledRejection);
+        },
+    };
+}
+/**
+ * The exit code to leave with: 0 for a signal, 1 for everything else.
+ *
+ * A handled SIGTERM means the process did what it was asked, so a clean 0 —
+ * exiting non-zero there makes an orderly rollout look like a failed one.
+ */
+function terminationExitCode(reason) {
+    return reason.kind === 'signal' ? 0 : 1;
+}
+/** One-line description of a reason, for the owner's shutdown log. */
+function describeReason(reason) {
+    switch (reason.kind) {
+        case 'signal':
+            return `signal ${reason.signal}`;
+        case 'uncaughtException':
+            return `uncaught exception: ${formatValue(reason.error)}`;
+        case 'unhandledRejection':
+            return `unhandled rejection: ${formatValue(reason.reason)}`;
+        case 'explicit':
+            return `explicit termination: ${formatValue(reason.reason)}`;
+    }
+}
+function formatValue(value) {
+    if (value instanceof Error)
+        return value.stack ?? value.message;
+    if (typeof value === 'string')
+        return value;
+    try {
+        // Guards bigints and circular references, both plausible in a context
+        // object assembled at the point an invariant broke.
+        return (0, serialization_1.stringifyBigIntFields)(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinestone/service-sdk",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Shared SDK for Rhinestone services",
   "author": {
     "name": "Rhinestone",
@@ -18,6 +18,7 @@
   "exports": {
     ".": "./dist/index.js",
     "./chains": "./dist/chains.js",
+    "./lifecycle": "./dist/lifecycle.js",
     "./opentelemetry": "./dist/opentelemetry/index.js",
     "./serialization": "./dist/serialization.js"
   },
@@ -26,6 +27,9 @@
       "chains": [
         "dist/chains.d.ts"
       ],
+      "lifecycle": [
+        "dist/lifecycle.d.ts"
+      ],
       "opentelemetry": [
         "dist/opentelemetry/index.d.ts"
       ],