acrylblends 0.0.0-stage → 0.3.0

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

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

@@ -0,0 +1,83 @@
+import type { RouteContext } from '../types.ts'
+
+export interface SseStream {
+  /** Send one event. Objects and arrays are sent as JSON; strings as they are. */
+  send(data: unknown, options?: { readonly event?: string, readonly id?: string }): void
+  /** Send a comment line (a keep-alive that clients ignore). */
+  comment(text: string): void
+  /** End the stream from the server side. */
+  close(): void
+  /** Aborted when the client goes away or the router is disposed. */
+  readonly signal: AbortSignal
+}
+
+const HEADERS = {
+  'content-type': 'text/event-stream; charset=utf-8',
+  'cache-control': 'no-store',
+  'x-content-type-options': 'nosniff',
+} as const
+
+const encode = (text: string): Uint8Array => new TextEncoder().encode(text)
+
+export interface SseOptions {
+  /** A comment line is sent this often so proxies and browsers keep an idle stream open. Default 15 seconds. */
+  readonly keepAliveMs?: number
+}
+
+const DEFAULT_KEEP_ALIVE_MS = 15_000
+
+/**
+ * A server-sent-event response. `run` starts the stream; whatever cleanup function it returns runs exactly once when the stream
+ * ends for any reason (the client disconnects, `close()`, a plugin unload, the router being disposed). The request is held in flight with `waitUntil`
+ * until then, so disposal waits for the stream instead of leaking it.
+ */
+export function streamSSE(c: RouteContext, run: (stream: SseStream) => void | (() => void), options: SseOptions = {}): Response {
+  let finish!: () => void
+  c.waitUntil(new Promise<void>(resolve => { finish = resolve }))
+  let controller!: ReadableStreamDefaultController<Uint8Array>
+  let cleanup: (() => void) | undefined
+  let ended = false
+  let keepAlive: ReturnType<typeof setInterval> | undefined
+
+  const end = (): void => {
+    if (ended) return
+    ended = true
+    clearInterval(keepAlive)
+    c.signal.removeEventListener('abort', end)
+    try { cleanup?.() } finally {
+      try { controller.close() } catch { /* already closed */ }
+      finish()
+    }
+  }
+
+  const body = new ReadableStream<Uint8Array>({
+    start: ctrl => {
+      controller = ctrl
+      const stream: SseStream = {
+        signal: c.signal,
+        send: (data, options) => {
+          if (ended) return
+          const lines: string[] = []
+          if (options?.id !== undefined) lines.push(`id: ${options.id}`)
+          if (options?.event !== undefined) lines.push(`event: ${options.event}`)
+          const payload = typeof data === 'string' ? data : JSON.stringify(data)
+          for (const line of payload.split('\n')) lines.push(`data: ${line}`)
+          try { controller.enqueue(encode(`${lines.join('\n')}\n\n`)) } catch { end() }
+        },
+        comment: text => {
+          if (ended) return
+          try { controller.enqueue(encode(`: ${text.replaceAll('\n', ' ')}\n\n`)) } catch { end() }
+        },
+        close: end,
+      }
+      if (c.signal.aborted) { end(); return }
+      c.signal.addEventListener('abort', end, { once: true })
+      keepAlive = setInterval(() => { stream.comment('keepalive') }, options.keepAliveMs ?? DEFAULT_KEEP_ALIVE_MS)
+      keepAlive.unref()
+      cleanup = run(stream) ?? undefined
+      if (ended) { try { cleanup?.() } catch { /* the stream already ended */ } }
+    },
+    cancel: end,
+  })
+  return new Response(body, { headers: HEADERS })
+}

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

