acrylblends 0.2.0 → 0.3.0

package/plugins/acryl-router/src/helpers/sse.ts

@@ -0,0 +1,83 @@
+import type { RouteContext } from '../types.ts'
+
+export interface SseStream {
+  /** Send one event. Objects and arrays are sent as JSON; strings as they are. */
+  send(data: unknown, options?: { readonly event?: string, readonly id?: string }): void
+  /** Send a comment line (a keep-alive that clients ignore). */
+  comment(text: string): void
+  /** End the stream from the server side. */
+  close(): void
+  /** Aborted when the client goes away or the router is disposed. */
+  readonly signal: AbortSignal
+}
+
+const HEADERS = {
+  'content-type': 'text/event-stream; charset=utf-8',
+  'cache-control': 'no-store',
+  'x-content-type-options': 'nosniff',
+} as const
+
+const encode = (text: string): Uint8Array => new TextEncoder().encode(text)
+
+export interface SseOptions {
+  /** A comment line is sent this often so proxies and browsers keep an idle stream open. Default 15 seconds. */
+  readonly keepAliveMs?: number
+}
+
+const DEFAULT_KEEP_ALIVE_MS = 15_000
+
+/**
+ * A server-sent-event response. `run` starts the stream; whatever cleanup function it returns runs exactly once when the stream
+ * ends for any reason (the client disconnects, `close()`, a plugin unload, the router being disposed). The request is held in flight with `waitUntil`
+ * until then, so disposal waits for the stream instead of leaking it.
+ */
+export function streamSSE(c: RouteContext, run: (stream: SseStream) => void | (() => void), options: SseOptions = {}): Response {
+  let finish!: () => void
+  c.waitUntil(new Promise<void>(resolve => { finish = resolve }))
+  let controller!: ReadableStreamDefaultController<Uint8Array>
+  let cleanup: (() => void) | undefined
+  let ended = false
+  let keepAlive: ReturnType<typeof setInterval> | undefined
+
+  const end = (): void => {
+    if (ended) return
+    ended = true
+    clearInterval(keepAlive)
+    c.signal.removeEventListener('abort', end)
+    try { cleanup?.() } finally {
+      try { controller.close() } catch { /* already closed */ }
+      finish()
+    }
+  }
+
+  const body = new ReadableStream<Uint8Array>({
+    start: ctrl => {
+      controller = ctrl
+      const stream: SseStream = {
+        signal: c.signal,
+        send: (data, options) => {
+          if (ended) return
+          const lines: string[] = []
+          if (options?.id !== undefined) lines.push(`id: ${options.id}`)
+          if (options?.event !== undefined) lines.push(`event: ${options.event}`)
+          const payload = typeof data === 'string' ? data : JSON.stringify(data)
+          for (const line of payload.split('\n')) lines.push(`data: ${line}`)
+          try { controller.enqueue(encode(`${lines.join('\n')}\n\n`)) } catch { end() }
+        },
+        comment: text => {
+          if (ended) return
+          try { controller.enqueue(encode(`: ${text.replaceAll('\n', ' ')}\n\n`)) } catch { end() }
+        },
+        close: end,
+      }
+      if (c.signal.aborted) { end(); return }
+      c.signal.addEventListener('abort', end, { once: true })
+      keepAlive = setInterval(() => { stream.comment('keepalive') }, options.keepAliveMs ?? DEFAULT_KEEP_ALIVE_MS)
+      keepAlive.unref()
+      cleanup = run(stream) ?? undefined
+      if (ended) { try { cleanup?.() } catch { /* the stream already ended */ } }
+    },
+    cancel: end,
+  })
+  return new Response(body, { headers: HEADERS })
+}

package/plugins/acryl-router/src/helpers/validate.ts

