@lovrozagar/honey 0.6.5 → 0.7.0

package/src/node.ts

@@ -1,38 +1,94 @@
-import type { IncomingMessage, Server, ServerResponse } from "node:http"
-import { createServer } from "node:http"
+import type { IncomingMessage, Server } from "node:http"
+import { createServer, ServerResponse } from "node:http"
+import type { Socket } from "node:net"
 import { Readable, type Duplex } from "node:stream"
 import { pipeline } from "node:stream/promises"
 import type { Honey } from "./index.ts"
+import { bodyKind, rawBodyOf } from "./body-kind.ts"
 import { isHoneyResponse } from "./honey-response.ts"
-import { incomingToNodeRequest } from "./node-request.ts"
+import {
+	ABORT_REQUEST,
+	BODY_OVERFLOW,
+	DEFAULT_MAX_REQUEST_BODY,
+	incomingToNodeRequest,
+	nodeRequestUrl,
+	type NodeRequestOptions,
+} from "./node-request.ts"
+import type { WSAdapter } from "./ws/cloudflare.ts"
+import type { NodeUpgradeData } from "./ws/node.ts"
 
-type ServeOptions<TEnv> = {
+export type NodeServeOptions<TEnv> = {
 	env: TEnv
 	hostname?: string
 	port?: number
+	/**
+	 * Largest request body a read accepts, in bytes. A bigger one fails the read with 413 and the
+	 * connection is closed. `0` disables the cap. Default 128 MiB, as on Bun.
+	 */
+	maxRequestBodySize?: number
+	/** Node's `server.headersTimeout`, in ms (Node's default: 60 000). */
+	headersTimeout?: number
+	/** Node's `server.requestTimeout`, in ms (Node's default: 300 000). */
+	requestTimeout?: number
+	/** Node's `server.keepAliveTimeout`, in ms (Node's default: 5 000). */
+	keepAliveTimeout?: number
+	/**
+	 * How long an upgrade request may take to become a WebSocket (or be answered), in ms.
+	 * Default 30 000.
+	 */
+	upgradeTimeout?: number
+	/** Errors the adapter could not hand to the app (it then answers 500). Default: `console.error`. */
+	onError?: (error: unknown) => void
 }
 
 /** Buffer known-size bodies up to this many bytes, then `res.end(buf)`. */
 const BUFFER_BODY_MAX = 256 * 1024
-const RAW_BODY = Symbol.for("honey.rawBody")
+const DEFAULT_UPGRADE_TIMEOUT = 30_000
+
+/**
+ * Hop-by-hop headers (RFC 9110 §7.6.1): they describe one connection, so a response from
+ * somewhere else (a proxied `fetch()`) must not carry them onto this one. Node writes its own.
+ */
+const HOP_BY_HOP = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-connection",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade",
+])
 
 // Node's `Readable.fromWeb` wants `node:stream/web` streams; DOM/Bun brands do not overlap.
 function asNodeWebStream(stream: ReadableStream<Uint8Array>): import("node:stream/web").ReadableStream {
 	return stream as unknown as import("node:stream/web").ReadableStream
 }
 
