foldkit-plus 0.18.0 → 0.20.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,63 @@ 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. Every warm request is checked, since a deployed
202
+ limit applies to each rather than to their mean: `warm` in a reading is the
203
+ most one spent. Over budget, it throws with every route's reading; a 5xx
204
+ throws too, since a failure costs nothing. `cold` is the route's first
205
+ request in the call, so in a fresh stack it is a cold isolate's: code not yet
206
+ optimized, and work kept per isolate (a compiled query, Auth) done for the
207
+ first time.
208
+
209
+ There are two meters:
210
+
211
+ - `stack.cpu` sends each request straight to the Worker and reads the main
212
+ thread of the stack's workerd processes, where JavaScript runs, from the
213
+ operating system (`/proc` on Linux, PowerShell on Windows; other systems
214
+ are refused). It counts the Worker's code and what workerd does on that
215
+ thread around it, D1's SQLite included, which a deployed Worker's CPU time
216
+ leaves out: an empty route reads about 1 ms. V8's helper threads (garbage
217
+ collection, compiling) are left out. Stacks started at the same time in one
218
+ process cannot tell their workerd apart, and their `spent()` refuses.
219
+ - `Cpu.inThread(handler, origin?)` runs a `(request) => Promise<Response>`
220
+ in this process and reads this thread's CPU time: for a handler Node can
221
+ run, such as a page renderer or a Remote server over Node's SQLite, with no
222
+ stack to start.
223
+
224
+ Read budgets on Linux, where both meters count nanoseconds. Windows adds to
225
+ a thread's time a scheduler tick (15.6 ms) at a time, so a reading there is
226
+ only good as a mean of many requests. Choose a budget from Linux readings,
227
+ with room for a slower CI runner: a route several times over it is the
228
+ fault to catch, not noise. The examples hold their main routes to one:
229
+ [examples/cloudflare](https://github.com/doeixd/foldkit-plus/blob/main/examples/cloudflare/test/cpu.test.ts),
230
+ [examples/chirp](https://github.com/doeixd/foldkit-plus/blob/main/examples/chirp/test/cpu.test.ts)
231
+ and
232
+ [examples/foldkit/domains-plus](https://github.com/doeixd/foldkit-plus/blob/main/examples/foldkit/domains-plus/test/cpu.test.ts).
233
+
167
234
  <!-- docs-check
168
235
  import type { Page } from 'playwright'
169
236
  import { expect } from 'vitest'
@@ -185,7 +252,23 @@ await Behaviors.neverShows(page, {
185
252
  expect(errors()).toEqual([])
186
253
  ```
187
254
 
188
- These check the drawn page over the real network. `consoleErrors` lists
255
+ These check the drawn page over the real network. `optimistic` holds every
256
+ Remote mutation at the network, for `hold` and until it has looked for
257
+ `shows`, and requires `shows` within `within` of the action beginning, so what
258
+ it sees was drawn before any answer however long the action takes (an action
259
+ still running after 10 seconds, or `hold` if longer, is refused: one waiting
260
+ for its own write's answer would wait for good). From then until the write settles, each element `shows` resolves to
261
+ must stay the same node, in the same place in its parent, within 1px of where
262
+ it was drawn, and visible. A prediction that is drawn again, pushed down by a
263
+ line said only while the write is pending, or hidden for a frame fails with
264
+ what moved and when. Settled is evidence: no Remote request of the page in
265
+ flight (an answer can ask for more), then three quiet frames. `stays` names
266
+ what must hold still instead (a `Locator`: the list around a row its answer
267
+ deliberately draws again), or `'shown'` for only "shows after". Writes that
268
+ reach the server another way (a port to a SharedWorker) pass `writes: {
269
+ answered }`, and the page holds them itself; `examples/chirp`'s end-to-end
270
+ test opens its sandbox with `?latency=1500` and reads its outbox. An error the
271
+ page logs while a write settles fails it too. `consoleErrors` lists
189
272
  `console.error` and uncaught exceptions, which includes every `error`
190
273
  diagnostic the default `Diagnostics` reporter logs. To find which Message makes
191
274
  a read blink, `foldkit-plus/remote/testing`'s `Trace` runs `update` and Remote's
@@ -210,6 +293,11 @@ package to the tested one, which keeps one copy of each:
210
293
  that already holds a `pnpm` field);
211
294
  - Yarn: `resolutions`; Bun: `overrides`.
212
295
 
296
+ npm keeps a package its lockfile holds rather than move it down to an
297
+ override, and a scaffold locks the newest Effect patch under
298
+ `@foldkit/vite-plugin`. Where `package-lock.json` already holds a later patch
299
+ of the tested minor, `setup` pins that one instead.
300
+
213
301
  That also holds `foldkit-durable`'s `@effect/sql-sqlite-node`, whose every
214
302
  release peers on an `effect` at least its own version. Each release of
215
303
  `foldkit-plus` pins the release of every package it brings, so the set is one