@sigil-dev/grimoire 0.7.4 → 0.7.6

package/src/server/coordinator.ts

@@ -1,297 +1,306 @@
-import { type Subprocess, spawn } from "bun";
-import { join } from "path";
-import { matchRoute } from "../routing/router";
-import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
-import type {
-	CoordinatorContext,
-	GrimoireConfig,
-	GrimoirePlugin,
-	Route,
-	WorkerDescriptor,
-	WorkerMode,
-} from "../types";
-import { buildProject } from "./build";
-import {
-	runHook,
-	runRouteRequest,
-	runSerializeLocals,
-	runWorkerSpawn,
-} from "./plugins";
-
-async function waitForWorkers(
-	workers: LiveWorker[],
-	timeoutMs = 10_000,
-): Promise<void> {
-	const ready = new Set<number>();
-	const start = Date.now();
-
-	while (ready.size < workers.length) {
-		if (Date.now() - start > timeoutMs) {
-			const pending = workers
-				.filter((w) => !ready.has(w.descriptor.globalIndex))
-				.map(
-					(w) =>
-						w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
-				)
-				.join(", ");
-			throw new Error(
-				`Grimoire: workers timed out waiting to become ready: ${pending}`,
-			);
-		}
-		for (const w of workers) {
-			if (ready.has(w.descriptor.globalIndex)) continue;
-			if (w.descriptor.pid != null) {
-				ready.add(w.descriptor.globalIndex);
-			}
-		}
-		await Bun.sleep(50);
-	}
-}
-
-function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
-	const idx = roundRobinCounter++ % workers.length;
-	return workers[idx];
-}
-let roundRobinCounter = 0;
-
-function consistentHash(
-	req: Request,
-	workers: WorkerDescriptor[],
-): WorkerDescriptor {
-	const key = req.headers.get("cookie") ?? req.url;
-	let hash = 0;
-	for (let i = 0; i < key.length; i++) {
-		hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
-	}
-	return workers[hash % workers.length];
-}
-
-function defaultRoute(
-	req: Request,
-	workers: WorkerDescriptor[],
-	tree: RouteTree,
-): WorkerDescriptor {
-	const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
-
-	if (isWs) {
-		const wsWorkers = workers.filter(
-			(w) => w.mode === "ws" || w.mode === "full",
-		);
-		if (wsWorkers.length) return consistentHash(req, wsWorkers);
-	}
-
-	const url = new URL(req.url);
-	const matched = matchRoute(tree, url);
-
-	if (matched?.route.type === "server") {
-		const apiWorkers = workers.filter(
-			(w) => w.mode === "api" || w.mode === "full",
-		);
-		if (apiWorkers.length) return roundRobin(apiWorkers);
-	}
-
-	const frontendWorkers = workers.filter(
-		(w) => w.mode === "frontend" || w.mode === "full",
-	);
-	if (frontendWorkers.length) return roundRobin(frontendWorkers);
-
-	// fallback — should not happen if scale spec is valid
-	return workers[0];
-}
-
-export interface ScaleSpec {
-	api?: number;
-	frontend?: number;
-	ws?: number;
-	[mode: string]: number | undefined;
-}
-
-export interface CoordinatorOptions {
-	config: GrimoireConfig;
-	plugins: GrimoirePlugin[];
-	scale: ScaleSpec;
-	noBuild: boolean;
-}
-
-interface LiveWorker {
-	descriptor: WorkerDescriptor;
-	process: Subprocess;
-	port: number;
-}
-
-export async function startCoordinator(options: CoordinatorOptions) {
-	const { config, plugins, scale, noBuild } = options;
-	const { port = 3000, host = "localhost", routes = "src/routes" } = config;
-	let stopping = false;
-
-	// 1. build if needed
-	if (!noBuild) {
-		const { result } = await buildProject(config, plugins);
-		if (!result.success) throw new Error("Grimoire: build failed");
-	}
-
-	// 2. generate ephemeral secret
-	const secret = crypto.randomUUID() + crypto.randomUUID(); // 72 hex chars
-
-	// 3. scan routes once — coordinator owns the route tree
-	const routesDir = /* resolve */ routes;
-	const tree = await scanRoutes(routesDir, process.cwd());
-
-	// 4. derive route slices per mode
-	const slices: Record<string, RouteFile[]> = {
-		api: tree.routes.filter((r) => r.type === "server"),
-		ws: tree.routes.filter((r) => r.type === "server"),
-		frontend: tree.routes.filter(
-			(r) => r.type === "page" || r.type === "simple",
-		),
-		full: [...tree.routes],
-	};
-
-	// 5. spawn workers
-	const liveWorkers: LiveWorker[] = [];
-	let globalIndex = 0;
-	let nextPort = port + 1;
-
-	for (const [mode, count = 0] of Object.entries(scale)) {
-		for (let i = 0; i < count; i++) {
-			const workerPort = nextPort++;
-			const descriptor: WorkerDescriptor = {
-				mode: mode as WorkerMode,
-				index: i + 1,
-				globalIndex: globalIndex++,
-				internalUrl: `http://127.0.0.1:${workerPort}`,
-				routes: slices[mode] ?? slices.full,
-			};
-
-			// let plugins inject env and name
-			const workerEnv = await runWorkerSpawn(plugins, descriptor);
-			const workerEntry = join(import.meta.dir, "./worker.ts");
-			if (workerEnv.name) descriptor.name = workerEnv.name;
-
-			const proc = spawn(["bun", "run", workerEntry], {
-				env: {
-					...process.env,
-					...workerEnv.env,
-					GRIMOIRE_MODE: mode,
-					GRIMOIRE_WORKER_INDEX: String(i),
-					GRIMOIRE_WORKER_PORT: String(workerPort),
-					GRIMOIRE_INTERNAL_SECRET: secret,
-					GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
-				},
-				ipc(message) {
-					// worker sends { ready: true } when Bun.serve is up
-					if (message?.ready) {
-						descriptor.pid = proc.pid;
-						runHook(plugins, "onWorkerReady", descriptor);
-					}
-				},
-				onExit(proc, exitCode) {
-					const intentional = stopping;
-					runHook(
-						plugins,
-						"onWorkerDeath",
-						descriptor,
-						intentional ? "intentional" : "crash",
-					);
-					if (!intentional) {
-						console.error(
-							`[grimoire] worker ${descriptor.name ?? descriptor.mode + "-" + descriptor.index} crashed (exit ${exitCode}), respawning...`,
-						);
-						// respawn: same descriptor, same port
-						// (simplified — plugin-scale can override this behavior)
-					}
-				},
-			});
-
-			liveWorkers.push({ descriptor, process: proc, port: workerPort });
-		}
-	}
-
-	// 6. wait for all workers ready (with timeout)
-	// workers send IPC { ready: true } — coordinator waits up to 10s
-	await waitForWorkers(liveWorkers);
-
-	// 7. fire onCoordinatorStart
-	const ctx: CoordinatorContext = {
-		workers: liveWorkers.map((w) => w.descriptor),
-		port,
-		secret,
-		routes: tree,
-	};
-	await runHook(plugins, "onCoordinatorStart", ctx);
-
-	// 8. start coordinator Bun.serve
-
-	const server = Bun.serve({
-		port,
-		hostname: host,
-		fetch: async (req) => {
-			// run hooks.server.ts to populate locals
-			const locals: App.Locals = {};
-			// ... same handle() chain as createServer but resolve() just
-			// forwards instead of rendering
-
-			// pick worker
-			const descriptors = liveWorkers.map((w) => w.descriptor);
-			const chosen =
-				(await runRouteRequest(plugins, req, descriptors, tree)) ??
-				defaultRoute(req, descriptors, tree);
-
-			// serialize locals
-			const serialized =
-				(await runSerializeLocals(plugins, locals)) ??
-				defaultSerialize(locals, secret);
-
-			// forward
-			return fetch(chosen.internalUrl + new URL(req.url).pathname, {
-				method: req.method,
-				headers: {
-					//@ts-expect-error shut Up
-					...Object.fromEntries(req.headers),
-					"X-Grimoire-Locals": serialized,
-					"X-Grimoire-Internal": secret,
-				},
-				body: req.body,
-			});
-		},
-	});
-
-	// 9. shutdown
-	const handleShutdown = async () => {
-		if (stopping) return;
-		stopping = true;
-		await runHook(plugins, "onStop", "shutdown");
-		for (const w of liveWorkers) w.process.kill();
-		server.stop();
-		process.exit(0);
-	};
-	process.on("SIGINT", handleShutdown);
-	process.on("SIGTERM", handleShutdown);
-
-	return {
-		server,
-		workers: liveWorkers.map((w) => ({
-			name: w.descriptor.name,
-			mode: w.descriptor.mode,
-			port: w.port,
-			index: w.descriptor.index,
-		})),
-	};
-}
-
-function defaultSerialize(locals: App.Locals, secret: string): string {
-	const payload = JSON.stringify(locals);
-	const sig = new Bun.CryptoHasher("sha256")
-		.update(secret + payload)
-		.digest("hex");
-	return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
-}
-
-function defaultDeserialize(raw: string, secret: string): App.Locals {
-	const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
-	const expected = new Bun.CryptoHasher("sha256")
-		.update(secret + payload)
-		.digest("hex");
-	if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
-	return JSON.parse(payload);
-}
+import { type Subprocess, spawn } from "bun";
+import { join } from "path";
+import { matchRoute } from "../routing/router";
+import { type RouteFile, type RouteTree, scanRoutes } from "../routing/scanner";
+import type {
+	CoordinatorContext,
+	GrimoireConfig,
+	GrimoirePlugin,
+	Route,
+	WorkerDescriptor,
+	WorkerMode,
+} from "../types";
+import { buildProject } from "./build";
+import {
+	runHook,
+	runRouteRequest,
+	runSerializeLocals,
+	runWorkerSpawn,
+} from "./plugins";
+
+async function waitForWorkers(
+	workers: LiveWorker[],
+	timeoutMs = 10_000,
+): Promise<void> {
+	const ready = new Set<number>();
+	const start = Date.now();
+
+	while (ready.size < workers.length) {
+		if (Date.now() - start > timeoutMs) {
+			const pending = workers
+				.filter((w) => !ready.has(w.descriptor.globalIndex))
+				.map(
+					(w) =>
+						w.descriptor.name ?? `${w.descriptor.mode}-${w.descriptor.index}`,
+				)
+				.join(", ");
+			throw new Error(
+				`Grimoire: workers timed out waiting to become ready: ${pending}`,
+			);
+		}
+		for (const w of workers) {
+			if (ready.has(w.descriptor.globalIndex)) continue;
+			if (w.descriptor.pid != null) {
+				ready.add(w.descriptor.globalIndex);
+			}
+		}
+		await Bun.sleep(50);
+	}
+}
+
+function roundRobin(workers: WorkerDescriptor[]): WorkerDescriptor {
+	const idx = roundRobinCounter++ % workers.length;
+	return workers[idx];
+}
+let roundRobinCounter = 0;
+
+function consistentHash(
+	req: Request,
+	workers: WorkerDescriptor[],
+): WorkerDescriptor {
+	const key = req.headers.get("cookie") ?? req.url;
+	let hash = 0;
+	for (let i = 0; i < key.length; i++) {
+		hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+	}
+	return workers[hash % workers.length];
+}
+
+function defaultRoute(
+	req: Request,
+	workers: WorkerDescriptor[],
+	tree: RouteTree,
+): WorkerDescriptor {
+	const isWs = req.headers.get("upgrade")?.toLowerCase() === "websocket";
+
+	if (isWs) {
+		const wsWorkers = workers.filter(
+			(w) => w.mode === "ws" || w.mode === "full",
+		);
+		if (wsWorkers.length) return consistentHash(req, wsWorkers);
+	}
+
+	const url = new URL(req.url);
+	const matched = matchRoute(tree, url);
+
+	if (matched?.route.type === "server") {
+		const apiWorkers = workers.filter(
+			(w) => w.mode === "api" || w.mode === "full",
+		);
+		if (apiWorkers.length) return roundRobin(apiWorkers);
+	}
+
+	const frontendWorkers = workers.filter(
+		(w) => w.mode === "frontend" || w.mode === "full",
+	);
+	if (frontendWorkers.length) return roundRobin(frontendWorkers);
+
+	// fallback — should not happen if scale spec is valid
+	return workers[0];
+}
+
+export interface ScaleSpec {
+	api?: number;
+	frontend?: number;
+	ws?: number;
+	[mode: string]: number | undefined;
+}
+
+export interface CoordinatorOptions {
+	config: GrimoireConfig;
+	plugins: GrimoirePlugin[];
+	scale: ScaleSpec;
+	noBuild: boolean;
+}
+
+interface LiveWorker {
+	descriptor: WorkerDescriptor;
+	process: Subprocess;
+	port: number;
+}
+
+export async function startCoordinator(options: CoordinatorOptions) {
+	const { config, plugins, scale, noBuild } = options;
+	const { port = 3000, host = "localhost", routes = "src/routes" } = config;
+	let stopping = false;
+
+	// 1. build if needed
+	if (!noBuild) {
+		const { result } = await buildProject(config, plugins);
+		if (!result.success) throw new Error("Grimoire: build failed");
+	}
+
+	// 2. generate ephemeral secret
+	const secret = crypto.randomUUID() + crypto.randomUUID(); // 72 hex chars
+
+	// 3. scan routes once — coordinator owns the route tree
+	const routesDir = /* resolve */ routes;
+	const tree = await scanRoutes(routesDir, process.cwd());
+
+	// 4. derive route slices per mode
+	const slices: Record<string, RouteFile[]> = {
+		api: tree.routes.filter((r) => r.type === "server"),
+		ws: tree.routes.filter((r) => r.type === "server"),
+		frontend: tree.routes.filter(
+			(r) => r.type === "page" || r.type === "simple",
+		),
+		full: [...tree.routes],
+	};
+
+	// 5. spawn workers
+	const liveWorkers: LiveWorker[] = [];
+	let globalIndex = 0;
+	let nextPort = port + 1;
+
+	for (const [mode, count = 0] of Object.entries(scale)) {
+		for (let i = 0; i < count; i++) {
+			const workerPort = nextPort++;
+			const descriptor: WorkerDescriptor = {
+				mode: mode as WorkerMode,
+				index: i + 1,
+				globalIndex: globalIndex++,
+				internalUrl: `http://127.0.0.1:${workerPort}`,
+				routes: slices[mode] ?? slices.full,
+			};
+
+			// let plugins inject env and name
+			const workerEnv = await runWorkerSpawn(plugins, descriptor);
+			const workerEntry = join(import.meta.dir, "./worker.ts");
+			if (workerEnv.name) descriptor.name = workerEnv.name;
+
+			// Inject env vars prefixed with PUBLIC_ so they're available to client bundles
+			const publicEnvVars: Record<string, string> = {};
+			for (const [key, value] of Object.entries(process.env)) {
+				if (key.startsWith("PUBLIC_") && value !== undefined) {
+					publicEnvVars[key] = value;
+				}
+			}
+
+			const proc = spawn(["bun", "run", workerEntry], {
+				env: {
+					...process.env,
+					...workerEnv.env,
+					...publicEnvVars,
+					GRIMOIRE_MODE: mode,
+					GRIMOIRE_WORKER_INDEX: String(i),
+					GRIMOIRE_WORKER_PORT: String(workerPort),
+					GRIMOIRE_INTERNAL_SECRET: secret,
+					GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
+				},
+				ipc(message) {
+					// worker sends { ready: true } when Bun.serve is up
+					if (message?.ready) {
+						descriptor.pid = proc.pid;
+						runHook(plugins, "onWorkerReady", descriptor);
+					}
+				},
+				onExit(proc, exitCode) {
+					const intentional = stopping;
+					runHook(
+						plugins,
+						"onWorkerDeath",
+						descriptor,
+						intentional ? "intentional" : "crash",
+					);
+					if (!intentional) {
+						console.error(
+							`[grimoire] worker ${descriptor.name ?? descriptor.mode + "-" + descriptor.index} crashed (exit ${exitCode}), respawning...`,
+						);
+						// respawn: same descriptor, same port
+						// (simplified — plugin-scale can override this behavior)
+					}
+				},
+			});
+
+			liveWorkers.push({ descriptor, process: proc, port: workerPort });
+		}
+	}
+
+	// 6. wait for all workers ready (with timeout)
+	// workers send IPC { ready: true } — coordinator waits up to 10s
+	await waitForWorkers(liveWorkers);
+
+	// 7. fire onCoordinatorStart
+	const ctx: CoordinatorContext = {
+		workers: liveWorkers.map((w) => w.descriptor),
+		port,
+		secret,
+		routes: tree,
+	};
+	await runHook(plugins, "onCoordinatorStart", ctx);
+
+	// 8. start coordinator Bun.serve
+
+	const server = Bun.serve({
+		port,
+		hostname: host,
+		fetch: async (req) => {
+			// run hooks.server.ts to populate locals
+			const locals: App.Locals = {};
+			// ... same handle() chain as createServer but resolve() just
+			// forwards instead of rendering
+
+			// pick worker
+			const descriptors = liveWorkers.map((w) => w.descriptor);
+			const chosen =
+				(await runRouteRequest(plugins, req, descriptors, tree)) ??
+				defaultRoute(req, descriptors, tree);
+
+			// serialize locals
+			const serialized =
+				(await runSerializeLocals(plugins, locals)) ??
+				defaultSerialize(locals, secret);
+
+			// forward
+			return fetch(chosen.internalUrl + new URL(req.url).pathname, {
+				method: req.method,
+				headers: {
+					//@ts-expect-error shut Up
+					...Object.fromEntries(req.headers),
+					"X-Grimoire-Locals": serialized,
+					"X-Grimoire-Internal": secret,
+				},
+				body: req.body,
+			});
+		},
+	});
+
+	// 9. shutdown
+	const handleShutdown = async () => {
+		if (stopping) return;
+		stopping = true;
+		await runHook(plugins, "onStop", "shutdown");
+		for (const w of liveWorkers) w.process.kill();
+		server.stop();
+		process.exit(0);
+	};
+	process.on("SIGINT", handleShutdown);
+	process.on("SIGTERM", handleShutdown);
+
+	return {
+		server,
+		workers: liveWorkers.map((w) => ({
+			name: w.descriptor.name,
+			mode: w.descriptor.mode,
+			port: w.port,
+			index: w.descriptor.index,
+		})),
+	};
+}
+
+function defaultSerialize(locals: App.Locals, secret: string): string {
+	const payload = JSON.stringify(locals);
+	const sig = new Bun.CryptoHasher("sha256")
+		.update(secret + payload)
+		.digest("hex");
+	return Buffer.from(JSON.stringify({ payload, sig })).toString("base64");
+}
+
+function defaultDeserialize(raw: string, secret: string): App.Locals {
+	const { payload, sig } = JSON.parse(Buffer.from(raw, "base64").toString());
+	const expected = new Bun.CryptoHasher("sha256")
+		.update(secret + payload)
+		.digest("hex");
+	if (sig !== expected) throw new Error("Grimoire: locals signature invalid");
+	return JSON.parse(payload);
+}

