@greendrake/rpc-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @greendrake/rpc-server
+
+The server half of the [`@greendrake/rpc`](../rpc) wire format: one dispatch table, an HTTP endpoint and a WebSocket endpoint over it, per-method auth and argument validation, and a connection registry that pushes to clients unasked. **Runs on [bun](https://bun.sh)** — `Bun.serve` owns the sockets. The protocol core (dispatch, auth, nonce, validation) is pure functions over the wire types and touches no runtime API.
+
+## Install
+
+```sh
+bun add @greendrake/rpc-server
+```
+
+TypeScript source ships as-is (`src/main.ts` is the entry; no build step, no `.d.ts`). Extend `@greendrake/dev-config/tsconfig/base.json` with `"types": ["bun"]` — base rather than the node config because `@greendrake/rpc`, the client this serves and whose wire types it imports, is the same code a browser runs and needs the DOM lib.
+
+## A service, whole
+
+```ts
+import { ConnRegistry, clientIp, createDispatcher, httpHandler, keyAuthResolver, memoryNonceStore, method, websocketHandler } from '@greendrake/rpc-server'
+import { z } from 'zod'
+
+const registry = new ConnRegistry()
+
+const methods = {
+    'user.get': method({
+        auth: 'user',
+        args: z.object({ id: z.string() }),
+        handler: (ctx, args) => users.get(args.id, ctx.signal)
+    }),
+    'user.list': method({ auth: 'admin', handler: () => users.all() })
+}
+
+const dispatcher = createDispatcher(methods, {
+    auth: keyAuthResolver(process.env.ADMIN_API_KEY!, { userId: 'operator', isAdmin: true, phantom: false }),
+    nonces: memoryNonceStore(5 * 60 * 1000)
+})
+const api = httpHandler(dispatcher)
+const ws = websocketHandler(dispatcher, registry)
+
+Bun.serve({
+    port: 8080,
+    websocket: ws.handlers,
+    async fetch(request, server) {
+        const { pathname } = new URL(request.url)
+        if (pathname === '/v1/ws') return (await ws.upgrade(request, server)) ? undefined : new Response(null, { status: 400 })
+        if (pathname === '/v1/api') return api(request, clientIp(request, server))
+        return new Response(null, { status: 404 })
+    }
+})
+```
+
+[`@greendrake/server`](../server) wraps that last call with health probes, CORS and a graceful-shutdown sequence; nothing here requires it.
+
+## Methods
+
+A `MethodDef` is what a method requires of its caller, what its argument looks like, and what runs:
+
+```ts
+interface MethodDef<A = void, R = unknown> {
+    auth: 'none' | 'user' | 'admin'
+    allowPhantom?: boolean
+    args?: StandardSchemaV1<unknown, A>
+    handler(ctx: HandlerContext, args: A): R | Promise<R>
+}
+```
+
+**A method with no `args` schema takes no argument.** That is the rule, not an omission: validation is where an argument's type comes from, so a handler cannot be handed a value nothing has checked. A method taking a free-form payload declares a permissive schema and says so.
+
+`method()` is identity at runtime and exists for inference — written inline in a table, a definition has nowhere to get its argument type from, because the table's own type erases it. Wrap each entry in it and the schema's output type reaches the handler's parameter.
+
+`HandlerContext` carries `auth`, `locale`, `clientIp` and a `signal` that aborts when the caller goes away — an HTTP client disconnecting, a WebSocket closing. Pass it to whatever I/O the handler does, so work nobody is waiting for is abandoned rather than run to completion.
+
+### Argument validation
+
+`args` takes any [Standard Schema](https://standardschema.dev): zod, valibot and arktype all implement it, and this package depends on none of them. A failure answers `INVALID_ARGUMENT` with the issues in `error_details`:
+
+```json
+{ "success": false, "error": "INVALID_ARGUMENT", "error_details": [{ "field": "filters.0.from", "message": "Expected number" }] }
+```
+
+`field` is the issue's path joined with dots, which is what a form keys its per-field messages by.
+
+### Authentication
+
+`AuthResolver` turns a credential into an `AuthInfo { userId, isAdmin, phantom }`, or `null` where it names nobody — a stranger, not a refusal, since what a method requires of a principal is the dispatcher's business. `userId` is `unknown`: it is the application's own id type, and nothing here reads it.
+
+`keyAuthResolver(key, info)` is the static-key pattern — one pre-shared secret standing for one identity, for a dashboard behind an operator gate or a deployment tool. An empty key matches nothing.
+
+The auth rules, in the order a refusal is decided:
+
+| `auth` | Refuses with |
+| --- | --- |
+| `'none'` | nothing |
+| `'user'` | `AUTH_REQUIRED` for an anonymous caller |
+| `'admin'` | `AUTH_REQUIRED`, then `ADMIN_REQUIRED` |
+
+A phantom — a provisional principal the application has not fully registered — is additionally refused with `PHANTOM_NOT_ALLOWED` unless the method sets `allowPhantom`.
+
+### Nonces
+
+A request carrying a `nonce` runs once: `NonceStore.checkAndSet` answers false for a repeat, and the call is refused with `DUPLICATE_REQUEST`. `memoryNonceStore(ttlMs)` is one process's worth — behind a load balancer the replicas would each keep their own set, so use a shared store (Redis `SET NX PX` implements the interface in a few lines).
+
+## Transports
+
+`httpHandler(dispatcher, { codec? })` returns `(request, clientIp) => Promise<Response>`: POST only (405 otherwise), the credential from the `Authorization` header (`Bearer <token>` or a bare pre-shared key), and one call per request. `clientIp(request, server)` reads `X-Forwarded-For`, then `X-Real-Ip`, then the socket.
+
+`websocketHandler(dispatcher, registry, { onOpen?, onClose? })` returns `{ upgrade, handlers }`. The handshake credential is the `token` query parameter — the only channel a browser's WebSocket constructor leaves open, having no headers, and one a reconnect carries again for free. Calls dispatch concurrently, correlated by the `id` the client puts on each frame.
+
+The exception is `auth.token` and `auth.logout`, the in-band frames `@greendrake/rpc`'s `WsTransport` sends: they change who every later call on that socket is made by, so each goes on a per-connection gate the calls wait behind. Without it a call sent right after a bind would race it and come back `UNAUTHENTICATED`.
+
+A codec applies to everything on the wire, in both directions, for a service whose clients obscure or encrypt their payloads: `new ConnRegistry(codec)` for the socket, `httpHandler(dispatcher, { codec })` for the endpoint.
+
+## Pushing
+
+`ConnRegistry` holds every open socket and indexes them by principal:
+
+```ts
+registry.emitToUser(userId, 'thread.updated', { id })  // {type:'event', event, data} to that user's sockets
+registry.broadcastEvent('service.state', status) // …to every socket
+registry.broadcastData('telemetry', reading) // the bare {type, data} form
+```
+
+Push-producing code takes the `EventSink` interface (`emitToUser` + `broadcastEvent`) rather than the class, so it can be driven by anything. On the client, `@greendrake/rpc`'s `liveBinding` — or `@greendrake/vue-api`'s `useLive` — subscribes to these, folds each push in or re-reads, and re-reads again after a dropped socket returns.
+
+## Error codes
+
+Codes, not sentences: the client keys on them. A handler's own outcomes are `throw new ApiError(code, details?)`; anything else it throws is a fault, logged and answered `INTERNAL_ERROR`.
+
+| Code | Meaning |
+| --- | --- |
+| `UNKNOWN_METHOD` | no such method in the table |
+| `INVALID_JSON` | the body or frame did not parse |
+| `INVALID_ARGUMENT` | the argument failed the method's schema |
+| `AUTH_REQUIRED` | the method needs a caller and there is none |
+| `ADMIN_REQUIRED` | the caller is not an admin |
+| `PHANTOM_NOT_ALLOWED` | the caller is provisional and this method is not open to one |
+| `UNAUTHENTICATED` | an `auth.token` frame named nobody |
+| `AUTH_NOT_CONFIGURED` | an auth frame reached a service with no resolver |
+| `DUPLICATE_REQUEST` | this nonce has already been used |
+| `INTERNAL_ERROR` | a handler faulted |
+
+By convention a code ending `_NOT_FOUND` becomes a `NotFoundError` client-side, which is the one class `@greendrake/rpc` maps specially. Nothing here enforces it.
+
+## The pair's typing
+
+`ClientMethods<M>` turns a dispatch table into the method map a client hands `RpcClient` or `ApiClient`:
+
+```ts
+export const methods = { /* … */ }
+export type ApiMethods = ClientMethods<typeof methods>
+```
+
+Declared once, on the side that defines the methods: a method whose argument shape or result changes stops compiling in whatever calls it. `examples/service-pair` is a working pair built this way.

package/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@greendrake/rpc-server",
+    "version": "0.1.0",
+    "description": "RPC server over JSON for bun: method dispatch with auth, nonce and Standard Schema argument validation, HTTP and WebSocket transports, connection registry and server push",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "rpc-server"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/rpc-server#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "dependencies": {
+        "@greendrake/rpc": "0.1.0",
+        "@standard-schema/spec": "^1.1.0"
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "@types/bun": "^1.3.5",
+        "typescript": "6.0.3"
+    }
+}

