@greendrake/rpc-server 0.5.0 → 0.6.0

package/README.md

@@ -117,6 +117,8 @@ 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.
 
+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
 
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/rpc-server",
-    "version": "0.5.0",
+    "version": "0.6.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,11 +34,11 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "dependencies": {
-        "@greendrake/rpc": "0.5.0",
+        "@greendrake/rpc": "0.6.0",
         "@standard-schema/spec": "^1.1.0"
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.5.0",
+        "@greendrake/dev-config": "0.6.0",
         "@types/bun": "^1.3.5",
         "typescript": "6.0.3"
     }

package/src/main.ts

@@ -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 Connection, type ConnectionData, type EventSink } from './registry'
+export { ConnRegistry, type Audience, type Connection, type ConnectionData, type EventSink } from './registry'
 export type { Codec, RpcRequest, RpcResponse } from './types'

package/src/registry.ts

@@ -26,12 +26,24 @@ export interface EventSink {
     broadcastEvent(event: string, data: unknown): 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.
+export interface Audience {
+    // How many sockets are open.
+    readonly size: number
+    // Called with true as the first socket opens and false as the last one
+    // closes. The function returned stops the calls.
+    onPresence(listener: (present: boolean) => void): () => 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 {
+export class ConnRegistry implements EventSink, Audience {
     readonly #connections = new Set<Connection>()
+    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
@@ -50,7 +62,11 @@ export class ConnRegistry implements EventSink {
     // called when a socket opens and again whenever an auth frame changes who
     // it is.
     register(conn: Connection): void {
+        const arriving = !this.#connections.has(conn)
         this.#connections.add(conn)
+        if (arriving && this.#connections.size === 1) {
+            this.#presence.forEach(listener => listener(true))
+        }
         const userId = conn.data.auth.userId
         if (this.#filedUnder.get(conn) === userId) {
             return
@@ -69,8 +85,18 @@ export class ConnRegistry implements EventSink {
     }
 
     unregister(conn: Connection): void {
-        this.#connections.delete(conn)
+        const leaving = this.#connections.delete(conn)
         this.#unfile(conn)
+        if (leaving && this.#connections.size === 0) {
+            this.#presence.forEach(listener => listener(false))
+        }
+    }
+
+    onPresence(listener: (present: boolean) => void): () => void {
+        this.#presence.add(listener)
+        return () => {
+            this.#presence.delete(listener)
+        }
     }
 
     #unfile(conn: Connection): void {