package/src/server/hooks.ts

@@ -1,7 +1,7 @@
 /**
  * SvelteKit-style server hooks.
  *
- * Create a hooks.index.ts in your project root:
+ * Create a hooks.server.ts in your project root:
  *
  *   import type { Handle } from "@sigil-dev/grimoire/hooks";
  *
@@ -12,6 +12,10 @@
  *     return response;
  *   };
  *
+ *   export const handleError: HandleError = ({ error, status, message }) => {
+ *     console.error(`[${status}] ${message}`, error);
+ *   };
+ *
  *   // optional: runs once at server start
  *   export const init = () => {
  *     console.log("Server started");
@@ -32,8 +36,10 @@ export interface RequestEvent {
 	request: Request;
 	url: URL;
 	params: Record<string, string>;
-	locals: Record<string, any>;
+	locals: App.Locals;
 	cookies: Cookies;
+	route: { id: string };
+	fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 	setHeaders: (headers: Record<string, string>) => void;
 }
 
@@ -60,6 +66,21 @@ export type Handle = (input: {
 	resolve: ResolveFunction;
 }) => MaybePromise<Response>;
 
+export interface HandleErrorInput {
+	error: unknown;
+	event: RequestEvent;
+	status: number;
+	message: string;
+}
+export type HandleError = (input: HandleErrorInput) => void | Promise<void>;
+
+export interface HandleFetchInput {
+	request: Request;
+	fetch: typeof globalThis.fetch;
+	event: RequestEvent;
+}
+export type HandleFetch = (input: HandleFetchInput) => MaybePromise<Response>;
+
 export type InitFunction = () => void | Promise<void>;
 
 /**
@@ -73,7 +94,7 @@ export function sequence(...handlers: Handle[]): Handle {
 		const next: ResolveFunction = async (evt) => {
 			if (i < handlers.length) {
 				const handler = handlers[i++];
-				return handler({ event: evt, resolve: next });
+				return handler!({ event: evt, resolve: next });
 			}
 			return resolve(evt);
 		};