create-acrylblends 0.4.0 → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +4 -2
  2. package/dist/index.d.ts +10 -1
  3. package/dist/index.js +37 -16
  4. package/dist/index.js.map +1 -1
  5. package/docs/framework/README.md +5 -3
  6. package/docs/framework/agents/index.md +1 -1
  7. package/docs/framework/api/acryl.md +3 -3
  8. package/docs/framework/api/summary.md +1 -1
  9. package/docs/framework/concepts/web-standard.md +4 -14
  10. package/docs/framework/cordis/acryl-in-a-cordis-app.md +13 -8
  11. package/docs/framework/cordis/migration-from-0-4.md +1 -1
  12. package/docs/framework/cordis/migration-to-1-0.md +45 -0
  13. package/docs/framework/cordis/node-server.md +27 -5
  14. package/docs/framework/getting-started/basic.md +15 -10
  15. package/docs/framework/getting-started/desktop.md +1 -1
  16. package/docs/framework/getting-started/other-runtimes.md +10 -14
  17. package/docs/framework/guides/create-acrylblends.md +4 -2
  18. package/docs/framework/guides/data.md +1 -1
  19. package/docs/framework/guides/faq.md +1 -1
  20. package/docs/framework/guides/production.md +43 -0
  21. package/docs/framework/helpers/conninfo.md +1 -36
  22. package/docs/framework/helpers/websocket.md +4 -11
  23. package/docs/framework/middleware/builtin/ip-restriction.md +1 -1
  24. package/docs/framework/middleware/builtin/loopback-only.md +1 -1
  25. package/package.json +2 -2
  26. package/docs/framework/getting-started/aws-lambda.md +0 -115
  27. package/docs/framework/getting-started/cloudflare-pages.md +0 -53
  28. package/docs/framework/getting-started/cloudflare-workers.md +0 -67
  29. package/docs/framework/getting-started/lambda-edge.md +0 -41
  30. package/docs/framework/getting-started/netlify.md +0 -25
  31. package/docs/framework/getting-started/service-worker.md +0 -33
  32. package/docs/framework/getting-started/vercel.md +0 -28
@@ -9,8 +9,8 @@ The server is a Cordis plugin that provides the `nodeServer` service:
9
9
 
