@greendrake/rpc-server 0.7.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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 — events, and the state documents every socket keeps. **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
 
@@ -63,7 +63,7 @@ interface MethodDef<A = void, R = unknown> {
 
 `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.
+`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. It also carries `topics`, the calling socket's subscriptions (see [Pushing](#pushing)), which is `null` for a call that came over HTTP.
 
 ### Argument validation
 
@@ -101,13 +101,15 @@ A request carrying a `nonce` runs once: `NonceStore.checkAndSet` answers false f
 
 `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.
 
+Nothing pushed is ever dropped. Bun drops a frame once a socket's send buffer passes its `backpressureLimit`; `handlers` sets `closeOnBackpressureLimit`, so such a socket is closed instead. A client that has stopped reading would otherwise be left silently wrong. Once it reconnects, its re-read (`liveBinding`) or the documents it is greeted with put it right.
+
 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:
+`ConnRegistry` holds every open socket and indexes them by principal and by [topic](#topics):
 
 ```ts
 registry.emitToUser(userId, 'thread.updated', { id })  // {type:'event', event, data} to that user's sockets
@@ -117,6 +119,50 @@ 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` subscribes to these, folds each push in or re-reads, and re-reads again after a dropped socket returns.
 
+### Documents
+
+State the whole service shares, kept current on every socket, is a document rather than a stream of events:
+
+```ts
+const cameras = registry.document('cameras', () => fleet.states()) // { gate: {…}, porch: {…} }
+
+fleet.onChange(() => cameras.refresh())
+```
+
+- **Greeting.** `document(type, produce)` produces the state now, and every socket that opens is sent it whole: `{type, data: {doc}}`.
+- **Patches.** Each `refresh()` produces the state again and sends every socket the RFC 7386 merge patch from the last one: `{type, data: {patch}}`. Objects merge, `null` removes a member, and anything else replaces, so collections are objects keyed by id. Nothing is sent when nothing changed, so a producer calls `refresh` on any change it knows of.
+- **Shape.** The state must be a JSON object, or `document` throws. A member produced as `null` is dropped, the same as one left out, since a patch could not tell the two apart.
+- **Ordering.** Sends are synchronous, so no patch can precede or overtake a socket's document.
+
+On the client, `@greendrake/rpc`'s `liveDocument` keeps the document. A reconnect is greeted with it afresh, so no re-read is needed.
+
+### Topics
+
+For state only the sockets that asked for it want — one record's changes, followed by whoever has it open — a socket joins a topic, and the application publishes to the topic:
+
+```ts
+const methods = {
+    'thing.watch': method({
+        auth: 'user',
+        args: z.object({ id: z.string() }),
+        handler: (ctx, { id }) => {
+            topicsOf(ctx).join(`thing:${id}`)
+            return things.get(id)
+        }
+    }),
+    'thing.unwatch': method({
+        auth: 'user',
+        args: z.object({ id: z.string() }),
+        handler: (ctx, { id }) => topicsOf(ctx).leave(`thing:${id}`)
+    })
+}
+
+registry.publish(`thing:${id}`, 'thing.changed', thing) // {type:'event', event, data} to every socket in the topic
+registry.topics() // the topics with at least one socket in them
+```
+
+A handler joins and leaves for its own caller, through `ctx.topics`; only the transport knows which socket a call came in on. `topicsOf(ctx)` is that, or `WEBSOCKET_REQUIRED` for a call that came over HTTP, where there is no connection to push to. A socket is in a topic until it leaves it or closes, and a handler that joins after its caller has gone joins nothing. A topic is whatever string the application makes it; a reconnecting client is a new socket and joins again, which `liveBinding`'s re-read on reconnect is the natural place to do.
+
 The registry is also an `Audience`: `size` is how many sockets are open, and `onPresence(listener)` calls the listener with `true` as the first one opens and `false` as the last one closes, returning the function that stops it. It is for a producer whose pushes cost something to produce — a reading taken from somewhere slow — and are worth producing only while somebody is connected to be told.
 
 ## Error codes
@@ -134,6 +180,7 @@ Codes, not sentences: the client keys on them. A handler's own outcomes are `thr
 | `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 |
+| `WEBSOCKET_REQUIRED` | a method that subscribes its caller was called over HTTP (`topicsOf`) |
 | `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.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/rpc-server",
-    "version": "0.7.0",
+    "version": "0.9.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>",
@@ -34,7 +34,7 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "dependencies": {
-        "@greendrake/rpc": "0.7.0",
+        "@greendrake/rpc": "^0.9.0",
         "@standard-schema/spec": "^1.1.0"
     },
     "devDependencies": {

package/src/http.ts

@@ -55,7 +55,9 @@ export const httpHandler = (dispatcher: Dispatcher, options: HttpHandlerOptions
             await dispatcher.dispatch(parsed, {
                 auth,
                 clientIp: ip,
-                signal: request.signal
+                signal: request.signal,
+                // One request, one response, and no connection left to push to.
+                topics: null
             })
         )
     }

package/src/main.ts

@@ -1,4 +1,4 @@
-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 { ANONYMOUS, method, topicsOf, 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 Topics, type WsResponse } from './types'
 export { ApiError } from './errors'
 export { unwrapArguments, validateArguments } from './arguments'
 export { createDispatcher, type Dispatcher, type DispatcherOptions } from './dispatcher'
@@ -6,5 +6,5 @@ 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 Audience, type Connection, type ConnectionData, type EventSink } from './registry'
+export { ConnRegistry, type Audience, type Connection, type ConnectionData, type Document, type EventSink } from './registry'
 export type { Codec, RpcRequest, RpcResponse } from './types'