-function incomingToRequest(req: IncomingMessage): Request {
-	return incomingToNodeRequest(req)
+/** `null` when the request target or `Host` is invalid (see `nodeRequestUrl`); the caller answers 400. */
+function incomingToRequest(req: IncomingMessage, opts: NodeRequestOptions): Request | null {
+	const url = nodeRequestUrl(req)
+	return url === null ? null : incomingToNodeRequest(req, url, opts)
 }
 
 function collectNodeHeaders(response: Response, extra?: Record<string, string>): Record<string, string | string[]> {
 	const headerObj: Record<string, string | string[]> = {}
 	let hasSetCookie = false
+	/* headers a `Connection` header names are hop-by-hop too */
+	const named = response.headers.get("connection")
+	const dropNamed =
+		named === null
+			? null
+			: named
+					.toLowerCase()
+					.split(",")
+					.map((t) => t.trim())
 	response.headers.forEach((value, key) => {
 		if (key === "set-cookie") {
 			hasSetCookie = true
 			return
 		}
+		if (HOP_BY_HOP.has(key) && !(key === "upgrade" && response.status === 101)) return
+		if (dropNamed !== null && dropNamed.includes(key)) return
 		headerObj[key] = value
 	})
 	if (hasSetCookie) {
@@ -43,25 +99,40 @@ function collectNodeHeaders(response: Response, extra?: Record<string, string>):
 	return headerObj
 }
 
+/**
+ * Buffer a body only when its size is known and small: a body Honey built in memory, or one
+ * that declares `content-length`. Everything else (SSE, `generate()`, a proxied stream, an
+ * untagged `new Response(stream)`) is piped as it is produced, whatever its content type.
+ */
 function shouldBufferBody(response: Response): boolean {
-	const rawLen = response.headers.get("content-length")
-	if (rawLen !== null) {
-		const len = Number(rawLen)
-		return Number.isFinite(len) && len <= BUFFER_BODY_MAX
+	if (bodyKind(response) !== "buffered") return false
+	const len = Number(response.headers.get("content-length"))
+	return Number.isFinite(len) && len <= BUFFER_BODY_MAX
+}
+
+/**
+ * Pipe a body to the socket. When the response closes first (client gone, shutdown), the
+ * reader is cancelled so the producer stops; nothing is left reading.
+ */
+async function pipeBody(stream: ReadableStream<Uint8Array>, res: ServerResponse): Promise<void> {
+	const readable = Readable.fromWeb(asNodeWebStream(stream))
+	const onClose = (): void => {
+		if (!res.writableFinished) readable.destroy()
+	}
+	res.once("close", onClose)
+	try {
+		await pipeline(readable, res)
+	} catch {
+		if (!res.destroyed) res.destroy()
+		/* `destroy()` cancels the web reader; this covers a stream that errored on its own */
+		stream.cancel().catch(() => {})
+	} finally {
+		res.off("close", onClose)
 	}
-	const ct = response.headers.get("content-type") ?? ""
-	if (ct.startsWith("text/event-stream")) return false
-	return (
-		ct.startsWith("application/json") ||
-		ct.startsWith("text/plain") ||
-		ct.startsWith("text/html") ||
-		ct.startsWith("text/csv") ||
-		ct.startsWith("application/xml")
-	)
 }
 
-function rawBodyOf(response: Response): string | Uint8Array | undefined {
-	return (response as Response & { [RAW_BODY]?: string | Uint8Array })[RAW_BODY]
+function statusMessage(response: Response): string | undefined {
+	return response.statusText === "" ? undefined : response.statusText
 }
 
 async function responseToNode(response: Response, res: ServerResponse): Promise<void> {
@@ -80,25 +151,25 @@ async function responseToNode(response: Response, res: ServerResponse): Promise<
 			return
 		}
 		res.writeHead(response.status, response.plainHeaders)
-		try {
-			await pipeline(Readable.fromWeb(asNodeWebStream(stream)), res)
-		} catch {
-			if (!res.destroyed) res.destroy()
-		}
+		await pipeBody(stream, res)
 		return
 	}
 
 	const raw = rawBodyOf(response)
 	if (typeof raw === "string" || raw instanceof Uint8Array) {
 		const byteLength = typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength
-		res.writeHead(response.status, collectNodeHeaders(response, { "content-length": String(byteLength) }))
+		res.writeHead(
+			response.status,
+			statusMessage(response),
+			collectNodeHeaders(response, { "content-length": String(byteLength) }),
+		)
 		res.end(raw)
 		return
 	}
 
 	const body = response.body
 	if (body === null) {
-		res.writeHead(response.status, collectNodeHeaders(response))
+		res.writeHead(response.status, statusMessage(response), collectNodeHeaders(response))
 		res.end()
 		return
 	}
@@ -106,17 +177,79 @@ async function responseToNode(response: Response, res: ServerResponse): Promise<
 	if (shouldBufferBody(response)) {
 		const buf = Buffer.from(await response.arrayBuffer())
 		if (res.destroyed) return
-		res.writeHead(response.status, collectNodeHeaders(response, { "content-length": String(buf.byteLength) }))
+		res.writeHead(
+			response.status,
+			statusMessage(response),
+			collectNodeHeaders(response, { "content-length": String(buf.byteLength) }),
+		)
 		res.end(buf)
 		return
 	}
 
-	res.writeHead(response.status, collectNodeHeaders(response))
-	try {
-		await pipeline(Readable.fromWeb(asNodeWebStream(body)), res)
-	} catch {
-		if (!res.destroyed) res.destroy()
-	}
+	const headers = collectNodeHeaders(response)
+	/* a stream's declared length is never trusted (`fetch()` keeps the encoded length of a body it
+	 * decoded): Node chunks it, so a wrong length cannot truncate it or desynchronize keep-alive */
+	delete headers["content-length"]
+	res.writeHead(response.status, statusMessage(response), headers)
+	await pipeBody(body, res)
+}
+
+function isWebSocketUpgrade(req: IncomingMessage): boolean {
+	return req.headers.upgrade?.toLowerCase() === "websocket"
+}
+
+/**
+ * The body of a request that came in on Node's `'upgrade'` path but is served as a normal
+ * request. Node with `shouldUpgradeCallback` never sends those there; before that,
+ * some versions leave the body on the socket (the first bytes in `head`). Only a declared
+ * `content-length` can be read back that way.
+ */
+function upgradeBodySource(
+	req: IncomingMessage,
+	socket: Duplex,
+	head: Buffer,
+): AsyncIterable<Buffer> | null | "unsupported" {
+	/* newer Node parses the body into `req` itself */
+	if (!req.complete) return null
+	if (req.headers["transfer-encoding"] !== undefined) return "unsupported"
+	const declared = Number(req.headers["content-length"] ?? 0)
+	if (!Number.isSafeInteger(declared) || declared <= 0) return null
+	return (async function* () {
+		let remaining = declared
+		if (head.byteLength > 0) {
+			const first = head.subarray(0, remaining)
+			remaining -= first.byteLength
+			yield first
+		}
+		if (remaining <= 0) return
+		for await (const chunk of socket as AsyncIterable<Buffer>) {
+			const part = chunk.subarray(0, remaining)
+			remaining -= part.byteLength
+			yield part
+			if (remaining <= 0) return
+		}
+	})()
+}
+
+/** Answer on a socket Node handed over through `'upgrade'`, with a real `ServerResponse`. */
+function responseOnSocket(req: IncomingMessage, socket: Socket): ServerResponse {
+	const res = new ServerResponse(req)
+	/* the connection ends with this response */
+	res.shouldKeepAlive = false
+	res.assignSocket(socket)
+	res.once("finish", () => {
+		res.detachSocket(socket)
+		socket.end()
+	})
+	return res
+}
+
+/** A response written before any Request exists (bad target or `Host`): plain text, then close. */
+function writeRawStatus(socket: Duplex, status: 400 | 503, text: string): void {
+	if (socket.destroyed) return
+	socket.end(
+		`HTTP/1.1 ${status} ${text}\r\nconnection: close\r\ncontent-type: text/plain\r\ncontent-length: ${text.length}\r\n\r\n${text}`,
+	)
 }
 
 export type HoneyServer = Server & {
@@ -125,83 +258,193 @@ export type HoneyServer = Server & {
 
 export function serve<TEnv>(
 	app: Honey<TEnv, unknown, unknown, unknown, unknown, string, string>,
-	options: ServeOptions<TEnv>,
+	options: NodeServeOptions<TEnv>,
 ): HoneyServer {
 	const env = options.env
-	let inflight = 0
+	const requestOpts: NodeRequestOptions = { maxBodySize: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY }
+	const upgradeTimeout = options.upgradeTimeout ?? DEFAULT_UPGRADE_TIMEOUT
+	const reportError =
+		options.onError ??
+		((err: unknown): void => {
+			console.error("honey: request failed in the Node adapter", err)
+		})
+	/* in-flight requests and their responses: shutdown aborts their signals */
+	const inflight = new Map<ServerResponse, Request>()
+	/* sockets that became WebSockets: shutdown closes them */
+	const upgraded = new Set<Duplex>()
 	let draining = false
-	let drainResolve: (() => void) | null = null
 
-	const server = createServer(async (req, res) => {
+	const abort = (request: Request, reason: unknown): void => {
+		;(request as unknown as { [ABORT_REQUEST]?: (r?: unknown) => void })[ABORT_REQUEST]?.(reason)
+	}
+	const wsAdapter = (): WSAdapter | null =>
+		(app as unknown as { _graph: { settings: { wsAdapter: WSAdapter | null } } })._graph.settings.wsAdapter
+
+	/** One HTTP request, whether it came in normally or on the `'upgrade'` path. */
+	const handle = async (
+		req: IncomingMessage,
+		res: ServerResponse,
+		bodySource: AsyncIterable<Buffer> | null = null,
+	): Promise<void> => {
 		if (draining) {
-			res.writeHead(503)
+			res.writeHead(503, { connection: "close" })
 			res.end("Service Unavailable")
 			return
 		}
-		inflight++
+		let request: Request | null = null
 		try {
-			const request = incomingToRequest(req)
+			request = incomingToRequest(req, bodySource === null ? requestOpts : { ...requestOpts, bodySource })
+			if (request === null) {
+				res.writeHead(400, { connection: "close", "content-type": "text/plain" })
+				res.end("Bad Request")
+				return
+			}
+			const tracked = request
+			inflight.set(res, tracked)
+			/* the response closed before it finished: the client left (or shutdown cut it) */
+			res.once("close", () => {
+				if (!res.writableFinished) abort(tracked, new DOMException("The client disconnected", "AbortError"))
+			})
 			const maybe = app.fetch(request, env)
 			const response = maybe instanceof Promise ? await maybe : maybe
+			/* while draining, tell keep-alive clients this connection ends with the response */
+			if (draining) res.shouldKeepAlive = false
+			/* a body over the cap was left unread on the socket: never reuse the connection */
+			if ((request as unknown as { [BODY_OVERFLOW]?: boolean })[BODY_OVERFLOW] === true) res.shouldKeepAlive = false
 			await responseToNode(response, res)
-		} catch {
+		} catch (err) {
+			reportError(err)
 			if (!res.headersSent) {
-				res.writeHead(500)
+				res.writeHead(500, { "content-type": "text/plain" })
 				res.end("Internal Server Error")
 			} else if (!res.destroyed) {
 				res.destroy()
 			}
 		} finally {
-			inflight--
-			if (draining && inflight === 0) {
-				drainResolve?.()
-			}
+			if (request !== null) inflight.delete(res)
+			/* a keep-alive connection that just went idle would hold `close()` open until it times out */
+			if (draining) setImmediate(() => server.closeIdleConnections())
 		}
-	})
+	}
+
+	const server = createServer(
+		{
+			/* only a WebSocket handshake takes the upgrade path; `Upgrade: h2c` and the like are
+			 * served as the normal requests they are (where Node has `shouldUpgradeCallback`; older Node ignores the option) */
+			shouldUpgradeCallback: isWebSocketUpgrade,
+		} as Parameters<typeof createServer>[0],
+		(req, res) => {
+			void handle(req, res)
+		},
+	)
+	if (options.headersTimeout !== undefined) server.headersTimeout = options.headersTimeout
+	if (options.requestTimeout !== undefined) server.requestTimeout = options.requestTimeout
+	if (options.keepAliveTimeout !== undefined) server.keepAliveTimeout = options.keepAliveTimeout
 
-	/* WebSocket upgrade handling */
-	server.on("upgrade", async (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+	/** A WebSocket handshake, or (on Node without `shouldUpgradeCallback`) any request with `Upgrade`. */
+	const handleUpgrade = async (req: IncomingMessage, socket: Socket, head: Buffer): Promise<void> => {
+		if (!isWebSocketUpgrade(req)) {
+			const source = upgradeBodySource(req, socket, head)
+			if (source === "unsupported") {
+				writeRawStatus(socket, 400, "Bad Request")
+				return
+			}
+			socket.setTimeout(0)
+			await handle(req, responseOnSocket(req, socket), source)
+			return
+		}
+		if (draining) {
+			writeRawStatus(socket, 503, "Service Unavailable")
+			return
+		}
+		const request = incomingToRequest(req, requestOpts)
+		if (request === null) {
+			writeRawStatus(socket, 400, "Bad Request")
+			return
+		}
+		socket.once("close", () => {
+			abort(request, new DOMException("The client disconnected", "AbortError"))
+		})
+		const state: NodeUpgradeData = { head, req, socket, upgraded: false }
+		const envWithUpgrade = { ...env, __nodeUpgrade: state } as TEnv
+		let response: Response
 		try {
-			const request = incomingToRequest(req)
-			const envWithUpgrade = { ...env, __nodeUpgrade: { head, req, socket } } as TEnv
 			const maybe = app.fetch(request, envWithUpgrade)
-			const response = maybe instanceof Promise ? await maybe : maybe
-
-			if (response.status !== 101) {
-				const text = await response.text()
-				socket.write(
-					`HTTP/1.1 ${response.status} ${response.statusText ?? "Error"}\r\n` +
-						"content-type: application/json\r\n" +
-						`\r\n${text}`,
-				)
-				socket.destroy()
+			response = maybe instanceof Promise ? await maybe : maybe
+		} catch (err) {
+			reportError(err)
+			/* once ws wrote the 101 the socket is a WebSocket: an HTTP status would corrupt it */
+			if (!state.upgraded) {
+				socket.setTimeout(0)
+				const res = responseOnSocket(req, socket)
+				res.writeHead(500, { "content-type": "text/plain" })
+				res.end("Internal Server Error")
 			}
-		} catch {
-			socket.write("HTTP/1.1 500 Internal Server Error\r\n\r\n")
+			return
+		}
+		if (state.upgraded) {
+			socket.setTimeout(0)
+			upgraded.add(socket)
+			socket.once("close", () => upgraded.delete(socket))
+			return
+		}
+		if (socket.destroyed) {
+			await response.body?.cancel().catch(() => {})
+			return
+		}
+		/* not upgraded (auth rejected, 404, 426, an SSE route…): a real response, streamed, every header kept */
+		socket.setTimeout(0)
+		try {
+			await responseToNode(response, responseOnSocket(req, socket))
+		} catch (err) {
+			reportError(err)
 			socket.destroy()
 		}
+	}
+
+	server.on("upgrade", (req: IncomingMessage, duplex: Duplex, head: Buffer) => {
+		const socket = duplex as Socket
+		/* first: a reset while the app is still deciding must not become an uncaught 'error' event */
+		socket.on("error", () => {
+			socket.destroy()
+		})
+		if (upgradeTimeout > 0) socket.setTimeout(upgradeTimeout, () => socket.destroy())
+		handleUpgrade(req, socket, head).catch((err: unknown) => {
+			reportError(err)
+			socket.destroy()
+		})
 	})
 
 	server.listen(options?.port ?? 0, options?.hostname)
 
 	const honeyServer = server as HoneyServer
+	/**
+	 * Stop accepting connections and let in-flight requests finish. Responses already streaming
+	 * (SSE, `generate()`) never finish on their own, so their `ctx.signal` aborts now and they
+	 * end; WebSockets get a 1001 close. Handlers still working get until `timeout`; then their
+	 * signal aborts and every connection, WebSockets included, is closed.
+	 */
 	honeyServer.shutdown = (timeout?: number): Promise<void> => {
 		draining = true
+		const shutdownReason = (): DOMException => new DOMException("The server is shutting down", "AbortError")
 
 		return new Promise<void>((resolve) => {
+			let timer: ReturnType<typeof setTimeout> | undefined
+			/* fires once every connection has closed */
 			server.close(() => {
-				if (inflight === 0) {
-					resolve()
-					return
-				}
-				drainResolve = resolve
+				if (timer !== undefined) clearTimeout(timer)
+				resolve()
 			})
-
+			server.closeIdleConnections()
+			for (const [res, request] of inflight) {
+				if (res.headersSent) abort(request, shutdownReason())
+			}
+			wsAdapter()?.closeAll?.(1001, "server shutting down")
 			if (timeout !== undefined) {
-				setTimeout(() => {
-					drainResolve = null
+				timer = setTimeout(() => {
+					for (const request of inflight.values()) abort(request, shutdownReason())
+					for (const socket of upgraded) socket.destroy()
 					server.closeAllConnections()
-					resolve()
 				}, timeout)
 			}
 		})

package/src/openapi/collect.ts

@@ -1,4 +1,5 @@
-import type { RouteHandler, TreeNode, WSRouteHandler } from "../tree.ts"
+import { parsePattern, toOpenApiTemplate, UNNAMED_WILDCARD } from "../pattern.ts"
+import type { RouteHandler, WSRouteHandler } from "../tree.ts"
 import type { InputSchemaEntry, StandardSchemaLike } from "../types.ts"
 
 export type CollectedRoute = {
@@ -12,59 +13,33 @@ export type CollectedWSRoute = {
 	path: string
 }
 
+/** Path parameter names of a route pattern, as OpenAPI names them (wildcards included). */
 export function extractParams(path: string): string[] {
-	const params: string[] = []
-	for (const seg of path.split("/")) {
-		if (seg.startsWith(":")) {
-			params.push(seg.endsWith("?") ? seg.slice(1, -1) : seg.slice(1))
-		}
+	const out: string[] = []
+	for (const seg of parsePattern(path)) {
+		if (seg.k === "param") out.push(seg.n)
+		else if (seg.k === "wildcard") out.push(seg.n === UNNAMED_WILDCARD ? "wildcard" : seg.n)
 	}
-	return params
+	return out
 }
 
 export function toOpenApiPath(path: string): string {
-	return path.replace(/:(\w+)\??/g, "{$1}")
+	return toOpenApiTemplate(parsePattern(path))
 }
 
-export function walkTree(
-	node: TreeNode,
-	currentPath: string,
-	routes: CollectedRoute[],
-	includeSkipped?: boolean,
-): void {
-	if (node.m !== null) {
-		for (const [method, handler] of Object.entries(node.m)) {
-			if (handler._skip && !includeSkipped) continue
-			routes.push({ handler, method, path: currentPath || "/" })
-		}
-	}
-
-	for (const [seg, child] of Object.entries(node.s)) {
-		walkTree(child, `${currentPath}/${seg}`, routes, includeSkipped)
-	}
-
-	if (node.d !== null) {
-		walkTree(node.d.c, `${currentPath}/:${node.d.n}`, routes, includeSkipped)
-	}
+type RouteSource = {
+	_collectRoutes(includeSkipped?: boolean): CollectedRoute[]
+	_collectWsRoutes(): CollectedWSRoute[]
+}
 
-	if (node.w !== null) {
-		for (const [method, handler] of Object.entries(node.w.m)) {
-			if (handler._skip && !includeSkipped) continue
-			routes.push({ handler, method, path: `${currentPath}/*${node.w.n}` })
-		}
-	}
+/** Every served HTTP route of an app, one entry per concrete path. */
+export function collectRoutes(app: unknown, includeSkipped?: boolean): CollectedRoute[] {
+	return (app as RouteSource)._collectRoutes(includeSkipped)
 }
 
-export function walkWSRoutes(node: TreeNode, currentPath: string, routes: CollectedWSRoute[]): void {
-	if (node.ws !== null) {
-		routes.push({ handler: node.ws, path: currentPath || "/" })
-	}
-	for (const [seg, child] of Object.entries(node.s)) {
-		walkWSRoutes(child, `${currentPath}/${seg}`, routes)
-	}
-	if (node.d !== null) {
-		walkWSRoutes(node.d.c, `${currentPath}/:${node.d.n}`, routes)
-	}
+/** Every websocket route of an app, one entry per concrete path. */
+export function collectWsRoutes(app: unknown): CollectedWSRoute[] {
+	return (app as RouteSource)._collectWsRoutes()
 }
 
 export function unwrapEntry(entry: InputSchemaEntry): StandardSchemaLike {

package/src/openapi/docs-page.ts

@@ -0,0 +1,89 @@
+import type { TypedResponse } from "../response.ts"
+
+/**
+ * Pinned docs UI assets with Subresource Integrity. The page runs on the API's own origin, so
+ * an unpinned CDN script could read anything the origin can; a pinned version with an
+ * integrity hash can only ever be these bytes.
+ */
+export const SWAGGER_UI = {
+	css: {
+		integrity: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW",
+		url: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.1/swagger-ui.css",
+	},
+	js: {
+		integrity: "sha384-ZPehFMQommnnuaZ4rpxgkgTT2DKFVp4hZC/7pLit+9Lek9T1YGSo23eHFbvNkXkw",
+		url: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.1/swagger-ui-bundle.js",
+	},
+} as const
+
+export const SCALAR = {
+	js: {
+		integrity: "sha384-kYDGzV91Jnn3TbHINV3nt54riK2uMJDfN5Al8dAkz4FssELTBWbD8rgw32sTKfOi",
+		url: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.73.1/dist/browser/standalone.js",
+	},
+} as const
+
+const CDN_ORIGIN = "https://cdn.jsdelivr.net"
+
+/* built from char codes: a formatter may turn an escape in a literal into the raw separator */
+const LINE_SEPARATOR = String.fromCharCode(0x2028)
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029)
+
+/**
+ * JSON for an inline `<script>`: `<` cannot end the element, and U+2028/U+2029 cannot end a
+ * string literal in older engines.
+ */
+export function inlineJson(value: unknown): string {
+	return JSON.stringify(value)
+		.replace(/</g, "\\u003c")
+		.replace(/>/g, "\\u003e")
+		.replace(/&/g, "\\u0026")
+		.replaceAll(LINE_SEPARATOR, "\\u2028")
+		.replaceAll(PARAGRAPH_SEPARATOR, "\\u2029")
+}
+
+export function escapeAttribute(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+}
+
+function nonce(): string {
+	const bytes = new Uint8Array(16)
+	crypto.getRandomValues(bytes)
+	let s = ""
+	for (const b of bytes) s += String.fromCharCode(b)
+	return btoa(s)
+}
+
+type DocsCtx = { res: { html(sk: "ok", body: string, opts?: { headers?: Record<string, string> }): TypedResponse } }
+
+/**
+ * A docs page handler: a fresh script nonce per response, a CSP that allows only that inline
+ * script and the pinned CDN, and `nosniff`.
+ */
+export function docsPage(render: (nonce: string) => string): (ctx: DocsCtx) => TypedResponse {
+	const handler = (ctx: DocsCtx) => {
+		const n = nonce()
+		const csp = [
+			"default-src 'none'",
+			`script-src 'nonce-${n}' ${CDN_ORIGIN}`,
+			`style-src 'self' 'unsafe-inline' ${CDN_ORIGIN}`,
+			"img-src 'self' data: https:",
+			"font-src 'self' data: https:",
+			"connect-src 'self' https:",
+			"worker-src blob:",
+			"base-uri 'none'",
+			"form-action 'none'",
+			"frame-ancestors 'self'",
+			"object-src 'none'",
+		].join("; ")
+		return ctx.res.html("ok", render(n), {
+			headers: {
+				"content-security-policy": csp,
+				"referrer-policy": "no-referrer",
+				"x-content-type-options": "nosniff",
+			},
+		})
+	}
+	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
+	return handler
+}