@sigil-dev/grimoire 0.8.5 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,11 +1,12 @@
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
7
  CoordinatorContext,
7
8
  GrimoireConfig,
8
- GrimoirePlugin,
9
+ GrimoirePlugin, PluginContext,
9
10
  WorkerDescriptor,
10
11
  WorkerMode,
11
12
  } from "../types";
@@ -17,13 +18,14 @@ import {
17
18
  runWorkerSpawn,
18
19
  } from "./plugins";
19
20
 
21
+ const logger = log.scope("loom");
22
+
20
23
  async function waitForWorkers(
21
24
  workers: LiveWorker[],
22
25
  timeoutMs = 10_000,
23
26
  ): Promise<void> {
24
27
  const ready = new Set<number>();
25
28
  const start = Date.now();
26
-
27
29
  while (ready.size < workers.length) {
28
30
  if (Date.now() - start > timeoutMs) {
29
31
  const pending = workers
@@ -33,13 +35,10 @@ async function waitForWorkers(
33
35
  w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
34
36
  )
35
37
  .join(", ");
36
- throw new Error(
37
- `Grimoire: workers timed out waiting to become ready: ${pending}`,
38
- );
38
+ throw new Error(`Grimoire: workers timed out: ${pending}`);
39
39
  }
40
40
  for (const w of workers) {
41
- if (ready.has(w.descriptor.globalIndex)) continue;
42
- if (w.descriptor.pid != null) {
41
+ if (!ready.has(w.descriptor.globalIndex) && w.descriptor.pid != null) {
43
42
  ready.add(w.descriptor.globalIndex);
44
43
  }
45
44
  }
@@ -59,9 +58,8 @@ function consistentHash(
59
58
  ): WorkerDescriptor {
60
59
  const key = req.headers.get("cookie") ?? req.url;
61
60
  let hash = 0;
62
- for (let i = 0; i < key.length; i++) {
61
+ for (let i = 0; i < key.length; i++)
63
62
  hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
64
- }
65
63
  return workers[hash % workers.length];
66
64
  }
67
65
 
@@ -71,30 +69,20 @@ function defaultRoute(
71
69
  tree: RouteTree,
72
70
  ): WorkerDescriptor {
73
71
  const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
74
-
75
72
  if (isWs) {
76
- const wsWorkers = workers.filter(
77
- (w) => w.mode === "ws" || w.mode === "full",
78
- );
79
- if (wsWorkers.length) return consistentHash(req, wsWorkers);
73
+ const ws = workers.filter((w) => w.mode === "ws" || w.mode === "full");
74
+ if (ws.length) return consistentHash(req, ws);
80
75
  }
81
-
82
76
  const url = new URL(req.url);
83
77
  const matched = matchRoute(tree, url);
84
-
85
78
  if (matched?.route.type === "server") {
86
- const apiWorkers = workers.filter(
87
- (w) => w.mode === "api" || w.mode === "full",
88
- );
89
- if (apiWorkers.length) return roundRobin(apiWorkers);
79
+ const api = workers.filter((w) => w.mode === "api" || w.mode === "full");
80
+ if (api.length) return roundRobin(api);
90
81
  }
91
-
92
- const frontendWorkers = workers.filter(
82
+ const frontend = workers.filter(
93
83
  (w) => w.mode === "frontend" || w.mode === "full",
94
84
  );
95
- if (frontendWorkers.length) return roundRobin(frontendWorkers);
96
-
97
- // fallback — should not happen if scale spec is valid
85
+ if (frontend.length) return roundRobin(frontend);
98
86
  return workers[0];
99
87
  }
100
88
 
@@ -116,6 +104,8 @@ interface LiveWorker {
116
104
  descriptor: WorkerDescriptor;
117
105
  process: Subprocess;
118
106
  port: number;
107
+ env: Record<string, string>;
108
+ intentional: boolean; // ← add
119
109
  }
120
110
 
121
111
  export async function startCoordinator(options: CoordinatorOptions) {
@@ -123,20 +113,69 @@ export async function startCoordinator(options: CoordinatorOptions) {
123
113
  const { port = 3000, host = "localhost", routes = "src/routes" } = config;
124
114
  let stopping = false;
125
115
 
126
- // 1. build if needed
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
127
167
  if (!noBuild) {
128
168
  const { result } = await buildProject(config, plugins);
129
169
  if (!result.success) throw new Error("Grimoire: build failed");
130
170
  }
131
171
 
132
- // 2. generate ephemeral secret
133
- const secret = crypto.randomUUID() + crypto.randomUUID(); // 72 hex chars
172
+ // 2. ephemeral secret
173
+ const secret = crypto.randomUUID() + crypto.randomUUID();
134
174
 
135
- // 3. scan routes once — coordinator owns the route tree
136
- const routesDir = /* resolve */ routes;
137
- const tree = await scanRoutes(routesDir, process.cwd());
175
+ // 3. scan routes
176
+ const tree = await scanRoutes(routes, process.cwd());
138
177
 
139
- // 4. derive route slices per mode
178
+ // 4. route slices
140
179
  const slices: Record<string, RouteFile[]> = {
141
180
  api: tree.routes.filter((r) => r.type === "server"),
142
181
  ws: tree.routes.filter((r) => r.type === "server"),
@@ -162,64 +201,41 @@ export async function startCoordinator(options: CoordinatorOptions) {
162
201
  routes: slices[mode] ?? slices.full,
163
202
  };
164
203
 
165
- // let plugins inject env and name
166
- const workerEnv = await runWorkerSpawn(plugins, descriptor);
167
- const workerEntry = join(import.meta.dir, "./worker.ts");
168
- if (workerEnv.name) descriptor.name = workerEnv.name;
169
-
170
- // Inject env vars prefixed with PUBLIC_ so they're available to client bundles
171
204
  const publicEnvVars: Record<string, string> = {};
172
- for (const [key, value] of Object.entries(process.env)) {
173
- if (key.startsWith("PUBLIC_") && value !== undefined) {
174
- publicEnvVars[key] = value;
175
- }
205
+ for (const [k, v] of Object.entries(process.env)) {
206
+ if (k.startsWith("PUBLIC_") && v !== undefined) publicEnvVars[k] = v;
176
207
  }
177
208
 
178
- const proc = spawn(["bun", "run", workerEntry], {
179
- env: {
180
- ...process.env,
181
- ...workerEnv.env,
182
- ...publicEnvVars,
183
- GRIMOIRE_MODE: mode,
184
- GRIMOIRE_WORKER_INDEX: String(i),
185
- GRIMOIRE_WORKER_PORT: String(workerPort),
186
- GRIMOIRE_INTERNAL_SECRET: secret,
187
- GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
188
- },
189
- ipc(message) {
190
- // worker sends { ready: true } when Bun.serve is up
191
- if (message?.ready) {
192
- descriptor.pid = proc.pid;
193
- runHook(plugins, "onWorkerReady", descriptor);
194
- }
195
- },
196
- onExit(_proc, exitCode) {
197
- const intentional = stopping;
198
- runHook(
199
- plugins,
200
- "onWorkerDeath",
201
- descriptor,
202
- intentional ? "intentional" : "crash",
203
- );
204
- if (!intentional) {
205
- console.error(
206
- `[grimoire] worker ${descriptor.name ?? `${descriptor.mode}-${descriptor.index}`} crashed (exit ${exitCode}), respawning...`,
207
- );
208
- // respawn: same descriptor, same port
209
- // (simplified — plugin-scale can override this behavior)
210
- }
211
- },
212
- });
209
+ const workerEnv = await runWorkerSpawn(plugins, descriptor);
210
+ if (workerEnv.name) descriptor.name = workerEnv.name;
213
211
 
214
- liveWorkers.push({ descriptor, process: proc, port: workerPort });
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);
215
232
  }
216
233
  }
217
234
 
218
- // 6. wait for all workers ready (with timeout)
219
- // workers send IPC { ready: true } — coordinator waits up to 10s
235
+ // 6. wait for ready
220
236
  await waitForWorkers(liveWorkers);
221
237
 
222
- // 7. fire onCoordinatorStart
238
+ // 7. onCoordinatorStart
223
239
  const ctx: CoordinatorContext = {
224
240
  workers: liveWorkers.map((w) => w.descriptor),
225
241
  port,
@@ -228,56 +244,91 @@ export async function startCoordinator(options: CoordinatorOptions) {
228
244
  };
229
245
  await runHook(plugins, "onCoordinatorStart", ctx);
230
246
 
231
- // 8. start coordinator Bun.serve
232
-
247
+ // 8. coordinator server
233
248
  const server = Bun.serve({
234
249
  port,
235
250
  hostname: host,
236
251
  fetch: async (req) => {
237
- // run hooks.server.ts to populate locals
238
- const locals: App.Locals = {};
239
- // ... same handle() chain as createServer but resolve() just
240
- // forwards instead of rendering
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
+ }
241
267
 
242
- // pick worker
268
+ const locals: App.Locals = {};
243
269
  const descriptors = liveWorkers.map((w) => w.descriptor);
244
270
  const chosen =
245
271
  (await runRouteRequest(plugins, req, descriptors, tree)) ??
246
272
  defaultRoute(req, descriptors, tree);
247
-
248
- // serialize locals
249
273
  const serialized =
250
274
  (await runSerializeLocals(plugins, locals)) ??
251
275
  defaultSerialize(locals, secret);
252
-
253
- // forward
254
- return fetch(chosen.internalUrl + new URL(req.url).pathname, {
255
- method: req.method,
256
- headers: {
257
- //@ts-expect-error shut Up
258
- ...Object.fromEntries(req.headers),
259
- "X-Grimoire-Locals": serialized,
260
- "X-Grimoire-Internal": 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,
261
287
  },
262
- body: req.body,
263
- });
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) {},
264
313
  },
265
314
  });
266
315
 
267
- // 9. shutdown
268
- const handleShutdown = async () => {
316
+ // 9. expose stop + restartAll — CLI owns process lifetime
317
+ const stop = async () => {
269
318
  if (stopping) return;
270
319
  stopping = true;
271
320
  await runHook(plugins, "onStop", "shutdown");
272
321
  for (const w of liveWorkers) w.process.kill();
273
322
  server.stop();
274
- process.exit(0);
275
323
  };
276
- process.on("SIGINT", handleShutdown);
277
- process.on("SIGTERM", handleShutdown);
324
+
325
+ const restartAll = () =>
326
+ Promise.all(liveWorkers.map((w) => respawnWorker(w)));
278
327
 
279
328
  return {
280
329
  server,
330
+ stop,
331
+ restartAll,
281
332
  workers: liveWorkers.map((w) => ({
282
333
  name: w.descriptor.name,
283
334
  mode: w.descriptor.mode,
@@ -355,7 +355,13 @@ export async function createServer(config: GrimoireConfig = {}) {
355
355
  );
356
356
  };
357
357
  }
358
-
358
+ const patchedFetch: typeof fetch = (input, init) => {
359
+ const resolved =
360
+ typeof input === "string" && input.startsWith("/")
361
+ ? new URL(input, url.origin).toString()
362
+ : input;
363
+ return globalThis.fetch(resolved as any, init);
364
+ };
359
365
  const resolve: ResolveFunction = async (evt) => {
360
366
  // matching happens here — after handle() has run
361
367
  const matched = matchRoute(tree, evt.url);
@@ -454,6 +460,7 @@ export async function createServer(config: GrimoireConfig = {}) {
454
460
  params: matched.params,
455
461
  url: evt.url,
456
462
  locals: evt.locals,
463
+ fetch: patchedFetch,
457
464
  });
458
465
  } catch (e) {
459
466
  if (isRedirectResult(e)) {
@@ -521,6 +528,7 @@ export async function createServer(config: GrimoireConfig = {}) {
521
528
  plugins,
522
529
  cspNonce,
523
530
  dev,
531
+ patchedFetch,
524
532
  );
525
533
 
526
534
  if (evt.request.headers.get("x-grimoire-navigate") === "1") {
@@ -555,8 +563,8 @@ export async function createServer(config: GrimoireConfig = {}) {
555
563
  response = await hooksHandle({ event, resolve });
556
564
  }
557
565
  } catch (err) {
558
- console.error(
559
- `[grimoire] ${event.request.method} ${event.url.pathname} failed:`,
566
+ logger.error(
567
+ `${event.request.method} ${event.url.pathname} failed:`,
560
568
  err,
561
569
  );
562
570
  await hooksHandleError?.({
@@ -646,6 +654,5 @@ export async function createServer(config: GrimoireConfig = {}) {
646
654
  hostname: server.hostname,
647
655
  stop: () => server.stop(),
648
656
  });
649
- // console.log(`Grimoire running at http://${host}:${port}`);
650
657
  return server;
651
658
  }
@@ -0,0 +1,56 @@
1
+ export interface InteractiveOptions {
2
+ onQuit: () => void | Promise<void>;
3
+ onRestart: () => void | Promise<void>;
4
+ onClear: () => void;
5
+ }
6
+
7
+ /**
8
+ * Returns a promise that resolves only when explicitly settled.
9
+ * Used to keep the dev/start process alive until the user quits.
10
+ */
11
+ export function createWaiter() {
12
+ let resolve!: () => void;
13
+ const promise = new Promise<void>((r) => {
14
+ resolve = r;
15
+ });
16
+ return { promise, resolve };
17
+ }
18
+
19
+ /**
20
+ * Listen for interactive keypresses in dev mode.
21
+ * Mirrors Vite's UX: q=quit, r=restart, c=clear.
22
+ * Falls back gracefully if stdin is not a TTY (CI, piped input).
23
+ */
24
+ export function listenForKeys(opts: InteractiveOptions) {
25
+ if (!process.stdin.isTTY) return;
26
+
27
+ process.stdin.setRawMode(true);
28
+ process.stdin.resume();
29
+ process.stdin.setEncoding("utf8");
30
+
31
+ process.stdin.on("data", async (key: string) => {
32
+ // ctrl+c
33
+ if (key === "\x03") {
34
+ await opts.onQuit();
35
+ return;
36
+ }
37
+
38
+ switch (key.toLowerCase()) {
39
+ case "q":
40
+ await opts.onQuit();
41
+ break;
42
+ case "r":
43
+ await opts.onRestart();
44
+ break;
45
+ case "c":
46
+ opts.onClear();
47
+ break;
48
+ }
49
+ });
50
+ }
51
+
52
+ export function stopListening() {
53
+ if (!process.stdin.isTTY) return;
54
+ process.stdin.setRawMode(false);
55
+ process.stdin.pause();
56
+ }
@@ -3,7 +3,7 @@ import type {
3
3
  BuildResult,
4
4
  CoordinatorContext,
5
5
  GrimoirePlugin,
6
- LoadContext,
6
+ LoadContext, PluginContext,
7
7
  Route,
8
8
  Server,
9
9
  WorkerDescriptor,
@@ -15,6 +15,7 @@ import type {
15
15
  // calling conventions (middleware chain / inline transform loop) handled in index.ts.
16
16
  // Keep HookArgs in sync with GrimoirePlugin in types.ts.
17
17
  type HookArgs = {
18
+ onPluginsResolved: [ctx: PluginContext];
18
19
  onStart: [server: Server];
19
20
  onStop: [reason: "shutdown" | "restart"];
20
21
  onBuildStart: [];