stitchkit 0.48.1 → 0.49.0

package/llms-full.txt

@@ -712,8 +712,9 @@ The registry is intentionally flat: every key must point to one concrete
 
 ## `createServer`
 
-`createServer(config)` builds the router and starts `Bun.serve()`. It returns
-the Bun server instance.
+`createServer(config)` builds the router and starts `Bun.serve()`. It returns a
+managed handle with `url`, `port`, the concrete server under `runtime`, live
+`status`, and one idempotent `shutdown()` lifecycle.
 
 ```ts
 import { createServer } from 'stitchkit/server'
@@ -746,8 +747,34 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
 | `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
 | `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
-| `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
-| `routes` / `development` / `bun` | passthrough to `Bun.serve` |
+| `socket` | full Stitchkit Socket.IO handle; route, default WebSocket handler and shutdown are mounted once |
+| `websocket` | custom Bun WebSocket handler; with `socket`, this is the explicit composed handler |
+| `development` / `bun` | passthrough to `Bun.serve` |
+
+Native Bun `routes` are intentionally not accepted: Bun matches them before
+`fetch`, so they could bypass shutdown admission. Use `rawRoutes`; they retain
+the Fetch `Request → Response` model and participate in lifecycle tracking.
+
+### Managed shutdown
+
+```ts
+const server = createServer({ services, socket })
+
+const result = await server.shutdown({
+  gracePeriodMs: 30_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
+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.
 
 ### Trusted HTTPS in development
 
@@ -1561,6 +1588,15 @@ attempt, so the default `2` permits at most three total attempts. The default
 `statusCodes: []` does not replay HTTP responses; explicit `methods` or
 `statusCodes` expand that policy when a project has a proven idempotent case.
 
+Inside Next.js 16 server rendering, the first attempt still uses Next's normal
+request memoization. If Ky authorizes a retry after a network rejection,
+Stitchkit passes that retry's current `Request.signal` in the second fetch
+argument and materializes the current Request as URL + init. Next 16.3 otherwise
+merges `init` into a Request before its dedupe layer and loses the explicit
+signal opt-out. The retry therefore performs a new network attempt instead of
+returning the cached rejection. This adapter does not broaden retry policy: POST, unconfigured HTTP
+statuses, cancellation and exhausted budgets retain the rules above.
+
 ## `createClient`
 
 ```ts
@@ -3103,13 +3139,12 @@ realtime.onConnection(({ raw, events, to }) => {
 })
 ```
 
-It returns a handle with three pieces, all wired into `createServer`:
+Pass the full handle to `createServer`; it mounts and owns the transport once:
 
 ```ts
 createServer({
   services,
-  websocket: socket.websocket,   // → Bun.serve websocket handlers
-  rawRoutes: [socket.route],     // ready-made /socket.io/*socketPath route
+  socket,
 })
 
 // elsewhere — validated broadcast:
@@ -3129,11 +3164,15 @@ export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
 | Handle field | Purpose |
 |--------------|---------|
 | `io` | raw Socket.IO server for middleware, handshake auth and transport ownership |
-| `websocket` | Bun WebSocket handlers — pass to `createServer({ websocket })` |
-| `route` | the `/socket.io/*socketPath` raw route — pass to `createServer({ rawRoutes })` |
-
-`SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout` and
-`pingInterval`. For anything else socket.io's `ServerOptions` exposes, use the
+| `websocket` | Bun handlers used directly only in explicit raw-lane composition |
+| `route` | `/socket.io/*socketPath`, mounted automatically by `createServer({ socket })` |
+| `close()` | idempotent standalone close for CLI/tools with no HTTP server |
+| `beginShutdown()` / `connections()` | lifecycle surface consumed by the managed server |
+
+`SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout`,
+`pingInterval` and a runtime-neutral `allowRequest(Request)` handshake policy.
+The policy is composed with managed-shutdown admission on both Bun and Node.
+For anything else socket.io's `ServerOptions` exposes, use the
 typed **`serverOptions`** passthrough — most often `maxHttpBufferSize` to lift the
 1 MB default for large emits:
 
@@ -3144,7 +3183,8 @@ await createSocketIOServer({
 })
 ```
 
-The wrapper-owned fields (`cors` / `path` / `transports` / `ping*`) take
+The wrapper-owned fields (`cors` / `path` / `transports` / `ping*` /
+`allowRequest`) take
 precedence over the same keys in `serverOptions`. On Bun the engine-level options
 (`maxHttpBufferSize`, the ping heartbeat, `upgradeTimeout`) are forwarded to
 `@socket.io/bun-engine` too — so a configured `maxHttpBufferSize` actually applies
@@ -3441,8 +3481,9 @@ const websocket = composeWebSocketHandlers(
 
 createServer({
   services,
+  socket,
   websocket,
-  rawRoutes: [socket.route, pcmRoute],
+  rawRoutes: [pcmRoute],
 })
 ```
 
