@lovrozagar/honey 0.6.8 → 0.7.1

package/src/realtime/bus.ts

@@ -1,11 +1,34 @@
+/**
+ * In-process topic bus behind `app.realtime()`. Topics are opaque keys here; the realtime server
+ * namespaces them per route before they reach the bus. Each publish serializes its payload once and
+ * hands every subscriber the same JSON text frame.
+ */
 export interface RealtimeBus {
 	subscribe(connId: string, topic: string): void
 	unsubscribe(connId: string, topic: string): void
 	unsubscribeAll(connId: string): void
+	/** Serialize `data` once and deliver the frame to every subscriber of `topic`. Throws when `data` is not JSON-serializable. */
 	publish(topic: string, data: unknown): void
-	onMessage(connId: string, handler: (data: unknown) => void): void
+	/** Deliver an already-serialized frame to every subscriber of `topic`. */
+	publishFrame(topic: string, frame: string): void
+	onMessage(connId: string, handler: (frame: string) => void): void
 	removeHandler(connId: string): void
 	presence(topic: string): string[]
+	/** Number of topics `connId` is subscribed to. */
+	topicCount(connId: string): number
+	isSubscribed(connId: string, topic: string): boolean
+}
+
+/**
+ * The wire format of the shipped bus: every frame, in both directions, is one JSON text.
+ * Throws a `TypeError` for values JSON cannot represent (`undefined`, functions, symbols, BigInt, cycles).
+ */
+export function encodeRealtimeFrame(data: unknown): string {
+	const frame = JSON.stringify(data) as string | undefined
+	if (frame === undefined) {
+		throw new TypeError(`realtime payload is not JSON-serializable (got ${typeof data})`)
+	}
+	return frame
 }
 
 export function createBus(): RealtimeBus {
@@ -13,8 +36,8 @@ export function createBus(): RealtimeBus {
 	const topicSubs = new Map<string, Set<string>>()
 	/* connId -> set of topics it is subscribed to (reverse lookup for unsubscribeAll) */
 	const connTopics = new Map<string, Set<string>>()
-	/* connId -> message handler */
-	const handlers = new Map<string, (data: unknown) => void>()
+	/* connId -> frame sink */
+	const handlers = new Map<string, (frame: string) => void>()
 
 	function subscribe(connId: string, topic: string): void {
 		let subs = topicSubs.get(topic)
@@ -60,22 +83,27 @@ export function createBus(): RealtimeBus {
 		connTopics.delete(connId)
 	}
 
-	function publish(topic: string, data: unknown): void {
+	function publishFrame(topic: string, frame: string): void {
 		const subs = topicSubs.get(topic)
 		if (!subs) return
 
-		for (const connId of subs) {
+		/* snapshot: a sink that closes its connection unsubscribes while we iterate */
+		for (const connId of Array.from(subs)) {
 			const handler = handlers.get(connId)
 			if (!handler) continue
 			try {
-				handler(data)
+				handler(frame)
 			} catch {
-				/* swallow — error isolation: one broken handler must not block others */
+				/* sinks are internal and contain their own errors; one must never block the others */
 			}
 		}
 	}
 
-	function onMessage(connId: string, handler: (data: unknown) => void): void {
+	function publish(topic: string, data: unknown): void {
+		publishFrame(topic, encodeRealtimeFrame(data))
+	}
+
+	function onMessage(connId: string, handler: (frame: string) => void): void {
 		handlers.set(connId, handler)
 	}
 
@@ -89,5 +117,24 @@ export function createBus(): RealtimeBus {
 		return [...subs]
 	}
 
-	return { onMessage, presence, publish, removeHandler, subscribe, unsubscribe, unsubscribeAll }
+	function topicCount(connId: string): number {
+		return connTopics.get(connId)?.size ?? 0
+	}
+
+	function isSubscribed(connId: string, topic: string): boolean {
+		return connTopics.get(connId)?.has(topic) ?? false
+	}
+
+	return {
+		isSubscribed,
+		onMessage,
+		presence,
+		publish,
+		publishFrame,
+		removeHandler,
+		subscribe,
+		topicCount,
+		unsubscribe,
+		unsubscribeAll,
+	}
 }

package/src/realtime/register.ts

@@ -0,0 +1,13 @@
+/**
+ * `import "@lovrozagar/honey/realtime"` makes `app.realtime()` available. The core never
+ * imports the realtime server, so an app without realtime routes does not bundle it.
+ */
+import { registerFeature } from "../feature-slots.ts"
+import { createBus } from "./bus.ts"
+import { resolveRealtimeConfig } from "./route.ts"
+import { createRealtimePublisher, createRealtimeSession } from "./server.ts"
+
+registerFeature("realtime", { createBus, createRealtimePublisher, createRealtimeSession, resolveRealtimeConfig })
+
+export type { ConnContext, RealtimeLimits, RealtimeRouteOpts } from "./route.ts"
+export type { RealtimePublisher } from "./server.ts"

package/src/realtime/route.ts

@@ -1,104 +1,153 @@
+import { validateOriginPolicy, type WSOriginPolicy } from "../ws-origin.ts"
+
+/**
+ * One realtime connection as the route handler sees it. Only the WebSocket transport ships.
+ * Every frame, in both directions, is one JSON text (see the README's realtime wire format).
+ */
 export type ConnContext = {
 	readonly id: string
+	/** What the route's `identify(ctx)` returned, else `null`. */
 	readonly userId: string | null
-	readonly transport: "ws" | "sse" | "longpoll"
+	readonly transport: "ws"
+	/** `true` once the connection closed (or `close()` was called). `join` and `send` are then no-ops. */
+	readonly closed: boolean
 	readonly state: Record<string, unknown>
+	/** Subscribe to `topic` in this route's namespace. Throws past `limits.maxTopics`. */
 	join(topic: string): void
 	leave(topic: string): void
+	/** Send one JSON frame to this connection. Throws when `payload` is not JSON-serializable. */
 	send(payload: unknown): void
+	/** Send one JSON frame to every connection on `topic` in this route's namespace (this one included). */
 	publish(topic: string, payload: unknown): void
+	/** Close with code 1000. A reason longer than 123 UTF-8 bytes is truncated. */
 	close(reason?: string): void
-	on(event: "message", handler: (payload: unknown) => void): void
-	on(event: "close", handler: (reason: string) => void): void
-	readonly _handlers: { message: ((payload: unknown) => void) | null; close: ((reason: string) => void) | null }
+	on(event: "message", handler: (payload: unknown) => void | Promise<void>): void
+	on(event: "close", handler: (reason: string) => void | Promise<void>): void
+}
+
+export type RealtimeLimits = {
+	/** Topics one connection may join. Default 128. */
+	maxTopics?: number
+	/** Largest inbound text frame in UTF-8 bytes; larger frames close the connection with 1009. Default 1 MiB. */
+	maxFrameBytes?: number
+	/**
+	 * Inbound frames waiting for a handler (a slow async `message` handler, or none attached yet).
+	 * Past this the connection closes with 1008. Default 64.
+	 */
+	maxPendingFrames?: number
+	/**
+	 * Outbound bytes the runtime may hold for a client that is not reading, where the runtime reports
+	 * it (`bufferedAmount`). Past this `slowConsumer` applies. Default 4 MiB.
+	 */
+	maxBufferedBytes?: number
+	/** `"close"` (default) closes a slow consumer with 1013; `"drop"` drops frames until it catches up. */
+	slowConsumer?: "close" | "drop"
 }
 
-export type RealtimeRouteOpts = {
+/** `C` is the request context of the handle `realtime()` is called on. */
+export type RealtimeRouteOpts<C = unknown> = {
 	use?: Array<(ctx: unknown, next: () => Promise<Response>) => Promise<Response>>
-	reconnectBuffer?: number
-	handler: (c: unknown, conn: ConnContext) => void | Promise<void>
+	/**
+	 * Topic namespace. Connections only see topics of their own namespace. Defaults to the route's
+	 * full path pattern, so two realtime routes never share topics unless they name the same namespace.
+	 */
+	namespace?: string
+	/** Runs after the route's middleware, before the upgrade. Its result becomes `conn.userId`; a throw rejects the upgrade. */
+	identify?: (ctx: C) => string | null | undefined | Promise<string | null | undefined>
+	/** Receives every error thrown by `handler` and the `message`/`close` handlers. Defaults to the app logger. */
+	onError?: (error: unknown, conn: ConnContext) => void | Promise<void>
+	limits?: RealtimeLimits
+	/**
+	 * Browser origins allowed to connect: `"*"`, a list (`https://app.example.com`), or a
+	 * predicate. Same-origin always passes. Unset, a cross-origin upgrade that carries `Cookie`
+	 * or `Authorization` gets 403.
+	 */
+	allowedOrigins?: WSOriginPolicy
+	handler: (c: C, conn: ConnContext) => void | Promise<void>
 }
 
-export type RealtimeRouteHandler = {
+/** A realtime route after validation, with every default applied. */
+export type RealtimeConfig = {
+	allowedOrigins: WSOriginPolicy | null
 	handler: RealtimeRouteOpts["handler"]
-	middlewares: RealtimeRouteOpts["use"]
-	reconnectBuffer: number
+	identify: NonNullable<RealtimeRouteOpts["identify"]> | null
+	limits: Required<RealtimeLimits>
+	namespace: string
+	/** false when `namespace` is the default (the route's path), which follows the route when mounted */
+	namespaceExplicit: boolean
+	onError: NonNullable<RealtimeRouteOpts["onError"]> | null
 	path: string
 }
 
-export function createConnContext(opts: {
-	id: string
-	userId: string | null
-	transport: "ws" | "sse" | "longpoll"
-	bus: {
-		subscribe(connId: string, topic: string): void
-		unsubscribe(connId: string, topic: string): void
-		unsubscribeAll(connId: string): void
-		publish(topic: string, data: unknown): void
-	}
-	sendFn: (payload: unknown) => void
-	closeFn: (reason?: string) => void
-}): ConnContext {
-	const state: Record<string, unknown> = {}
-	const handlers: { message: ((payload: unknown) => void) | null; close: ((reason: string) => void) | null } = {
-		close: null,
-		message: null,
-	}
-
-	const conn: ConnContext = Object.create(null)
-
-	Object.defineProperty(conn, "id", { enumerable: true, value: opts.id, writable: false })
-	Object.defineProperty(conn, "userId", { enumerable: true, value: opts.userId, writable: false })
-	Object.defineProperty(conn, "transport", { enumerable: true, value: opts.transport, writable: false })
-	Object.defineProperty(conn, "state", { enumerable: true, get: () => state })
-	Object.defineProperty(conn, "_handlers", { enumerable: false, get: () => handlers })
-
-	Object.defineProperty(conn, "join", {
-		enumerable: true,
-		value(topic: string) {
-			opts.bus.subscribe(opts.id, topic)
-		},
-	})
-
-	Object.defineProperty(conn, "leave", {
-		enumerable: true,
-		value(topic: string) {
-			opts.bus.unsubscribe(opts.id, topic)
-		},
-	})
-
-	Object.defineProperty(conn, "send", {
-		enumerable: true,
-		value(payload: unknown) {
-			opts.sendFn(payload)
-		},
-	})
+const DEFAULT_LIMITS: Required<RealtimeLimits> = {
+	maxBufferedBytes: 4 * 1024 * 1024,
+	maxFrameBytes: 1024 * 1024,
+	maxPendingFrames: 64,
+	maxTopics: 128,
+	slowConsumer: "close",
+}
 
-	Object.defineProperty(conn, "publish", {
-		enumerable: true,
-		value(topic: string, payload: unknown) {
-			opts.bus.publish(topic, payload)
-		},
-	})
+function positiveInt(name: string, value: unknown, fallback: number): number {
+	if (value === undefined) return fallback
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+		throw new TypeError(`realtime limits.${name} must be a positive integer, got ${String(value)}`)
+	}
+	return value
+}
 
-	Object.defineProperty(conn, "close", {
-		enumerable: true,
-		value(reason?: string) {
-			opts.bus.unsubscribeAll(opts.id)
-			opts.closeFn(reason)
+/** Validate `app.realtime()` options. Options the shipped bus does not implement are rejected, not ignored. */
+export function resolveRealtimeConfig<C>(path: string, routeOpts: RealtimeRouteOpts<C>): RealtimeConfig {
+	const opts = routeOpts as unknown as RealtimeRouteOpts
+	if (typeof opts?.handler !== "function") {
+		throw new TypeError(`app.realtime("${path}"): handler must be a function`)
+	}
+	const legacy = opts as { reconnectBuffer?: unknown; transports?: unknown }
+	if (legacy.reconnectBuffer !== undefined) {
+		throw new TypeError(
+			`app.realtime("${path}"): reconnectBuffer is not supported. Realtime ships the WebSocket transport without resume; remove the option.`,
+		)
+	}
+	if (legacy.transports !== undefined) {
+		throw new TypeError(`app.realtime("${path}"): only the WebSocket transport ships; remove transports.`)
+	}
+	if (opts.namespace !== undefined && (typeof opts.namespace !== "string" || opts.namespace === "")) {
+		throw new TypeError(`app.realtime("${path}"): namespace must be a non-empty string`)
+	}
+	const l = opts.limits ?? {}
+	if (l.slowConsumer !== undefined && l.slowConsumer !== "close" && l.slowConsumer !== "drop") {
+		throw new TypeError(`realtime limits.slowConsumer must be "close" or "drop"`)
+	}
+	return {
+		allowedOrigins: opts.allowedOrigins === undefined ? null : validateOriginPolicy(opts.allowedOrigins),
+		handler: opts.handler,
+		identify: opts.identify ?? null,
+		limits: {
+			maxBufferedBytes: positiveInt("maxBufferedBytes", l.maxBufferedBytes, DEFAULT_LIMITS.maxBufferedBytes),
+			maxFrameBytes: positiveInt("maxFrameBytes", l.maxFrameBytes, DEFAULT_LIMITS.maxFrameBytes),
+			maxPendingFrames: positiveInt("maxPendingFrames", l.maxPendingFrames, DEFAULT_LIMITS.maxPendingFrames),
+			maxTopics: positiveInt("maxTopics", l.maxTopics, DEFAULT_LIMITS.maxTopics),
+			slowConsumer: l.slowConsumer ?? DEFAULT_LIMITS.slowConsumer,
 		},
-	})
+		namespace: opts.namespace ?? path,
+		namespaceExplicit: opts.namespace !== undefined,
+		onError: opts.onError ?? null,
+		path,
+	}
+}
 
-	Object.defineProperty(conn, "on", {
-		enumerable: true,
-		value(event: "message" | "close", handler: (...args: unknown[]) => void) {
-			if (event === "message") {
-				handlers.message = handler as (payload: unknown) => void
-			} else {
-				handlers.close = handler as (reason: string) => void
-			}
-		},
-	})
+const encoder = new TextEncoder()
 
-	return conn
+/** Cut `reason` to at most `max` UTF-8 bytes without splitting a code point. */
+export function truncateUtf8(reason: string, max: number): string {
+	if (reason.length * 3 <= max) return reason
+	if (encoder.encode(reason).byteLength <= max) return reason
+	let bytes = 0
+	let out = ""
+	for (const ch of reason) {
+		const n = encoder.encode(ch).byteLength
+		if (bytes + n > max) break
+		bytes += n
+		out += ch
+	}
+	return out
 }

package/src/realtime/server.ts

@@ -0,0 +1,298 @@
+import { invokeUser } from "../invoke-user.ts"
+import type { WSContext, WSHandler } from "../ws/cloudflare.ts"
+import { encodeRealtimeFrame } from "./bus.ts"
+import type { RealtimeBus } from "./bus.ts"
+import {
+	bufferedAmountOf,
+	CLOSE_INTERNAL,
+	CLOSE_NORMAL,
+	CLOSE_POLICY,
+	CLOSE_TOO_BIG,
+	CLOSE_TRY_AGAIN,
+	exceedsPayload,
+	MAX_CLOSE_REASON,
+} from "../ws/shared.ts"
+import { truncateUtf8 } from "./route.ts"
+import type { ConnContext, RealtimeConfig } from "./route.ts"
+
+type Logger = {
+	error?: (obj: Record<string, unknown>, msg?: string) => void
+	warn?: (obj: Record<string, unknown>, msg?: string) => void
+}
+
+/** `ctx.realtime` — publish into a realtime namespace from any request. */
+export type RealtimePublisher = {
+	/**
+	 * Publish to `topic` in the app's only realtime namespace. Throws when the app has several
+	 * namespaces; use `namespace(name).publish()` then.
+	 */
+	publish(topic: string, data: unknown): void
+	/** The publisher for one namespace (a route's `namespace` option, or its full path pattern). */
+	namespace(name: string): { publish(topic: string, data: unknown): void }
+}
+
+const SEP = "\u0000"
+
+/** The bus key of `topic` in namespace `ns`. Namespaces never see each other's topics. */
+export function topicKey(ns: string, topic: string): string {
+	return ns + SEP + topic
+}
+
+export function createRealtimePublisher(bus: RealtimeBus, namespaces: () => Iterable<string>): RealtimePublisher {
+	const forNs = (ns: string) => ({
+		publish(topic: string, data: unknown) {
+			bus.publish(topicKey(ns, String(topic)), data)
+		},
+	})
+	return {
+		namespace(name: string) {
+			return forNs(String(name))
+		},
+		publish(topic: string, data: unknown) {
+			const all = new Set(namespaces())
+			if (all.size !== 1) {
+				throw new Error(
+					all.size === 0
+						? "ctx.realtime.publish: the app has no realtime routes"
+						: `ctx.realtime.publish: the app has ${all.size} realtime namespaces (${[...all].join(", ")}); use ctx.realtime.namespace(name).publish(topic, data)`,
+				)
+			}
+			forNs(all.values().next().value as string).publish(topic, data)
+		},
+	}
+}
+
+export type RealtimeSession = {
+	/** The handler to pass to the runtime's WebSocket adapter. */
+	handler: WSHandler<unknown>
+	/** Attach the socket and start the connection (idempotent). Adapters that return an open socket from `upgrade()` call this right away; others get it from `onOpen`. */
+	attach(ws: WSContext<unknown>): void
+}
+
+/**
+ * One realtime connection: binds the socket to the bus and runs the route's callbacks on one ordered
+ * queue — `handler`, then each inbound frame, then `close` — each awaited. Every callback is
+ * contained: a throw or rejection goes to the route's `onError` (or the app logger) and never escapes
+ * into the runtime, so it can neither crash the process nor poison the queue.
+ */
+export function createRealtimeSession(opts: {
+	bus: RealtimeBus
+	config: RealtimeConfig
+	ctx: unknown
+	log: Logger | undefined
+	userId: string | null
+}): RealtimeSession {
+	const { bus, config, ctx, log, userId } = opts
+	const { limits, namespace } = config
+	const connId = crypto.randomUUID()
+	const state: Record<string, unknown> = {}
+
+	let socket: WSContext<unknown> | null = null
+	let closed = false
+	let tornDown = false
+	let closeRan = false
+	let onMessageFn: ((payload: unknown) => void | Promise<void>) | null = null
+	let onCloseFn: ((reason: string) => void | Promise<void>) | null = null
+
+	/* ordered queue: open → messages → close. Every inbound frame waits in `inbox` in arrival
+	 * order, including frames that beat the open or the `message` handler; a drain task delivers
+	 * them, so a frame never overtakes one that arrived before it. */
+	let queue: Promise<void> = Promise.resolve()
+	const inbox: unknown[] = []
+
+	/* the same containment as WebSocket callbacks: onError gets the error, an onError that
+	 * throws is logged and never invoked again for its own error, nothing reaches the runtime */
+	const invoke = (phase: string, fn: () => void | Promise<void>): Promise<boolean> =>
+		invokeUser(fn, {
+			fields: { connId, namespace, route: config.path },
+			log,
+			onError: config.onError ? (err) => config.onError?.(err, conn) : null,
+			phase,
+		})
+
+	const enqueue = (task: () => Promise<unknown>) => {
+		queue = queue.then(task).then(
+			() => undefined,
+			() => undefined,
+		)
+	}
+
+	/** Drop the connection from the bus. Runs exactly once, before any user close handler. */
+	const teardown = () => {
+		if (tornDown) return
+		tornDown = true
+		closed = true
+		bus.unsubscribeAll(connId)
+		bus.removeHandler(connId)
+	}
+
+	const closeSocket = (code: number, reason: string) => {
+		const ws = socket
+		teardown()
+		if (ws === null) return
+		try {
+			ws.close(code, truncateUtf8(reason, MAX_CLOSE_REASON))
+		} catch (e) {
+			log?.warn?.({ connId, err: e }, "realtime close failed")
+		}
+	}
+
+	const sendFrame = (frame: string) => {
+		const ws = socket
+		if (closed || ws === null) return
+		if (bufferedAmountOf(ws.raw) > limits.maxBufferedBytes) {
+			if (limits.slowConsumer === "drop") return
+			closeSocket(CLOSE_TRY_AGAIN, "slow consumer")
+			return
+		}
+		try {
+			ws.send(frame)
+		} catch (e) {
+			/* the socket went away between the readyState check and the write */
+			log?.warn?.({ connId, err: e }, "realtime send failed")
+		}
+	}
+
+	/* frames that arrived before the close still run; the close handler is queued after them.
+	 * Without a handler the frames stay in the inbox until one is attached, or are dropped on close. */
+	const drain = async (): Promise<void> => {
+		while (inbox.length > 0) {
+			const fn = onMessageFn
+			if (fn === null) {
+				if (closed) inbox.length = 0
+				return
+			}
+			const payload = inbox.shift()
+			await invoke("message", () => fn(payload))
+		}
+	}
+
+	const accept = (payload: unknown) => {
+		if (inbox.length >= limits.maxPendingFrames) {
+			closeSocket(CLOSE_POLICY, "too many pending frames")
+			return
+		}
+		inbox.push(payload)
+		enqueue(drain)
+	}
+
+	const conn = Object.create(null) as ConnContext
+	Object.defineProperties(conn, {
+		close: {
+			enumerable: true,
+			value(reason?: string) {
+				if (closed) return
+				closeSocket(CLOSE_NORMAL, reason === undefined ? "" : String(reason))
+			},
+		},
+		closed: { enumerable: true, get: () => closed },
+		id: { enumerable: true, value: connId },
+		join: {
+			enumerable: true,
+			value(topic: string) {
+				if (closed) return
+				const key = topicKey(namespace, String(topic))
+				if (bus.topicCount(connId) >= limits.maxTopics && !bus.isSubscribed(connId, key)) {
+					throw new RangeError(`realtime: a connection may join at most ${limits.maxTopics} topics`)
+				}
+				bus.subscribe(connId, key)
+			},
+		},
+		leave: {
+			enumerable: true,
+			value(topic: string) {
+				if (closed) return
+				bus.unsubscribe(connId, topicKey(namespace, String(topic)))
+			},
+		},
+		on: {
+			enumerable: true,
+			value(event: "message" | "close", fn: (arg: never) => void | Promise<void>) {
+				if (typeof fn !== "function") throw new TypeError("conn.on: handler must be a function")
+				if (event === "message") {
+					onMessageFn = fn as (payload: unknown) => void | Promise<void>
+					/* frames that waited for a handler run next, in arrival order */
+					if (inbox.length > 0) enqueue(drain)
+				} else if (event === "close") {
+					onCloseFn = fn as (reason: string) => void | Promise<void>
+				} else {
+					throw new TypeError(`conn.on: unknown event "${String(event)}"`)
+				}
+			},
+		},
+		/* publishing after close is allowed: a close handler announcing a departure is the common case */
+		publish: {
+			enumerable: true,
+			value(topic: string, payload: unknown) {
+				bus.publish(topicKey(namespace, String(topic)), payload)
+			},
+		},
+		send: {
+			enumerable: true,
+			value(payload: unknown) {
+				const frame = encodeRealtimeFrame(payload)
+				sendFrame(frame)
+			},
+		},
+		state: { enumerable: true, get: () => state },
+		transport: { enumerable: true, value: "ws" },
+		userId: { enumerable: true, value: userId },
+	})
+
+	const attach = (ws: WSContext<unknown>) => {
+		if (socket !== null || tornDown) return
+		socket = ws
+		bus.onMessage(connId, sendFrame)
+		enqueue(async () => {
+			const ok = await invoke("handler", () => config.handler(ctx, conn))
+			if (!ok) closeSocket(CLOSE_INTERNAL, "internal error")
+		})
+	}
+
+	const onSocketClose = (reason: string) => {
+		teardown()
+		if (closeRan) return
+		closeRan = true
+		enqueue(() => {
+			const fn = onCloseFn
+			return fn === null ? Promise.resolve() : invoke("close", () => fn(reason))
+		})
+	}
+
+	const handler: WSHandler<unknown> = {
+		onClose: (_ctx, _ws, _code, reason) => {
+			onSocketClose(reason || "normal")
+		},
+		onError: (_ctx, _ws, error) => {
+			log?.warn?.({ connId, err: error }, "realtime socket error")
+		},
+		onMessage: (_ctx, _ws, data) => {
+			if (closed) return
+			/* the wire format is JSON text; binary frames are not part of it */
+			if (typeof data !== "string") return
+			if (exceedsPayload(data, limits.maxFrameBytes)) {
+				closeSocket(CLOSE_TOO_BIG, "frame too large")
+				return
+			}
+			let payload: unknown
+			try {
+				payload = JSON.parse(data)
+			} catch {
+				/* not JSON: not a frame of this protocol */
+				return
+			}
+			if (socket === null) {
+				/* a frame before open (runtime quirk): it waits in the inbox, ahead of later frames */
+				if (inbox.length >= limits.maxPendingFrames) return
+				inbox.push(payload)
+				return
+			}
+			accept(payload)
+		},
+		onOpen: (_ctx, ws) => {
+			attach(ws)
+		},
+	}
+
+	return { attach, handler }
+}

package/src/request-id.ts

@@ -1,21 +1,31 @@
 import { namedMiddleware } from "./middleware.ts"
 import type { MiddlewareFn } from "./middleware.ts"
+import { withHeaders } from "./with-headers.ts"
 
 type RequestIdOptions = {
 	generator?: () => string
 	header?: string
+	/**
+	 * Decides whether an inbound id is reused. Default: 1–128 characters of
+	 * `A-Z a-z 0-9 . _ : + / = -` (UUIDs, ULIDs, base64, W3C trace ids).
+	 * Anything else is replaced with a generated id, so a client cannot put
+	 * arbitrary text into logs or response headers.
+	 */
+	validate?: (id: string) => boolean
 }
 
+const SAFE_ID_RE = /^[\w.:+/=-]{1,128}$/
+
 export function requestId(options?: RequestIdOptions): MiddlewareFn<{ req: Request }, { requestId: string }> {
 	const headerName = options?.header ?? "x-request-id"
 	const generate = options?.generator ?? (() => crypto.randomUUID())
+	const validate = options?.validate ?? ((id: string) => SAFE_ID_RE.test(id))
 
 	const mw: MiddlewareFn<{ req: Request }, { requestId: string }> = async (ctx, next) => {
 		const existing = ctx.req.headers.get(headerName)
-		const id = existing ?? generate()
+		const id = existing !== null && validate(existing) ? existing : generate()
 		const response = await next({ requestId: id })
-		response.headers.set(headerName, id)
-		return response
+		return withHeaders(response, (headers) => headers.set(headerName, id))
 	}
 
 	return namedMiddleware("requestId", mw)