@lovrozagar/honey 0.6.8 → 0.7.0

package/src/openapi/json-schema-slot.ts

@@ -1,3 +1,4 @@
+import { sanitizeZodJsonSchema } from "../codegen-sanitize.ts"
 import type { StandardSchemaLike } from "../types.ts"
 
 export type JsonSchemaConverter = (schema: StandardSchemaLike, io?: "input" | "output") => Record<string, unknown>
@@ -11,3 +12,42 @@ export function setJsonSchemaConverter(next: JsonSchemaConverter | undefined): v
 export function getJsonSchemaConverter(): JsonSchemaConverter | undefined {
 	return converter
 }
+
+type InstanceConverters = {
+	"~standard": {
+		jsonSchema?: Partial<Record<"input" | "output", (params?: unknown) => unknown>>
+		vendor: string
+	}
+	toJsonSchema?: () => unknown
+}
+
+/**
+ * The converter used when the full codegen one is not loaded (`@lovrozagar/honey/openapi/spec`
+ * on a worker). It uses only what the schema instance carries — Zod 4's Standard JSON Schema
+ * and ArkType's `toJsonSchema()` — so it pulls in no validator package. A node JSON Schema
+ * cannot express degrades to `{}`, never the whole schema.
+ */
+export function instanceJsonSchema(
+	schema: StandardSchemaLike,
+	io: "input" | "output" = "output",
+): Record<string, unknown> {
+	const s = schema as unknown as InstanceConverters
+	try {
+		const fromStandard = s["~standard"].jsonSchema?.[io]
+		if (typeof fromStandard === "function") {
+			const result = fromStandard({ libraryOptions: { unrepresentable: "any" }, target: "draft-2020-12" })
+			if (result !== null && typeof result === "object") {
+				return s["~standard"].vendor === "zod"
+					? sanitizeZodJsonSchema(result as Record<string, unknown>)
+					: (result as Record<string, unknown>)
+			}
+		}
+		if (typeof s.toJsonSchema === "function") {
+			const result = s.toJsonSchema()
+			if (result !== null && typeof result === "object") return result as Record<string, unknown>
+		}
+	} catch {
+		/* the schema cannot describe itself — an unconstrained schema is the honest answer */
+	}
+	return {}
+}

package/src/openapi/register.ts

@@ -1,14 +1,19 @@
 import { generateManifest, generateOpenApi } from "../codegen.ts"
 import { toYaml } from "../yaml.ts"
 import { scalar } from "./scalar.ts"
+import { artifactResponse, toServedArtifact } from "./serve.ts"
 import { swagger } from "./swagger.ts"
 import { registerOpenApiRuntime } from "./spec-factory.ts"
 
 export function enableOpenApi(): void {
 	registerOpenApiRuntime({
+		artifactResponse,
 		docsUi: (kind, specUrl) => (kind === "swagger" ? swagger({ url: specUrl }) : scalar({ url: specUrl })),
-		generateManifest: (app) => Promise.resolve(generateManifest(app as never)),
-		generateOpenApi: (app, options) => generateOpenApi(app as never, options),
+		/* served artifacts follow the document's visibility policy and never fail on one schema */
+		generateManifest: (app, options) =>
+			Promise.resolve(generateManifest(app as never, { visibility: "published", ...options })),
+		generateOpenApi: (app, options) => generateOpenApi(app as never, { onSchemaError: "warn", ...options }),
+		toServedArtifact,
 		toYaml,
 	})
 }

package/src/openapi/scalar.ts

@@ -1,4 +1,5 @@
 import type { TypedResponse } from "../response.ts"
