acrylblends 0.0.0-stage → 0.3.0

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

package/plugins/acryl-router/tests/conformance.ts

@@ -0,0 +1,170 @@
+/**
+ * The framework-neutral conformance suite for a `router` (spec 046, milestone M0). A candidate is one factory returning
+ * five operations; the same checks run against every implementation, so choosing between the rewrite, H3 or
+ * a Rou3-based core is a matter of one adapter function and a test run.
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { Handler, Middleware, RouteMethod } from '../src/types.ts'
+
+export interface Candidate {
+  route(method: RouteMethod, path: string, handler: Handler): () => void
+  use(path: string, middleware: Middleware): () => void
+  fetch(request: Request): Promise<Response>
+  /** Routes plus middleware currently registered. */
+  size(): number
+}
+
+const req = (path: string, method = 'GET'): Request => new Request(`http://acryl.test${path}`, { method })
+const body = async (response: Response): Promise<string> => response.text()
+const echo = (label: string): Handler => c => c.text(`${label}:${JSON.stringify(c.params)}`)
+
+export function conformance(label: string, make: () => Promise<Candidate> | Candidate): void {
+  describe(`router conformance: ${label}`, () => {
+    it('matches exact, parameter and wildcard routes and decodes parameters', async () => {
+      const r = await make()
+      r.route('GET', '/', echo('root'))
+      r.route('GET', '/market', echo('market'))
+      r.route('GET', '/market/:id', echo('item'))
+      r.route('GET', '/files/*', echo('files'))
+      expect(await body(await r.fetch(req('/')))).toBe('root:{}')
+      expect(await body(await r.fetch(req('/market')))).toBe('market:{}')
+      expect(await body(await r.fetch(req('/market/a%20b')))).toBe('item:{"id":"a b"}')
+      expect(await body(await r.fetch(req('/files/a/b/c')))).toBe('files:{"*":"a/b/c"}')
+      expect((await r.fetch(req('/market/a/b'))).status).toBe(404)
+    })
+
+    it('prefers static over parameter over wildcard, whatever the registration order', async () => {
+      const r = await make()
+      r.route('GET', '/x/*', echo('wild'))
+      r.route('GET', '/x/:id', echo('param'))
+      r.route('GET', '/x/fixed', echo('static'))
+      expect(await body(await r.fetch(req('/x/fixed')))).toBe('static:{}')
+      expect(await body(await r.fetch(req('/x/other')))).toBe('param:{"id":"other"}')
+      expect(await body(await r.fetch(req('/x/other/deep')))).toBe('wild:{"*":"other/deep"}')
+    })
+
+    it('answers 404 for unknown paths and 405 with Allow for a known path with another method', async () => {
+      const r = await make()
+      r.route('GET', '/a', echo('a'))
+      r.route('POST', '/a', echo('a-post'))
+      expect((await r.fetch(req('/nope'))).status).toBe(404)
+      const refused = await r.fetch(req('/a', 'DELETE'))
+      expect(refused.status).toBe(405)
+      expect(refused.headers.get('allow')).toBe('GET, HEAD, POST')
+    })
+
+    it('answers HEAD from the GET route with the same status and headers and no body, unless a HEAD route exists', async () => {
+      const r = await make()
+      r.route('GET', '/h', c => c.json({ big: 'body' }, 202))
+      const head = await r.fetch(req('/h', 'HEAD'))
+      expect(head.status).toBe(202)
+      expect(head.headers.get('content-type')).toContain('application/json')
+      expect(await body(head)).toBe('')
+      r.route('HEAD', '/h', c => c.text('', 204))
+      expect((await r.fetch(req('/h', 'HEAD'))).status).toBe(204)
+    })
+
+    it('lets a specific method beat the any-method route, and the any-method route catch the rest', async () => {
+      const r = await make()
+      r.route('*', '/m', echo('any'))
+      r.route('GET', '/m', echo('get'))
+      expect(await body(await r.fetch(req('/m')))).toBe('get:{}')
+      expect(await body(await r.fetch(req('/m', 'PUT')))).toBe('any:{}')
+    })
+
+    it('throws on a duplicate route, including one that differs only in parameter name', async () => {
+      const r = await make()
+      r.route('GET', '/dup/:id', echo('one'))
+      expect(() => r.route('GET', '/dup/:name', echo('two'))).toThrow(/duplicate/i)
+      expect(() => r.route('POST', '/dup/:name', echo('post'))).not.toThrow()
+    })
+
+    it('rejects malformed paths', async () => {
+      const r = await make()
+      expect(() => r.route('GET', 'no-slash', echo('x'))).toThrow()
+      expect(() => r.route('GET', '/a/*/b', echo('x'))).toThrow()
+      expect(() => r.route('GET', '/a/:/b', echo('x'))).toThrow()
+      expect(() => r.route('GET', '/a/:id/:id', echo('x'))).toThrow()
+    })
+
+    it('runs middleware in registration order around the handler and lets one short-circuit', async () => {
+      const r = await make()
+      const seen: string[] = []
+      r.use('/api', async (c, next) => { seen.push('a-in'); c.set('who', 'alice'); const res = await next(); seen.push('a-out'); return res })
+      r.use('/api', async (_c, next) => { seen.push('b-in'); const res = await next(); seen.push('b-out'); return res })
+      r.use('/api/private', (c) => c.text('denied', 401))
+      r.route('GET', '/api/ok', c => c.text(`hello ${c.get<string>('who') ?? '?'}`))
+      r.route('GET', '/api/private/x', c => c.text('secret'))
+      r.route('GET', '/open', c => c.text('open'))
+
+      expect(await body(await r.fetch(req('/api/ok')))).toBe('hello alice')
+      expect(seen).toEqual(['a-in', 'b-in', 'b-out', 'a-out'])
+      seen.length = 0
+      const denied = await r.fetch(req('/api/private/x'))
+      expect(denied.status).toBe(401)
+      // The /api middleware still ran before the /api/private one refused; /open is outside every middleware path.
+      expect(seen).toEqual(['a-in', 'b-in', 'b-out', 'a-out'])
+      seen.length = 0
+      expect(await body(await r.fetch(req('/open')))).toBe('open')
+      expect(seen).toEqual([])
+    })
+
+    it('turns a throwing handler into a 500 and a double next() into a 500', async () => {
+      const r = await make()
+      r.route('GET', '/boom', () => { throw new Error('boom') })
+      r.use('/twice', async (_c, next) => { await next(); return next() })
+      r.route('GET', '/twice', echo('t'))
+      expect((await r.fetch(req('/boom'))).status).toBe(500)
+      expect((await r.fetch(req('/twice'))).status).toBe(500)
+    })
+
+    it('removes a route when its remover runs, is idempotent, and leaves other routes alone', async () => {
+      const r = await make()
+      const removeA = r.route('GET', '/a', echo('a'))
+      r.route('GET', '/b', echo('b'))
+      expect((await r.fetch(req('/a'))).status).toBe(200)
+      removeA()
+      removeA()
+      expect((await r.fetch(req('/a'))).status).toBe(404)
+      expect((await r.fetch(req('/b'))).status).toBe(200)
+      r.route('GET', '/a', echo('a2'))
+      expect(await body(await r.fetch(req('/a')))).toBe('a2:{}')
+    })
+
+    it('removes middleware with its remover', async () => {
+      const r = await make()
+      r.route('GET', '/p', echo('p'))
+      const remove = r.use('/', (c) => c.text('blocked', 403))
+      expect((await r.fetch(req('/p'))).status).toBe(403)
+      remove()
+      expect((await r.fetch(req('/p'))).status).toBe(200)
+    })
+
+    it('returns to its baseline size after fifty register and remove cycles', async () => {
+      const r = await make()
+      r.route('GET', '/stay', echo('stay'))
+      const baseline = r.size()
+      for (let i = 0; i < 50; i += 1) {
+        const a = r.route('GET', `/cycle/${String(i)}`, echo('c'))
+        const b = r.use(`/cycle/${String(i)}`, async (_c, next) => next())
+        expect(r.size()).toBe(baseline + 2)
+        a()
+        b()
+      }
+      expect(r.size()).toBe(baseline)
+    })
+
+    it('gives the same response through fetch as a handler builds, including headers and status', async () => {
+      const r = await make()
+      r.route('POST', '/echo/:name', async c => {
+        const text = await c.req.text()
+        return c.json({ name: c.params['name'], text, query: c.url.searchParams.get('q') }, 201)
+      })
+      const response = await r.fetch(new Request('http://acryl.test/echo/zed?q=1', { method: 'POST', body: 'hi' }))
+      expect(response.status).toBe(201)
+      expect(response.headers.get('content-type')).toContain('application/json')
+      expect(await response.json()).toEqual({ name: 'zed', text: 'hi', query: '1' })
+    })
+  })
+}

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

