@lovrozagar/honey 0.6.8 → 0.7.1

package/src/ws/node.ts

@@ -1,36 +1,58 @@
-export { type RawSocket, type WSAdapter, type WSContext, WSContextImpl, type WSHandler } from "./cloudflare.ts"
+export {
+	type RawSocket,
+	type WSAdapter,
+	type WSAdapterOptions,
+	type WSContext,
+	WSContextImpl,
+	type WSHandler,
+} from "./cloudflare.ts"
 
 import type { WSAdapter, WSHandler } from "./cloudflare.ts"
-import { WSContextImpl } from "./cloudflare.ts"
+import { fireHandler, WSContextImpl } from "./cloudflare.ts"
+import {
+	type ResolvedWSOptions,
+	resolveWSOptions,
+	selectProtocol,
+	toArrayBuffer,
+	type WSAdapterOptions,
+} from "./shared.ts"
+
+type WebSocketServerOptions = {
+	handleProtocols?: (protocols: Set<string>, req: unknown) => string | false
+	maxPayload: number
+	noServer: true
+	perMessageDeflate: boolean
+}
 
 type WsModule = {
-	WebSocketServer: new (opts: { noServer: true; perMessageDeflate: boolean }) => {
-		handleUpgrade(req: unknown, socket: unknown, head: unknown, cb: (ws: NodeWS) => void): void
-	}
+	WebSocketServer: new (opts: WebSocketServerOptions) => WssInstance
 }
 
 type NodeWS = {
+	binaryType: string
+	bufferedAmount: number
 	close(code?: number, reason?: string): void
 	on(event: "close", cb: (code: number, reason: Buffer) => void): void
 	on(event: "error", cb: (err: unknown) => void): void
-	on(event: "message", cb: (data: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => void): void
-	on(event: "pong", cb: () => void): void
+	on(event: "message", cb: (data: ArrayBuffer | Buffer | Buffer[], isBinary: boolean) => void): void
+	on(event: "pong" | "ping", cb: () => void): void
 	ping(): void
 	readyState: number
 	send(data: ArrayBuffer | Buffer | Uint8Array | string): void
+	terminate(): void
 }
 
-type NodeUpgradeData = {
+/**
+ * What the Node adapter (`serve()`) puts on `env.__nodeUpgrade`. `upgraded` turns true once the
+ * 101 is written: from then on the socket belongs to `ws`, and the adapter must not write to it.
+ */
+export type NodeUpgradeData = {
 	head: Buffer
 	req: unknown
 	socket: unknown
+	upgraded: boolean
 }
 
-/**
- * Node.js WebSocket adapter.
- * Requires the `ws` package. Creates a no-server WebSocketServer internally.
- * Reads __nodeUpgrade from env (placed there by serve()).
- */
 type WssInstance = {
 	handleUpgrade(req: unknown, socket: unknown, head: unknown, cb: (ws: NodeWS) => void): void
 }
@@ -40,96 +62,166 @@ type KeepaliveConfig = {
 	timeout: number
 }
 
-export function nodeWebSocket(opts?: { keepalive?: KeepaliveConfig }): WSAdapter {
+export type NodeWebSocketOptions = WSAdapterOptions & {
+	/** Ping every `interval` ms; a pong missing after `timeout` ms terminates the connection. */
+	keepalive?: KeepaliveConfig
+}
+
+const WS_MISSING =
+	'WebSocket routes on Node need the "ws" package, which is an optional peer dependency of honey. Install it: npm install ws'
+
+/**
+ * Node.js WebSocket adapter, on the `ws` package (an optional peer dependency). It reads
+ * `env.__nodeUpgrade`, which honey's `serve()` puts there for an upgrade request.
+ */
+export function nodeWebSocket(opts?: NodeWebSocketOptions): WSAdapter {
+	const options: ResolvedWSOptions = resolveWSOptions(opts)
+	const keepalive = opts?.keepalive
+	if (keepalive !== undefined && !(keepalive.interval > 0 && keepalive.timeout > 0)) {
+		throw new TypeError("nodeWebSocket: keepalive.interval and keepalive.timeout must be positive")
+	}
 	let wss: WssInstance | null = null
-	let wssReady: Promise<void> | null = null
+	let wssReady: Promise<WssInstance> | null = null
+	const open = new Set<NodeWS>()
+	/* the Request being upgraded, for the protocol callback (ws hands it the IncomingMessage) */
+	let upgrading: Request | null = null
 
-	const ensureWss = async (): Promise<WssInstance> => {
-		if (wss) return wss
+	const ensureWss = (): Promise<WssInstance> => {
+		if (wss) return Promise.resolve(wss)
 		if (!wssReady) {
-			wssReady = import("ws").then((mod) => {
-				const wsModule = mod as unknown as WsModule
-				wss = new wsModule.WebSocketServer({ noServer: true, perMessageDeflate: false })
-			})
+			wssReady = import("ws").then(
+				(mod) => {
+					const wsModule = mod as unknown as WsModule
+					wss = new wsModule.WebSocketServer({
+						handleProtocols: (protocols) => {
+							if (protocols.size === 0 || upgrading === null) return false
+							return selectProtocol(upgrading, options) ?? false
+						},
+						maxPayload: options.maxPayload,
+						noServer: true,
+						perMessageDeflate: false,
+					})
+					return wss
+				},
+				(err: unknown) => {
+					/* not cached: installing ws later works without a restart */
+					wssReady = null
+					throw new Error(WS_MISSING, { cause: err })
+				},
+			)
 		}
-		await wssReady
-		if (!wss) throw new Error("Failed to initialize WebSocketServer")
-		return wss
+		return wssReady
+	}
+
+	const watch = (ws: NodeWS): void => {
+		let pingTimer: ReturnType<typeof setInterval> | undefined
+		let pongTimeout: ReturnType<typeof setTimeout> | undefined
+		let idleTimer: ReturnType<typeof setInterval> | undefined
+		let lastSeen = Date.now()
+		const seen = (): void => {
+			lastSeen = Date.now()
+		}
+
+		ws.on("pong", () => {
+			seen()
+			if (pongTimeout !== undefined) {
+				clearTimeout(pongTimeout)
+				pongTimeout = undefined
+			}
+		})
+		ws.on("ping", seen)
+
+		if (keepalive) {
+			pingTimer = setInterval(() => {
+				if (ws.readyState !== 1) return
+				/* one pong outstanding at a time: a slow pong must not stack timers */
+				if (pongTimeout !== undefined) return
+				ws.ping()
+				pongTimeout = setTimeout(() => ws.terminate(), keepalive.timeout)
+			}, keepalive.interval)
+		}
+
+		const idle = options.idleTimeout
+		if (idle > 0) {
+			const tick = Math.max(Math.floor(idle / 2), 1)
+			idleTimer = setInterval(() => {
+				if (ws.readyState !== 1) return
+				const quiet = Date.now() - lastSeen
+				if (quiet >= idle) ws.terminate()
+				else if (quiet >= tick) ws.ping()
+			}, tick)
+		}
+
+		const stop = (): void => {
+			if (pingTimer !== undefined) clearInterval(pingTimer)
+			if (pongTimeout !== undefined) clearTimeout(pongTimeout)
+			if (idleTimer !== undefined) clearInterval(idleTimer)
+			pingTimer = pongTimeout = idleTimer = undefined
+		}
+		ws.on("close", stop)
+		ws.on("error", stop)
 	}
 
 	return {
-		async upgrade(_req: Request, env: unknown, handler: WSHandler<unknown>) {
+		closeAll(code: number, reason: string) {
+			for (const ws of open) {
+				try {
+					ws.close(code, reason)
+				} catch {
+					ws.terminate()
+				}
+			}
+		},
+		options,
+		async upgrade(req: Request, env: unknown, handler: WSHandler<unknown>) {
 			const server = await ensureWss()
-
-			const nodeEnv = env as Record<string, unknown>
-			const upgrade = nodeEnv.__nodeUpgrade as NodeUpgradeData
+			const upgrade = (env as Record<string, unknown>).__nodeUpgrade as NodeUpgradeData | undefined
+			if (upgrade === undefined) {
+				throw new Error("nodeWebSocket: no upgrade socket; serve the app with honey's serve() on Node")
+			}
 
 			return new Promise((resolve, reject) => {
+				/* ws answers a malformed handshake itself and never calls back: fail instead of hanging */
+				const sock = upgrade.socket as { once?(event: "close", cb: () => void): void }
+				sock.once?.("close", () => {
+					if (!upgrade.upgraded) reject(new Error("WebSocket handshake failed"))
+				})
+				upgrading = req
 				try {
 					server.handleUpgrade(upgrade.req, upgrade.socket, upgrade.head, (ws: NodeWS) => {
-						const socket = new WSContextImpl(ws)
+						upgrade.upgraded = true
+						ws.binaryType = "arraybuffer"
+						open.add(ws)
+						const socket = new WSContextImpl(ws, options)
 
-						ws.on("message", (data: Buffer | ArrayBuffer | Buffer[], isBinary: boolean) => {
+						ws.on("message", (data: ArrayBuffer | Buffer | Buffer[], isBinary: boolean) => {
+							let payload: ArrayBuffer | string
 							if (!isBinary) {
-								/* text frame — decode to string to match other runtimes */
-								const text = Buffer.isBuffer(data) ? data.toString("utf-8") : String(data)
-								handler.onMessage?.(undefined, socket, text)
-							} else if (Buffer.isBuffer(data)) {
-								/* binary frame — slice from pool to get exact bytes */
-								handler.onMessage?.(
-									undefined,
-									socket,
-									data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer,
-								)
-							} else if (Array.isArray(data)) {
-								const merged = Buffer.concat(data)
-								handler.onMessage?.(
-									undefined,
-									socket,
-									merged.buffer.slice(merged.byteOffset, merged.byteOffset + merged.byteLength) as ArrayBuffer,
-								)
+								/* text frame: a string, as on every other runtime */
+								payload = Buffer.isBuffer(data)
+									? data.toString("utf-8")
+									: data instanceof ArrayBuffer
+										? Buffer.from(data).toString("utf-8")
+										: Buffer.concat(data).toString("utf-8")
+							} else if (data instanceof ArrayBuffer) {
+								payload = data
 							} else {
-								handler.onMessage?.(undefined, socket, data)
+								payload = toArrayBuffer(Array.isArray(data) ? Buffer.concat(data) : data)
 							}
+							fireHandler("message", () => handler.onMessage?.(undefined, socket, payload))
 						})
-
-						/* keepalive ping/pong */
-						let pingTimer: ReturnType<typeof setInterval> | undefined
-						let pongTimeout: ReturnType<typeof setTimeout> | undefined
-
-						if (opts?.keepalive) {
-							const { interval, timeout } = opts.keepalive
-							ws.on("pong", () => {
-								if (pongTimeout !== undefined) {
-									clearTimeout(pongTimeout)
-									pongTimeout = undefined
-								}
-							})
-							pingTimer = setInterval(() => {
-								if (ws.readyState !== 1) {
-									clearInterval(pingTimer)
-									return
-								}
-								ws.ping()
-								pongTimeout = setTimeout(() => {
-									ws.close(1001, "keepalive timeout")
-								}, timeout)
-							}, interval)
-						}
+						watch(ws)
 
 						ws.on("close", (code: number, reason: Buffer) => {
-							if (pingTimer !== undefined) clearInterval(pingTimer)
-							if (pongTimeout !== undefined) clearTimeout(pongTimeout)
-							handler.onClose?.(undefined, socket, code, reason.toString())
+							open.delete(ws)
+							fireHandler("close", () => handler.onClose?.(undefined, socket, code, reason.toString()))
 						})
 
 						ws.on("error", (err: unknown) => {
-							if (pingTimer !== undefined) clearInterval(pingTimer)
-							if (pongTimeout !== undefined) clearTimeout(pongTimeout)
-							handler.onError?.(undefined, socket, err)
+							fireHandler("error", () => handler.onError?.(undefined, socket, err))
 						})
 
-						handler.onOpen?.(undefined, socket)
+						fireHandler("open", () => handler.onOpen?.(undefined, socket))
 
 						/* Node's Response rejects status 101 (Fetch spec: 200-599 only).
 						   Create a valid Response and override status for the sentinel check. */
@@ -139,6 +231,8 @@ export function nodeWebSocket(opts?: { keepalive?: KeepaliveConfig }): WSAdapter
 					})
 				} catch (err) {
 					reject(err)
+				} finally {
+					upgrading = null
 				}
 			})
 		},

package/src/ws/session.ts

@@ -0,0 +1,73 @@
+/**
+ * The server side of one websocket route connection: the user's callbacks run on one ordered
+ * queue (open, then messages, then close), each contained, with a cap on waiting messages.
+ * Every honey adapter imports this module, which registers it, so the core never bundles it
+ * for an app without websockets.
+ */
+import { registerFeature } from "../feature-slots.ts"
+import { createEventQueue, invokeUser, type InvokeLogger } from "../invoke-user.ts"
+import { originAllowed } from "../ws-origin.ts"
+import type { WSContext, WSHandler } from "./cloudflare.ts"
+
+/** Messages one websocket connection may have waiting for its handler; more close it with 1008. */
+const WS_PENDING_MAX = 1024
+
+/** `callbacks` are the route's own; each receives the route's request context `ctx` first. */
+export function createWsSession(opts: {
+	callbacks: WSHandler<unknown>
+	ctx: unknown
+	log: InvokeLogger | null
+	reconnectToken: string | null
+	route: string
+}): WSHandler<unknown> {
+	const { callbacks, ctx, log, reconnectToken, route } = opts
+	const { onClose, onError, onMessage, onOpen, onReconnect } = callbacks
+	const queue = createEventQueue()
+	let pending = 0
+
+	const run = (phase: string, ws: WSContext, fn: () => unknown): Promise<unknown> =>
+		invokeUser(fn, {
+			fields: { route },
+			log,
+			onError: onError ? (err) => onError(ctx, ws, err) : null,
+			phase: `websocket ${phase}`,
+		})
+
+	return {
+		onClose: (_ctx, ws, code, reason) => {
+			if (onClose) void queue.push(() => run("close", ws, () => onClose(ctx, ws, code, reason)))
+		},
+		/* a transport error: tell onError once; if onError throws, that is logged */
+		onError: (_ctx, ws, error) => {
+			void queue.push(() =>
+				invokeUser(() => (onError ? onError(ctx, ws, error) : Promise.reject(error)), {
+					fields: { route },
+					log,
+					phase: "websocket error",
+				}),
+			)
+		},
+		onMessage: (_ctx, ws, data) => {
+			if (!onMessage) return
+			if (pending >= WS_PENDING_MAX) {
+				ws.close(1008, "too many pending messages")
+				return
+			}
+			pending++
+			void queue.push(() =>
+				run("message", ws, () => onMessage(ctx, ws, data)).finally(() => {
+					pending--
+				}),
+			)
+		},
+		onOpen: (_ctx, ws) => {
+			if (reconnectToken && onReconnect) {
+				void queue.push(() => run("open", ws, () => onReconnect(ctx, ws, reconnectToken)))
+			} else if (onOpen) {
+				void queue.push(() => run("open", ws, () => onOpen(ctx, ws)))
+			}
+		},
+	}
+}
+
+registerFeature("ws", { createWsSession, originAllowed })

package/src/ws/shared.ts

@@ -0,0 +1,140 @@
+/**
+ * Options every WebSocket adapter takes, with the same meaning and defaults on Node, Bun, Deno
+ * and Workers. Each adapter enforces what its runtime does not.
+ */
+export type WSAdapterOptions = {
+	/**
+	 * Largest inbound message in bytes. A bigger one closes the connection with 1009.
+	 * Default 1 MiB.
+	 */
+	maxPayload?: number
+	/**
+	 * Outbound bytes a socket may hold unsent before `backpressurePolicy` applies to the next
+	 * `send()`. Default 8 MiB.
+	 */
+	backpressureLimit?: number
+	/**
+	 * Over `backpressureLimit`: `"close"` closes the connection with 1013 (try again later),
+	 * `"drop"` discards the message. Default `"close"`.
+	 */
+	backpressurePolicy?: "close" | "drop"
+	/**
+	 * Close a connection that has received nothing (no message, no pong) for this many
+	 * milliseconds. Idle peers are pinged first where the runtime allows it. `0` disables.
+	 * Default 120 000 (Bun's default). Deno and Bun take whole seconds.
+	 */
+	idleTimeout?: number
+	/**
+	 * Choose the subprotocol from the ones the client offered (`Sec-WebSocket-Protocol`).
+	 * Return `null` or `undefined` for none. Default: the first one offered.
+	 */
+	protocol?: (offered: string[], req: Request) => string | null | undefined
+}
+
+export type ResolvedWSOptions = {
+	backpressureLimit: number
+	backpressurePolicy: "close" | "drop"
+	idleTimeout: number
+	maxPayload: number
+	protocol: (offered: string[], req: Request) => string | null | undefined
+}
+
+export const DEFAULT_MAX_PAYLOAD = 1024 * 1024
+export const DEFAULT_BACKPRESSURE_LIMIT = 8 * 1024 * 1024
+export const DEFAULT_IDLE_TIMEOUT = 120_000
+
+/** Close codes the adapters and the realtime server use. */
+export const CLOSE_NORMAL = 1000
+export const CLOSE_GOING_AWAY = 1001
+export const CLOSE_POLICY = 1008
+export const CLOSE_TOO_BIG = 1009
+export const CLOSE_INTERNAL = 1011
+export const CLOSE_TRY_AGAIN = 1013
+
+/** Longest close reason a frame can carry (125-byte control payload minus the 2-byte code). */
+export const MAX_CLOSE_REASON = 123
+
+const firstOffered = (offered: string[]): string | null => offered[0] ?? null
+
+function nonNegative(name: string, value: number | undefined, fallback: number): number {
+	if (value === undefined) return fallback
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+		throw new TypeError(`WebSocket adapter: ${name} must be a non-negative number`)
+	}
+	return value
+}
+
+export function resolveWSOptions(opts: WSAdapterOptions | undefined): ResolvedWSOptions {
+	const policy = opts?.backpressurePolicy ?? "close"
+	if (policy !== "close" && policy !== "drop") {
+		throw new TypeError('WebSocket adapter: backpressurePolicy must be "close" or "drop"')
+	}
+	const maxPayload = nonNegative("maxPayload", opts?.maxPayload, DEFAULT_MAX_PAYLOAD)
+	if (maxPayload === 0) throw new TypeError("WebSocket adapter: maxPayload must be positive")
+	return {
+		backpressureLimit: nonNegative("backpressureLimit", opts?.backpressureLimit, DEFAULT_BACKPRESSURE_LIMIT),
+		backpressurePolicy: policy,
+		idleTimeout: nonNegative("idleTimeout", opts?.idleTimeout, DEFAULT_IDLE_TIMEOUT),
+		maxPayload,
+		protocol: opts?.protocol ?? firstOffered,
+	}
+}
+
+/** The subprotocols the client offered, in order. */
+export function offeredProtocols(req: Request): string[] {
+	const raw = req.headers.get("sec-websocket-protocol")
+	if (raw === null) return []
+	const out: string[] = []
+	for (const part of raw.split(",")) {
+		const p = part.trim()
+		if (p !== "") out.push(p)
+	}
+	return out
+}
+
+/** The subprotocol to answer with, or `null`. A choice the client did not offer is ignored. */
+export function selectProtocol(req: Request, opts: ResolvedWSOptions): string | null {
+	const offered = offeredProtocols(req)
+	if (offered.length === 0) return null
+	const chosen = opts.protocol(offered, req)
+	return typeof chosen === "string" && offered.includes(chosen) ? chosen : null
+}
+
+/** Outbound bytes the runtime holds for this socket, when it reports them. */
+export function bufferedAmountOf(raw: unknown): number {
+	if (raw === null || typeof raw !== "object") return 0
+	const r = raw as { bufferedAmount?: unknown; getBufferedAmount?: () => unknown }
+	if (typeof r.getBufferedAmount === "function") {
+		const n = r.getBufferedAmount()
+		return typeof n === "number" ? n : 0
+	}
+	return typeof r.bufferedAmount === "number" ? r.bufferedAmount : 0
+}
+
+/** Whether an inbound message is larger than `limit` bytes. */
+export function exceedsPayload(data: ArrayBuffer | ArrayBufferView | Blob | string, limit: number): boolean {
+	if (typeof data === "string") {
+		if (data.length > limit) return true
+		/* a UTF-16 unit is at most 3 UTF-8 bytes, so most strings need no encode */
+		if (data.length * 3 <= limit) return false
+		return new TextEncoder().encode(data).byteLength > limit
+	}
+	if (typeof Blob !== "undefined" && data instanceof Blob) return data.size > limit
+	return (data as ArrayBuffer | ArrayBufferView).byteLength > limit
+}
+
+/** `data` as an `ArrayBuffer` holding exactly its bytes (a pooled Buffer's backing store is larger). */
+export function toArrayBuffer(data: ArrayBuffer | ArrayBufferView): ArrayBuffer {
+	if (data instanceof ArrayBuffer) return data
+	const { buffer, byteLength, byteOffset } = data
+	if (byteOffset === 0 && byteLength === buffer.byteLength && buffer instanceof ArrayBuffer) return buffer
+	return buffer.slice(byteOffset, byteOffset + byteLength) as ArrayBuffer
+}
+
+/** A close code a server may send: 1000, 1001-1014 except the reserved ones, or 3000-4999. */
+export function sendableCloseCode(code: number | undefined): number {
+	if (code === undefined) return 1000
+	if (code === 1000 || (code >= 3000 && code <= 4999)) return code
+	if (code >= 1001 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) return code
+	return 1000
+}

package/src/ws-origin.ts

@@ -0,0 +1,53 @@
+/**
+ * Which browser origins may open a WebSocket. A browser lets any page open a socket to any host
+ * and sends that host's cookies with it, so a cookie-authenticated socket is open to cross-site
+ * hijacking unless the server checks `Origin`.
+ *
+ * - `"*"`: every origin.
+ * - a list: those exact origins (`https://app.example.com`), plus same-origin.
+ * - a function: called with the `Origin` value; same-origin always passes.
+ * - unset (the default): same-origin always passes; a cross-origin upgrade is rejected when it
+ *   carries credentials (`Cookie` or `Authorization`), since that is what hijacking needs. A
+ *   request without `Origin` (not a browser) passes.
+ */
+export type WSOriginPolicy = "*" | readonly string[] | ((origin: string) => boolean)
+
+function originHost(origin: string): string | null {
+	if (origin === "null") return null
+	try {
+		return new URL(origin).host.toLowerCase()
+	} catch {
+		return null
+	}
+}
+
+export function validateOriginPolicy(policy: unknown): WSOriginPolicy {
+	if (policy === "*" || typeof policy === "function") return policy as WSOriginPolicy
+	if (Array.isArray(policy) && policy.every((o) => typeof o === "string")) {
+		for (const o of policy as string[]) {
+			if (originHost(o) === null)
+				throw new TypeError(`allowedOrigins: "${o}" is not an origin like https://example.com`)
+		}
+		return Object.freeze([...(policy as string[])])
+	}
+	throw new TypeError('allowedOrigins must be "*", a list of origins, or a function')
+}
+
+/**
+ * Whether an upgrade from `origin` may proceed. `host` is the host the client asked for
+ * (`clientInfo(ctx).host`, which follows `trustProxy`).
+ */
+export function originAllowed(
+	policy: WSOriginPolicy | null,
+	origin: string | null,
+	host: string | null,
+	hasCredentials: boolean,
+): boolean {
+	if (policy === "*") return true
+	if (origin === null) return true
+	const oh = originHost(origin)
+	if (oh !== null && host !== null && oh === host.toLowerCase()) return true
+	if (policy === null) return !hasCredentials
+	if (typeof policy === "function") return policy(origin) === true
+	return policy.includes(origin)
+}

package/src/yaml.ts

@@ -1,4 +1,10 @@
-/** JSON-compatible YAML 1.2 emitter — same document as JSON.stringify, different encoding. */
+/**
+ * JSON-compatible YAML 1.2 emitter: the same document as `JSON.stringify`, in a
+ * different encoding. Input is first normalized through JSON (so `undefined` keys
+ * are skipped, `Date` becomes its ISO string, `NaN` becomes `null`), then every
+ * string that is not plainly safe is written as a double-quoted scalar, which
+ * also reads the same under YAML 1.1 parsers.
+ */
 
 const INDENT = "  "
 
@@ -7,38 +13,55 @@ export function yamlSiblingPath(jsonPath: string): string {
 	return jsonPath.endsWith(".json") ? `${jsonPath.slice(0, -5)}.yaml` : `${jsonPath}.yaml`
 }
 
+/**
+ * Where an OpenAPI output configured at `path` is written. A `.yaml`/`.yml` path is that YAML file
+ * alone; any other path is JSON there plus its YAML sibling.
+ */
+export function openApiOutputPaths(path: string): { json: string | null; yaml: string } {
+	if (path.endsWith(".yaml") || path.endsWith(".yml")) return { json: null, yaml: path }
+	return { json: path, yaml: yamlSiblingPath(path) }
+}
+
 export function toYaml(value: unknown): string {
-	return `${emit(value, 0)}\n`
+	const json = JSON.stringify(value)
+	/* JSON.stringify(undefined) is undefined; emit the JSON equivalent of "nothing". */
+	const normalized: unknown = json === undefined ? null : JSON.parse(json)
+	return `${emit(normalized, 0)}\n`
 }
 
 function emit(value: unknown, indent: number): string {
-	if (value === null || value === undefined) return "null"
+	if (value === null) return "null"
 	if (typeof value === "boolean") return value ? "true" : "false"
-	if (typeof value === "number") {
-		if (!Number.isFinite(value)) return JSON.stringify(String(value))
-		return Object.is(value, -0) ? "-0" : String(value)
-	}
+	if (typeof value === "number") return String(value)
 	if (typeof value === "string") return emitString(value)
 	if (Array.isArray(value)) return emitArray(value, indent)
-	if (typeof value === "object") return emitObject(value as Record<string, unknown>, indent)
-	return JSON.stringify(String(value))
+	return emitObject(value as Record<string, unknown>, indent)
 }
 
+/*
+ * A plain scalar is used only for a conservative shape: starts with a letter,
+ * `_`, `/` or `$`; contains only word characters, `.`, `/`, `$`, `-`, `+`,
+ * `{}`, `()` and inner spaces. That excludes every indicator, `: `, ` #`,
+ * leading digits (numbers, YAML 1.1 octal and sexagesimal), and `.inf`/`.nan`.
+ */
+const PLAIN_RE = /^[A-Za-z_/$](?:[\w./${}()+-]| (?! ))*$/
+/* Words YAML 1.1 or 1.2 resolves to null or a boolean. */
+const RESERVED_RE = /^(?:y|n|yes|no|on|off|true|false|null|~)$/i
+
 function emitString(value: string): string {
-	if (value === "") return '""'
-	if (needsQuotes(value)) return JSON.stringify(value)
-	return value
+	if (PLAIN_RE.test(value) && !value.endsWith(" ") && !RESERVED_RE.test(value)) return value
+	return quote(value)
 }
 
-function needsQuotes(value: string): boolean {
-	if (/^[-?:{},[\],&*#|!>'%@`]/.test(value)) return true
-	if (/[\n\r\t]/.test(value)) return true
-	if (/^\s|\s$/.test(value)) return true
-	if (value.includes(": ") || value.includes(" #")) return true
-	if (/^(true|false|null|yes|no|on|off)$/i.test(value)) return true
-	if (/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return true
-	if (/^\d/.test(value)) return true
-	return false
+/*
+ * JSON string syntax is a valid YAML double-quoted scalar, except that YAML
+ * forbids raw DEL, C1 controls (other than NEL) and the BOM/non-characters.
+ */
+function quote(value: string): string {
+	return JSON.stringify(value).replace(
+		/[\u007f-\u0084\u0086-\u009f￾￿]/g,
+		(ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`,
+	)
 }
 
 function isNonEmptyCollection(value: unknown): boolean {
@@ -70,7 +93,7 @@ function emitObject(value: Record<string, unknown>, indent: number): string {
 	return keys
 		.map((key) => {
 			const child = value[key]
-			const renderedKey = needsQuotes(key) || key === "" ? JSON.stringify(key) : key
+			const renderedKey = emitString(key)
 			if (isNonEmptyCollection(child)) {
 				return `${pad}${renderedKey}:\n${emit(child, indent + 1)}`
 			}