@sigil-dev/grimoire 0.9.29 → 0.9.31

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.
Files changed (105) hide show
  1. package/bin/sigil.ts +4 -0
  2. package/index.ts +16 -10
  3. package/package.json +14 -6
  4. package/server.ts +2 -2
  5. package/src/adapters/bun.ts +17 -17
  6. package/src/adapters/static.ts +41 -41
  7. package/src/adapters/types.ts +36 -36
  8. package/src/base.ts +4 -1
  9. package/src/client/csrf.ts +47 -47
  10. package/src/client/deferred.ts +1 -4
  11. package/src/client/enhance.ts +160 -160
  12. package/src/client/router.ts +927 -926
  13. package/src/config-file.ts +84 -0
  14. package/src/dev/compile-module.ts +199 -193
  15. package/src/dev/hmr-client.ts +229 -229
  16. package/src/dev/hmr-server.ts +274 -266
  17. package/src/dev/loader.ts +144 -144
  18. package/src/dev/runtime-bundle.ts +5 -3
  19. package/src/duration.ts +46 -0
  20. package/src/env/modules.ts +62 -62
  21. package/src/env/required.ts +42 -42
  22. package/src/env/typegen.ts +61 -61
  23. package/src/headers.ts +105 -105
  24. package/src/logger/transports.ts +117 -117
  25. package/src/plugin-order.ts +88 -0
  26. package/src/rendering/head.ts +49 -49
  27. package/src/rendering/hydrate.ts +162 -162
  28. package/src/rendering/images.ts +43 -43
  29. package/src/rendering/preload.ts +22 -8
  30. package/src/rendering/ssrPlugin.ts +107 -107
  31. package/src/rendering/timing.ts +40 -40
  32. package/src/routing/route-ids.ts +65 -0
  33. package/src/routing/route.ts +65 -0
  34. package/src/routing/router.ts +84 -32
  35. package/src/routing/scanner.ts +18 -5
  36. package/src/routing/transform-routes.ts +102 -102
  37. package/src/server/after-response.ts +206 -206
  38. package/src/server/asset-cache.ts +57 -57
  39. package/src/server/build.ts +304 -295
  40. package/src/server/cached.ts +114 -114
  41. package/src/server/client-address.ts +82 -82
  42. package/src/server/client-dir.ts +63 -63
  43. package/src/server/client-entry.ts +44 -44
  44. package/src/server/context.ts +18 -10
  45. package/src/server/cookie-utils.ts +80 -80
  46. package/src/server/coordinator.ts +479 -476
  47. package/src/server/hooks.ts +122 -122
  48. package/src/server/index.ts +1181 -1171
  49. package/src/server/plugins.ts +172 -172
  50. package/src/server/prerender.ts +473 -473
  51. package/src/server/reserved.ts +17 -17
  52. package/src/server/resolver.ts +149 -123
  53. package/src/server/rewrite.ts +28 -28
  54. package/src/server/warm.ts +9 -3
  55. package/src/server/with-headers.ts +27 -27
  56. package/src/server/worker.ts +2 -6
  57. package/src/server-only.ts +78 -0
  58. package/src/testing/dom.ts +73 -73
  59. package/src/testing/index.ts +169 -169
  60. package/src/testing/server.ts +1 -0
  61. package/src/typegen/index.ts +97 -2
  62. package/src/types.ts +642 -508
  63. package/test/after-response.test.ts +132 -132
  64. package/test/asset-cache-policy.test.ts +6 -2
  65. package/test/base.test.ts +20 -6
  66. package/test/cached.test.ts +126 -126
  67. package/test/client-address.test.ts +78 -78
  68. package/test/client-csrf.test.ts +61 -61
  69. package/test/client-dir.test.ts +101 -101
  70. package/test/client-router.test.ts +37 -5
  71. package/test/config-file.test.ts +84 -0
  72. package/test/coordinator.test.ts +9 -2
  73. package/test/deferred.test.ts +4 -2
  74. package/test/dev-loader.test.ts +30 -30
  75. package/test/env.test.ts +171 -171
  76. package/test/force-production.test.ts +7 -2
  77. package/test/images.test.ts +20 -8
  78. package/test/locals-header.test.ts +61 -61
  79. package/test/middleware.test.ts +243 -243
  80. package/test/parser-plugins.test.ts +98 -92
  81. package/test/plugin-handle.test.ts +62 -62
  82. package/test/plugin-order.test.ts +98 -0
  83. package/test/plugin-routes.test.ts +47 -42
  84. package/test/plugin-services-context.test.ts +7 -2
  85. package/test/preload.test.ts +4 -1
  86. package/test/prerender.test.ts +3 -1
  87. package/test/rendering.test.ts +3 -2
  88. package/test/required-env.test.ts +32 -32
  89. package/test/resolver-windows.test.ts +22 -23
  90. package/test/rewrite-html.test.ts +90 -90
  91. package/test/route-group-layouts.test.ts +38 -36
  92. package/test/route.test.ts +103 -0
  93. package/test/routing.test.ts +225 -197
  94. package/test/scanning.test.ts +53 -33
  95. package/test/server-context.test.ts +22 -0
  96. package/test/server-only.test.ts +110 -0
  97. package/test/server.test.ts +659 -640
  98. package/test/services.test.ts +3 -3
  99. package/test/streaming.test.ts +11 -6
  100. package/test/testing-helpers.test.ts +166 -166
  101. package/test/typegen.test.ts +209 -112
  102. package/test/warm.test.ts +96 -96
  103. package/test/worker-context.test.ts +59 -59
  104. package/test/workspace-files.test.ts +26 -10
  105. package/test/workspace-versions.test.ts +146 -131