@@ -0,0 +1,172 @@
+/** The route helpers (spec 046): bounded body reading, server-sent events, and validation. */
+
+import { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, name, type Router } from '../src/index.ts'
+import { readBytes, readJson, readText, streamSSE, valid, validate } from '../src/helpers/index.ts'
+import { bodyLimit } from '../src/middleware/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+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 }
+}
+
+describe('readJson / readText / readBytes', () => {
+  it('reads a JSON body, and an empty body as no bytes', async () => {
+    const { router } = await mount()
+    router.post('/j', async c => c.json({ got: await readJson(c) }))
+    router.post('/t', async c => c.text(String((await readBytes(c)).byteLength)))
+    expect(await (await router.request('/j', { method: 'POST', body: '{"a":1}' })).json()).toEqual({ got: { a: 1 } })
+    expect(await (await router.request('/t', { method: 'POST' })).text()).toBe('0')
+  })
+
+  it('answers 400 for bad JSON and 413 over the limit, counting the bytes it reads', async () => {
+    const { router } = await mount()
+    router.post('/j', async c => c.json(await readJson(c, { maxBytes: 16 })))
+    expect((await router.request('/j', { method: 'POST', body: '{nope' })).status).toBe(400)
+    const big = await router.request('/j', { method: 'POST', body: JSON.stringify({ pad: 'x'.repeat(100) }) })
+    expect(big.status).toBe(413)
+  })
+
+  it('stops a chunked body that has no declared length at the limit', async () => {
+    const { router } = await mount()
+    router.post('/t', async c => c.text(await readText(c, { maxBytes: 8 })))
+    const stream = new ReadableStream<Uint8Array>({ start(controller) { controller.enqueue(new TextEncoder().encode('0123456789')); controller.close() } })
+    const response = await router.request(new Request('http://localhost/t', { method: 'POST', body: stream, duplex: 'half' } as RequestInit))
+    expect(response.status).toBe(413)
+  })
+
+  it('uses the limit the bodyLimit middleware set', async () => {
+    const { router } = await mount()
+    router.use(bodyLimit({ maxBytes: 4 }))
+    router.post('/t', async c => c.text(await readText(c)))
+    const stream = new ReadableStream<Uint8Array>({ start(controller) { controller.enqueue(new TextEncoder().encode('abcdefgh')); controller.close() } })
+    expect((await router.request(new Request('http://localhost/t', { method: 'POST', body: stream, duplex: 'half' } as RequestInit))).status).toBe(413)
+  })
+})
+
+describe('streamSSE', () => {
+  async function read(response: Response, count: number): Promise<string[]> {
+    const reader = response.body!.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    const out: string[] = []
+    while (out.length < count) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      for (let at = buffer.indexOf('\n\n'); at !== -1; at = buffer.indexOf('\n\n')) { out.push(buffer.slice(0, at)); buffer = buffer.slice(at + 2) }
+    }
+    reader.releaseLock()
+    return out
+  }
+
+  it('sends events with ids, names, JSON and multi-line text, and a comment', async () => {
+    const { router } = await mount()
+    router.get('/s', c => streamSSE(c, stream => {
+      stream.send({ n: 1 }, { event: 'tick', id: '7' })
+      stream.send('line one\nline two')
+      stream.comment('keep-alive')
+    }))
+    const events = await read(await router.request('/s'), 3)
+    expect(events).toEqual(['id: 7\nevent: tick\ndata: {"n":1}', 'data: line one\ndata: line two', ': keep-alive'])
+  })
+
+  it('runs its cleanup once when the client aborts, and ends the stream', async () => {
+    const { router } = await mount()
+    let cleaned = 0
+    router.get('/s', c => streamSSE(c, () => () => { cleaned += 1 }))
+    const controller = new AbortController()
+    const response = await router.request('/s', { signal: controller.signal })
+    const reader = response.body!.getReader()
+    controller.abort()
+    await expect(reader.read()).resolves.toMatchObject({ done: true })
+    await settle(5)
+    expect(cleaned).toBe(1)
+  })
+
+  it('lets the server close the stream, and runs the cleanup once even if cancelled afterwards', async () => {
+    const { router } = await mount()
+    let cleaned = 0
+    router.get('/s', c => streamSSE(c, stream => { stream.send('only'); stream.close(); return () => { cleaned += 1 } }))
+    const response = await router.request('/s')
+    const reader = response.body!.getReader()
+    expect((await reader.read()).done).toBe(false)
+    await expect(reader.read()).resolves.toMatchObject({ done: true })
+    await reader.cancel()
+    expect(cleaned).toBe(1)
+  })
+
+  it('is ended and awaited when its plugin unloads the router', async () => {
+    const { ctx, router } = await mount()
+    let cleaned = 0
+    router.get('/s', c => streamSSE(c, () => () => { cleaned += 1 }))
+    const response = await router.request('/s')
+    const reader = response.body!.getReader()
+    const ended = reader.read()
+    await ctx.fiber.dispose()
+    contexts.length = 0
+    await expect(ended).resolves.toMatchObject({ done: true })
+    expect(cleaned).toBe(1)
+  })
+})
+
+describe('validate', () => {
+  const Body = z.object({ name: z.string().required(), age: z.number().default(0) })
+
+  it('hands the handler the parsed value, with defaults applied', async () => {
+    const { router } = await mount()
+    router.post('/u', validate('json', Body), c => c.json(valid<{ name: string, age: number }>(c, 'json')))
+    const response = await router.request('/u', { method: 'POST', body: '{"name":"ada"}' })
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ name: 'ada', age: 0 })
+  })
+
+  it('answers 400 with the issues for an invalid body, query or parameter', async () => {
+    const { router } = await mount()
+    router.post('/u', validate('json', Body), c => c.text('ok'))
+    router.get('/q', validate('query', z.object({ page: z.string().required() })), c => c.text('ok'))
+    router.get('/p/:id', validate('param', z.object({ id: z.string().pattern(/^\d+$/u).required() })), c => c.text('ok'))
+    const bad = await router.request('/u', { method: 'POST', body: '{}' })
+    expect(bad.status).toBe(400)
+    expect(((await bad.json()) as { error: string }).error).toBe('invalid json')
+    expect((await router.request('/q')).status).toBe(400)
+    expect((await router.request('/q?page=2')).status).toBe(200)
+    expect((await router.request('/p/abc')).status).toBe(400)
+    expect((await router.request('/p/42')).status).toBe(200)
+  })
+
+  it('tells the author when valid() is used without validate()', async () => {
+    const { router } = await mount()
+    router.get('/x', c => c.text(String(valid(c, 'json'))))
+    expect((await router.request('/x')).status).toBe(500)
+  })
+})
+
+describe('streamSSE keepalive and validate on bad JSON', () => {
+  it('sends a comment line on an idle stream and stops when it ends', async () => {
+    const { router } = await mount()
+    router.get('/s', c => streamSSE(c, () => undefined, { keepAliveMs: 10 }))
+    const response = await router.request('/s')
+    const reader = response.body!.getReader()
+    const chunk = new TextDecoder().decode((await reader.read()).value)
+    expect(chunk).toBe(': keepalive\n\n')
+    await reader.cancel()
+  })
+
+  it('answers 400, not 500, when the body is not JSON', async () => {
+    const { router } = await mount()
+    router.post('/v', validate('json', z.object({ a: z.number() }) as never), c => c.json(valid(c, 'json')))
+    expect((await router.request('/v', { method: 'POST', body: '{nope' })).status).toBe(400)
+  })
+})

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

