@lovrozagar/honey 0.6.8 → 0.7.1

package/src/logger.ts

@@ -39,38 +39,61 @@ type CreateLoggerOptions = {
 	write?: (line: string) => void
 }
 
-function createLogger(opts?: CreateLoggerOptions): LoggerInstance {
-	const threshold = LEVELS[opts?.level ?? "info"]
-	const write = opts?.write ?? ((line: string) => console.log(line))
-	const base = opts?.base ?? {}
+/* Methods live on the prototype: `logger()` makes a child per request, and a
+ * closure-per-level instance cost seven allocations each time. */
+class Logger implements LoggerInstance {
+	level: LogLevel
+	#threshold: number
+	#write: (line: string) => void
+	#base: Record<string, unknown>
+
+	constructor(level: LogLevel, write: (line: string) => void, base: Record<string, unknown>) {
+		this.level = level
+		this.#threshold = LEVELS[level]
+		this.#write = write
+		this.#base = base
+	}
 
-	function emit(level: number, first: Record<string, unknown> | string, second?: string): void {
-		if (level < threshold) return
-		const obj =
-			typeof first === "string"
-				? { ...base, level, msg: first, time: Date.now() }
-				: { ...base, ...first, level, msg: second ?? "", time: Date.now() }
-		write(JSON.stringify(obj))
+	child(bindings: Record<string, unknown>): LoggerInstance {
+		return new Logger(this.level, this.#write, { ...this.#base, ...bindings })
+	}
+
+	trace(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.trace, first, second)
+	}
+
+	debug(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.debug, first, second)
+	}
+
+	info(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.info, first, second)
+	}
+
+	warn(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.warn, first, second)
+	}
+
+	error(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.error, first, second)
 	}
 
-	const instance: LoggerInstance = {
-		child(bindings: Record<string, unknown>): LoggerInstance {
-			return createLogger({
-				base: { ...base, ...bindings },
-				level: opts?.level,
-				write,
-			})
-		},
-		debug: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.debug, first, second),
-		error: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.error, first, second),
-		fatal: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.fatal, first, second),
-		info: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.info, first, second),
-		level: opts?.level ?? "info",
-		trace: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.trace, first, second),
-		warn: (first: Record<string, unknown> | string, second?: string) => emit(LEVELS.warn, first, second),
+	fatal(first: Record<string, unknown> | string, second?: string): void {
+		this.#emit(LEVELS.fatal, first, second)
+	}
+
+	#emit(level: number, first: Record<string, unknown> | string, second?: string): void {
+		if (level < this.#threshold) return
+		const obj =
+			typeof first === "string"
+				? { ...this.#base, level, msg: first, time: Date.now() }
+				: { ...this.#base, ...first, level, msg: second ?? "", time: Date.now() }
+		this.#write(JSON.stringify(obj))
 	}
+}
 
-	return instance
+function createLogger(opts?: CreateLoggerOptions): LoggerInstance {
+	return new Logger(opts?.level ?? "info", opts?.write ?? ((line: string) => console.log(line)), opts?.base ?? {})
 }
 
 /* ── request lifecycle middleware ── */
@@ -116,8 +139,13 @@ function logger(options?: LoggerOptions): MiddlewareFn<{ path: string; req: Requ
 				})
 			: noopLogger
 
+		/* a failing sink never fails the request, on the way in or out */
 		if (instance) {
-			child.info(`--> ${method} ${path}`)
+			try {
+				child.info(`--> ${method} ${path}`)
+			} catch (err) {
+				console.error("logger: failed to log request", err)
+			}
 		}
 
 		const response = await next({ log: child })
@@ -131,14 +159,15 @@ function logger(options?: LoggerOptions): MiddlewareFn<{ path: string; req: Requ
 			status: response.status,
 		}
 