@@ -1,476 +1,479 @@
1
- import { join } from "node:path";
2
- import { type ServerWebSocket, type Subprocess, spawn } from "bun";
3
- import { assertRequiredEnv } from "../env/required";
4
- import { log } from "../logger/instance";
5
- import { matchRoute } from "../routing/router";
6
- import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
7
- import type {
8
- CoordinatorContext,
9
- GrimoireConfig,
10
- GrimoirePlugin,
11
- PluginContext,
12
- WorkerDescriptor,
13
- WorkerMode,
14
- } from "../types";
15
- import { buildProject } from "./build";
16
- import { CLIENT_ADDRESS_HEADER, resolveClientAddress } from "./client-address";
17
- import {
18
- runHook,
19
- runRouteRequest,
20
- runSerializeLocals,
21
- runWorkerSpawn,
22
- } from "./plugins";
23
-
24
- const logger = log.scope("loom");
25
-
26
- async function waitForWorkers(
27
- workers: LiveWorker[],
28
- timeoutMs = 10_000,
29
- ): Promise<void> {
30
- const ready = new Set<number>();
31
- const start = Date.now();
32
- while (ready.size < workers.length) {
33
- if (Date.now() - start > timeoutMs) {
34
- const pending = workers
35
- .filter((w) => !ready.has(w.descriptor.globalIndex))
36
- .map(
37
- (w) =>
38
- w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
39
- )
40
- .join(", ");
41
- throw new Error(`Grimoire: workers timed out: ${pending}`);
42
- }
43
- for (const w of workers) {
44
- if (!ready.has(w.descriptor.globalIndex) && w.descriptor.pid != null) {
45
- ready.add(w.descriptor.globalIndex);
46
- }
47
- }
48
- await Bun.sleep(50);
49
- }
50
- }
51
-
52
- function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
53
- const idx = roundRobinCounter++ % workers.length;
54
- return workers[idx];
55
- }
56
- let roundRobinCounter = 0;
57
-
58
- function consistentHash(
59
- req: Request,
60
- workers: WorkerDescriptor[],
61
- ): WorkerDescriptor {
62
- const key = req.headers.get("cookie") ?? req.url;
63
- let hash = 0;
64
- for (let i = 0; i < key.length; i++)
65
- hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
66
- return workers[hash % workers.length];
67
- }
68
-
69
- function defaultRoute(
70
- req: Request,
71
- workers: WorkerDescriptor[],
72
- tree: RouteTree,
73
- ): WorkerDescriptor {
74
- const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
75
- if (isWs) {
76
- const ws = workers.filter((w) => w.mode === "ws" || w.mode === "full");
77
- if (ws.length) return consistentHash(req, ws);
78
- }
79
- const url = new URL(req.url);
80
- const matched = matchRoute(tree, url);
81
- if (matched?.route.type === "server") {
82
- const api = workers.filter((w) => w.mode === "api" || w.mode === "full");
83
- if (api.length) return roundRobin(api);
84
- }
85
- const frontend = workers.filter(
86
- (w) => w.mode === "frontend" || w.mode === "full",
87
- );
88
- if (frontend.length) return roundRobin(frontend);
89
- return workers[0];
90
- }
91
-
92
- export interface ScaleSpec {
93
- api?: number;
94
- frontend?: number;
95
- ws?: number;
96
- [mode: string]: number | undefined;
97
- }
98
-
99
- export interface CoordinatorOptions {
100
- config: GrimoireConfig;
101
- plugins: GrimoirePlugin[];
102
- scale: ScaleSpec;
103
- noBuild: boolean;
104
- }
105
-
106
- interface LiveWorker {
107
- descriptor: WorkerDescriptor;
108
- process: Subprocess;
109
- port: number;
110
- env: Record<string, string>;
111
- intentional: boolean;
112
- /** When the current process was spawned, and the next restart delay. */
113
- startedAt: number;
114
- backoff: number;
115
- }
116
-
117
- export async function startCoordinator(options: CoordinatorOptions) {
118
- const { config, plugins, scale, noBuild } = options;
119
- const { port = 3000, host = "localhost", routes = "src/routes" } = config;
120
- let stopping = false;
121
-
122
- const workerEntry = join(import.meta.dir, "./worker.ts");
123
-
124
- // ── inner helpers (close over plugins/stopping/workerEntry) ──
125
-
126
- function spawnWorker(lw: LiveWorker): void {
127
- const proc = spawn(["bun", "run", workerEntry], {
128
- env: lw.env,
129
- ipc(message) {
130
- if (message?.ready) {
131
- lw.descriptor.pid = proc.pid;
132
- runHook(plugins, "onWorkerReady", lw.descriptor);
133
- }
134
- },
135
- onExit(_, exitCode) {
136
- if (lw.intentional) {
137
- lw.intentional = false;
138
- return;
139
- }
140
- lw.descriptor.pid = undefined;
141
- runHook(
142
- plugins,
143
- "onWorkerDeath",
144
- lw.descriptor,
145
- stopping ? "intentional" : "crash",
146
- );
147
- if (stopping) return;
148
- // a worker that stayed up a while starts over at one second; one
149
- // that keeps dying on startup waits longer each time, up to 30s
150
- const upFor = Date.now() - lw.startedAt;
151
- lw.backoff = upFor > 30_000 ? 1_000 : Math.min(lw.backoff * 2, 30_000);
152
- logger.error(
153
- `worker ${lw.descriptor.name ?? `${lw.descriptor.mode}-${lw.descriptor.index}`} crashed (exit ${exitCode}), respawning in ${lw.backoff / 1000}s`,
154
- );
155
- setTimeout(() => {
156
- if (!stopping) spawnWorker(lw);
157
- }, lw.backoff);
158
- },
159
- });
160
- lw.process = proc;
161
- lw.startedAt = Date.now();
162
- }
163
-
164
- async function respawnWorker(lw: LiveWorker): Promise<void> {
165
- lw.intentional = true;
166
- lw.process.kill();
167
- lw.descriptor.pid = undefined;
168
- spawnWorker(lw);
169
- await waitForWorkers([lw]);
170
- }
171
-
172
- // 0. plugin resolution
173
- const pluginCtx: PluginContext = {
174
- mode: config.dev ? "development" : "production",
175
- plugins: new Map(plugins.map((p) => [p.name, p])),
176
- logger: log.scope("plugins"),
177
- };
178
- await runHook(plugins, "onPluginsResolved", pluginCtx);
179
-
180
- // Before the build and before any worker exists: one error in the
181
- // terminal beats N workers each failing and being respawned.
182
- assertRequiredEnv(config);
183
-
184
- // 1. build
185
- if (!noBuild) {
186
- const { result } = await buildProject(config, plugins);
187
- if (!result.success) throw new Error("Grimoire: build failed");
188
- }
189
-
190
- // 2. ephemeral secret
191
- const secret = crypto.randomUUID() + crypto.randomUUID();
192
-
193
- // 3. scan routes
194
- const tree = await scanRoutes(routes, process.cwd());
195
-
196
- // 4. route slices
197
- const slices: Record<string, RouteFile[]> = {
198
- api: tree.routes.filter((r) => r.type === "server"),
199
- ws: tree.routes.filter((r) => r.type === "server"),
200
- frontend: tree.routes.filter(
201
- (r) => r.type === "page" || r.type === "simple",
202
- ),
203
- full: [...tree.routes],
204
- };
205
-
206
- // 5. spawn workers
207
- const liveWorkers: LiveWorker[] = [];
208
- let globalIndex = 0;
209
- let nextPort = port + 1;
210
-
211
- // Total workers across every mode, known before the first spawn. A
212
- // plugin that creates a per-worker resource needs the whole picture to
213
- // divide a global budget (a connection pool of N across W workers is
214
- // N/W each) — and the index alone cannot tell it how many siblings
215
- // exist. Without this, `max: 20` silently means 20 *per worker*.
216
- const workerCount = Object.values(scale).reduce<number>(
217
- (sum, n) => sum + (n ?? 0),
218
- 0,
219
- );
220
-
221
- for (const [mode, count = 0] of Object.entries(scale)) {
222
- for (let i = 0; i < count; i++) {
223
- const workerPort = nextPort++;
224
- const descriptor: WorkerDescriptor = {
225
- mode: mode as WorkerMode,
226
- index: i + 1,
227
- globalIndex: globalIndex++,
228
- internalUrl: `http://127.0.0.1:${workerPort}`,
229
- routes: slices[mode] ?? slices.full,
230
- };
231
-
232
- const publicEnvVars: Record<string, string> = {};
233
- for (const [k, v] of Object.entries(process.env)) {
234
- if (k.startsWith("PUBLIC_") && v !== undefined) publicEnvVars[k] = v;
235
- }
236
-
237
- const workerEnv = await runWorkerSpawn(plugins, descriptor);
238
- if (workerEnv.name) descriptor.name = workerEnv.name;
239
-
240
- const env = {
241
- ...process.env,
242
- ...workerEnv.env,
243
- ...publicEnvVars,
244
- GRIMOIRE_MODE: mode,
245
- GRIMOIRE_WORKER_INDEX: String(i),
246
- // The sibling count, so a per-worker resource can divide a global
247
- // budget instead of taking the whole of it.
248
- GRIMOIRE_WORKER_COUNT: String(workerCount),
249
- GRIMOIRE_WORKER_PORT: String(workerPort),
250
- GRIMOIRE_INTERNAL_SECRET: secret,
251
- GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
252
- } as Record<string, string>;
253
-
254
- const lw: LiveWorker = {
255
- descriptor,
256
- process: null as any,
257
- port: workerPort,
258
- env,
259
- intentional: false,
260
- startedAt: 0,
261
- backoff: 500,
262
- };
263
- spawnWorker(lw);
264
- liveWorkers.push(lw);
265
- }
266
- }
267
-
268
- // 6. wait for ready
269
- await waitForWorkers(liveWorkers);
270
-
271
- // 7. onCoordinatorStart
272
- const ctx: CoordinatorContext = {
273
- workers: liveWorkers.map((w) => w.descriptor),
274
- port,
275
- secret,
276
- routes: tree,
277
- };
278
- await runHook(plugins, "onCoordinatorStart", ctx);
279
-
280
- // 8. coordinator server
281
- const server = Bun.serve({
282
- port,
283
- hostname: host,
284
- fetch: async (req) => {
285
- const url = new URL(req.url);
286
- const isWsUpgrade =
287
- req.headers.get("upgrade")?.toLowerCase() === "websocket";
288
-
289
- if (isWsUpgrade) {
290
- const descriptors = liveWorkers.map((w) => w.descriptor);
291
- const chosen =
292
- (await runRouteRequest(plugins, req, descriptors, tree)) ??
293
- defaultRoute(req, descriptors, tree);
294
-
295
- const data: WsProxyData = {
296
- workerUrl: chosen.internalUrl,
297
- pathname: url.pathname + url.search,
298
- headers: upstreamWsHeaders(
299
- req,
300
- secret,
301
- resolveClientAddress(req, server.requestIP(req)?.address),
302
- ),
303
- pending: [],
304
- };
305
- if (server.upgrade(req, { data })) {
306
- return undefined as unknown as Response;
307
- }
308
- return new Response("Upgrade Required", { status: 426 });
309
- }
310
-
311
- const locals: App.Locals = {};
312
- const descriptors = liveWorkers.map((w) => w.descriptor);
313
- const chosen =
314
- (await runRouteRequest(plugins, req, descriptors, tree)) ??
315
- defaultRoute(req, descriptors, tree);
316
- const serialized =
317
- (await runSerializeLocals(plugins, locals)) ??
318
- defaultSerialize(locals, secret);
319
- // Only the two headers the coordinator writes itself are dropped from
320
- // the client's: spread next to ours under a different case, both
321
- // reached the worker joined by a comma, and the secret check refused
322
- // the request. The rest of x-grimoire-* is the client talking to the
323
- // worker: x-grimoire-navigate asks for a page's data as JSON and
324
- // x-grimoire-form marks an enhanced submit. Dropping them made every
325
- // client-side navigation come back as a full HTML page, so the router
326
- // reloaded the document on each click.
327
- const forwardHeaders = new Headers();
328
- for (const [k, v] of req.headers) {
329
- if (!INTERNAL_HEADERS.has(k.toLowerCase())) forwardHeaders.set(k, v);
330
- }
331
- forwardHeaders.set("X-Grimoire-Locals", serialized);
332
- forwardHeaders.set("X-Grimoire-Internal", secret);
333
- // the worker sees the coordinator's connection, not the visitor's
334
- forwardHeaders.set(
335
- CLIENT_ADDRESS_HEADER,
336
- resolveClientAddress(req, server.requestIP(req)?.address),
337
- );
338
- try {
339
- return await fetch(chosen.internalUrl + url.pathname + url.search, {
340
- method: req.method,
341
- headers: forwardHeaders,
342
- body: req.body,
343
- // never follow worker redirects: a 303 from a form action must
344
- // reach the client verbatim (Set-Cookie + Location), otherwise
345
- // the coordinator silently swallows the session cookie and
346
- // returns the redirect target's HTML as a 200.
347
- redirect: "manual",
348
- });
349
- } catch {
350
- // the worker is down (it's being restarted)
351
- return new Response("Bad Gateway", {
352
- status: 502,
353
- headers: { "Retry-After": "1" },
354
- });
355
- }
356
- },
357
- websocket: {
358
- // Relay to the worker. Messages that arrive before the worker's
359
- // socket is open are queued: sending on a connecting socket throws,
360
- // and uncaught, that took the whole coordinator down.
361
- open(ws: ServerWebSocket<WsProxyData>) {
362
- const d = ws.data;
363
- const upstream = new WebSocket(
364
- d.workerUrl.replace(/^http/, "ws") + d.pathname,
365
- // Bun extension: the worker checks the internal secret on the
366
- // upgrade, and hooks need the visitor's cookies
367
- { headers: d.headers } as unknown as string[],
368
- );
369
- upstream.binaryType = "arraybuffer";
370
- upstream.onopen = () => {
371
- for (const m of d.pending) upstream.send(m);
372
- d.pending = [];
373
- };
374
- upstream.onmessage = (ev) => ws.send(ev.data);
375
- upstream.onclose = (ev) =>
376
- ws.close(ev.code === 1005 ? 1000 : ev.code, ev.reason);
377
- upstream.onerror = () => ws.close(1011);
378
- d.upstream = upstream;
379
- },
380
- message(ws: ServerWebSocket<WsProxyData>, data) {
381
- const upstream = ws.data.upstream;
382
- if (upstream?.readyState === WebSocket.OPEN) upstream.send(data);
383
- else if (upstream?.readyState === WebSocket.CONNECTING)
384
- ws.data.pending.push(data);
385
- },
386
- close(ws: ServerWebSocket<WsProxyData>) {
387
- ws.data.upstream?.close();
388
- },
389
- },
390
- });
391
-
392
- // 9. expose stop + restartAll — CLI owns process lifetime
393
- const stop = async () => {
394
- if (stopping) return;
395
- stopping = true;
396
- await runHook(plugins, "onStop", "shutdown");
397
- for (const w of liveWorkers) w.process.kill();
398
- server.stop(true);
399
- };
400
-
401
- const restartAll = () =>
402
- Promise.all(liveWorkers.map((w) => respawnWorker(w)));
403
-
404
- return {
405
- server,
406
- stop,
407
- restartAll,
408
- workers: liveWorkers.map((w) => ({
409
- name: w.descriptor.name,
410
- mode: w.descriptor.mode,
411
- port: w.port,
412
- index: w.descriptor.index,
413
- /** The worker's current process id (changes when it's respawned). */
414
- get pid() {
415
- return w.process.pid;
416
- },
417
- })),
418
- };
419
- }
420
-
421
- interface WsProxyData {
422
- workerUrl: string;
423
- pathname: string;
424
- headers: Record<string, string>;
425
- pending: (string | Buffer)[];
426
- upstream?: WebSocket;
427
- }
428
-
429
- /** Headers the coordinator sets itself; a client's copy is never forwarded. */
430
- const INTERNAL_HEADERS = new Set([
431
- "x-grimoire-locals",
432
- "x-grimoire-internal",
433
- CLIENT_ADDRESS_HEADER,
434
- ]);
435
-
436
- /** Headers for the coordinator's own socket to the worker. */
437
- function upstreamWsHeaders(
438
- req: Request,
439
- secret: string,
440
- address: string,
441
- ): Record<string, string> {
442
- const out: Record<string, string> = {};
443
- for (const [k, v] of req.headers) {
444
- const key = k.toLowerCase();
445
- // the WebSocket client writes its own handshake headers
446
- if (
447
- key.startsWith("sec-websocket-") ||
448
- INTERNAL_HEADERS.has(key) ||
449
- key === "upgrade" ||
450
- key === "connection" ||
451
- key === "host"
452
- )
453
- continue;
454
- out[k] = v;
455
- }
456
- out["X-Grimoire-Internal"] = secret;
457
- out[CLIENT_ADDRESS_HEADER] = address;
458
- return out;
459
- }
460
-
461
- function defaultSerialize(locals: App.Locals, secret: string): string {
462
- const payload = JSON.stringify(locals);
463
- const sig = new Bun.CryptoHasher("sha256")
464
- .update(secret + payload)
465
- .digest("hex");
466
- return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
467
- }
468
-
469
- function _defaultDeserialize(raw: string, secret: string): App.Locals {
470
- const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
471
- const expected = new Bun.CryptoHasher("sha256")
472
- .update(secret + payload)
473
- .digest("hex");
474
- if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
475
- return JSON.parse(payload);
476
- }
1
+ import { join } from "node:path";
2
+ import { type ServerWebSocket, type Subprocess, spawn } from "bun";
3
+ import { assertRequiredEnv } from "../env/required";
4
+ import { log } from "../logger/instance";
5
+ import { matchRoute } from "../routing/router";
6
+ import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
7
+ import type {
8
+ CoordinatorContext,
9
+ GrimoireConfig,
10
+ GrimoirePlugin,
11
+ PluginContext,
12
+ WorkerDescriptor,
13
+ WorkerMode,
14
+ } from "../types";
15
+ import { buildProject } from "./build";
16
+ import { CLIENT_ADDRESS_HEADER, resolveClientAddress } from "./client-address";
17
+ import {
18
+ runHook,
19
+ runRouteRequest,
20
+ runSerializeLocals,
21
+ runWorkerSpawn,
22
+ } from "./plugins";
23
+
24
+ const logger = log.scope("loom");
25
+
26
+ async function waitForWorkers(
27
+ workers: LiveWorker[],
28
+ timeoutMs = 10_000,
29
+ ): Promise<void> {
30
+ const ready = new Set<number>();
31
+ const start = Date.now();
32
+ while (ready.size < workers.length) {
33
+ if (Date.now() - start > timeoutMs) {
34
+ const pending = workers
35
+ .filter((w) => !ready.has(w.descriptor.globalIndex))
36
+ .map(
37
+ (w) =>
38
+ w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
39
+ )
40
+ .join(", ");
41
+ throw new Error(`Grimoire: workers timed out: ${pending}`);
42
+ }
43
+ for (const w of workers) {
44
+ if (!ready.has(w.descriptor.globalIndex) && w.descriptor.pid != null) {
45
+ ready.add(w.descriptor.globalIndex);
46
+ }
47
+ }
48
+ await Bun.sleep(50);
49
+ }
50
+ }
51
+
52
+ function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
53
+ const idx = roundRobinCounter++ % workers.length;
54
+ return workers[idx];
55
+ }
56
+ let roundRobinCounter = 0;
57
+
58
+ function consistentHash(
59
+ req: Request,
60
+ workers: WorkerDescriptor[],
61
+ ): WorkerDescriptor {
62
+ const key = req.headers.get("cookie") ?? req.url;
63
+ let hash = 0;
64
+ for (let i = 0; i < key.length; i++)
65
+ hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
66
+ return workers[hash % workers.length];
67
+ }
68
+
69
+ function defaultRoute(
70
+ req: Request,
71
+ workers: WorkerDescriptor[],
72
+ tree: RouteTree,
73
+ ): WorkerDescriptor {
74
+ const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
75
+ if (isWs) {
76
+ const ws = workers.filter((w) => w.mode === "ws" || w.mode === "full");
77
+ if (ws.length) return consistentHash(req, ws);
78
+ }
79
+ const url = new URL(req.url);
80
+ const matched = matchRoute(tree, url);
81
+ if (matched?.route.type === "server") {
82
+ const api = workers.filter((w) => w.mode === "api" || w.mode === "full");
83
+ if (api.length) return roundRobin(api);
84
+ }
85
+ const frontend = workers.filter(
86
+ (w) => w.mode === "frontend" || w.mode === "full",
87
+ );
88
+ if (frontend.length) return roundRobin(frontend);
89
+ return workers[0];
90
+ }
91
+
92
+ export interface ScaleSpec {
93
+ api?: number;
94
+ frontend?: number;
95
+ ws?: number;
96
+ [mode: string]: number | undefined;
97
+ }
98
+
99
+ export interface CoordinatorOptions {
100
+ config: GrimoireConfig;
101
+ plugins: GrimoirePlugin[];
102
+ scale: ScaleSpec;
103
+ noBuild: boolean;
104
+ }
105
+
106
+ interface LiveWorker {
107
+ descriptor: WorkerDescriptor;
108
+ process: Subprocess;
109
+ port: number;
110
+ env: Record<string, string>;
111
+ intentional: boolean;
112
+ /** When the current process was spawned, and the next restart delay. */
113
+ startedAt: number;
114
+ backoff: number;
115
+ }
116
+
117
+ export async function startCoordinator(options: CoordinatorOptions) {
118
+ const { config, plugins, scale, noBuild } = options;
119
+ const { port = 3000, host = "localhost", routes = "src/routes" } = config;
120
+ let stopping = false;
121
+
122
+ const workerEntry = join(import.meta.dir, "./worker.ts");
123
+
124
+ // ── inner helpers (close over plugins/stopping/workerEntry) ──
125
+
126
+ function spawnWorker(lw: LiveWorker): void {
127
+ const proc = spawn(["bun", "run", workerEntry], {
128
+ env: lw.env,
129
+ ipc(message) {
130
+ if (message?.ready) {
131
+ lw.descriptor.pid = proc.pid;
132
+ runHook(plugins, "onWorkerReady", lw.descriptor);
133
+ }
134
+ },
135
+ onExit(_, exitCode) {
136
+ if (lw.intentional) {
137
+ lw.intentional = false;
138
+ return;
139
+ }
140
+ lw.descriptor.pid = undefined;
141
+ runHook(
142
+ plugins,
143
+ "onWorkerDeath",
144
+ lw.descriptor,
145
+ stopping ? "intentional" : "crash",
146
+ );
147
+ if (stopping) return;
148
+ // a worker that stayed up a while starts over at one second; one
149
+ // that keeps dying on startup waits longer each time, up to 30s
150
+ const upFor = Date.now() - lw.startedAt;
151
+ lw.backoff = upFor > 30_000 ? 1_000 : Math.min(lw.backoff * 2, 30_000);
152
+ logger.error(
153
+ `worker ${lw.descriptor.name ?? `${lw.descriptor.mode}-${lw.descriptor.index}`} crashed (exit ${exitCode}), respawning in ${lw.backoff / 1000}s`,
154
+ );
155
+ setTimeout(() => {
156
+ if (!stopping) spawnWorker(lw);
157
+ }, lw.backoff);
158
+ },
159
+ });
160
+ lw.process = proc;
161
+ lw.startedAt = Date.now();
162
+ }
163
+
164
+ async function respawnWorker(lw: LiveWorker): Promise<void> {
165
+ lw.intentional = true;
166
+ lw.process.kill();
167
+ lw.descriptor.pid = undefined;
168
+ spawnWorker(lw);
169
+ await waitForWorkers([lw]);
170
+ }
171
+
172
+ // 0. plugin resolution
173
+ const pluginCtx: PluginContext = {
174
+ mode: config.dev ? "development" : "production",
175
+ plugins: new Map(plugins.map((p) => [p.name, p])),
176
+ logger: log.scope("plugins"),
177
+ };
178
+ await runHook(plugins, "onPluginsResolved", pluginCtx);
179
+
180
+ // Before the build and before any worker exists: one error in the
181
+ // terminal beats N workers each failing and being respawned.
182
+ assertRequiredEnv(config);
183
+
184
+ // 1. build
185
+ if (!noBuild) {
186
+ const { result } = await buildProject(config, plugins);
187
+ if (!result.success) throw new Error("Grimoire: build failed");
188
+ }
189
+
190
+ // 2. ephemeral secret
191
+ const secret = crypto.randomUUID() + crypto.randomUUID();
192
+
193
+ // 3. scan routes
194
+ const tree = await scanRoutes(routes, process.cwd());
195
+
196
+ // 4. route slices
197
+ const slices: Record<string, RouteFile[]> = {
198
+ api: tree.routes.filter((r) => r.type === "server"),
199
+ ws: tree.routes.filter((r) => r.type === "server"),
200
+ frontend: tree.routes.filter(
201
+ (r) => r.type === "page" || r.type === "simple",
202
+ ),
203
+ full: [...tree.routes],
204
+ };
205
+
206
+ // 5. spawn workers
207
+ const liveWorkers: LiveWorker[] = [];
208
+ let globalIndex = 0;
209
+ let nextPort = port + 1;
210
+
211
+ // Total workers across every mode, known before the first spawn. A
212
+ // plugin that creates a per-worker resource needs the whole picture to
213
+ // divide a global budget (a connection pool of N across W workers is
214
+ // N/W each) — and the index alone cannot tell it how many siblings
215
+ // exist. Without this, `max: 20` silently means 20 *per worker*.
216
+ const workerCount = Object.values(scale).reduce<number>(
217
+ (sum, n) => sum + (n ?? 0),
218
+ 0,
219
+ );
220
+
221
+ for (const [mode, count = 0] of Object.entries(scale)) {
222
+ for (let i = 0; i < count; i++) {
223
+ const workerPort = nextPort++;
224
+ const descriptor: WorkerDescriptor = {
225
+ mode: mode as WorkerMode,
226
+ index: i + 1,
227
+ globalIndex: globalIndex++,
228
+ internalUrl: `http://127.0.0.1:${workerPort}`,
229
+ routes: slices[mode] ?? slices.full,
230
+ };
231
+
232
+ const publicEnvVars: Record<string, string> = {};
233
+ for (const [k, v] of Object.entries(process.env)) {
234
+ if (k.startsWith("PUBLIC_") && v !== undefined) publicEnvVars[k] = v;
235
+ }
236
+
237
+ const workerEnv = await runWorkerSpawn(plugins, descriptor);
238
+ if (workerEnv.name) descriptor.name = workerEnv.name;
239
+
240
+ const env = {
241
+ ...process.env,
242
+ ...workerEnv.env,
243
+ ...publicEnvVars,
244
+ GRIMOIRE_MODE: mode,
245
+ GRIMOIRE_WORKER_INDEX: String(i),
246
+ // The sibling count, so a per-worker resource can divide a global
247
+ // budget instead of taking the whole of it.
248
+ GRIMOIRE_WORKER_COUNT: String(workerCount),
249
+ GRIMOIRE_WORKER_PORT: String(workerPort),
250
+ GRIMOIRE_INTERNAL_SECRET: secret,
251
+ GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
252
+ } as Record<string, string>;
253
+
254
+ const lw: LiveWorker = {
255
+ descriptor,
256
+ process: null as any,
257
+ port: workerPort,
258
+ env,
259
+ intentional: false,
260
+ startedAt: 0,
261
+ backoff: 500,
262
+ };
263
+ spawnWorker(lw);
264
+ liveWorkers.push(lw);
265
+ }
266
+ }
267
+
268
+ // 6. wait for ready
269
+ await waitForWorkers(liveWorkers);
270
+
271
+ // 7. onCoordinatorStart
272
+ const ctx: CoordinatorContext = {
273
+ workers: liveWorkers.map((w) => w.descriptor),
274
+ port,
275
+ secret,
276
+ routes: tree,
277
+ };
278
+ await runHook(plugins, "onCoordinatorStart", ctx);
279
+
280
+ // 8. coordinator server
281
+ const server = Bun.serve({
282
+ port,
283
+ hostname: host,
284
+ // the workers get the same two from the config they're spawned with
285
+ idleTimeout: config.idleTimeout,
286
+ maxRequestBodySize: config.maxRequestBodySize,
287
+ fetch: async (req) => {
288
+ const url = new URL(req.url);
289
+ const isWsUpgrade =
290
+ req.headers.get("upgrade")?.toLowerCase() === "websocket";
291
+
292
+ if (isWsUpgrade) {
293
+ const descriptors = liveWorkers.map((w) => w.descriptor);
294
+ const chosen =
295
+ (await runRouteRequest(plugins, req, descriptors, tree)) ??
296
+ defaultRoute(req, descriptors, tree);
297
+
298
+ const data: WsProxyData = {
299
+ workerUrl: chosen.internalUrl,
300
+ pathname: url.pathname + url.search,
301
+ headers: upstreamWsHeaders(
302
+ req,
303
+ secret,
304
+ resolveClientAddress(req, server.requestIP(req)?.address),
305
+ ),
306
+ pending: [],
307
+ };
308
+ if (server.upgrade(req, { data })) {
309
+ return undefined as unknown as Response;
310
+ }
311
+ return new Response("Upgrade Required", { status: 426 });
312
+ }
313
+
314
+ const locals: App.Locals = {};
315
+ const descriptors = liveWorkers.map((w) => w.descriptor);
316
+ const chosen =
317
+ (await runRouteRequest(plugins, req, descriptors, tree)) ??
318
+ defaultRoute(req, descriptors, tree);
319
+ const serialized =
320
+ (await runSerializeLocals(plugins, locals)) ??
321
+ defaultSerialize(locals, secret);
322
+ // Only the two headers the coordinator writes itself are dropped from
323
+ // the client's: spread next to ours under a different case, both
324
+ // reached the worker joined by a comma, and the secret check refused
325
+ // the request. The rest of x-grimoire-* is the client talking to the
326
+ // worker: x-grimoire-navigate asks for a page's data as JSON and
327
+ // x-grimoire-form marks an enhanced submit. Dropping them made every
328
+ // client-side navigation come back as a full HTML page, so the router
329
+ // reloaded the document on each click.
330
+ const forwardHeaders = new Headers();
331
+ for (const [k, v] of req.headers) {
332
+ if (!INTERNAL_HEADERS.has(k.toLowerCase())) forwardHeaders.set(k, v);
333
+ }
334
+ forwardHeaders.set("X-Grimoire-Locals", serialized);
335
+ forwardHeaders.set("X-Grimoire-Internal", secret);
336
+ // the worker sees the coordinator's connection, not the visitor's
337
+ forwardHeaders.set(
338
+ CLIENT_ADDRESS_HEADER,
339
+ resolveClientAddress(req, server.requestIP(req)?.address),
340
+ );
341
+ try {
342
+ return await fetch(chosen.internalUrl + url.pathname + url.search, {
343
+ method: req.method,
344
+ headers: forwardHeaders,
345
+ body: req.body,
346
+ // never follow worker redirects: a 303 from a form action must
347
+ // reach the client verbatim (Set-Cookie + Location), otherwise
348
+ // the coordinator silently swallows the session cookie and
349
+ // returns the redirect target's HTML as a 200.
350
+ redirect: "manual",
351
+ });
352
+ } catch {
353
+ // the worker is down (it's being restarted)
354
+ return new Response("Bad Gateway", {
355
+ status: 502,
356
+ headers: { "Retry-After": "1" },
357
+ });
358
+ }
359
+ },
360
+ websocket: {
361
+ // Relay to the worker. Messages that arrive before the worker's
362
+ // socket is open are queued: sending on a connecting socket throws,
363
+ // and uncaught, that took the whole coordinator down.
364
+ open(ws: ServerWebSocket<WsProxyData>) {
365
+ const d = ws.data;
366
+ const upstream = new WebSocket(
367
+ d.workerUrl.replace(/^http/, "ws") + d.pathname,
368
+ // Bun extension: the worker checks the internal secret on the
369
+ // upgrade, and hooks need the visitor's cookies
370
+ { headers: d.headers } as unknown as string[],
371
+ );
372
+ upstream.binaryType = "arraybuffer";
373
+ upstream.onopen = () => {
374
+ for (const m of d.pending) upstream.send(m);
375
+ d.pending = [];
376
+ };
377
+ upstream.onmessage = (ev) => ws.send(ev.data);
378
+ upstream.onclose = (ev) =>
379
+ ws.close(ev.code === 1005 ? 1000 : ev.code, ev.reason);
380
+ upstream.onerror = () => ws.close(1011);
381
+ d.upstream = upstream;
382
+ },
383
+ message(ws: ServerWebSocket<WsProxyData>, data) {
384
+ const upstream = ws.data.upstream;
385
+ if (upstream?.readyState === WebSocket.OPEN) upstream.send(data);
386
+ else if (upstream?.readyState === WebSocket.CONNECTING)
387
+ ws.data.pending.push(data);
388
+ },
389
+ close(ws: ServerWebSocket<WsProxyData>) {
390
+ ws.data.upstream?.close();
391
+ },
392
+ },
393
+ });
394
+
395
+ // 9. expose stop + restartAll — CLI owns process lifetime
396
+ const stop = async () => {
397
+ if (stopping) return;
398
+ stopping = true;
399
+ await runHook(plugins, "onStop", "shutdown");
400
+ for (const w of liveWorkers) w.process.kill();
401
+ server.stop(true);
402
+ };
403
+
404
+ const restartAll = () =>
405
+ Promise.all(liveWorkers.map((w) => respawnWorker(w)));
406
+
407
+ return {
408
+ server,
409
+ stop,
410
+ restartAll,
411
+ workers: liveWorkers.map((w) => ({
412
+ name: w.descriptor.name,
413
+ mode: w.descriptor.mode,
414
+ port: w.port,
415
+ index: w.descriptor.index,
416
+ /** The worker's current process id (changes when it's respawned). */
417
+ get pid() {
418
+ return w.process.pid;
419
+ },
420
+ })),
421
+ };
422
+ }
423
+
424
+ interface WsProxyData {
425
+ workerUrl: string;
426
+ pathname: string;
427
+ headers: Record<string, string>;
428
+ pending: (string | Buffer)[];
429
+ upstream?: WebSocket;
430
+ }
431
+
432
+ /** Headers the coordinator sets itself; a client's copy is never forwarded. */
433
+ const INTERNAL_HEADERS = new Set([
434
+ "x-grimoire-locals",
435
+ "x-grimoire-internal",
436
+ CLIENT_ADDRESS_HEADER,
437
+ ]);
438
+
439
+ /** Headers for the coordinator's own socket to the worker. */
440
+ function upstreamWsHeaders(
441
+ req: Request,
442
+ secret: string,
443
+ address: string,
444
+ ): Record<string, string> {
445
+ const out: Record<string, string> = {};
446
+ for (const [k, v] of req.headers) {
447
+ const key = k.toLowerCase();
448
+ // the WebSocket client writes its own handshake headers
449
+ if (
450
+ key.startsWith("sec-websocket-") ||
451
+ INTERNAL_HEADERS.has(key) ||
452
+ key === "upgrade" ||
453
+ key === "connection" ||
454
+ key === "host"
455
+ )
456
+ continue;
457
+ out[k] = v;
458
+ }
459
+ out["X-Grimoire-Internal"] = secret;
460
+ out[CLIENT_ADDRESS_HEADER] = address;
461
+ return out;
462
+ }
463
+
464
+ function defaultSerialize(locals: App.Locals, secret: string): string {
465
+ const payload = JSON.stringify(locals);
466
+ const sig = new Bun.CryptoHasher("sha256")
467
+ .update(secret + payload)
468
+ .digest("hex");
469
+ return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
470
+ }
471
+
472
+ function _defaultDeserialize(raw: string, secret: string): App.Locals {
473
+ const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
474
+ const expected = new Bun.CryptoHasher("sha256")
475
+ .update(secret + payload)
476
+ .digest("hex");
477
+ if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
478
+ return JSON.parse(payload);
479
+ }