@@ -0,0 +1,44 @@
+import { HttpError } from '../http-error.ts'
+import type { Middleware, RouteContext } from '../types.ts'
+import { readJson } from './read-body.ts'
+
+/** The slice of the Standard Schema interface this needs; Schemastery (what Cordis uses), Zod and Valibot all implement it. */
+export interface StandardSchema<T = unknown> {
+  readonly '~standard': {
+    validate(value: unknown): StandardResult<T> | Promise<StandardResult<T>>
+  }
+}
+
+type StandardResult<T> =
+  | { readonly value: T, readonly issues?: undefined }
+  | { readonly issues: readonly { readonly message: string, readonly path?: readonly unknown[] | undefined }[] }
+
+export type ValidationTarget = 'json' | 'query' | 'param'
+
+const key = (target: ValidationTarget): string => `valid:${target}`
+
+/**
+ * Validate part of the request against a schema before the handler runs. A failure is a 400 with the issues; success stores the
+ * parsed value, which the handler reads with `valid(c, target)`. `json` reads the body within the limit; `query` is the first value of each query
+ * parameter; `param` is the matched path parameters.
+ */
+export function validate<T>(target: ValidationTarget, schema: StandardSchema<T>): Middleware {
+  return async (c, next) => {
+    const input = target === 'json' ? await readJson(c) : target === 'query' ? c.query() : { ...c.param() }
+    const result = await schema['~standard'].validate(input)
+    if (result.issues !== undefined) {
+      throw new HttpError(400, {
+        response: c.json({ error: `invalid ${target}`, issues: result.issues.map(issue => ({ message: issue.message, path: (issue.path ?? []).map(part => String(typeof part === 'object' && part !== null && 'key' in part ? (part as { key: unknown }).key : part)).join('.') })) }, 400),
+      })
+    }
+    c.set(key(target), result.value)
+    return next()
+  }
+}
+
+/** The value `validate(target, schema)` stored. Throws if that middleware did not run on this route. */
+export function valid<T>(c: RouteContext, target: ValidationTarget): T {
+  const value = c.get<T>(key(target))
+  if (value === undefined) throw new Error(`valid("${target}"): no validate("${target}", schema) ran before this handler`)
+  return value
+}

package/plugins/acryl-router/src/http-error.ts

