acrylblends 0.2.0 → 0.3.0

package/plugins/acryl-inspect/tests/report.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { explain, renderReports, reportFiber, stateName, type FiberView } from '../src/report.ts'
+
+function fiber(over: Partial<FiberView> & { effects?: FiberView['getEffects'] extends () => infer R ? R : never } = {}): FiberView {
+  const { effects = [], ...rest } = over
+  return { state: 2, inject: {}, runtime: { name: 'demo' }, getEffects: () => effects, ...rest }
+}
+
+describe('reportFiber', () => {
+  it('sorts effects into provides, routes, middleware and everything else, including nested ones', () => {
+    const report = reportFiber(fiber({
+      inject: { router: null, acrylSettings: null },
+      effects: [
+        { label: 'ctx.provide("things")', children: [] },
+        { label: 'acryl-router: GET /api/things/:id', children: [] },
+        { label: 'acryl-router: POST /api/things', children: [{ label: 'inner timer', children: [] }] },
+        { label: 'acryl-router: use /api', children: [] },
+        { label: 'ctx.on("internal/status")', children: [] },
+      ],
+    }))
+    expect(report).toEqual({
+      name: 'demo',
+      state: 'ACTIVE',
+      requires: ['acrylSettings', 'router'],
+      provides: ['things'],
+      routes: [{ method: 'GET', path: '/api/things/:id' }, { method: 'POST', path: '/api/things' }],
+      middleware: ['/api'],
+      other: ['inner timer', 'ctx.on("internal/status")'],
+      removedOnUnload: 6,
+    })
+  })
+
+  it('names the state and an anonymous plugin', () => {
+    expect(stateName(0)).toBe('PENDING')
+    expect(stateName(2)).toBe('ACTIVE')
+    expect(stateName(5)).toBe('UNLOADING')
+    expect(reportFiber(fiber({ runtime: null })).name).toBe('anonymous')
+  })
+})
+
+describe('explain', () => {
+  it('says what a plugin needs, adds and removes on unload', () => {
+    const text = explain(reportFiber(fiber({
+      inject: { router: null },
+      effects: [{ label: 'acryl-router: GET /a', children: [] }],
+    })))
+    expect(text).toContain('demo (ACTIVE)')
+    expect(text).toContain('needs:     router')
+    expect(text).toContain('routes:    GET /a')
+    expect(text).toContain('unloading: removes 1 registration and nothing else')
+  })
+
+  it('says a pending plugin is waiting for its services', () => {
+    const text = explain(reportFiber(fiber({ state: 0, inject: { router: null, webServer: null } })))
+    expect(text).toContain('demo (PENDING)')
+    expect(text).toContain('it starts when router, webServer are available')
+  })
+
+  it('renders several plugins as blocks', () => {
+    const a = reportFiber(fiber({ runtime: { name: 'a' } }))
+    const b = reportFiber(fiber({ runtime: { name: 'b' } }))
+    expect(renderReports([a, b]).split('\n\n')).toHaveLength(2)
+  })
+})

package/plugins/acryl-inspect/tests/service.spec.ts