10
10
  ```ts
11
11
  import { Context } from '@deepseek-ai/cordis'
12
- import * as router from 'acryl-router'
13
- import * as nodeServer from 'acrylblends/node-server'
12
+ import * as router from 'acrylblends/cordis/router'
13
+ import * as nodeServer from 'acrylblends/cordis/node-server'
14
14
  import * as todo from './todo.ts'
15
15
 
16
16
  const root = new Context()
@@ -72,7 +72,29 @@ plugin that only mounted routes is different: its mount and the requests it is s
72
72
  Let the process configuration choose the address. Do not hard-code a development port in a reusable plugin: a plugin mounts routes and
73
73
  leaves the socket to whichever adapter the app runs with.
74
74
 
75
- ## Not yet supported
75
+ ## WebSocket upgrades
76
76
 
77
- WebSocket upgrades under the router are a later task. The adapter's own WebSocket support exists in `src/adapter/` with its tests but is
78
- not wired to the router yet.
77
+ A plugin takes WebSocket upgrades with `ctx.nodeServer.upgrades()` (or `ctx.routerHttp.upgrades()` on the Host's web server, with `ctx.routerHttp.mount(prefix, { upgrade: [paths] })` naming the exact paths). It returns the ported `upgradeWebSocket`; the route is an ordinary route with ordinary middleware in front of it:
78
+
79
+ ```ts
80
+ export function apply(ctx: Context) {
81
+ const upgrade = ctx.nodeServer.upgrades()
82
+ ctx.router.route('/', new Acryl()
83
+ // Checks run before the upgrade: own page, loopback peer, exact Origin and Host. A refusal is a plain HTTP status with Connection: close, sent before any handshake.
84
+ .use('/terminal', ownPage)
85
+ .get('/terminal', upgrade(() => ({
86
+ onMessage(event, socket) {
87
+ if (socket.bufferedAmount < 1_000_000) socket.send(`echo ${String(event.data)}`)
88
+ },
89
+ onClose(event) {
90
+ // Called exactly once, whoever closed the socket.
91
+ },
92
+ }), { textOnly: true })))
93
+ }
94
+ ```
95
+
96
+ - **Limits.** Text frames only with `{ textOnly: true }` (binary frames never reach `onMessage`); `websocket.maxPayload` (default 1 MiB, a bigger frame closes the socket with 1009); no per-message compression; `socket.bufferedAmount` for back-pressure; `socket.close(code, reason)` with application codes such as 1013 or 4404 (a code the protocol forbids on the wire becomes 1011). No raw socket is exposed.
97
+ - **Dead peers.** The server pings every `websocket.heartbeat` ms (default 30 000) and terminates a peer that did not answer the last ping. `websocket.grace` (default 2000) is how long a closing socket gets.
98
+ - **Ownership.** The sockets a plugin's routes accepted belong to that plugin. When it unloads they are closed with 1001 within the grace (what is left is terminated), its handler sees `close` once, other plugins' sockets are untouched, and `ctx.nodeServer.sockets` counts what is still open. Stopping the server closes every socket.
99
+ - **Needs `ws`.** `npm install ws`; an app that never upgrades does not need it.
100
+ - **Tests.** `testWebSocket((request, env) => app.fetch(request, env), '/terminal', { headers })` from `acrylblends/node-server` runs the route and its middleware in process: a refusal answers `{ status }`, an accepted connection gives a `socket` that sends text frames, collects what the handler sent (`received`) and closes.
@@ -1,11 +1,11 @@
1
1
  # Getting Started
2
2
 
3
- 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
4
- entry point for each. This page shows the basic usage.
3
+ Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code runs on Node.js, the verified runtime, and on Bun,
4
+ which is experimental; only the entry point differs. This page shows the basic usage.
5
5
 
6
6
  ## Starter
7
7
 
8
- Starter templates are available for each runtime. Use the "create-acrylblends" command.
8
+ A starter is a Cordis app that arrives already wired: `blend.yaml`, its plugins in `plugins/`, and a test. Use the "create-acrylblends" command.
9
9
 
10
10
  **npm**
11
11
 
@@ -34,12 +34,17 @@ bun create acrylblends@latest my-app
34
34
  You are asked which template you want:
35
35
 
36
36
  ```
37
- ? Which template do you want to use?
38
- ❯ nodejs
39
- acryl-app
37
+ Templates:
38
+ blank the router, a server and one route: the smallest app
39
+ nodejs a web app with a page and a client component
40
+ notes a multi-user notes app on the db port (sign-up, log-in, sessions)
41
+ chat a chat app that streams an answer over server-sent events
42
+ todo a to-do list on the router and state
43
+ agent the blank app with an offline agent that builds plugins into the running app
44
+ Which template do you want to use? [nodejs]:
40
45
  ```
41
46
 
42
- Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, and `acryl-app` adds an agent that can extend it while it
47
+ Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `blank` is the smallest app, `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, `todo` is a to-do list, and `agent` adds an agent that can extend the app while it
43
48
  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).
44
49
 
45
50
  The template is created in `my-app`: go to it, install the dependencies and start the local server.
@@ -52,9 +57,9 @@ npm run dev
52
57
 
53
58
  ## Hello World
54
59
 
55
- Write your first application in `src/index.ts`. The example below is a starter Acryl application.
60
+ In a generated app the routes live in `src/routes.ts`, which builds an `Acryl` app and mounts it with `ctx.router.route`; `src/main.ts` picks where the app lives and starts it. The app on its own is plain:
56
61
 
57
- 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)).
62
+ The `import` and the final `export default` are the same on Node.js and on Bun; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
58
63
 
59
64
  ```ts twoslash
60
65
  import { Acryl } from 'acrylblends'
@@ -131,7 +136,7 @@ app.get('/', (c) => {
131
136
  })
132
137
  ```
133
138
 
134
- [JSX](../guides/jsx.md) is not yet available.
139
+ JSX works too: `acrylblends/jsx` renders on the server and in the browser, and the `nodejs` template ships a `.tsx` page. See [JSX](../guides/jsx.md).
135
140
 
136
141
  ## Return raw Response
137
142
 
@@ -1,7 +1,7 @@
1
1
  # Desktop
