@lovrozagar/honey 0.6.5 → 0.7.0

package/src/request-limits.ts

@@ -0,0 +1,2 @@
+/** Bun's default request body cap; honey's Node adapter applies the same one. */
+export const DEFAULT_MAX_REQUEST_BODY = 128 * 1024 * 1024

package/src/request-path.ts

@@ -0,0 +1,165 @@
+const PLAIN = 0
+/** a character the slow path rewrites: a backslash, or one `encodeSegment` percent-encodes */
+const SLOW = 1
+const PERCENT = 2
+const SLASH = 3
+
+const CHAR_CLASS = new Uint8Array(128)
+for (let c = 0; c < 128; c++) {
+	if (c <= 0x20 || c === 0x7f || c === 92 || needsEncoding(c)) CHAR_CLASS[c] = SLOW
+}
+CHAR_CLASS[37] = PERCENT
+CHAR_CLASS[47] = SLASH
+
+/**
+ * The request path the router, scopes, `ctx.path`, `proxy()` and `staticFiles()` all see.
+ *
+ * Policy, applied the same way on every runtime:
+ * - empty segments collapse: `//admin///users` is `/admin/users`
+ * - dot segments resolve: `.` is dropped and `..` removes the segment before it, never past
+ *   the root; `%2e` counts as a dot, as it does for WHATWG URL parsing
+ * - a trailing slash is kept (the router and `trailingSlash()` decide what it means)
+ * - a backslash is a `/`, and characters a URL path cannot hold raw (space, controls, `"`, `<`,
+ *   `>`, `` ` ``, `{`, `}`, non-ASCII) are percent-encoded as UTF-8 — what WHATWG URL parsing
+ *   does, so a runtime that hands the app the raw target (Deno) and one that parses it first
+ *   (Bun, Node) route the same bytes the same way
+ * - an encoded `/` or `\` (`%2F`, `%5C`) is rejected unless `encodedSlashes` is `"allow"`: a
+ *   segment that decodes to a path separator means one thing to this router and another to
+ *   whatever the path is forwarded to (a proxy upstream, a file system). Allowed, it stays
+ *   encoded in the path and decodes into a param value.
+ * - everything else stays percent-encoded; params are decoded when they are extracted
+ *
+ * Returns `null` for a rejected path; the app answers 400.
+ */
+export function normalizePath(raw: string, encodedSlashes: "allow" | "reject" = "reject"): string | null {
+	const rejectEncoded = encodedSlashes === "reject"
+	let canonical = raw.charCodeAt(0) === 47
+	const len = raw.length
+	for (let i = 0; i < len; i++) {
+		const c = raw.charCodeAt(i)
+		const k = c < 128 ? CHAR_CLASS[c] : SLOW
+		if (k === PLAIN) continue
+		if (k === SLOW) {
+			canonical = false
+		} else if (k === PERCENT) {
+			const hi = raw.charCodeAt(i + 1)
+			const lo = raw.charCodeAt(i + 2) | 0x20
+			if (hi === 50 /* 2 */) {
+				if (lo === 102 /* f */ && rejectEncoded) return null
+				if (lo === 101 /* e */) canonical = false
+			} else if (hi === 53 /* 5 */ && lo === 99 /* c */ && rejectEncoded) {
+				return null
+			}
+		} else {
+			const n = raw.charCodeAt(i + 1)
+			if (n === 47 || n === 46 /* . */) canonical = false
+		}
+	}
+	if (canonical) return raw
+
+	const out: string[] = []
+	const segments = raw.replaceAll("\\", "/").split("/")
+	let trailing = false
+	for (let i = 0; i < segments.length; i++) {
+		const seg = segments[i]
+		const last = i === segments.length - 1
+		if (seg === "") {
+			if (last && i > 0) trailing = true
+			continue
+		}
+		const dots = dotSegment(seg)
+		if (dots === 0) {
+			out.push(encodeSegment(seg))
+			continue
+		}
+		if (dots === 2) out.pop()
+		/* `/a/b/..` is `/a/`, like URL resolution */
+		if (last) trailing = true
+	}
+	if (out.length === 0) return "/"
+	const path = `/${out.join("/")}`
+	return trailing ? `${path}/` : path
+}
+
+/**
+ * The WHATWG path percent-encode set, plus every non-ASCII code unit. `^` joined the set in
+ * 2023; Node and Bun encode it, Deno's parser does not yet, so it is encoded here to keep
+ * `ctx.path` the same on all three.
+ */
+function needsEncoding(c: number): boolean {
+	return (
+		c <= 0x20 ||
+		c >= 0x7f ||
+		c === 34 /* " */ ||
+		c === 60 /* < */ ||
+		c === 62 /* > */ ||
+		c === 94 /* ^ */ ||
+		c === 96 /* ` */ ||
+		c === 123 /* { */ ||
+		c === 125 /* } */
+	)
+}
+
+/**
+ * One path segment as a normalized request path holds it: characters a URL path cannot hold
+ * raw become UTF-8 percent escapes, everything else (existing escapes included) is kept.
+ * Route patterns encode their static segments with this too, so `app.get("/é")` matches the
+ * `/%C3%A9` every runtime hands the app.
+ */
+export function encodeSegment(seg: string): string {
+	let needs = false
+	for (let i = 0; i < seg.length; i++) {
+		if (needsEncoding(seg.charCodeAt(i))) {
+			needs = true
+			break
+		}
+	}
+	if (!needs) return seg
+	let out = ""
+	for (const ch of seg) {
+		const c = ch.charCodeAt(0)
+		if (ch.length === 1 && !needsEncoding(c)) {
+			out += ch
+			continue
+		}
+		try {
+			out += encodeURIComponent(ch)
+		} catch {
+			/* a lone surrogate: U+FFFD, as URL parsing encodes it */
+			out += "%EF%BF%BD"
+		}
+	}
+	return out
+}
+
+/** 1 for `.`, 2 for `..` (either may be written `%2e`), 0 for anything else. */
+function dotSegment(seg: string): 0 | 1 | 2 {
+	if (seg.length > 6) return 0
+	const s = seg.toLowerCase().replaceAll("%2e", ".")
+	if (s === ".") return 1
+	if (s === "..") return 2
+	return 0
+}
+
+/** The path of a request URL without `new URL()`: everything from the first `/` after the authority, up to `?` or `#`. */
+export function pathOfUrl(rawUrl: string): string {
+	const protoEnd = rawUrl.indexOf("//")
+	const pathStart = protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2)
+	if (pathStart === -1) return "/"
+	for (let i = pathStart; i < rawUrl.length; i++) {
+		const c = rawUrl.charCodeAt(i)
+		if (c === 63 /* ? */ || c === 35 /* # */) return rawUrl.substring(pathStart, i)
+	}
+	return rawUrl.substring(pathStart)
+}
+
+/** `?query` of a request URL (with the `?`), or `""`. Never includes a fragment. */
+export function searchOfUrl(rawUrl: string): string {
+	const protoEnd = rawUrl.indexOf("//")
+	const pathStart = protoEnd === -1 ? 0 : rawUrl.indexOf("/", protoEnd + 2)
+	if (pathStart === -1) return ""
+	const q = rawUrl.indexOf("?", pathStart)
+	if (q === -1) return ""
+	const hash = rawUrl.indexOf("#", q)
+	return hash === -1 ? rawUrl.substring(q) : rawUrl.substring(q, hash)
+}