@@ -0,0 +1,21 @@
+/**
+ * An error that carries the response it should become. A handler or middleware throws it to stop a request
+ * with a status: `throw new HttpError(401, { message: 'Sign in first' })`. The router answers with `getResponse()`; a registered
+ * `onError` handler still sees every other error.
+ */
+export class HttpError extends Error {
+  readonly status: number
+  private readonly response: Response | undefined
+
+  constructor(status: number, options: { readonly message?: string, readonly response?: Response, readonly cause?: unknown } = {}) {
+    super(options.message ?? `HTTP ${String(status)}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'HttpError'
+    this.status = status
+    this.response = options.response
+  }
+
+  /** The response this error stands for: the one it was given, or its message as plain text with its status. */
+  getResponse(): Response {
+    return this.response ?? new Response(this.message, { status: this.status, headers: { 'content-type': 'text/plain; charset=utf-8' } })
+  }
+}

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

@@ -0,0 +1,6 @@
+export { Router, Config, apply, name, type RouterHttpService } from './service.ts'
+export { RouteTable, type RouteTableOptions } from './table.ts'
+export { compose } from './compose.ts'
+export { HttpError } from './http-error.ts'
+export type { Registrar, RouteHandlers, UseArguments } from './registrar.ts'
+export type { ConnectionInfo, ErrorHandler, NotFoundHandler, ResponseBody, Handler, Method, Middleware, Next, RouteContext, RouteMethod, TrailingSlash } from './types.ts'

package/plugins/acryl-router/src/middleware/body-limit.ts

@@ -0,0 +1,25 @@
+import type { Middleware, RouteContext } from '../types.ts'
+
+export interface BodyLimitOptions {
+  readonly maxBytes: number
+  /** The response for a body that is too large. Defaults to a 413 with a small JSON body. */
+  readonly onError?: (c: RouteContext) => Response | Promise<Response>
+}
+
+/** The context key under which the limit is kept for the body-reading helpers. */
+export const BODY_LIMIT_KEY = 'bodyLimit'
+
+/**
+ * Refuse a request whose declared `content-length` is over the limit, and remember the limit so `readJson` and `readText` enforce it on the bytes
+ * they read (a chunked body declares no length). A request body is a stream: only the helpers, or a handler that counts, can stop it midway.
+ */
+export function bodyLimit(options: BodyLimitOptions): Middleware {
+  return async (c, next) => {
+    const declared = Number(c.req.headers.get('content-length'))
+    if (Number.isFinite(declared) && declared > options.maxBytes) {
+      return options.onError === undefined ? c.json({ error: 'payload too large', maxBytes: options.maxBytes }, 413) : options.onError(c)
+    }
+    c.set(BODY_LIMIT_KEY, options.maxBytes)
+    return next()
+  }
+}

package/plugins/acryl-router/src/middleware/cors.ts

@@ -0,0 +1,46 @@
+import type { Middleware } from '../types.ts'
+import { appendVary, setHeaders } from '../util.ts'
+
+export interface CorsOptions {
+  /** `'*'`, one origin, a list, or a function that returns the origin to allow (or `undefined` to refuse). */
+  readonly origin?: string | readonly string[] | ((origin: string) => string | undefined)
+  readonly allowMethods?: readonly string[]
+  readonly allowHeaders?: readonly string[]
+  readonly exposeHeaders?: readonly string[]
+  readonly maxAge?: number
+  readonly credentials?: boolean
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']
+
+/** Cross-origin resource sharing, with preflight answered here (a 204 that never reaches the route). */
+export function cors(options: CorsOptions = {}): Middleware {
+  const allowed = (origin: string): string | undefined => {
+    const rule = options.origin ?? '*'
+    if (typeof rule === 'function') return rule(origin)
+    if (typeof rule === 'string') return rule === '*' || rule === origin ? rule : undefined
+    return rule.includes(origin) ? origin : undefined
+  }
+  return async (c, next) => {
+    const origin = c.req.headers.get('origin')
+    const match = origin === null ? undefined : allowed(origin)
+    const shared: Record<string, string> = {}
+    if (match !== undefined) shared['access-control-allow-origin'] = match
+    if (options.credentials === true && match !== undefined) shared['access-control-allow-credentials'] = 'true'
+    if (options.exposeHeaders !== undefined && options.exposeHeaders.length > 0) shared['access-control-expose-headers'] = options.exposeHeaders.join(',')
+
+    if (c.req.method === 'OPTIONS' && c.req.headers.has('access-control-request-method')) {
+      const headers = { ...shared }
+      if (match !== undefined) {
+        headers['access-control-allow-methods'] = (options.allowMethods ?? DEFAULT_METHODS).join(',')
+        const requested = c.req.headers.get('access-control-request-headers')
+        const allowHeaders = options.allowHeaders ?? (requested === null ? [] : requested.split(',').map(part => part.trim()))
+        if (allowHeaders.length > 0) headers['access-control-allow-headers'] = allowHeaders.join(',')
+        if (options.maxAge !== undefined) headers['access-control-max-age'] = String(options.maxAge)
+      }
+      return appendVary(c.body(null, 204, headers), 'Origin')
+    }
+    const response = await next()
+    return appendVary(setHeaders(response, shared), 'Origin')
+  }
+}

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

@@ -0,0 +1,6 @@
+export { bodyLimit, BODY_LIMIT_KEY, type BodyLimitOptions } from './body-limit.ts'
+export { cors, type CorsOptions } from './cors.ts'
+export { logger, type LogSink } from './logger.ts'
+export { loopbackAuthority, loopbackOnly, sameOrigin, type LoopbackOptions } from './loopback-only.ts'
+export { requestId, type RequestIdOptions } from './request-id.ts'
+export { secureHeaders, type SecureHeadersOptions } from './secure-headers.ts'

package/plugins/acryl-router/src/middleware/logger.ts

@@ -0,0 +1,21 @@
+import type { Middleware } from '../types.ts'
+
+/** One line to a sink the caller owns, for example `line => ctx.logger.info(line)`. */
+export type LogSink = (line: string) => void
+
+/** Log each request on the way in and its status and time on the way out. The sink is required: a framework does not write to the console on its own. */
+export function logger(sink: LogSink): Middleware {
+  return async (c, next) => {
+    const label = `${c.req.method} ${c.url.pathname}`
+    sink(`<-- ${label}`)
+    const started = performance.now()
+    try {
+      const response = await next()
+      sink(`--> ${label} ${String(response.status)} ${String(Math.round(performance.now() - started))}ms`)
+      return response
+    } catch (error) {
+      sink(`--> ${label} threw ${error instanceof Error ? error.message : String(error)} ${String(Math.round(performance.now() - started))}ms`)
+      throw error
+    }
+  }
+}

package/plugins/acryl-router/src/middleware/loopback-only.ts

@@ -0,0 +1,82 @@
+import { BlockList, isIP } from 'node:net'
+import type { Middleware, RouteContext } from '../types.ts'
+
+export interface LoopbackOptions {
+  /** Hostnames a `Host` header may name. Default: the loopback names `127.0.0.1`, `localhost` and `[::1]`. */
+  readonly hostnames?: readonly string[]
+  /**
+   * What a request that changes things (not GET, HEAD or OPTIONS) must show: `same-origin` (default) refuses an `Origin` header that is not this same
+   * authority (including `null`), which stops another web page from driving a local app. A browser always sends `Origin` on a cross-origin change, so a
+   * request with no `Origin` (curl, a script) is allowed: the `Host` it names is already checked to be a loopback address with this server's port, which
+   * is what stops DNS rebinding. `none` checks only the peer and the `Host`.
+   */
+  readonly mutations?: 'same-origin' | 'none'
+  /**
+   * A call made inside the process (the terminal UI, a test) has no socket, so no peer to check. `deny` (default) refuses it, the safe choice for a route
+   * that guards something; `allow` lets it through for routes whose in-process caller is the host's own code. A request that came over a socket is always
+   * checked in full: only a call with no connection facts at all counts as in process.
+   */
+  readonly inProcess?: 'deny' | 'allow'
+}
+
+const loopback = new BlockList()
+loopback.addSubnet('127.0.0.0', 8, 'ipv4')
+loopback.addSubnet('::1', 128, 'ipv6')
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * The authority a loopback request addressed: the `Host` header as a URL, or `undefined` when the request does not come from a loopback peer to the
+ * real local port, names another host, or is marked cross-site by the browser. The peer and the port come from the transport (`c.connection`), never
+ * from a header; an in-process call has neither and is refused.
+ */
+export const LOOPBACK_HOSTNAMES: readonly string[] = ['127.0.0.1', 'localhost', '[::1]']
+
+export function loopbackAuthority(c: RouteContext, hostnames: readonly string[] = LOOPBACK_HOSTNAMES): URL | undefined {
+  const { remoteAddress, localPort } = c.connection
+  const host = c.req.headers.get('host')
+  if (remoteAddress === undefined || localPort === undefined || host === null) return undefined
+  const address = (remoteAddress.replace(/^\[|\]$/gu, '').split('%', 1)[0] ?? '').replace(/^::ffff:/iu, '')
+  const family = isIP(address)
+  if (family === 0 || !loopback.check(address, family === 4 ? 'ipv4' : 'ipv6')) return undefined
+  let authority: URL
+  try {
+    authority = new URL(`http://${host}`)
+  } catch {
+    return undefined
+  }
+  if (
+    authority.protocol !== 'http:'
+    || Number(authority.port || '80') !== localPort
+    || !hostnames.includes(authority.hostname)
+    || c.req.headers.get('sec-fetch-site') === 'cross-site'
+  ) return undefined
+  return authority
+}
+
+/** Whether a changing request is acceptable by its `Origin`: absent (not a browser cross-origin change) or naming this same authority. `null` and any other origin are not. */
+export function sameOrigin(c: RouteContext, authority: URL): boolean {
+  const origin = c.req.headers.get('origin')
+  if (origin === null) return true
+  try {
+    const parsed = new URL(origin)
+    return parsed.protocol === 'http:' && parsed.host === authority.host && parsed.pathname === '/'
+  } catch {
+    return false
+  }
+}
+
+/** Only requests from this machine to this app: loopback peer, the real port, an allowed `Host`, and for mutations a matching `Origin`. Everything else gets a 403. */
+export function loopbackOnly(options: LoopbackOptions = {}): Middleware {
+  const mutations = options.mutations ?? 'same-origin'
+  const inProcess = options.inProcess ?? 'deny'
+  return async (c, next) => {
+    if (inProcess === 'allow' && c.connection.remoteAddress === undefined && c.connection.localPort === undefined) return next()
+    const authority = loopbackAuthority(c, options.hostnames)
+    if (authority === undefined) return c.json({ error: 'request authority rejected' }, 403)
+    if (mutations === 'same-origin' && !SAFE_METHODS.has(c.req.method) && !sameOrigin(c, authority)) {
+      return c.json({ error: 'a change must come from this app\'s own origin' }, 403)
+    }
+    return next()
+  }
+}