package/src/arguments.ts

@@ -0,0 +1,33 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { ApiError } from './errors'
+
+// A method takes one argument, and the envelope carries it two ways: wrapped
+// in an array, which is what @greendrake/rpc sends, or as the value itself,
+// which is what a hand-written caller or another language's client tends to
+// send. Both unwrap to the same thing.
+export const unwrapArguments = (raw: unknown): unknown => {
+    if (raw === undefined || raw === null) {
+        return undefined
+    }
+    return Array.isArray(raw) ? raw[0] : raw
+}
+
+// Validates the unwrapped argument against a method's schema. A failure is an
+// ApiError carrying every issue, so a form can mark each offending field
+// rather than showing one message for the whole submission.
+export const validateArguments = async <A>(schema: StandardSchemaV1<unknown, A>, value: unknown): Promise<A> => {
+    const result = await schema['~standard'].validate(value)
+    if (result.issues) {
+        // An issue's path — `['filters', 0, 'from']` — becomes the dotted name a
+        // form field is keyed by. Segments arrive bare or wrapped in a `{ key }`
+        // object; both name the same step.
+        throw new ApiError(
+            'INVALID_ARGUMENT',
+            result.issues.map(issue => ({
+                field: (issue.path ?? []).map(segment => String(typeof segment === 'object' ? segment.key : segment)).join('.'),
+                message: issue.message
+            }))
+        )
+    }
+    return result.value
+}