package/src/registry.ts

@@ -1,6 +1,6 @@
 import type { ServerWebSocket } from 'bun'
-import { identityCodec } from '@greendrake/rpc'
-import type { AuthInfo, Codec, ServerFrame } from './types'
+import { documentOf, identityCodec, mergePatchBetween, type JsonObject } from '@greendrake/rpc'
+import type { AuthInfo, Codec, EventFrame, ServerFrame } from './types'
 
 // Per-socket state, carried as Bun's websocket `data`.
 export interface ConnectionData {
@@ -26,6 +26,15 @@ export interface EventSink {
     broadcastEvent(event: string, data: unknown): void
 }
 
+// What a producer holds of its document: publishing it is the producer's whole part.
+export interface Document {
+    // Publishes the state as `produce` now has it: what changed since it was last
+    // published goes to every socket as one patch, and nothing goes when nothing
+    // changed. So a producer calls it on any change it knows of; a call too many
+    // costs a diff.
+    refresh(): void
+}
+
 // Whether anybody is connected to hear a broadcast, for a producer whose
 // pushes cost something to produce — a reading taken from somewhere slow —
 // and are worth producing only while somebody is there to be told.
@@ -37,18 +46,64 @@ export interface Audience {
     onPresence(listener: (present: boolean) => void): () => void
 }
 
+// One entry of a one-to-many index. A key is present exactly while something is
+// under it, so an index never holds a set for a key with nothing left in it.
+const addTo = <K, V>(index: Map<K, Set<V>>, key: K, value: V): void => {
+    const under = index.get(key)
+    if (under) {
+        under.add(value)
+    } else {
+        index.set(key, new Set([value]))
+    }
+}
+
+const removeFrom = <K, V>(index: Map<K, Set<V>>, key: K, value: V): void => {
+    const under = index.get(key)
+    if (!under) {
+        return
+    }
+    under.delete(value)
+    if (under.size === 0) {
+        index.delete(key)
+    }
+}
+
+const eventFrame = (event: string, data: unknown): EventFrame => ({
+    type: 'event',
+    event,
+    data
+})
+
+// A document the registry publishes: what it is called on the wire, and the state as
+// last published, which is what an opening socket is sent.
+interface Published {
+    type: string
+    doc: JsonObject
+}
+
 // 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.
+//
+// And the topics sockets have joined: subscriptions a method takes out for its
+// caller (see Topics), published to by the application and dropped with the
+// socket.
+//
+// And the documents every socket keeps (see document()).
 export class ConnRegistry implements EventSink, Audience {
     readonly #connections = new Set<Connection>()
+    readonly #documents: Published[] = []
     readonly #presence = new Set<(present: boolean) => void>()
     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>()
+    // A topic's sockets, and a socket's topics: the second so a closing socket
+    // leaves every topic it is in without a search through all of them.
+    readonly #topicMembers = new Map<string, Set<Connection>>()
+    readonly #joined = new Map<Connection, Set<string>>()
     // Public because the WebSocket handler decodes inbound frames with it:
     // one codec governs the socket in both directions, and it is configured
     // here, once.
@@ -64,6 +119,9 @@ export class ConnRegistry implements EventSink, Audience {
     register(conn: Connection): void {
         const arriving = !this.#connections.has(conn)
         this.#connections.add(conn)
+        if (arriving) {
+            this.#documents.forEach(published => this.#greet(conn, published))
+        }
         if (arriving && this.#connections.size === 1) {
             this.#presence.forEach(listener => listener(true))
         }
@@ -75,23 +133,50 @@ export class ConnRegistry implements EventSink, Audience {
         if (userId === null) {
             return
         }
-        let bound = this.#byUser.get(userId)
-        if (!bound) {
-            bound = new Set()
-            this.#byUser.set(userId, bound)
-        }
-        bound.add(conn)
+        addTo(this.#byUser, userId, conn)
         this.#filedUnder.set(conn, userId)
     }
 
     unregister(conn: Connection): void {
         const leaving = this.#connections.delete(conn)
         this.#unfile(conn)
+        // A copy: leaving a topic takes it out of the set being walked.
+        for (const topic of [...(this.#joined.get(conn) ?? [])]) {
+            this.leave(conn, topic)
+        }
         if (leaving && this.#connections.size === 0) {
             this.#presence.forEach(listener => listener(false))
         }
     }
 
+    // Puts the socket in the topic, for publish to reach. A socket that has
+    // already closed joins nothing: a handler can outlive its caller, and a
+    // membership taken after the close would be a dead socket published to for
+    // as long as the process runs.
+    join(conn: Connection, topic: string): void {
+        if (!this.#connections.has(conn)) {
+            return
+        }
+        addTo(this.#topicMembers, topic, conn)
+        addTo(this.#joined, conn, topic)
+    }
+
+    leave(conn: Connection, topic: string): void {
+        removeFrom(this.#topicMembers, topic, conn)
+        removeFrom(this.#joined, conn, topic)
+    }
+
+    // To every socket in the topic, whoever it is bound as — for state only the
+    // sockets that asked for it want.
+    publish(topic: string, event: string, data: unknown): void {
+        this.#topicMembers.get(topic)?.forEach(conn => this.send(conn, eventFrame(event, data)))
+    }
+
+    // The topics with at least one socket in them, as they are now.
+    topics(): ReadonlySet<string> {
+        return new Set(this.#topicMembers.keys())
+    }
+
     onPresence(listener: (present: boolean) => void): () => void {
         this.#presence.add(listener)
         return () => {
@@ -105,14 +190,7 @@ export class ConnRegistry implements EventSink, Audience {
         }
         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)
-        }
+        removeFrom(this.#byUser, userId, conn)
     }
 
     // The one place a frame becomes bytes: responses and pushes leave a socket
@@ -126,23 +204,13 @@ export class ConnRegistry implements EventSink, Audience {
     }
 
     emitToUser(userId: unknown, event: string, data: unknown): void {
-        this.sendToUser(userId, {
-            type: 'event',
-            event,
-            data
-        })
+        this.sendToUser(userId, eventFrame(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
-            })
-        )
+        this.#connections.forEach(conn => this.send(conn, eventFrame(event, data)))
     }
 
     // The bare `{type, data}` form, for a push whose own type names the
@@ -151,6 +219,38 @@ export class ConnRegistry implements EventSink, Audience {
         this.#connections.forEach(conn => this.send(conn, { type, data }))
     }
 
+    // A state stream: the whole of some state as one JSON object, kept by every
+    // socket. A socket is sent the document as last published when it opens,
+    // `{type, data: {doc}}`, and each change after that as an RFC 7386 merge
+    // patch over it, `{type, data: {patch}}` — objects merge, null removes a
+    // member, anything else replaces — so what it holds is always the document.
+    // A member produced as null is dropped, the same as one left out, a patch
+    // being unable to tell the two apart (`@greendrake/rpc`'s documentOf, which
+    // the client end shares). `produce` runs now, so every greeting has a
+    // document, and again on each refresh. A state that is no JSON object
+    // throws. Sends are synchronous, so no patch can precede or overtake a
+    // socket's document.
+    document(type: string, produce: () => object): Document {
+        const published: Published = { type, doc: documentOf(type, produce()) }
+        this.#documents.push(published)
+        this.#connections.forEach(conn => this.#greet(conn, published))
+        return {
+            refresh: () => {
+                const next = documentOf(type, produce())
+                const patch = mergePatchBetween(published.doc, next)
+                if (!patch) {
+                    return
+                }
+                published.doc = next
+                this.#connections.forEach(conn => this.send(conn, { type, data: { patch } }))
+            }
+        }
+    }
+
+    #greet(conn: Connection, published: Published): void {
+        this.send(conn, { type: published.type, data: { doc: published.doc } })
+    }
+
     get size(): number {
         return this.#connections.size
     }

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { RpcRequest, RpcResponse } from '@greendrake/rpc'
+import { ApiError } from './errors'
 
 // 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,
@@ -38,6 +39,13 @@ export interface NonceStore {
 // policy; this package only carries the value.
 export type LocaleResolver = (requested: string | undefined) => string
 
+// The calling socket's topic memberships: what a method that subscribes its
+// caller to something joins it to, and leaves. See ConnRegistry's topics.
+export interface Topics {
+    join(topic: string): void
+    leave(topic: string): void
+}
+
 // What the transport knows about a call before it dispatches.
 export interface CallContext {
     auth: AuthInfo
@@ -46,6 +54,9 @@ export interface CallContext {
     // 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
+    // The caller's socket, for a method that subscribes it. Null for a call
+    // that came over HTTP: there is no connection to push to afterwards.
+    topics: Topics | null
 }
 
 export interface HandlerContext extends CallContext {
@@ -77,6 +88,16 @@ export interface MethodDef<A = void, R = unknown> {
 // widens to, so a table mixing schemas and bare methods is one value.
 export type Methods = Record<string, MethodDef<unknown, unknown>>
 
+// The caller's socket, for a method that is nothing without one: a call that
+// came over HTTP is refused with WEBSOCKET_REQUIRED rather than subscribed to
+// pushes it has no connection to receive.
+export const topicsOf = (ctx: CallContext): Topics => {
+    if (ctx.topics === null) {
+        throw new ApiError('WEBSOCKET_REQUIRED')
+    }
+    return ctx.topics
+}
+
 // 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

package/src/ws.ts

@@ -7,8 +7,8 @@ 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.
+    // Run once the socket can be written to, after the registry has greeted it
+    // with every document.
     onOpen?: (conn: Connection) => void
     // Run when the socket has gone, before it leaves the registry.
     onClose?: (conn: Connection) => void
@@ -89,6 +89,11 @@ export const websocketHandler = (dispatcher: Dispatcher, registry: ConnRegistry,
             return server.upgrade(request, { data })
         },
         handlers: {
+            // A socket whose client has stopped reading, once its send buffer
+            // passes Bun's backpressure limit, is closed rather than having its
+            // frames dropped: a frame lost would leave the client silently wrong,
+            // and a closed socket reconnects to be greeted afresh.
+            closeOnBackpressureLimit: true,
             open(conn) {
                 registry.register(conn)
                 options.onOpen?.(conn)
@@ -121,7 +126,11 @@ export const websocketHandler = (dispatcher: Dispatcher, registry: ConnRegistry,
                         dispatcher.dispatch(request, {
                             auth: conn.data.auth,
                             clientIp: conn.data.clientIp,
-                            signal: conn.data.controller.signal
+                            signal: conn.data.controller.signal,
+                            topics: {
+                                join: topic => registry.join(conn, topic),
+                                leave: topic => registry.leave(conn, topic)
+                            }
                         })
                     )
                     .then(response => {