@@ -0,0 +1,44 @@
+import { HttpError } from '../http-error.ts'
+import type { Middleware, RouteContext } from '../types.ts'
+import { readJson } from './read-body.ts'
+
+/** The slice of the Standard Schema interface this needs; Schemastery (what Cordis uses), Zod and Valibot all implement it. */
+export interface StandardSchema<T = unknown> {
+  readonly '~standard': {
+    validate(value: unknown): StandardResult<T> | Promise<StandardResult<T>>
+  }
+}
+
+type StandardResult<T> =
+  | { readonly value: T, readonly issues?: undefined }
+  | { readonly issues: readonly { readonly message: string, readonly path?: readonly unknown[] | undefined }[] }
+
+export type ValidationTarget = 'json' | 'query' | 'param'
+
+const key = (target: ValidationTarget): string => `valid:${target}`
+
+/**
+ * Validate part of the request against a schema before the handler runs. A failure is a 400 with the issues; success stores the
+ * parsed value, which the handler reads with `valid(c, target)`. `json` reads the body within the limit; `query` is the first value of each query
+ * parameter; `param` is the matched path parameters.
+ */
+export function validate<T>(target: ValidationTarget, schema: StandardSchema<T>): Middleware {
+  return async (c, next) => {
+    const input = target === 'json' ? await readJson(c) : target === 'query' ? c.query() : { ...c.param() }
+    const result = await schema['~standard'].validate(input)
+    if (result.issues !== undefined) {
+      throw new HttpError(400, {
+        response: c.json({ error: `invalid ${target}`, issues: result.issues.map(issue => ({ message: issue.message, path: (issue.path ?? []).map(part => String(typeof part === 'object' && part !== null && 'key' in part ? (part as { key: unknown }).key : part)).join('.') })) }, 400),
+      })
+    }
+    c.set(key(target), result.value)
+    return next()
+  }
+}
+
+/** The value `validate(target, schema)` stored. Throws if that middleware did not run on this route. */
+export function valid<T>(c: RouteContext, target: ValidationTarget): T {
+  const value = c.get<T>(key(target))
+  if (value === undefined) throw new Error(`valid("${target}"): no validate("${target}", schema) ran before this handler`)
+  return value
+}

package/plugins/acryl-router/src/http-error.ts

