@greendrake/rpc-server 0.7.0 → 0.8.0

package/README.md

@@ -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
 
@@ -107,7 +107,7 @@ A codec applies to everything on the wire, in both directions, for a service who
 
 ## 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 +117,33 @@ 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.
 
+### 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 +161,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.8.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.8.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'

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 type { AuthInfo, Codec, EventFrame, ServerFrame } from './types'
 
 // Per-socket state, carried as Bun's websocket `data`.
 export interface ConnectionData {
@@ -37,10 +37,42 @@ 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
+})
+
 // 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.
 export class ConnRegistry implements EventSink, Audience {
     readonly #connections = new Set<Connection>()
     readonly #presence = new Set<(present: boolean) => void>()
@@ -49,6 +81,10 @@ export class ConnRegistry implements EventSink, Audience {
     // 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.
@@ -75,23 +111,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 +168,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 +182,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

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

@@ -121,7 +121,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 => {