stitchkit 0.52.0 → 0.53.1

package/llms-full.txt

@@ -851,6 +851,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `rawRoutes` | non-contract routes (see below) |
 | `maxJsonBodyBytes` | optional JSON body cap (bytes); per-route value overrides; unset preserves existing behaviour |
 | `port` / `hostname` | listen address — port defaults to `3000` |
+| `unix` | listen on a unix domain socket instead of TCP — `'/run/app.sock'` or `{ path, mode }` (see below) |
 | `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }`. `origin` is **required** when `cors` is present: pass an explicit origin (or list), or `'*'` to deliberately allow every origin — an origin-less config is a construction error, never a silent wildcard. Omit `cors` entirely to emit no CORS headers. |
 | `hooks` | lifecycle hooks (see below) |
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
@@ -864,6 +865,41 @@ 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.
 
+### Local daemon over a unix socket
+
+A local daemon whose door is a socket file needs no TCP port at all:
+
+```ts
+const server = createServer({
+  services,
+  unix: { path: '/run/my-daemon.sock', mode: 0o600 },
+})
+```
+
+`unix` is mutually exclusive with `port`/`hostname` (construction error). The
+handle stays honest: `server.url` is `unix:///run/my-daemon.sock` — an
+identifier, **not** a fetchable address (dial the path with
+`createHttpClient({ unix })`, [client guide](client.md#unix-domain-sockets)) —
+and `server.port` is `0`.
+
+Socket-file hygiene is built in. A stale file left by a killed process is
+reclaimed automatically: the path is probed, and only a socket that is owned by
+the current user **and** answers no live listener is removed before binding
+(best-effort — two processes racing the same path resolve through the loud
+bind error of the loser). A regular file at the path, another user's socket, or
+a live listener each fail with a specific error instead of being unlinked. A
+clean `server.shutdown()` removes the file.
+
+`mode` tightens the socket file permissions after listen. Bun creates the file
+`0755` under a normal umask — since `connect(2)` requires *write* permission
+that is already owner-only in practice — but when access to the socket **is**
+the credential, set `mode: 0o600` explicitly and let the filesystem be the
+policy. The Socket.IO lifecycle (`socket`) cannot mount on a unix listener
+(socket.io clients dial TCP only — construction error); Bun's own WebSocket
+client cannot dial a unix path either. Unix listeners are Bun-only: `srvx`
+resolves a numeric port unconditionally, so `stitchkit/node` does not offer
+`unix` (no half-support).
+
 ### Managed shutdown
 
 ```ts
@@ -1678,6 +1714,7 @@ without repeating transport configuration.
 | `suppressUnauthorizedFor` | `[]` | exact contract-derived operation matchers whose expected 401 does not emit `unauthorized` |
 | `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
 | `trace` | `false` | emit a W3C `traceparent` header on every request |
+| `unix` | — | dial a unix domain socket instead of TCP (Bun only, see below) |
 
 `headers` as a function is the hook for runtime tokens — a bearer token or any
 short-lived credential — re-evaluated on every request.
@@ -1691,6 +1728,26 @@ compile the prefix structure without a concrete tenant id. Matching is exact by
 path segments, including params and trailing wildcards — a shared prefix never
 suppresses a neighbouring protected endpoint.
 
+### Unix domain sockets
+
+The same typed client dials a local daemon's socket file
+([server side](server.md#local-daemon-over-a-unix-socket)):
+
+```ts
+const http = createHttpClient({
+  baseUrl: 'http://localhost', // required prefix source; its host is ignored
+  unix: '/run/my-daemon.sock',
+})
+const daemon = createClient(daemonContract, http)
+```
+
+`baseUrl` stays required — it supplies the path prefix and the `Host` header,
+while the connection itself goes through the socket file. Bun runtime only:
+other runtimes ignore the option and dial `baseUrl` over TCP (Node's fetch
+would need an undici dispatcher — out of scope). A missing socket file
+surfaces as a normal `ApiError` and is not retried (transport retry stays
+connection-refused-only).
+
 `trace: true` mints a fresh root trace per request. The stitchkit server
 [continues an inbound `traceparent`](./observability.md#trace-context), so the
 browser call, the HTTP handler and every nested tool call share one trace id
@@ -3286,8 +3343,11 @@ export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
 | `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.
+`pingInterval`, a runtime-neutral `allowRequest(Request)` handshake policy and
+the typed **`handshake`** identity gate (schema + verify →
+[typed `socket.data`](#handshake-auth--cookie-or-token)). `allowRequest` is the
+transport gate (composed with managed-shutdown admission on both Bun and Node);
+`handshake` is the identity gate that runs after it.
 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:
@@ -3337,7 +3397,40 @@ subscribe once; reconnection is the wrapper's problem, not yours.
 
 `SocketIOClientConfig` takes `url`, `path`, `withCredentials` (cookies on the
 handshake — default `true`), `auth`, `query`, `extraHeaders`, `transports`,
-`reconnectionAttempts`, `reconnectionDelay` and `retain` (below).
+`reconnectionAttempts`, `reconnectionDelay`, `retain` (below), `onConnectError`
+(handshake/connection failures — see the auth section) and `onDroppedEmit`
+(observability for emits dropped while disconnected — see below).
+
+### Honest emit — what happens while disconnected
+
+`emit` has exactly three outcomes, in order:
+
+1. **A local contract violation throws** (validated `RealtimeClient` only) —
+   validation runs before the connection guard, even while disconnected.
+2. **Disconnected → the emit is dropped**: `emit` returns `false` and the
+   `onDroppedEmit` hook fires with the event name and wire arguments. This
+   includes the short window right after `connect()` while the socket.io peer
+   is still loading.
+3. **Otherwise `emit` returns `true`** — handed to the transport, which is
+   *not* a delivery guarantee.
+
+The default is deliberately a drop, not a buffer: after a reconnect, durable
+subscriptions and [sticky events](#sticky-events) replay current state
+deterministically, instead of the server receiving an unordered backlog of
+stale emits. What changed is that the drop is now observable — assert it
+per-call (`if (!client.emit(...)) …`) or centrally:
+
+```ts
+const client = createSocketIOClient({
+  url,
+  onDroppedEmit: ({ event }) => metrics.count('realtime.dropped_emit', { event }),
+})
+```
+
+Server-side emits (`realtime.emit`, `to(room).emit`, `connection.events.emit`)
+always return `true` — a broadcast into an empty room is not a drop, and the
+server has no disconnected state of this kind. For state that must survive
+gaps, see [durability](#durability--idempotent--replay).
 
 ### Sticky events
 
@@ -3392,32 +3485,71 @@ const socket = createRealtimeClient(realtimeContract, {
 ```
 
 ```ts
-// server — the gate is your logic, on socket.handshake.auth
+// server — the typed identity gate: Zod-validate handshake.auth, verify,
+// and the result lands in socket.data — typed all the way to onConnection.
 import { verifyJwt } from 'stitchkit/server'
 
-socket.io.use(async (s, next) => {
-  const token = s.handshake.auth.token
-  if (typeof token !== 'string') return next(new Error('unauthorized'))
-  try {
-    s.data.user = await verifyJwt(token, secret)
-    next()
-  } catch {
-    next(new Error('unauthorized'))
-  }
+const socket = await createSocketIOServer({
+  cors: { origin: 'https://app.example.com' },
+  handshake: {
+    schema: z.object({ token: z.string() }),
+    verify: async ({ token }) => ({ user: await verifyJwt(token, secret) }),
+  },
+})
+
+const realtime = bindRealtimeServer(realtimeContract, socket)
+realtime.onConnection(({ raw }) => {
+  raw.data.user // typed — no String(...) coercions, no casts
 })
 ```
 
+`verify` may be async (the wrapper runs it inside a settled promise chain —
+raw async `io.use` middleware would leak an unhandled rejection); throwing or
+returning `null` rejects the handshake **before** the connection handler and
+before any event validation. A thrown error's raw message is logged
+server-side and never reaches the unauthenticated peer — the wire always
+carries the generic `handshake rejected` (the same never-leak policy as the
+HTTP error normalizer). The schema itself must be synchronous (no async
+refine/transform). Omit `verify` and the schema output itself is the
+identity. The gate registers as the **first** middleware, so `socket.io.use(…)`
+middlewares you add afterwards see the typed `socket.data` already in place.
+Raw `io.use` remains available for anything beyond identity.
+
+Type inference works on calls without explicit event generics (the
+`bindRealtimeServer` lane above). With explicit generics TypeScript cannot
+partially infer — pass the identity types too:
+`createSocketIOServer<S, C, z.infer<typeof schema>, Identity>`.
+
 A static object (`auth: { token }`) works too, but only the function form
 re-reads on reconnect — prefer it for rotating tokens. `query` adds handshake
-URL params (`socket.handshake.query`); `extraHeaders` adds handshake headers,
-but in a browser those apply to the **polling** transport only (a WebSocket
-upgrade cannot set request headers) — for browser WebSocket auth use `auth`.
-If an auth producer throws or rejects, the wrapper sends an empty auth object so
-the server gate can reject it instead of leaving the handshake waiting forever.
+URL params (`socket.handshake.query`) — note its values are **strings** on the
+wire, which is why the schema gate reads `auth`; `extraHeaders` adds handshake
+headers, but in a browser those apply to the **polling** transport only (a
+WebSocket upgrade cannot set request headers) — for browser WebSocket auth use
+`auth`.
+
+**A gate rejection is terminal for the client.** Unlike a transport-level
+failure (which socket.io retries indefinitely), a middleware/handshake-gate
+rejection stops the client: socket.io destroys its retry path and will not
+reconnect on its own. The stitchkit client surfaces this through
+**`onConnectError`** with `terminal: true` (and `data.code ===
+'handshake_rejected'` for the built-in gate) and resets its connection intent —
+so recovery is explicit: rotate the credential, call `connect()`, and the
+function-form `auth` is re-read:
+
+```ts
+const client = createRealtimeClient(realtimeContract, {
+  url: 'https://api.example.com',
+  auth: () => ({ token: getAccessToken() }),
+  onConnectError: ({ terminal }) => {
+    if (terminal) refreshTokenThen(() => client.connect())
+  },
+})
+```
 
-On a hard auth failure Socket.IO emits `connect_error` and keeps retrying
-(`reconnectionAttempts` defaults to `Infinity`) — set a finite value if a
-rejected token should stop hammering the server.
+If an auth producer throws or rejects, the wrapper sends an empty auth object —
+the server gate then rejects it visibly (via `onConnectError`) instead of
+leaving the handshake waiting forever.
 
 ## Cache bridge
 
@@ -5277,6 +5409,28 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides
@@ -6208,7 +6362,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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 |
-| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default — [details](../guide/client.md#createhttpclient) |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `unix` dials a unix domain socket (Bun only) — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -6224,8 +6378,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `SocketIOClient` | _type_ | the client handle |
-| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`) |
+| `SocketIOClient` | _type_ | the client handle; `emit` returns `false` for an emit dropped while disconnected |
+| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
 | `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
@@ -6239,7 +6393,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeRejectDirection` | _type_ | server/client inbound/outbound rejection direction |
 | `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
 | `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
-| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries |
+| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
@@ -6393,7 +6547,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
 | `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) |
+| `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `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 graceful budget, bounded forced-completion timeout, retry hint and optional external abort signal |
@@ -6469,9 +6624,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `bindRealtimeServer` | function | inferred, runtime-validated connection and broadcast boundary |
 | `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` |
+| `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer`; carries the handshake identity type through to `connection.raw.data` |
 | `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
-| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
+| `SocketIOServerConfig` | _type_ | config for `createSocketIOServer`; `handshake` is the typed identity gate — [guide](../guide/realtime.md#handshake-auth--cookie-or-token) |
+| `SocketIOHandshakeConfig` | _type_ | the `handshake` gate — Zod `schema` over `handshake.auth` plus optional async `verify`; the result lands typed in `socket.data` |
 | `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)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.52.0",
+  "version": "0.53.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",