package/src/request-to-curl.ts

@@ -2,30 +2,51 @@ export type RequestToCurlOptions = {
 	excludeHeader?: (name: string, value: string) => boolean
 }
 
-function shellEscape(value: string): string {
-	return value.replace(/'/g, "'\\''")
+function hasControl(value: string): boolean {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i)
+		if (code < 0x20 || code === 0x7f) return true
+	}
+	return false
+}
+
+/**
+ * Quote one shell word. Plain values use single quotes; values with control
+ * characters (CR, LF, ESC, …) use ANSI-C `$'…'` quoting with `\xHH` escapes, so
+ * a pasted command cannot carry a raw newline and a log line cannot be split.
+ */
+export function shellQuote(value: string): string {
+	if (!hasControl(value)) return `'${value.replace(/'/g, "'\\''")}'`
+	let out = "$'"
+	for (const ch of value) {
+		const code = ch.codePointAt(0) as number
+		if (ch === "\\" || ch === "'") out += `\\${ch}`
+		else if (code < 0x20 || code === 0x7f) out += `\\x${code.toString(16).padStart(2, "0")}`
+		else out += ch
+	}
+	return `${out}'`
 }
 
 /**
- * Convert a native Request into a curl command string.
+ * Convert a native Request into a curl command string. Every word is quoted.
  * The request is cloned so reading the body does not consume the original stream.
  */
 export async function requestToCurl(request: Request, options?: RequestToCurlOptions): Promise<string> {
 	const clonedRequest = request.clone()
-	const parts: string[] = [`curl -X ${clonedRequest.method}`]
+	const parts: string[] = ["curl", "-X", shellQuote(clonedRequest.method)]
 
 	for (const [name, value] of clonedRequest.headers.entries()) {
 		if (options?.excludeHeader?.(name, value) === true) continue
-		parts.push(`-H '${shellEscape(name)}: ${shellEscape(value)}'`)
+		parts.push("-H", shellQuote(`${name}: ${value}`))
 	}
 
 	const body = await clonedRequest.text()
 
 	if (body.length > 0) {
-		parts.push(`--data-raw '${shellEscape(body)}'`)
+		parts.push("--data-raw", shellQuote(body))
 	}
 
-	parts.push(`'${shellEscape(clonedRequest.url)}'`)
+	parts.push(shellQuote(clonedRequest.url))
 
 	return parts.join(" ")
 }