@@ -0,0 +1,120 @@
+/**
+ * The inspector against real Cordis plugins: what it reports is what Cordis holds, so the tests build a small system and
+ * compare the report with what the plugins actually did.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, name, type PluginReport } 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()
+})
+
+const market = {
+  name: 'demo-market',
+  inject: ['router'],
+  apply(ctx: Context): void {
+    ctx.router.use('/api/demo', async (_c, next) => next())
+    ctx.router.get('/api/demo/state', c => c.json({ ok: true }))
+    ctx.router.post('/api/demo/sources', c => c.json({ ok: true }, 201))
+  },
+}
+
+async function system(): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name, apply })
+  await settle()
+  return ctx
+}
+
+const byName = (reports: readonly PluginReport[], pluginName: string): PluginReport => {
+  const found = reports.find(report => report.name === pluginName)
+  if (found === undefined) throw new Error(`no report for ${pluginName}`)
+  return found
+}
+
+describe('acryl-inspect', () => {
+  it('counts what an inline ctx.inject callback registers as the owning plugin\'s', async () => {
+    const ctx = await system()
+    ctx.plugin({
+      name: 'demo-inline',
+      apply(inner: Context): void {
+        inner.inject(['router'], deeper => { deeper.router.get('/api/inline', c => c.json({ ok: true })) })
+      },
+    })
+    await settle()
+    const reports = ctx.inspect.plugins()
+    expect(byName(reports, 'demo-inline').routes).toEqual([{ method: 'GET', path: '/api/inline' }])
+    expect(reports.every(report => report.name !== 'anonymous')).toBe(true)
+  })
+
+  it('reports what a plugin requires, provides and registers, from the running system', async () => {
+    const ctx = await system()
+    ctx.plugin(market)
+    await settle()
+    const reports = ctx.inspect.plugins()
+
+    expect(byName(reports, 'acryl-router')).toMatchObject({ state: 'ACTIVE', requires: [], provides: ['router'] })
+    expect(byName(reports, 'acryl-inspect')).toMatchObject({ state: 'ACTIVE', provides: ['inspect'] })
+    const demo = byName(reports, 'demo-market')
+    expect(demo).toMatchObject({
+      state: 'ACTIVE',
+      requires: ['router'],
+      provides: [],
+      routes: [{ method: 'GET', path: '/api/demo/state' }, { method: 'POST', path: '/api/demo/sources' }],
+      middleware: ['/api/demo'],
+      removedOnUnload: 3,
+    })
+  })
+
+  it('shows a plugin whose service is missing as PENDING and says what it waits for', async () => {
+    const ctx = await system()
+    ctx.plugin({ name: 'needs-a-thing', inject: ['neverProvided'], apply() { /* never runs */ } })
+    await settle()
+    expect(byName(ctx.inspect.plugins(), 'needs-a-thing')).toMatchObject({ state: 'PENDING', requires: ['neverProvided'] })
+    expect(ctx.inspect.explain('needs-a-thing')).toContain('it starts when neverProvided is available')
+  })
+
+  it('stops listing a plugin that unloaded, and the router really lost what the report said would go', async () => {
+    const ctx = await system()
+    const baseline = ctx.router.size
+    const fiber = ctx.plugin(market)
+    await settle()
+    const promised = byName(ctx.inspect.plugins(), 'demo-market').removedOnUnload
+    expect(ctx.router.size - baseline).toBe(promised)
+
+    await fiber.dispose()
+    await settle()
+    expect(ctx.inspect.plugins().some(report => report.name === 'demo-market' && report.state === 'ACTIVE')).toBe(false)
+    expect(ctx.router.size).toBe(baseline)
+  })
+
+  it('serves the same facts on the router, in process', async () => {
+    const ctx = await system()
+    ctx.plugin(market)
+    await settle()
+    const list = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins'))
+    expect(list.status).toBe(200)
+    const reports = await list.json() as PluginReport[]
+    expect(byName(reports, 'demo-market').routes).toHaveLength(2)
+
+    const one = await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/demo-market'))
+    expect(await one.text()).toContain('removes 3 registrations and nothing else')
+    expect((await ctx.router.fetch(new Request('http://acryl.test/api/inspect/plugins/nope'))).status).toBe(404)
+  })
+
+  it('needs no router: without one it still answers in code and registers no routes', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    ctx.plugin({ name, apply })
+    await settle()
+    expect(byName(ctx.inspect.plugins(), 'acryl-inspect').routes).toEqual([])
+    expect(ctx.inspect.render()).toContain('acryl-inspect (ACTIVE)')
+  })
+})

package/plugins/acryl-inspect/upstream.json

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-inspect",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 3,
+  "digest": "sha256:0fa799474c66b7a2a159c17ea143030b9fc6a38fcb4219f5139e78fd4508bdb7",
+  "testsNotRun": {},
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-node-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-node-server/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-node-server",
+  "description": "The standalone HTTP server as a Cordis plugin: one node:http listener that sends every request to the router. Port, loopback host and next-free-port scan; ends open streams and frees the port when unloaded. Vendored from ACRYL.",
+  "requires": ["acryl-router", "acryl-router-http"],
+  "inject": ["router"],
+  "provides": ["nodeServer"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "root.plugin(router); root.plugin(nodeServer, { port: 3000, hostname: '127.0.0.1', scan: 20 }); ctx.nodeServer.url"
+}

package/plugins/acryl-node-server/src/index.ts