@@ -0,0 +1,21 @@
+/**
+ * An error that carries the response it should become. A handler or middleware throws it to stop a request
+ * with a status: `throw new HttpError(401, { message: 'Sign in first' })`. The router answers with `getResponse()`; a registered
+ * `onError` handler still sees every other error.
+ */
+export class HttpError extends Error {
+  readonly status: number
+  private readonly response: Response | undefined
+
+  constructor(status: number, options: { readonly message?: string, readonly response?: Response, readonly cause?: unknown } = {}) {
+    super(options.message ?? `HTTP ${String(status)}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'HttpError'
+    this.status = status
+    this.response = options.response
+  }
+
+  /** The response this error stands for: the one it was given, or its message as plain text with its status. */
+  getResponse(): Response {
+    return this.response ?? new Response(this.message, { status: this.status, headers: { 'content-type': 'text/plain; charset=utf-8' } })
+  }
+}

package/plugins/acryl-router/src/index.ts

@@ -0,0 +1,6 @@
+export { Router, Config, apply, name, type RouterHttpService } from './service.ts'
+export { RouteTable, type RouteTableOptions } from './table.ts'
+export { compose } from './compose.ts'
+export { HttpError } from './http-error.ts'
+export type { Registrar, RouteHandlers, UseArguments } from './registrar.ts'
+export type { ConnectionInfo, ErrorHandler, NotFoundHandler, ResponseBody, Handler, Method, Middleware, Next, RouteContext, RouteMethod, TrailingSlash } from './types.ts'

package/plugins/acryl-router/src/middleware/body-limit.ts

@@ -0,0 +1,25 @@
+import type { Middleware, RouteContext } from '../types.ts'
+
+export interface BodyLimitOptions {
+  readonly maxBytes: number
+  /** The response for a body that is too large. Defaults to a 413 with a small JSON body. */
+  readonly onError?: (c: RouteContext) => Response | Promise<Response>
+}
+
+/** The context key under which the limit is kept for the body-reading helpers. */
+export const BODY_LIMIT_KEY = 'bodyLimit'
+
+/**
+ * Refuse a request whose declared `content-length` is over the limit, and remember the limit so `readJson` and `readText` enforce it on the bytes
+ * they read (a chunked body declares no length). A request body is a stream: only the helpers, or a handler that counts, can stop it midway.
+ */
+export function bodyLimit(options: BodyLimitOptions): Middleware {
+  return async (c, next) => {
+    const declared = Number(c.req.headers.get('content-length'))
+    if (Number.isFinite(declared) && declared > options.maxBytes) {
+      return options.onError === undefined ? c.json({ error: 'payload too large', maxBytes: options.maxBytes }, 413) : options.onError(c)
+    }
+    c.set(BODY_LIMIT_KEY, options.maxBytes)
+    return next()
+  }
+}

package/plugins/acryl-router/src/middleware/cors.ts

@@ -0,0 +1,46 @@
+import type { Middleware } from '../types.ts'
+import { appendVary, setHeaders } from '../util.ts'
+
+export interface CorsOptions {
+  /** `'*'`, one origin, a list, or a function that returns the origin to allow (or `undefined` to refuse). */
+  readonly origin?: string | readonly string[] | ((origin: string) => string | undefined)
+  readonly allowMethods?: readonly string[]
+  readonly allowHeaders?: readonly string[]
+  readonly exposeHeaders?: readonly string[]
+  readonly maxAge?: number
+  readonly credentials?: boolean
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']
+
+/** Cross-origin resource sharing, with preflight answered here (a 204 that never reaches the route). */
+export function cors(options: CorsOptions = {}): Middleware {
+  const allowed = (origin: string): string | undefined => {
+    const rule = options.origin ?? '*'
+    if (typeof rule === 'function') return rule(origin)
+    if (typeof rule === 'string') return rule === '*' || rule === origin ? rule : undefined
+    return rule.includes(origin) ? origin : undefined
+  }
+  return async (c, next) => {
+    const origin = c.req.headers.get('origin')
+    const match = origin === null ? undefined : allowed(origin)
+    const shared: Record<string, string> = {}
+    if (match !== undefined) shared['access-control-allow-origin'] = match
+    if (options.credentials === true && match !== undefined) shared['access-control-allow-credentials'] = 'true'
+    if (options.exposeHeaders !== undefined && options.exposeHeaders.length > 0) shared['access-control-expose-headers'] = options.exposeHeaders.join(',')
+
+    if (c.req.method === 'OPTIONS' && c.req.headers.has('access-control-request-method')) {
+      const headers = { ...shared }
+      if (match !== undefined) {
+        headers['access-control-allow-methods'] = (options.allowMethods ?? DEFAULT_METHODS).join(',')
+        const requested = c.req.headers.get('access-control-request-headers')
+        const allowHeaders = options.allowHeaders ?? (requested === null ? [] : requested.split(',').map(part => part.trim()))
+        if (allowHeaders.length > 0) headers['access-control-allow-headers'] = allowHeaders.join(',')
+        if (options.maxAge !== undefined) headers['access-control-max-age'] = String(options.maxAge)
+      }
+      return appendVary(c.body(null, 204, headers), 'Origin')
+    }
+    const response = await next()
+    return appendVary(setHeaders(response, shared), 'Origin')
+  }
+}

package/plugins/acryl-router/src/middleware/index.ts

@@ -0,0 +1,6 @@
+export { bodyLimit, BODY_LIMIT_KEY, type BodyLimitOptions } from './body-limit.ts'
+export { cors, type CorsOptions } from './cors.ts'
+export { logger, type LogSink } from './logger.ts'
+export { loopbackAuthority, loopbackOnly, sameOrigin, type LoopbackOptions } from './loopback-only.ts'
+export { requestId, type RequestIdOptions } from './request-id.ts'
+export { secureHeaders, type SecureHeadersOptions } from './secure-headers.ts'

package/plugins/acryl-router/src/middleware/logger.ts

@@ -0,0 +1,21 @@
+import type { Middleware } from '../types.ts'
+
+/** One line to a sink the caller owns, for example `line => ctx.logger.info(line)`. */
+export type LogSink = (line: string) => void
+
+/** Log each request on the way in and its status and time on the way out. The sink is required: a framework does not write to the console on its own. */
+export function logger(sink: LogSink): Middleware {
+  return async (c, next) => {
+    const label = `${c.req.method} ${c.url.pathname}`
+    sink(`<-- ${label}`)
+    const started = performance.now()
+    try {
+      const response = await next()
+      sink(`--> ${label} ${String(response.status)} ${String(Math.round(performance.now() - started))}ms`)
+      return response
+    } catch (error) {
+      sink(`--> ${label} threw ${error instanceof Error ? error.message : String(error)} ${String(Math.round(performance.now() - started))}ms`)
+      throw error
+    }
+  }
+}

package/plugins/acryl-router/src/middleware/loopback-only.ts

@@ -0,0 +1,82 @@
+import { BlockList, isIP } from 'node:net'
+import type { Middleware, RouteContext } from '../types.ts'
+
+export interface LoopbackOptions {
+  /** Hostnames a `Host` header may name. Default: the loopback names `127.0.0.1`, `localhost` and `[::1]`. */
+  readonly hostnames?: readonly string[]
+  /**
+   * What a request that changes things (not GET, HEAD or OPTIONS) must show: `same-origin` (default) refuses an `Origin` header that is not this same
+   * authority (including `null`), which stops another web page from driving a local app. A browser always sends `Origin` on a cross-origin change, so a
+   * request with no `Origin` (curl, a script) is allowed: the `Host` it names is already checked to be a loopback address with this server's port, which
+   * is what stops DNS rebinding. `none` checks only the peer and the `Host`.
+   */
+  readonly mutations?: 'same-origin' | 'none'
+  /**
+   * A call made inside the process (the terminal UI, a test) has no socket, so no peer to check. `deny` (default) refuses it, the safe choice for a route
+   * that guards something; `allow` lets it through for routes whose in-process caller is the host's own code. A request that came over a socket is always
+   * checked in full: only a call with no connection facts at all counts as in process.
+   */
+  readonly inProcess?: 'deny' | 'allow'
+}
+
+const loopback = new BlockList()
+loopback.addSubnet('127.0.0.0', 8, 'ipv4')
+loopback.addSubnet('::1', 128, 'ipv6')
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * The authority a loopback request addressed: the `Host` header as a URL, or `undefined` when the request does not come from a loopback peer to the
+ * real local port, names another host, or is marked cross-site by the browser. The peer and the port come from the transport (`c.connection`), never
+ * from a header; an in-process call has neither and is refused.
+ */
+export const LOOPBACK_HOSTNAMES: readonly string[] = ['127.0.0.1', 'localhost', '[::1]']
+
+export function loopbackAuthority(c: RouteContext, hostnames: readonly string[] = LOOPBACK_HOSTNAMES): URL | undefined {
+  const { remoteAddress, localPort } = c.connection
+  const host = c.req.headers.get('host')
+  if (remoteAddress === undefined || localPort === undefined || host === null) return undefined
+  const address = (remoteAddress.replace(/^\[|\]$/gu, '').split('%', 1)[0] ?? '').replace(/^::ffff:/iu, '')
+  const family = isIP(address)
+  if (family === 0 || !loopback.check(address, family === 4 ? 'ipv4' : 'ipv6')) return undefined
+  let authority: URL
+  try {
+    authority = new URL(`http://${host}`)
+  } catch {
+    return undefined
+  }
+  if (
+    authority.protocol !== 'http:'
+    || Number(authority.port || '80') !== localPort
+    || !hostnames.includes(authority.hostname)
+    || c.req.headers.get('sec-fetch-site') === 'cross-site'
+  ) return undefined
+  return authority
+}
+
+/** Whether a changing request is acceptable by its `Origin`: absent (not a browser cross-origin change) or naming this same authority. `null` and any other origin are not. */
+export function sameOrigin(c: RouteContext, authority: URL): boolean {
+  const origin = c.req.headers.get('origin')
+  if (origin === null) return true
+  try {
+    const parsed = new URL(origin)
+    return parsed.protocol === 'http:' && parsed.host === authority.host && parsed.pathname === '/'
+  } catch {
+    return false
+  }
+}
+
+/** Only requests from this machine to this app: loopback peer, the real port, an allowed `Host`, and for mutations a matching `Origin`. Everything else gets a 403. */
+export function loopbackOnly(options: LoopbackOptions = {}): Middleware {
+  const mutations = options.mutations ?? 'same-origin'
+  const inProcess = options.inProcess ?? 'deny'
+  return async (c, next) => {
+    if (inProcess === 'allow' && c.connection.remoteAddress === undefined && c.connection.localPort === undefined) return next()
+    const authority = loopbackAuthority(c, options.hostnames)
+    if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+    if (mutations === 'same-origin' && !SAFE_METHODS.has(c.req.method) && !sameOrigin(c, authority)) {
+      return c.json({ error: 'a change must come from this app\'s own origin' }, 403)
+    }
+    return next()
+  }
+}

package/plugins/acryl-router/src/middleware/request-id.ts

@@ -0,0 +1,24 @@
+import { randomUUID } from 'node:crypto'
+import type { Middleware } from '../types.ts'
+import { setHeaders } from '../util.ts'
+
+export interface RequestIdOptions {
+  /** The header read from the request and written to the response. */
+  readonly header?: string
+  /** Makes an id when the request brought none. */
+  readonly generate?: () => string
+}
+
+const SAFE_ID = /^[\w\-=]{1,255}$/u
+
+/** Give every request an id: the caller's, when it is well formed, otherwise a new one. It is `c.get('requestId')` and the response header. */
+export function requestId(options: RequestIdOptions = {}): Middleware {
+  const header = options.header ?? 'x-request-id'
+  const generate = options.generate ?? randomUUID
+  return async (c, next) => {
+    const incoming = c.req.headers.get(header)
+    const id = incoming !== null && SAFE_ID.test(incoming) ? incoming : generate()
+    c.set('requestId', id)
+    return setHeaders(await next(), { [header]: id })
+  }
+}

package/plugins/acryl-router/src/middleware/secure-headers.ts

@@ -0,0 +1,23 @@
+import type { Middleware } from '../types.ts'
+import { setHeaders } from '../util.ts'
+
+export interface SecureHeadersOptions {
+  /** Extra or replacement headers, merged over the defaults. A value of `''` removes a default. */
+  readonly headers?: Readonly<Record<string, string>>
+}
+
+const DEFAULTS: Record<string, string> = {
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': 'SAMEORIGIN',
+  'referrer-policy': 'no-referrer',
+  'cross-origin-resource-policy': 'same-origin',
+}
+
+/** Add the standard hardening headers to every response (never overriding one the handler already set). */
+export function secureHeaders(options: SecureHeadersOptions = {}): Middleware {
+  const wanted = Object.entries({ ...DEFAULTS, ...options.headers }).filter(([, value]) => value !== '')
+  return async (_c, next) => {
+    const response = await next()
+    return setHeaders(response, Object.fromEntries(wanted.filter(([name]) => !response.headers.has(name))))
+  }
+}

package/plugins/acryl-router/src/pattern.ts

@@ -0,0 +1,89 @@
+import type { TrailingSlash } from './types.ts'
+
+/** One piece of a route path. */
+export type Segment =
+  | { readonly kind: 'static', readonly value: string }
+  | { readonly kind: 'param', readonly name: string }
+  | { readonly kind: 'wildcard' }
+
+export interface Pattern {
+  /** The path as written (normalized for the trailing-slash rule). */
+  readonly source: string
+  readonly segments: readonly Segment[]
+}
+
+/** Split a pathname into segments. `/` is the empty list; under `strict` a trailing slash leaves a final empty segment. */
+export function splitPath(path: string, trailingSlash: TrailingSlash): string[] {
+  let value = path
+  if (trailingSlash === 'ignore' && value.length > 1 && value.endsWith('/')) value = value.slice(0, -1)
+  if (value === '/' || value === '') return []
+  return value.slice(1).split('/')
+}
+
+/** Compile `/a/:id/*`. A `*` is allowed only as the last segment; param names must be non-empty and unique. */
+export function compilePattern(path: string, trailingSlash: TrailingSlash): Pattern {
+  if (!path.startsWith('/')) throw new TypeError(`router: path "${path}" must start with "/"`)
+  const parts = splitPath(path, trailingSlash)
+  const names = new Set<string>()
+  const segments: Segment[] = parts.map((part, index) => {
+    if (part === '*') {
+      if (index !== parts.length - 1) throw new TypeError(`router: "*" must be the last segment in "${path}"`)
+      return { kind: 'wildcard' }
+    }
+    if (part.startsWith(':')) {
+      const name = part.slice(1)
+      if (name === '') throw new TypeError(`router: empty parameter name in "${path}"`)
+      if (names.has(name)) throw new TypeError(`router: duplicate parameter ":${name}" in "${path}"`)
+      names.add(name)
+      return { kind: 'param', name }
+    }
+    return { kind: 'static', value: part }
+  })
+  return { source: path, segments }
+}
+
+/** The same path with every parameter name erased, so `/a/:id` and `/a/:name` collide as duplicates. */
+export function shapeOf(pattern: Pattern): string {
+  return '/' + pattern.segments.map(s => s.kind === 'static' ? s.value : s.kind === 'param' ? ':' : '*').join('/')
+}
+
+function decode(value: string): string {
+  try { return decodeURIComponent(value) } catch { return value }
+}
+
+/** Match concrete path segments against a pattern; returns the parameters, or `undefined` when it does not match. */
+export function matchPattern(pattern: Pattern, parts: readonly string[]): Record<string, string> | undefined {
+  const params: Record<string, string> = {}
+  const { segments } = pattern
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    if (segment === undefined) return undefined
+    if (segment.kind === 'wildcard') {
+      params['*'] = parts.slice(i).map(decode).join('/')
+      return params
+    }
+    const part = parts[i]
+    if (part === undefined) return undefined
+    if (segment.kind === 'static') {
+      if (segment.value !== part) return undefined
+    } else {
+      params[segment.name] = decode(part)
+    }
+  }
+  return parts.length === segments.length ? params : undefined
+}
+
+const SCORE = { static: 3, param: 2, wildcard: 1 } as const
+
+/** Compare two matching patterns: the more specific one (static before param before wildcard, left to right) wins. */
+export function compareSpecificity(a: Pattern, b: Pattern): number {
+  const length = Math.max(a.segments.length, b.segments.length)
+  for (let i = 0; i < length; i++) {
+    const left = a.segments[i]
+    const right = b.segments[i]
+    const l = left === undefined ? 0 : SCORE[left.kind]
+    const r = right === undefined ? 0 : SCORE[right.kind]
+    if (l !== r) return l - r
+  }
+  return 0
+}