2
2
 
3
3
  An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
4
- template) and a Blend app (the `acryl-app` template or `acrylblends init`). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
4
+ template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
5
5
 
6
6
  ## Add it
7
7
 
@@ -2,24 +2,20 @@
2
2
 
3
3
  Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Node.js ([guide](nodejs.md)) is the runtime the framework is verified on. Bun is experimental ([guide](bun.md)).
4
4
 
5
- ## Hosting platforms with an adapter
5
+ ## Runtimes with an adapter
6
6
 
7
- These platforms have an adapter in acrylblends, ported from the upstream adapters with their tests. Each is called with the platform's own events in the framework's release check; the ACRYL team has not deployed to these platforms, so try a first deploy on a test project.
7
+ | Runtime | Guide | Import | Status |
8
+ | --- | --- | --- | --- |
9
+ | Node.js | [Node.js](nodejs.md) | `acrylblends/node-server` | Primary. Verified on Node 22 and 24, on Linux, macOS and Windows. |
10
+ | Bun | [Bun](bun.md) | `acrylblends/bun` | Experimental. One smoke gate: the Bun adapter is run on Bun (a static file, the client address, a WebSocket echo). |
8
11
 
9
- | Platform | Guide | Import |
10
- | --- | --- | --- |
11
- | AWS Lambda (API Gateway, ALB, Function URLs, VPC Lattice) | [AWS Lambda](aws-lambda.md) | `acrylblends/aws-lambda` |
12
- | Lambda@Edge (CloudFront) | [Lambda@Edge](lambda-edge.md) | `acrylblends/lambda-edge` |
13
- | Cloudflare Workers | [Cloudflare Workers](cloudflare-workers.md) | `acrylblends/cloudflare-workers` |
14
- | Cloudflare Pages | [Cloudflare Pages](cloudflare-pages.md) | `acrylblends/cloudflare-pages` |
15
- | Vercel | [Vercel](vercel.md) | `acrylblends/vercel` |
16
- | Netlify | [Netlify](netlify.md) | `acrylblends/netlify` |
17
- | Service Worker | [Service Worker](service-worker.md) | `acrylblends/service-worker` |
18
- | Bun | [Bun](bun.md) | `acrylblends/bun` |
12
+ ## Removed in 1.0
13
+
14
+ The upstream also ships adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers. They were part of 0.x, ported with their tests, but no gate of ours deploys to any of them, so a 1.0 package does not promise them: they are not built or exported. Their ported sources stay in `plugins/acryl-router/src/core/adapter/` in the repository and may come back as separate plugins, each with its own gate. An app written with `acrylblends` is still plain `fetch` code (`app.fetch(request)`), so a platform that calls a `fetch` handler can call it directly.
19
15
 
20
16
  ## Not yet verified
21
17
 
22
- The following runtimes and platforms have no adapter and no getting-started page yet:
18
+ The following runtimes and platforms have no adapter and no getting-started page:
23
19
 
24
20
  - Deno, and Deno Deploy
25
21
  - Fastly Compute
@@ -31,4 +27,4 @@ The following runtimes and platforms have no adapter and no getting-started page
31
27
  - CloudBase
32
28
  - WebAssembly (WASI)
33
29
 
34
- A page is added here, with a getting-started guide, when a platform has an adapter and a test that calls it.
30
+ A page is added here, with a getting-started guide, when a runtime has an adapter and a gate that runs it.
@@ -7,10 +7,12 @@
7
7
 
8
8
  | Template | What you get |
9
9
  | --- | --- |
10
+ | `blank` | the smallest app: the router, a server and one route, with a test |
10
11
  | `nodejs` | a web app: routes, a server-rendered JSX page and a client component, mounted by the app's own plugin; run with Node.js 22.19 or newer |
11
12
  | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
12
13
  | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
13
- | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
14
+ | `todo` | a to-do list on the router and state: CRUD routes, a page, tests |
15
+ | `agent` | the blank app with an offline agent that builds plugins into the running app, through the door (`acryl-app` is the old name for it and still works) |
14
16
 
15
17
  Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create acrylblends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
16
18
 
@@ -51,7 +53,7 @@ bun create acrylblends@latest my-app --template nodejs
51
53
  | :-- | :-- | :-- |
