@sigil-dev/grimoire 0.9.12 → 0.9.14

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.
package/index.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  // server loads call depends() to register invalidation keys
2
2
  export { depends } from "./src/client/deps";
3
+ export type { Deferred } from "./src/client/deferred";
4
+ export { deferred, onDeferred } from "./src/client/deferred";
3
5
  export { Head } from "./src/rendering/head";
4
6
  // registerSSRPlugin is server-only — import from "@sigil-dev/grimoire/bun"
5
7
  export type { RouteFile, RouteTree } from "./src/routing/scanner";
@@ -34,5 +36,6 @@ export type {
34
36
  WorkerEnv,
35
37
  WorkerMode,
36
38
  WsRouteHandler,
39
+ WorkerContext,
37
40
  } from "./src/types";
38
- export { defineConfig } from "./src/types";
41
+ export { defineConfig, workerContext } from "./src/types";
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "module": "index.ts",
5
5
  "type": "module",
6
6
  "private": false,
7
- "version": "0.9.12",
7
+ "version": "0.9.14",
8
8
  "exports": {
9
9
  ".": "./index.ts",
10
10
  "./server": "./server.ts",
@@ -23,8 +23,8 @@
23
23
  "test": "bun test"
24
24
  },
25
25
  "dependencies": {
26
- "@sigil-dev/compiler": "0.9.12",
27
- "@sigil-dev/runtime": "0.9.12",
26
+ "@sigil-dev/compiler": "0.9.14",
27
+ "@sigil-dev/runtime": "0.9.14",
28
28
  "vite": "^8.0.16"
29
29
  },
