acrylblends 0.3.0 → 0.4.1

package/docs/framework/concepts.md

@@ -0,0 +1,105 @@
+# Core concepts
+
+The framework's request-handling model is designed so every extension point belongs to a Cordis plugin. This page explains the pieces
+before the API reference.
+
+## App
+
+An `App` is a self-contained ACRYL application. It owns:
+
+- routes;
+- middleware;
+- an error handler (`app.onError`);
+- a request entry point (`app.fetch`, and `app.request` for tests);
+- sub-applications placed below a path with `app.route(path, sub)`.
+
+An app can be tested without a server:
+
+```ts
+const response = await app.request('/todos/42')
+```
+
+An app is not itself a Cordis service. That separation lets the same app be mounted by different hosts, at different paths, or not
+mounted at all.
+
+## Router service
+
+The Cordis `router` service (`ctx.router`, provided by `acryl-router`) composes the mounted apps into one route space. A plugin builds an
+app and mounts it:
+
+```ts
+ctx.router.route('/todo', app)
+```
+
+The mount copies the app's routes at that call. When any mount is added or removed, the next request composes a fresh app from the mounts
+that are live, in the order they were made; requests already running keep the app they started with. This matches Cordis: plugins can
+load, unload, reload and be replaced while the host stays up. The core's route tables are add-only, so rebuilding is the only correct way
+to remove a route; it costs about 1 ms per 1000 routes, once per change.
+
+The router also takes one router-wide `onError` and one `notFound` (each owned by the plugin that set it), and runs requests in process:
+`ctx.router.fetch(request, connection?)` and `ctx.router.request(path, init?, connection?)`.
+
+## Handler
+
+A handler receives one context object, conventionally named `c`:
+
+```ts
+app.get('/todos/:id', c => {
+  return c.json({ id: c.req.param('id') })
+})
+```
+
+Handlers return a Web `Response`, either directly or through context helpers such as `c.text`, `c.json` and `c.html`.
+
+## Middleware
+
+Middleware wraps handlers and other middleware:
+
+```ts
+app.use('/admin/*', async (c, next) => {
+  if (!isAllowed(c)) return c.text('Forbidden', 403)
+  await next()
+})
+```
+
+Code before `await next()` runs on the way in. Code after it can inspect or change the response (`c.res`) on the way out.
+
+## Surface
+
+A surface is the place a person or another program uses the application:
+
+| Surface | Transport |
+| --- | --- |
+| Web | the ACRYL Host's web server, through `acryl-router-http` |
+| Desktop | the same: the Electron window talks to the app's own loopback web server |
+| Terminal UI | in process: `ctx.router.request(...)`, no server |
+| A standalone process | `acryl-node-server` serves the whole router |
+| Tests | `ctx.router.request(...)` or `app.request(...)` |
+
+Surfaces share capabilities and contracts. They do not need to share a transport or a user interface.
+
+## Plugin contract
+
+Following the ACRYL framework rules, a plugin declares what it:
+
+- provides as services;
+- requires through injection;
+- registers as routes, commands, tools or interface slots;
+- owns until disposal.
+
+The declaration is what lets tooling answer two questions without reading all the code: what does this plugin do, and what disappears
+when it unloads? `acryl-inspect` reads it from the running system: each mount is labeled with its path and has one labeled child per route it serves.
+
+## State
+
+Request state belongs to the context. Application state shared between surfaces belongs in `acryl-state` or an application-owned Cordis
+service. Do not hide shared mutable state in module globals: Cordis can reload plugins and run several surfaces from one host, and a
+module global outlives the plugin that wrote it.
+
+## Design rules
+
+1. Everything extensible is a Cordis plugin.
+2. One application can serve several surfaces.
+3. Each plugin has one declared contract.
+4. Every registration is reversible.
+5. Normal application code should not need runtime internals.

package/docs/framework/context.md

