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.
- package/README.md +4 -2
- package/dist/index.d.ts +10 -1
- package/dist/index.js +37 -16
- package/dist/index.js.map +1 -1
- package/docs/framework/README.md +5 -3
- package/docs/framework/agents/index.md +1 -1
- package/docs/framework/api/acryl.md +3 -3
- package/docs/framework/api/summary.md +1 -1
- package/docs/framework/concepts/web-standard.md +4 -14
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +13 -8
- package/docs/framework/cordis/migration-from-0-4.md +1 -1
- package/docs/framework/cordis/migration-to-1-0.md +45 -0
- package/docs/framework/cordis/node-server.md +27 -5
- package/docs/framework/getting-started/basic.md +15 -10
- package/docs/framework/getting-started/desktop.md +1 -1
- package/docs/framework/getting-started/other-runtimes.md +10 -14
- package/docs/framework/guides/create-acrylblends.md +4 -2
- package/docs/framework/guides/data.md +1 -1
- package/docs/framework/guides/faq.md +1 -1
- package/docs/framework/guides/production.md +43 -0
- package/docs/framework/helpers/conninfo.md +1 -36
- package/docs/framework/helpers/websocket.md +4 -11
- package/docs/framework/middleware/builtin/ip-restriction.md +1 -1
- package/docs/framework/middleware/builtin/loopback-only.md +1 -1
- package/package.json +2 -2
- package/docs/framework/getting-started/aws-lambda.md +0 -115
- package/docs/framework/getting-started/cloudflare-pages.md +0 -53
- package/docs/framework/getting-started/cloudflare-workers.md +0 -67
- package/docs/framework/getting-started/lambda-edge.md +0 -41
- package/docs/framework/getting-started/netlify.md +0 -25
- package/docs/framework/getting-started/service-worker.md +0 -33
- 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 '
|
|
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
|
-
##
|
|
75
|
+
## WebSocket upgrades
|
|
76
76
|
|
|
77
|
-
WebSocket upgrades
|
|
78
|
-
|
|
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
|
|
4
|
-
entry point
|
|
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
|
-
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
|
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)
|
|
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 `
|
|
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
|
-
##
|
|
5
|
+
## Runtimes with an adapter
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
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 '
|
|
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
|
|
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
|
|
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
|
|
4
|
+
The Node.js and Bun adapters are available.
|
|
5
5
|
|
|
6
6
|
## Import
|
|
7
7
|
|
|
8
|
-
The Node.js adapter (`acrylblends/node-server`)
|
|
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`
|
|
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/
|
|
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/
|
|
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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-acrylblends",
|
|
3
|
-
"version": "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.
|
|
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).
|