52
54
  | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
53
55
  | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
54
- | `--template <template>` | One of `nodejs`, `notes`, `chat`, `acryl-app`. Skips the template question; a bare name after the directory means the same. | `--template notes` |
56
+ | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
55
57
  | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
56
58
  | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
57
59
  | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
@@ -289,7 +289,7 @@ applies the `migrations` folder, and provides `db`; a plugin declares `inject: [
289
289
 
290
290
  ```ts
291
291
  import type { Context } from '@deepseek-ai/cordis'
292
- import type {} from 'acryl-db'
292
+ import type {} from 'acrylblends/cordis/db'
293
293
 
294
294
  export const name = 'notes'
295
295
  export const inject = ['db']
@@ -12,7 +12,7 @@ A `json` validation target reads the body only when the request has a JSON `Cont
12
12
 
13
13
  ## Which runtimes are verified?
14
14
 
15
- Node.js. Bun is experimental. The hosting platforms with an adapter (AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify, Service Worker) and the ones without are listed on [Other runtimes](../getting-started/other-runtimes.md).
15
+ Node.js. Bun is experimental. The other hosting platforms have no adapter in 1.0; they are listed on [Other runtimes](../getting-started/other-runtimes.md).
16
16
 
17
17
  ## Where are the parts marked "not yet available"?
18
18
 
@@ -0,0 +1,43 @@
1
+ # What runs in production
2
+
3
+ `acrylblends` has two kinds of parts: the ones an app is built from, which run in production, and the development tools that let an agent (or you) work on the running app, which do not. This page says which is which, and exactly what the safety checks around live plugin install do and do not promise. A test (`plugins/driver-pty/test/production.test.ts`) mounts every development tool in one app and checks the table below.
4
+
5
+ ## The table
6
+
7
+ | Part | In development | With `NODE_ENV=production` |
8
+ | --- | --- | --- |
9
+ | Your routes and plugins, the router, the server, state, the `db` and `kv` ports and their providers | run | run |
10
+ | **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
11
+ | **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
12
+ | **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
13
+ | **Live plugin install** (`extensions`, `builder`) | **experimental**: install, update, remove and reload plugins while the app runs | the `nodejs`, `notes` and `chat` templates leave the `extensions` row out; the `agent` template does not (see below) |
14
+ | `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
15
+
16
+ Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
17
+
18
+ ## The `agent` template is a development app
19
+
20
+ The `agent` template mounts an agent behind `POST /ask` that can write plugins into the running app (`builder`) and install them (`extensions`). Only its door is left out in production. Do not deploy it as it is: remove the `agent`, `builder` and `extensions` rows from `blend.yaml` (or start from `blank`, `nodejs`, `notes`, `chat` or `todo`), and if live install is wanted anywhere shared, set `approval: true` so an install waits for `POST /extensions/approve`.
21
+
22
+ ## What live plugin install does and does not promise
23
+
24
+ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the builder's `install_plugin`) is a **correctness check, not a security boundary**:
25
+
26
+ - It stages a content-hashed copy, imports it, mounts it, and reports the real state (`active`, `pending` with what it waits for, or `failed` with the error). If an update fails to start, the previous version is mounted again. A ledger line records every change.
27
+ - **The plugin's code runs inside the app's own process with the app's permissions**: it can read the app's files and environment, open sockets and start processes. Nothing in the install check stops that.
28
+ - At start-up the app reinstalls what was installed, and installs a new folder only from a source trusted to `install` (the app's own `plugins/` is). Code that arrived through a `git pull` into an untrusted source is listed, not run.
29
+ - `approval: true` holds an install until someone posts to `/extensions/approve`: it decides *whether* a plugin installs, not what an installed plugin can do.
30
+
31
+ ## What the sandbox does and does not stop
32
+
33
+ `ctx.sandbox` runs code you do not trust, such as a **tool** an agent just wrote, in a separate Node process with the permission model on (`node --permission`):
34
+
35
+ - It **stops**: reading any file outside the tool's own folder; writing files; starting child processes or workers; loading native addons; using the inspector. It gets an empty environment (no keys, no paths). It is killed after a time limit and capped in memory and output size. Calls are independent: nothing survives into the next one.
36
+ - It **does not stop**: network access (Node 24 has no network permission: restrict egress outside the process where that matters), and it does not apply to plugins installed live (those are not run in the sandbox).
37
+
38
+ ## Checklist for a deployment
39
+
40
+ 1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
41
+ 2. Start from a template that is not `agent`, or remove the agent rows.
42
+ 3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
43
+ 4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.
@@ -4,14 +4,7 @@ The ConnInfo Helper helps you to get the connection information. For example, yo
4
4
 
5
5
  ## Import
6
6
 
7
- Each adapter has its own `getConnInfo`: `acrylblends/node-server`, `acrylblends/cloudflare-workers`, `acrylblends/vercel`, `acrylblends/aws-lambda`, `acrylblends/netlify`, `acrylblends/lambda-edge` and `acrylblends/bun`. The Bun example is not type-checked by the docs tests, which run without Bun's types.
8
-
9
- **Cloudflare Workers**
10
-
11
- ```ts
12
- import { Acryl } from 'acrylblends'
13
- import { getConnInfo } from 'acrylblends/cloudflare-workers'
14
- ```
7
+ Each adapter has its own `getConnInfo`: `acrylblends/node-server` and `acrylblends/bun` (experimental).
15
8
 
16
9
  **Bun**
17
10
 
@@ -20,34 +13,6 @@ import { Acryl } from 'acrylblends'
20
13
  import { getConnInfo } from 'acrylblends/bun'
21
14
  ```
22
15
 
23
- **Vercel**
24
-
25
- ```ts
26
- import { Acryl } from 'acrylblends'
27
- import { getConnInfo } from 'acrylblends/vercel'
28
- ```
29
-
30
- **AWS Lambda**
31
-
32
- ```ts
33
- import { Acryl } from 'acrylblends'
34
- import { getConnInfo } from 'acrylblends/aws-lambda'
35
- ```
36
-
37
- **Netlify**
38
-
39
- ```ts
40
- import { Acryl } from 'acrylblends'
41
- import { getConnInfo } from 'acrylblends/netlify'
42
- ```
43
-
44
- **Lambda@Edge**
45
-
46
- ```ts
47
- import { Acryl } from 'acrylblends'
48
- import { getConnInfo } from 'acrylblends/lambda-edge'
49
- ```
50
-
51
16
  **Node.js**
52
17
 
53
18
  ```ts
@@ -1,18 +1,11 @@
1
1
  # WebSocket Helper
2
2
 
3
3
  WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
4
- The Node.js, Cloudflare Workers and Bun adapters are available.
4
+ The Node.js and Bun adapters are available.
5
5
 
6
6
  ## Import
7
7
 
8
- The Node.js adapter (`acrylblends/node-server`), the Cloudflare Workers adapter (`acrylblends/cloudflare-workers`) and the Bun adapter (`acrylblends/bun`) provide `upgradeWebSocket`. The other platforms have no WebSocket support in their adapters. The Bun adapter is checked on Bun in the framework's release check; its examples below are not type-checked by the docs tests, which run without Bun's types.
9
-
10
- **Cloudflare Workers**
11
-
12
- ```ts
13
- import { Acryl } from 'acrylblends'
14
- import { upgradeWebSocket } from 'acrylblends/cloudflare-workers'
15
- ```
8
+ The Node.js adapter (`acrylblends/node-server`) and the Bun adapter (`acrylblends/bun`, experimental) provide `upgradeWebSocket`. The other platforms have no adapter in 1.0.
16
9
 
17
10
  **Bun**
18
11
 
@@ -63,7 +56,7 @@ app.get(
63
56
 
64
57
  Available events:
65
58
 
66
- - `onOpen` - Currently, Cloudflare Workers does not support it.
59
+ - `onOpen`
67
60
  - `onMessage`
68
61
  - `onClose`
69
62
  - `onError`
@@ -103,7 +96,7 @@ See the examples using WebSocket Helper.
103
96
  ```ts
104
97
  // server.ts
105
98
  import { Acryl } from 'acrylblends'
106
- import { upgradeWebSocket } from 'acrylblends/cloudflare-workers'
99
+ import { upgradeWebSocket } from 'acrylblends/node-server'
107
100
 
108
101
  const app = new Acryl().get(
109
102
  '/ws',
@@ -31,7 +31,7 @@ app.use(
31
31
  app.get('/', (c) => c.text('Acryl!'))
32
32
  ```
33
33
 
34
- Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/bun`, `acrylblends/aws-lambda`, `acrylblends/node-server` and the others).
34
+ Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/node-server` and `acrylblends/bun`).
35
35
 
36
36
  ## Rules
37
37
 
@@ -3,7 +3,7 @@
3
3
  The guard for a local app's own routes, such as a control API a desktop window calls:
4
4
 
5
5
  ```ts
6
- import { loopbackOnly } from 'acryl-router/middleware'
6
+ import { loopbackOnly } from 'acrylblends/loopback-only'
7
7
 
8
8
  app.use('/control/*', loopbackOnly())
9
9
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-acrylblends",
3
- "version": "0.4.0",
3
+ "version": "1.0.0-rc.1",
4
4
  "description": "Create an Acryl app: npm create acrylblends@latest",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -36,7 +36,7 @@
36
36
  "scaffold"
37
37
  ],
38
38
  "dependencies": {
39
- "acrylblends": "^0.10.0",
39
+ "acrylblends": "^1.0.0-rc.1",
40
40
  "@webboxes/app-persistence": "0.1.1"
41
41
  },
42
42
  "publishConfig": {
@@ -1,115 +0,0 @@
1
- # AWS Lambda
2
-
3
- An Acryl app runs on AWS Lambda behind API Gateway (REST API and HTTP API), an Application Load Balancer, a Lambda Function URL or VPC Lattice. `handle(app)` from `acrylblends/aws-lambda` turns the app into the Lambda handler: it builds a `Request` from the event, calls `app.fetch`, and returns the result in the shape the event source expects.
4
-
5
- > **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with API Gateway v1 and v2 and ALB events. It has not been deployed to an AWS account by the ACRYL team: try your first deploy with a test stage.
6
-
7
- ## Install and write the handler
8
-
9
- ```sh
10
- npm install acrylblends
11
- ```
12
-
13
- ```ts
14
- import { Acryl } from 'acrylblends'
15
- import { handle } from 'acrylblends/aws-lambda'
16
-
17
- const app = new Acryl()
18
-
19
- app.get('/', (c) => c.text('Hello from Lambda'))
20
- app.get('/json', (c) => c.json({ message: 'Hello JSON' }))
21
-
22
- export const handler = handle(app)
23
- ```
24
-
25
- Bundle the file to one JavaScript file for the `nodejs22.x` (or newer) runtime with your tool of choice (esbuild is common), upload it, and set the handler to `index.handler` (the file name, a dot, the export).
26
-
27
- ## The event and the Lambda context
28
-
29
- Both are in the bindings of the request:
30
-
31
- ```ts
32
- import { Acryl } from 'acrylblends'
33
- import type { LambdaContext, LambdaEvent } from 'acrylblends/aws-lambda'
34
-
35
- type Bindings = {
36
- event: LambdaEvent
37
- lambdaContext: LambdaContext
38
- }
39
-
40
- const app = new Acryl<{ Bindings: Bindings }>()
41
-
42
- app.get('/info', (c) => {
43
- return c.json({
44
- isBase64Encoded: c.env.event.isBase64Encoded,
45
- awsRequestId: c.env.lambdaContext.awsRequestId,
46
- })
47
- })
48
- ```
49
-
50
- `c.env.requestContext` holds the request context of the event (API Gateway, ALB or Lattice). The client's address is available through the [ConnInfo helper](../helpers/conninfo.md): `getConnInfo(c).remote.address`.
51
-
52
- ## Binary responses
53
-
54
- A response is returned base64 encoded when its content type is binary (images, audio, video, PDF, archives and other non-text types) or it has a content encoding such as `gzip`. To decide differently, pass `isContentTypeBinary`:
55
-
56
- ```ts
57
- import { Acryl } from 'acrylblends'
58
- import { defaultIsContentTypeBinary, handle } from 'acrylblends/aws-lambda'
59
-
60
- const app = new Acryl()
61
-
62
- export const handler = handle(app, {
63
- isContentTypeBinary: (contentType) =>
64
- defaultIsContentTypeBinary(contentType) || contentType.startsWith('application/vnd.api+octet'),
65
- })
66
- ```
67
-
68
- ## Response streaming
69
-
70
- On a Function URL with `RESPONSE_STREAM` invoke mode, use `streamHandle` instead of `handle`: the body is written to the response stream as the app produces it, so [streaming helpers](../helpers/streaming.md) (SSE, `stream`, `streamText`) reach the client as they are written. It needs the `awslambda` global, which only the Lambda runtime provides.
71
-
72
- ```ts
73
- import { Acryl } from 'acrylblends'
74
- import { streamHandle } from 'acrylblends/aws-lambda'
75
-
76
- const app = new Acryl()
77
-
78
- export const handler = streamHandle(app)
79
- ```
80
-
81
- ## Try it without AWS
82
-
83
- A handler is a function from an event to a result, so it can be called locally with a sample event:
84
-
85
- ```ts
86
- import { Acryl } from 'acrylblends'
87
- import { handle } from 'acrylblends/aws-lambda'
88
-
89
- const app = new Acryl().get('/', (c) => c.text('Hello from Lambda'))
90
-
91
- const result = await handle(app)({
92
- version: '2.0',
93
- routeKey: '$default',
94
- rawPath: '/',
95
- rawQueryString: '',
96
- headers: { host: 'example.execute-api.eu-west-1.amazonaws.com' },
97
- requestContext: {
98
- accountId: '1',
99
- apiId: 'example',
100
- authentication: null,
101
- authorizer: {},
102
- domainName: 'example.execute-api.eu-west-1.amazonaws.com',
103
- domainPrefix: 'example',
104
- http: { method: 'GET', path: '/', protocol: 'HTTP/1.1', sourceIp: '203.0.113.9', userAgent: 'test' },
105
- requestId: 'r',
106
- routeKey: '$default',
107
- stage: '$default',
108
- time: '25/Oct/2026:12:00:00 +0000',
109
- timeEpoch: 0,
110
- },
111
- body: null,
112
- isBase64Encoded: false,
113
- })
114
- console.log(result.statusCode, result.body) // 200 Hello from Lambda
115
- ```
@@ -1,53 +0,0 @@
1
- # Cloudflare Pages
2
-
3
- Cloudflare Pages Functions run code next to a static site. `handle(app)` from `acrylblends/cloudflare-pages` turns an Acryl app into a Pages Function, and `handleMiddleware` turns a middleware into a Pages middleware.
4
-
5
- > **Status.** The adapter is the upstream adapter ported with its test suite, and the framework's release check calls it with a Pages event context. It has not been deployed to Cloudflare by the ACRYL team. Cloudflare recommends Workers with static assets for new projects (see [Cloudflare Workers](cloudflare-workers.md)).
6
-
7
- ## A catch-all function
8
-
9
- Put the file in `functions/[[route]].ts` so it answers every path that is not a static file:
10
-
11
- ```ts
12
- import { Acryl } from 'acrylblends'
13
- import { handle } from 'acrylblends/cloudflare-pages'
14
-
15
- const app = new Acryl().basePath('/api')
16
-
17
- app.get('/hello', (c) => c.json({ message: 'Hello from Pages Functions' }))
18
-
19
- export const onRequest = handle(app)
20
- ```
21
-
22
- `basePath('/api')` is for a function at `functions/api/[[route]].ts`.
23
-
24
- ## The event context and the bindings
25
-
26
- The Pages event context (`env`, `params`, `data`, `waitUntil`, `next`) is `c.env.eventContext`; the environment bindings are `c.env` as in Workers:
27
-
28
- ```ts
29
- import { Acryl } from 'acrylblends'
30
- import type { EventContext } from 'acrylblends/cloudflare-pages'
31
-
32
- type Bindings = { MY_KV: unknown; eventContext: EventContext }
33
-
34
- const app = new Acryl<{ Bindings: Bindings }>()
35
-
36
- app.get('/params', (c) => c.json(c.env.eventContext.params))
37
- ```
38
-
39
- ## Middleware
40
-
41
- ```ts
42
- import { handleMiddleware } from 'acrylblends/cloudflare-pages'
43
-
44
- // functions/_middleware.ts
45
- export const onRequest = handleMiddleware(async (c, next) => {
46
- await next()
47
- c.res.headers.set('x-checked', 'yes')
48
- })
49
- ```
50
-
51
- ## Static files
52
-
53
- In [advanced mode](https://developers.cloudflare.com/pages/platform/functions/advanced-mode/) (a `_worker.js` that answers every request), `serveStatic()` from `acrylblends/cloudflare-pages` answers a request from the Pages `ASSETS` binding and falls through to the app's not-found handler when there is no such file. The client's address is available through the [ConnInfo helper](../helpers/conninfo.md).
@@ -1,67 +0,0 @@
1
- # Cloudflare Workers
2
-
3
- A Cloudflare Worker is a module that exports a `fetch` handler, which is what an Acryl app has: `export default app` is a Worker. The adapter `acrylblends/cloudflare-workers` adds the pieces that need Cloudflare: the client's address, WebSockets, and (deprecated) serving static files from Workers KV.
4
-
5
- > **Status.** The adapter is the upstream adapter ported with its test suite, and a Worker with these routes (`export default app`, bindings from `vars`, `getConnInfo`, `waitUntil`) has been run in `workerd` with `wrangler dev --local`, which needs no Cloudflare account. The ACRYL team has not deployed to Cloudflare itself: run `wrangler dev` first.
6
-
7
- ## A Worker
8
-
9
- ```ts
10
- import { Acryl } from 'acrylblends'
11
-
12
- const app = new Acryl()
13
-
14
- app.get('/', (c) => c.text('Hello Cloudflare Workers!'))
15
-
16
- export default app
17
- ```
18
-
19
- With Wrangler: a `wrangler.jsonc` naming the entry file and a compatibility date (`"main": "src/index.ts"`, `"compatibility_date": "2026-01-01"`), then `npx wrangler dev` to run it locally and `npx wrangler deploy` to publish it.
20
-
21
- ## Bindings and the execution context
22
-
23
- Environment variables, secrets, KV namespaces, D1 databases and R2 buckets arrive as `c.env`; the `ExecutionContext` is `c.executionCtx`:
24
-
25
- ```ts
26
- import { Acryl } from 'acrylblends'
27
-
28
- type Bindings = {
29
- MY_SECRET: string
30
- }
31
-
32
- const app = new Acryl<{ Bindings: Bindings }>()
33
-
34
- app.get('/', (c) => {
35
- c.executionCtx.waitUntil(Promise.resolve()) // work that may finish after the response
36
- return c.text(c.env.MY_SECRET ? 'configured' : 'missing')
37
- })
38
-
39
- export default app
40
- ```
41
-
42
- ## The client's address
43
-
44
- ```ts
45
- import { Acryl } from 'acrylblends'
46
- import { getConnInfo } from 'acrylblends/cloudflare-workers'
47
-
48
- const app = new Acryl()
49
-
50
- app.get('/ip', (c) => c.text(getConnInfo(c).remote.address ?? 'unknown'))
51
-
52
- export default app
53
- ```
54
-
55
- It reads the `cf-connecting-ip` header that Cloudflare sets. See the [ConnInfo helper](../helpers/conninfo.md).
56
-
57
- ## WebSockets
58
-
59
- `upgradeWebSocket` from `acrylblends/cloudflare-workers` accepts the upgrade with Cloudflare's `WebSocketPair`. Cloudflare does not give an `onOpen` event. See the [WebSocket helper](../helpers/websocket.md).
60
-
61
- ## Static files
62
-
63
- Prefer Cloudflare's static assets (the `assets` setting of Wrangler), which serve files before your code runs. `serveStatic` from `acrylblends/cloudflare-workers`, which reads files from Workers KV (`__STATIC_CONTENT`), is deprecated by Cloudflare's move to static assets and is kept for existing Workers Sites projects. Cloudflare Pages is the other option: see [Cloudflare Pages](cloudflare-pages.md).
64
-
65
- ## Service Worker syntax
66
-
67
- A Worker written in the old non-module syntax (`addEventListener('fetch', ...)`) uses `fire` from `acrylblends/service-worker`: see [Service Worker](service-worker.md).