acrylblends 0.3.0 → 0.4.0

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

@@ -1,29 +1,38 @@
 /**
- * The ACRYL router service (`ctx.router`): plugin-owned routes and middleware on Web-standard Request and Response.
+ * The ACRYL router service (`ctx.router`): plugin-owned `App` mounts 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.
+ * A plugin builds an ordinary `App` and mounts it with `ctx.router.route(path, app)` from its own context, so the mount disappears when that
+ * plugin unloads. `fetch(request)` runs a request in process: Web and Desktop serve it behind HTTP through an adapter, the terminal UI calls
+ * it directly, so one handler serves every surface without opening a socket. Disposal refuses new requests, aborts in-flight ones, ends any
+ * response body still streaming and waits for all of it 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'
+import type { ConnectionInfo, RouterBindings } from './connection.ts'
+import { App } from './core/app.ts'
+import type { ExecutionContext } from './core/context.ts'
+import { HTTPException } from './core/http-exception.ts'
+import { TrieRouter } from './core/router/trie-router/index.ts'
+import { COMPOSED_HANDLER } from './core/utils/constants.ts'
+import { mergePath } from './core/utils/url.ts'
+import type { ErrorHandler, H, NotFoundHandler } from './core/types.ts'
 
 const DEFAULT_DISPOSE_GRACE_MS = 2000
 
+/** How a trailing slash is read: `strict` keeps `/a` and `/a/` distinct, `ignore` treats them as one path. */
+export type TrailingSlash = 'strict' | 'ignore'
+
 /** Validated plugin configuration. */
 export interface Config {
   trailingSlash: TrailingSlash
   disposeGraceMs: number
 }
 
-export const Config: z<Config> = z.object({
+/** Every field has a default, so a caller passes only what it changes: `ctx.plugin(plugin, { ... })` takes the partial shape. */
+export const Config: z<Partial<Config>, 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.'),
+  disposeGraceMs: z.number().min(0).default(DEFAULT_DISPOSE_GRACE_MS).description('How long disposal waits for aborted requests, their response bodies and their waitUntil tasks before it gives up on them.'),
 })
 
 /**
@@ -45,84 +54,170 @@ declare module '@deepseek-ai/cordis' {
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-router'
 
+// Any `App`, whatever its Env and schema; the router only reads its routes.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type MountableApp = App<any, any, any>
+
+interface Mount {
+  readonly path: string
+  readonly app: MountableApp
+}
+
+interface RouterState {
+  readonly mounts: Set<Mount>
+  errorHandler: ErrorHandler | undefined
+  notFoundHandler: NotFoundHandler | undefined
+  /** The app composed from the live mounts; dropped on every change and composed again by the next request. */
+  composed: App | undefined
+  closing: boolean
+}
+
 interface Flight {
   readonly controller: AbortController
-  /** Settles when the handler is done and every `waitUntil` task it registered has settled. */
+  /** How many of each mount's handlers are running for this request right now (a middleware counts until its `next()` returns). */
+  readonly running: Map<Mount, number>
+  /** The mount whose handler produced the response; its body is that mount's code still running. */
+  producer: Mount | undefined
+  /** Ends the response body early (disposal); a no-op once the body is done or when there is none. */
+  readonly endBody: () => void
+  /** Settles when the handler is done, its body has been read or cancelled, and every `waitUntil` task it registered has settled. */
   readonly settled: Promise<unknown>
 }
 
