acrylblends 0.2.0 → 0.3.0

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

package/plugins/acryl-router/tests/api.spec.ts

@@ -0,0 +1,223 @@
+/**
+ * The registration surface (spec 046): several handlers per route, `all` and `on`, optional-path `use`, `group`, `onError` and
+ * `notFound`, `HttpError`, `request()`, and the context helpers. Everything runs through the real Cordis service, so ownership is checked too.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, HttpError, name, type Router } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function mount(): Promise<{ ctx: Context, router: Router }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name, apply })
+  await settle()
+  return { ctx, router: ctx.router }
+}
+
+const text = async (response: Response | Promise<Response>): Promise<string> => (await response).text()
+
+describe('registration', () => {
+  it('runs route-level middleware before the handler, in order, for that route only', async () => {
+    const { router } = await mount()
+    const seen: string[] = []
+    router.get('/a', async (_c, next) => { seen.push('m1'); return next() }, async (_c, next) => { seen.push('m2'); return next() }, c => { seen.push('h'); return c.text('a') })
+    router.get('/b', c => c.text('b'))
+    expect(await text(router.request('/a'))).toBe('a')
+    expect(seen).toEqual(['m1', 'm2', 'h'])
+    seen.length = 0
+    await router.request('/b')
+    expect(seen).toEqual([])
+  })
+
+  it('answers any method with all(), and a chosen set with on()', async () => {
+    const { router } = await mount()
+    router.all('/any', c => c.text(c.req.method))
+    router.on(['GET', 'POST'], '/two', c => c.text(c.req.method))
+    expect(await text(router.request('/any', { method: 'PATCH' }))).toBe('PATCH')
+    expect(await text(router.request('/two', { method: 'POST' }))).toBe('POST')
+    expect((await router.request('/two', { method: 'DELETE' })).status).toBe(405)
+  })
+
+  it('removes every method of an on() registration with the one remover it returns', async () => {
+    const { router } = await mount()
+    const remove = router.on(['GET', 'POST'], '/two', c => c.text('x'))
+    const before = router.size
+    remove()
+    expect(before - router.size).toBe(2)
+  })
+
+  it('applies use() without a path to everything', async () => {
+    const { router } = await mount()
+    router.use(async (_c, next) => { const response = await next(); response.headers.set('x-seen', '1'); return response })
+    router.get('/x', c => c.text('x'))
+    expect((await router.request('/x')).headers.get('x-seen')).toBe('1')
+    expect((await router.request('/missing')).headers.get('x-seen')).toBe('1')
+  })
+})
+
+describe('group', () => {
+  it('prefixes paths, nests, and scopes group middleware to the prefix', async () => {
+    const { router } = await mount()
+    const seen: string[] = []
+    const api = router.group('/api', async (_c, next) => { seen.push('api'); return next() })
+    api.get('/', c => c.text('index'))
+    api.get('/items/:id', c => c.json({ id: c.param('id') }))
+    const admin = api.group('/admin')
+    admin.use(async (_c, next) => { seen.push('admin'); return next() })
+    admin.get('/stats', c => c.text('stats'))
+    router.get('/outside', c => c.text('outside'))
+
+    expect(await text(router.request('/api'))).toBe('index')
+    expect(await (await router.request('/api/items/7')).json()).toEqual({ id: '7' })
+    expect(await text(router.request('/api/admin/stats'))).toBe('stats')
+    expect(seen).toEqual(['api', 'api', 'api', 'admin'])
+    seen.length = 0
+    await router.request('/outside')
+    expect(seen).toEqual([])
+  })
+
+  it('belongs to the plugin that made it: its routes vanish when that plugin unloads', async () => {
+    const { ctx, router } = await mount()
+    const baseline = router.size
+    const fiber = ctx.plugin({
+      name: 'notes',
+      inject: ['router'],
+      apply(c: Context) {
+        const notes = c.router.group('/notes')
+        notes.get('/', x => x.text('list'))
+        notes.post('/', x => x.text('create', 201))
+      },
+    })
+    await settle()
+    expect(router.size - baseline).toBe(2)
+    expect(await text(router.request('/notes'))).toBe('list')
+    await fiber.dispose()
+    await settle()
+    expect(router.size).toBe(baseline)
+    expect((await router.request('/notes')).status).toBe(404)
+  })
+
+  it('rejects a prefix that is not a plain path', async () => {
+    const { router } = await mount()
+    expect(() => router.group('/api/')).toThrow(/plain path/)
+    expect(() => router.group('/a/:id')).toThrow(/plain path/)
+    expect(() => router.group('/a/*')).toThrow(/plain path/)
+    expect(() => router.group('api')).toThrow(/plain path/)
+  })
+})
+
+describe('errors and not found', () => {
+  it('turns a thrown HttpError into its response without logging an error', async () => {
+    const { router } = await mount()
+    router.get('/secret', () => { throw new HttpError(401, { message: 'Sign in first' }) })
+    router.get('/custom', () => { throw new HttpError(418, { response: new Response('teapot', { status: 418, headers: { 'x-brew': 'yes' } }) }) })
+    const denied = await router.request('/secret')
+    expect(denied.status).toBe(401)
+    expect(await denied.text()).toBe('Sign in first')
+    const teapot = await router.request('/custom')
+    expect(teapot.status).toBe(418)
+    expect(teapot.headers.get('x-brew')).toBe('yes')
+  })
+
+  it('lets one onError handler own every error, including HttpError, and removes it with its plugin', async () => {
+    const { ctx, router } = await mount()
+    const fiber = ctx.plugin({
+      name: 'errors',
+      inject: ['router'],
+      apply(c: Context) {
+        c.router.onError((error, x) => x.json({ message: error instanceof Error ? error.message : 'unknown' }, error instanceof HttpError ? error.status : 500))
+      },
+    })
+    await settle()
+    router.get('/boom', () => { throw new Error('boom') })
+    router.get('/http', () => { throw new HttpError(403, { message: 'nope' }) })
+    expect(await (await router.request('/boom')).json()).toEqual({ message: 'boom' })
+    const forbidden = await router.request('/http')
+    expect(forbidden.status).toBe(403)
+    expect(await forbidden.json()).toEqual({ message: 'nope' })
+    expect(() => router.onError(() => new Response('second'))).toThrow(/already registered/)
+    await fiber.dispose()
+    await settle()
+    expect((await router.request('/boom')).status).toBe(500)
+  })
+
+  it('answers 500 when the error handler itself throws', async () => {
+    const { router } = await mount()
+    router.onError(() => { throw new Error('handler broke') })
+    router.get('/boom', () => { throw new Error('boom') })
+    expect((await router.request('/boom')).status).toBe(500)
+  })
+
+  it('uses a registered notFound handler, also through c.notFound()', async () => {
+    const { router } = await mount()
+    router.notFound(c => c.json({ missing: c.url.pathname }, 404))
+    router.get('/maybe', c => c.req.headers.has('x-found') ? c.text('found') : c.notFound())
+    const missing = await router.request('/nowhere')
+    expect(missing.status).toBe(404)
+    expect(await missing.json()).toEqual({ missing: '/nowhere' })
+    expect((await router.request('/maybe')).status).toBe(404)
+    expect(await text(router.request('/maybe', { headers: { 'x-found': '1' } }))).toBe('found')
+    expect(() => router.notFound(() => new Response('second'))).toThrow(/already registered/)
+  })
+})
+
+describe('context helpers', () => {
+  it('carries header() and status() into the response helpers', async () => {
+    const { router } = await mount()
+    router.get('/h', c => { c.header('x-app', 'acryl'); c.status(202); return c.json({ ok: true }) })
+    const response = await router.request('/h')
+    expect(response.status).toBe(202)
+    expect(response.headers.get('x-app')).toBe('acryl')
+    expect(response.headers.get('content-type')).toContain('application/json')
+  })
+
+  it('builds html, raw bodies and redirects', async () => {
+    const { router } = await mount()
+    router.get('/html', c => c.html('<h1>hi</h1>'))
+    router.get('/raw', c => c.body(new Uint8Array([1, 2, 3]), 200, { 'content-type': 'application/octet-stream' }))
+    router.get('/go', c => c.redirect('/html', 301))
+    router.get('/empty', c => c.body(null, 204))
+    const html = await router.request('/html')
+    expect(html.headers.get('content-type')).toContain('text/html')
+    expect(await html.text()).toBe('<h1>hi</h1>')
+    expect([...new Uint8Array(await (await router.request('/raw')).arrayBuffer())]).toEqual([1, 2, 3])
+    const moved = await router.request('/go')
+    expect(moved.status).toBe(301)
+    expect(moved.headers.get('location')).toBe('/html')
+    expect((await router.request('/empty')).status).toBe(204)
+  })
+
+  it('reads query and path parameters one at a time or all at once', async () => {
+    const { router } = await mount()
+    router.get('/u/:name', c => c.json({ one: c.query('q'), all: c.query(), name: c.param('name'), params: c.param() }))
+    const body = await (await router.request('/u/zed?q=1&q=2&r=3')).json()
+    expect(body).toEqual({ one: '1', all: { q: '1', r: '3' }, name: 'zed', params: { name: 'zed' } })
+  })
+
+  it('shares values between middleware and handler with set() and get()', async () => {
+    const { router } = await mount()
+    router.use(async (c, next) => { c.set('user', 'ada'); return next() })
+    router.get('/me', c => c.text(c.get<string>('user') ?? '?'))
+    expect(await text(router.request('/me'))).toBe('ada')
+  })
+})
+
+describe('request()', () => {
+  it('accepts a relative path, a URL, and a Request, with init and connection info', async () => {
+    const { router } = await mount()
+    router.post('/echo', async c => c.json({ got: await c.req.text(), peer: c.connection.remoteAddress ?? null }))
+    const viaPath = await router.request('/echo', { method: 'POST', body: 'a' })
+    expect(await viaPath.json()).toEqual({ got: 'a', peer: null })
+    const viaUrl = await router.request(new URL('http://example.test/echo'), { method: 'POST', body: 'b' }, { remoteAddress: '127.0.0.1' })
+    expect(await viaUrl.json()).toEqual({ got: 'b', peer: '127.0.0.1' })
+    const viaRequest = await router.request(new Request('http://example.test/echo', { method: 'POST', body: 'c' }))
+    expect((await viaRequest.json() as { got: string }).got).toBe('c')
+  })
+})