@acryldev/create-blends 1.7.1 → 1.7.2
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/{LICENSE → docs/framework/LICENSE} +3 -1
- package/docs/framework/README.md +70 -0
- package/docs/framework/agents/index.md +59 -0
- package/docs/framework/api/acryl.md +247 -0
- package/docs/framework/api/context.md +478 -0
- package/docs/framework/api/exception.md +80 -0
- package/docs/framework/api/index.md +12 -0
- package/docs/framework/api/presets.md +62 -0
- package/docs/framework/api/request.md +396 -0
- package/docs/framework/api/routing.md +303 -0
- package/docs/framework/api/summary.md +143 -0
- package/docs/framework/concepts/benchmarks.md +26 -0
- package/docs/framework/concepts/developer-experience.md +5 -0
- package/docs/framework/concepts/middleware.md +21 -0
- package/docs/framework/concepts/motivation.md +14 -0
- package/docs/framework/concepts/routers.md +63 -0
- package/docs/framework/concepts/stacks.md +235 -0
- package/docs/framework/concepts/web-standard.md +27 -0
- package/docs/framework/cordis/acryl-in-a-cordis-app.md +160 -0
- package/docs/framework/cordis/concepts.md +105 -0
- package/docs/framework/cordis/middleware.md +8 -0
- package/docs/framework/cordis/migration-from-0-3.md +111 -0
- package/docs/framework/cordis/migration-from-0-4.md +14 -0
- package/docs/framework/cordis/migration-from-dsh-webserver.md +109 -0
- package/docs/framework/cordis/migration-to-1-0.md +46 -0
- package/docs/framework/cordis/mounting.md +85 -0
- package/docs/framework/cordis/node-server.md +100 -0
- package/docs/framework/cordis/plugin-lifecycle.md +111 -0
- package/docs/framework/cordis/surfaces.md +71 -0
- package/docs/framework/cordis/transport-and-cancellation.md +57 -0
- package/docs/framework/cordis/validation.md +135 -0
- package/docs/framework/getting-started/basic.md +201 -0
- package/docs/framework/getting-started/bun.md +219 -0
- package/docs/framework/getting-started/deploy.md +133 -0
- package/docs/framework/getting-started/desktop.md +80 -0
- package/docs/framework/getting-started/nodejs.md +365 -0
- package/docs/framework/getting-started/other-runtimes.md +30 -0
- package/docs/framework/guides/best-practices.md +231 -0
- package/docs/framework/guides/bring-your-own-tool.md +218 -0
- package/docs/framework/guides/client-modules.md +210 -0
- package/docs/framework/guides/create-acrylblends.md +143 -0
- package/docs/framework/guides/data.md +314 -0
- package/docs/framework/guides/examples.md +3 -0
- package/docs/framework/guides/faq.md +19 -0
- package/docs/framework/guides/forms-and-sessions.md +235 -0
- package/docs/framework/guides/helpers.md +33 -0
- package/docs/framework/guides/jsx-dom.md +301 -0
- package/docs/framework/guides/jsx.md +487 -0
- package/docs/framework/guides/middleware.md +253 -0
- package/docs/framework/guides/production.md +80 -0
- package/docs/framework/guides/rpc.md +878 -0
- package/docs/framework/guides/testing.md +133 -0
- package/docs/framework/guides/validation.md +470 -0
- package/docs/framework/helpers/accepts.md +60 -0
- package/docs/framework/helpers/adapter.md +57 -0
- package/docs/framework/helpers/conninfo.md +77 -0
- package/docs/framework/helpers/cookie.md +232 -0
- package/docs/framework/helpers/css.md +282 -0
- package/docs/framework/helpers/dev.md +64 -0
- package/docs/framework/helpers/factory.md +180 -0
- package/docs/framework/helpers/html.md +123 -0
- package/docs/framework/helpers/jwt.md +184 -0
- package/docs/framework/helpers/proxy.md +115 -0
- package/docs/framework/helpers/route.md +143 -0
- package/docs/framework/helpers/ssg.md +390 -0
- package/docs/framework/helpers/streaming.md +224 -0
- package/docs/framework/helpers/testing.md +118 -0
- package/docs/framework/helpers/websocket.md +208 -0
- package/docs/framework/middleware/builtin/basic-auth.md +165 -0
- package/docs/framework/middleware/builtin/bearer-auth.md +138 -0
- package/docs/framework/middleware/builtin/body-limit.md +71 -0
- package/docs/framework/middleware/builtin/cache.md +99 -0
- package/docs/framework/middleware/builtin/combine.md +94 -0
- package/docs/framework/middleware/builtin/compress.md +59 -0
- package/docs/framework/middleware/builtin/context-storage.md +74 -0
- package/docs/framework/middleware/builtin/cors.md +134 -0
- package/docs/framework/middleware/builtin/csrf.md +105 -0
- package/docs/framework/middleware/builtin/etag.md +54 -0
- package/docs/framework/middleware/builtin/ip-restriction.md +69 -0
- package/docs/framework/middleware/builtin/jsx-renderer.md +283 -0
- package/docs/framework/middleware/builtin/jwk.md +192 -0
- package/docs/framework/middleware/builtin/jwt.md +145 -0
- package/docs/framework/middleware/builtin/language.md +232 -0
- package/docs/framework/middleware/builtin/logger.md +74 -0
- package/docs/framework/middleware/builtin/loopback-only.md +31 -0
- package/docs/framework/middleware/builtin/method-not-allowed.md +48 -0
- package/docs/framework/middleware/builtin/method-override.md +80 -0
- package/docs/framework/middleware/builtin/mount.md +103 -0
- package/docs/framework/middleware/builtin/pretty-json.md +53 -0
- package/docs/framework/middleware/builtin/request-id.md +87 -0
- package/docs/framework/middleware/builtin/secure-headers.md +247 -0
- package/docs/framework/middleware/builtin/timeout.md +98 -0
- package/docs/framework/middleware/builtin/timing.md +100 -0
- package/docs/framework/middleware/builtin/trailing-slash.md +74 -0
- package/docs/framework/middleware/third-party.md +4 -0
- package/docs/framework/workshop/README.md +294 -0
- package/docs/framework/workshop/facilitator.md +101 -0
- package/package.json +2 -2
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
# Middleware
|
|
2
|
+
|
|
3
|
+
Middleware works before/after the endpoint `Handler`. We can get the `Request` before dispatching or manipulate the `Response` after dispatching.
|
|
4
|
+
|
|
5
|
+
## Definition of Middleware
|
|
6
|
+
|
|
7
|
+
- Handler - should return `Response` object. Only one handler will be called.
|
|
8
|
+
- Middleware - should `await next()` and return nothing to call the next Middleware, **or** return a `Response` to early-exit.
|
|
9
|
+
|
|
10
|
+
The user can register middleware using `app.use` or using `app.HTTP_METHOD` as well as the handlers. For this feature, it's easy to specify the path and the method.
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
// match any method, all routes
|
|
14
|
+
app.use(logger())
|
|
15
|
+
|
|
16
|
+
// specify path
|
|
17
|
+
app.use('/posts/*', cors())
|
|
18
|
+
|
|
19
|
+
// specify method and path
|
|
20
|
+
app.post('/posts/*', basicAuth())
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
If the handler returns `Response`, it will be used for the end-user and will stop processing.
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
app.post('/posts', (c) => c.text('Created!', 201))
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
In this case, four middleware are processed before dispatching like this:
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
logger() -> cors() -> basicAuth() -> *handler*
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Execution order
|
|
36
|
+
|
|
37
|
+
The order in which Middleware is executed is determined by the order in which it is registered.
|
|
38
|
+
The process before the `next` of the first registered Middleware is executed first,
|
|
39
|
+
and the process after the `next` is executed last.
|
|
40
|
+
See below.
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
app.use(async (_, next) => {
|
|
44
|
+
console.log('middleware 1 start')
|
|
45
|
+
await next()
|
|
46
|
+
console.log('middleware 1 end')
|
|
47
|
+
})
|
|
48
|
+
app.use(async (_, next) => {
|
|
49
|
+
console.log('middleware 2 start')
|
|
50
|
+
await next()
|
|
51
|
+
console.log('middleware 2 end')
|
|
52
|
+
})
|
|
53
|
+
app.use(async (_, next) => {
|
|
54
|
+
console.log('middleware 3 start')
|
|
55
|
+
await next()
|
|
56
|
+
console.log('middleware 3 end')
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
app.get('/', (c) => {
|
|
60
|
+
console.log('handler')
|
|
61
|
+
return c.text('Hello!')
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Result is the following.
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
middleware 1 start
|
|
69
|
+
middleware 2 start
|
|
70
|
+
middleware 3 start
|
|
71
|
+
handler
|
|
72
|
+
middleware 3 end
|
|
73
|
+
middleware 2 end
|
|
74
|
+
middleware 1 end
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Note that if the handler or any middleware throws, acrylblends will catch it and either pass it to [your app.onError() callback](../api/acryl.md#error-handling) or automatically convert it to a 500 response before returning it up the chain of middleware. This means that next() will never throw, so there is no need to wrap it in a try/catch/finally.
|
|
78
|
+
|
|
79
|
+
## Built-in Middleware
|
|
80
|
+
|
|
81
|
+
Acryl has built-in middleware.
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { Acryl } from '@acryldev/blends'
|
|
85
|
+
import { poweredBy } from '@acryldev/blends/powered-by'
|
|
86
|
+
import { logger } from '@acryldev/blends/logger'
|
|
87
|
+
import { basicAuth } from '@acryldev/blends/basic-auth'
|
|
88
|
+
|
|
89
|
+
const app = new Acryl()
|
|
90
|
+
|
|
91
|
+
app.use(poweredBy())
|
|
92
|
+
app.use(logger())
|
|
93
|
+
|
|
94
|
+
app.use(
|
|
95
|
+
'/auth/*',
|
|
96
|
+
basicAuth({
|
|
97
|
+
username: 'acrylblends',
|
|
98
|
+
password: process.env.BASIC_AUTH_PASSWORD!,
|
|
99
|
+
})
|
|
100
|
+
)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Warning.**
|
|
104
|
+
|
|
105
|
+
For example, this code is not working because the version is different.
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
import { Acryl } from 'npm:acrylblends'
|
|
109
|
+
import { upgradeWebSocket } from 'npm:acrylblends'
|
|
110
|
+
|
|
111
|
+
const app = new Acryl()
|
|
112
|
+
|
|
113
|
+
app.get(
|
|
114
|
+
'/ws',
|
|
115
|
+
upgradeWebSocket(() => ({
|
|
116
|
+
// ...
|
|
117
|
+
}))
|
|
118
|
+
)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Custom Middleware
|
|
122
|
+
|
|
123
|
+
You can write your own middleware directly inside `app.use()`:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
// Custom logger
|
|
127
|
+
app.use(async (c, next) => {
|
|
128
|
+
console.log(`[${c.req.method}] ${c.req.url}`)
|
|
129
|
+
await next()
|
|
130
|
+
})
|
|
131
|
+
|
|
132
|
+
// Add a custom header
|
|
133
|
+
app.use('/message/*', async (c, next) => {
|
|
134
|
+
await next()
|
|
135
|
+
c.header('x-message', 'This is middleware!')
|
|
136
|
+
})
|
|
137
|
+
|
|
138
|
+
app.get('/message/hello', (c) => c.text('Hello Middleware!'))
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
However, embedding middleware directly within `app.use()` can limit its reusability. Therefore, we can separate our middleware into different files.
|
|
142
|
+
|
|
143
|
+
To ensure we don't lose type definitions for `context` and `next`, when separating middleware, we can use [`createMiddleware()`](../helpers/factory.md#createmiddleware) from Acryl's factory. This also allows us to type-safely [access data we've `set` in `Context`](../api/context.md#set-get) from downstream handlers.
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { createMiddleware } from '@acryldev/blends/factory'
|
|
147
|
+
|
|
148
|
+
const logger = createMiddleware(async (c, next) => {
|
|
149
|
+
console.log(`[${c.req.method}] ${c.req.url}`)
|
|
150
|
+
await next()
|
|
151
|
+
})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Note.**
|
|
155
|
+
|
|
156
|
+
Type generics can be used with `createMiddleware`:
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
createMiddleware<{Bindings: Bindings}>(async (c, next) =>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Modify the Response After Next
|
|
163
|
+
|
|
164
|
+
Additionally, middleware can be designed to modify responses if necessary:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const stripRes = createMiddleware(async (c, next) => {
|
|
168
|
+
await next()
|
|
169
|
+
c.res = undefined
|
|
170
|
+
c.res = new Response('New Response')
|
|
171
|
+
})
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Context access inside Middleware arguments
|
|
175
|
+
|
|
176
|
+
To access the context inside middleware arguments, directly use the context parameter provided by `app.use`. See the example below for clarification.
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
import { cors } from '@acryldev/blends/cors'
|
|
180
|
+
|
|
181
|
+
app.use('*', async (c, next) => {
|
|
182
|
+
const middleware = cors({
|
|
183
|
+
origin: c.env.CORS_ORIGIN,
|
|
184
|
+
})
|
|
185
|
+
return middleware(c, next)
|
|
186
|
+
})
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Extending the Context in Middleware
|
|
190
|
+
|
|
191
|
+
To extend the context inside middleware, use `c.set`. You can make this type-safe by passing a `{ Variables: { yourVariable: YourVariableType } }` generic argument to the `createMiddleware` function.
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
import { createMiddleware } from '@acryldev/blends/factory'
|
|
195
|
+
|
|
196
|
+
const echoMiddleware = createMiddleware<{
|
|
197
|
+
Variables: {
|
|
198
|
+
echo: (str: string) => string
|
|
199
|
+
}
|
|
200
|
+
}>(async (c, next) => {
|
|
201
|
+
c.set('echo', (str) => str)
|
|
202
|
+
await next()
|
|
203
|
+
})
|
|
204
|
+
|
|
205
|
+
app.get('/echo', echoMiddleware, (c) => {
|
|
206
|
+
return c.text(c.var.echo('Hello!'))
|
|
207
|
+
})
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Type Inference Across Chained Middleware
|
|
211
|
+
|
|
212
|
+
When you chain multiple middleware using `.use()`, Acryl automatically accumulates the `Variables` types. Route handlers that follow the middleware chain can access all variables from every preceding middleware in a type-safe way:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
import { createMiddleware } from '@acryldev/blends/factory'
|
|
216
|
+
|
|
217
|
+
const authMiddleware = createMiddleware<{
|
|
218
|
+
Variables: { user: { id: string; name: string } }
|
|
219
|
+
}>(async (c, next) => {
|
|
220
|
+
c.set('user', { id: '123', name: 'Alice' })
|
|
221
|
+
await next()
|
|
222
|
+
})
|
|
223
|
+
|
|
224
|
+
const dbMiddleware = createMiddleware<{
|
|
225
|
+
Variables: { db: { query: (sql: string) => Promise<unknown> } }
|
|
226
|
+
}>(async (c, next) => {
|
|
227
|
+
c.set('db', {
|
|
228
|
+
query: async (sql) => {
|
|
229
|
+
/* ... */
|
|
230
|
+
},
|
|
231
|
+
})
|
|
232
|
+
await next()
|
|
233
|
+
})
|
|
234
|
+
|
|
235
|
+
const app = new Acryl()
|
|
236
|
+
.use(authMiddleware)
|
|
237
|
+
.use(dbMiddleware)
|
|
238
|
+
.get('/', (c) => {
|
|
239
|
+
// Both `user` and `db` are available and type-safe
|
|
240
|
+
const user = c.var.user // { id: string; name: string }
|
|
241
|
+
const db = c.var.db // { query: (sql: string) => Promise<unknown> }
|
|
242
|
+
return c.json({ user })
|
|
243
|
+
})
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
This works because each `.use()` call returns a new Acryl instance with the merged type, so the type grows as middleware is chained. This eliminates the need to manually declare a combined `Env` type upfront for most use cases.
|
|
247
|
+
|
|
248
|
+
## Third-party Middleware
|
|
249
|
+
|
|
250
|
+
Built-in middleware does not depend on external modules, but third-party middleware can depend on third-party libraries. So with them, we may make a more complex application.
|
|
251
|
+
|
|
252
|
+
We can explore a variety of third-party middleware.
|
|
253
|
+
For example, we have GraphQL Server Middleware, Sentry Middleware, Firebase Auth Middleware, and others.
|
|
@@ -0,0 +1,80 @@
|
|
|
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** (`@acryldev/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 and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent` and `builder` (since 1.0.1) and starts the `extensions` read-only (since 1.0.7: the plugins in `plugins/` run as deployed, nothing can be installed or changed) unless `ACRYL_PRODUCTION_KEEP` names them |
|
|
14
|
+
| **The chat template's model endpoint** (`POST /api/chat`) | answers anyone | **closed** (503) unless `CHAT_ACCESS_TOKEN` is set, or `ACRYL_PRODUCTION_KEEP=chat` makes it public with a warning and a per-address limit (since 1.0.2) |
|
|
15
|
+
| `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
## The `agent` template in production
|
|
20
|
+
|
|
21
|
+
The `agent` template mounts an agent behind `POST /ask` that spends the model key and can write plugins into the running app (`builder`) and install them (`extensions`, with `POST /extensions/approve` deciding installs). **None of that is behind a login.** Since 1.0.1, with `NODE_ENV=production` the template leaves the `agent` and `builder` rows out, along with the door: `/ask`, `/extensions*` and `/tasks*` are not mounted, and the page and `GET /health` stay. 1.0.0 left them mounted. **What the agent built is still served**: 1.0.1 to 1.0.6 also left the `extensions` row out, so an app whose pages were extensions (the workshop's board) lost them in production. Since 1.0.7 the row starts again, read-only: the extension folders of `plugins/` (what the agent installed in development, committed with the app) are loaded once from where they are, nothing can be installed, updated, removed or approved while the app runs, and the start prints one line, `extensions (read-only): board, notes` (or `extensions: none found in plugins/`). If `extensions.json` in the app's data folder records an extension that `plugins/` has no folder for, a `WARNING` names it: commit its folder, or install it again in development.
|
|
22
|
+
|
|
23
|
+
- To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list; naming `extensions` keeps the live install, not just the read-only start). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
|
|
24
|
+
- **An app made by 1.0.0 keeps its own `src/app.ts` and `src/routes.ts`**, which `acrylblends upgrade` never touches (they are your files). Until you change them: deploy with the `agent`, `builder` and `extensions` rows set to `disabled: true` in `blend.yaml`, or start from another template, or copy the new `src/app.ts` and `src/routes.ts` of a fresh `acrylblends init my-app --template agent` over yours.
|
|
25
|
+
|
|
26
|
+
## The `chat` template in production
|
|
27
|
+
|
|
28
|
+
The chat template answers with the owner's model key, so anyone who can reach it spends that key. Since 1.0.2, with `NODE_ENV=production` it is **closed**: every route but `GET /health` answers 503 until you choose one of:
|
|
29
|
+
|
|
30
|
+
- `CHAT_ACCESS_TOKEN=<a long random string>`: the browser asks for a login and takes any user name with the token as the password. Share the token with the people who may use the chat.
|
|
31
|
+
- `ACRYL_PRODUCTION_KEEP=chat`: the chat is public, with a `WARNING` line at start and a limit of `CHAT_RATE_PER_MINUTE` messages a minute from one address (default 20; behind a proxy you run, set `TRUST_PROXY=1` so the limit counts the visitor, not the proxy). Prefer your own login in front.
|
|
32
|
+
|
|
33
|
+
An app made by 1.0.0 or 1.0.1 keeps its own `src/routes.ts`: copy `src/access.ts`, `src/chat-app.ts` and `src/routes.ts` from a fresh `acrylblends init my-app --template chat`, or put a login in front.
|
|
34
|
+
|
|
35
|
+
## What live plugin install does and does not promise
|
|
36
|
+
|
|
37
|
+
Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the builder's `install_plugin`) is a **correctness check, not a security boundary**:
|
|
38
|
+
|
|
39
|
+
- 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.
|
|
40
|
+
- **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.
|
|
41
|
+
- 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.
|
|
42
|
+
- `approval: true` holds an install until someone posts to `/extensions/approve`: it decides *whether* a plugin installs, not what an installed plugin can do.
|
|
43
|
+
|
|
44
|
+
## What the sandbox does and does not stop
|
|
45
|
+
|
|
46
|
+
`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`):
|
|
47
|
+
|
|
48
|
+
- 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.
|
|
49
|
+
- 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).
|
|
50
|
+
|
|
51
|
+
## The address and the port
|
|
52
|
+
|
|
53
|
+
A server made from a template listens on `127.0.0.1` and starts looking for a free port at a number of its own (3100 and up, chosen from the app's folder). A hosting platform tells the process where to listen with `PORT`, and a container needs `0.0.0.0` to be reached from outside. The app reads four variables, in this order:
|
|
54
|
+
|
|
55
|
+
| What | First | Then | Otherwise |
|
|
56
|
+
| --- | --- | --- | --- |
|
|
57
|
+
| The port to start from (`0` for any free port) | `ACRYLBLENDS_PORT` | `PORT` | a number of its own, from the app's folder |
|
|
58
|
+
| The interface | `ACRYLBLENDS_HOST` | `HOST` | `127.0.0.1` (this machine only) |
|
|
59
|
+
|
|
60
|
+
`PORT` and `HOST` have been read since 1.1.0; before it, the `agent` and `blank` templates ignored `PORT` (`PORT=3299` still listened on the app's own number). If the port is taken the server tries the next ones, and the line it prints at start (`app listening on http://0.0.0.0:3299`) says which it got; a platform that routes to a fixed port should be given one that is free. For example, on a plain server:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
npm ci --omit=dev
|
|
64
|
+
NODE_ENV=production HOST=0.0.0.0 PORT=3299 npm start
|
|
65
|
+
# app listening on http://0.0.0.0:3299 (data in /home/app/.acryl/apps/app-3f9c/data; ...)
|
|
66
|
+
curl http://127.0.0.1:3299/health
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The data is in `~/.acryl/apps/<id>/data` of the user that runs the app, and the `<id>` is kept in the app folder's `.acryl/app.json`, which git ignores: a
|
|
70
|
+
deploy into a fresh clone gets a new id and an empty data folder. On a server, set `ACRYLBLENDS_HOME` to a fixed folder (the `agent` template's Dockerfile
|
|
71
|
+
sets `/data`).
|
|
72
|
+
|
|
73
|
+
Putting the app on `0.0.0.0` makes it reachable by anyone who can reach the machine: put the login or the proxy in front first (see the checklist below).
|
|
74
|
+
|
|
75
|
+
## Checklist for a deployment
|
|
76
|
+
|
|
77
|
+
1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
|
|
78
|
+
2. With the `agent` template, leave `ACRYL_PRODUCTION_KEEP` unset (1.0.1 and later), or remove the agent rows. With the `chat` template, set `CHAT_ACCESS_TOKEN` (1.0.2 and later) or put your own login in front.
|
|
79
|
+
3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
|
|
80
|
+
4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.
|