create-acrylblends 0.0.0-stage → 0.1.0

package/docs/framework/cordis/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/cordis/surfaces.md

@@ -0,0 +1,71 @@
+# Surfaces and adapters
+
+An ACRYL application is written once and reached through the surface that fits the user. Surfaces provide transport and presentation;
+plugins provide capabilities.
+
+## Surface model
+
+| Surface | How requests arrive | Typical use |
+| --- | --- | --- |
+| Web | HTTP to the ACRYL Host's web server, through `acryl-router-http` | browser applications and APIs |
+| Desktop | the same Host web server on a loopback port, opened in the Electron window | local-first applications |
+| Terminal UI | in process: `ctx.router.request(...)` or `ctx.router.fetch(...)` | operator tools, agents, terminal workflows |
+| Standalone process | HTTP through `acryl-node-server` | an app that runs without the Host |
+| Tests | `ctx.router.request(...)` or `app.request(...)` | handler and contract tests |
+
+The handler does not know which row supplied the request. When it needs a transport fact it reads the connection from the context
+(`connectionOf(c)`), which is empty for an in-process call.
+
+## Web
+
+The Host owns the listening socket, the address and process shutdown. A plugin mounts its app on the router, then asks the adapter to
+serve the prefix over HTTP:
+
+```ts
+ctx.router.route('/todo', app)
+ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+```
+
+Only prefixes asked for this way are served over HTTP. A prefix the Host's web server already serves cannot be claimed: `mount` throws,
+so a plugin cannot take over a Host route by mounting on it.
+
+## Desktop
+
+Desktop runs the same Host inside Electron, and its window talks to the Host's web server on a loopback port. A plugin's routes therefore
+serve Desktop exactly as they serve Web, with no Desktop-specific code. Guard local control routes with `loopbackOnly` (see
+[Middleware](../concepts/middleware.md#loopbackonly)).
+
+A transport without a port, handing `ctx.router.fetch` to Electron's `protocol.handle`, needs no change to plugins and is a later task
+(`specs/047-framework-port/plan.md` T014).
+
+Desktop capabilities such as windows, files and native dialogs belong in declared Cordis services. A handler calls the service; it does not
+import Electron.
+
+## Terminal UI
+
+A terminal surface needs no server. It calls the composed router in process:
+
+```ts
+const response = await ctx.router.request('/todo/todos')
+const todos = await response.json()
+```
+
+The `routerHttp` service does not exist there, so the plugin's `ctx.inject(['routerHttp'], ...)` simply never runs. Check the services a
+host declares instead of assuming a network route exists.
+
+## What belongs where
+
+| Concern | Owner |
+| --- | --- |
+| Route handlers and middleware | the feature plugin's `Acryl` |
+| Mount path and lifetime | the feature plugin, through `ctx.router.route` |
+| Socket and port | the Host (`acryl-router-http`) or `acryl-node-server` |
+| Terminal rendering and input | the terminal surface |
+| Shared domain behavior | a domain service every surface uses |
+| Shared reactive state | `acryl-state` or an application service |
+
+## Loopback-only routes
+
+Some routes exist only for the local host, such as callbacks and control endpoints. Guard them with `loopbackOnly` at the framework
+boundary; do not rely on an obscure path or a missing link as access control. Loopback restriction is separate from authentication: a
+local route that does privileged work still needs the host's authorization policy.

package/docs/framework/cordis/transport-and-cancellation.md

@@ -0,0 +1,57 @@
+# Transport facts and cancellation
+
+`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 { Acryl } from 'acrylblends'
+import { connectionOf, type RouterEnv } from 'acrylblends/conninfo'
+import { getConnInfo } from 'acrylblends/conninfo'
+
+const app = new Acryl<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 'acrylblends/http-exception'
+
+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/cordis/validation.md

@@ -0,0 +1,135 @@
+# Validation
+
+Validate untrusted input at the route boundary. `schemaValidator` takes any [Standard Schema](https://standardschema.dev): Schemastery
+(the schema library Cordis already uses for plugin config), Zod and Valibot all implement it, so a route needs no extra dependency.
+
+## Validate JSON
+
+```ts
+import z from '@deepseek-ai/schemastery'
+import { Acryl } from 'acrylblends'
+import { schemaValidator } from 'acrylblends/schema-validator'
+
+const NewTodo = z.object({
+  title: z.string().required(),
+  done: z.boolean().default(false),
+})
+
+const app = new Acryl().post('/todos', schemaValidator('json', NewTodo), c => {
+  const todo = c.req.valid('json')   // typed by the schema's output
+  return c.json({ todo }, 201)
+})
+```
+
+A validated route has three parts: a schema for one input target, the validator middleware for that target, and a handler that reads
+`c.req.valid(target)` instead of the raw body.
+
+## Failures
+
+When the schema reports issues the handler does not run and the answer is 400 with `Content-Type: application/json` and exactly this
+shape:
+
+```ts
+{ error: `invalid ${target}`, issues: Array<{ message: string, path: string }> }
+```
+
+```json
+{ "error": "invalid json", "issues": [{ "message": "title must be 1 to 200 characters", "path": "title" }] }
+```
+
+- `error` names the target: `invalid json`, `invalid query`, `invalid param`, ...
+- There is one entry per issue the schema reported, in its order, with the schema's own `message`.
+- `path` is the issue's path joined with dots: `["items", 0, "title"]` becomes `"items.0.title"`, and a path segment given as
+  `{ key }` (as Standard Schema allows) contributes its `key`.
+- An issue without a path, which a hand-written Standard Schema often reports for a whole-value check, gets `"path": ""`.
+  `{ issues: [{ message: 'not allowed' }] }` answers `{ "error": "invalid json", "issues": [{ "message": "not allowed", "path": "" }] }`.
+  Give issues a path when a client should point at a field.
+
+### A JSON body without a JSON content type
+
+A `json` target reads the body only when the request's `Content-Type` is JSON (`application/json`, with or without parameters such as
+`; charset=utf-8`, or `application/*+json`). Any other content type, or none, is not an error by itself: the schema sees `{}`. So a
+client that forgets the header gets a misleading field error for a field it did send:
+
+```sh
+curl -X POST -d '{"title":"milk"}' http://127.0.0.1:<port>/todo/api      # no content type: curl sends a form type
+# 400 {"error":"invalid json","issues":[{"message":"title must be 1 to 200 characters","path":"title"}]}
+```
+
+If you see a field error for a field the request clearly carries, check the request's `Content-Type` first. A route that wants to say so
+explicitly can refuse other content types before the validator:
+
+```ts
+import type { MiddlewareHandler } from 'acrylblends'
+
+const jsonOnly: MiddlewareHandler = async (c, next) => {
+  // The same types the json target reads: application/json and application/*+json, parameters allowed.
+  const type = c.req.header('content-type')?.split(';', 1)[0]?.trim() ?? ''
+  if (!/^application\/([a-z.-]+\+)?json$/i.test(type)) return c.json({ error: 'content type must be JSON' }, 415)
+  await next()
+}
+
+app.post('/todos', jsonOnly, schemaValidator('json', NewTodo), createTodo)
+```
+
+### A body that is not JSON
+
+A JSON content type with a body that does not parse fails before the schema runs: the answer is 400 with the text body
+`Malformed JSON in request body` (a thrown `HTTPException`, so an `onError` handler can reshape it). The `form` target does the same for
+a form body that does not parse, with the text `Malformed FormData request.`
+
+Keep the public failure shape consistent across the application and do not leak internals in messages. An application that needs a
+different body writes its own check with the core `validator` (below). Valid input is not proof that the caller may use it:
+authentication and authorization stay separate checks.
+
+## Targets
+
+| Target | Read from |
+| --- | --- |
+| `json` | the JSON body |
+| `form` | a `multipart/form-data` or `application/x-www-form-urlencoded` body |
+| `query` | the query string |
+| `param` | route parameters |
+| `header` | request headers (names in lowercase) |
+| `cookie` | cookies |
+
+Validate only the targets the route uses, and chain one validator per target:
+
+```ts
+app.get('/todos/:id', schemaValidator('param', z.object({ id: z.natural() })), schemaValidator('query', Paging), handler)
+```
+
+## The core validator
+
+`validator` (from `acrylblends/validator`) takes a function instead of a schema. Return the value the handler should see, or a
+response to refuse:
+
+```ts
+import { validator } from 'acrylblends/validator'
+
+app.post('/posts', validator('form', (value, c) => {
+  const body = value['body']
+  if (typeof body !== 'string') return c.text('Invalid!', 400)
+  return { body }
+}), c => c.json({ body: c.req.valid('form').body }, 201))
+```
+
+## Limit the body first
+
+Validation reads the whole body. Put `bodyLimit` in front of a validator on any route open to untrusted callers:
+
+```ts
+import { bodyLimit } from 'acrylblends/body-limit'
+
+app.post('/todos', bodyLimit({ maxSize: 16 * 1024 }), schemaValidator('json', NewTodo), createTodo)
+```
+
+## Typed clients
+
+The validated input types flow into the route types, so the typed `testClient` and `acrylblends/client` check the request a caller sends.
+See [Helpers](../guides/helpers.md#testing).
+
+## What not to validate twice
+
+Validate shape at the HTTP boundary, then enforce domain rules in the domain service. The route checks that `title` is a string; the
+todo service decides whether that title is allowed.

package/docs/framework/getting-started/basic.md

@@ -0,0 +1,196 @@
+# Getting Started
+
+Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code works on every verified runtime, with a different
+entry point for each. This page shows the basic usage.
+
+## Starter
+
+Starter templates are available for each runtime. Use the "create-acrylblends" command.
+
+**npm**
+
+```sh
+npm create acrylblends@latest my-app
+```
+
+**yarn**
+
+```sh
+yarn create acrylblends my-app
+```
+
+**pnpm**
+
+```sh
+pnpm create acrylblends@latest my-app
+```
+
+**bun**
+
+```sh
+bun create acrylblends@latest my-app
+```
+
+You are asked which template you want:
+
+```
+? Which template do you want to use?
+❯   nodejs
+    bun (experimental)
+    acryl-app
+```
+
+`nodejs` and `bun` (experimental) are a minimal Acryl application for that runtime. `acryl-app` is a Cordis app built from plugins, with an agent that can extend it while it
+runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [create-acrylblends](../guides/create-acrylblends.md).
+
+The template is created in `my-app`: go to it, install the dependencies and start the local server.
+
+```sh
+cd my-app
+npm install
+npm run dev
+```
+
+## Hello World
+
+Write your first application in `src/index.ts`. The example below is a starter Acryl application.
+
+The `import` and the final `export default` are the same on every runtime; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', (c) => {
+  return c.text('Hello Acryl!')
+})
+
+export default app
+```
+
+Start the development server and open the address it prints.
+
+## Return JSON
+
+Returning JSON is also easy. The following handles a GET request to `/api/hello` and returns an `application/json` response.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/api/hello', (c) => {
+  return c.json({
+    ok: true,
+    message: 'Hello Acryl!',
+  })
+})
+```
+
+## Request and Response
+
+Getting a path parameter, a URL query value, and adding a response header is written as follows.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/posts/:id', (c) => {
+  const page = c.req.query('page')
+  const id = c.req.param('id')
+  c.header('X-Message', 'Hi!')
+  return c.text(`You want to see ${page} of ${id}`)
+})
+```
+
+POST, PUT and DELETE are handled the same way as GET.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.post('/posts', (c) => c.text('Created!', 201))
+app.delete('/posts/:id', (c) => c.text(`${c.req.param('id')} is deleted!`))
+```
+
+## Return HTML
+
+Write HTML with [the html helper](../helpers/html.md):
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { html } from 'acrylblends/html'
+
+const app = new Acryl()
+
+app.get('/', (c) => {
+  const name = 'Acryl'
+  return c.html(html`<!doctype html><h1>Hello ${name}!</h1>`)
+})
+```
+
+[JSX](../guides/jsx.md) is not yet available.
+
+## Return raw Response
+
+You can also return a raw Web Standard `Response`.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+
+app.get('/', () => {
+  return new Response('Good morning!')
+})
+```
+
+## Using Middleware
+
+Middleware can do the hard work for you. For example, add Basic Authentication.
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+import { basicAuth } from 'acrylblends/basic-auth'
+
+const app = new Acryl()
+
+app.use(
+  '/admin/*',
+  basicAuth({
+    username: 'admin',
+    password: 'secret',
+  })
+)
+
+app.get('/admin', (c) => {
+  return c.text('You are authorized!')
+})
+```
+
+There are useful middleware included, such as Bearer and JWT authentication, CORS and ETag. See [Built-in middleware](../middleware/builtin/basic-auth.md).
+
+## Testing
+
+An app is a function from `Request` to `Response`, so a test needs no server:
+
+```ts twoslash
+import { Acryl } from 'acrylblends'
+
+const app = new Acryl()
+app.get('/', (c) => c.text('Hello Acryl!'))
+
+const response = await app.request('/')
+console.log(response.status, await response.text())
+```
+
+See [Testing](../guides/testing.md).
+
+## Next
+
+- [Node.js](nodejs.md) and [Bun](bun.md) (experimental)
+- [Routing](../api/routing.md), [Context](../api/context.md) and [Request](../api/request.md)
+- [Validation](../guides/validation.md)