package/src/auth.ts

@@ -0,0 +1,29 @@
+import type { AuthInfo, AuthResolver } from './types'
+
+// A single pre-shared secret — the static API key pattern: a trusted
+// non-browser caller (an admin dashboard behind a webserver-level gate, a
+// deployment tool, an MCP server) authenticates with one configured key
+// instead of a per-user token. The identity a match yields is the
+// application's, so the whole principal is supplied here.
+//
+// An empty key matches nothing: an unconfigured secret must not turn into a
+// hole that lets everyone in.
+export const keyAuthResolver = (key: string, info: AuthInfo): AuthResolver => ({
+    resolveToken: token => Promise.resolve(key !== '' && token === key ? info : null)
+})
+
+// The credential out of an Authorization header. Two forms are on the wire:
+// `Bearer <token>`, and a bare pre-shared key with no scheme at all (what the
+// key-auth callers above send). Any other scheme is not a credential this
+// understands, and yields none.
+export const bearerToken = (request: Request): string => {
+    const header = request.headers.get('authorization')
+    if (!header) {
+        return ''
+    }
+    const space = header.indexOf(' ')
+    if (space === -1) {
+        return header
+    }
+    return header.slice(0, space).toLowerCase() === 'bearer' ? header.slice(space + 1) : ''
+}

package/src/dispatcher.ts