@@ -0,0 +1,129 @@
+# Context
+
+Every handler and middleware receives a context, normally named `c`. The context connects the current request, the response being built,
+route data, transport information and work that must finish after the response. It lives for one request.
+
+## Return a response
+
+```ts
+app.get('/text', c => c.text('Hello'))
+app.get('/json', c => c.json({ ok: true }))
+app.get('/html', c => c.html('<h1>Hello</h1>'))
+app.get('/empty', c => c.body(null, 204))
+app.get('/raw', () => new Response('Good morning!'))
+app.get('/notfound', c => c.notFound())
+app.get('/redirect', c => c.redirect('/'))              // 302
+app.get('/moved', c => c.redirect('/', 301))
+```
+
+Set the status and headers before or with the body:
+
+```ts
+app.post('/posts', c => {
+  c.status(201)
+  c.header('X-Message', 'created')
+  return c.json({ created: true })
+})
+
+app.get('/welcome', c => c.body('Thank you for coming', 201, { 'X-Message': 'Hello!', 'Content-Type': 'text/plain' }))
+```
+
+## The response on the way out
+
+Middleware can read or replace the response after `next()`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  c.res.headers.append('X-Debug', 'Debug message')
+})
+```
+
+## Read request data
+
+The request object is `c.req`:
+
+```ts
+const id = c.req.param('id')
+const search = c.req.query('q')
+const agent = c.req.header('User-Agent')
+```
+
+See [Request](./request.md) for bodies, repeated values and validated input.
+
+## Store request-local values
+
+`c.set` and `c.get` (or `c.var.name`) pass data from middleware to handlers. Declare the variables as the app's type parameter so both
+sides agree:
+
+```ts
+const app = new App<{ Variables: { requestId: string } }>()
+
+app.use(async (c, next) => {
+  c.set('requestId', crypto.randomUUID())
+  await next()
+})
+
+app.get('/', c => c.text(c.get('requestId')))
+```
+
+These values live only for the current request. Do not use them as a cache or as application state. `createMiddleware` (from
+`acryl-router/helpers`) types a middleware that sets variables, and chained `.use(...)` calls accumulate their types; see
+[Middleware](./middleware.md).
+
+## Transport facts
+
+`c.env` carries what the caller of the router supplied for this request. Under the router that is `{ connection }`: the socket's peer
+address and the real local port, filled by the HTTP adapter and empty for an in-process call. Transport facts never travel in headers.
+
+```ts
+import { App, connectionOf, type RouterEnv } from 'acryl-router'
+import { getConnInfo } from 'acryl-router/helpers'
+
+const app = new App<RouterEnv>()   // types c.env.connection
+app.get('/peer', c => c.json({
+  connection: connectionOf(c),     // { remoteAddress?, localPort? }
+  info: getConnInfo(c),            // the same peer in the core's conninfo shape, for middleware such as ipRestriction
+}))
+```
+
+The same handler then runs over HTTP, in process or in a test, and reads an empty connection where there is no socket. Guards such as
+`loopbackOnly` refuse an empty one unless told otherwise.
+
+## Cancellation and background work
+
+- `c.req.raw.signal` aborts when the caller goes away, when the plugin whose code is serving the request unloads, and when the router is
+  disposed. Long work
+  should pass it on (`fetch(url, { signal: c.req.raw.signal })`) or check it.
+- `c.executionCtx.waitUntil(promise)` keeps the request in flight until the promise settles, for work that continues after the response
+  is returned.
+
+Both belong to the current request, and both end with their owner: see [Plugin lifecycle](./plugin-lifecycle.md#disposal-sequence).
+
+## Errors and control flow
+
+Return a response for expected failures, or throw an `HTTPException`, which becomes its own response:
+
+```ts
+import { HTTPException } from 'acryl-router'
+
+if (!todo) return c.json({ error: 'todo_not_found' }, 404)
+if (!allowed) throw new HTTPException(403, { message: 'not yours' })
+```
+
+Anything else that is thrown goes to the app's `onError`, or to the router's when the app has none. A middleware's `await next()` never
+throws: the error has already become a response by then, and the error itself is in `c.error`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  if (c.error) report(c.error)
+})
+```
+
+## Context rules
+
+- Treat the context as request-local.
+- Do not retain it after the handler returns.
+- Do not put sockets, server objects or Cordis internals into context values for other plugins to discover accidentally.
+- Put cross-plugin capabilities in a declared Cordis service, not in `c.set`.

package/docs/framework/getting-started.md