@@ -4590,8 +4631,34 @@ createServer({
 })
 ```
 
-`createServer` returns the `Bun.serve` instance — keep the reference if you need
-`.stop()` for a graceful shutdown.
+Keep the managed handle and wire process policy explicitly:
+
+```ts
+const server = createServer({ services, socket })
+const force = new AbortController()
+let closing: Promise<void> | undefined
+
+function shutdown() {
+  if (closing) {
+    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 => {
+    await mcp.close()
+    await prisma.$disconnect()
+    console.log(result)
+  })
+  return closing
+}
+
+process.on('SIGTERM', () => void shutdown())
+process.on('SIGINT', () => void shutdown())
+```
+
+The server owns HTTP/Socket.IO transport resources. MCP, databases, queues and
+domain run-state remain application resources and close explicitly after server
+drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
+`shutdown()`.
 
 ### Deploy on Node
 
@@ -4602,10 +4669,13 @@ the listener differs: replace `createServer` with **`serveNode`** (from
 ```ts
 import { serveNode } from 'stitchkit/node'
 
-serveNode({
+const server = await serveNode({
   services,
+  socket,
   port: Number(process.env.PORT ?? 3000),
 })
+
+await server.shutdown({ gracePeriodMs: 30_000 })
 ```
 
 Notes for a Node host:
@@ -4614,9 +4684,6 @@ Notes for a Node host:
   raw routes use `RawRoute<TServer = unknown>`; supply a host server generic
   only when an embedding adapter passes one to `createHandler`.
 
-- Add **`@types/bun`** as a dev dependency — it is an optional peer that types the
-  shared `stitchkit/server` surface (without it `tsc` reports a missing `Bun`
-  namespace).
 - **Socket.IO** attaches to the Node HTTP server via `serveNode({ socket })`, and
   on Node the default transport is `['websocket']` — set the client to match
   (`transports: ['websocket']`). See [realtime](./realtime.md).
@@ -5626,9 +5693,68 @@ socket.io
 socket.attach(nodeHttpServer)
 ```
 
-Inline Bun routes passed to `createServer` continue to infer `BunServer`; no
-annotation is needed. Node consumers can remove `@types/bun` unless another
-dependency independently requires it.
+Node consumers can remove `@types/bun` unless another dependency independently
+requires it.
+
+### Managed server shutdown
+
+`createServer()` and `serveNode()` now return the same structural managed
+lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
+
+```ts
+// before — split ownership
+const socket = await createSocketIOServer(config)
+const server = createServer({
+  services,
+  websocket: socket.websocket,
+  rawRoutes: [socket.route],
+})
+server.stop()
+await socket.io.close()
+
+// after — one owner and one total deadline
+const socket = await createSocketIOServer(config)
+const server = createServer({ services, socket })
+const result = await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+On Node, keep the same `socket` field and replace `handle.close()` with
+`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
+do not use it as a second shutdown path. Standalone CLI/tools that create a
+Socket.IO handle without an HTTP server call `await socket.close()`.
+
+If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
+but let the server mount the Socket.IO route:
+
+```ts
+createServer({
+  services,
+  socket,
+  websocket: composeWebSocketHandlers([
+    webSocketLane({ match: isRaw, handlers: rawHandlers }),
+    socketIoLane(socket.websocket),
+  ]),
+  rawRoutes: [rawUpgradeRoute],
+})
+```
+
+Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
+Fetch handler and therefore cannot participate in admission or drain. Wire
+`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
+a later signal may abort the same controller. Close MCP, databases and queues
+after the server result—those resources remain application-owned.
+
+Move a handshake policy from the Node-only callback shape inside
+`serverOptions` to the runtime-neutral top-level policy. It receives a Web
+`Request`, may be async, and returns whether to admit the handshake:
+
+```ts
+// before
+serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
+
+// after
+allowRequest: (request) => allowed(request)
+```
 
 ## Your handlers may be returning more than the contract declares
 
@@ -5718,7 +5844,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
-| `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
+| `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
@@ -5897,6 +6023,12 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `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 |
+| `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 |
 | `ServiceDef` | _type_ | the result of `implement` |
 | `MethodDef` | _type_ | one resolved endpoint inside a service |
 | `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
@@ -5962,8 +6094,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `RealtimeServer` | _type_ | validated broadcast and connection API inferred from a realtime contract |
 | `RealtimeServerConnection` | _type_ | one validated connection with raw socket access for auth and rooms |
 | `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer` |
+| `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
 | `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
-| `SocketIOServerHandle` | _type_ | the `{ io, websocket, route }` handle |
+| `SocketIOServerHandle` | _type_ | typed Socket.IO server plus Bun mount fields and idempotent lifecycle |
+| `SocketIOServerLifecycle` | _type_ | non-generic Bun mount/shutdown portion accepted by `createServer` |
 | `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |
 | `webSocketLane` | function | a typed, cast-free lane for `composeWebSocketHandlers` |
 | `socketIoLane` | function | the Socket.IO catch-all lane for `composeWebSocketHandlers` |
@@ -6292,9 +6426,11 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `createSocketIOServer` | function | the typed Node Socket.IO server (`io` + `attach`; no Bun engine declarations) |
 | `implement` / `createImplement` | function | bind a contract to typed handlers (same as `/server`) |
 | `NodeServerConfig` | _type_ | config for `serveNode` |
-| `NodeServerHandle` | _type_ | the `serveNode` handle (`{ port, stop }`) |
+| `NodeServerHandle` | _type_ | managed Node handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
+| `NodeRuntimeServer` | _type_ | concrete `srvx/node` runtime escape hatch |
+| `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
 | `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
-| `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | shared config and the Node-only `{ io, attach }` handle |
+| `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config and Bun-free Node handle with `io`, `attach` and lifecycle |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "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",
@@ -95,6 +95,7 @@
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
+    "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
     "consumer-lane": "bun scripts/consumer-lane/run.mjs",
     "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts"
   },