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 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 and after its answer (`optimistic`), a text never shows during some steps, even for one frame (`neverShows`), and the page's errors (`consoleErrors`) |
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. `consoleErrors` lists
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