@@ -0,0 +1,75 @@
+import { unwrapArguments, validateArguments } from './arguments'
+import { ApiError } from './errors'
+import type { AuthResolver, CallContext, HandlerContext, IncomingRequest, LocaleResolver, Methods, NonceStore, RpcResponse } from './types'
+
+export interface DispatcherOptions {
+    // Absent means the service has no notion of identity: every method it
+    // serves must be `auth: 'none'`, and an in-band auth frame answers
+    // AUTH_NOT_CONFIGURED.
+    auth?: AuthResolver
+    // Absent means nonces are carried but not checked — fine for a
+    // single-caller service, not for one exposed to retries it cannot afford
+    // to apply twice.
+    nonces?: NonceStore
+    locale?: LocaleResolver
+}
+
+// The engine both transports share: everything between a parsed envelope and a
+// response, and nothing about how either got there.
+export interface Dispatcher {
+    // Exposed because the transports resolve credentials of their own — a
+    // bearer header, a query parameter at the WebSocket handshake, an in-band
+    // auth frame — before there is a request to dispatch.
+    readonly auth?: AuthResolver
+    dispatch(request: IncomingRequest, context: CallContext): Promise<RpcResponse>
+}
+
+const failure = (error: string, details?: unknown): RpcResponse => ({
+    success: false,
+    error,
+    error_details: details
+})
+
+export const createDispatcher = (methods: Methods, options: DispatcherOptions = {}): Dispatcher => ({
+    auth: options.auth,
+    async dispatch(request, context) {
+        try {
+            // A repeat of a call that already ran is refused before anything
+            // else: the point of the nonce is that its effect happens once.
+            if (request.nonce && options.nonces && !(await options.nonces.checkAndSet(request.nonce))) {
+                return failure('DUPLICATE_REQUEST')
+            }
+            // Own properties only: a method named `toString` or `constructor`
+            // is not a method this service serves.
+            if (!Object.hasOwn(methods, request.method)) {
+                return failure('UNKNOWN_METHOD')
+            }
+            const def = methods[request.method]
+            if (def.auth !== 'none') {
+                if (context.auth.userId === null) {
+                    return failure('AUTH_REQUIRED')
+                }
+                if (def.auth === 'admin' && !context.auth.isAdmin) {
+                    return failure('ADMIN_REQUIRED')
+                }
+                if (context.auth.phantom && !def.allowPhantom) {
+                    return failure('PHANTOM_NOT_ALLOWED')
+                }
+            }
+            const ctx: HandlerContext = { ...context, locale: options.locale?.(request.locale) ?? '' }
+            const args = def.args ? await validateArguments(def.args, unwrapArguments(request.arguments)) : undefined
+            return { success: true, data: await def.handler(ctx, args) }
+        } catch (e) {
+            if (e instanceof ApiError) {
+                return failure(e.code, e.details)
+            }
+            // A request whose caller has already gone fails in whatever way the
+            // abandoned I/O reports; that is the disconnect, not a fault of the
+            // service, and its response is discarded anyway.
+            if (!context.signal.aborted) {
+                console.error(`[rpc-server] ${request.method}:`, e)
+            }
+            return failure('INTERNAL_ERROR')
+        }
+    }
+})

package/src/errors.ts

@@ -0,0 +1,19 @@
+// A business outcome the caller is meant to see: `code` becomes the response's
+// `error`, `details` its `error_details` (the structured payload a handler
+// attaches alongside a code — the per-field list argument validation produces,
+// the conflicting record's id, whatever the method's contract says).
+//
+// Anything else a handler throws is a fault, not an outcome: it is logged and
+// answered INTERNAL_ERROR, so an unforeseen failure never leaks its internals
+// to a client.
+export class ApiError extends Error {
+    readonly code: string
+    readonly details?: unknown
+
+    constructor(code: string, details?: unknown) {
+        super(code)
+        this.name = 'ApiError'
+        this.code = code
+        this.details = details
+    }
+}

package/src/http.ts

@@ -0,0 +1,62 @@
+import type { Server } from 'bun'
+import { identityCodec } from '@greendrake/rpc'
+import { bearerToken } from './auth'
+import type { Dispatcher } from './dispatcher'
+import { ANONYMOUS } from './types'
+import type { Codec, IncomingRequest, RpcResponse } from './types'
+
+export interface HttpHandlerOptions {
+    // Applied to the request body and the response body. Identity by default;
+    // a service whose clients obscure or encrypt their payloads supplies the
+    // same codec both ends run.
+    codec?: Codec
+}
+
+// Where the call came from, as the proxies in front of this service report it.
+// A service behind nothing still gets the socket's own address.
+export const clientIp = <T>(request: Request, server: Server<T>): string => {
+    const forwarded = request.headers.get('x-forwarded-for')
+    if (forwarded) {
+        // The left-most entry is the original client; the rest are the proxies
+        // it passed through.
+        return forwarded.split(',')[0].trim()
+    }
+    return request.headers.get('x-real-ip') ?? server.requestIP(request)?.address ?? ''
+}
+
+// The single-endpoint HTTP transport: one POST carries one call. Returns the
+// handler a `Bun.serve` fetch routes its API path to.
+export const httpHandler = (dispatcher: Dispatcher, options: HttpHandlerOptions = {}): ((request: Request, ip: string) => Promise<Response>) => {
+    const codec = options.codec ?? identityCodec
+    // A codec's output is not JSON any more, and calling it JSON misleads
+    // everything that sniffs the body — devtools, proxies, CDNs.
+    const contentType = options.codec ? 'text/plain; charset=utf-8' : 'application/json'
+    const respond = (response: RpcResponse): Response => new Response(codec.encode(JSON.stringify(response)), { headers: { 'content-type': contentType } })
+
+    return async (request, ip) => {
+        if (request.method !== 'POST') {
+            return new Response(null, { status: 405 })
+        }
+        const token = bearerToken(request)
+        // A token nobody recognises leaves the caller anonymous rather than
+        // refused: what that costs them is decided per method, by the rule the
+        // method declares.
+        const auth = (token && (await dispatcher.auth?.resolveToken(token, request.signal))) || ANONYMOUS
+
+        let parsed: IncomingRequest
+        try {
+            parsed = JSON.parse(codec.decode(await request.text())) as IncomingRequest
+        } catch {
+            return respond({ success: false, error: 'INVALID_JSON' })
+        }
+        // No `type` on an HTTP response: the field exists to tell a WebSocket
+        // frame's kind apart, and here there is only one kind.
+        return respond(
+            await dispatcher.dispatch(parsed, {
+                auth,
+                clientIp: ip,
+                signal: request.signal
+            })
+        )
+    }
+}