package/src/response.ts

@@ -2,6 +2,7 @@ import type { CookieOptions } from "./cookie.ts"
 import { serializeCookie } from "./cookie.ts"
 import type { HoneyError } from "./error.ts"
 import { createHoneyResponse, isHoneyResponse } from "./honey-response.ts"
+import { generatorStream, producerStream, tagStream, type ProducerOptions } from "./producer-stream.ts"
 import type { StatusKey } from "./types.ts"
 import { statusKeyToCode } from "./types.ts"
 
@@ -28,9 +29,19 @@ export type SSEOptions = ResponseOptions & {
 }
 
 export type SSEStream = {
+	/** End the stream. Idempotent and synchronous: safe in a `finally`. */
 	close(): void
+	/** True once the stream ended: closed, or the client went away. */
+	readonly closed: boolean
 	lastEventId: string | undefined
+	/**
+	 * Queue an event. Resolves when the client is ready for more. After the stream ended it
+	 * rejects with an `AbortError`, which ends an awaiting loop; Honey does not report that
+	 * rejection, and an unawaited one never surfaces as an unhandled rejection.
+	 */
 	send(event: SSEEvent): Promise<void>
+	/** Aborts when the client disconnects, the request times out, or the server shuts down. */
+	readonly signal: AbortSignal
 }
 
 export type ErrorFormatter = (error: HoneyError, defaultShape: Record<string, unknown>) => Record<string, unknown>
