@lovrozagar/honey 0.6.5 → 0.7.0

package/src/serve-slot.ts

@@ -1,9 +1,16 @@
+import { detectRuntime } from "./detect-runtime.ts"
 import type { HoneyServeOptions, ServeHandle } from "./serve.ts"
 
 export type ServeStart = (app: unknown, options?: HoneyServeOptions) => Promise<ServeHandle>
 
 const MISSING = 'Honey.serve() requires `import "@lovrozagar/honey/serve"` in the app entry.'
 
+/**
+ * Set while codegen evaluates an app module. A global, not a module variable: the app may load a
+ * different copy of this module than the generator (jiti instance, source vs compiled build).
+ */
+const CODEGEN = Symbol.for("@lovrozagar/honey.codegen")
+
 let runtime: ServeStart | undefined
 
 export function registerServeRuntime(next: ServeStart): void {
@@ -15,6 +22,37 @@ export function resetServeRuntime(): void {
 }
 
 export function getServeRuntime(): ServeStart {
+	if (isCodegenProcess()) return codegenServe
 	if (!runtime) throw new Error(MISSING)
 	return runtime
 }
+
+/** Marks this process as running codegen: `app.serve()` resolves without listening. */
+export function setCodegenProcess(active: boolean): void {
+	const slot = globalThis as unknown as Record<symbol, unknown>
+	if (active) slot[CODEGEN] = true
+	else delete slot[CODEGEN]
+}
+
+export function isCodegenProcess(): boolean {
+	return (globalThis as unknown as Record<symbol, unknown>)[CODEGEN] === true
+}
+
+/* codegen loads the app to read its routes; a top-level `await app.serve()` must not bind a port */
+const codegenServe: ServeStart = async (_app, options = {}) => {
+	let detected = options.runtime
+	try {
+		detected ??= detectRuntime()
+	} catch {
+		detected = "node"
+	}
+	const hostname = options.hostname ?? "127.0.0.1"
+	const port = options.port ?? 3000
+	return {
+		async close() {},
+		hostname,
+		port,
+		runtime: detected === "cloudflare" ? "node" : detected,
+		url: `http://${hostname}:${port}`,
+	}
+}

package/src/serve.ts

@@ -1,12 +1,20 @@
 import type { Honey } from "./index.ts"
 import { cors, type CORSOptions } from "./cors.ts"
 import { detectRuntime, type ServeRuntime } from "./detect-runtime.ts"
+import { DEFAULT_MAX_REQUEST_BODY } from "./request-limits.ts"
+import { setPeerAddress } from "./peer.ts"
+import { hasValidHost } from "./client-info.ts"
+import type { WSAdapter } from "./ws/cloudflare.ts"
 
 export type { ServeRuntime }
 export { detectRuntime }
 
 export type ServeHandle = {
-	close(): Promise<void>
+	/**
+	 * Stop accepting connections, close WebSockets with 1001, and let in-flight requests finish
+	 * for up to `timeout` ms (default 1000); then every connection is cut. Same on Node, Bun and Deno.
+	 */
+	close(timeout?: number): Promise<void>
 	hostname: string
 	port: number
 	runtime: Exclude<ServeRuntime, "cloudflare">
@@ -19,6 +27,41 @@ export type HoneyServeOptions = {
 	hostname?: string
 	port?: number
 	runtime?: ServeRuntime
+	/**
+	 * Largest request body, in bytes; a bigger one is answered 413. Default 128 MiB on Node and
+	 * Bun. Deno has no cap of its own.
+	 */
+	maxRequestBodySize?: number
+	/** Node only: `server.headersTimeout`, ms. */
+	headersTimeout?: number
+	/** Node only: `server.requestTimeout`, ms. */
+	requestTimeout?: number
+	/** Node only: `server.keepAliveTimeout`, ms. */
+	keepAliveTimeout?: number
+	/** Node only: how long an upgrade request may take to become a WebSocket, ms (default 30 000). */
+	upgradeTimeout?: number
+}
+
+const DEFAULT_CLOSE_TIMEOUT = 1_000
+
+type AppInternals = { _graph: { settings: { wsAdapter: WSAdapter | null } } }
+
+/** The adapter the app already has (`app.wsAdapter(...)`), if any: serve() keeps it. */
+function ownAdapter(app: Honey<Record<string, unknown>>): WSAdapter | null {
+	return (app as unknown as AppInternals)._graph.settings.wsAdapter
+}
+
+/** Settle with `work`, or with `"timeout"` after `ms`; the timer never outlives the race. */
+async function within(work: Promise<unknown>, ms: number): Promise<"done" | "timeout"> {
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const timeout = new Promise<"timeout">((r) => {
+		timer = setTimeout(() => r("timeout"), ms)
+	})
+	try {
+		return await Promise.race([work.then(() => "done" as const), timeout])
+	} finally {
+		clearTimeout(timer)
+	}
 }
 
 const CF_SERVE_ERROR =
@@ -40,31 +83,51 @@ export async function startHoneyServer(
 		throw new Error(CF_SERVE_ERROR)
 	}
 
-	let listening: Honey<Record<string, unknown>> = app
-	if (options.cors) {
-		const corsOpts = options.cors === true ? undefined : options.cors
-		listening = app.use(cors(corsOpts)) as Honey<Record<string, unknown>>
-	}
+	const listening: Honey<Record<string, unknown>> = app
+	/* app-wide: every route, 404, 405 and preflight run it first — replaced, not stacked, on a re-serve */
+	const corsMw = options.cors ? cors(options.cors === true ? undefined : options.cors) : null
+	;(app as unknown as { _setGlobal(key: string, mw: unknown): void })._setGlobal("serve:cors", corsMw)
 
 	const hostname = options.hostname ?? (runtime === "deno" ? "127.0.0.1" : "0.0.0.0")
 	const port = options.port ?? 3000
 	const env = (options.env ?? {}) as Record<string, unknown>
 
 	if (runtime === "bun") {
-		const { bunWebSocket } = await import("./ws/bun.ts")
-		const bunWs = bunWebSocket()
-		listening.wsAdapter(bunWs)
+		const existing = ownAdapter(listening)
+		let bunWs: BunWSAdapter
+		if (existing === null) {
+			const { bunWebSocket } = await import("./ws/bun.ts")
+			bunWs = bunWebSocket()
+			listening.wsAdapter(bunWs)
+		} else if ("websocket" in existing) {
+			bunWs = existing as BunWSAdapter
+		} else {
+			throw new Error("serve() on Bun needs a bunWebSocket() adapter, but app.wsAdapter() was given another one")
+		}
 		const BunNs = (globalThis as unknown as { Bun: { serve: (opts: Record<string, unknown>) => BunServer } }).Bun
+		/* `server` is the same object for every request: build the env once */
+		let envWithServer: Record<string, unknown> | null = null
 		const server = BunNs.serve({
-			fetch: (req: Request, server: unknown) => listening.fetch(req, { ...env, server }),
+			fetch: (req: Request, srv: unknown) => {
+				if (envWithServer === null) envWithServer = { ...env, server: srv }
+				return listening.fetch(req, envWithServer)
+			},
 			hostname,
+			maxRequestBodySize: options.maxRequestBodySize ?? DEFAULT_MAX_REQUEST_BODY,
 			port,
 			websocket: bunWs.websocket,
 		})
 		const bound = server.port
 		return {
-			async close() {
-				await Promise.resolve(server.stop(true))
+			async close(timeout = DEFAULT_CLOSE_TIMEOUT) {
+				bunWs.closeAll?.(1001, "server shutting down")
+				/* graceful first: in-flight requests finish; then cut what is left. Bun before 1.4 keeps
+				 * idle keep-alive connections serving after stop(false), so close those explicitly,
+				 * now and again once in-flight requests have finished and left theirs idle. */
+				const graceful = Promise.resolve(server.stop(false))
+				server.closeIdleConnections?.()
+				if ((await within(graceful, timeout)) === "timeout") await Promise.resolve(server.stop(true))
+				server.closeIdleConnections?.()
 			},
 			hostname,
 			port: bound,
@@ -74,29 +137,40 @@ export async function startHoneyServer(
 	}
 
 	if (runtime === "deno") {
-		const { denoWebSocket } = await import("./ws/deno.ts")
-		listening.wsAdapter(denoWebSocket())
+		if (ownAdapter(listening) === null) {
+			const { denoWebSocket } = await import("./ws/deno.ts")
+			listening.wsAdapter(denoWebSocket())
+		}
 		const DenoNs = (
 			globalThis as unknown as {
 				Deno: {
 					serve: (
 						opts: { hostname: string; port: number; signal?: AbortSignal },
-						handler: (req: Request) => Response | Promise<Response>,
+						handler: (req: Request, info: { remoteAddr?: { hostname?: string } }) => Response | Promise<Response>,
 					) => { addr?: { port?: number }; finished?: Promise<void>; shutdown?: () => Promise<void> }
 				}
 			}
 		).Deno
 		const ac = new AbortController()
-		const server = DenoNs.serve({ hostname, port, signal: ac.signal }, (req) => listening.fetch(req, env))
+		const server = DenoNs.serve({ hostname, port, signal: ac.signal }, (req, info) => {
+			/* Deno builds req.url from Host and the target: a `Host: x/admin?` would pick the path */
+			if (!hasValidHost(req)) return (listening as unknown as { _badRequestTarget(): Response })._badRequestTarget()
+			const peer = info?.remoteAddr?.hostname
+			if (typeof peer === "string") setPeerAddress(req, peer)
+			return listening.fetch(req, env)
+		})
 		const bound = server.addr?.port ?? port
 		return {
-			async close() {
-				ac.abort()
+			async close(timeout = DEFAULT_CLOSE_TIMEOUT) {
+				ownAdapter(listening)?.closeAll?.(1001, "server shutting down")
 				if (server.shutdown) {
-					await Promise.race([server.shutdown(), new Promise<void>((r) => setTimeout(r, 1_000))])
+					/* graceful: in-flight requests finish. Deno has no forced close, so a request still
+					 * running after `timeout` ends on its own (aborting the signal now would throw) */
+					await within(server.shutdown(), timeout)
 					return
 				}
-				await Promise.race([server.finished ?? Promise.resolve(), new Promise<void>((r) => setTimeout(r, 1_000))])
+				ac.abort()
+				await within(server.finished ?? Promise.resolve(), timeout)
 			},
 			hostname,
 			port: bound,
@@ -105,10 +179,21 @@ export async function startHoneyServer(
 		}
 	}
 
-	const { nodeWebSocket } = await import("./ws/node.ts")
 	const { serve } = await import("./node.ts")
-	listening.wsAdapter(nodeWebSocket())
-	const server = serve(listening as never, { env, hostname, port })
+	if (ownAdapter(listening) === null) {
+		const { nodeWebSocket } = await import("./ws/node.ts")
+		listening.wsAdapter(nodeWebSocket())
+	}
+	const server = serve(listening as never, {
+		env,
+		headersTimeout: options.headersTimeout,
+		hostname,
+		keepAliveTimeout: options.keepAliveTimeout,
+		maxRequestBodySize: options.maxRequestBodySize,
+		port,
+		requestTimeout: options.requestTimeout,
+		upgradeTimeout: options.upgradeTimeout,
+	})
 	await new Promise<void>((resolve, reject) => {
 		server.once("listening", () => resolve())
 		server.once("error", reject)
@@ -116,8 +201,8 @@ export async function startHoneyServer(
 	const addr = server.address()
 	const bound = typeof addr === "object" && addr !== null ? addr.port : port
 	return {
-		async close() {
-			await server.shutdown(1_000)
+		async close(timeout = DEFAULT_CLOSE_TIMEOUT) {
+			await server.shutdown(timeout)
 		},
 		hostname,
 		port: bound,
@@ -126,7 +211,10 @@ export async function startHoneyServer(
 	}
 }
 
+type BunWSAdapter = WSAdapter & { websocket: Record<string, unknown> }
+
 type BunServer = {
+	closeIdleConnections?(): void
 	port: number
 	stop(closeActiveConnections?: boolean): void | Promise<void>
 }

package/src/server-timing.ts

@@ -1,5 +1,6 @@
 import { namedMiddleware } from "./middleware.ts"
 import type { MiddlewareFn } from "./middleware.ts"
+import { withHeaders } from "./with-headers.ts"
 
 export type Timing = {
 	end(name: string): void
@@ -12,14 +13,17 @@ type TimingEntry = {
 	start: number
 }
 
-/** Strip characters that would break Server-Timing header syntax */
-const unsafeNameRe = /[;,="]/g
+/* metric names are RFC 9110 tokens; anything else becomes `_` */
+const nonTokenRe = /[^!#$%&'*+.^`|~\w-]/g
 function sanitizeName(name: string): string {
-	return name.replace(unsafeNameRe, "")
+	const token = name.replace(nonTokenRe, "_")
+	return token.length > 0 ? token : "_"
 }
 
+/* descriptions are quoted-strings: latin1 only, no controls, `\` and `"` escaped */
+const nonQuotableRe = /[^\t\x20-\x7e\x80-\xff]/g
 function escapeDescription(desc: string): string {
-	return desc.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+	return desc.replace(nonQuotableRe, "?").replace(/[\\"]/g, "\\$&")
 }
 
 export function serverTiming(): MiddlewareFn<{}, { timing: Timing }> {
@@ -58,9 +62,9 @@ export function serverTiming(): MiddlewareFn<{}, { timing: Timing }> {
 		const totalDur = (performance.now() - requestStart).toFixed(2)
 		parts.push(`total;dur=${totalDur}`)
 
-		response.headers.set("server-timing", parts.join(", "))
-
-		return response
+		/* append: an upstream or handler Server-Timing is kept */
+		const value = parts.join(", ")
+		return withHeaders(response, (headers) => headers.append("server-timing", value))
 	}
 
 	return namedMiddleware("serverTiming", mw)

package/src/static.ts

@@ -1,58 +1,111 @@
 import { namedMiddleware } from "./middleware.ts"
 import type { MiddlewareFn } from "./middleware.ts"
+import { normalizePath, pathOfUrl } from "./request-path.ts"
+import { withHeaders } from "./with-headers.ts"
 
 type StaticConfig<TCtx> = {
+	/**
+	 * Returns the file for `filePath`, or `null` to fall through to the next handler.
+	 * `filePath` starts with `/`, is decoded once, and has no `.`, `..`, empty, NUL, `:` or
+	 * separator-bearing segments — joining it onto a root directory cannot leave that root,
+	 * on POSIX or Windows.
+	 */
 	resolve: (ctx: TCtx, filePath: string) => Response | null | Promise<Response | null>
+	/** Mount point, matched on whole segments: `/assets` serves `/assets/x`, never `/assets-private/x`. */
 	prefix?: string
+	/** Extra response headers; a function receives the same `filePath` that `resolve` got. */
 	headers?: Record<string, string> | ((filePath: string) => Record<string, string>)
+	/** Rewrites the decoded file path before `resolve`. The result is checked again. */
 	rewritePath?: (filePath: string, ctx: TCtx) => string
 }
 
-const TRAVERSAL = /(?:^|\/)\.\.\//
+function normalizePrefix(prefix: string): string {
+	const normalized = normalizePath(prefix.startsWith("/") ? prefix : `/${prefix}`)
+	if (normalized === null) throw new Error(`staticFiles: invalid prefix ${JSON.stringify(prefix)}`)
+	return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized
+}
+
+/**
+ * `/`-joined decoded segments, or `null` when any segment is malformed percent-encoding or
+ * decodes to something a file system treats specially (`.`, `..`, empty, a separator, NUL, `:`).
+ */
+function safeFilePath(encoded: string): string | null {
+	const parts = encoded.split("/")
+	const out: string[] = []
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i]
+		if (part === "") {
+			/* the leading slash, and a trailing one (a directory request) */
+			if (i === 0 || i === parts.length - 1) continue
+			return null
+		}
+		let seg: string
+		try {
+			seg = decodeURIComponent(part)
+		} catch {
+			return null
+		}
+		if (!isSafeSegment(seg)) return null
+		out.push(seg)
+	}
+	const joined = `/${out.join("/")}`
+	return out.length > 0 && encoded.endsWith("/") ? `${joined}/` : joined
+}
+
+function isSafeSegment(seg: string): boolean {
+	if (seg === "" || seg === "." || seg === "..") return false
+	/* `:` makes a Windows drive (`C:`) or alternate data stream (`a.txt::$DATA`) */
+	return !seg.includes("/") && !seg.includes("\\") && !seg.includes("\0") && !seg.includes(":")
+}
+
+/** Re-checks a `rewritePath` result: it must be the same safe shape `resolve` would get without one. */
+function safeRewrite(path: string): string | null {
+	if (!path.startsWith("/")) return null
+	const parts = path.split("/")
+	for (let i = 1; i < parts.length; i++) {
+		if (parts[i] === "" && i === parts.length - 1) continue
+		if (!isSafeSegment(parts[i])) return null
+	}
+	return path
+}
 
 export function staticFiles<TCtx extends { req: Request }>(config: StaticConfig<TCtx>): MiddlewareFn<TCtx, {}> {
-	const prefix = config.prefix ?? "/"
+	const prefix = normalizePrefix(config.prefix ?? "/")
 
 	const mw: MiddlewareFn<TCtx, {}> = async (ctx, next) => {
 		const method = ctx.req.method
 		if (method !== "GET" && method !== "HEAD") return next()
 
-		/* fast path extraction — no new URL() */
-		const raw = ctx.req.url
-		const protoEnd = raw.indexOf("//")
-		const pathStart = protoEnd === -1 ? 0 : raw.indexOf("/", protoEnd + 2)
-		const qIdx = pathStart === -1 ? -1 : raw.indexOf("?", pathStart)
-		let path: string
-		if (pathStart === -1) {
-			path = "/"
-		} else if (qIdx === -1) {
-			path = raw.substring(pathStart)
+		/* the normalized path the router matched — never the raw request target */
+		const fromCtx = (ctx as { path?: unknown }).path
+		const path = typeof fromCtx === "string" && fromCtx !== "" ? fromCtx : normalizePath(pathOfUrl(ctx.req.url))
+		if (path === null) return next()
+
+		let rest: string
+		if (prefix === "/") {
+			rest = path
+		} else if (path === prefix) {
+			rest = "/"
+		} else if (path.startsWith(prefix) && path.charCodeAt(prefix.length) === 47) {
+			rest = path.substring(prefix.length)
 		} else {
-			path = raw.substring(pathStart, qIdx)
+			return next()
 		}
 
-		if (!path.startsWith(prefix)) return next()
+		const decoded = safeFilePath(rest)
+		if (decoded === null) return next()
+		const filePath = config.rewritePath ? safeRewrite(config.rewritePath(decoded, ctx)) : decoded
+		if (filePath === null) return next()
 
-		const stripped = prefix === "/" ? path : path.substring(prefix.length)
-		const filePath = stripped === "" ? "/" : stripped
-
-		/* path traversal guard — reject encoded and literal .. segments */
-		const decoded = decodeURIComponent(filePath)
-		if (TRAVERSAL.test(decoded)) return next()
-
-		const resolved = config.rewritePath ? config.rewritePath(filePath, ctx) : filePath
-		const response = await config.resolve(ctx, resolved)
+		const response = await config.resolve(ctx, filePath)
 		if (response === null) return next()
 
-		/* apply extra headers */
-		if (config.headers) {
-			const extra = typeof config.headers === "function" ? config.headers(filePath) : config.headers
-			for (const key in extra) {
-				response.headers.set(key, extra[key])
-			}
-		}
-
-		return response
+		if (!config.headers) return response
+		/* a resolver's Response can have immutable headers (`fetch()`, a Workers ASSETS binding) */
+		const extra = typeof config.headers === "function" ? config.headers(filePath) : config.headers
+		return withHeaders(response, (headers) => {
+			for (const key of Object.keys(extra)) headers.set(key, extra[key])
+		})
 	}
 
 	return namedMiddleware("staticFiles", mw)

package/src/telemetry/otel.ts

@@ -12,13 +12,32 @@ type Tracer = {
 
 type TelemetryAdapter = {
 	onError?(ctx: { duration: number; error: HoneyError; method: string; path: string }): void
-	onHandler?(ctx: { duration: number; method: string; path: string; status: number }): void
+	onHandler?(ctx: { duration: number; method: string; path: string; route?: string; status: number }): void
 	onMethodNotAllowed?(ctx: { allowed: string[]; method: string; path: string; req: Request }): void
 	onMiddleware?(ctx: { duration: number; error?: unknown; name: string }): void
 	onNotFound?(ctx: { method: string; path: string; req: Request }): void
 	onRequest?(ctx: { env: unknown; req: Request }): void
 	onResponse?(ctx: { duration: number; req: Request; status: number }): void
-	onRoute?(ctx: { method: string; params: Record<string, string>; path: string; req: Request }): void
+	onRoute?(ctx: { method: string; params: Record<string, string>; path: string; req: Request; route?: string }): void
+}
+
+/**
+ * The request URL without its query string or fragment: queries carry tokens and session ids,
+ * and attribute values are exported to whatever backend the tracer feeds.
+ */
+function urlWithoutQuery(url: string): string {
+	const q = url.indexOf("?")
+	const h = url.indexOf("#")
+	const end = q === -1 ? h : h === -1 ? q : Math.min(q, h)
+	return end === -1 ? url : url.slice(0, end)
+}
+
+/** Path part of an absolute URL, without the query. */
+function pathOf(url: string): string {
+	const bare = urlWithoutQuery(url)
+	const scheme = bare.indexOf("//")
+	const start = scheme === -1 ? 0 : bare.indexOf("/", scheme + 2)
+	return start === -1 ? "/" : bare.slice(start)
 }
 
 export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
@@ -45,7 +64,8 @@ export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
 			try {
 				const span = options.tracer.startSpan("http.handler")
 				span.setAttribute("http.method", ctx.method)
-				span.setAttribute("http.route", ctx.path)
+				/* the pattern, never the request path: one series per route, not per id */
+				if (ctx.route !== undefined && ctx.route !== "") span.setAttribute("http.route", ctx.route)
 				span.setAttribute("http.status_code", ctx.status)
 				span.setAttribute("http.duration_ms", ctx.duration)
 				span.end()
@@ -61,7 +81,7 @@ export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
 					span.addEvent("method_not_allowed", {
 						"http.allowed_methods": ctx.allowed.join(", "),
 						"http.method": ctx.method,
-						"http.route": ctx.path,
+						"url.path": ctx.path,
 					})
 				}
 			} catch {
@@ -87,7 +107,7 @@ export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
 				if (span) {
 					span.addEvent("not_found", {
 						"http.method": ctx.method,
-						"http.path": ctx.path,
+						"url.path": ctx.path,
 					})
 				}
 			} catch {
@@ -98,7 +118,9 @@ export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
 		onRequest(ctx) {
 			try {
 				const span = options.tracer.startSpan("http.request")
-				span.setAttribute("http.url", ctx.req.url)
+				span.setAttribute("http.method", ctx.req.method)
+				span.setAttribute("http.url", urlWithoutQuery(ctx.req.url))
+				span.setAttribute("url.path", pathOf(ctx.req.url))
 				spans.set(ctx.req, span)
 			} catch {
 				/* swallow */
@@ -124,7 +146,7 @@ export function otelAdapter(options: { tracer: Tracer }): TelemetryAdapter {
 				const span = spans.get(ctx.req)
 				if (span) {
 					span.setAttribute("http.method", ctx.method)
-					span.setAttribute("http.route", ctx.path)
+					if (ctx.route !== undefined && ctx.route !== "") span.setAttribute("http.route", ctx.route)
 				}
 			} catch {
 				/* swallow */