acrylblends 0.3.0 → 0.4.1

package/docs/framework/migration-from-0-3.md

@@ -0,0 +1,108 @@
+# Migration from 0.3
+
+0.3.0 had the framework's own small router API: routes registered one at a time on `ctx.router`, and a `RouteContext` with a few
+helpers. 0.4.0 replaces it with the ported application API: a plugin builds an `App` and mounts it. The old calls are removed, not kept
+as aliases, so there is one way to write a route.
+
+## Before and after
+
+0.3.0:
+
+```ts
+import { HttpError } from 'acryl-router'
+import { readJson, streamSSE, valid, validate } from 'acryl-router/helpers'
+import { bodyLimit } from 'acryl-router/middleware'
+
+export function apply(ctx: Context): void {
+  const api = ctx.router.group('/todo')
+  api.use(bodyLimit({ maxBytes: 16 * 1024 }))
+  api.get('/todos/:id', c => {
+    const todo = find(c.param('id'))
+    if (!todo) throw new HttpError(404, { message: 'no such todo' })
+    return c.json(todo)
+  })
+  api.post('/todos', validate('json', NewTodo), c => c.json(create(valid(c, 'json')), 201))
+  api.get('/events', c => streamSSE(c, stream => {
+    const off = events.on('change', todo => stream.send(todo, { event: 'change' }))
+    return off
+  }))
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+0.4.0:
+
+```ts
+import { App, HTTPException } from 'acryl-router'
+import { schemaValidator, streamSSE } from 'acryl-router/helpers'
+import { bodyLimit } from 'acryl-router/middleware'
+
+export function apply(ctx: Context): void {
+  const app = new App()
+    .use(bodyLimit({ maxSize: 16 * 1024 }))
+    .get('/todos/:id', c => {
+      const todo = find(c.req.param('id'))
+      if (!todo) throw new HTTPException(404, { message: 'no such todo' })
+      return c.json(todo)
+    })
+    .post('/todos', schemaValidator('json', NewTodo), c => c.json(create(c.req.valid('json')), 201))
+    .get('/events', c => streamSSE(c, async stream => {
+      const off = events.on('change', todo => { void stream.writeSSE({ event: 'change', data: JSON.stringify(todo) }) })
+      stream.onAbort(off)
+      while (!stream.aborted) await stream.sleep(15_000).then(() => stream.write(': keep-alive\n\n'))
+    }))
+
+  ctx.router.route('/todo', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+Public paths do not change: the mount path plus the app's route path is the old group prefix plus the old route path.
+
+## What maps to what
+
+| 0.3.0 | 0.4.0 |
+| --- | --- |
+| `ctx.router.get/post/put/patch/delete/all/on(path, ...)` | the same methods on an `App`, then `ctx.router.route(prefix, app)` |
+| `ctx.router.use(...)` | `app.use(...)` on the app it should wrap (or on an app mounted earlier, for a guard in front of other plugins) |
+| `ctx.router.group(prefix, ...middleware)` | one `App` per group mounted at `prefix`, or `app.route(prefix, sub)` / `app.basePath(prefix)` |
+| the remover each registration returned | the one remover `ctx.router.route` returns; the mount is owned by the calling plugin as before |
+| `ctx.router.onError`, `ctx.router.notFound` | unchanged; an app's own `app.onError` now also applies to its routes |
+| `c.param(name)`, `c.params` | `c.req.param(name)`, `c.req.param()` |
+| `c.query(name)`, `c.query()` | `c.req.query(name)`, `c.req.query()` (and `c.req.queries(name)` for repeated values) |
+| `c.url` | `new URL(c.req.url)`, or `c.req.path` |
+| `c.req` (the Web `Request`) | `c.req.raw`; `c.req` is now the request wrapper |
+| `c.connection` | `connectionOf(c)` (or `getConnInfo(c)`); type the app `new App<RouterEnv>()` to read `c.env.connection` |
+| `c.signal` | `c.req.raw.signal` |
+| `c.waitUntil(task)` | `c.executionCtx.waitUntil(task)` |
+| `c.get(key)` / `c.set(key, value)` | unchanged, typed by the app's `Variables` (`c.var.key` also works) |
+| `c.json/text/html/body/redirect/notFound/header/status` | unchanged |
+| `HttpError(status, { message, response, cause })` | `HTTPException(status, { message, res, cause })` |
+| `readJson(c)`, `readText(c)`, `readBytes(c)` with `{ maxBytes }` | `bodyLimit({ maxSize })` in front, then `c.req.json()`, `c.req.text()`, `c.req.arrayBuffer()` |
+| `bodyLimit({ maxBytes })` | `bodyLimit({ maxSize })` |
+| `validate(target, schema)` and `valid(c, target)` | `schemaValidator(target, schema)` and `c.req.valid(target)`, with more targets (`form`, `header`, `cookie`) |
+| `streamSSE(c, stream => cleanup)` with `stream.send(data, { event, id })` | `streamSSE(c, async stream => ...)` with `stream.writeSSE({ data, event, id })`; `data` is a string, so `JSON.stringify` objects |
+| the SSE stream's automatic keep-alive comment | none: write a comment on a timer when a proxy closes idle connections |
+| the cleanup function `run` returned | `stream.onAbort(cleanup)`; the callback's end closes the stream |
+| a 405 with `Allow` for a known path and another method | 404 by default; add the `methodNotAllowed` middleware for 405 |
+| the `Middleware` type, `(c, next) => Response` | `MiddlewareHandler`, `async (c, next) => { await next() }`; change `c.res` after `next()` instead of returning it |
+| `logger`, `cors`, `requestId`, `secureHeaders`, `loopbackOnly` | same names in `acryl-router/middleware`; the first four now take the core's options |
+
+## Behavior changes to check
+
+- **A mount is a snapshot.** Routes an app registers after `ctx.router.route(...)` are not served. 0.3.0 registered each call live.
+- **A JSON validator needs a JSON `Content-Type`.** Without it the schema sees `{}`. 0.3.0 read the body whatever its type.
+- **`await next()` does not throw.** A thrown error has already become a response; read it from `c.error`.
+- **Trailing slashes are strict by default, as before**, and `trailingSlash: 'ignore'` still treats `/a` and `/a/` as one path.
+- **Disposal is unchanged:** a plugin's unload ends the requests and streams its code is serving, and router disposal ends all of them,
+  bounded by `disposeGraceMs`.
+
+## Checklist
+
+For each plugin:
+
+- collect its route registrations into one app per mount path and keep the public paths;
+- move middleware and error handling onto the owning app;
+- replace the context and helper calls from the table above;
+- run its route tests, then one activation test that unloads and reloads the plugin;
+- leave no 0.3.0-style calls behind: the old API is gone, and two styles would give new code a second API to copy.

package/docs/framework/migration-from-dsh-webserver.md

@@ -0,0 +1,103 @@
+# Migration from the DSH webServer
+
+ACRYL plugins have registered HTTP routes directly with the DSH `webServer` (or the Host's `acrylWeb` wrapper of it): one Node-style handler
+per exact path or prefix, with no middleware chain. The framework replaces that with an `App`, a mount, and Web-standard requests.
+
+## Before and after
+
+Before, a plugin claims a path and writes the Node response itself:
+
+```ts
+export function apply(ctx: Context): void {
+  ctx.effect(() => ctx.acrylWeb.register({
+    kind: 'exact',
+    path: '/api/health',
+    handler: (req, res) => {
+      res.statusCode = 200
+      res.setHeader('content-type', 'application/json')
+      res.end(JSON.stringify({ ok: true }))
+    },
+  }))
+}
+```
+
+After, it builds an app, mounts it, and asks the Host adapter to serve the prefix:
+
+```ts
+import { App } from 'acryl-router'
+
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  const app = new App().get('/health', c => c.json({ ok: true }))
+  ctx.router.route('/api', app)
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/health') })
+}
+```
+
+`routerHttp.mount(prefix)` claims the prefix on the same web server, so the public path does not change. The terminal UI and tests reach
+the route in process (`ctx.router.request('/api/health')`), which the old handler never allowed.
+
+## What maps to what
+
+| webServer | Framework |
+| --- | --- |
+| `register({ kind: 'exact', path, handler })` | a route on an `App`, mounted with `ctx.router.route`; served with `routerHttp.mount(path)` |
+| `register({ kind: 'prefix', path, handler })` | an `App` mounted at `path` with its own routes below it |
+| `req.method` checks in the handler | `app.get`, `app.post`, ... (add `methodNotAllowed` for 405 answers) |
+| `new URL(req.url, ...)` and manual parsing | `c.req.param`, `c.req.query`, `c.req.header` |
+| reading the body stream by hand | `c.req.json()`, `c.req.parseBody()` behind `bodyLimit`, or a validator |
+| `res.statusCode`, `res.setHeader`, `res.end` | `c.json`, `c.text`, `c.body`, `c.header`, or a returned `Response` |
+| `req.socket.remoteAddress` | `connectionOf(c)` / `getConnInfo(c)` |
+| a peer or origin check copied into each handler | `loopbackOnly`, `cors`, `csrf` or a middleware of your own |
+| the disposer returned by `register` | nothing: `route` and `mount` belong to the calling plugin |
+
+## Migration steps
+
+Move one capability at a time:
+
+1. Build an `App` for the capability and move its handlers into it without changing their public answers.
+2. Mount it with `ctx.router.route` and serve the same prefix with `routerHttp.mount`.
+3. Remove the direct `webServer` registration in the same change: the two cannot claim one prefix, `mount` throws.
+4. Test the route through the router (`ctx.router.request`) and over the Host, and unload and reload the plugin to confirm the route goes
+   away and comes back once.
+
+Keep domain calls unchanged until the transport change is green; do not rewrite transport, handlers and authorization in one step.
+
+## A worked example: the workspace
+
+`acryl-workspace` (files, git, terminals, projects, agents) was the largest user of the webServer: 24 exact routes. It now builds one app
+per domain folder (`filesRoutes`, `gitRoutes`, `ptyRoutes`, ...), composes them once (`privateApi` in `src/private-route.ts`), mounts the
+result after the effect that builds its services, and serves the one prefix `/api/acryl-workspace`:
+
+```ts
+const built: { api?: App } = {}
+ctx.effect(() => {
+  // ... the PTY table, git, files, the project registry ...
+  built.api = privateApi(filesRoutes(files, report), gitRoutes(git, report) /* , ... */)
+  return async () => { /* release them */ }
+})
+ctx.router.route('/', built.api)
+ctx.routerHttp.mount('/api/acryl-workspace')
+```
+
+Mounting after the effect orders the unload: the mount goes first, so the requests and event streams its code is serving end and are
+waited for, then the services are released. Each route names its guard (`loopbackOnly({ callers: 'own-page' })` for the page, a bearer token
+for the agent hooks) and its body limit; the event stream is `streamSSE`, and its keep-alive is one timer the plugin owns, not one per
+request. The terminal's WebSocket stays a webServer upgrade until the router carries upgrades (spec 047 T009).
+
+The answers that changed are recorded with it: a body over a route's limit is 413 on every route (some said 400); a wrong method is 405 with
+an `Allow` header on every route; a missing or wrong agent-hook token is 401 with `WWW-Authenticate` (it was 403); and the hook's `Host`
+must be the app's own loopback address. Its routes refuse an in-process call on purpose (the guard needs a socket to check), so its tests
+run over loopback through the same adapter (`tests/serve-api.ts`), which is the "test over the Host" below.
+
+## Completion check
+
+A capability is migrated when:
+
+- no handler in it touches Node `req` / `res` objects or the old server types;
+- its public paths and answers are unchanged, or the changes are recorded;
+- it unloads and reloads without duplicate or missing routes;
+- the same handler passes an in-process test and a test over the Host.
+
+Typed RPC stays a separate concern. Do not convert RPC methods because their names look like HTTP routes.

package/docs/framework/node-server.md

@@ -0,0 +1,75 @@
+# Node server
+
+`acryl-node-server` serves the whole router over HTTP from a standalone Node.js process. Use it for an app that runs without the ACRYL
+Host. Inside the Host (Web and Desktop), the Host owns the web server and a plugin asks `acryl-router-http` to serve its prefix instead.
+
+## Serve the router
+
+The server is a Cordis plugin that provides the `nodeServer` service:
+
+```ts
+import { Context } from '@deepseek-ai/cordis'
+import * as router from 'acryl-router'
+import * as nodeServer from 'acryl-node-server'
+import * as todo from './todo.ts'
+
+const root = new Context()
+root.plugin(router)
+root.plugin(nodeServer, { port: 3000 })
+root.plugin(todo)
+
+root.inject(['nodeServer'], ctx => {
+  console.log(`listening on ${ctx.nodeServer.url}`)
+})
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `hostname` | `127.0.0.1` | address to bind; binding elsewhere exposes the app to the network |
+| `port` | `0` | port to listen on; 0 lets the system choose |
+| `scan` | `20` | how many further ports to try when the configured one is taken |
+
+The plugin becomes active once the server listens, so a plugin that injects `nodeServer` can rely on `ctx.nodeServer.url` and
+`ctx.nodeServer.port`. A failure to bind fails the plugin.
+
+Every request goes to `ctx.router.fetch`, so routes appear and disappear as plugins mount and unload, with no restart. A plugin's
+`ctx.inject(['routerHttp'], ...)` call never fires here: this adapter serves every prefix already.
+
+## Connection information
+
+The adapter passes the socket's peer address and local port to the router as connection facts. Handlers read them through
+`connectionOf(c)` or `getConnInfo(c)` and never touch Node socket objects, so the same handler runs in process and through the Host. See
+[Context](./context.md#transport-facts).
+
+## Static files
+
+The Node `serveStatic` reads files from disk:
+
+```ts
+import { serveStatic } from 'acryl-node-server'
+
+const app = new App()
+  .use('/assets/*', serveStatic({ root: './public' }))
+  .get('/', serveStatic({ path: './public/index.html' }))
+```
+
+`root` is joined with the request path, relative to the working directory unless absolute. A request path with a `.` or `..` segment, a
+doubled slash, a backslash or (unless `allowPercentInPath`) an encoded `%` is treated as not found and passed on with `next()`. Only `GET`
+and `HEAD` are served. Other options: `rewriteRequestPath`, `precompressed` (serve a `.br`, `.zst` or `.gz` sibling when the client
+accepts it), `index` (default `index.html`), and `onFound` / `onNotFound` hooks. Serve build output, never source folders.
+
+## Shutdown
+
+Disposing the plugin (or the root context) ends open streams, closes every connection and returns once the port is free. Disposing a
+plugin that only mounted routes is different: its mount and the requests it is serving end, and the server keeps serving the others (see
+[Plugin lifecycle](./plugin-lifecycle.md#disposal-sequence)).
+
+## Choosing a port
+
+Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
+leaves the socket to whichever adapter the app runs with.
+
+## Not yet supported
+
+WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
+not wired to the router yet.

package/docs/framework/plugin-lifecycle.md

@@ -0,0 +1,111 @@
+# Plugin lifecycle and disposal
+
+Cordis gives every framework registration an owner and a lifetime. This is the main difference between using the application API on its
+own and using it as part of ACRYL.
+
+## Every registration has an owner
+
+```ts
+export const name = 'todo'
+export const inject = ['router']
+
+export function apply(ctx: Context): void {
+  ctx.router.route('/todo', createTodoApp())
+}
+```
+
+`route`, `onError` and `notFound` register themselves as effects of the plugin that called them, so there is nothing to wrap: when the
+plugin's fiber unloads, its mount goes away, and a reload mounts it again without duplicates. `route` returns a function that removes the
+mount sooner. Never register routes as a side effect of importing a module.
+
+Resources an app uses (timers, watchers, connections, subprocesses) belong to one `ctx.effect()` of the plugin, whose disposer releases
+them:
+
+```ts
+export function apply(ctx: Context): void {
+  const events = new EventEmitter()
+  ctx.effect(() => {
+    const timer = setInterval(() => events.emit('tick'), 1000)
+    return () => clearInterval(timer)
+  }, 'todo: ticker')
+  ctx.router.route('/todo', createTodoApp(events))
+}
+```
+
+## Live composition
+
+The router is built for a host whose plugin set changes while it runs. Mounts are added and removed, and each request after a change is
+served by an app composed from the mounts that are live at that time; a request already running keeps the app it started with. The core's
+route tables only grow, so the router rebuilds the composition instead of editing it. Application code does not manage this.
+
+A mount is a snapshot of the app's routes at the `route` call. Build the app, then mount it.
+
+## Missing providers
+
+A plugin that injects `router` stays PENDING while no router exists. That is a normal Cordis state, not an error: when a router appears the
+plugin activates and mounts. When the router is replaced, the plugin unloads and activates again against the new one, so it must not keep
+the old service object anywhere else.
+
+## Disposal sequence
+
+When a plugin that owns a mount unloads:
+
+1. The mount leaves the composition, so new requests no longer reach it.
+2. The requests its code is still serving end: a request inside one of its handlers or middleware (before `next()` returned), and a
+   response body one of its handlers produced. Their signals abort (`c.req.raw.signal`) and their bodies are cancelled, which runs the
+   stream helpers' `onAbort`.
+3. The unload waits for those requests, their bodies and their `c.executionCtx.waitUntil` work, bounded by the router's `disposeGraceMs`.
+
+A request the plugin's middleware already passed on to another plugin's handler is not touched. When the router itself is disposed, the
+same happens to every running request, and new requests are answered with 503.
+
+Handlers get a chance to release their resources, nothing a plugin started outlives it, and disposal cannot hang forever.
+
+## Services and the shadow context
+
+A plugin reaches a service through its own view of it: `ctx.router` in one plugin and in another are two different objects over one
+service. Two facts follow, each with a test as proof.
+
+**Fields are shared.** Reading or assigning a service's field through any plugin's view reads or writes the one instance, so every caller
+sees the same value (`plugins/acryl-router/tests/shadow-state.spec.ts`). Keeping changing state in one object, as the router does, is a
+readability choice, not a requirement.
+
+**`this.ctx` inside a method is the caller's view, not the service's own context.** It is what lets `route` tie a mount to the plugin
+that called it. It is the wrong context for starting something that should belong to the service: a plugin started with
+`this.ctx.plugin(...)` from a method resolves services as the service's own fiber and fails with "cannot get property router without
+inject". Keep the context the constructor received and use that:
+
+```ts
+class Installer extends Service {
+  private readonly owner: Context
+
+  constructor(ctx: Context) {
+    super(ctx, 'installer')
+    this.owner = ctx                  // the service's own context
+  }
+
+  async install(plugin: Plugin): Promise<void> {
+    await this.owner.plugin(plugin)   // right: behaves like a plugin mounted at startup
+    // await this.ctx.plugin(plugin)  // wrong: the caller's view, see above
+  }
+}
+```
+
+The proof is `plugins/acryl-router/tests/live-install.spec.ts`, which runs both forms against a live router. This sits next to the general
+rule: a plugin started with `this.ctx.plugin(...)` in `apply` is a child of the plugin and unloads with it.
+
+## Module state
+
+Do not hide mutable state in module globals. Cordis can reload a plugin and run several surfaces from one host, and a module global
+outlives the plugin that wrote it.
+
+## What to test
+
+Test a route-owning plugin through real Cordis activation for:
+
+- activation when the router is present, and PENDING until it appears;
+- route removal after the plugin unloads, and a clean mount after reload, without duplicates over repeated cycles;
+- router replacement without stale service references;
+- disposal while a response is still open.
+
+`app.request` tests prove handler behavior. Only activation tests prove ownership.

package/docs/framework/request.md

@@ -0,0 +1,106 @@
+# Request
+
+Handlers read input through `c.req`, a thin wrapper around the Web `Request`. The original is `c.req.raw`.
+
+## Route parameters
+
+```ts
+app.get('/entry/:id', c => {
+  const id = c.req.param('id')
+  return c.json({ id })
+})
+
+app.get('/entry/:id/comment/:commentId', c => {
+  const { id, commentId } = c.req.param()
+  return c.json({ id, commentId })
+})
+```
+
+Named reads keep route contracts visible; read the whole map only when a generic logger or adapter needs it.
+
+## Query strings
+
+```ts
+const page = c.req.query('page')     // one value
+const all = c.req.query()            // every parameter, first value of each
+const tags = c.req.queries('tag')    // repeated values: ?tag=work&tag=home
+```
+
+Convert strings to numbers, booleans or dates at the application boundary and reject invalid values explicitly; a validator does both
+(see [Validation](./validation.md)).
+
+## Headers
+
+```ts
+const requestId = c.req.header('X-Request-Id')
+const headers = c.req.header()        // every header, keys in lowercase
+```
+
+Header names are case-insensitive for a named read. With no argument the record's keys are lowercase, so `c.req.header()['X-Foo']` is
+always undefined; read `c.req.header('X-Foo')` instead. Optional headers need a deliberate fallback; do not let a missing authentication
+header silently become an anonymous request unless that is the declared behavior.
+
+## Bodies
+
+```ts
+app.post('/entry', async c => {
+  const body = await c.req.json()       // application/json
+  return c.json({ received: body }, 201)
+})
+
+await c.req.text()
+await c.req.arrayBuffer()
+await c.req.blob()
+await c.req.formData()
+await c.req.parseBody()                 // multipart/form-data or application/x-www-form-urlencoded
+```
+
+The reads are cached, so a validator and the handler can both read the body. Read untrusted bodies behind `bodyLimit`, which refuses a body
+over the limit with 413 while it streams instead of after buffering it.
+
+### Forms and uploads
+
+`parseBody()` returns `string | File` per field; the last one wins when a name repeats:
+
+```ts
+const body = await c.req.parseBody()
+body['file']                                       // string | File
+const many = await c.req.parseBody({ all: true })  // repeated names become arrays
+many['files']                                      // (string | File)[] when several were sent
+const nested = await c.req.parseBody({ dot: true }) // obj.key1 -> { obj: { key1 } }
+```
+
+A field named with a `[]` suffix (`files[]`) is always an array. Treat every uploaded file as untrusted: check its type, size and
+destination, and never use a caller-provided filename as a filesystem path without normalizing it and confining it to the intended
+directory.
+
+## Validated input
+
+`c.req.valid(target)` returns what a validator for `json`, `form`, `query`, `header`, `cookie` or `param` produced, typed by it. See
+[Validation](./validation.md).
+
+## Method, path and URL
+
+```ts
+c.req.method   // 'GET'
+c.req.path     // '/about/me'
+c.req.url      // 'http://127.0.0.1:3290/about/me'
+```
+
+Do not parse the URL by hand to recover route parameters or query values the router already exposes. `routePath(c)` and
+`matchedRoutes(c)` from `acryl-router/helpers` give the registered path and the routes that matched.
+
+## Raw Web Request
+
+```ts
+const raw = c.req.raw
+const url = new URL(raw.url)
+```
+
+Use the raw object for standards-based libraries, streaming bodies and signatures over the exact payload. Use `c.req` for normal
+application code.
+
+## Request cancellation
+
+`c.req.raw.signal` aborts when the client goes away, when the plugin serving the request unloads and when the router is
+disposed. Work that ignores it can outlive the plugin that owns it; see [Context](./context.md#cancellation-and-background-work).