+import { docsPage, escapeAttribute, inlineJson, SCALAR } from "./docs-page.ts"
 
 type ScalarOptions = {
 	url: string
@@ -7,11 +8,14 @@ type ScalarOptions = {
 
 export function scalar(
 	options: ScalarOptions,
-): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
+): (ctx: {
+	res: { html(sk: "ok", body: string, opts?: { headers?: Record<string, string> }): TypedResponse }
+}) => TypedResponse {
 	const { url, ...rest } = options
-	const config = JSON.stringify({ url, ...rest })
+	const config = inlineJson({ url, ...rest })
 
-	const html = `<!DOCTYPE html>
+	return docsPage(
+		(nonce) => `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="utf-8" />
@@ -20,14 +24,11 @@ export function scalar(
 </head>
 <body>
   <div id="app"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
-  <script>
+  <script src="${SCALAR.js.url}" integrity="${SCALAR.js.integrity}" crossorigin="anonymous"></script>
+  <script nonce="${escapeAttribute(nonce)}">
     Scalar.createApiReference(document.getElementById("app"), ${config})
   </script>
 </body>
-</html>`
-
-	const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
-	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
-	return handler
+</html>`,
+	)
 }

package/src/openapi/serve.ts

@@ -0,0 +1,39 @@
+/**
+ * Serving side of `app.openapi()` and `app.manifest()`: serialize a document once, tag it, and
+ * answer conditional requests. Part of the lazily loaded OpenAPI feature, so none of this sits
+ * in the core bundle.
+ */
+import { ifNoneMatchHits } from "../etag.ts"
+import type { ServedArtifact } from "./spec-factory.ts"
+
+const encoder = new TextEncoder()
+
+/** Base64url of the first 16 bytes of SHA-256, quoted: a strong validator for the exact bytes. */
+async function entityTag(body: string): Promise<string> {
+	const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(body))).subarray(0, 16)
+	let binary = ""
+	for (let i = 0; i < hash.length; i++) binary += String.fromCharCode(hash[i])
+	return `"${btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}"`
+}
+
+/** Serialize `value` once; the result is cached per route epoch by the caller. */
+export async function toServedArtifact(body: string, contentType: string): Promise<ServedArtifact> {
+	return { body, contentType, etag: await entityTag(body) }
+}
+
+/**
+ * The response for a served artifact. Clients revalidate (`no-cache`) rather than reuse a stale
+ * document after a deploy; an unchanged document costs a 304.
+ */
+export function artifactResponse(request: Request, artifact: ServedArtifact): Response {
+	const headers = {
+		"cache-control": "no-cache",
+		"content-type": artifact.contentType,
+		etag: artifact.etag,
+		"x-content-type-options": "nosniff",
+	}
+	if (ifNoneMatchHits(request.headers.get("if-none-match"), artifact.etag)) {
+		return new Response(null, { headers, status: 304 })
+	}
+	return new Response(artifact.body, { headers })
+}

package/src/openapi/spec-factory.ts

@@ -6,12 +6,19 @@ export type OpenApiGenerate = (
 		filterRoutes?: (route: { meta: unknown; method: string; path: string }) => boolean
 		info: { description?: string; title: string; version: string }
 		invalidate?: "error" | "off" | "warn" | { entityKey?: string; level?: "error" | "off" | "warn" }
+		onSchemaError?: "throw" | "warn"
 		profile?: string
 		securitySchemes?: Record<string, unknown>
 	},
 ) => Promise<unknown>
 
-export type ManifestGenerate = (app: unknown) => Promise<unknown>
+export type ManifestGenerate = (
+	app: unknown,
+	options?: {
+		filterRoutes?: (route: { meta: unknown; method: string; path: string }) => boolean
+		visibility?: "all" | "published"
+	},
+) => Promise<unknown>
 
 export type YamlGenerate = (value: unknown) => string
 
@@ -22,10 +29,16 @@ export type DocsUi = (
 	specUrl: string,
 ) => (ctx: { res: HoneyRes }) => Response | Promise<Response>
 
+/** A served document, serialized once per route epoch: the bytes, their type and a strong ETag. */
+export type ServedArtifact = { body: string; contentType: string; etag: string }
+
 export type OpenApiRuntime = {
+	/** Answer a request for a served artifact: `ETag`, `Cache-Control`, and 304 on a match. */
+	artifactResponse: (request: Request, artifact: ServedArtifact) => Response
 	docsUi: DocsUi
 	generateManifest: ManifestGenerate
 	generateOpenApi: OpenApiGenerate
+	toServedArtifact: (body: string, contentType: string) => Promise<ServedArtifact>
 	toYaml: YamlGenerate
 }
 
