@lovrozagar/honey 0.6.5 → 0.7.0

package/src/ws/cloudflare.ts

@@ -1,11 +1,36 @@
+import "./session.ts"
+import { invokeUser } from "../invoke-user.ts"
+import { truncateUtf8 } from "../realtime/route.ts"
 import type { WSReadyState } from "../types.ts"
+import {
+	bufferedAmountOf,
+	CLOSE_TOO_BIG,
+	CLOSE_TRY_AGAIN,
+	exceedsPayload,
+	MAX_CLOSE_REASON,
+	type ResolvedWSOptions,
+	resolveWSOptions,
+	selectProtocol,
+	sendableCloseCode,
+	type WSAdapterOptions,
+} from "./shared.ts"
+
+export type { WSAdapterOptions } from "./shared.ts"
 
 export const WS_SEND_BUFFER_MAX = 32
 
 export type WSContext<T = unknown> = {
+	/** Outbound bytes the runtime holds unsent, when it reports them (0 otherwise). Adapters' sockets have it; a hand-written stub may not. */
+	readonly bufferedAmount?: number
+	/** Close the connection. A reason longer than 123 UTF-8 bytes is cut to fit. */
 	close(code?: number, reason?: string): void
 	raw: T
 	readyState: WSReadyState
+	/**
+	 * Send a message; objects are sent as JSON. While the socket is still opening, up to 32
+	 * messages wait for it; after it closed they are dropped. Over the adapter's backpressure
+	 * limit the adapter's policy applies (close with 1013, or drop).
+	 */
 	send(data: ArrayBuffer | Uint8Array | object | string): void
 }
 