-		if (skip?.(data)) {
-			return response
-		}
-
-		if (instance) {
-			child.info({ duration, status: response.status }, `<-- ${method} ${path}`)
-		} else {
-			log(data)
+		try {
+			if (skip?.(data)) return response
+			if (instance) {
+				child.info({ duration, status: response.status }, `<-- ${method} ${path}`)
+			} else {
+				log(data)
+			}
+		} catch (err) {
+			console.error("logger: failed to log request", err)
 		}
 
 		return response

package/src/media-type.ts

@@ -0,0 +1,104 @@
+/**
+ * One media-type parser (RFC 9110 §8.3.1) for every place that reads a `Content-Type`:
+ * input validation, `bodyLimit`, and the client. Type, subtype and parameter names are
+ * case-insensitive, so they are lowercased; parameter values keep their case.
+ *
+ * Pure and dependency-free: the client entry imports it too.
+ */
+
+export type MediaType = {
+	/** `type/subtype`, lowercased, without parameters */
+	essence: string
+	/** parameters by lowercased name; a repeated name keeps the first value */
+	params: Record<string, string>
+	subtype: string
+	/** the structured-syntax suffix (`json` for `application/vnd.api+json`), or `null` */
+	suffix: string | null
+	type: string
+}
+
+/* RFC 9110 token characters */
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/
+
+function isToken(s: string): boolean {
+	return s.length > 0 && TOKEN.test(s)
+}
+
+/**
+ * Parses a `Content-Type` (or any media type) value. Returns `null` for an absent or
+ * malformed value, so a caller never mistakes `application/jsonx` or `json` for JSON.
+ */
+export function parseMediaType(value: string | null | undefined): MediaType | null {
+	if (value === null || value === undefined) return null
+	const semi = value.indexOf(";")
+	const head = (semi === -1 ? value : value.slice(0, semi)).trim()
+	const slash = head.indexOf("/")
+	if (slash === -1) return null
+	const type = head.slice(0, slash).toLowerCase()
+	const subtype = head.slice(slash + 1).toLowerCase()
+	if (!isToken(type) || !isToken(subtype)) return null
+	const plus = subtype.lastIndexOf("+")
+	const suffix = plus > 0 && plus < subtype.length - 1 ? subtype.slice(plus + 1) : null
+	const params = Object.create(null) as Record<string, string>
+	if (semi !== -1) parseParams(value, semi + 1, params)
+	return { essence: `${type}/${subtype}`, params, subtype, suffix, type }
+}
+
+/* `; name=value` pairs; value is a token or a quoted-string. Malformed pairs are skipped,
+ * as browsers and undici do, rather than rejecting the whole header. */
+function parseParams(value: string, start: number, out: Record<string, string>): void {
+	let i = start
+	const n = value.length
+	while (i < n) {
+		while (i < n && (value[i] === " " || value[i] === "\t" || value[i] === ";")) i++
+		const eq = value.indexOf("=", i)
+		const nextSemi = value.indexOf(";", i)
+		if (eq === -1 || (nextSemi !== -1 && nextSemi < eq)) {
+			i = nextSemi === -1 ? n : nextSemi + 1
+			continue
+		}
+		const name = value.slice(i, eq).trim().toLowerCase()
+		i = eq + 1
+		let v: string
+		if (value[i] === '"') {
+			i++
+			let buf = ""
+			while (i < n && value[i] !== '"') {
+				if (value[i] === "\\" && i + 1 < n) i++
+				buf += value[i]
+				i++
+			}
+			v = buf
+			i++ /* closing quote */
+			const after = value.indexOf(";", i)
+			i = after === -1 ? n : after + 1
+		} else {
+			const end = value.indexOf(";", i)
+			v = (end === -1 ? value.slice(i) : value.slice(i, end)).trim()
+			i = end === -1 ? n : end + 1
+		}
+		if (isToken(name) && !(name in out)) out[name] = v
+	}
+}
+
+/** `application/json`, or any `+json` structured-syntax type (`application/problem+json`). */
+export function isJsonMediaType(mt: MediaType | null): boolean {
+	return mt !== null && (mt.essence === "application/json" || mt.suffix === "json")
+}
+
+/** Text-like bodies: `text/*`, `application/xml`, and any `+xml` type. */
+export function isTextMediaType(mt: MediaType | null): boolean {
+	return mt !== null && (mt.type === "text" || mt.essence === "application/xml" || mt.suffix === "xml")
+}
+
+export type BodyParser = "json" | "multipart" | "urlencoded"
+
+/** Which body parser a request `Content-Type` selects, or `null` when none applies. */
+export function bodyParserFor(contentType: string | null | undefined): BodyParser | null {
+	const mt = parseMediaType(contentType)
+	if (mt === null) return null
+	if (isJsonMediaType(mt)) return "json"
+	if (mt.essence === "multipart/form-data") return "multipart"
+	if (mt.essence === "application/x-www-form-urlencoded") return "urlencoded"
+	return null
+}

package/src/meta-spec-merge.ts

@@ -0,0 +1,80 @@
+/**
+ * Composition of metaSpec policies across mounted sub-apps. Kept apart from the policy engine
+ * so the app core can merge policies without loading the engine.
+ */
+import type { MetaSpecConfig, MetaSpecEntry, MetaSpecMergeConflict, MetaSpecStrictness } from "./types.ts"
+
+/** The strictness a declared policy actually runs with: `"error"` unless it says otherwise. */
+export function resolvedStrictness(config: MetaSpecConfig | null): MetaSpecStrictness {
+	return config?.strict ?? (config ? "error" : "off")
+}
+
+/**
+ * Merge a mounted sub-app's policy into a parent's.
+ *
+ * The parent wins on conflict, so one gateway keeps one answer for its aggregate document —
+ * with a single exception. A sub entry of `false` wins over anything the parent says, because
+ * hiding is a safety claim and the strictest claim has to survive composition: a worker that
+ * declares a field unpublishable must not have the gateway publish it. Wrongly hidden is a
+ * visible gap; wrongly published is a leak.
+ *
+ * Strictness is the parent's *resolved* setting: a parent that never wrote `strict` runs with
+ * `"error"`, and a sub-app's `"off"` must not downgrade it. Every other disagreement is
+ * recorded in `conflicts` and reported at codegen.
+ *
+ * Order-independent with respect to when the parent declares its own policy: callers may keep
+ * the absorbed sub policies and merge them in at codegen time.
+ */
+export function mergeMetaSpec(own: MetaSpecConfig | null, sub: MetaSpecConfig | null): MetaSpecConfig | null {
+	if (!sub) return own
+	if (!own) return sub
+	const conflicts: MetaSpecMergeConflict[] = [...(own.conflicts ?? []), ...(sub.conflicts ?? [])]
+
+	const meta: Record<string, MetaSpecEntry> = { ...sub.meta, ...own.meta }
+	for (const [key, subEntry] of Object.entries(sub.meta ?? {})) {
+		const ownEntry = own.meta?.[key]
+		if (ownEntry === undefined || ownEntry === subEntry) continue
+		if (subEntry === false && ownEntry !== false) {
+			meta[key] = false
+			conflicts.push({ key, resolution: "hidden", section: "meta" })
+			continue
+		}
+		conflicts.push({ key, resolution: "parent", section: "meta" })
+	}
+
+	const recordOverlap = (section: "profiles" | "schema", subSide: object, ownSide: object): void => {
+		for (const [key, subEntry] of Object.entries(subSide)) {
+			const ownEntry = (ownSide as Record<string, unknown>)[key]
+			if (ownEntry === undefined || ownEntry === subEntry) continue
+			conflicts.push({ key, resolution: "parent", section })
+		}
+	}
+	recordOverlap("schema", sub.schema ?? {}, own.schema ?? {})
+	recordOverlap("profiles", sub.profiles ?? {}, own.profiles ?? {})
+
+	return {
+		conflicts,
+		meta,
+		profiles: { ...sub.profiles, ...own.profiles },
+		schema: { ...sub.schema, ...own.schema },
+		strict: resolvedStrictness(own),
+	}
+}
+
+/** A policy as an app holds it: its own declaration and each mounted sub-app's source, unmerged. */
+export type MetaSpecSource = {
+	readonly declared: MetaSpecConfig | null
+	readonly absorbed: readonly MetaSpecSource[]
+}
+
+function resolveSource(source: MetaSpecSource): MetaSpecConfig | null {
+	let merged = source.declared
+	for (const sub of source.absorbed) merged = mergeMetaSpec(merged, resolveSource(sub))
+	return merged
+}
+
+/** The policy codegen applies to `app`: its own, with every mounted sub-app's merged in mount order. */
+export function metaSpecOf(app: unknown): MetaSpecConfig | null {
+	const source = (app as { _metaSpecSource?: MetaSpecSource })._metaSpecSource
+	return source === undefined ? null : resolveSource(source)
+}

package/src/middleware.ts

@@ -94,9 +94,8 @@ export function createMiddleware<TReqs = {}, TRet extends Promise<Response> = Pr
 }
 
 /**
- * Merge meta contributed by a middleware chain, in mount order. Resolved once at route
- * registration — never per request, because the precompiled route tree bakes `mt` as a literal
- * and a lazily-derived value would diverge from it.
+ * Merge meta contributed by a middleware chain, in run order (later wins). Resolved once when
+ * the app finalizes, from the chain the route runs — never per request.
  */
 export function collectMiddlewareMeta(
 	groups: ReadonlyArray<ReadonlyArray<RuntimeMiddleware>>,
@@ -114,20 +113,71 @@ export function collectMiddlewareMeta(
 }
 
 /**
- * Context properties that middleware additions must not overwrite.
- * These are set by the framework during request construction.
- * TypeScript prevents this at compile time; this guard catches runtime bypasses.
+ * Every name the framework owns on a request context — fields, lazy getters, methods and
+ * internal backing state. `next({ ... })` additions and `.context()` values may not use them:
+ * an addition would silently replace framework state, and a value assigned over a getter-only
+ * field throws on every request. TypeScript prevents most of this at compile time; this set
+ * is the runtime guard.
  */
-const RESERVED_CTX_KEYS = new Set(["background", "cookies", "env", "headers", "params", "req", "res", "search"])
+export const RESERVED_CTX_KEYS: ReadonlySet<string> = new Set([
+	"background",
+	"cookies",
+	"env",
+	"error",
+	"errors",
+	"executionCtx",
+	"headers",
+	"input",
+	"ip",
+	"meta",
+	"params",
+	"path",
+	"realtime",
+	"req",
+	"res",
+	"routePattern",
+	"search",
+	"searchAll",
+	"signal",
+	"tap",
+	"_ac",
+	"_errorToResponse",
+	"_isErrorResponse",
+	"_lzClient",
+	"_lzCookies",
+	"_lzHeaders",
+	"_lzSearch",
+	"_lzSearchAll",
+	"_lzUrlFn",
+	"_pendingTaps",
+	"_rq",
+	"_setErrors",
+])
 
 /**
- * Compile a middleware chain + handler into a single function at registration time.
- * Eliminates per-request recursive dispatch, closure allocation, and Promise.resolve wrapping.
+ * Turns a value thrown inside a chain into the Response that stands in for it. Supplied by
+ * the app; must not throw.
+ */
+export type ChainErrorConverter = (thrown: unknown, ctx: object) => Response | Promise<Response>
+
+const NO_RESPONSE_HANDLER = "handler must return a Response — did you forget 'return ctx.res...()'?"
+const NO_RESPONSE_MIDDLEWARE = "middleware must return a Response — did you forget 'return next(...)'?"
+
+/**
+ * Compile a middleware chain + handler into a single function, once.
+ *
+ * With `convert`, every `next()` boundary is an error boundary: whatever the handler or a
+ * middleware throws (or rejects with) becomes a Response at that layer, so the middleware
+ * around it always gets a Response back from `next()` and its post-`next()` code — headers,
+ * logging, timing — runs on error responses too. The compiled function never rejects as long
+ * as `convert` does not. Without `convert`, throws propagate (the bare executor).
  */
 export function compileChain(
 	middlewares: RuntimeMiddleware[],
 	handler: (ctx: object) => Response | Promise<Response>,
+	convert?: ChainErrorConverter,
 ): (ctx: object) => Response | Promise<Response> {
+	if (convert !== undefined) return compileConverting(middlewares, handler, convert)
 	if (middlewares.length === 0) {
 		/* sync fast path — avoids microtask overhead for sync handlers */
 		return (ctx) => {
@@ -136,7 +186,7 @@ export function compileChain(
 				return result.then(validateResponse)
 			}
 			if (result === undefined || result === null) {
-				throw new Error("handler must return a Response — did you forget 'return ctx.res...()'?")
+				throw new Error(NO_RESPONSE_HANDLER)
 			}
 			return result
 		}
@@ -165,6 +215,56 @@ export function compileChain(
 	return (ctx) => executeChain(middlewares, ctx, handler)
 }
 
+function compileConverting(
+	middlewares: readonly RuntimeMiddleware[],
+	handler: (ctx: object) => Response | Promise<Response>,
+	convert: ChainErrorConverter,
+): (ctx: object) => Response | Promise<Response> {
+	const n = middlewares.length
+
+	const runHandler = (ctx: object): Response | Promise<Response> => {
+		let result: Response | Promise<Response>
+		try {
+			result = handler(ctx)
+		} catch (thrown) {
+			return convert(thrown, ctx)
+		}
+		if (result instanceof Promise) {
+			return result.then(
+				(value) => (value === undefined || value === null ? convert(new Error(NO_RESPONSE_HANDLER), ctx) : value),
+				(thrown: unknown) => convert(thrown, ctx),
+			)
+		}
+		if (result === undefined || result === null) return convert(new Error(NO_RESPONSE_HANDLER), ctx)
+		return result
+	}
+
+	const step = (i: number, ctx: object): Response | Promise<Response> => {
+		if (i === n) return runHandler(ctx)
+		const mw = middlewares[i] as RuntimeMiddleware
+		let called = false
+		const next = (additions?: Record<string, unknown>): Promise<Response> => {
+			if (called) throw new Error("next() called multiple times")
+			called = true
+			if (additions) mergeAdditions(ctx, additions)
+			const downstream = step(i + 1, ctx)
+			return downstream instanceof Promise ? downstream : Promise.resolve(downstream)
+		}
+		let out: Promise<Response>
+		try {
+			out = mw(ctx as Record<string, unknown>, next)
+		} catch (thrown) {
+			return convert(thrown, ctx)
+		}
+		return Promise.resolve(out).then(
+			(value) => (value === undefined || value === null ? convert(new Error(NO_RESPONSE_MIDDLEWARE), ctx) : value),
+			(thrown: unknown) => convert(thrown, ctx),
+		)
+	}
+
+	return (ctx) => step(0, ctx)
+}
+
 function mergeAdditions(ctx: object, additions: Record<string, unknown>): void {
 	for (const key in additions) {
 		if (!RESERVED_CTX_KEYS.has(key)) {
@@ -175,14 +275,14 @@ function mergeAdditions(ctx: object, additions: Record<string, unknown>): void {
 
 function validateResponse(result: Response): Response {
 	if (result === undefined || result === null) {
-		throw new Error("handler must return a Response — did you forget 'return ctx.res...()'?")
+		throw new Error(NO_RESPONSE_HANDLER)
 	}
 	return result
 }
 
 function validateMiddlewareResponse(result: Response): Response {
 	if (result === undefined || result === null) {
-		throw new Error("middleware must return a Response — did you forget 'return next(...)'?")
+		throw new Error(NO_RESPONSE_MIDDLEWARE)
 	}
 	return result
 }