package/src/main.ts

@@ -0,0 +1,10 @@
+export { ANONYMOUS, method, type AuthInfo, type AuthRequirement, type AuthResolver, type CallContext, type ClientMethods, type DataFrame, type EventFrame, type HandlerContext, type IncomingRequest, type LocaleResolver, type MethodDef, type Methods, type NonceStore, type WsResponse } from './types'
+export { ApiError } from './errors'
+export { unwrapArguments, validateArguments } from './arguments'
+export { createDispatcher, type Dispatcher, type DispatcherOptions } from './dispatcher'
+export { bearerToken, keyAuthResolver } from './auth'
+export { memoryNonceStore } from './nonce'
+export { clientIp, httpHandler, type HttpHandlerOptions } from './http'
+export { websocketHandler, type RpcWebSocket, type WebSocketHandlerOptions } from './ws'
+export { ConnRegistry, type Connection, type ConnectionData, type EventSink } from './registry'
+export type { Codec, RpcRequest, RpcResponse } from './types'

package/src/nonce.ts

@@ -0,0 +1,28 @@
+import type { NonceStore } from './types'
+
+// In-process nonce store: a Map swept on insert, so it needs no timer and no
+// teardown. One process only — behind a load balancer the replicas would each
+// keep their own set and a retry landing elsewhere would run twice, so a
+// multi-instance deployment needs a shared store (Redis `SET NX PX` with the
+// same TTL implements this interface in a few lines).
+export const memoryNonceStore = (ttlMs: number): NonceStore => {
+    // Insertion order is expiry order, the TTL being constant, so the sweep
+    // stops at the first entry still alive instead of walking the whole map.
+    const expiries = new Map<string, number>()
+    return {
+        checkAndSet: nonce => {
+            const now = Date.now()
+            for (const [seen, expiry] of expiries) {
+                if (expiry > now) {
+                    break
+                }
+                expiries.delete(seen)
+            }
+            if (expiries.has(nonce)) {
+                return Promise.resolve(false)
+            }
+            expiries.set(nonce, now + ttlMs)
+            return Promise.resolve(true)
+        }
+    }
+}

package/src/registry.ts