30
30
  "peerDependencies": {
@@ -0,0 +1,179 @@
1
+ /**
2
+ * Reading a value that is still in flight.
3
+ *
4
+ * A top-level promise in load data streams in later. The server sends the
5
+ * page immediately, so the component renders with that value `undefined` and
6
+ * the visitor reads the rest of the page while the slow part is still on its
7
+ * way. When it settles, the server sends a small patch script that writes the
8
+ * value into the state and dispatches `grimoire:deferred`.
9
+ *
10
+ * Until now each app wired that event up by hand — the same fifteen lines,
11
+ * copied, with the details easy to get wrong. `deferred()` is those lines.
12
+ *
13
+ * ```tsx
14
+ * const reviews = deferred<Review[]>(props.data.reviews, []);
15
+ *
16
+ * return reviews.done
17
+ * ? <ul>{reviews.value.map((r) => <li key={r.id}>{r.text}</li>)}</ul>
18
+ * : <p>Loading reviews…</p>;
19
+ * ```
20
+ *
21
+ * The one thing this cannot do is beat hydration. The page's state script
22
+ * holds the values, and hydration waits for the whole response, so a value
23
+ * that arrives after the document does will not re-render the tree on its
24
+ * own. The listener is what closes that gap — it fires for late arrivals and
25
+ * updates the signal, so a component that re-renders (on a click, a
26
+ * navigation, a transition) sees the value. For a value that has to appear
27
+ * the instant it lands without any other interaction, the [Suspense
28
+ * boundary](https://react.dev/reference/react/Suspense) already in your tree
29
+ * is the mechanism — the value goes in as ordinary data and Suspense
30
+ * handles the timing.
31
+ */
32
+
33
+ /**
34
+ * The hydration state the server embeds, as this module sees it.
35
+ *
36
+ * Declared locally because the same shape is declared in @sigil-dev/types
37
+ * for applications, and grimoire does not depend on that package — a
38
+ * framework package should not reach for the app's type package to describe
39
+ * its own runtime. The two must agree, and `deferred.test.ts` drives the
40
+ * server's real patch script, so a change to one that the other does not
41
+ * follow fails a test.
42
+ */
43
+ interface GrimoireStateMirror {
44
+ pattern?: string;
45
+ data?: Record<string, unknown>;
46
+ }
47
+
48
+ /** The window this module reads. A local alias, not a global augmentation. */
49
+ interface GrimoireWindow {
50
+ __grimoire_state__?: GrimoireStateMirror | HTMLElement;
51
+ }
52
+
53
+ const state = (): GrimoireStateMirror | HTMLElement | undefined =>
54
+ (globalThis as unknown as { window?: GrimoireWindow }).window
55
+ ?.__grimoire_state__;
56
+
57
+ /** The value a component sees while it is still in flight. */
58
+ export interface Deferred<T> {
59
+ /** The value, or `fallback` while it is still loading. */
60
+ readonly value: T;
61
+ /** `true` once the real value has arrived. */
62
+ readonly done: boolean;
63
+ }
64
+
65
+ /** The current value of a streamed property, or `undefined` if still in flight. */
66
+ function readDeferredValue<T>(key?: string): T | undefined {
67
+ const held = state();
68
+ // The element carries the authoritative copy but has nodeType; the plain
69
+ // mirror does not. Reading the wrong one silently loses the value, so
70
+ // this guard is the difference between working and not.
71
+ if (!held) return undefined;
72
+ const data = held instanceof HTMLElement ? undefined : held.data;
73
+ if (!data) return undefined;
74
+ if (key !== undefined) {
75
+ const one = data[key];
76
+ return one === undefined || one === null ? undefined : (one as T);
77
+ }
78
+ for (const one of Object.values(data)) {
79
+ if (one !== undefined && one !== null) return one as T;
80
+ }
81
+ return undefined;
82
+ }
83
+
84
+ /**
85
+ * Wrap a possibly-streamed load value.
86
+ *
87
+ * @param incoming The prop from `data`. `undefined` means still loading; any
88
+ * other value is already resolved, which is the normal case on a
89
+ * client-side navigation and on the server.
90
+ * @param fallback What to render while loading.
91
+ * @param key The property name this value streams under. Required when a
92
+ * page has more than one deferred value, because the patch event only says
93
+ * *that* something settled — reading the first non-empty entry in the state
94
+ * would hand one component another's data. With a single deferred value on
95
+ * the page it can be left out, and any settled value is taken.
96
+ */
97
+ export function deferred<T>(
98
+ incoming: T | undefined,
99
+ fallback: T,
100
+ key?: string,
101
+ ): Deferred<T> {
102
+ let value = incoming ?? fallback;
103
+ let done = incoming !== undefined;
104
+
105
+ // Only in a browser: the server has no window, and a value still in
106
+ // flight is genuinely `undefined` here.
107
+ if (typeof window !== "undefined" && !done) {
108
+ // The patch may have landed between this component's first render and
109
+ // the event wiring, which is a real window when a value resolves in
110
+ // ~1ms. Reading on the way in is what closes it.
111
+ const early = readDeferredValue<T>(key);
112
+ if (early !== undefined) {
113
+ value = early;
114
+ done = true;
115
+ } else {
116
+ window.addEventListener("grimoire:deferred", (event) => {
117
+ // With a key, the event names it — so an unrelated value
118
+ // settling does not mark this one done.
119
+ if (key !== undefined) {
120
+ const detail = (event as CustomEvent<{ key?: string }>).detail;
121
+ if (detail?.key !== undefined && detail.key !== key) return;
122
+ }
123
+ const held = readDeferredValue<T>(key);
124
+ if (held === undefined) return;
125
+ value = held;
126
+ done = true;
127
+ });
128
+ }
129
+ }
130
+
131
+ return {
132
+ get value() {
133
+ return value;
134
+ },
135
+ get done() {
136
+ return done;
137
+ },
138
+ };
139
+ }
140
+
141
+ /**
142
+ * Drive a `$state` from a streamed value.
143
+ *
144
+ * `deferred()` returns a snapshot, which is right for a component that
145
+ * re-renders on its own. This is for a value that is rendered somewhere
146
+ * else, or held in shared state — the pattern where a module-level
147
+ * `$state` is assigned from the event:
148
+ *
149
+ * ```ts
150
+ * let omenText = $state("(the ink is still drying…)");
151
+ * onDeferred((value) => { omenText = value; }, "omen");
152
+ * ```
153
+ *
154
+ * The callback runs once immediately if the value has already landed, so
155
+ * there is no window where it is missed.
156
+ */
157
+ export function onDeferred<T>(
158
+ apply: (value: T) => void,
159
+ key?: string,
160
+ ): void {
161
+ if (typeof window === "undefined") return;
162
+
163
+ // Fires once, immediately, if the value has already landed — the same
164
+ // early-arrival read deferred() does, so there is no window where a
165
+ // value that settled first is missed.
166
+ const current = readDeferredValue<T>(key);
167
+ if (current !== undefined) {
168
+ apply(current);
169
+ return;
170
+ }
171
+ window.addEventListener("grimoire:deferred", (event) => {
172
+ if (key !== undefined) {
173
+ const detail = (event as CustomEvent<{ key?: string }>).detail;
174
+ if (detail?.key !== undefined && detail.key !== key) return;
175
+ }
176
+ const held = readDeferredValue<T>(key);
177
+ if (held !== undefined) apply(held);
178
+ });
179
+ }
@@ -15,6 +15,8 @@ export { depends };
15
15
 
16
16
  async function refetchCurrent(): Promise<void> {
17
17
  if (!lastState) return;
18
+ // a refetch exists because the data changed; never serve it from a prefetch
19
+ prefetched.clear();
18
20
  await navigate(location.pathname, { history: "replace" });
19
21
  }
20
22
 
@@ -185,42 +187,84 @@ function restorePreservedScroll(positions: Map<string, number>): void {
185
187
  }
186
188
 
187
189
  // C3: Preloading
190
+ //
191
+ // A prefetch keeps its in-flight Response here and navigate() consumes it.
192
+ // The HTTP cache cannot do this job: the navigate JSON carries no freshness
193
+ // headers and pages are commonly served `no-cache`, so a plain prefetch
194
+ // warmed nothing the click could reuse.
188
195
  let preloadTimer: Timer | null = null;
196
+ const PREFETCH_TTL_MS = 15_000;
197
+ const prefetched = new Map<string, { res: Promise<Response>; at: number }>();
189
198
 
190
- function setupPreload(): void {
191
- document.addEventListener("mouseover", (e) => {
192
- const a = (e.target as Element).closest("a");
193
- if (!a) return;
194
- const href = a.getAttribute("href");
195
- if (!href) return;
196
- if (/^(https?:\/\/|\/\/|#|mailto:|tel:)/.test(href)) return;
197
- if (a.getAttribute("data-sigil-preload") === "off") return;
199
+ function navigateFetch(path: string, priority?: "low"): Promise<Response> {
200
+ return fetch(path, {
201
+ headers: { "x-grimoire-navigate": "1" },
202
+ redirect: "manual",
203
+ ...(priority ? { priority } : {}),
204
+ });
205
+ }
198
206
 
199
- // Only prefetch links that resolve to a known client route — external
200
- // pages and non-page endpoints (API routes, redirects) are skipped.
201
- try {
202
- const url = new URL(href, location.origin);
203
- if (!findPattern(url.pathname)) return;
204
- } catch {
205
- return;
206
- }
207
+ /** The route-local href of an anchor worth prefetching, or null. */
208
+ function prefetchHref(a: Element | null): string | null {
209
+ if (!a) return null;
210
+ const href = a.getAttribute("href");
211
+ if (!href) return null;
212
+ if (/^(https?:\/\/|\/\/|#|mailto:|tel:)/.test(href)) return null;
213
+ if (a.getAttribute("data-sigil-preload") === "off") return null;
214
+ // Only links that resolve to a known client route — external pages and
215
+ // non-page endpoints (API routes, redirects) are skipped.
216
+ try {
217
+ const url = new URL(href, location.origin);
218
+ if (!findPattern(url.pathname)) return null;
219
+ } catch {
220
+ return null;
221
+ }
222
+ return href;
223
+ }
207
224
 
208
- const preloadCode = a.hasAttribute("data-sigil-preload-code");
225
+ /**
226
+ * Warm a navigation: load the route's code and start its data request. The
227
+ * response is held for a short while so the click that follows reuses it.
228
+ */
229
+ export function prefetch(href: string): void {
230
+ const conn = (navigator as { connection?: { saveData?: boolean } }).connection;
231
+ if (conn?.saveData) return;
232
+ const url = new URL(href, location.origin);
233
+ const key = url.pathname + url.search;
234
+ const hit = prefetched.get(key);
235
+ if (hit && Date.now() - hit.at < PREFETCH_TTL_MS) return;
236
+ const pattern = findPattern(url.pathname);
237
+ if (pattern) void resolveRoute(pattern).catch(() => {});
238
+ const res = navigateFetch(key, "low");
239
+ res.catch(() => prefetched.delete(key));
240
+ prefetched.set(key, { res, at: Date.now() });
241
+ }
209
242
 
243
+ /** The held prefetch for `path` if it is still fresh; each is used once. */
244
+ function takePrefetched(path: string): Promise<Response> | null {
245
+ const url = new URL(path, location.origin);
246
+ const key = url.pathname + url.search;
247
+ const hit = prefetched.get(key);
248
+ prefetched.delete(key);
249
+ if (!hit || Date.now() - hit.at >= PREFETCH_TTL_MS) return null;
250
+ return hit.res;
251
+ }
252
+
253
+ function setupPreload(): void {
254
+ // Hover is a desktop signal; a short delay ignores cursors passing over.
255
+ document.addEventListener("mouseover", (e) => {
256
+ const a = (e.target as Element).closest("a");
257
+ const href = prefetchHref(a);
258
+ if (!a || !href) return;
210
259
  clearTimeout(preloadTimer);
211
260
  preloadTimer = setTimeout(() => {
212
- if (preloadCode) {
261
+ if (a.hasAttribute("data-sigil-preload-code")) {
213
262
  const link = document.createElement("link");
214
263
  link.rel = "prefetch";
215
264
  link.href = href;
216
265
  document.head.appendChild(link);
217
266
  }
218
- // data prefetch is the default; -code is the explicit escalation
219
- fetch(href, {
220
- headers: { "x-grimoire-navigate": "1" },
221
- redirect: "manual",
222
- priority: "low",
223
- }).catch(() => {});
267
+ prefetch(href);
224
268
  }, 80);
225
269
  });
226
270
 
@@ -229,6 +273,43 @@ function setupPreload(): void {
229
273
  if (!a) return;
230
274
  clearTimeout(preloadTimer);
231
275
  });
276
+
277
+ // Touch has no hover, but a tap lands 100-300ms after the finger goes
278
+ // down; start the request then.
279
+ document.addEventListener(
280
+ "touchstart",
281
+ (e) => {
282
+ const href = prefetchHref((e.target as Element).closest("a"));
283
+ if (href) prefetch(href);
284
+ },
285
+ { passive: true },
286
+ );
287
+
288
+ // Opt-in: `data-sigil-preload="viewport"` warms a link once it scrolls
289
+ // into view, for navs whose next tap is predictable.
290
+ if (typeof IntersectionObserver !== "undefined") {
291
+ const io = new IntersectionObserver((entries) => {
292
+ for (const entry of entries) {
293
+ if (!entry.isIntersecting) continue;
294
+ io.unobserve(entry.target);
295
+ const href = prefetchHref(entry.target);
296
+ if (href) prefetch(href);
297
+ }
298
+ });
299
+ const observe = (root: ParentNode) => {
300
+ for (const a of root.querySelectorAll('a[data-sigil-preload="viewport"]'))
301
+ io.observe(a);
302
+ };
303
+ observe(document);
304
+ new MutationObserver((muts) => {
305
+ for (const m of muts)
306
+ for (const n of m.addedNodes)
307
+ if (n instanceof Element) {
308
+ if (n.matches('a[data-sigil-preload="viewport"]')) io.observe(n);
309
+ observe(n);
310
+ }
311
+ }).observe(document.body, { childList: true, subtree: true });
312
+ }
232
313
  }
233
314
 
234
315
  let lastState: {
@@ -358,10 +439,13 @@ export async function navigate(
358
439
  else document.getElementById("grimoire-root")?.replaceChildren(loadingNode);
359
440
  }
360
441
 
361
- const res = await fetch(path, {
362
- headers: { "x-grimoire-navigate": "1" },
363
- redirect: "manual",
364
- });
442
+ let res: Response;
443
+ try {
444
+ res = await (takePrefetched(path) ?? navigateFetch(path));
445
+ } catch {
446
+ // a failed prefetch must not fail the click
447
+ res = await navigateFetch(path);
448
+ }
365
449
  if (navId !== navigationId) return;
366
450
  const contentType = res.headers.get("content-type") ?? "";
367
451
  if (!contentType.includes("application/json")) {
@@ -517,6 +601,7 @@ export function initRouter(
517
601
  paramMatcherFns = ext?.matchers ?? {};
518
602
  routeMap = routes;
519
603
  layoutList = layouts;
604
+ prefetched.clear();
520
605
  disposeCurrentPage = initialDispose ?? null;
521
606
  currentPath = location.pathname;
522
607
  currentSearch = location.search;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Default image loading for server-rendered pages.
3
+ *
4
+ * The first few images are left alone: they are what the visitor sees first
5
+ * and lazy-loading them would delay the largest paint. Every later `<img>`
6
+ * gets `loading="lazy"` and `decoding="async"` so a long grid of thumbnails
7
+ * does not compete with the stylesheet and scripts for the first seconds of
8
+ * bandwidth. An author's own `loading` / `decoding` always wins.
9
+ */
10
+ export const EAGER_IMAGE_COUNT = 4;
11
+
12
+ const IMG_TAG = /<img\b[^>]*>/gi;
13
+ // inline scripts and styles may contain "<img" inside strings
14
+ const RAW_BLOCK = /<(script|style|template)\b[\s\S]*?<\/\1>/gi;
15
+
16
+ export function optimizeImages(html: string): string {
17
+ if (!html.includes("<img")) return html;
18
+ let seen = 0;
19
+ const tag = (t: string) => {
20
+ if (seen++ < EAGER_IMAGE_COUNT) return t;
21
+ let extra = "";
22
+ if (!/\sloading\s*=/i.test(t)) extra += ' loading="lazy"';
23
+ if (!/\sdecoding\s*=/i.test(t)) extra += ' decoding="async"';
24
+ // attributes go before the tag's own trailing space and `/>`
25
+ return extra ? t.replace(/(\s*\/?>)$/, `${extra}$1`) : t;
26
+ };
27
+ let out = "";
28
+ let last = 0;
29
+ for (const m of html.matchAll(RAW_BLOCK)) {
30
+ out += html.slice(last, m.index).replace(IMG_TAG, tag) + m[0];
31
+ last = m.index + m[0].length;
32
+ }
33
+ return out + html.slice(last).replace(IMG_TAG, tag);
34
+ }
@@ -1,4 +1,5 @@
1
1
  import { randomBytes } from "node:crypto";
2
+ import { optimizeImages } from "./images.ts";
2
3
  import { SafeHtml } from "@sigil-dev/runtime";
3
4
  import { startCollecting, stopCollecting } from "../client/deps";
4
5
  import { filterPublic } from "../env/index";
@@ -668,7 +669,7 @@ export async function renderRoute(
668
669
  form: actionFailure?.data,
669
670
  });
670
671
 
671
- bodyHtml = injectCsrf(bodyHtml, csrfToken);
672
+ bodyHtml = optimizeImages(injectCsrf(bodyHtml, csrfToken));
672
673
 
673
674
  const hoistedCss = hoistStylesheets(bodyHtml);
674
675
  const styles = scopedStyles(bodyHtml, nonceAttr);
@@ -8,6 +8,7 @@ import {
8
8
  import { log } from "../logger/instance";
9
9
  import { rewriteAliases } from "../server/resolver";
10
10
  import type { GrimoirePlugin } from "../types";
11
+ import type { ParserPlugin } from "@babel/core";
11
12
 
12
13
  const logger = log.scope("scope");
13
14
  let registered = false;
@@ -67,7 +68,21 @@ export function registerSSRPlugin(
67
68
  configFile: false,
68
69
  babelrc: false,
69
70
  parserOpts: {
70
- plugins: ["typescript", "jsx"],
71
+ // The jsx plugin goes on .tsx files only.
72
+ //
73
+ // With it enabled everywhere, Babel parses `<R>(x: R) => x`
74
+ // as the opening of a JSX element and fails with
75
+ // "Unexpected token `>`". So a generic arrow function in a
76
+ // plain .ts file — completely ordinary TypeScript — could
77
+ // not be compiled. Found while writing the Drizzle adapter
78
+ // recipe, where `transaction: <R>(db, fn) => ...` is the
79
+ // form that removes an `as any`.
80
+ //
81
+ // A .tsx file is genuinely ambiguous (`<R>(x) => x` is
82
+ // JSX there), so .tsx keeps both and users write `<R,>`.
83
+ plugins: path.endsWith(".tsx")
84
+ ? (["typescript", "jsx"] as ParserPlugin[])
85
+ : (["typescript"] as ParserPlugin[]),
71
86
  },
72
87
  plugins: [[sigilPlugin, { mode: "ssr", hash }]],
73
88
  filename: path,
@@ -20,6 +20,10 @@
20
20
  export function isContentAddressed(pathname: string, search: string): boolean {
21
21
  // /style.a1b2c3d4.css — a hash inserted before the extension.
22
22
  if (/\.[0-9a-f]{8,}\.[a-z0-9]+$/i.test(pathname)) return true;
23
+ // /__grimoire__/chunk-jp4kgm87.js — the name the bundler gives a shared
24
+ // chunk: "chunk-" and a hash of the contents. Anchored on the prefix, since
25
+ // a bare "8+ letters before the extension" would also match hero-background.png.
26
+ if (/(^|\/)chunk-[a-z0-9]{8,}\.[a-z0-9]+$/i.test(pathname)) return true;
23
27
  // A non-empty version query, e.g. /style.css?v=3. Deliberately does not
24
28
  // treat `?` with an empty value as addressed: /style.css? is the same
25
29
  // URL and would cache forever without ever changing.
@@ -202,6 +202,16 @@ export async function startCoordinator(options: CoordinatorOptions) {
202
202
  let globalIndex = 0;
203
203
  let nextPort = port + 1;
204
204
 
205
+ // Total workers across every mode, known before the first spawn. A
206
+ // plugin that creates a per-worker resource needs the whole picture to
207
+ // divide a global budget (a connection pool of N across W workers is
208
+ // N/W each) — and the index alone cannot tell it how many siblings
209
+ // exist. Without this, `max: 20` silently means 20 *per worker*.
210
+ const workerCount = Object.values(scale).reduce<number>(
211
+ (sum, n) => sum + (n ?? 0),
212
+ 0,
213
+ );
214
+
205
215
  for (const [mode, count = 0] of Object.entries(scale)) {
206
216
  for (let i = 0; i < count; i++) {
207
217
  const workerPort = nextPort++;
@@ -227,6 +237,9 @@ export async function startCoordinator(options: CoordinatorOptions) {
227
237
  ...publicEnvVars,
228
238
  GRIMOIRE_MODE: mode,
229
239
  GRIMOIRE_WORKER_INDEX: String(i),
240
+ // The sibling count, so a per-worker resource can divide a global
241
+ // budget instead of taking the whole of it.
242
+ GRIMOIRE_WORKER_COUNT: String(workerCount),
230
243
  GRIMOIRE_WORKER_PORT: String(workerPort),
231
244
  GRIMOIRE_INTERNAL_SECRET: secret,
232
245
  GRIMOIRE_WORKER_NAME: descriptor.name ?? `${mode}-${i}`,
@@ -293,13 +306,17 @@ export async function startCoordinator(options: CoordinatorOptions) {
293
306
  const serialized =
294
307
  (await runSerializeLocals(plugins, locals)) ??
295
308
  defaultSerialize(locals, secret);
296
- // the client's own x-grimoire-* headers are dropped: spread next to
297
- // ours under a different case, both reached the worker joined by a
298
- // comma, and the secret check refused the request
309
+ // Only the two headers the coordinator writes itself are dropped from
310
+ // the client's: spread next to ours under a different case, both
311
+ // reached the worker joined by a comma, and the secret check refused
312
+ // the request. The rest of x-grimoire-* is the client talking to the
313
+ // worker: x-grimoire-navigate asks for a page's data as JSON and
314
+ // x-grimoire-form marks an enhanced submit. Dropping them made every
315
+ // client-side navigation come back as a full HTML page, so the router
316
+ // reloaded the document on each click.
299
317
  const forwardHeaders = new Headers();
300
318
  for (const [k, v] of req.headers) {
301
- if (!k.toLowerCase().startsWith("x-grimoire-"))
302
- forwardHeaders.set(k, v);
319
+ if (!INTERNAL_HEADERS.has(k.toLowerCase())) forwardHeaders.set(k, v);
303
320
  }
304
321
  forwardHeaders.set("X-Grimoire-Locals", serialized);
305
322
  forwardHeaders.set("X-Grimoire-Internal", secret);
@@ -394,6 +411,9 @@ interface WsProxyData {
394
411
  upstream?: WebSocket;
395
412
  }
396
413
 
414
+ /** Headers the coordinator sets itself; a client's copy is never forwarded. */
415
+ const INTERNAL_HEADERS = new Set(["x-grimoire-locals", "x-grimoire-internal"]);
416
+
397
417
  /** Headers for the coordinator's own socket to the worker. */
398
418
  function upstreamWsHeaders(
399
419
  req: Request,
@@ -405,7 +425,7 @@ function upstreamWsHeaders(
405
425
  // the WebSocket client writes its own handshake headers
406
426
  if (
407
427
  key.startsWith("sec-websocket-") ||
408
- key.startsWith("x-grimoire-") ||
428
+ INTERNAL_HEADERS.has(key) ||
409
429
  key === "upgrade" ||
410
430
  key === "connection" ||
411
431
  key === "host"
@@ -30,7 +30,12 @@ import type {
30
30
  RequestEvent,
31
31
  ResolveFunction,
32
32
  } from "./hooks";
33
- import { runDeserializeLocals, runHook, runRequestHooks } from "./plugins";
33
+ import {
34
+ collectServices,
35
+ runDeserializeLocals,
36
+ runHook,
37
+ runRequestHooks,
38
+ } from "./plugins";
34
39
  import { projectAliases, resolverPlugin } from "./resolver";
35
40
 
36
41
  const logger = log.scope("server");
@@ -61,6 +66,25 @@ function watchRoots(projectRoot: string, routesDir: string): string[] {
61
66
  return roots;
62
67
  }
63
68
 
69
+ /**
70
+ * ETags by file, keyed on size and modification time. Hashing the content on
71
+ * every request read the whole file and ran sha256 over it for each page
72
+ * view; the answer only changes when the file does.
73
+ */
74
+ const etags = new Map<string, { stamp: string; etag: string }>();
75
+
76
+ async function etagFor(file: ReturnType<typeof Bun.file>): Promise<string> {
77
+ const key = file.name ?? "";
78
+ const stamp = `${file.size}:${file.lastModified}`;
79
+ const hit = etags.get(key);
80
+ if (hit && hit.stamp === stamp) return hit.etag;
81
+ const hasher = new Bun.CryptoHasher("sha256");
82
+ hasher.update(await file.arrayBuffer());
83
+ const etag = `"${hasher.digest("hex").slice(0, 16)}"`;
84
+ etags.set(key, { stamp, etag });
85
+ return etag;
86
+ }
87
+
64
88
  /**
65
89
  * Serve a file from public/, or return null when the path is not one.
66
90
  *
@@ -97,9 +121,7 @@ async function servePublicAsset(
97
121
  if (policy === "revalidate") {
98
122
  // The hash of the content, so a revalidation can be answered with
99
123
  // 304 instead of the whole file.
100
- const hasher = new Bun.CryptoHasher("sha256");
101
- hasher.update(await file.arrayBuffer());
102
- const etag = `"${hasher.digest("hex").slice(0, 16)}"`;
124
+ const etag = await etagFor(file);
103
125
  headers["ETag"] = etag;
104
126
 
105
127
  // Compared here rather than left to Bun: a Bun.file body does not
@@ -311,6 +333,15 @@ export async function createServer(config: GrimoireConfig = {}) {
311
333
  handleFetch: hooksHandleFetch,
312
334
  } = await loadHooks(process.cwd());
313
335
 
336
+ // Resolved once at startup, not per request: services() may open a pool,
337
+ // and the object is immutable for the process lifetime, so building it
338
+ // inside handleRequest would open a connection per visitor.
339
+ //
340
+ // Before init(), so hooks.server.ts can use what plugins opened — a
341
+ // database for a warm-up query or a migration check is the usual case,
342
+ // and running init first meant it could only fail.
343
+ const services = await collectServices(plugins);
344
+
314
345
  // Run init hook if present
315
346
  await hooksInit?.();
316
347
 
@@ -331,6 +362,12 @@ export async function createServer(config: GrimoireConfig = {}) {
331
362
  const locals: App.Locals = rawLocals
332
363
  ? ((await runDeserializeLocals(plugins, rawLocals)) ?? {})
333
364
  : {};
365
+ // Plugin services sit under the request's own locals: what the app
366
+ // set (a session, a user) always wins over what a plugin declared,
367
+ // so a plugin cannot clobber auth by defining a common key.
368
+ for (const [key, value] of Object.entries(services)) {
369
+ if (!(key in locals)) locals[key] = value;
370
+ }
334
371
  const url = new URL(req.url);
335
372
 
336
373
  if (dev && url.pathname === "/__grimoire__/hmr") {