package/plugins/acryl-router/src/registrar.ts

@@ -0,0 +1,90 @@
+/**
+ * The registration API every router scope shares (`get`, `use`, `group`): the router itself is one scope with an empty prefix, and
+ * `router.group('/api')` is another with a prefix. A scope never owns anything; every registration is released by the plugin that made it.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { compose } from './compose.ts'
+import type { Handler, Method, Middleware, RouteMethod } from './types.ts'
+
+/** The last argument is the handler; everything before it is middleware that runs for this route only. */
+export type RouteHandlers = readonly [...Middleware[], Handler]
+
+export type UseArguments = readonly [Middleware, ...Middleware[]] | readonly [string, Middleware, ...Middleware[]]
+
+export interface Registrar {
+  /** Register a route owned by the calling plugin. Returns a remover; the route also goes away when the caller unloads. */
+  route(method: RouteMethod, path: string, ...handlers: RouteHandlers): () => void
+  get(path: string, ...handlers: RouteHandlers): () => void
+  post(path: string, ...handlers: RouteHandlers): () => void
+  put(path: string, ...handlers: RouteHandlers): () => void
+  patch(path: string, ...handlers: RouteHandlers): () => void
+  delete(path: string, ...handlers: RouteHandlers): () => void
+  /** A route that answers every method no more specific route claims. */
+  all(path: string, ...handlers: RouteHandlers): () => void
+  /** The same handlers on several methods. Returns one remover for all of them. */
+  on(methods: Method | readonly Method[], path: string, ...handlers: RouteHandlers): () => void
+  /** Middleware for a path and everything below it (default: everything in this scope), in registration order. */
+  use(...args: UseArguments): () => void
+  /** A scope whose paths all start with `prefix`; optional middleware runs for everything under it. */
+  group(prefix: string, ...middleware: Middleware[]): Registrar
+}
+
+/** What a scope needs from the router: put one route or one middleware into the table, owned by `owner`. */
+export interface Primitives {
+  add(owner: Context, method: RouteMethod, path: string, handler: Handler): () => void
+  use(owner: Context, path: string, middleware: Middleware): () => void
+}
+
+const PREFIX = /^\/(?:[^/*:\s]+(?:\/[^/*:\s]+)*)?$/
+
+/** Join a scope prefix and a path: `('/api', '/x')` is `/api/x`, `('/api', '/')` is `/api`, and an empty prefix leaves the path alone. */
+export function joinPath(prefix: string, path: string): string {
+  if (prefix === '') return path
+  if (path === '/' || path === '') return prefix
+  if (!path.startsWith('/')) throw new TypeError(`router: path "${path}" must start with "/"`)
+  return `${prefix}${path}`
+}
+
+function validatePrefix(prefix: string): void {
+  if (prefix !== '' && !PREFIX.test(prefix)) throw new TypeError(`router: group prefix "${prefix}" must be a plain path like "/api" (no wildcard, no parameter, no trailing slash)`)
+}
+
+function single(handlers: RouteHandlers): Handler {
+  const last = handlers.at(-1)
+  if (last === undefined) throw new TypeError('router: a route needs a handler')
+  const middleware = handlers.slice(0, -1) as Middleware[]
+  return middleware.length === 0 ? last as Handler : compose(middleware, last as Handler)
+}
+
+export function createRegistrar(owner: Context, prefix: string, primitives: Primitives): Registrar {
+  validatePrefix(prefix)
+  const route = (method: RouteMethod, path: string, ...handlers: RouteHandlers): (() => void) =>
+    primitives.add(owner, method, joinPath(prefix, path), single(handlers))
+  const registrar: Registrar = {
+    route,
+    get: (path, ...h) => route('GET', path, ...h),
+    post: (path, ...h) => route('POST', path, ...h),
+    put: (path, ...h) => route('PUT', path, ...h),
+    patch: (path, ...h) => route('PATCH', path, ...h),
+    delete: (path, ...h) => route('DELETE', path, ...h),
+    all: (path, ...h) => route('*', path, ...h),
+    on: (methods, path, ...h) => {
+      const removers = (Array.isArray(methods) ? methods as readonly Method[] : [methods as Method]).map(method => route(method, path, ...h))
+      return () => { for (const remove of removers) remove() }
+    },
+    use: (...args) => {
+      const [first, ...rest] = args as readonly [string | Middleware, ...Middleware[]]
+      const path = typeof first === 'string' ? first : '/'
+      const middleware = typeof first === 'string' ? rest : [first, ...rest]
+      const removers = middleware.map(mw => primitives.use(owner, joinPath(prefix, path), mw))
+      return () => { for (const remove of removers) remove() }
+    },
+    group: (nested, ...middleware) => {
+      const scope = createRegistrar(owner, joinPath(prefix, nested), primitives)
+      if (middleware.length > 0) scope.use(...(middleware as [Middleware, ...Middleware[]]))
+      return scope
+    },
+  }
+  return registrar
+}