@@ -0,0 +1,131 @@
+import type { ServerWebSocket } from 'bun'
+import { identityCodec } from '@greendrake/rpc'
+import type { AuthInfo, Codec, ServerFrame } from './types'
+
+// Per-socket state, carried as Bun's websocket `data`.
+export interface ConnectionData {
+    // Who the socket is bound as: the query-parameter credential it opened
+    // with, or whatever an in-band auth frame has since made it.
+    auth: AuthInfo
+    // Aborted when the socket closes, so every handler still running on it
+    // learns its caller is gone.
+    controller: AbortController
+    clientIp: string
+    // Serialises the frames that change who the connection is against the
+    // calls that depend on the answer. See the WebSocket handler.
+    gate: Promise<unknown>
+}
+
+export type Connection = ServerWebSocket<ConnectionData>
+
+// What a subsystem needs in order to tell clients something happened, without
+// knowing what a connection is. Push-producing code takes this, not the
+// registry.
+export interface EventSink {
+    emitToUser(userId: unknown, event: string, data: unknown): void
+    broadcastEvent(event: string, data: unknown): void
+}
+
+// Every open socket, and the index from principal to the sockets bound as it —
+// a user with three tabs has three. Holding all of them as well as the index
+// is what lets a broadcast reach anonymous connections too, which a per-user
+// index alone cannot.
+export class ConnRegistry implements EventSink {
+    readonly #connections = new Set<Connection>()
+    readonly #byUser = new Map<unknown, Set<Connection>>()
+    // Where each connection is currently filed, so a principal that changes
+    // mid-connection can be re-indexed without the caller tracking what it
+    // used to be.
+    readonly #filedUnder = new Map<Connection, unknown>()
+    // Public because the WebSocket handler decodes inbound frames with it:
+    // one codec governs the socket in both directions, and it is configured
+    // here, once.
+    readonly codec: Codec
+
+    constructor(codec: Codec = identityCodec) {
+        this.codec = codec
+    }
+
+    // Idempotent, and the one way a connection's principal reaches the index:
+    // called when a socket opens and again whenever an auth frame changes who
+    // it is.
+    register(conn: Connection): void {
+        this.#connections.add(conn)
+        const userId = conn.data.auth.userId
+        if (this.#filedUnder.get(conn) === userId) {
+            return
+        }
+        this.#unfile(conn)
+        if (userId === null) {
+            return
+        }
+        let bound = this.#byUser.get(userId)
+        if (!bound) {
+            bound = new Set()
+            this.#byUser.set(userId, bound)
+        }
+        bound.add(conn)
+        this.#filedUnder.set(conn, userId)
+    }
+
+    unregister(conn: Connection): void {
+        this.#connections.delete(conn)
+        this.#unfile(conn)
+    }
+
+    #unfile(conn: Connection): void {
+        if (!this.#filedUnder.has(conn)) {
+            return
+        }
+        const userId = this.#filedUnder.get(conn)
+        this.#filedUnder.delete(conn)
+        const bound = this.#byUser.get(userId)
+        if (!bound) {
+            return
+        }
+        bound.delete(conn)
+        if (bound.size === 0) {
+            this.#byUser.delete(userId)
+        }
+    }
+
+    // The one place a frame becomes bytes: responses and pushes leave a socket
+    // the same way, so a codec is configured once rather than per call site.
+    send(conn: Connection, frame: ServerFrame): void {
+        conn.send(this.codec.encode(JSON.stringify(frame)))
+    }
+
+    sendToUser(userId: unknown, frame: ServerFrame): void {
+        this.#byUser.get(userId)?.forEach(conn => this.send(conn, frame))
+    }
+
+    emitToUser(userId: unknown, event: string, data: unknown): void {
+        this.sendToUser(userId, {
+            type: 'event',
+            event,
+            data
+        })
+    }
+
+    // To every open socket, whoever it is bound as — for state the whole
+    // service shares rather than anything addressed to a user.
+    broadcastEvent(event: string, data: unknown): void {
+        this.#connections.forEach(conn =>
+            this.send(conn, {
+                type: 'event',
+                event,
+                data
+            })
+        )
+    }
+
+    // The bare `{type, data}` form, for a push whose own type names the
+    // payload and needs no event envelope.
+    broadcastData(type: string, data: unknown): void {
+        this.#connections.forEach(conn => this.send(conn, { type, data }))
+    }
+
+    get size(): number {
+        return this.#connections.size
+    }
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { RpcRequest, RpcResponse } from '@greendrake/rpc'
+
+// Who is calling, as the application's resolver reports it. `userId` is opaque
+// — the application's own id type — and null for a caller no credential named,
+// which is the one thing every auth rule but 'none' turns away.
+export interface AuthInfo {
+    userId: unknown
+    isAdmin: boolean
+    phantom: boolean
+}
+
+// The principal a request carries until a credential says otherwise. Not a
+// stand-in for "unknown": a resolver that ran and matched nothing yields this
+// too, because a token nobody recognises makes its bearer a stranger, not an
+// error.
+export const ANONYMOUS: AuthInfo = {
+    userId: null,
+    isAdmin: false,
+    phantom: false
+}
+
+// Turns a credential into a principal, or null where it names nobody. What a
+// method then requires of that principal is the dispatcher's business, so this
+// never refuses: it only reports.
+export interface AuthResolver {
+    resolveToken(token: string, signal: AbortSignal): Promise<AuthInfo | null>
+}
+
+// Replay protection for the calls that carry a nonce: true the first time one
+// is seen, false for a repeat.
+export interface NonceStore {
+    checkAndSet(nonce: string): Promise<boolean>
+}
+
+// Maps the language tag a client asked for onto one the application actually
+// ships. Which locales exist and how a near miss resolves is the application's
+// policy; this package only carries the value.
+export type LocaleResolver = (requested: string | undefined) => string
+
+// What the transport knows about a call before it dispatches.
+export interface CallContext {
+    auth: AuthInfo
+    clientIp: string
+    // Aborted when the caller goes away — an HTTP client disconnecting, a
+    // WebSocket closing. Handlers pass it to whatever I/O they do, so work
+    // nobody is waiting for is abandoned rather than run to completion.
+    signal: AbortSignal
+}
+
+export interface HandlerContext extends CallContext {
+    // Empty unless the dispatcher was given a LocaleResolver.
+    locale: string
+}
+
+export type AuthRequirement = 'none' | 'user' | 'admin'
+
+// One method: what it requires of the caller, what shape its argument has, and
+// what runs. `A` defaults to void — a method with no `args` schema takes none,
+// and ClientMethods turns that into a zero-argument call.
+export interface MethodDef<A = void, R = unknown> {
+    auth: AuthRequirement
+    // Let a phantom — a provisional principal the application has not fully
+    // registered — through. Off by default: a method reached by one says so.
+    allowPhantom?: boolean
+    // Validates the single argument and types the handler's. Any Standard
+    // Schema validator (zod, valibot, arktype) qualifies; failures answer
+    // INVALID_ARGUMENT with the per-field issues in `error_details`.
+    args?: StandardSchemaV1<unknown, A>
+    // Declared as a method rather than a property so the map below can hold
+    // definitions of every argument type: parameter bivariance is what makes a
+    // MethodDef<Something> a MethodDef<unknown>.
+    handler(ctx: HandlerContext, args: A): R | Promise<R>
+}
+
+// A dispatch table. The erased argument type is what every concrete MethodDef
+// widens to, so a table mixing schemas and bare methods is one value.
+export type Methods = Record<string, MethodDef<unknown, unknown>>
+
+// Identity at runtime; inference is its whole job. A definition written inline
+// in a table has nowhere to get its argument type from — the table's own type
+// erases it — so the schema's output reaches the handler's parameter through
+// this. A definition with no schema takes no argument, and says so.
+export const method = <A = void, R = unknown>(def: MethodDef<A, R>): MethodDef<A, R> => def
+
+type MethodArgs<A> = [A] extends [void] ? [] : [args: A]
+
+// The client-side view of a dispatch table: the method map a dashboard hands
+// `ApiClient<…>`, derived from the definitions rather than restated beside
+// them. The pair's typing meets here — a method whose argument shape or result
+// changes server-side stops compiling in the frontend that calls it.
+export type ClientMethods<M extends Methods> = {
+    [K in keyof M]: M[K] extends MethodDef<infer A, infer R> ? (...args: MethodArgs<A>) => Awaited<R> : never
+}
+
+// The WebSocket transport's additions to the wire: an id correlating a
+// response with its request, and the frames the server pushes unasked.
+export interface WsResponse extends RpcResponse {
+    type: 'response'
+    id?: string
+}
+
+export interface EventFrame {
+    type: 'event'
+    event: string
+    data: unknown
+}
+
+export interface DataFrame {
+    type: string
+    data: unknown
+}
+
+// The wire types both halves share, re-exported so a server's modules have one
+// place to import from.
+export type { Codec, RpcRequest, RpcResponse } from '@greendrake/rpc'
+
+// Everything that goes out on a socket, so the registry's send path is typed
+// rather than `unknown`.
+export type ServerFrame = WsResponse | EventFrame | DataFrame
+
+// A request as it arrives: the shared envelope plus the WebSocket's id.
+export interface IncomingRequest extends RpcRequest {
+    id?: string
+}