+/** Wait for `tasks`, including any added while waiting (a stream may register more after the handler returned). */
+async function drain(tasks: readonly Promise<unknown>[]): Promise<void> {
+  let seen = 0
+  while (seen < tasks.length) {
+    const batch = tasks.slice(seen)
+    seen = tasks.length
+    await Promise.allSettled(batch)
+  }
+}
+
 export class Router extends Service {
-  private readonly table: RouteTable
+  /** Everything that changes after construction, kept in one object so the service's live state is in one place. */
+  private readonly state: RouterState = { mounts: new Set(), errorHandler: undefined, notFoundHandler: undefined, composed: undefined, closing: false }
   private readonly flights = new Set<Flight>()
-  private closing = false
+  /** The flight of each request the router dispatched, keyed by the request its handlers see as `c.req.raw`. */
+  private readonly flightOf = new WeakMap<Request, Flight>()
+  private readonly strict: boolean
   private readonly graceMs: number
+  private readonly logError: ErrorHandler
 
   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.strict = trailingSlash === 'strict'
     this.graceMs = disposeGraceMs
-    this.table = new RouteTable({
-      trailingSlash,
-      onError: error => ctx.logger.error(`acryl-router: handler failed: ${error instanceof Error ? error.message : String(error)}`),
-    })
+    this.logError = (error, c) => {
+      if (error instanceof HTTPException) return error.getResponse()
+      // A handler that gave up because its caller left or the router is closing is not a failure worth logging.
+      if (c.req.raw.signal.aborted) return new Response('Client Closed Request', { status: 499 })
+      ctx.logger.error(`acryl-router: handler failed: ${error instanceof Error ? error.message : String(error)}`)
+      return c.text('Internal Server Error', 500)
+    }
     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`)
+      this.state.closing = true
+      await this.end([...this.flights], 'disposal')
     }, 'acryl-router: abort and settle in-flight requests')
   }
 
-  /** Routes plus middleware currently registered; a leak check for reload tests. */
+  /** Registrations currently held (mounts, and the router-wide error and not-found handlers); a leak check for reload tests. */
   get size(): number {
-    return this.table.size
+    return this.state.mounts.size + (this.state.errorHandler === undefined ? 0 : 1) + (this.state.notFoundHandler === undefined ? 0 : 1)
   }
 
-  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
-    },
+  /**
+   * Serve `app` under `path` (`'/'` for its own paths as they are). The mount belongs to the calling plugin and goes away when it unloads;
+   * the returned function removes it sooner. Mounts are composed in the order they were made. Like the core's own `app.route`, the routes
+   * are copied now: one the app registers after this call is not served (mount again, or finish the app first).
+   */
+  route(path: string, app: MountableApp): () => void {
+    const mount = this.snapshot(path, app)
+    this.state.mounts.add(mount)
+    this.state.composed = undefined
+    // Removing a mount ends the requests its code is still serving: their signals abort, a body it produced is cancelled, and the
+    // plugin's unload waits for them (bounded by `disposeGraceMs`), so nothing a plugin started outlives it.
+    const remove = (): Promise<void> => {
+      if (!this.state.mounts.delete(mount)) return Promise.resolve()
+      this.state.composed = undefined
+      return this.end([...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`)
+    }
+    // The label lists what the mount serves, so the inspector can report routes without asking the router (`ALL` is middleware or `all`).
+    const served = app.routes.map(route => `${route.method} ${mergePath(path, route.path)}`).join(', ')
+    this.ctx.effect(() => remove, `acryl-router: route ${path} (${served})`)
+    return () => { void 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)
+  /**
+   * The mount's own copy of `app`'s routes as they are now (like the core's `app.route`), each handler wrapped so the router knows which
+   * mount's code a request is in. The core's `app.route` runs first so a sub-app's own `onError` still applies to its routes.
+   */
+  private snapshot(path: string, app: MountableApp): Mount {
+    const copy = new App().route('/', app)
+    const tagged = new App()
+    const mount: Mount = { path, app: tagged }
+    for (const route of copy.routes) {
+      const inner = route.handler
+      const handler: H = async (c, next) => {
+        const flight = this.flightOf.get(c.req.raw)
+        if (flight === undefined) return inner(c, next)
+        let calledNext = false
+        flight.running.set(mount, (flight.running.get(mount) ?? 0) + 1)
+        try {
+          const result = await inner(c, () => { calledNext = true; return next() })
+          if (!calledNext && result instanceof Response) flight.producer = mount
+          return result
+        } finally {
+          flight.running.set(mount, (flight.running.get(mount) ?? 1) - 1)
+        }
+      }
+      ;(handler as unknown as Record<string, unknown>)[COMPOSED_HANDLER] = inner
+      tagged.on(route.method, route.path, handler)
+    }
+    return mount
   }
 