@@ -0,0 +1,64 @@
+/**
+ * Mounting a plugin after startup from inside a Service method (what an Extensions service does). Inside a service method `this.ctx` is Cordis's
+ * "shadow" context, which resolves services as the SERVICE'S OWN fiber; a child plugin mounted with it inherits that shadow, so its `ctx.router`
+ * is looked up in the installer's fiber (which never injected it) and throws "cannot get property router without inject", even though the child's
+ * own `fiber.inject` and `ctx.get('router')` are fine. The context captured in the constructor is not shadowed and mounts a plugin that behaves
+ * exactly like one mounted at startup.
+ */
+import { Context, Service } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, name } 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()
+})
+
+class Installer extends Service {
+  private readonly owner: Context
+  constructor(ctx: Context) {
+    super(ctx, 'installer')
+    this.owner = ctx
+  }
+
+  /** Right: mount from the context captured in the constructor. */
+  async install(module: object): Promise<void> {
+    await this.owner.plugin(module as { apply(ctx: Context): void })
+  }
+
+  /** Wrong: `this.ctx` inside a method is the shadow context. */
+  async installFromShadow(module: object): Promise<void> {
+    await this.ctx.plugin(module as { apply(ctx: Context): void })
+  }
+}
+
+async function system(): Promise<Context & { installer: Installer }> {
+  const root = new Context()
+  contexts.push(root)
+  root.plugin({ name, apply })
+  root.plugin({ name: 'installer', apply: (ctx: Context) => { new Installer(ctx) } })
+  await settle()
+  return root as Context & { installer: Installer }
+}
+
+const extension = (): object => ({
+  name: 'live-ext',
+  inject: ['router'],
+  apply(ctx: Context): void {
+    ctx.router.get('/live', c => c.json({ ok: true }))
+  },
+})
+
+describe('live install from a service method', () => {
+  it('works from the constructor context: the plugin reads ctx.router like one mounted at startup', async () => {
+    const root = await system()
+    await root.installer.install(extension())
+    expect(await (await root.router.request('/live')).json()).toEqual({ ok: true })
+  })
+
+  it('fails from this.ctx, which is Cordis behavior the framework docs warn about', async () => {
+    const root = await system()
+    await expect(root.installer.installFromShadow(extension())).rejects.toThrow(/cannot get property "router" without inject/u)
+  })
+})