package/src/ws.ts

@@ -0,0 +1,144 @@
+import type { Server, WebSocketHandler } from 'bun'
+import { unwrapArguments } from './arguments'
+import type { Dispatcher } from './dispatcher'
+import { clientIp } from './http'
+import type { Connection, ConnectionData, ConnRegistry } from './registry'
+import { ANONYMOUS } from './types'
+import type { AuthInfo, IncomingRequest, RpcResponse } from './types'
+
+export interface WebSocketHandlerOptions {
+    // Run once the socket can be written to. A service that greets a new
+    // connection with its current state does it here.
+    onOpen?: (conn: Connection) => void
+    // Run when the socket has gone, before it leaves the registry.
+    onClose?: (conn: Connection) => void
+}
+
+export interface RpcWebSocket {
+    // Resolves the handshake credential and hands the socket to Bun. False
+    // when Bun refused the upgrade, which is the fetch handler's cue to answer
+    // the request itself.
+    upgrade(request: Request, server: Server<ConnectionData>): Promise<boolean>
+    // Pass to `Bun.serve`'s `websocket`.
+    handlers: WebSocketHandler<ConnectionData>
+}
+
+// The credential a socket presents at the handshake, as a query parameter —
+// the only channel a browser's WebSocket constructor leaves open, having no
+// headers. Reconnects carry it again for free, which is why a dashboard with a
+// static key needs no in-band handshake at all.
+const TOKEN_PARAM = 'token'
+
+// The WebSocket transport: many calls over one socket, correlated by id, plus
+// the pushes the server sends unasked. Requests dispatch concurrently — a slow
+// one must not hold up the socket — with one exception, below.
+export const websocketHandler = (dispatcher: Dispatcher, registry: ConnRegistry, options: WebSocketHandlerOptions = {}): RpcWebSocket => {
+    const reply = (conn: Connection, id: string | undefined, response: RpcResponse): void =>
+        registry.send(conn, {
+            type: 'response',
+            id,
+            ...response
+        })
+
+    // Who the connection is from here on: the index follows, and the frame that
+    // asked is answered once it does.
+    const bindAs = (conn: Connection, request: IncomingRequest, auth: AuthInfo): void => {
+        conn.data.auth = auth
+        registry.register(conn)
+        reply(conn, request.id, { success: true })
+    }
+
+    const authenticate = async (conn: Connection, request: IncomingRequest): Promise<void> => {
+        if (!dispatcher.auth) {
+            reply(conn, request.id, { success: false, error: 'AUTH_NOT_CONFIGURED' })
+            return
+        }
+        const token = unwrapArguments(request.arguments)
+        if (typeof token !== 'string') {
+            reply(conn, request.id, { success: false, error: 'INVALID_ARGUMENT' })
+            return
+        }
+        const auth = await dispatcher.auth.resolveToken(token, conn.data.controller.signal)
+        if (!auth || auth.userId === null) {
+            reply(conn, request.id, { success: false, error: 'UNAUTHENTICATED' })
+            return
+        }
+        bindAs(conn, request, auth)
+    }
+
+    const logout = (conn: Connection, request: IncomingRequest): void => bindAs(conn, request, ANONYMOUS)
+
+    // The frames that change who a connection is, rather than asking it to do
+    // something. @greendrake/rpc's WsTransport sends exactly these. A Map, so a
+    // client naming an inherited property does not reach a function.
+    const authFrames = new Map<string, (conn: Connection, request: IncomingRequest) => void | Promise<void>>([
+        ['auth.token', authenticate],
+        ['auth.logout', logout]
+    ])
+
+    return {
+        async upgrade(request, server) {
+            const token = new URL(request.url).searchParams.get(TOKEN_PARAM)
+            const resolved = token && dispatcher.auth ? await dispatcher.auth.resolveToken(token, request.signal) : null
+            const data: ConnectionData = {
+                auth: resolved ?? ANONYMOUS,
+                controller: new AbortController(),
+                clientIp: clientIp(request, server),
+                gate: Promise.resolve()
+            }
+            return server.upgrade(request, { data })
+        },
+        handlers: {
+            open(conn) {
+                registry.register(conn)
+                options.onOpen?.(conn)
+            },
+            message(conn, raw) {
+                let request: IncomingRequest
+                try {
+                    request = JSON.parse(registry.codec.decode(String(raw))) as IncomingRequest
+                } catch {
+                    reply(conn, undefined, { success: false, error: 'INVALID_JSON' })
+                    return
+                }
+                const bind = authFrames.get(request.method)
+                if (bind) {
+                    // An auth frame changes who every later call on this socket
+                    // is made by, so it goes on the gate the calls wait behind:
+                    // a request sent right after one must not race it and come
+                    // back UNAUTHENTICATED. The chain is kept fulfilled — a
+                    // rejected gate would silently strand every frame behind it.
+                    conn.data.gate = conn.data.gate
+                        .then(() => bind(conn, request))
+                        .catch((e: unknown) => {
+                            console.error(`[rpc-server] ${request.method}:`, e)
+                            reply(conn, request.id, { success: false, error: 'INTERNAL_ERROR' })
+                        })
+                    return
+                }
+                void conn.data.gate
+                    .then(() =>
+                        dispatcher.dispatch(request, {
+                            auth: conn.data.auth,
+                            clientIp: conn.data.clientIp,
+                            signal: conn.data.controller.signal
+                        })
+                    )
+                    .then(response => {
+                        // The socket went while the handler ran: the response
+                        // has nowhere to go, and Bun would throw writing it.
+                        if (!conn.data.controller.signal.aborted) {
+                            reply(conn, request.id, response)
+                        }
+                    })
+            },
+            close(conn) {
+                // Every handler still running on this socket learns its caller
+                // is gone, and abandons whatever I/O it is waiting on.
+                conn.data.controller.abort()
+                options.onClose?.(conn)
+                registry.unregister(conn)
+            }
+        }
+    }
+}