@sigil-dev/grimoire 0.9.21 → 0.9.23

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