stitchkit 0.49.0 → 0.49.1

package/dist/{index-fjfzsq6y.js → index-z992nfbx.js}

@@ -1409,6 +1409,7 @@ var ShutdownStateSchema = z.enum([
 ]);
 var ShutdownOptionsSchema = z.object({
   gracePeriodMs: z.number().int().nonnegative().default(30000),
+  forceTimeoutMs: z.number().int().nonnegative().default(5000),
   retryAfterSeconds: z.number().int().nonnegative().default(5),
   signal: z.custom((value) => typeof value === "object" && value !== null && ("aborted" in value) && ("addEventListener" in value), "Expected an AbortSignal").optional()
 });
@@ -1461,6 +1462,18 @@ function untilAbort(signal) {
     return Promise.resolve();
   return new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
 }
+function withTimeout(promise, timeoutMs, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+    promise.then((value) => {
+      clearTimeout(timer);
+      resolve(value);
+    }, (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
 function createServerLifecycle(getAdapter) {
   let state = "running";
   let acceptedRequests = 0;
@@ -1504,6 +1517,7 @@ function createServerLifecycle(getAdapter) {
     shutdownPromise = new Promise((resolve, reject) => {
       const phaseAbort = new AbortController;
       let forcedReason;
+      let phaseError;
       const force = (reason) => {
         if (forcedReason)
           return;
@@ -1520,28 +1534,21 @@ function createServerLifecycle(getAdapter) {
         parsed.signal?.removeEventListener("abort", onExternalAbort);
       };
       (async () => {
-        await waitForZero(() => pendingApplicationRequests, phaseAbort.signal);
-        if (!forcedReason) {
-          state = "closing-realtime";
-          const closeRealtime = adapter.closeRealtime();
-          await Promise.race([
-            closeRealtime.catch((error) => {
-              if (!forcedReason)
-                throw error;
-            }),
-            untilAbort(phaseAbort.signal)
-          ]);
-        }
-        if (!forcedReason) {
-          state = "stopping-runtime";
-          const stopGracefully = adapter.stopGracefully();
-          await Promise.race([
-            stopGracefully.catch((error) => {
-              if (!forcedReason)
-                throw error;
-            }),
-            untilAbort(phaseAbort.signal)
-          ]);
+        try {
+          await waitForZero(() => pendingApplicationRequests, phaseAbort.signal);
+          if (!forcedReason) {
+            state = "closing-realtime";
+            await Promise.race([adapter.closeRealtime(), untilAbort(phaseAbort.signal)]);
+          }
+          if (!forcedReason) {
+            state = "stopping-runtime";
+            await Promise.race([adapter.stopGracefully(), untilAbort(phaseAbort.signal)]);
+          }
+        } catch (error) {
+          if (!forcedReason) {
+            phaseError = error;
+            force("error");
+          }
         }
         let pendingRequestsAtForce = 0;
         let pendingWebSocketsAtForce = 0;
@@ -1549,8 +1556,24 @@ function createServerLifecycle(getAdapter) {
           state = "stopping-runtime";
           pendingRequestsAtForce = adapter.pendingRequests();
           pendingWebSocketsAtForce = adapter.pendingWebSockets();
-          await adapter.forceStop();
-          state = "forced";
+          let forceError;
+          let forceFailed = false;
+          try {
+            await withTimeout(adapter.forceStop(), parsed.forceTimeoutMs, `[stitchkit] forced shutdown did not complete within ${parsed.forceTimeoutMs}ms`);
+          } catch (error) {
+            forceFailed = true;
+            forceError = error;
+          } finally {
+            state = "forced";
+          }
+          if (forcedReason === "error") {
+            if (forceFailed) {
+              throw new AggregateError([phaseError, forceError], "[stitchkit] graceful shutdown failed and forced cleanup also failed", { cause: phaseError });
+            }
+            throw phaseError;
+          }
+          if (forceFailed)
+            throw forceError;
         } else {
           state = "clean";
         }

package/dist/node.js

@@ -11,7 +11,7 @@ import {
   createSocketIOServer,
   implement,
   implementRegistry
-} from "./index-fjfzsq6y.js";
+} from "./index-z992nfbx.js";
 import"./index-r1qp4rve.js";
 import {
   AppError,

package/dist/server/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAE7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqIrE"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/server/bun.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;AACtD,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,KAAK,oBAAoB,GAAG,GAAG,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC1D,KAAK,qBAAqB,GAAG,eAAe,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,eAAe,EACf,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,CAChF,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB,EAAE,mBAAmB;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,iGAAiG;IACjG,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;AAE7D,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAyIrE"}

package/dist/server/index.js

@@ -16,7 +16,7 @@ import {
   parseMultipart,
   socketIoLane,
   webSocketLane
-} from "../index-fjfzsq6y.js";
+} from "../index-z992nfbx.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -83,7 +83,20 @@ function createServer(config) {
   const socketRoutePrefix = socket?.route.path.replace(/\*socketPath$/, "");
   const websocket = configuredWebSocket ?? socket?.websocket;
   const openSockets = new Set;
+  const socketDrainWaiters = new Set;
   let hadWebSockets = false;
+  const resolveSocketDrain = () => {
+    if (openSockets.size !== 0)
+      return;
+    for (const resolve of socketDrainWaiters)
+      resolve();
+    socketDrainWaiters.clear();
+  };
+  const waitForSocketDrain = () => {
+    if (openSockets.size === 0)
+      return Promise.resolve();
+    return new Promise((resolve) => socketDrainWaiters.add(resolve));
+  };
   const trackedWebSocket = websocket ? {
     ...websocket,
     open(ws) {
@@ -93,6 +106,7 @@ function createServer(config) {
     },
     close(ws, code, reason) {
       openSockets.delete(ws);
+      resolveSocketDrain();
       websocket.close?.(ws, code, reason);
     }
   } : undefined;
@@ -110,21 +124,7 @@ function createServer(config) {
       const logicalClose = socket?.close();
       for (const ws of openSockets)
         ws.close(1001, "Server shutting down");
-      await Promise.all([
-        logicalClose,
-        new Promise((resolve) => {
-          if (openSockets.size === 0) {
-            resolve();
-            return;
-          }
-          const timer = setInterval(() => {
-            if (openSockets.size === 0) {
-              clearInterval(timer);
-              resolve();
-            }
-          }, 5);
-        })
-      ]);
+      await Promise.all([logicalClose, waitForSocketDrain()]);
     },
     async stopGracefully() {
       await new Promise((resolve) => setTimeout(resolve, 0));
@@ -142,9 +142,10 @@ function createServer(config) {
       await server2.stop(false);
     },
     async forceStop() {
-      for (const ws of openSockets)
+      const logicalClose = socket?.close();
+      const physicalClose = waitForSocketDrain();
+      for (const ws of [...openSockets])
         ws.terminate();
-      openSockets.clear();
       const stopping = requireRuntime().stop(true);
       if (!hadWebSockets)
         await stopping;
@@ -152,6 +153,7 @@ function createServer(config) {
         stopping.catch(() => {
           return;
         });
+      await Promise.all([logicalClose, physicalClose]);
     }
   };
   const lifecycle = createServerLifecycle(() => adapter);

package/dist/server/shutdown.d.ts

@@ -11,6 +11,7 @@ export declare const ShutdownStateSchema: z.ZodEnum<{
 export type ShutdownState = z.infer<typeof ShutdownStateSchema>;
 export declare const ShutdownOptionsSchema: z.ZodObject<{
     gracePeriodMs: z.ZodDefault<z.ZodNumber>;
+    forceTimeoutMs: z.ZodDefault<z.ZodNumber>;
     retryAfterSeconds: z.ZodDefault<z.ZodNumber>;
     signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
 }, z.core.$strip>;

package/dist/server/shutdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/server/shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB;;;;iBAahC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB,CAAC,QAAQ;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,eAAe,IAAI,MAAM,CAAC;IAC1B,iBAAiB,IAAI,MAAM,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,UAAU,eAAe;IACvB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9D;AAqCD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,eAAe,GAAG,eAAe,CA8HxF"}
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/server/shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,eAAO,MAAM,mBAAmB;;;;;;;EAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,qBAAqB;;;;;iBAchC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB,CAAC,QAAQ;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,eAAe,IAAI,MAAM,CAAC;IAC1B,iBAAiB,IAAI,MAAM,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,UAAU,eAAe;IACvB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC9D;AAqDD,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,eAAe,GAAG,eAAe,CAiJxF"}

package/dist/server/websocket.d.ts

@@ -66,7 +66,7 @@ export declare function webSocketLane<TData>(lane: WebSocketLane<TData>): Compos
  *   [webSocketLane({ match: isPcmSocket, handlers: pcmHandlers }), socketIoLane(socket.websocket)],
  *   { maxPayloadLength: 16 * 1024 * 1024 },
  * )
- * createServer({ websocket: ws, rawRoutes: [socket.route, pcmUpgradeRoute] })
+ * createServer({ socket, websocket: ws, rawRoutes: [pcmUpgradeRoute] })
  * ```
  */
 export declare function composeWebSocketHandlers(lanes: ComposedLane[], config?: WebSocketComposeConfig): WebSocketHandler<unknown>;

package/llms-full.txt

@@ -762,19 +762,24 @@ const server = createServer({ services, socket })
 
 const result = await server.shutdown({
   gracePeriodMs: 30_000,
+  forceTimeoutMs: 5_000,
   retryAfterSeconds: 5,
   signal: shutdownController.signal,
 })
 ```
 
-The first call closes HTTP and Socket.IO admission, drains accepted application
-requests, closes realtime transports and stops the runtime within one total
-budget. Repeated calls return the same Promise; the first options win. New
+The first call closes HTTP and Socket.IO admission, then gives the complete
+graceful request/realtime/runtime chain one `gracePeriodMs` budget. If that
+budget or the external signal forces destructive teardown, `forceTimeoutMs`
+bounds physical completion separately. Repeated calls return the same Promise;
+the first options win. New
 ordinary HTTP work receives `503`, `Retry-After` and `Connection: close` outside
 `wrapFetch`. `result.outcome` is `clean` or `forced`; a forced result preserves
 the pending snapshot and reason while final pending counters describe the
-post-close transport state. `runtime` is a diagnostics escape hatch, not a
-second canonical stop path.
+post-close transport state. A graceful phase error still runs forced cleanup and
+then rejects with the original error; a forced transport that cannot confirm
+completion before `forceTimeoutMs` rejects instead of reporting a false zero.
+`runtime` is a diagnostics escape hatch, not a second canonical stop path.
 
 ### Trusted HTTPS in development
 
@@ -4643,7 +4648,11 @@ function shutdown() {
     force.abort() // a later signal shortens the same shutdown, not a second chain
     return closing
   }
-  closing = server.shutdown({ gracePeriodMs: 30_000, signal: force.signal }).then(async result => {
+  closing = server.shutdown({
+    gracePeriodMs: 30_000,
+    forceTimeoutMs: 5_000,
+    signal: force.signal,
+  }).then(async result => {
     await mcp.close()
     await prisma.$disconnect()
     console.log(result)
@@ -6025,7 +6034,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `BunServerConfig` | _type_ | config for `createServer` (Bun) |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |
-| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | one grace budget, retry hint and optional external abort signal |
+| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | one graceful budget, bounded forced-completion timeout, retry hint and optional external abort signal |
 | `ShutdownStatusSchema` / `ShutdownStatus` | schema / _type_ | live state and request/WebSocket counters |
 | `ShutdownResultSchema` / `ShutdownResult` | schema / _type_ | clean/forced result with final counters and at-force snapshots |
 | `ShutdownStateSchema` / `ShutdownState` | schema / _type_ | managed lifecycle state machine |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",