@@ -0,0 +1,94 @@
+/**
+ * The framework's standalone HTTP adapter (spec 046), the standalone counterpart of the Host adapter. It owns one
+ * `node:http` listener and hands every request to `ctx.router.fetch`, with the socket's peer address and local port as connection facts.
+ * Use it in an app that runs without the ACRYL Host; inside the Host, `acryl-router-http` mounts prefixes on the Host's own web server.
+ * One adapter per runtime: a plugin keeps asking `ctx.inject(['routerHttp'], ...)` for a mount, which simply never fires here, because this
+ * adapter serves the whole router.
+ *
+ * A configured port that is taken is followed by the next free one, at most `scan` further ports; port 0 lets the system choose. Disposal ends
+ * open streams, closes every connection and returns once the port is free.
+ */
+
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { serve } from '../../acryl-router-http/src/index.ts'
+import type {} from '../../acryl-router/src/index.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-node-server'
+export const inject = ['router']
+
+export interface Config {
+  hostname: string
+  port: number
+  scan: number
+}
+
+export const Config: z<Config> = z.object({
+  hostname: z.string().default('127.0.0.1').description('Address to bind. Loopback by default; binding elsewhere exposes the app to the network.'),
+  port: z.number().min(0).max(65535).default(0).description('Port to listen on; 0 lets the system choose. A taken port is followed by the next free one.'),
+  scan: z.number().min(0).default(20).description('How many further ports to try when the configured one is taken.'),
+})
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    nodeServer: NodeServer
+  }
+}
+
+export class NodeServer extends Service {
+  readonly hostname: string
+  readonly config: Config
+  private readonly server: Server
+  private bound = 0
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'nodeServer')
+    this.config = config
+    this.hostname = config.hostname
+    const router = ctx.router
+    this.server = createServer((req, res) => { void serve(router, req, res) })
+    ctx.effect(() => async () => {
+      this.server.closeAllConnections()
+      if (this.server.listening) await new Promise<void>(resolve => { this.server.close(() => { resolve() }) })
+    }, 'acryl-node-server: close listener and open connections')
+  }
+
+  /** The port in use, 0 before the server listens. */
+  get port(): number {
+    return this.bound
+  }
+
+  /** The address clients use. */
+  get url(): string {
+    return `http://${this.hostname.includes(':') ? `[${this.hostname}]` : this.hostname}:${String(this.bound)}`
+  }
+
+  /** Bind, scanning past taken ports. */
+  async listen(): Promise<void> {
+    const { port, scan, hostname } = this.config
+    const last = port === 0 ? 0 : Math.min(65535, port + scan)
+    for (let candidate = port; candidate <= last; candidate += 1) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const onError = (error: Error): void => { reject(error) }
+          this.server.once('error', onError)
+          this.server.listen(candidate, hostname, () => { this.server.off('error', onError); resolve() })
+        })
+        this.bound = (this.server.address() as AddressInfo).port
+        return
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+      }
+    }
+    throw new Error(`acryl-node-server: no free port from ${String(port)} to ${String(last)} on ${hostname}`)
+  }
+}
+
+/** Loads once the server listens, so a plugin that injects `nodeServer` can rely on `url`. A failure to bind fails the plugin. */
+export async function apply(ctx: Context, config: Partial<Config> = {}): Promise<void> {
+  const server = new NodeServer(ctx, { hostname: '127.0.0.1', port: 0, scan: 20, ...config })
+  await server.listen()
+}

package/plugins/acryl-node-server/tests/server.spec.ts

