acrylblends 0.0.0-stage → 0.3.0

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
+}

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

@@ -0,0 +1,164 @@
+/**
+ * The ACRYL router service (`ctx.router`): plugin-owned routes and middleware on Web-standard Request and Response.
+ *
+ * A route is registered from the owning plugin's context, so it disappears when that plugin unloads. `fetch(request)`
+ * runs a request in process: Web serves it behind HTTP (see spec 046, milestone M2), Desktop and the terminal UI call it
+ * directly, so one handler serves every surface without opening a socket. Disposal aborts in-flight requests through their
+ * `signal` and waits for them to settle.
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { createRegistrar, type Primitives, type Registrar, type RouteHandlers, type UseArguments } from './registrar.ts'
+import { RouteTable } from './table.ts'
+import type { ConnectionInfo, ErrorHandler, Method, Middleware, NotFoundHandler, RouteMethod, TrailingSlash } from './types.ts'
+
+const DEFAULT_DISPOSE_GRACE_MS = 2000
+
+/** Validated plugin configuration. */
+export interface Config {
+  trailingSlash: TrailingSlash
+  disposeGraceMs: number
+}
+
+export const Config: z<Config> = z.object({
+  trailingSlash: z.union(['strict', 'ignore']).default('strict').description('Whether `/a` and `/a/` are different paths.'),
+  disposeGraceMs: z.number().min(0).default(DEFAULT_DISPOSE_GRACE_MS).description('How long disposal waits for aborted requests (and their waitUntil tasks) to finish before it gives up on them.'),
+})
+
+/**
+ * The Web adapter's service (`ctx.routerHttp`, provided by `acryl-router-http`). Declared here, beside `router`, so a plugin can ask for its routes to be
+ * served over HTTP without depending on the adapter package.
+ */
+export interface RouterHttpService {
+  /** Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads. */
+  mount(prefix: string): () => void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    router: Router
+    routerHttp: RouterHttpService
+  }
+}
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-router'
+
+interface Flight {
+  readonly controller: AbortController
+  /** Settles when the handler is done and every `waitUntil` task it registered has settled. */
+  readonly settled: Promise<unknown>
+}
+
+export class Router extends Service {
+  private readonly table: RouteTable
+  private readonly flights = new Set<Flight>()
+  private closing = false
+  private readonly graceMs: number
+
+  constructor(ctx: Context, config: Partial<Config> = {}) {
+    super(ctx, 'router')
+    // The schema supplies these defaults when the Loader mounts the package; a plugin object mounted by hand skips the schema.
+    const { trailingSlash = 'strict', disposeGraceMs = DEFAULT_DISPOSE_GRACE_MS } = config
+    this.graceMs = disposeGraceMs
+    this.table = new RouteTable({
+      trailingSlash,
+      onError: error => ctx.logger.error(`acryl-router: handler failed: ${error instanceof Error ? error.message : String(error)}`),
+    })
+    ctx.effect(() => async () => {
+      this.closing = true
+      const open = [...this.flights]
+      for (const flight of open) flight.controller.abort()
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const gaveUp = new Promise<'gave-up'>(resolve => { timer = setTimeout(() => { resolve('gave-up') }, this.graceMs) })
+      const outcome = await Promise.race([Promise.allSettled(open.map(flight => flight.settled)).then(() => 'settled' as const), gaveUp])
+      clearTimeout(timer)
+      if (outcome === 'gave-up') ctx.logger.warn(`acryl-router: ${String(this.flights.size)} request(s) did not finish ${String(this.graceMs)} ms after abort; disposal continued without them`)
+    }, 'acryl-router: abort and settle in-flight requests')
+  }
+
+  /** Routes plus middleware currently registered; a leak check for reload tests. */
+  get size(): number {
+    return this.table.size
+  }
+
+  private readonly primitives: Primitives = {
+    add: (owner, method, path, handler) => {
+      const remove = this.table.add(method, path, handler)
+      owner.effect(() => () => { remove() }, `acryl-router: ${method} ${path}`)
+      return remove
+    },
+    use: (owner, path, middleware) => {
+      const remove = this.table.use(path, middleware)
+      owner.effect(() => () => { remove() }, `acryl-router: use ${path}`)
+      return remove
+    },
+  }
+
+  /** The scope the calling plugin registers into; `this.ctx` is the caller's context for the duration of a call made through `ctx.router`. */
+  private scope(): Registrar {
+    return createRegistrar(this.ctx, '', this.primitives)
+  }
+
+  route(method: RouteMethod, path: string, ...handlers: RouteHandlers): () => void { return this.scope().route(method, path, ...handlers) }
+  get(path: string, ...handlers: RouteHandlers): () => void { return this.scope().get(path, ...handlers) }
+  post(path: string, ...handlers: RouteHandlers): () => void { return this.scope().post(path, ...handlers) }
+  put(path: string, ...handlers: RouteHandlers): () => void { return this.scope().put(path, ...handlers) }
+  patch(path: string, ...handlers: RouteHandlers): () => void { return this.scope().patch(path, ...handlers) }
+  delete(path: string, ...handlers: RouteHandlers): () => void { return this.scope().delete(path, ...handlers) }
+  all(path: string, ...handlers: RouteHandlers): () => void { return this.scope().all(path, ...handlers) }
+  on(methods: Method | readonly Method[], path: string, ...handlers: RouteHandlers): () => void { return this.scope().on(methods, path, ...handlers) }
+  use(...args: UseArguments): () => void { return this.scope().use(...args) }
+  group(prefix: string, ...middleware: Middleware[]): Registrar { return this.scope().group(prefix, ...middleware) }
+
+  /** Turn errors into responses. One handler per router; the calling plugin owns it. */
+  onError(handler: ErrorHandler): () => void {
+    const remove = this.table.setErrorHandler(handler)
+    this.ctx.effect(() => () => { remove() }, 'acryl-router: onError')
+    return remove
+  }
+
+  /** Answer requests no route claimed. One handler per router; the calling plugin owns it. */
+  notFound(handler: NotFoundHandler): () => void {
+    const remove = this.table.setNotFoundHandler(handler)
+    this.ctx.effect(() => () => { remove() }, 'acryl-router: notFound')
+    return remove
+  }
+
+  /**
+   * Call the router the way a test calls an app: a path or URL string, a `URL` or a `Request`, with the usual init.
+   * A relative path is resolved against `http://localhost`.
+   */
+  request(input: string | URL | Request, init?: RequestInit, connection?: ConnectionInfo): Promise<Response> {
+    const request = input instanceof Request ? input : new Request(new URL(String(input), 'http://localhost'), init)
+    return this.fetch(request, connection)
+  }
+
+  /**
+   * Run a request in process. Never throws: failures become a 500, a disposed router answers 503. `connection` describes
+   * the transport (an HTTP adapter passes the socket's peer address); an in-process caller omits it.
+   */
+  fetch(request: Request, connection: ConnectionInfo = {}): Promise<Response> {
+    if (this.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
+    const controller = new AbortController()
+    const forward = (): void => controller.abort()
+    if (request.signal.aborted) controller.abort()
+    else request.signal.addEventListener('abort', forward, { once: true })
+    const tasks: Promise<unknown>[] = []
+    // The caller gets the Response the moment the handler returns it; the flight lasts until every waitUntil task settles.
+    const response = this.table.dispatch(request, controller.signal, connection, task => { tasks.push(task) })
+    const settled = response.then(() => Promise.allSettled(tasks))
+    const flight: Flight = { controller, settled }
+    this.flights.add(flight)
+    void settled.finally(() => {
+      request.signal.removeEventListener('abort', forward)
+      this.flights.delete(flight)
+    })
+    return response
+  }
+}
+
+export function apply(ctx: Context, config: Partial<Config> = {}): void {
+  new Router(ctx, config)
+}

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

@@ -0,0 +1,156 @@
+import { compose } from './compose.ts'
+import { createContext } from './context.ts'
+import { compareSpecificity, compilePattern, matchPattern, shapeOf, splitPath, type Pattern } from './pattern.ts'
+import { HttpError } from './http-error.ts'
+import type { ConnectionInfo, ErrorHandler, Handler, Middleware, NotFoundHandler, RouteContext, RouteMethod, TrailingSlash } from './types.ts'
+
+interface RouteEntry {
+  readonly method: RouteMethod
+  readonly pattern: Pattern
+  readonly handler: Handler
+}
+
+interface MiddlewareEntry {
+  readonly pattern: Pattern
+  readonly middleware: Middleware
+}
+
+export interface RouteTableOptions {
+  readonly trailingSlash: TrailingSlash
+  /** Called with anything a handler or middleware throws; the caller still receives a 500. */
+  readonly onError?: (error: unknown) => void
+}
+
+/**
+ * The routing core: pure data and matching, no Cordis. Registrations return an idempotent remover, and the table keeps
+ * insertion order so middleware runs in registration order. Matching picks the most specific route (static before
+ * parameter before wildcard) among those that answer the request method.
+ */
+export class RouteTable {
+  private readonly routes = new Map<string, RouteEntry>()
+  private readonly middleware = new Map<symbol, MiddlewareEntry>()
+  private errorHandler: ErrorHandler | undefined
+  private notFoundHandler: NotFoundHandler | undefined
+
+  private readonly options: RouteTableOptions
+
+  constructor(options: RouteTableOptions) {
+    this.options = options
+  }
+
+  /** Routes plus middleware currently registered. A reload that leaks registrations makes this grow. */
+  get size(): number {
+    return this.routes.size + this.middleware.size
+  }
+
+  add(method: RouteMethod, path: string, handler: Handler): () => void {
+    const pattern = compilePattern(path, this.options.trailingSlash)
+    const key = `${method} ${shapeOf(pattern)}`
+    if (this.routes.has(key)) throw new Error(`router: duplicate route ${method} ${path}`)
+    const entry: RouteEntry = { method, pattern, handler }
+    this.routes.set(key, entry)
+    return () => {
+      if (this.routes.get(key) === entry) this.routes.delete(key)
+    }
+  }
+
+  /** Register middleware for `path` and everything below it (`/` means every request). */
+  use(path: string, middleware: Middleware): () => void {
+    const compiled = compilePattern(path, this.options.trailingSlash)
+    const last = compiled.segments.at(-1)
+    const pattern: Pattern = last?.kind === 'wildcard'
+      ? compiled
+      : { source: compiled.source, segments: [...compiled.segments, { kind: 'wildcard' }] }
+    const id = Symbol(path)
+    this.middleware.set(id, { pattern, middleware })
+    return () => { this.middleware.delete(id) }
+  }
+
+  /** Register the one handler that turns errors into responses. A second registration throws: the app has one voice for its errors. */
+  setErrorHandler(handler: ErrorHandler): () => void {
+    if (this.errorHandler !== undefined) throw new Error('router: an error handler is already registered')
+    this.errorHandler = handler
+    return () => { if (this.errorHandler === handler) this.errorHandler = undefined }
+  }
+
+  /** Register the one handler that answers requests no route claimed. A second registration throws. */
+  setNotFoundHandler(handler: NotFoundHandler): () => void {
+    if (this.notFoundHandler !== undefined) throw new Error('router: a not-found handler is already registered')
+    this.notFoundHandler = handler
+    return () => { if (this.notFoundHandler === handler) this.notFoundHandler = undefined }
+  }
+
+  private readonly notFoundResponse = (c: RouteContext): Response | Promise<Response> =>
+    this.notFoundHandler === undefined ? new Response('Not Found', { status: 404 }) : this.notFoundHandler(c)
+
+  private async errorResponse(error: unknown, context: RouteContext): Promise<Response> {
+    if (this.errorHandler !== undefined) {
+      try {
+        return await this.errorHandler(error, context)
+      } catch (inner) {
+        this.options.onError?.(inner)
+        return new Response('Internal Server Error', { status: 500 })
+      }
+    }
+    if (error instanceof HttpError) return error.getResponse()
+    this.options.onError?.(error)
+    return new Response('Internal Server Error', { status: 500 })
+  }
+
+  private hasMethod(method: RouteMethod, parts: readonly string[]): boolean {
+    for (const entry of this.routes.values()) {
+      if (entry.method === method && matchPattern(entry.pattern, parts) !== undefined) return true
+    }
+    return false
+  }
+
+  async dispatch(
+    req: Request,
+    signal: AbortSignal,
+    connection: ConnectionInfo = {},
+    track: (task: Promise<unknown>) => void = () => undefined,
+  ): Promise<Response> {
+    const parts = splitPath(new URL(req.url).pathname, this.options.trailingSlash)
+    const method = req.method.toUpperCase()
+
+    let best: { entry: RouteEntry, params: Record<string, string> } | undefined
+    const allowed = new Set<string>()
+    // HEAD is answered by the GET route when no route claims HEAD itself, and the body is dropped below.
+    const headFromGet = method === 'HEAD' && !this.hasMethod('HEAD', parts)
+    for (const entry of this.routes.values()) {
+      const params = matchPattern(entry.pattern, parts)
+      if (params === undefined) continue
+      allowed.add(entry.method)
+      if (entry.method === 'GET') allowed.add('HEAD')
+      const answers = entry.method === '*' || entry.method === method || (headFromGet && entry.method === 'GET')
+      if (!answers) continue
+      if (best === undefined || isBetter(entry, best.entry)) best = { entry, params }
+    }
+
+    const chain: Middleware[] = []
+    for (const entry of this.middleware.values()) {
+      if (matchPattern(entry.pattern, parts) !== undefined) chain.push(entry.middleware)
+    }
+
+    const final: Handler = best !== undefined
+      ? best.entry.handler
+      : allowed.size > 0 && !allowed.has('*')
+        ? () => new Response('Method Not Allowed', { status: 405, headers: { allow: [...allowed].sort().join(', ') } })
+        : this.notFoundResponse
+
+    const context = createContext(req, best?.params ?? {}, signal, connection, track, this.notFoundResponse)
+    try {
+      const response = await compose(chain, final)(context)
+      return method === 'HEAD' ? new Response(null, { status: response.status, statusText: response.statusText, headers: response.headers }) : response
+    } catch (error) {
+      if (signal.aborted) return new Response('Request aborted', { status: 499 })
+      return await this.errorResponse(error, context)
+    }
+  }
+}
+
+function isBetter(candidate: RouteEntry, current: RouteEntry): boolean {
+  const order = compareSpecificity(candidate.pattern, current.pattern)
+  if (order !== 0) return order > 0
+  return current.method === '*' && candidate.method !== '*'
+}

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

@@ -0,0 +1,73 @@
+/** What a `Response` can be constructed from: bytes, a string, a stream, or nothing. */
+export type ResponseBody = ConstructorParameters<typeof Response>[0]
+
+/** HTTP methods a route can answer; `*` answers any method not claimed by a more specific route. */
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'
+export type RouteMethod = Method | '*'
+
+/** How a trailing slash is read: `strict` keeps `/a` and `/a/` distinct, `ignore` treats them as one path. */
+export type TrailingSlash = 'strict' | 'ignore'
+
+/**
+ * Facts about the transport the request arrived on, supplied by the caller of `fetch` and never by the request itself.
+ * An in-process caller (the terminal UI) passes nothing, so a handler that needs a trusted peer must refuse it.
+ */
+export interface ConnectionInfo {
+  /** The peer address of the socket, when the request came over one (for example `127.0.0.1`). */
+  readonly remoteAddress?: string | undefined
+  /** The local port the socket is connected to, the real one a `Host` header should be checked against. */
+  readonly localPort?: number | undefined
+}
+
+/** What a handler or middleware sees. Deliberately small: the Web-standard request plus a few response helpers. */
+export interface RouteContext {
+  /** The incoming request. */
+  readonly req: Request
+  /** Parsed `req.url`. */
+  readonly url: URL
+  /** Matched `:name` segments, and `*` for the remainder of a wildcard route. Values are URL-decoded. */
+  readonly params: Readonly<Record<string, string>>
+  /** The transport the request arrived on; empty for an in-process call. */
+  readonly connection: ConnectionInfo
+  /** Aborted when the caller aborts the request or when the router is disposed. Handlers should honor it. */
+  readonly signal: AbortSignal
+  /** Request-scoped values shared between middleware and the handler. */
+  get<T>(key: string): T | undefined
+  set(key: string, value: unknown): void
+  /**
+   * Keep this request "in flight" until `task` settles, even after the handler returned its `Response`. A handler that
+   * streams (server-sent events) registers the promise that resolves when its stream ends; disposing the router aborts
+   * `signal` and waits for it, so a stream never outlives the plugin that served it.
+   */
+  waitUntil(task: Promise<unknown>): void
+  /**
+   * Set a header that the response helpers below (`json`, `text`, `html`, `body`, `redirect`, `notFound`) carry. A response built
+   * by hand with `new Response` is the handler's own and is left alone; middleware that must change any response reads it from `next()`.
+   */
+  header(name: string, value: string): void
+  /** The status the response helpers use when they are not given one. */
+  status(code: number): void
+  /** One query parameter, or all of them as an object (repeated names keep the first). */
+  query(): Record<string, string>
+  query(name: string): string | undefined
+  /** One route parameter, or all of them. Same values as `params`. */
+  param(): Readonly<Record<string, string>>
+  param(name: string): string | undefined
+  json(data: unknown, status?: number): Response
+  text(body: string, status?: number): Response
+  html(body: string, status?: number): Response
+  /** A response with a raw body (bytes, a string, a stream, or nothing) and optional extra headers. */
+  body(data: ResponseBody, status?: number, headers?: Record<string, string>): Response
+  redirect(location: string, status?: 301 | 302 | 303 | 307 | 308): Response
+  /** The router's not-found response (or the registered `notFound` handler's). */
+  notFound(): Response | Promise<Response>
+}
+
+export type Handler = (c: RouteContext) => Response | Promise<Response>
+export type Next = () => Promise<Response>
+export type Middleware = (c: RouteContext, next: Next) => Response | Promise<Response>
+
+/** Turns anything a handler or middleware threw into a response. Registered with `router.onError`. */
+export type ErrorHandler = (error: unknown, c: RouteContext) => Response | Promise<Response>
+/** Answers a request no route claimed. Registered with `router.notFound`. */
+export type NotFoundHandler = (c: RouteContext) => Response | Promise<Response>

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

@@ -0,0 +1,23 @@
+/** Small response utilities shared by the middleware. Not exported from the package. */
+
+/**
+ * Set headers on a response a handler already built. Responses made with `new Response` are mutable; ones from `fetch` or `Response.redirect` are
+ * not, so on a failed write the response is rebuilt around the same body.
+ */
+export function setHeaders(response: Response, headers: Record<string, string>): Response {
+  try {
+    for (const [name, value] of Object.entries(headers)) response.headers.set(name, value)
+    return response
+  } catch {
+    const merged = new Headers(response.headers)
+    for (const [name, value] of Object.entries(headers)) merged.set(name, value)
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers: merged })
+  }
+}
+
+export function appendVary(response: Response, value: string): Response {
+  const current = response.headers.get('vary')
+  const present = current?.split(',').map(part => part.trim().toLowerCase()) ?? []
+  if (present.includes('*') || present.includes(value.toLowerCase())) return response
+  return setHeaders(response, { vary: current === null || current === '' ? value : `${current}, ${value}` })
+}