@@ -0,0 +1,146 @@
+# Getting started
+
+The ACRYL Framework puts its application model inside Cordis. You build an ordinary `App`, register routes and middleware on it, then
+mount that app from a Cordis plugin.
+
+## The mental model
+
+There are two layers:
+
+1. **Application layer** - `App`, handlers, middleware, context, requests, responses, validation and helpers. This is the ACRYL
+   application API.
+2. **Cordis layer** - plugins, services, injection, effects and disposal. This decides when an application exists and which surface can
+   reach it.
+
+A route therefore has two owners. The `App` owns the route table. The plugin that mounted the app owns the mount for as long as its
+Cordis fiber is active.
+
+## A minimal plugin
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import { App } from 'acryl-router'
+
+export const name = 'todo'           // equals the package name and the Loader row id
+export const inject = ['router']     // PENDING until a router exists
+
+export function apply(ctx: Context): void {
+  const app = new App()
+    .get('/', c => c.json({ ok: true }))
+    .get('/todos/:id', c => c.json({ id: c.req.param('id') }))
+
+  ctx.router.route('/todo', app)
+  // Over HTTP only where the Host's adapter exists; the terminal UI and tests have no such service and skip this.
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}
+```
+
+`ctx.router.route('/todo', app)` serves the app below `/todo`:
+
+| Request | Answer |
+| --- | --- |
+| `GET /todo` | `{ "ok": true }` |
+| `GET /todo/todos/42` | `{ "id": "42" }` |
+| `GET /todo/` | 404: `/todo` and `/todo/` are different paths (see below) |
+
+### `/todo/` is a 404 until you choose
+
+`/todo/` is the first thing people type, and by default it is not found: the router treats `/todo` and `/todo/` as two paths. Choose
+one of these, in this order of preference:
+
+- **Redirect in your app** (what `examples/acryl-todo` does): add `trimTrailingSlash()` from `acryl-router/middleware` to the app.
+  A GET or HEAD that would be a 404 and ends in `/` gets a 301 to the same path without it, so `/todo/` reaches the page and every
+  route keeps one canonical path. Other methods are not redirected: `POST /todo/api/` stays a 404.
+
+  ```ts
+  import { trimTrailingSlash } from 'acryl-router/middleware'
+
+  const app = new App()
+    .use(trimTrailingSlash())
+    .get('/', c => c.json({ ok: true }))
+  ```
+
+- **One path everywhere**: the `acryl-router` row's config `trailingSlash: 'ignore'` makes `/a` and `/a/` the same path for every
+  mounted app, with no redirect. It is the app's composition that sets it (the Blueprint or profile that owns the router row), not one
+  plugin, because it changes every other plugin's routes too.
+
+`new App({ strict: false })` does not help once the app is mounted: the router composes every mount into its own root app, and only the
+router's `trailingSlash` setting decides. `strict: false` applies to an `App` you serve yourself (`app.fetch`, `app.request`). Details
+and a measured table: [Routing and mounting](./routing.md#trailing-slashes).
+
+The mount belongs to the plugin that made it: `route` registers it as a Cordis effect of the caller, so when the plugin unloads the
+routes disappear, and a reload mounts the app again without duplicating routes. `route` also returns a function that removes the mount
+sooner.
+
+Finish building the app before you mount it: the router copies the app's routes at the `route` call, as the core's own `app.route` does.
+
+## Add middleware
+
+Middleware is registered on the app before the routes it should wrap:
+
+```ts
+const app = new App()
+  .use(async (c, next) => {
+    const started = Date.now()
+    await next()
+    c.header('X-Response-Time', String(Date.now() - started))
+  })
+  .get('/', c => c.json({ ok: true }))
+```
+
+Use middleware for authentication, logging, CORS, compression, request IDs and other behavior that should wrap more than one handler.
+The built-in set is listed in [Middleware](./middleware.md).
+
+## Run the same app on a surface
+
+The application does not open a socket. A surface supplies requests to it:
+
+- **Web** and **Desktop**: the Host's web server, through `acryl-router-http` (`routerHttp.mount(prefix)`).
+- **Terminal UI**: in process, `await ctx.router.request('/todo/todos/42')`.
+- **Tests**: `await ctx.router.request(...)` through the plugin, or `await app.request(...)` on the app alone.
+- **A standalone process**: `acryl-node-server`, see [Node server](./node-server.md).
+
+## Mount it in a Blend
+
+Add a row to the Blend's `cordis.patch.yml`; the row id is the package name:
+
+```yaml
+- insert:
+    - id: todo
+      name: todo
+```
+
+A Blank app already carries the router, the HTTP adapter, state and the inspector. The reference app is `examples/acryl-todo`; the
+smallest one to copy is `examples/acryl-framework-starter`.
+
+## Test it without a socket
+
+```ts
+import { Context } from '@deepseek-ai/cordis'
+import * as router from 'acryl-router'
+import * as todo from '../src/index.ts'
+
+const ctx = new Context()
+ctx.plugin(router)
+ctx.plugin(todo)
+await new Promise(resolve => setTimeout(resolve, 0))   // let both plugins activate
+const response = await ctx.router.request('/todo/todos/42')
+expect(await response.json()).toEqual({ id: '42' })
+```
+
+## Package map
+
+| Package | Responsibility |
+| --- | --- |
+| `acryl-router` | the application API and the Cordis `router` service |
+| `acryl-router-http` | serving router prefixes on the ACRYL Host's web server |
+| `acryl-node-server` | serving the whole router from a standalone Node.js process |
+| `acryl-state` | shared application state across surfaces |
+| `acryl-inspect` | runtime inspection of mounts, routes and plugins |
+
+## Next
+
+- [Core concepts](./concepts.md)
+- [Routing and mounting](./routing.md)
+- [Context](./context.md)
+- [Plugin lifecycle and disposal](./plugin-lifecycle.md)

package/docs/framework/helpers.md

@@ -0,0 +1,118 @@
+# Helpers
+
+Helpers are small utilities an application should not have to rewrite. They are plain functions over the context, not Cordis services.
+Import them from `acryl-router/helpers`, except the typed client, which has its own entry, `acryl-router/client`.
+
+| Helper | Use |
+| --- | --- |
+| `stream`, `streamText`, `streamSSE` | streaming responses and server-sent events |
+| `getCookie`, `setCookie`, `deleteCookie`, `getSignedCookie`, `setSignedCookie`, `generateCookie`, `generateSignedCookie` | cookies |
+| `testClient` | a typed client that calls an app in process, for tests |
+| `validator`, `schemaValidator` | input validation, see [Validation](./validation.md) |
+| `createMiddleware`, `createFactory` | typed middleware and handlers that share variables |
+| `html`, `raw` | escaped HTML templates |
+| `accepts` | content negotiation from `Accept` headers |
+| `routePath`, `matchedRoutes`, `baseRoutePath`, `basePath` | the route a request matched |
+| `getConnInfo`, `connectionOf` | the peer and local port, see [Context](./context.md#transport-facts) |
+| `getMimeType`, `getExtension`, `mimes` | media types by file extension |
+| `defineWebSocketHelper`, `WSContext` and their types | the runtime-neutral WebSocket pieces an adapter builds on |
+
+JWT signing and verification (`sign`, `verify`, `decode`) live with the `jwt` middleware in `acryl-router/middleware`.
+
+## Streaming
+
+```ts
+import { stream, streamSSE, streamText } from 'acryl-router/helpers'
+
+app.get('/stream', c => stream(c, async stream => {
+  stream.onAbort(() => console.log('aborted'))
+  await stream.write(new Uint8Array([0x48, 0x69]))
+  await stream.pipe(anotherReadableStream)
+}))
+
+app.get('/text', c => streamText(c, async stream => {
+  await stream.writeln('Hello')
+  await stream.sleep(1000)
+  await stream.write('there')
+}))
+```
+
+Server-sent events write one message at a time with `writeSSE`:
+
+```ts
+app.get('/events', c => streamSSE(c, async stream => {
+  let id = 0
+  while (!stream.aborted) {
+    await stream.writeSSE({ event: 'time', data: new Date().toISOString(), id: String(id++) })
+    await stream.sleep(1000)
+  }
+}))
+```
+
+- The callback runs after the response is returned. When it throws, the optional third argument `onError(error, stream)` runs and the
+  stream sends an `error` event before it closes.
+- There is no built-in keep-alive: send a comment or an event on a timer when a proxy closes idle connections.
+- When the plugin that serves the stream unloads, or the router is disposed, the router cancels the response body, so `onAbort` runs,
+  `aborted` turns true and a loop that checks `stream.aborted` ends with its owner.
+
+## Cookies
+
+```ts
+import { deleteCookie, getCookie, getSignedCookie, setCookie, setSignedCookie } from 'acryl-router/helpers'
+
+app.get('/cookie', c => {
+  setCookie(c, 'theme', 'dark', { path: '/', httpOnly: true, secure: true, sameSite: 'Strict', maxAge: 60 * 60 * 24 })
+  const theme = getCookie(c, 'theme')
+  const all = getCookie(c)
+  deleteCookie(c, 'old')
+  return c.json({ theme, all })
+})
+
+app.get('/signed', async c => {
+  await setSignedCookie(c, 'session', 'value', secret)
+  const session = await getSignedCookie(c, secret, 'session')   // false when the signature does not match
+  return c.json({ session })
+})
+```
+
+`generateCookie` and `generateSignedCookie` return the `Set-Cookie` string without touching a context. The `__Secure-` and `__Host-`
+prefixes are available through `{ prefix: 'secure' }` and `{ prefix: 'host' }`, and the options are checked against their rules.
+
+## Testing
+
+`app.request(path, init?)` calls an app in process and returns a `Response`. `testClient` adds the route types:
+
+```ts
+import { testClient } from 'acryl-router/helpers'
+
+const app = new App()
+  .get('/search', c => c.json({ query: c.req.query('q') }))
+
+const client = testClient(app)
+const response = await client.search.$get({ query: { q: 'cordis' } })
+expect(await response.json()).toEqual({ query: 'cordis' })
+```
+
+The routes must be chained on one expression (as above) for their types to reach the client. Add a test through the Cordis router as well:
+an app test cannot prove the mount, the prefix or the disposal.
+
+## The typed client
+
+`acryl-router/client` is the same client for a real server. It runs in a browser or any runtime with `fetch`, without Cordis:
+
+```ts
+import { hc } from 'acryl-router/client'
+import type { SearchRoutes } from 'my-server'   // the type of the chained app, exported by the server package
+
+const client = hc<SearchRoutes>('http://127.0.0.1:3290/search-app')
+const response = await client.search.$get({ query: { q: 'cordis' } })
+```
+
+Export the app's type (`export type SearchRoutes = typeof app`) from the server package; the client imports only the type, never the
+server code.
+
+## Not yet ported
+
+Proxying, a WebSocket upgrade under the router, JSX, static-site generation, CSS-in-JS and the cache helpers are later tasks (see
+`specs/047-framework-port/plan.md`). Add a missing helper to the framework as a ported, tested helper, not as private code in one
+application.

package/docs/framework/middleware.md

@@ -0,0 +1,154 @@
+# Middleware
+
+Middleware is code that runs around a handler. Use it for behavior shared by several routes: authentication, authorization, logging, CORS,
+caching, compression, request IDs and timing.
+
+## Write middleware
+
+```ts
+import type { MiddlewareHandler } from 'acryl-router'
+
+const timing: MiddlewareHandler = async (c, next) => {
+  const started = performance.now()
+  await next()
+  c.header('X-Response-Time', String(Math.round(performance.now() - started)))
+}
+
+app.use(timing)
+```
+
+`await next()` runs the remaining middleware and then the handler. Not calling it ends the chain, so middleware that refuses a request
+returns a response itself:
+
+```ts
+const requireAdmin: MiddlewareHandler = async (c, next) => {
+  if (!isAdmin(c)) return c.json({ error: 'forbidden' }, 403)
+  await next()
+}
+```
+
+Middleware does not return a response *and* call `next()`: after `next()` it changes `c.res` (or assigns a new `Response` to it) instead.
+
+Authentication establishes an identity; authorization decides whether that identity may do this. Keep them as separate middleware when
+their failure answers differ.
+
+## Scope and order
+
+```ts
+app.use(requestLogger)               // every route of this app
+app.use('/admin/*', requireAdmin)    // below a prefix
+app.on(['POST', 'PUT'], '/items/*', audit)
+```
+
+Middleware runs in registration order and only wraps routes registered after it. The first middleware registered is the outermost: its code
+before `next()` runs first and its code after `next()` runs last.
+
+## Share values with handlers
+
+`createMiddleware` types the variables a middleware sets, and the app picks them up when it is chained:
+
+```ts
+import { createMiddleware } from 'acryl-router/helpers'
+
+const withUser = createMiddleware<{ Variables: { user: User } }>(async (c, next) => {
+  c.set('user', await loadUser(c))
+  await next()
+})
+
+const app = new App().use(withUser).get('/me', c => c.json(c.var.user))
+```
+
+Only request-local values belong here. Shared services belong behind Cordis injection.
+
+## Errors
+
+`await next()` does not throw. When a handler or later middleware throws, the error becomes a response first (an `HTTPException` its own,
+anything else through `onError`) and is left in `c.error`:
+
+```ts
+app.use(async (c, next) => {
+  await next()
+  if (c.error) metrics.count('request_failed')
+})
+```
+
+So a `try { await next() } catch` around `next()` never catches anything. Map domain errors to answers in `app.onError`:
+
+```ts
+app.onError((error, c) => {
+  if (error instanceof DomainError) return c.json({ error: error.code }, error.status)
+  console.error(error)
+  return c.json({ error: 'internal_error' }, 500)
+})
+```
+
+## Built-in middleware
+
+Import from `acryl-router/middleware`:
+
+| Middleware | What it does |
+| --- | --- |
+| `basicAuth`, `bearerAuth` | HTTP Basic and Bearer authentication |
+| `jwt`, `jwk` (with `sign`, `verify`, `decode`, `verifyWithJwks`) | JSON Web Token verification, from a secret or a key set |
+| `bodyLimit` | refuse a request body over a size, with 413, while it streams |
+| `cors` | CORS headers and preflight answers |
+| `csrf` | refuse a cross-site form submission by its `Origin` or `Sec-Fetch-Site` |
+| `secureHeaders` (with `NONCE`) | security headers, including a content security policy with nonces |
+| `ipRestriction` | allow or deny by the peer address (read through `getConnInfo`) |
+| `loopbackOnly` (with `loopbackAuthority`, `sameOrigin`) | only requests from this machine to this app; see below |
+| `compress` | gzip or deflate the response |
+| `etag` | ETag headers and 304 answers |
+| `logger` | one log line per request and response |
+| `requestId` | a request ID header and `c.var.requestId` |
+| `timing` (with `startTime`, `endTime`, `setMetric`, `wrapTime`) | `Server-Timing` headers |
+| `timeout` | answer with an error when a handler takes too long |
+| `prettyJSON` | indented JSON when the query asks for it |
+| `poweredBy` | an `X-Powered-By` header |
+| `methodNotAllowed({ app })` | 405 with an `Allow` header for a known path of `app` asked with another method |
+| `methodOverride` | take the method from a form field, header or query |
+| `trimTrailingSlash`, `appendTrailingSlash` | redirect to the canonical path |
+| `languageDetector` (with `detectFromPath`, `detectFromQuery`, `detectFromCookie`, `detectFromHeader`) | the request's language as a variable |
+| `contextStorage` (with `getContext`, `tryGetContext`) | the current context from code that is not given `c` |
+| `every`, `some`, `except` | combine middleware: all, the first that passes, or all except on some paths |
+| `serveStatic` | the runtime-neutral static file middleware; it needs a `getContent`. On Node use the one from `acryl-node-server` |
+
+### loopbackOnly
+
+The guard for a local app's own routes, such as a control API a desktop window calls:
+
+```ts
+import { loopbackOnly } from 'acryl-router/middleware'
+
+app.use('/control/*', loopbackOnly())
+```
+
+A request passes only when:
+
+- the peer is a loopback address and arrived on the real local port, both read from the transport, never from a header;
+- the `Host` header names a loopback hostname (`127.0.0.1`, `localhost`, `[::1]`, or `hostnames`) with that port, which stops DNS
+  rebinding;
+- for a request that changes things (not `GET`, `HEAD`, `OPTIONS`), any `Origin` is this same authority (`mutations: 'none'` turns this
+  off).
+
+An in-process call has no socket and is refused unless `inProcess: 'allow'` says the host's own code may call it. Everything refused gets a
+403.
+
+A private route that no other program on the machine may call either, such as a workspace's file and terminal routes, takes
+`callers: 'own-page'`:
+
+```ts
+app.use('/api/workspace/*', loopbackOnly({ callers: 'own-page', hostnames: ['127.0.0.1'] }))
+```
+
+Then every request must come from a page this app served: an `Origin` that is exactly this authority (with `Sec-Fetch-Site` absent or
+`same-origin`), or, for a read, which browsers often send without `Origin`, `Sec-Fetch-Site: same-origin` and a `Referer` from this
+authority. A script with no `Origin` is refused even for a read. `fromOwnPage(c, authority)` is the same check for middleware of your own.
+
+## Middleware in Cordis
+
+Middleware belongs to an `App`; it is not a separate Cordis registration, and it disappears with the mount that serves it. A plugin may
+build middleware from an injected service, but resources the middleware uses (timers, watchers, connections) are acquired in the plugin's
+`ctx.effect()` and only the finished middleware goes into the app. Do not start timers, watchers or sockets from a handler.
+
+Middleware an app registers with a path wraps the matching routes of every later mount too (an app mounted at `/` with
+`app.use('/todo/*', ...)` wraps a plugin mounted at `/todo`), so a host can put a guard in front of other plugins by mounting first.