foldkit-plus 0.18.0 → 0.19.0
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 +89 -3
- package/dist/cli.mjs +800 -259
- package/dist/cli.mjs.map +1 -1
- package/dist/project.d.mts.map +1 -1
- package/dist/project.mjs +17 -1
- package/dist/project.mjs.map +1 -1
- package/dist/remote/filter.d.mts +1 -0
- package/dist/remote/filter.mjs +2 -0
- package/dist/remote/live.d.mts +1 -0
- package/dist/remote/live.mjs +2 -0
- package/dist/remote/outbox.d.mts +1 -0
- package/dist/remote/outbox.mjs +2 -0
- package/dist/remote/overlay.d.mts +1 -0
- package/dist/remote/overlay.mjs +2 -0
- package/dist/remote/persistence.d.mts +1 -0
- package/dist/remote/persistence.mjs +2 -0
- package/dist/remote/why.d.mts +1 -0
- package/dist/remote/why.mjs +2 -0
- package/dist/setup.d.mts +10 -0
- package/dist/setup.d.mts.map +1 -1
- package/dist/setup.mjs +24 -5
- package/dist/setup.mjs.map +1 -1
- package/dist/testing/playwright.d.mts +41 -6
- package/dist/testing/playwright.d.mts.map +1 -1
- package/dist/testing/playwright.mjs +180 -24
- package/dist/testing/playwright.mjs.map +1 -1
- package/dist/testing/workers.d.mts +75 -1
- package/dist/testing/workers.d.mts.map +1 -1
- package/dist/testing/workers.mjs +285 -12
- package/dist/testing/workers.mjs.map +1 -1
- package/package.json +90 -54
package/README.md
CHANGED
|
@@ -127,8 +127,8 @@ subpath that needs one it cannot find says which.
|
|
|
127
127
|
|
|
128
128
|
| Subpath | Needs | For |
|
|
129
129
|
| --- | --- | --- |
|
|
130
|
-
| `foldkit-plus/testing/workers` | `wrangler`, `esbuild` | `Stack.start`: the Worker on a local workerd, configured by its own `wrangler.toml`, with fresh migrated D1 per stack; `Stack.writeBundle`: the same bundle where `main` says, for `wrangler deploy` |
|
|
131
|
-
| `foldkit-plus/testing/playwright` | `playwright` (types) | `Behaviors`: a write shows while it is held at the network
|
|
130
|
+
| `foldkit-plus/testing/workers` | `wrangler`, `esbuild`, `@foldkit/vite-plugin` | `Stack.start`: the Worker on a local workerd, configured by its own `wrangler.toml`, with fresh migrated D1 per stack; `Stack.writeBundle`: the same bundle where `main` says, for `wrangler deploy`; `Cpu.budget`: fails a test when a route spends more CPU than a budget |
|
|
131
|
+
| `foldkit-plus/testing/playwright` | `playwright` (types) | `Behaviors`: a write shows while it is held at the network, holds still until its answer is drawn, and shows after (`optimistic`), a text never shows during some steps, even for one frame (`neverShows`), and the page's errors (`consoleErrors`) |
|
|
132
132
|
|
|
133
133
|
<!-- docs-check
|
|
134
134
|
interface Env { readonly ORIGIN: string }
|
|
@@ -147,6 +147,16 @@ stack.logs() // what the Worker wrote to its console since the last call; also p
|
|
|
147
147
|
await stack.stop()
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
+
The bundle's views are branded as `@foldkit/vite-plugin` brands the
|
|
151
|
+
page's build: each function's result is named by its module's path from the
|
|
152
|
+
page's Vite root, which is the folder of `wrangler.toml` unless `pageRoot`
|
|
153
|
+
names another. Foldkit adopts a served element only when that name is the
|
|
154
|
+
one the browser's view gives it, and rebuilds the rest without a word in
|
|
155
|
+
production, so a Worker bundled without the brand had every page it rendered
|
|
156
|
+
rebuilt on hydration. A module an esbuild plugin of `plugins` loads is
|
|
157
|
+
branded too. Where the page root resolves no `foldkit`, there is no Foldkit
|
|
158
|
+
page to match, and the Worker is bundled as written.
|
|
159
|
+
|
|
150
160
|
The Worker's console is printed here as it arrives, each line with Node's
|
|
151
161
|
console method of its level and prefixed `[worker]`, so a 500 shows the error
|
|
152
162
|
behind it with its stack; `console: 'quiet'` keeps the lines for `logs()`
|
|
@@ -164,6 +174,61 @@ configuration the stack refuses, goes to `onRefused`, and the Worker running
|
|
|
164
174
|
keeps answering. `onStopped` is the rest: a swap that failed after its trial
|
|
165
175
|
started, which takes Wrangler's harness down with its storage.
|
|
166
176
|
|
|
177
|
+
### CPU per request
|
|
178
|
+
|
|
179
|
+
A deployed Worker that spends more CPU on a request than its plan allows
|
|
180
|
+
fails it with error 1102 (the free plan allows 10 ms). Miniflare neither
|
|
181
|
+
enforces that limit nor reports CPU: its tail events say `cpuTime: 0`,
|
|
182
|
+
`limits.cpu_ms` is not applied, and `process.cpuUsage` is not implemented.
|
|
183
|
+
So `Cpu.budget` reads it from outside, and fails a test when a route spends
|
|
184
|
+
more than a budget:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { Cpu } from 'foldkit-plus/testing/workers'
|
|
188
|
+
|
|
189
|
+
const readings = await Cpu.budget(stack.cpu, {
|
|
190
|
+
warm: 20, // ms each request after the first may spend
|
|
191
|
+
cold: 150, // ms the first may spend; unchecked when left out
|
|
192
|
+
routes: {
|
|
193
|
+
home: '/', // a GET of this path
|
|
194
|
+
search: () => new Request(`${stack.origin}/remote`, { method: 'POST', body: '{}' }),
|
|
195
|
+
},
|
|
196
|
+
})
|
|
197
|
+
// [{ route: 'home', status: 200, cold: 31.2, warm: 4.1 }, …]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Each route is asked once, then `runs` (5) times more, one request at a time,
|
|
201
|
+
each response read in full. Over budget, it throws with every route's
|
|
202
|
+
reading; a 5xx throws too, since a failure costs nothing. `cold` is the
|
|
203
|
+
route's first request in the call, so in a fresh stack it is a cold
|
|
204
|
+
isolate's: code not yet optimized, and work kept per isolate (a compiled
|
|
205
|
+
query, Auth) done for the first time.
|
|
206
|
+
|
|
207
|
+
There are two meters:
|
|
208
|
+
|
|
209
|
+
- `stack.cpu` sends each request straight to the Worker and reads the main
|
|
210
|
+
thread of the stack's workerd processes, where JavaScript runs, from the
|
|
211
|
+
operating system (`/proc` on Linux, PowerShell on Windows; other systems
|
|
212
|
+
are refused). It counts the Worker's code and what workerd does on that
|
|
213
|
+
thread around it, D1's SQLite included, which a deployed Worker's CPU time
|
|
214
|
+
leaves out: an empty route reads about 1 ms. V8's helper threads (garbage
|
|
215
|
+
collection, compiling) are left out. Stacks started at the same time in one
|
|
216
|
+
process cannot tell their workerd apart, and their `spent()` refuses.
|
|
217
|
+
- `Cpu.inThread(handler, origin?)` runs a `(request) => Promise<Response>`
|
|
218
|
+
in this process and reads this thread's CPU time: for a handler Node can
|
|
219
|
+
run, such as a page renderer or a Remote server over Node's SQLite, with no
|
|
220
|
+
stack to start.
|
|
221
|
+
|
|
222
|
+
Read budgets on Linux, where both meters count nanoseconds. Windows adds to
|
|
223
|
+
a thread's time a scheduler tick (15.6 ms) at a time, so a reading there is
|
|
224
|
+
only good as a mean of many requests. Choose a budget from Linux readings,
|
|
225
|
+
with room for a slower CI runner: a route several times over it is the
|
|
226
|
+
fault to catch, not noise. The examples hold their main routes to one:
|
|
227
|
+
[examples/cloudflare](https://github.com/doeixd/foldkit-plus/blob/main/examples/cloudflare/test/cpu.test.ts),
|
|
228
|
+
[examples/chirp](https://github.com/doeixd/foldkit-plus/blob/main/examples/chirp/test/cpu.test.ts)
|
|
229
|
+
and
|
|
230
|
+
[examples/foldkit/domains-plus](https://github.com/doeixd/foldkit-plus/blob/main/examples/foldkit/domains-plus/test/cpu.test.ts).
|
|
231
|
+
|
|
167
232
|
<!-- docs-check
|
|
168
233
|
import type { Page } from 'playwright'
|
|
169
234
|
import { expect } from 'vitest'
|
|
@@ -185,7 +250,23 @@ await Behaviors.neverShows(page, {
|
|
|
185
250
|
expect(errors()).toEqual([])
|
|
186
251
|
```
|
|
187
252
|
|
|
188
|
-
These check the drawn page over the real network. `
|
|
253
|
+
These check the drawn page over the real network. `optimistic` holds every
|
|
254
|
+
Remote mutation at the network, for `hold` and until it has looked for
|
|
255
|
+
`shows`, and requires `shows` within `within` of the action beginning, so what
|
|
256
|
+
it sees was drawn before any answer however long the action takes (an action
|
|
257
|
+
still running after 10 seconds, or `hold` if longer, is refused: one waiting
|
|
258
|
+
for its own write's answer would wait for good). From then until the write settles, each element `shows` resolves to
|
|
259
|
+
must stay the same node, in the same place in its parent, within 1px of where
|
|
260
|
+
it was drawn, and visible. A prediction that is drawn again, pushed down by a
|
|
261
|
+
line said only while the write is pending, or hidden for a frame fails with
|
|
262
|
+
what moved and when. Settled is evidence: no Remote request of the page in
|
|
263
|
+
flight (an answer can ask for more), then three quiet frames. `stays` names
|
|
264
|
+
what must hold still instead (a `Locator`: the list around a row its answer
|
|
265
|
+
deliberately draws again), or `'shown'` for only "shows after". Writes that
|
|
266
|
+
reach the server another way (a port to a SharedWorker) pass `writes: {
|
|
267
|
+
answered }`, and the page holds them itself; `examples/chirp`'s end-to-end
|
|
268
|
+
test opens its sandbox with `?latency=1500` and reads its outbox. An error the
|
|
269
|
+
page logs while a write settles fails it too. `consoleErrors` lists
|
|
189
270
|
`console.error` and uncaught exceptions, which includes every `error`
|
|
190
271
|
diagnostic the default `Diagnostics` reporter logs. To find which Message makes
|
|
191
272
|
a read blink, `foldkit-plus/remote/testing`'s `Trace` runs `update` and Remote's
|
|
@@ -210,6 +291,11 @@ package to the tested one, which keeps one copy of each:
|
|
|
210
291
|
that already holds a `pnpm` field);
|
|
211
292
|
- Yarn: `resolutions`; Bun: `overrides`.
|
|
212
293
|
|
|
294
|
+
npm keeps a package its lockfile holds rather than move it down to an
|
|
295
|
+
override, and a scaffold locks the newest Effect patch under
|
|
296
|
+
`@foldkit/vite-plugin`. Where `package-lock.json` already holds a later patch
|
|
297
|
+
of the tested minor, `setup` pins that one instead.
|
|
298
|
+
|
|
213
299
|
That also holds `foldkit-durable`'s `@effect/sql-sqlite-node`, whose every
|
|
214
300
|
release peers on an `effect` at least its own version. Each release of
|
|
215
301
|
`foldkit-plus` pins the release of every package it brings, so the set is one
|