@sigil-dev/grimoire 0.8.6 → 0.9.1

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.
@@ -1,272 +1,356 @@
1
1
  import { join } from "node:path";
2
2
  import { type Subprocess, spawn } from "bun";
3
+ import { log } from "../logger/instance";
3
4
  import { matchRoute } from "../routing/router";
4
5
  import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
5
6
  import type {
6
- CoordinatorContext,
7
- GrimoireConfig,
8
- GrimoirePlugin,
9
- WorkerDescriptor,
10
- WorkerMode,
7
+ CoordinatorContext,
8
+ GrimoireConfig,
9
+ GrimoirePlugin, PluginContext,
10
+ WorkerDescriptor,
11
+ WorkerMode,
11
12
  } from "../types";
12
13
  import { buildProject } from "./build";
13
14
  import {
14
- runHook,
15
- runRouteRequest,
16
- runSerializeLocals,
17
- runWorkerSpawn,
15
+ runHook,
16
+ runRouteRequest,
17
+ runSerializeLocals,
18
+ runWorkerSpawn,
18
19
  } from "./plugins";
19
- import { log } from "../logger/instance";
20
20
 
21
- const logger = log.scope("loom")
21
+ const logger = log.scope("loom");
22
22
 
23
23
  async function waitForWorkers(
24
- workers: LiveWorker[],
25
- timeoutMs = 10_000,
24
+ workers: LiveWorker[],
25
+ timeoutMs = 10_000,
26
26
  ): Promise<void> {
27
- const ready = new Set<number>();
28
- const start = Date.now();
29
- while (ready.size < workers.length) {
30
- if (Date.now() - start > timeoutMs) {
31
- const pending = workers
32
- .filter((w) => !ready.has(w.descriptor.globalIndex))
33
- .map((w) => w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`)
34
- .join(", ");
35
- throw new Error(`Grimoire: workers timed out: ${pending}`);
36
- }
37
- for (const w of workers) {
38
- if (!ready.has(w.descriptor.globalIndex) && w.descriptor.pid != null) {
39
- ready.add(w.descriptor.globalIndex);
40
- }
41
- }
42
- await Bun.sleep(50);
43
- }
27
+ const ready = new Set<number>();
28
+ const start = Date.now();
29
+ while (ready.size < workers.length) {
30
+ if (Date.now() - start > timeoutMs) {
31
+ const pending = workers
32
+ .filter((w) => !ready.has(w.descriptor.globalIndex))
33
+ .map(
34
+ (w) =>
35
+ w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
36
+ )
37
+ .join(", ");
38
+ throw new Error(`Grimoire: workers timed out: ${pending}`);
39
+ }
40
+ for (const w of workers) {
41
+ if (!ready.has(w.descriptor.globalIndex) && w.descriptor.pid != null) {
42
+ ready.add(w.descriptor.globalIndex);
43
+ }
44
+ }
45
+ await Bun.sleep(50);
46
+ }
44
47
  }
45
48
 
46
49
  function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
47
- const idx = roundRobinCounter++ % workers.length;
48
- return workers[idx];
50
+ const idx = roundRobinCounter++ % workers.length;
51
+ return workers[idx];
49
52
  }
50
53
  let roundRobinCounter = 0;
51
54
 
52
- function consistentHash(req: Request, workers: WorkerDescriptor[]): WorkerDescriptor {
53
- const key = req.headers.get("cookie") ?? req.url;
54
- let hash = 0;
55
- for (let i = 0; i < key.length; i++) hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
56
- return workers[hash % workers.length];
55
+ function consistentHash(
56
+ req: Request,
57
+ workers: WorkerDescriptor[],
58
+ ): WorkerDescriptor {
59
+ const key = req.headers.get("cookie") ?? req.url;
60
+ let hash = 0;
61
+ for (let i = 0; i < key.length; i++)
62
+ hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
63
+ return workers[hash % workers.length];
57
64
  }
58
65
 
59
- function defaultRoute(req: Request, workers: WorkerDescriptor[], tree: RouteTree): WorkerDescriptor {
60
- const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
61
- if (isWs) {
62
- const ws = workers.filter((w) => w.mode === "ws" || w.mode === "full");
63
- if (ws.length) return consistentHash(req, ws);
64
- }
65
- const url = new URL(req.url);
66
- const matched = matchRoute(tree, url);
67
- if (matched?.route.type === "server") {
68
- const api = workers.filter((w) => w.mode === "api" || w.mode === "full");
69
- if (api.length) return roundRobin(api);
70
- }
71
- const frontend = workers.filter((w) => w.mode === "frontend" || w.mode === "full");
72
- if (frontend.length) return roundRobin(frontend);
73
- return workers[0];
66
+ function defaultRoute(
67
+ req: Request,
68
+ workers: WorkerDescriptor[],
69
+ tree: RouteTree,
70
+ ): WorkerDescriptor {
71
+ const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
72
+ if (isWs) {
73
+ const ws = workers.filter((w) => w.mode === "ws" || w.mode === "full");
74
+ if (ws.length) return consistentHash(req, ws);
75
+ }
76
+ const url = new URL(req.url);
77
+ const matched = matchRoute(tree, url);
78
+ if (matched?.route.type === "server") {
79
+ const api = workers.filter((w) => w.mode === "api" || w.mode === "full");
80
+ if (api.length) return roundRobin(api);
81
+ }
82
+ const frontend = workers.filter(
83
+ (w) => w.mode === "frontend" || w.mode === "full",
84
+ );
85
+ if (frontend.length) return roundRobin(frontend);
86
+ return workers[0];
74
87
  }
75
88
 
76
89
  export interface ScaleSpec {
77
- api?: number;
78
- frontend?: number;
79
- ws?: number;
80
- [mode: string]: number | undefined;
90
+ api?: number;
91
+ frontend?: number;
92
+ ws?: number;
93
+ [mode: string]: number | undefined;
81
94
  }
82
95
 
83
96
  export interface CoordinatorOptions {
84
- config: GrimoireConfig;
85
- plugins: GrimoirePlugin[];
86
- scale: ScaleSpec;
87
- noBuild: boolean;
97
+ config: GrimoireConfig;
98
+ plugins: GrimoirePlugin[];
99
+ scale: ScaleSpec;
100
+ noBuild: boolean;
88
101
  }
89
102
 
90
103
  interface LiveWorker {
91
- descriptor: WorkerDescriptor;
92
- process: Subprocess;
93
- port: number;
94
- env: Record<string, string>;
95
- intentional: boolean; // ← add
104
+ descriptor: WorkerDescriptor;
105
+ process: Subprocess;
106
+ port: number;
107
+ env: Record<string, string>;
108
+ intentional: boolean; // ← add
96
109
  }
97
110
 
98
111
  export async function startCoordinator(options: CoordinatorOptions) {
99
- const { config, plugins, scale, noBuild } = options;
100
- const { port = 3000, host = "localhost", routes = "src/routes" } = config;
101
- let stopping = false;
102
-
103
- const workerEntry = join(import.meta.dir, "./worker.ts");
104
-
105
- // ── inner helpers (close over plugins/stopping/workerEntry) ──
106
-
107
- function spawnWorker(lw: LiveWorker): void {
108
- const proc = spawn(["bun", "run", workerEntry], {
109
- env: lw.env,
110
- ipc(message) {
111
- if (message?.ready) {
112
- lw.descriptor.pid = proc.pid;
113
- runHook(plugins, "onWorkerReady", lw.descriptor);
114
- }
115
- },
116
- onExit(_, exitCode) {
117
- if (lw.intentional) {
118
- lw.intentional = false;
119
- return;
120
- }
121
- runHook(plugins, "onWorkerDeath", lw.descriptor, stopping ? "intentional" : "crash");
122
- if (!stopping) {
123
- logger.error(`worker ${lw.descriptor.name ?? `${lw.descriptor.mode}-${lw.descriptor.index}`} crashed (exit ${exitCode}), respawning...`);
124
- }
125
- },
126
- });
127
- lw.process = proc;
128
- }
129
-
130
- async function respawnWorker(lw: LiveWorker): Promise<void> {
131
- lw.intentional = true;
132
- lw.process.kill();
133
- lw.descriptor.pid = undefined;
134
- spawnWorker(lw);
135
- await waitForWorkers([lw]);
136
- }
137
-
138
- // 1. build
139
- if (!noBuild) {
140
- const { result } = await buildProject(config, plugins);
141
- if (!result.success) throw new Error("Grimoire: build failed");
142
- }
143
-
144
- // 2. ephemeral secret
145
- const secret = crypto.randomUUID() + crypto.randomUUID();
146
-
147
- // 3. scan routes
148
- const tree = await scanRoutes(routes, process.cwd());
149
-
150
- // 4. route slices
151
- const slices: Record<string, RouteFile[]> = {
152
- api: tree.routes.filter((r) => r.type === "server"),
153
- ws: tree.routes.filter((r) => r.type === "server"),
154
- frontend: tree.routes.filter((r) => r.type === "page" || r.type === "simple"),
155
- full: [...tree.routes],
156
- };
157
-
158
- // 5. spawn workers
159
- const liveWorkers: LiveWorker[] = [];
160
- let globalIndex = 0;
161
- let nextPort = port + 1;
162
-
163
- for (const [mode, count = 0] of Object.entries(scale)) {
164
- for (let i = 0; i < count; i++) {
165
- const workerPort = nextPort++;
166
- const descriptor: WorkerDescriptor = {
167
- mode: mode as WorkerMode,
168
- index: i + 1,
169
- globalIndex: globalIndex++,
170
- internalUrl: `http://127.0.0.1:${workerPort}`,
171
- routes: slices[mode] ?? slices.full,
172
- };
173
-
174
- const publicEnvVars: Record<string, string> = {};
175
- for (const [k, v] of Object.entries(process.env)) {
176
- if (k.startsWith("PUBLIC_") && v !== undefined) publicEnvVars[k] = v;
177
- }
178
-
179
- const workerEnv = await runWorkerSpawn(plugins, descriptor);
180
- if (workerEnv.name) descriptor.name = workerEnv.name;
181
-
182
- const env = {
183
- ...process.env,
184
- ...workerEnv.env,
185
- ...publicEnvVars,
186
- GRIMOIRE_MODE: mode,
187
- GRIMOIRE_WORKER_INDEX: String(i),
188
- GRIMOIRE_WORKER_PORT: String(workerPort),
189
- GRIMOIRE_INTERNAL_SECRET: secret,
190
- GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
191
- } as Record<string, string>;
192
-
193
- const lw: LiveWorker = { descriptor, process: null as any, port: workerPort, env, intentional: false };
194
- spawnWorker(lw);
195
- liveWorkers.push(lw);
196
- }
197
- }
198
-
199
- // 6. wait for ready
200
- await waitForWorkers(liveWorkers);
201
-
202
- // 7. onCoordinatorStart
203
- const ctx: CoordinatorContext = {
204
- workers: liveWorkers.map((w) => w.descriptor),
205
- port,
206
- secret,
207
- routes: tree,
208
- };
209
- await runHook(plugins, "onCoordinatorStart", ctx);
210
-
211
- // 8. coordinator server
212
- const server = Bun.serve({
213
- port,
214
- hostname: host,
215
- fetch: async (req) => {
216
- const locals: App.Locals = {};
217
- const descriptors = liveWorkers.map((w) => w.descriptor);
218
- const chosen =
219
- (await runRouteRequest(plugins, req, descriptors, tree)) ??
220
- defaultRoute(req, descriptors, tree);
221
- const serialized =
222
- (await runSerializeLocals(plugins, locals)) ??
223
- defaultSerialize(locals, secret);
224
- return fetch(chosen.internalUrl + new URL(req.url).pathname + new URL(req.url).search, {
225
- method: req.method,
226
- headers: {
227
- //@ts-expect-error shut up
228
- ...Object.fromEntries(req.headers),
229
- "X-Grimoire-Locals": serialized,
230
- "X-Grimoire-Internal": secret,
231
- },
232
- body: req.body,
233
- });
234
- },
235
- });
236
-
237
- // 9. expose stop + restartAll — CLI owns process lifetime
238
- const stop = async () => {
239
- if (stopping) return;
240
- stopping = true;
241
- await runHook(plugins, "onStop", "shutdown");
242
- for (const w of liveWorkers) w.process.kill();
243
- server.stop();
244
- };
245
-
246
- const restartAll = () => Promise.all(liveWorkers.map((w) => respawnWorker(w)));
247
-
248
- return {
249
- server,
250
- stop,
251
- restartAll,
252
- workers: liveWorkers.map((w) => ({
253
- name: w.descriptor.name,
254
- mode: w.descriptor.mode,
255
- port: w.port,
256
- index: w.descriptor.index,
257
- })),
258
- };
112
+ const { config, plugins, scale, noBuild } = options;
113
+ const { port = 3000, host = "localhost", routes = "src/routes" } = config;
114
+ let stopping = false;
115
+
116
+ const workerEntry = join(import.meta.dir, "./worker.ts");
117
+
118
+ // ── inner helpers (close over plugins/stopping/workerEntry) ──
119
+
120
+ function spawnWorker(lw: LiveWorker): void {
121
+ const proc = spawn(["bun", "run", workerEntry], {
122
+ env: lw.env,
123
+ ipc(message) {
124
+ if (message?.ready) {
125
+ lw.descriptor.pid = proc.pid;
126
+ runHook(plugins, "onWorkerReady", lw.descriptor);
127
+ }
128
+ },
129
+ onExit(_, exitCode) {
130
+ if (lw.intentional) {
131
+ lw.intentional = false;
132
+ return;
133
+ }
134
+ runHook(
135
+ plugins,
136
+ "onWorkerDeath",
137
+ lw.descriptor,
138
+ stopping ? "intentional" : "crash",
139
+ );
140
+ if (!stopping) {
141
+ logger.error(
142
+ `worker ${lw.descriptor.name ?? `${lw.descriptor.mode}-${lw.descriptor.index}`} crashed (exit ${exitCode}), respawning...`,
143
+ );
144
+ }
145
+ },
146
+ });
147
+ lw.process = proc;
148
+ }
149
+
150
+ async function respawnWorker(lw: LiveWorker): Promise<void> {
151
+ lw.intentional = true;
152
+ lw.process.kill();
153
+ lw.descriptor.pid = undefined;
154
+ spawnWorker(lw);
155
+ await waitForWorkers([lw]);
156
+ }
157
+
158
+ // 0. plugin resolution
159
+ const pluginCtx: PluginContext = {
160
+ mode: config.dev ? "development" : "production",
161
+ plugins: new Map(plugins.map((p) => [p.name, p])),
162
+ logger: log.scope("plugins"),
163
+ };
164
+ await runHook(plugins, "onPluginsResolved", pluginCtx);
165
+
166
+ // 1. build
167
+ if (!noBuild) {
168
+ const { result } = await buildProject(config, plugins);
169
+ if (!result.success) throw new Error("Grimoire: build failed");
170
+ }
171
+
172
+ // 2. ephemeral secret
173
+ const secret = crypto.randomUUID() + crypto.randomUUID();
174
+
175
+ // 3. scan routes
176
+ const tree = await scanRoutes(routes, process.cwd());
177
+
178
+ // 4. route slices
179
+ const slices: Record<string, RouteFile[]> = {
180
+ api: tree.routes.filter((r) => r.type === "server"),
181
+ ws: tree.routes.filter((r) => r.type === "server"),
182
+ frontend: tree.routes.filter(
183
+ (r) => r.type === "page" || r.type === "simple",
184
+ ),
185
+ full: [...tree.routes],
186
+ };
187
+
188
+ // 5. spawn workers
189
+ const liveWorkers: LiveWorker[] = [];
190
+ let globalIndex = 0;
191
+ let nextPort = port + 1;
192
+
193
+ for (const [mode, count = 0] of Object.entries(scale)) {
194
+ for (let i = 0; i < count; i++) {
195
+ const workerPort = nextPort++;
196
+ const descriptor: WorkerDescriptor = {
197
+ mode: mode as WorkerMode,
198
+ index: i + 1,
199
+ globalIndex: globalIndex++,
200
+ internalUrl: `http://127.0.0.1:${workerPort}`,
201
+ routes: slices[mode] ?? slices.full,
202
+ };
203
+
204
+ const publicEnvVars: Record<string, string> = {};
205
+ for (const [k, v] of Object.entries(process.env)) {
206
+ if (k.startsWith("PUBLIC_") && v !== undefined) publicEnvVars[k] = v;
207
+ }
208
+
209
+ const workerEnv = await runWorkerSpawn(plugins, descriptor);
210
+ if (workerEnv.name) descriptor.name = workerEnv.name;
211
+
212
+ const env = {
213
+ ...process.env,
214
+ ...workerEnv.env,
215
+ ...publicEnvVars,
216
+ GRIMOIRE_MODE: mode,
217
+ GRIMOIRE_WORKER_INDEX: String(i),
218
+ GRIMOIRE_WORKER_PORT: String(workerPort),
219
+ GRIMOIRE_INTERNAL_SECRET: secret,
220
+ GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
221
+ } as Record<string, string>;
222
+
223
+ const lw: LiveWorker = {
224
+ descriptor,
225
+ process: null as any,
226
+ port: workerPort,
227
+ env,
228
+ intentional: false,
229
+ };
230
+ spawnWorker(lw);
231
+ liveWorkers.push(lw);
232
+ }
233
+ }
234
+
235
+ // 6. wait for ready
236
+ await waitForWorkers(liveWorkers);
237
+
238
+ // 7. onCoordinatorStart
239
+ const ctx: CoordinatorContext = {
240
+ workers: liveWorkers.map((w) => w.descriptor),
241
+ port,
242
+ secret,
243
+ routes: tree,
244
+ };
245
+ await runHook(plugins, "onCoordinatorStart", ctx);
246
+
247
+ // 8. coordinator server
248
+ const server = Bun.serve({
249
+ port,
250
+ hostname: host,
251
+ fetch: async (req) => {
252
+ const url = new URL(req.url);
253
+ const isWsUpgrade = req.headers.get("upgrade")?.toLowerCase() === "websocket";
254
+
255
+ if (isWsUpgrade) {
256
+ const descriptors = liveWorkers.map((w) => w.descriptor);
257
+ const chosen =
258
+ (await runRouteRequest(plugins, req, descriptors, tree)) ??
259
+ defaultRoute(req, descriptors, tree);
260
+
261
+ //@ts-expect-error
262
+ if (server.upgrade(req, { data: { workerUrl: chosen.internalUrl, pathname: url.pathname + url.search } })) {
263
+ return undefined as unknown as Response;
264
+ }
265
+ return new Response("Upgrade Required", { status: 426 });
266
+ }
267
+
268
+ const locals: App.Locals = {};
269
+ const descriptors = liveWorkers.map((w) => w.descriptor);
270
+ const chosen =
271
+ (await runRouteRequest(plugins, req, descriptors, tree)) ??
272
+ defaultRoute(req, descriptors, tree);
273
+ const serialized =
274
+ (await runSerializeLocals(plugins, locals)) ??
275
+ defaultSerialize(locals, secret);
276
+ return fetch(
277
+ chosen.internalUrl + url.pathname + url.search,
278
+ {
279
+ method: req.method,
280
+ headers: {
281
+ //@ts-expect-error shut up
282
+ ...Object.fromEntries(req.headers),
283
+ "X-Grimoire-Locals": serialized,
284
+ "X-Grimoire-Internal": secret,
285
+ },
286
+ body: req.body,
287
+ },
288
+ );
289
+ },
290
+ websocket: {
291
+ open(ws) {
292
+ const upstream = new WebSocket(
293
+ //@ts-expect-error we give it data upstream
294
+ ws.data.workerUrl.replace("http://", "ws://").replace("https://", "wss://") +
295
+ //@ts-expect-error we give it data upstream
296
+ ws.data.pathname
297
+ );
298
+ upstream.onmessage = (ev) => ws.send(ev.data);
299
+ upstream.onclose = () => ws.close();
300
+ upstream.onerror = () => ws.close();
301
+ //@ts-expect-error we give it data upstream
302
+ ws.data.upstream = upstream;
303
+ },
304
+ message(ws, data) {
305
+ //@ts-expect-error we give it data upstream
306
+ ws.data.upstream?.send(data);
307
+ },
308
+ close(ws) {
309
+ //@ts-expect-error we give it data upstream
310
+ ws.data.upstream?.close();
311
+ },
312
+ drain(ws) {},
313
+ },
314
+ });
315
+
316
+ // 9. expose stop + restartAll — CLI owns process lifetime
317
+ const stop = async () => {
318
+ if (stopping) return;
319
+ stopping = true;
320
+ await runHook(plugins, "onStop", "shutdown");
321
+ for (const w of liveWorkers) w.process.kill();
322
+ server.stop();
323
+ };
324
+
325
+ const restartAll = () =>
326
+ Promise.all(liveWorkers.map((w) => respawnWorker(w)));
327
+
328
+ return {
329
+ server,
330
+ stop,
331
+ restartAll,
332
+ workers: liveWorkers.map((w) => ({
333
+ name: w.descriptor.name,
334
+ mode: w.descriptor.mode,
335
+ port: w.port,
336
+ index: w.descriptor.index,
337
+ })),
338
+ };
259
339
  }
260
340
 
261
341
  function defaultSerialize(locals: App.Locals, secret: string): string {
262
- const payload = JSON.stringify(locals);
263
- const sig = new Bun.CryptoHasher("sha256").update(secret + payload).digest("hex");
264
- return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
342
+ const payload = JSON.stringify(locals);
343
+ const sig = new Bun.CryptoHasher("sha256")
344
+ .update(secret + payload)
345
+ .digest("hex");
346
+ return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
265
347
  }
266
348
 
267
349
  function _defaultDeserialize(raw: string, secret: string): App.Locals {
268
- const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
269
- const expected = new Bun.CryptoHasher("sha256").update(secret + payload).digest("hex");
270
- if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
271
- return JSON.parse(payload);
350
+ const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
351
+ const expected = new Bun.CryptoHasher("sha256")
352
+ .update(secret + payload)
353
+ .digest("hex");
354
+ if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
355
+ return JSON.parse(payload);
272
356
  }