@@ -55,7 +66,9 @@ function applyPlainOptions(headers: Record<string, string | string[]>, opts?: Re
 		}
 	}
 	if (opts?.cookies) {
-		const cookies: string[] = []
+		/* append, as `Headers.append` does on the native path: a `set-cookie` in `opts.headers` stays */
+		const existing = headers["set-cookie"]
+		const cookies: string[] = existing === undefined ? [] : Array.isArray(existing) ? [...existing] : [existing]
 		for (const [name, cookieOpts] of Object.entries(opts.cookies)) {
 			cookies.push(serializeCookie(name, cookieOpts))
 		}
@@ -63,6 +76,11 @@ function applyPlainOptions(headers: Record<string, string | string[]>, opts?: Re
 	}
 }
 
+/** Statuses whose responses never carry a body (Fetch "null body status"). */
+function isNullBodyStatus(status: number): boolean {
+	return status === 101 || status === 103 || status === 204 || status === 205 || status === 304
+}
+
 /* phantom brands — exist only at type level, never assigned at runtime */
 declare const CONTENT_TYPE: unique symbol
 declare const STATUS_KEY: unique symbol
@@ -93,6 +111,11 @@ const HTML_HEADERS = { "content-type": "text/html; charset=utf-8" }
 const CSV_HEADERS = { "content-type": "text/csv; charset=utf-8" }
 const BINARY_HEADERS = { "content-type": "application/octet-stream" }
 