@@ -0,0 +1,105 @@
+/** The standalone adapter over real sockets: serving, connection facts, port scan, streams, disposal, reload. */
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { Context } from '@deepseek-ai/cordis'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { streamSSE } from '../../acryl-router/src/helpers/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as nodeServer from '../src/index.ts'
+
+/** The plugin as an object, so its config is the partial `apply` accepts rather than the Loader's validated shape. */
+const plugin = { name: nodeServer.name, inject: nodeServer.inject, apply: nodeServer.apply }
+const contexts: Context[] = []
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+const settle = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 20))
+
+async function boot(config: Partial<nodeServer.Config> = {}): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name: routerName, apply: routerApply })
+  ctx.plugin(plugin, config)
+  await settle()
+  return ctx
+}
+
+/** Hold a port so a server asked for it has to scan. */
+async function occupy(): Promise<{ port: number, release: () => Promise<void> }> {
+  const blocker = createServer()
+  await new Promise<void>(resolve => blocker.listen(0, '127.0.0.1', resolve))
+  return { port: (blocker.address() as AddressInfo).port, release: () => new Promise<void>(resolve => blocker.close(() => { resolve() })) }
+}
+
+const portIsFree = async (port: number): Promise<boolean> => {
+  const probe = createServer()
+  return new Promise<boolean>(resolve => {
+    probe.once('error', () => { resolve(false) })
+    probe.listen(port, '127.0.0.1', () => { probe.close(() => { resolve(true) }) })
+  })
+}
+
+describe('acryl-node-server', () => {
+  it('serves the router over a real socket with the peer and port as connection facts', async () => {
+    const ctx = await boot()
+    ctx.router.get('/who', c => c.json({ peer: c.connection.remoteAddress, port: c.connection.localPort }))
+    const body = await (await fetch(`${ctx.nodeServer.url}/who`)).json() as { peer: string, port: number }
+    expect(ctx.nodeServer.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/u)
+    expect(body.port).toBe(ctx.nodeServer.port)
+    expect(body.peer).toMatch(/127\.0\.0\.1/u)
+    expect((await fetch(`${ctx.nodeServer.url}/missing`)).status).toBe(404)
+  })
+
+  it('scans to the next free port when the configured one is taken', async () => {
+    const taken = await occupy()
+    try {
+      const ctx = await boot({ port: taken.port, scan: 20 })
+      expect(ctx.nodeServer.port).toBeGreaterThan(taken.port)
+      expect(ctx.nodeServer.port).toBeLessThanOrEqual(taken.port + 20)
+    } finally {
+      await taken.release()
+    }
+  })
+
+  it('fails the plugin when no port in the scan range is free', async () => {
+    const taken = await occupy()
+    try {
+      const ctx = new Context()
+      contexts.push(ctx)
+      ctx.plugin({ name: routerName, apply: routerApply })
+      const fiber = ctx.plugin(plugin, { port: taken.port, scan: 0 })
+      await settle()
+      expect(fiber.state).toBe(3) // FAILED
+    } finally {
+      await taken.release()
+    }
+  })
+
+  it('on dispose ends open event streams and frees the port', async () => {
+    const ctx = await boot()
+    ctx.router.get('/events', c => streamSSE(c, stream => { stream.send('hello') }))
+    const port = ctx.nodeServer.port
+    const response = await fetch(`${ctx.nodeServer.url}/events`)
+    const reader = response.body!.getReader()
+    expect(new TextDecoder().decode((await reader.read()).value)).toContain('data: hello')
+    await ctx.fiber.dispose()
+    contexts.splice(contexts.indexOf(ctx), 1)
+    const ended = await reader.read().then(result => result.done, () => true)
+    expect(ended).toBe(true)
+    expect(await portIsFree(port)).toBe(true)
+  })
+
+  it('reloads without leaking a listener', async () => {
+    const ctx = new Context()
+    contexts.push(ctx)
+    ctx.plugin({ name: routerName, apply: routerApply })
+    const ports: number[] = []
+    for (let round = 0; round < 5; round += 1) {
+      const fiber = ctx.plugin(plugin, {})
+      await settle()
+      ports.push(ctx.nodeServer.port)
+      await fiber.dispose()
+    }
+    for (const port of ports) expect(await portIsFree(port)).toBe(true)
+  })
+})

package/plugins/acryl-node-server/upstream.json

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-node-server",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 4,
+  "digest": "sha256:0931c522f7b595d80dd39a4d6179d8ba05acef612f309985149f2501c2c4622e",
+  "testsNotRun": {},
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-router/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-router/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-router",
+  "description": "The router service as a Cordis plugin: Web-standard Request and Response, path parameters, middleware, helpers, an in-process fetch and request() for tests. Vendored from ACRYL.",
+  "requires": [],
+  "inject": [],
+  "provides": ["router"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "root.plugin(router); then in your own plugin: inject: ['router'] and ctx.router.get('/path', (c) => c.json({ ok: true }))"
+}

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

@@ -0,0 +1,21 @@
+import type { Handler, Middleware, RouteContext } from './types.ts'
+
+/**
+ * Run `middleware` in order around `final`. Each middleware receives `next`, which runs the rest of the chain and
+ * resolves to its response. Calling `next` twice in one middleware is a programming error and rejects.
+ */
+export function compose(middleware: readonly Middleware[], final: Handler): Handler {
+  return (c: RouteContext): Promise<Response> => {
+    const dispatch = async (index: number): Promise<Response> => {
+      const current = middleware[index]
+      if (current === undefined) return final(c)
+      let called = false
+      return current(c, () => {
+        if (called) return Promise.reject(new Error('router: next() called more than once'))
+        called = true
+        return dispatch(index + 1)
+      })
+    }
+    return dispatch(0)
+  }
+}

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