@@ -49,3 +62,39 @@ export function getOpenApiRuntime(): OpenApiRuntime {
 export function tryGetOpenApiRuntime(): OpenApiRuntime | undefined {
 	return runtime
 }
+
+/**
+ * Memoize `compute` per route epoch. A failure is cached too, until the routes change: a
+ * document that cannot be generated fails every request the same way instead of re-running the
+ * whole generation per request.
+ */
+export function epochCached<T>(epochOf: () => number, compute: () => Promise<T>): () => Promise<T> {
+	let entry: { epoch: number; value: Promise<T> } | null = null
+	return () => {
+		const epoch = epochOf()
+		if (entry === null || entry.epoch !== epoch) {
+			const value = Promise.resolve().then(compute)
+			/* handled here so a failure no request is awaiting yet is never an unhandled rejection */
+			value.catch(() => {})
+			entry = { epoch, value }
+		}
+		return entry.value
+	}
+}
+
+const APP = Symbol.for("honey.app")
+
+/**
+ * Bind an internal handler (`spec()`, docs UIs) to the app serving it. Returns a new function
+ * per app, so one `spec()` handler mounted on two apps documents each of them — binding onto
+ * the shared function object would make the second mount throw or steal the first.
+ */
+export function bindInternalHandler<F extends (ctx: never, app?: unknown) => unknown>(fn: F, app: unknown): F {
+	const bound = ((ctx: never) => fn(ctx, app)) as unknown as F
+	for (const key of Reflect.ownKeys(fn)) {
+		if (typeof key !== "symbol" || key === APP) continue
+		Object.defineProperty(bound, key, { value: (fn as unknown as Record<symbol, unknown>)[key] })
+	}
+	Object.defineProperty(bound, APP, { value: app })
+	return bound
+}

package/src/openapi/spec.ts

@@ -1,5 +1,5 @@
-import type { DefaultMeta } from "../types.ts"
 import type { TypedResponse } from "../response.ts"
+import type { DefaultMeta } from "../types.ts"
 import { generateOpenApiFromTree, type OpenApiRouteInfo } from "./document.ts"
 import { tryGetOpenApiRuntime } from "./spec-factory.ts"
 
@@ -13,38 +13,61 @@ type SpecOptions<TMeta = Record<string, unknown> | null> = {
 	version: string
 }
 
-/** Walks the live or intern tree. Intern trees omit `iv`/`os`; serve generate-time OpenAPI JSON as assets instead of this walker on a gateway isolate. */
+type SpecCtx = { res: { raw(response: Response): TypedResponse } }
+
+type Cached = { body: Promise<string>; epoch: number }
+
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" }
+
+function appEpoch(app: object): number {
+	return (app as { _epoch?: number })._epoch ?? 0
+}
+
+/**
+ * Serve an OpenAPI document for the app the handler is mounted on.
+ *
+ * Walks the live route graph. Schemas are converted with the full codegen converter when
+ * `@lovrozagar/honey/openapi` is loaded, and otherwise with what the schema instances carry
+ * (Zod 4, ArkType), so a worker bundle still documents bodies and parameters. The serialized
+ * document is cached per app and rebuilt when routes change; a failed build is cached for the
+ * same route graph too, so a broken schema costs one build, not one per request.
+ */
 export function spec<TMeta = Record<string, unknown> | null>(
 	options: SpecOptions<TMeta>,
-): (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => TypedResponse | Promise<TypedResponse> {
-	let cached: string | null = null
-
-	const handler = async (ctx: { res: { json(sk: "ok", data: unknown): TypedResponse } }) => {
-		if (cached === null) {
-			const desc = Object.getOwnPropertyDescriptor(handler, Symbol.for("honey.app"))
-			const app = desc?.value
-			const generateOptions = {
-				filterRoutes: options.filterRoutes,
-				info: options,
-				/* a served document is not an authoring moment — the check belongs to `honey generate` */
-				invalidate: "off" as const,
-				profile: options.profile,
-				securitySchemes: options.securitySchemes,
-			}
-			const runtime = tryGetOpenApiRuntime()
-			const openApiSpec = app
-				? runtime
-					? await runtime.generateOpenApi(app, {
-							...generateOptions,
-							filterRoutes: options.filterRoutes as
-								| ((route: { meta: unknown; method: string; path: string }) => boolean)
-								| undefined,
-						})
-					: generateOpenApiFromTree(app, generateOptions)
-				: {}
-			cached = JSON.stringify(openApiSpec)
+): (ctx: SpecCtx, app?: unknown) => Promise<TypedResponse> {
+	const cache = new WeakMap<object, Cached>()
+	const info = { description: options.description, title: options.title, version: options.version }
+
+	const build = async (app: object): Promise<string> => {
+		const generateOptions = {
+			filterRoutes: options.filterRoutes as ((route: OpenApiRouteInfo) => boolean) | undefined,
+			info,
+			/* a served document is not an authoring moment — the check belongs to `honey generate` */
+			invalidate: "off" as const,
+			profile: options.profile,
+			securitySchemes: options.securitySchemes,
+		}
+		const runtime = tryGetOpenApiRuntime()
+		const document = runtime
+			? await runtime.generateOpenApi(app, { ...generateOptions, onSchemaError: "warn" })
+			: generateOpenApiFromTree(app, generateOptions)
+		return JSON.stringify(document)
+	}
+
+	const handler = async (ctx: SpecCtx, bound?: unknown): Promise<TypedResponse> => {
+		const app = (bound ?? Object.getOwnPropertyDescriptor(handler, Symbol.for("honey.app"))?.value) as
+			| object
+			| undefined
+		if (app === undefined) {
+			throw new Error("spec(): the handler is not mounted on an app — register it with app.get(path, spec(...))")
+		}
+		const epoch = appEpoch(app)
+		let entry = cache.get(app)
+		if (entry === undefined || entry.epoch !== epoch) {
+			entry = { body: build(app), epoch }
+			cache.set(app, entry)
 		}
-		return ctx.res.json("ok", JSON.parse(cached))
+		return ctx.res.raw(new Response(await entry.body, { headers: JSON_HEADERS }))
 	}
 	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
 	return handler

package/src/openapi/swagger.ts

@@ -1,4 +1,5 @@
 import type { TypedResponse } from "../response.ts"
+import { docsPage, escapeAttribute, inlineJson, SWAGGER_UI } from "./docs-page.ts"
 
 type SwaggerOptions = {
 	url: string
@@ -7,28 +8,28 @@ type SwaggerOptions = {
 
 export function swagger(
 	options: SwaggerOptions,
-): (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => TypedResponse {
+): (ctx: {
+	res: { html(sk: "ok", body: string, opts?: { headers?: Record<string, string> }): TypedResponse }
+}) => TypedResponse {
 	const { url, ...rest } = options
-	const config = JSON.stringify({ dom_id: "#swagger-ui", url, ...rest })
+	const config = inlineJson({ dom_id: "#swagger-ui", url, ...rest })
 
-	const html = `<!DOCTYPE html>
+	return docsPage(
+		(nonce) => `<!DOCTYPE html>
 <html>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Swagger UI</title>
-  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
+  <link rel="stylesheet" href="${SWAGGER_UI.css.url}" integrity="${SWAGGER_UI.css.integrity}" crossorigin="anonymous" />
 </head>
 <body>
   <div id="swagger-ui"></div>
-  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
-  <script>
+  <script src="${SWAGGER_UI.js.url}" integrity="${SWAGGER_UI.js.integrity}" crossorigin="anonymous"></script>
+  <script nonce="${escapeAttribute(nonce)}">
     SwaggerUIBundle(${config})
   </script>
 </body>
-</html>`
-
-	const handler = (ctx: { res: { html(sk: "ok", body: string): TypedResponse } }) => ctx.res.html("ok", html)
-	Object.defineProperty(handler, Symbol.for("honey.internal"), { value: true })
-	return handler
+</html>`,
+	)
 }

package/src/pattern.ts

@@ -0,0 +1,245 @@
+/**
+ * The one route-pattern grammar. Registration, the router tree, scope matching, codegen
+ * selectors and OpenAPI paths all consume the parsed form; nothing re-derives params from
+ * a pattern string with its own regex.
+ *
+ *     pattern  = "/" | ("/" segment)+ ["/"]
+ *     segment  = static | param | wildcard
+ *     param    = ":" name ["?"]        optional only as the last segment
+ *     wildcard = "*" [name]            last segment only; unnamed is called "*"
+ *     name     = [A-Za-z_$][A-Za-z0-9_$-]*
+ *
+ * Empty segments are dropped (`//a` is `/a`), a trailing slash is not significant, and a
+ * pattern without a leading slash gets one. `.` and `..` segments are rejected.
+ */
+
+import { encodeSegment } from "./request-path.ts"
+
+export type StaticSegment = { readonly k: "static"; readonly v: string }
+export type ParamSegment = { readonly k: "param"; readonly n: string; readonly o: boolean }
+export type WildcardSegment = { readonly k: "wildcard"; readonly n: string }
+export type Segment = StaticSegment | ParamSegment | WildcardSegment
+
+/** `METHOD /canonical/pattern` — stable identity of a route across apps, trees and codegen. */
+export type RouteId = string
+
+const NAME = /^[A-Za-z_$][A-Za-z0-9_$-]*$/
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i
+
+/** Name given to a `*` wildcard without a name. */
+export const UNNAMED_WILDCARD = "*"
+
+function invalid(path: string, why: string): never {
+	throw new Error(`Invalid route pattern "${path}": ${why}`)
+}
+
+export function parsePattern(path: string): Segment[] {
+	if (typeof path !== "string") invalid(String(path), "must be a string")
+	if (path.includes("#")) invalid(path, "fragments are not part of a route pattern")
+	const raw = path.split("/")
+	const segments: Segment[] = []
+	const names = new Set<string>()
+	for (let i = 0; i < raw.length; i++) {
+		const seg = raw[i]
+		if (seg === "") continue
+		/* `%2e` is a dot to every URL parser, so `/%2e%2e` can never be requested either */
+		if (DOT_SEGMENT.test(seg)) invalid(path, `"${seg}" segments are not allowed`)
+		const c = seg.charCodeAt(0)
+		if (c === 58 /* : */) {
+			const optional = seg.endsWith("?")
+			const name = optional ? seg.slice(1, -1) : seg.slice(1)
+			if (!NAME.test(name)) {
+				invalid(
+					path,
+					`parameter ":${name}" is not a valid name (letters, digits, "_", "$" and "-"; it takes the whole segment)`,
+				)
+			}
+			if (names.has(name)) invalid(path, `parameter ":${name}" appears twice`)
+			names.add(name)
+			segments.push({ k: "param", n: name, o: optional })
+			continue
+		}
+		if (c === 42 /* * */) {
+			const name = seg.length > 1 ? seg.slice(1) : UNNAMED_WILDCARD
+			if (name !== UNNAMED_WILDCARD && !NAME.test(name)) {
+				invalid(path, `wildcard "*${name}" is not a valid name`)
+			}
+			if (names.has(name)) invalid(path, `"${name}" appears twice`)
+			names.add(name)
+			segments.push({ k: "wildcard", n: name })
+			continue
+		}
+		if (seg.includes("?")) invalid(path, "query strings are not part of a route pattern")
+		/* the request path is percent-encoded the way URL parsing encodes it; so is a literal */
+		segments.push({ k: "static", v: encodeSegment(seg) })
+	}
+	for (let i = 0; i < segments.length - 1; i++) {
+		const s = segments[i]
+		if (s.k === "wildcard") invalid(path, "a wildcard must be the last segment")
+		if (s.k === "param" && s.o) invalid(path, "an optional parameter must be the last segment")
+	}
+	return segments
+}
+
+export function formatSegment(seg: Segment): string {
+	if (seg.k === "static") return seg.v
+	if (seg.k === "param") return `:${seg.n}${seg.o ? "?" : ""}`
+	return seg.n === UNNAMED_WILDCARD ? "*" : `*${seg.n}`
+}
+
+/** Canonical pattern string: leading slash, no empty segments, no trailing slash. */
+export function canonical(segments: readonly Segment[]): string {
+	if (segments.length === 0) return "/"
+	let out = ""
+	for (const seg of segments) out += `/${formatSegment(seg)}`
+	return out
+}
+
+/** Parse and re-print — throws on anything the grammar cannot express. */
+export function normalizePattern(path: string): string {
+	return canonical(parsePattern(path))
+}
+
+/** Join two patterns: `joinPatterns("/api/", "users")` is `/api/users`. */
+export function joinPatterns(base: string, path: string): string {
+	const b = parsePattern(base)
+	const p = parsePattern(path)
+	if (b.length > 0) {
+		const last = b[b.length - 1]
+		if (last.k === "wildcard" || (last.k === "param" && last.o)) {
+			if (p.length > 0) invalid(`${base}${path}`, "cannot append to a wildcard or optional parameter")
+		}
+	}
+	/* re-parse: a name used on both sides (`/:id` + `/:id`) is only caught on the whole pattern */
+	return normalizePattern(canonical([...b, ...p]))
+}
+
+/**
+ * Concrete variants of a pattern: an optional last parameter yields the pattern with and
+ * without it. Every other pattern is its own single variant.
+ */
+export function expandOptional(segments: readonly Segment[]): Segment[][] {
+	const last = segments[segments.length - 1]
+	if (last !== undefined && last.k === "param" && last.o) {
+		return [segments.slice(0, -1), [...segments.slice(0, -1), { k: "param", n: last.n, o: false }]]
+	}
+	return [[...segments]]
+}
+
+export function isStaticPattern(segments: readonly Segment[]): boolean {
+	for (const s of segments) if (s.k !== "static") return false
+	return true
+}
+
+/** Parameter and wildcard names, in order. */
+export function patternParams(segments: readonly Segment[]): string[] {
+	const out: string[] = []
+	for (const s of segments) if (s.k !== "static") out.push(s.n)
+	return out
+}
+
+export function routeId(method: string, pattern: string): RouteId {
+	return `${method} ${pattern}`
+}
+
+/** Split a RouteId back into method and canonical pattern. */
+export function splitRouteId(id: RouteId): { method: string; pattern: string } {
+	const sp = id.indexOf(" ")
+	return { method: id.slice(0, sp), pattern: id.slice(sp + 1) }
+}
+
+/** OpenAPI path template: `:id` and named wildcards become `{name}`. */
+export function toOpenApiTemplate(segments: readonly Segment[]): string {
+	if (segments.length === 0) return "/"
+	let out = ""
+	for (const s of segments) {
+		if (s.k === "static") out += `/${s.v}`
+		else if (s.k === "param") out += `/{${s.n}}`
+		else out += s.n === UNNAMED_WILDCARD ? "/{wildcard}" : `/{${s.n}}`
+	}
+	return out
+}
+
+/*
+ * Scopes. `app.use("/admin", mw)` guards request paths: a path is inside the scope when its
+ * leading segments match the scope pattern — static segments literally, `:param` any one
+ * segment, `*` and an optional last param everything below. The scope uses the route
+ * grammar, so `/orgs/:id` and `/admin/*` mean what they mean in a route.
+ */
+
+/** How much of a route a scope covers: every path it serves, none, or only some. */
+export type ScopeCoverage = "all" | "none" | "some"
+
+function coverVariant(route: readonly Segment[], scope: readonly Segment[]): ScopeCoverage {
+	let uncertain = false
+	for (let i = 0; i < scope.length; i++) {
+		const s = scope[i] as Segment
+		/* a wildcard or optional last param covers everything at and below this depth */
+		if (s.k === "wildcard" || (s.k === "param" && s.o)) return uncertain ? "some" : "all"
+		const r = route[i]
+		/* the route's paths end before the scope's do */
+		if (r === undefined) return "none"
+		/* a route wildcard serves paths both inside and outside the rest of the scope */
+		if (r.k === "wildcard") return "some"
+		if (r.k === "static") {
+			if (s.k === "static" && s.v !== r.v && safeDecode(r.v) !== safeDecode(s.v)) return "none"
+			continue
+		}
+		/* route param against a scope literal: inside the scope only when the value matches */
+		if (s.k === "static") uncertain = true
+	}
+	return uncertain ? "some" : "all"
+}
+
+function combine(a: ScopeCoverage, b: ScopeCoverage): ScopeCoverage {
+	return a === b ? a : "some"
+}
+
+/**
+ * Decide at registration time whether a scope covers a route. `"some"` means the answer
+ * depends on the request path (a route param or wildcard can land inside the scope), so the
+ * scope's middleware is guarded by {@link pathInScope} at request time.
+ */
+export function scopeCoverage(route: readonly Segment[], scope: readonly Segment[]): ScopeCoverage {
+	let out: ScopeCoverage | undefined
+	for (const rv of expandOptional(route)) {
+		const c = coverVariant(rv, scope)
+		out = out === undefined ? c : combine(out, c)
+	}
+	return out ?? "none"
+}
+
+function safeDecode(s: string): string {
+	if (s.indexOf("%") === -1) return s
+	try {
+		return decodeURIComponent(s)
+	} catch {
+		return s
+	}
+}
+
+/**
+ * Is a request path inside a scope? Splits the path the way the router does (empty segments
+ * dropped) and compares each segment both as sent and percent-decoded, so a route param that
+ * decodes to a scoped literal is guarded exactly like the literal.
+ */
+export function pathInScope(path: string, scope: readonly Segment[]): boolean {
+	let pos = 0
+	const len = path.length
+	for (let i = 0; i < scope.length; i++) {
+		const s = scope[i] as Segment
+		if (s.k === "wildcard" || (s.k === "param" && s.o)) return true
+		while (pos < len && path.charCodeAt(pos) === 47) pos++
+		if (pos >= len) return false
+		let end = path.indexOf("/", pos)
+		if (end === -1) end = len
+		if (s.k === "static") {
+			const seg = path.substring(pos, end)
+			/* both sides decoded: a literal is stored encoded (`%C3%A9`), and a request may spell the
+			 * same bytes with lowercase escapes (`%c3%a9`) or raw */
+			if (seg !== s.v && safeDecode(seg) !== safeDecode(s.v)) return false
+		}
+		pos = end
+	}
+	return true
+}

package/src/peer.ts

@@ -0,0 +1,53 @@
+/**
+ * The address of the TCP peer of a request, as the runtime reports it. Adapters register it;
+ * `ctx.ip` reads it through the app's trust setting (`trust.ts`).
+ *
+ * - Node (`serve()` from `/node`): the socket's `remoteAddress`
+ * - Bun: `server.requestIP(req)`, whether `serve()` or `Bun.serve({ fetch: app.fetch })` passed the server
+ * - Deno: `info.remoteAddr`, whether `serve()` or `Deno.serve(app.fetch)` passed the info
+ * - Cloudflare Workers: `CF-Connecting-IP`, which the edge sets and a client cannot
+ */
+
+type PeerSource = string | (() => string | null)
+
+const peers = new WeakMap<object, PeerSource>()
+
+/** A request object can report its own peer under this key (the Node shim does, allocation-free). */
+export const PEER_ADDRESS = Symbol.for("honey.peerAddress")
+
+/** Called by adapters before `app.fetch`. A function is called at most once, on first read. */
+export function setPeerAddress(req: Request, address: PeerSource): void {
+	peers.set(req, address)
+}
+
+function isWorkers(): boolean {
+	return (globalThis as { navigator?: { userAgent?: string } }).navigator?.userAgent === "Cloudflare-Workers"
+}
+
+type BunServerLike = { requestIP?: (req: Request) => { address?: string } | null }
+
+export function peerAddressOf(req: Request, env: unknown): string | null {
+	const own = (req as unknown as Record<symbol, unknown>)[PEER_ADDRESS]
+	if (typeof own === "string") return own
+	const registered = peers.get(req)
+	if (registered !== undefined) {
+		if (typeof registered === "string") return registered === "" ? null : registered
+		const resolved = registered()
+		peers.set(req, resolved ?? "")
+		return resolved
+	}
+	if (env !== null && typeof env === "object") {
+		const e = env as BunServerLike & { server?: BunServerLike; remoteAddr?: { hostname?: unknown } }
+		const server = typeof e.requestIP === "function" ? e : e.server
+		if (server !== undefined && typeof server.requestIP === "function") {
+			try {
+				return server.requestIP(req)?.address ?? null
+			} catch {
+				return null
+			}
+		}
+		if (typeof e.remoteAddr?.hostname === "string") return e.remoteAddr.hostname
+	}
+	if (isWorkers()) return req.headers.get("cf-connecting-ip")
+	return null
+}