+/** Report a stream producer failure where no logger is wired (a bare `HoneyRes`). */
+function reportToConsole(err: unknown): void {
+	console.error("honey: stream producer failed", err)
+}
+
 export class HoneyRes {
 	protected readonly _nodeOut: boolean
 
@@ -100,12 +123,22 @@ export class HoneyRes {
 		this._nodeOut = nodeOut
 	}
 
+	/** Signal and error reporting for streams; the per-request res wires `ctx.signal` and the logger. */
+	protected _producer(): ProducerOptions {
+		return { report: reportToConsole }
+	}
+
 	private _known<CT extends string, SK extends string>(
-		status: number,
+		statusCode: number,
 		headers: Record<string, string>,
 		raw: string | Uint8Array,
 		opts?: ResponseOptions,
 	): TypedResponse<CT, SK> {
+		const status = opts?.status ?? statusCode
+		if (isNullBodyStatus(status)) {
+			/* `new Response(body, { status: 204 })` throws on the native path; fail the same way everywhere */
+			throw new TypeError(`A ${status} response cannot have a body; use ctx.res.noContent() or another status`)
+		}
 		if (this._nodeOut) {
 			if (!opts?.headers && !opts?.cookies) {
 				return typed(createHoneyResponse({ headers, raw, status }))
@@ -181,129 +214,128 @@ export class HoneyRes {
 	}
 
 	sse(callback: (stream: SSEStream) => Promise<void>, opts?: SSEOptions): TypedResponse<"text/event-stream", "ok"> {
-		const { readable, writable } = new TransformStream()
-		const writer = writable.getWriter()
 		const encoder = new TextEncoder()
-		let keepaliveTimer: ReturnType<typeof setInterval> | undefined
-
-		let closed = false
-		const sseStream: SSEStream = {
-			close() {
-				if (closed) return
-				closed = true
-				if (keepaliveTimer !== undefined) clearInterval(keepaliveTimer)
-				writer.close()
-			},
-			lastEventId: opts?.lastEventId,
-			send(event) {
-				if (/[\r\n]/.test(event.event)) {
-					throw new Error("SSE event name must not contain newlines")
-				}
-				if (event.id && /[\r\n]/.test(event.id)) {
-					throw new Error("SSE id must not contain newlines")
-				}
-				const dataStr = typeof event.data === "string" ? event.data : JSON.stringify(event.data)
-				const dataLines = dataStr
-					.split(/\r\n|\r|\n/)
-					.map((line) => `data: ${line}`)
-					.join("\n")
-				let msg = `event: ${event.event}\n${dataLines}\n`
-				if (event.id) msg += `id: ${event.id}\n`
-				/** SSE retry must be a non-negative integer per spec — skip if invalid */
-				if (event.retry !== undefined && Number.isFinite(event.retry) && event.retry >= 0) {
-					msg += `retry: ${Math.floor(event.retry)}\n`
-				}
-				msg += "\n"
-				return writer.write(encoder.encode(msg))
-			},
-		}
-
-		if (opts?.defaultRetry !== undefined) {
-			writer.write(encoder.encode(`retry: ${opts.defaultRetry}\n\n`))
-		}
-
-		if (opts?.keepalive !== undefined && opts.keepalive > 0) {
-			keepaliveTimer = setInterval(() => {
-				writer.write(encoder.encode(": heartbeat\n\n")).catch(() => {
-					if (keepaliveTimer !== undefined) clearInterval(keepaliveTimer)
-				})
-			}, opts.keepalive)
-		}
-
-		void callback(sseStream).then(
-			async () => {
-				if (closed) return
-				closed = true
-				if (keepaliveTimer !== undefined) clearInterval(keepaliveTimer)
-				try {
-					await writer.close()
-				} catch {}
-			},
-			async () => {
-				if (closed) return
-				closed = true
-				if (keepaliveTimer !== undefined) clearInterval(keepaliveTimer)
-				try {
-					await writer.close()
-				} catch {}
-			},
-		)
+		const body = producerStream((sink) => {
+			const stream: SSEStream = {
+				close: () => sink.close(),
+				get closed() {
+					return sink.closed
+				},
+				lastEventId: opts?.lastEventId,
+				send(event) {
+					if (/[\r\n]/.test(event.event)) {
+						throw new Error("SSE event name must not contain newlines")
+					}
+					if (event.id && /[\r\n]/.test(event.id)) {
+						throw new Error("SSE id must not contain newlines")
+					}
+					const dataStr = typeof event.data === "string" ? event.data : JSON.stringify(event.data)
+					const dataLines = dataStr
+						.split(/\r\n|\r|\n/)
+						.map((line) => `data: ${line}`)
+						.join("\n")
+					let msg = `event: ${event.event}\n${dataLines}\n`
+					if (event.id) msg += `id: ${event.id}\n`
+					/** SSE retry must be a non-negative integer per spec — skip if invalid */
+					if (event.retry !== undefined && Number.isFinite(event.retry) && event.retry >= 0) {
+						msg += `retry: ${Math.floor(event.retry)}\n`
+					}
+					msg += "\n"
+					return sink.write(encoder.encode(msg))
+				},
+				signal: sink.signal,
+			}
+			if (opts?.defaultRetry !== undefined) {
+				void sink.write(encoder.encode(`retry: ${opts.defaultRetry}\n\n`))
+			}
+			if (opts?.keepalive !== undefined && opts.keepalive > 0) {
+				const heartbeat = encoder.encode(": heartbeat\n\n")
+				const timer = setInterval(() => {
+					void sink.write(heartbeat)
+				}, opts.keepalive)
+				sink.onEnd(() => clearInterval(timer))
+			}
+			return callback(stream)
+		}, this._producer())
 
+		/* no `connection: keep-alive`: HTTP/1.1 keeps the connection by default, the header would
+		 * override a client's `Connection: close`, and HTTP/2 forbids it */
 		const headers = new Headers({
 			"cache-control": "no-cache",
-			connection: "keep-alive",
 			"content-type": "text/event-stream",
 		})
 		applyResponseOptions(headers, opts)
-		return typed(new Response(readable, { headers, status: 200 }))
+		return typed(tagStream(new Response(body, { headers, status: opts?.status ?? 200 })))
 	}
 
+	/**
+	 * Stream a generator's values. A disconnect, `timeout()` or shutdown calls `generator.return()`,
+	 * so its `finally` runs; a throw mid-stream breaks the body instead of ending it cleanly.
+	 */
 	generate(
-		generator: AsyncGenerator<string, void, unknown> | Generator<string, void, unknown>,
+		generator: AsyncGenerator<string | Uint8Array, void, unknown> | Generator<string | Uint8Array, void, unknown>,
 		opts?: { contentType?: string; status?: number },
 	): TypedResponse<string, "ok"> {
-		const encoder = new TextEncoder()
-		const gen = generator
-		const readable = new ReadableStream({
-			async pull(controller) {
-				try {
-					const { done, value } = await gen.next()
-					if (done) {
-						controller.close()
-						return
-					}
-					controller.enqueue(encoder.encode(value))
-				} catch {
-					controller.close()
-				}
-			},
-		})
 		const headers = new Headers({
 			"content-type": opts?.contentType ?? "application/octet-stream",
 		})
-		return typed(new Response(readable, { headers, status: opts?.status ?? 200 }))
+		const body = generatorStream(generator, this._producer())
+		return typed(tagStream(new Response(body, { headers, status: opts?.status ?? 200 })))
 	}
 
+	/**
+	 * Write the body through a `WritableStream`. The callback starts when the body is first read
+	 * (never for HEAD); `signal` aborts when the client disconnects, the request times out, or the
+	 * server shuts down. Returning ends the body after queued writes flush, whether or not the
+	 * writable was closed; throwing breaks it, even while the callback holds a writer.
+	 */
 	stream(
-		callback: (writable: WritableStream) => Promise<void>,
+		callback: (writable: WritableStream, signal: AbortSignal) => Promise<void>,
 		opts?: ResponseOptions,
 	): TypedResponse<"application/octet-stream", "ok"> {
-		const { readable, writable } = new TransformStream()
-		void callback(writable).then(
-			async () => {
-				try {
-					await writable.close()
-				} catch {}
-			},
-			async () => {
-				try {
-					await writable.close()
-				} catch {}
-			},
-		)
+		const encoder = new TextEncoder()
+		const body = producerStream(async (sink) => {
+			/* `size()` runs as each chunk enters the writable's queue: it counts writes not yet flushed */
+			let queued = 0
+			let flushed = 0
+			let onFlushed: (() => void) | null = null
+			const writable = new WritableStream<unknown>(
+				{
+					abort(reason) {
+						sink.error(reason)
+					},
+					close() {
+						sink.close()
+					},
+					async write(chunk) {
+						try {
+							await sink.write(toBytes(chunk, encoder))
+						} finally {
+							flushed++
+							if (flushed === queued) onFlushed?.()
+						}
+					},
+				},
+				{
+					highWaterMark: 1,
+					size() {
+						queued++
+						return 1
+					},
+				},
+			)
+			await callback(writable, sink.signal)
+			if (sink.closed) return
+			if (flushed < queued) {
+				await new Promise<void>((resolve) => {
+					onFlushed = resolve
+					sink.onEnd(resolve)
+				})
+			}
+		}, this._producer())
 		const headers = new Headers()
 		applyResponseOptions(headers, opts)
-		return typed(new Response(readable, { headers, status: opts?.status ?? 200 }))
+		return typed(tagStream(new Response(body, { headers, status: opts?.status ?? 200 })))
 	}
 
 	text<SK extends StatusKey>(statusKey: SK, body: string, opts?: ResponseOptions): TypedResponse<"text/plain", SK> {
@@ -315,6 +347,14 @@ export class HoneyRes {
 	}
 }
 
+function toBytes(chunk: unknown, encoder: TextEncoder): Uint8Array {
+	if (chunk instanceof Uint8Array) return chunk
+	if (typeof chunk === "string") return encoder.encode(chunk)
+	if (chunk instanceof ArrayBuffer) return new Uint8Array(chunk)
+	if (ArrayBuffer.isView(chunk)) return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+	throw new TypeError("ctx.res.stream() chunks must be strings, ArrayBuffers or typed arrays")
+}
+
 export type CustomErrorFormatter = (error: HoneyError, data: Record<string, unknown>) => Record<string, unknown>
 
 export function createErrorResponse(