@@ -0,0 +1,59 @@
+import type { ConnectionInfo, ResponseBody, RouteContext } from './types.ts'
+
+const JSON_TYPE = 'application/json; charset=utf-8'
+const TEXT_TYPE = 'text/plain; charset=utf-8'
+const HTML_TYPE = 'text/html; charset=utf-8'
+
+/** Statuses that must not carry a body; a `Response` constructed with one throws. */
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304])
+const bodyFor = <T>(status: number, body: T): T | null => NULL_BODY_STATUSES.has(status) ? null : body
+
+/** Build the per-request context. `notFound` is what `c.notFound()` runs: the router's own answer. */
+export function createContext(
+  req: Request,
+  params: Record<string, string>,
+  signal: AbortSignal,
+  connection: ConnectionInfo,
+  track: (task: Promise<unknown>) => void,
+  notFound: (c: RouteContext) => Response | Promise<Response>,
+): RouteContext {
+  const values = new Map<string, unknown>()
+  const url = new URL(req.url)
+  const defaults = new Headers()
+  let defaultStatus = 200
+
+  const respond = (body: ResponseBody, status: number | undefined, type: string | undefined, extra?: Record<string, string>): Response => {
+    const code = status ?? defaultStatus
+    const headers = new Headers(defaults)
+    if (type !== undefined && !headers.has('content-type')) headers.set('content-type', type)
+    for (const [name, value] of Object.entries(extra ?? {})) headers.set(name, value)
+    return new Response(bodyFor(code, body), { status: code, headers })
+  }
+
+  const context: RouteContext = {
+    req,
+    url,
+    params,
+    connection,
+    signal,
+    waitUntil: track,
+    get: <T>(key: string) => values.get(key) as T | undefined,
+    set: (key, value) => { values.set(key, value) },
+    header: (name, value) => { defaults.set(name, value) },
+    status: code => { defaultStatus = code },
+    query: ((name?: string) => {
+      if (name !== undefined) return url.searchParams.get(name) ?? undefined
+      const all: Record<string, string> = {}
+      for (const [key, value] of url.searchParams) if (!(key in all)) all[key] = value
+      return all
+    }) as RouteContext['query'],
+    param: ((name?: string) => name === undefined ? params : params[name]) as RouteContext['param'],
+    json: (data, status) => respond(JSON.stringify(data), status, JSON_TYPE),
+    text: (body, status) => respond(body, status, TEXT_TYPE),
+    html: (body, status) => respond(body, status, HTML_TYPE),
+    body: (data, status, headers) => respond(data, status, undefined, headers),
+    redirect: (location, status = 302) => respond(null, status, undefined, { location }),
+    notFound: () => notFound(context),
+  }
+  return context
+}

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

@@ -0,0 +1,3 @@
+export { readBytes, readJson, readText, type ReadBodyOptions } from './read-body.ts'
+export { streamSSE, type SseOptions, type SseStream } from './sse.ts'
+export { valid, validate, type StandardSchema, type ValidationTarget } from './validate.ts'

package/plugins/acryl-router/src/helpers/read-body.ts

@@ -0,0 +1,59 @@
+import { HttpError } from '../http-error.ts'
+import { BODY_LIMIT_KEY } from '../middleware/body-limit.ts'
+import type { RouteContext } from '../types.ts'
+
+export interface ReadBodyOptions {
+  /** The most bytes to accept. Defaults to the `bodyLimit` middleware's limit when it ran, otherwise 1 MiB. */
+  readonly maxBytes?: number
+}
+
+const DEFAULT_MAX_BYTES = 1024 * 1024
+
+/**
+ * Read the request body as bytes, counting as it streams, and stop at the limit (a 413 `HttpError`). Stops at once when the request is aborted.
+ * A request with no body gives an empty array.
+ */
+export async function readBytes(c: RouteContext, options: ReadBodyOptions = {}): Promise<Uint8Array> {
+  const limit = options.maxBytes ?? c.get<number>(BODY_LIMIT_KEY) ?? DEFAULT_MAX_BYTES
+  c.signal.throwIfAborted()
+  const reader = c.req.body?.getReader()
+  if (reader === undefined) return new Uint8Array()
+  const onAbort = (): void => { void reader.cancel(c.signal.reason).catch(() => undefined) }
+  c.signal.addEventListener('abort', onAbort, { once: true })
+  const chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > limit) {
+        await reader.cancel().catch(() => undefined)
+        throw new HttpError(413, { message: 'payload too large' })
+      }
+      chunks.push(value)
+    }
+  } finally {
+    c.signal.removeEventListener('abort', onAbort)
+  }
+  c.signal.throwIfAborted()
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength }
+  return bytes
+}
+
+/** The body as UTF-8 text, within the limit. */
+export async function readText(c: RouteContext, options?: ReadBodyOptions): Promise<string> {
+  return new TextDecoder().decode(await readBytes(c, options))
+}
+
+/** The body parsed as JSON, within the limit. Bad JSON is a 400 `HttpError`. */
+export async function readJson(c: RouteContext, options?: ReadBodyOptions): Promise<unknown> {
+  const text = await readText(c, options)
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    throw new HttpError(400, { message: 'invalid json' })
+  }
+}