@@ -36,6 +61,10 @@ export type WSAdapter = {
 	 * and returns `response` before any middleware Promise.
 	 */
 	preUpgrade?(req: Request): WSPreUpgrade | undefined
+	/** Close every open connection (graceful shutdown). */
+	closeAll?(code: number, reason: string): void
+	/** The adapter's resolved options. */
+	readonly options?: ResolvedWSOptions
 }
 
 export type RawSocket = {
@@ -47,25 +76,35 @@ export type RawSocket = {
 export class WSContextImpl<T extends RawSocket = RawSocket> implements WSContext<T> {
 	raw: T
 	private sendBuffer: Array<ArrayBuffer | Uint8Array | string> = []
+	private readonly limits: Pick<ResolvedWSOptions, "backpressureLimit" | "backpressurePolicy"> | null
 
-	constructor(raw: T) {
+	constructor(raw: T, opts?: Pick<ResolvedWSOptions, "backpressureLimit" | "backpressurePolicy">) {
 		this.raw = raw
+		this.limits = opts ?? null
 		const target = raw as T & { addEventListener?(type: string, listener: () => void): void }
 		if (raw.readyState !== 1 && typeof target.addEventListener === "function") {
-			target.addEventListener("open", () => {
-				for (const msg of this.sendBuffer) this.raw.send(msg)
-				this.sendBuffer = []
-			})
+			target.addEventListener("open", () => this.flush())
 		}
 	}
 
+	get bufferedAmount(): number {
+		return bufferedAmountOf(this.raw)
+	}
+
 	get readyState(): WSReadyState {
 		return this.raw.readyState as WSReadyState
 	}
 
+	/** Send what was queued while the socket was opening (adapters without an `open` event call this). */
+	flush(): void {
+		const queued = this.sendBuffer
+		this.sendBuffer = []
+		for (const msg of queued) this.send(msg)
+	}
+
 	close(code?: number, reason?: string): void {
 		this.sendBuffer = []
-		this.raw.close(code, reason)
+		this.raw.close(code, reason === undefined ? undefined : truncateUtf8(reason, MAX_CLOSE_REASON))
 	}
 
 	send(data: ArrayBuffer | Uint8Array | object | string): void {
@@ -73,53 +112,76 @@ export class WSContextImpl<T extends RawSocket = RawSocket> implements WSContext
 			typeof data === "string" || data instanceof ArrayBuffer || data instanceof Uint8Array
 				? data
 				: JSON.stringify(data)
-		if (this.raw.readyState === 1) {
+		const state = this.raw.readyState
+		if (state === 1) {
+			const limits = this.limits
+			if (limits !== null && limits.backpressureLimit > 0 && this.bufferedAmount > limits.backpressureLimit) {
+				if (limits.backpressurePolicy === "close") this.close(CLOSE_TRY_AGAIN, "slow consumer")
+				return
+			}
 			this.raw.send(payload)
 			return
 		}
+		/* closing or closed: nothing will ever send it */
+		if (state !== 0) return
 		if (this.sendBuffer.length >= WS_SEND_BUFFER_MAX) this.sendBuffer.shift()
 		this.sendBuffer.push(payload)
 	}
 }
 
+/** Call an adapter event on the handler; whatever it throws is logged, never thrown into the runtime. */
+export function fireHandler(phase: string, fn: () => unknown): void {
+	void invokeUser(fn, { phase: `websocket ${phase}` })
+}
+
 /**
  * Cloudflare Workers WebSocket adapter.
- * Uses WebSocketPair + server.accept() + addEventListener.
+ * Uses WebSocketPair + server.accept() + addEventListener. `idleTimeout` is not enforced:
+ * Workers has no ping API and evicts idle sockets itself.
  */
-export function cfWebSocket(): WSAdapter {
+export function cfWebSocket(opts?: WSAdapterOptions): WSAdapter {
+	const options = resolveWSOptions(opts)
 	return {
-		upgrade(_req: Request, _env: unknown, handler: WSHandler<unknown>) {
+		options,
+		upgrade(req: Request, _env: unknown, handler: WSHandler<unknown>) {
 			type CFWebSocket = RawSocket & { accept(): void }
 			const Ctor = (globalThis as Record<string, unknown>)["WebSocketPair"] as new () => [CFWebSocket, CFWebSocket]
 			const [client, server] = new Ctor()
 			server.accept()
-			const socket = new WSContextImpl(server)
+			const socket = new WSContextImpl(server, options)
 
 			const raw = server as unknown as EventTarget & RawSocket
 			if ("addEventListener" in raw) {
 				raw.addEventListener("message", (evt: Event) => {
-					const data = (evt as MessageEvent).data
-					handler.onMessage?.(undefined, socket, data)
+					const data = (evt as MessageEvent).data as ArrayBuffer | string
+					if (exceedsPayload(data, options.maxPayload)) {
+						socket.close(CLOSE_TOO_BIG, "message too big")
+						return
+					}
+					fireHandler("message", () => handler.onMessage?.(undefined, socket, data))
 				})
 				raw.addEventListener("close", (evt: Event) => {
 					const closeEvt = evt as CloseEvent
-					handler.onClose?.(undefined, socket, closeEvt.code, closeEvt.reason)
-					/* echo close frame so the client handshake completes */
+					fireHandler("close", () => handler.onClose?.(undefined, socket, closeEvt.code, closeEvt.reason))
+					/* echo the close frame so the client's handshake completes; 1005 and 1006 are never sent */
 					try {
-						server.close(closeEvt.code, closeEvt.reason)
+						server.close(sendableCloseCode(closeEvt.code), closeEvt.reason)
 					} catch {
 						/* already closed */
 					}
 				})
 				raw.addEventListener("error", (evt: Event) => {
-					handler.onError?.(undefined, socket, evt)
+					fireHandler("error", () => handler.onError?.(undefined, socket, evt))
 				})
 			}
-			handler.onOpen?.(undefined, socket)
+			fireHandler("open", () => handler.onOpen?.(undefined, socket))
 
+			const headers: Record<string, string> = { upgrade: "websocket" }
+			const protocol = selectProtocol(req, options)
+			if (protocol !== null) headers["sec-websocket-protocol"] = protocol
 			return {
 				response: new Response(null, {
-					headers: { upgrade: "websocket" },
+					headers,
 					status: 101,
 					webSocket: client,
 				} as unknown as ResponseInit),

package/src/ws/deno.ts

@@ -1,6 +1,7 @@
 export {
 	type RawSocket,
 	type WSAdapter,
+	type WSAdapterOptions,
 	type WSContext,
 	type WSPreUpgrade,
 	WSContextImpl,
@@ -8,20 +9,34 @@ export {
 } from "./cloudflare.ts"
 
 import type { WSAdapter, WSHandler, WSPreUpgrade } from "./cloudflare.ts"
-import { WSContextImpl } from "./cloudflare.ts"
+import { fireHandler, WSContextImpl } from "./cloudflare.ts"
+import {
+	CLOSE_POLICY,
+	CLOSE_TOO_BIG,
+	exceedsPayload,
+	type ResolvedWSOptions,
+	resolveWSOptions,
+	selectProtocol,
+	type WSAdapterOptions,
+} from "./shared.ts"
+
+type DenoUpgradeOptions = { idleTimeout?: number; protocol?: string }
 
 type DenoNs = {
 	Deno: {
-		upgradeWebSocket(req: Request): {
+		upgradeWebSocket(
+			req: Request,
+			opts?: DenoUpgradeOptions,
+		): {
 			response: Response
-			socket: {
-				addEventListener(type: string, listener: (...args: never[]) => void): void
-			} & DenoRawSocket
+			socket: DenoSocket
 		}
 	}
 }
 
 type DenoRawSocket = {
+	binaryType: string
+	bufferedAmount: number
 	close(code?: number, reason?: string): void
 	readyState: number
 	send(data: ArrayBuffer | Uint8Array | string): void
@@ -31,38 +46,119 @@ type DenoSocket = {
 	addEventListener(type: string, listener: (...args: never[]) => void): void
 } & DenoRawSocket
 
-function bindHandlers(rawSocket: DenoSocket, socket: WSContextImpl<DenoRawSocket>, handler: WSHandler<unknown>): void {
-	rawSocket.addEventListener("open", () => {
-		handler.onOpen?.(undefined, socket)
-	})
-	rawSocket.addEventListener("message", (evt: { data: ArrayBuffer | string }) => {
-		handler.onMessage?.(undefined, socket, evt.data)
-	})
-	rawSocket.addEventListener("close", (evt: { code: number; reason: string }) => {
-		handler.onClose?.(undefined, socket, evt.code, evt.reason)
-	})
-	rawSocket.addEventListener("error", (evt: unknown) => {
-		handler.onError?.(undefined, socket, evt)
+/** Events that arrive before the route's handler is bound (the `preUpgrade` path). */
+const EARLY_EVENTS_MAX = 64
+
+type DenoEvent =
+	| { data: ArrayBuffer | string; type: "message" }
+	| { code: number; reason: string; type: "close" }
+	| { error: unknown; type: "error" }
+	| { type: "open" }
+
+/**
+ * Listen on a Deno socket right away and deliver events to a handler bound later. Until then up
+ * to 64 events wait (frames the client sends between the 101 and the end of the middleware
+ * chain); more close the connection with 1008.
+ */
+function listen(raw: DenoSocket, socket: WSContextImpl<DenoRawSocket>, options: ResolvedWSOptions) {
+	let handler: WSHandler<unknown> | null = null
+	let early: DenoEvent[] | null = []
+
+	const deliver = (evt: DenoEvent, h: WSHandler<unknown>): void => {
+		switch (evt.type) {
+			case "open":
+				fireHandler("open", () => h.onOpen?.(undefined, socket))
+				return
+			case "message":
+				fireHandler("message", () => h.onMessage?.(undefined, socket, evt.data))
+				return
+			case "close":
+				fireHandler("close", () => h.onClose?.(undefined, socket, evt.code, evt.reason))
+				return
+			case "error":
+				fireHandler("error", () => h.onError?.(undefined, socket, evt.error))
+		}
+	}
+
+	const push = (evt: DenoEvent): void => {
+		if (handler !== null) {
+			deliver(evt, handler)
+			return
+		}
+		if (early === null) return
+		if (early.length >= EARLY_EVENTS_MAX && evt.type === "message") {
+			early = null
+			socket.close(CLOSE_POLICY, "too many messages before the handler was ready")
+			return
+		}
+		early.push(evt)
+	}
+
+	raw.addEventListener("open", () => push({ type: "open" }))
+	raw.addEventListener("message", (evt: { data: ArrayBuffer | string }) => {
+		if (exceedsPayload(evt.data, options.maxPayload)) {
+			socket.close(CLOSE_TOO_BIG, "message too big")
+			return
+		}
+		push({ data: evt.data, type: "message" })
 	})
+	raw.addEventListener("close", (evt: { code: number; reason: string }) =>
+		push({ code: evt.code, reason: evt.reason, type: "close" }),
+	)
+	raw.addEventListener("error", (evt: unknown) => push({ error: evt, type: "error" }))
+
+	return {
+		bind(h: WSHandler<unknown>): void {
+			handler = h
+			const queued = early ?? []
+			early = null
+			for (const evt of queued) deliver(evt, h)
+		},
+	}
 }
 
 /**
  * Deno WebSocket adapter.
  * Uses Deno.upgradeWebSocket() and addEventListener for event binding.
- * Keepalive is not supported — Deno's WebSocket lacks a ping() method.
- * Use nodeWebSocket() for keepalive support.
+ * Deno pings idle sockets itself (`idleTimeout`, whole seconds); there is no `keepalive` option.
  *
  * `preUpgrade` calls `Deno.upgradeWebSocket` in the same turn as the serve
  * callback (Deno rejects upgrades performed after the first await).
  */
-export function denoWebSocket(): WSAdapter {
-	const pending = new WeakMap<Request, { pre: WSPreUpgrade; raw: DenoSocket }>()
+export function denoWebSocket(opts?: WSAdapterOptions): WSAdapter {
+	const options = resolveWSOptions(opts)
+	const pending = new WeakMap<Request, { bind(h: WSHandler<unknown>): void; pre: WSPreUpgrade }>()
+	const open = new Set<WSContextImpl<DenoRawSocket>>()
+
+	const start = (req: Request) => {
+		const denoNs = globalThis as unknown as DenoNs
+		const protocol = selectProtocol(req, options)
+		const upgradeOpts: DenoUpgradeOptions = {}
+		if (protocol !== null) upgradeOpts.protocol = protocol
+		if (options.idleTimeout > 0) upgradeOpts.idleTimeout = Math.max(Math.ceil(options.idleTimeout / 1000), 1)
+		const { response, socket: rawSocket } = denoNs.Deno.upgradeWebSocket(req, upgradeOpts)
+		/* binary frames arrive as ArrayBuffer, as on every other runtime (Deno's default is Blob) */
+		rawSocket.binaryType = "arraybuffer"
+		const socket = new WSContextImpl(rawSocket as DenoRawSocket, options)
+		open.add(socket)
+		rawSocket.addEventListener("close", () => open.delete(socket))
+		const listener = listen(rawSocket, socket, options)
+		return { listener, rawSocket, response, socket }
+	}
 
 	return {
+		closeAll(code: number, reason: string) {
+			for (const socket of open) {
+				try {
+					socket.close(code, reason)
+				} catch {
+					/* already closing */
+				}
+			}
+		},
+		options,
 		preUpgrade(req: Request): WSPreUpgrade {
-			const denoNs = globalThis as unknown as DenoNs
-			const { response, socket: rawSocket } = denoNs.Deno.upgradeWebSocket(req)
-			const socket = new WSContextImpl(rawSocket as DenoRawSocket)
+			const { listener, rawSocket, response, socket } = start(req)
 			const pre: WSPreUpgrade = {
 				response,
 				socket,
@@ -74,26 +170,18 @@ export function denoWebSocket(): WSAdapter {
 					rawSocket.addEventListener("open", () => fn())
 				},
 			}
-			pending.set(req, { pre, raw: rawSocket })
+			pending.set(req, { bind: listener.bind, pre })
 			return pre
 		},
 		upgrade(req: Request, _env: unknown, handler: WSHandler<unknown>) {
 			const held = pending.get(req)
 			if (held) {
 				pending.delete(req)
-				bindHandlers(held.raw, held.pre.socket as WSContextImpl<DenoRawSocket>, handler)
-				/* handshake may have completed before listeners were attached */
-				if (held.raw.readyState === 1) {
-					handler.onOpen?.(undefined, held.pre.socket)
-				}
+				held.bind(handler)
 				return held.pre
 			}
-
-			/* globalThis cast: Deno namespace only exists at runtime on Deno — no way to type it statically */
-			const denoNs = globalThis as unknown as DenoNs
-			const { response, socket: rawSocket } = denoNs.Deno.upgradeWebSocket(req)
-			const socket = new WSContextImpl(rawSocket as DenoRawSocket)
-			bindHandlers(rawSocket, socket, handler)
+			const { listener, response, socket } = start(req)
+			listener.bind(handler)
 			return { response, socket }
 		},
 	}