-  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. */
+  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
+  private async end(flights: readonly Flight[], why: string): Promise<void> {
+    if (flights.length === 0) return
+    for (const flight of flights) {
+      flight.controller.abort()
+      flight.endBody()
+    }
+    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(flights.map(flight => flight.settled)).then(() => 'settled' as const), gaveUp])
+    clearTimeout(timer)
+    if (outcome === 'gave-up') this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(this.graceMs)} ms after abort (${why}); continued without them`)
+  }
+
+  /** Turn errors no mounted app handled 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')
+    if (this.state.errorHandler !== undefined) throw new Error('router: an error handler is already registered')
+    this.state.errorHandler = handler
+    this.state.composed = undefined
+    const remove = (): void => {
+      if (this.state.errorHandler !== handler) return
+      this.state.errorHandler = undefined
+      this.state.composed = undefined
+    }
+    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')
+    if (this.state.notFoundHandler !== undefined) throw new Error('router: a not-found handler is already registered')
+    this.state.notFoundHandler = handler
+    this.state.composed = undefined
+    const remove = (): void => {
+      if (this.state.notFoundHandler !== handler) return
+      this.state.notFoundHandler = undefined
+      this.state.composed = undefined
+    }
+    this.ctx.effect(() => remove, 'acryl-router: notFound')
     return remove
   }
 
@@ -136,20 +231,43 @@ export class Router extends Service {
   }
 
   /**
-   * 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.
+   * 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 and local port); an in-process caller omits it. Handlers read it with
+   * `connectionOf(c)`, abort with `c.req.raw.signal` and keep the request in flight with `c.executionCtx.waitUntil(task)`.
    */
   fetch(request: Request, connection: ConnectionInfo = {}): Promise<Response> {
-    if (this.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
+    if (this.state.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 }
+    const executionCtx: ExecutionContext = {
+      waitUntil: task => { tasks.push(task) },
+      passThroughOnException: () => {},
+      props: {},
+    }
+    const env: RouterBindings = { connection }
+    let bodyDone: Promise<void> = Promise.resolve()
+    let endBody = (): void => {}
+    let resolveSettled!: (value: Promise<unknown>) => void
+    const flight: Flight = { controller, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    const inner = new Request(request, { signal: controller.signal })
+    this.flightOf.set(inner, flight)
+    // The caller gets the Response the moment the handler returns it; the flight lasts until its body ends and every waitUntil task settles.
+    const response = this.dispatch(inner, env, executionCtx).then(raw => {
+      const tracked = this.track(raw)
+      bodyDone = tracked.done
+      endBody = tracked.end
+      // Aborted before the handler answered (disposal, or the caller left): nobody is going to read this body, so end it now.
+      if (controller.signal.aborted) tracked.end()
+      return tracked.response
+    })
+    const settled = response.then(async () => {
+      await bodyDone
+      await drain(tasks)
+    })
+    resolveSettled(settled)
     this.flights.add(flight)
     void settled.finally(() => {
       request.signal.removeEventListener('abort', forward)
@@ -157,6 +275,80 @@ export class Router extends Service {
     })
     return response
   }
+
+  private async dispatch(request: Request, env: RouterBindings, executionCtx: ExecutionContext): Promise<Response> {
+    try {
+      return await this.app().fetch(request, env, executionCtx)
+    } catch (error) {
+      this.ctx.logger.error(`acryl-router: request failed: ${error instanceof Error ? error.message : String(error)}`)
+      return new Response('Internal Server Error', { status: 500 })
+    }
+  }
+
+  private app(): App {
+    if (this.state.composed !== undefined) return this.state.composed
+    // The trie router, because the composed app is rebuilt after every mount change: the default matcher compiles one regular expression
+    // over all routes on its first request, which grows faster than the route count (measured: 22 ms at 1000 routes, 163 ms at 2000),
+    // while the trie rebuilds in about 1 ms per 1000 routes and matches as fast (scripts/bench-remount.mjs).
+    const root = new App({ strict: this.strict, router: new TrieRouter() })
+    for (const mount of this.state.mounts) root.route(mount.path, mount.app)
+    root.onError(this.state.errorHandler ?? this.logError)
+    if (this.state.notFoundHandler !== undefined) root.notFound(this.state.notFoundHandler)
+    this.state.composed = root
+    return root
+  }
+
+  /**
+   * Hand the caller a body the router can end. Reading it passes the handler's chunks through; disposal cancels the handler's stream (which runs
+   * the stream helpers' own abort cleanup) and closes the caller's side, so a stream never outlives the plugin that served it.
+   */
+  private track(response: Response): { response: Response, done: Promise<void>, end: () => void } {
+    const source = response.body
+    if (source === null) return { response, done: Promise.resolve(), end: () => {} }
+    const reader = source.getReader()
+    let finish!: () => void
+    const done = new Promise<void>(resolve => { finish = resolve })
+    let ended = false
+    let sink: ReadableStreamDefaultController<Uint8Array> | undefined
+    const end = (): void => {
+      if (ended) return
+      ended = true
+      finish()
+    }
+    const endEarly = (): void => {
+      if (ended) return
+      reader.cancel(new Error('acryl-router: disposed')).catch(() => {})
+      try { sink?.close() } catch { /* already closed */ }
+      end()
+    }
+    const body = new ReadableStream<Uint8Array>({
+      start: controller => { sink = controller },
+      pull: async controller => {
+        try {
+          const chunk = await reader.read()
+          if (ended) return
+          if (chunk.done) {
+            controller.close()
+            end()
+          } else {
+            controller.enqueue(chunk.value)
+          }
+        } catch (error) {
+          if (!ended) controller.error(error)
+          end()
+        }
+      },
+      cancel: async reason => {
+        end()
+        await reader.cancel(reason)
+      },
+    })
+    return {
+      response: new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers }),
+      done,
+      end: endEarly,
+    }
+  }
 }
 
 export function apply(ctx: Context, config: Partial<Config> = {}): void {

package/plugins/acryl-router/tests/docs-examples.spec.ts

@@ -0,0 +1,152 @@
+/**
+ * The examples `docs/framework/` relies on, run as written: if one of these fails, the page that shows it is wrong.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createMiddleware, schemaValidator, testClient } from '../src/helpers/index.ts'
+import { App, HTTPException, apply, name } from '../src/index.ts'
+import { methodNotAllowed } from '../src/middleware/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 withPlugin(plugin: { name: string, inject: string[], apply(ctx: Context): void }): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name, apply })
+  ctx.plugin(plugin)
+  await settle()
+  return ctx
+}
+
+describe('getting-started.md', () => {
+  it('serves the minimal plugin as the route table says', async () => {
+    const ctx = await withPlugin({
+      name: 'todo',
+      inject: ['router'],
+      apply(inner) {
+        const app = new App()
+          .get('/', c => c.json({ ok: true }))
+          .get('/todos/:id', c => c.json({ id: c.req.param('id') }))
+        inner.router.route('/todo', app)
+        inner.inject(['routerHttp'], deeper => { deeper.routerHttp.mount('/todo') })
+      },
+    })
+    expect(await (await ctx.router.request('/todo')).json()).toEqual({ ok: true })
+    expect(await (await ctx.router.request('/todo/todos/42')).json()).toEqual({ id: '42' })
+    expect((await ctx.router.request('/todo/')).status).toBe(404)
+  })
+})
+
+describe('routing.md', () => {
+  it('serves the routes an app had at the mount, not ones added later', async () => {
+    const app = new App().get('/a', c => c.text('a'))
+    const ctx = await withPlugin({ name: 'late', inject: ['router'], apply(inner) { inner.router.route('/x', app) } })
+    app.get('/b', c => c.text('b'))
+    expect((await ctx.router.request('/x/a')).status).toBe(200)
+    expect((await ctx.router.request('/x/b')).status).toBe(404)
+  })
+
+  it('answers a wrong method with 404, or 405 and Allow with methodNotAllowed', async () => {
+    const plain = new App().get('/item', c => c.text('item'))
+    expect((await plain.request('/item', { method: 'POST' })).status).toBe(404)
+    const strict = new App()
+    strict.use(methodNotAllowed({ app: strict })).get('/item', c => c.text('item'))
+    const response = await strict.request('/item', { method: 'POST' })
+    expect(response.status).toBe(405)
+    expect(response.headers.get('allow')).toContain('GET')
+
+    const ctx = await withPlugin({ name: 'items', inject: ['router'], apply(inner) { inner.router.route('/shop', strict) } })
+    const mounted = await ctx.router.request('/shop/item', { method: 'POST' })
+    expect(mounted.status).toBe(405)
+    expect(mounted.headers.get('allow')).toContain('GET')
+    expect((await ctx.router.request('/shop/item')).status).toBe(200)
+  })
+
+  it('uses a mounted app\'s onError for its routes', async () => {
+    const app = new App().get('/boom', () => { throw new Error('boom') })
+    app.onError((_error, c) => c.json({ error: 'internal_error' }, 500))
+    const ctx = await withPlugin({ name: 'errors', inject: ['router'], apply(inner) { inner.router.route('/', app) } })
+    expect(await (await ctx.router.request('/boom')).json()).toEqual({ error: 'internal_error' })
+  })
+})
+
+describe('context.md and middleware.md', () => {
+  it('passes typed variables from middleware to the handler', async () => {
+    const withUser = createMiddleware<{ Variables: { user: { name: string } } }>(async (c, next) => {
+      c.set('user', { name: 'ada' })
+      await next()
+    })
+    const app = new App().use(withUser).get('/me', c => c.json(c.var.user))
+    expect(await (await app.request('/me')).json()).toEqual({ name: 'ada' })
+  })
+
+  it('never throws from next(): the error is already a response and is left in c.error', async () => {
+    let caught = false
+    let seen: unknown
+    const app = new App()
+      .use(async (c, next) => {
+        try {
+          await next()
+        } catch {
+          caught = true
+        }
+        seen = c.error
+      })
+      .get('/', () => { throw new Error('boom') })
+    expect((await app.request('/')).status).toBe(500)
+    expect(caught).toBe(false)
+    expect(seen).toBeInstanceOf(Error)
+  })
+
+  it('turns an HTTPException into its own response', async () => {
+    const app = new App().get('/', () => { throw new HTTPException(403, { message: 'not yours' }) })
+    const response = await app.request('/')
+    expect(response.status).toBe(403)
+    expect(await response.text()).toBe('not yours')
+  })
+})
+
+describe('validation.md', () => {
+  const NewTodo = z.object({
+    title: z.string().required(),
+    done: z.boolean().default(false),
+  })
+  const app = new App().post('/todos', schemaValidator('json', NewTodo), c => c.json({ todo: c.req.valid('json') }, 201))
+  const post = (body: string, type?: string): Promise<Response> =>
+    Promise.resolve(app.request('/todos', { method: 'POST', body, headers: type === undefined ? {} : { 'content-type': type } }))
+
+  it('hands the handler the schema output', async () => {
+    const response = await post('{"title":"hello"}', 'application/json')
+    expect(response.status).toBe(201)
+    expect(await response.json()).toEqual({ todo: { title: 'hello', done: false } })
+  })
+
+  it('answers 400 with the issues the page shows', async () => {
+    const response = await post('{"title":1}', 'application/json')
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({ error: 'invalid json', issues: [{ message: '$.title expected string but got 1', path: 'title' }] })
+  })
+
+  it('validates {} when the request is not JSON, so a required field fails', async () => {
+    expect((await post('{"title":"hello"}')).status).toBe(400)
+  })
+
+  it('answers 400 for a body that is not JSON', async () => {
+    expect((await post('{', 'application/json')).status).toBe(400)
+  })
+})
+
+describe('helpers.md', () => {
+  it('calls a chained app through the typed test client', async () => {
+    const app = new App().get('/search', c => c.json({ query: c.req.query('q') }))
+    const client = testClient(app)
+    const response = await client.search.$get({ query: { q: 'cordis' } })
+    expect(await response.json()).toEqual({ query: 'cordis' })
+  })
+})

package/plugins/acryl-router/tests/live-install.spec.ts

@@ -7,7 +7,7 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it } from 'vitest'
-import { apply, name } from '../src/index.ts'
+import { App, apply, name } from '../src/index.ts'
 
 const contexts: Context[] = []
 const settle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0))
@@ -46,7 +46,7 @@ const extension = (): object => ({
   name: 'live-ext',
   inject: ['router'],
   apply(ctx: Context): void {
-    ctx.router.get('/live', c => c.json({ ok: true }))
+    ctx.router.route('/', new App().get('/live', c => c.json({ ok: true })))
   },
 })
 

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

@@ -11,6 +11,7 @@ import { join } from 'node:path'
 import { Context, type FiberState } from '@deepseek-ai/cordis'
 import { Loader } from '@deepseek-ai/cordis-plugin-loader'
 import { afterEach, describe, expect, it } from 'vitest'
+import { App } from '../src/index.ts'
 
 const ACTIVE = 2 as FiberState.ACTIVE
 const DISPOSED = 4 as FiberState.DISPOSED
@@ -45,7 +46,7 @@ describe('acryl-router through a real Loader', () => {
   it('activates from the built entry and serves a request in process', async () => {
     const { ctx, entryId } = await mount()
     expect(entryOf(ctx, entryId).fiber?.state).toBe(ACTIVE)
-    ctx.router.get('/ping', c => c.json({ ok: true }))
+    ctx.router.route('/', new App().get('/ping', c => c.json({ ok: true })))
     const response = await ctx.router.fetch(new Request('http://acryl.test/ping'))
     expect(await response.json()).toEqual({ ok: true })
   })
@@ -65,7 +66,7 @@ describe('acryl-router through a real Loader', () => {
     expect(ctx.router).not.toBe(first)
     expect(ctx.router.size).toBe(0)
     expect((await first.fetch(new Request('http://acryl.test/x'))).status).toBe(503)
-    ctx.router.get('/again', c => c.text('ok'))
+    ctx.router.route('/', new App().get('/again', c => c.text('ok')))
     expect(await (await ctx.router.fetch(new Request('http://acryl.test/again'))).text()).toBe('ok')
   })
 })