@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/src/serve.ts

@@ -1,220 +0,0 @@
-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 = {
-	/**
-	 * 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">
-	url: string
-}
-
-export type HoneyServeOptions = {
-	cors?: boolean | CORSOptions
-	env?: Record<string, unknown>
-	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 =
-	"Honey.serve() cannot run on Cloudflare Workers. Export fetch:\n\n" +
-	"export default {\n" +
-	"  fetch: (req, env, ctx) => app.fetch(req, env, ctx),\n" +
-	"}\n"
-
-function publicHost(hostname: string): string {
-	return hostname === "0.0.0.0" || hostname === "::" ? "127.0.0.1" : hostname
-}
-
-export async function startHoneyServer(
-	app: Honey<Record<string, unknown>>,
-	options: HoneyServeOptions = {},
-): Promise<ServeHandle> {
-	const runtime = options.runtime ?? detectRuntime()
-	if (runtime === "cloudflare") {
-		throw new Error(CF_SERVE_ERROR)
-	}
-
-	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 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, 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(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,
-			runtime,
-			url: `http://${publicHost(hostname)}:${bound}`,
-		}
-	}
-
-	if (runtime === "deno") {
-		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, 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, 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(timeout = DEFAULT_CLOSE_TIMEOUT) {
-				ownAdapter(listening)?.closeAll?.(1001, "server shutting down")
-				if (server.shutdown) {
-					/* 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
-				}
-				ac.abort()
-				await within(server.finished ?? Promise.resolve(), timeout)
-			},
-			hostname,
-			port: bound,
-			runtime,
-			url: `http://${publicHost(hostname)}:${bound}`,
-		}
-	}
-
-	const { serve } = await import("./node.ts")
-	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)
-	})
-	const addr = server.address()
-	const bound = typeof addr === "object" && addr !== null ? addr.port : port
-	return {
-		async close(timeout = DEFAULT_CLOSE_TIMEOUT) {
-			await server.shutdown(timeout)
-		},
-		hostname,
-		port: bound,
-		runtime: "node",
-		url: `http://${publicHost(hostname)}:${bound}`,
-	}
-}
-
-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,71 +0,0 @@
-import { namedMiddleware } from "./middleware.ts"
-import type { MiddlewareFn } from "./middleware.ts"
-import { withHeaders } from "./with-headers.ts"
-
-export type Timing = {
-	end(name: string): void
-	start(name: string, description?: string): void
-}
-
-type TimingEntry = {
-	description?: string
-	end?: number
-	start: number
-}
-
-/* metric names are RFC 9110 tokens; anything else becomes `_` */
-const nonTokenRe = /[^!#$%&'*+.^`|~\w-]/g
-function sanitizeName(name: string): string {
-	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(nonQuotableRe, "?").replace(/[\\"]/g, "\\$&")
-}
-
-export function serverTiming(): MiddlewareFn<{}, { timing: Timing }> {
-	const mw: MiddlewareFn<{}, { timing: Timing }> = async (_ctx, next) => {
-		const requestStart = performance.now()
-		const entries = new Map<string, TimingEntry>()
-
-		const timing: Timing = {
-			end(name: string) {
-				const entry = entries.get(name)
-				if (entry) {
-					entry.end = performance.now()
-				}
-			},
-			start(name: string, description?: string) {
-				entries.set(name, { description, start: performance.now() })
-			},
-		}
-
-		const response = await next({ timing })
-
-		/* auto-close any unclosed timings */
-		const now = performance.now()
-		const parts: string[] = []
-		for (const [name, entry] of entries) {
-			const dur = ((entry.end ?? now) - entry.start).toFixed(2)
-			let part = sanitizeName(name)
-			if (entry.description) {
-				part += `;desc="${escapeDescription(entry.description)}"`
-			}
-			part += `;dur=${dur}`
-			parts.push(part)
-		}
-
-		/* always include total request duration */
-		const totalDur = (performance.now() - requestStart).toFixed(2)
-		parts.push(`total;dur=${totalDur}`)
-
-		/* 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,112 +0,0 @@
-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
-}
-
-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 = normalizePrefix(config.prefix ?? "/")
-
-	const mw: MiddlewareFn<TCtx, {}> = async (ctx, next) => {
-		const method = ctx.req.method
-		if (method !== "GET" && method !== "HEAD") return next()
-
-		/* 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 {
-			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 response = await config.resolve(ctx, filePath)
-		if (response === null) return next()
-
-		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

@@ -1,156 +0,0 @@
-import type { HoneyError } from "../error.ts"
-
-type Span = {
-	addEvent(name: string, attributes?: Record<string, unknown>): void
-	end(): void
-	setAttribute(key: string, value: unknown): void
-}
-
-type Tracer = {
-	startSpan(name: string): Span
-}
-
-type TelemetryAdapter = {
-	onError?(ctx: { duration: number; error: HoneyError; method: string; path: string }): 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; 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 {
-	const spans = new WeakMap<Request, Span>()
-
-	return {
-		onError(ctx) {
-			try {
-				/*
-				 * onError doesn't receive req — error details are best captured
-				 * via a standalone span. Per-request root span is in onResponse.
-				 */
-				const span = options.tracer.startSpan("http.error")
-				span.setAttribute("error.key", ctx.error.errorKey)
-				span.setAttribute("error.status", ctx.error.status)
-				span.setAttribute("http.duration_ms", ctx.duration)
-				span.end()
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onHandler(ctx) {
-			try {
-				const span = options.tracer.startSpan("http.handler")
-				span.setAttribute("http.method", ctx.method)
-				/* 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()
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onMethodNotAllowed(ctx) {
-			try {
-				const span = spans.get(ctx.req)
-				if (span) {
-					span.addEvent("method_not_allowed", {
-						"http.allowed_methods": ctx.allowed.join(", "),
-						"http.method": ctx.method,
-						"url.path": ctx.path,
-					})
-				}
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onMiddleware(ctx) {
-			try {
-				const span = options.tracer.startSpan(`middleware.${ctx.name}`)
-				span.setAttribute("middleware.name", ctx.name)
-				span.setAttribute("middleware.duration_ms", ctx.duration)
-				if (ctx.error) span.addEvent("error")
-				span.end()
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onNotFound(ctx) {
-			try {
-				const span = spans.get(ctx.req)
-				if (span) {
-					span.addEvent("not_found", {
-						"http.method": ctx.method,
-						"url.path": ctx.path,
-					})
-				}
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onRequest(ctx) {
-			try {
-				const span = options.tracer.startSpan("http.request")
-				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 */
-			}
-		},
-
-		onResponse(ctx) {
-			try {
-				const span = spans.get(ctx.req)
-				if (span) {
-					span.setAttribute("http.status_code", ctx.status)
-					span.setAttribute("http.duration_ms", ctx.duration)
-					span.end()
-					spans.delete(ctx.req)
-				}
-			} catch {
-				/* swallow */
-			}
-		},
-
-		onRoute(ctx) {
-			try {
-				const span = spans.get(ctx.req)
-				if (span) {
-					span.setAttribute("http.method", ctx.method)
-					if (ctx.route !== undefined && ctx.route !== "") span.setAttribute("http.route", ctx.route)
-				}
-			} catch {
-				/* swallow */
-			}
-		},
-	}
-}