acrylblends 0.4.1 → 0.5.0

package/templates/todo/upstream.json

@@ -5,8 +5,8 @@
       "examples/acryl-todo/src/index.ts": "src/todo.ts",
       "examples/acryl-todo/src/page.ts": "src/page.ts"
     },
-    "commit": "64e7c9d2e787f74b2da82492644fbbb46a601074"
+    "commit": "f5151e7f0c4de3b81bddb5cc686b5ef329e48e1c"
   },
   "rewrittenSpecifiers": 4,
-  "digest": "sha256:b62b5167344084f7ac03c8286923f92419a4ab41c5d8235adb3247d983807aca"
+  "digest": "sha256:9093704776563001f7f472f94cc5c2fdd79206342c1cb59c11fce62aa74df3ed"
 }

package/docs/framework/context.md

@@ -1,129 +0,0 @@
-# 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/helpers.md

@@ -1,118 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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.

package/docs/framework/request.md

@@ -1,106 +0,0 @@
-# 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).