@sigil-dev/grimoire 0.9.13 → 0.9.15

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.
@@ -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.
@@ -0,0 +1,114 @@
1
+ /**
2
+ * In-memory stale-while-revalidate cache for expensive server-side values.
3
+ *
4
+ * The common hand-rolled version is "if the entry is older than an hour,
5
+ * rebuild it inline", which makes one unlucky visitor per hour (per worker)
6
+ * wait for the rebuild. Here, once a value exists it is always returned at
7
+ * once; an expired one is refreshed in the background, by a single shared
8
+ * call, while callers keep getting the old value.
9
+ *
10
+ * const costumeIndex = cached(() => buildIndex(), { ttl: 3600_000 });
11
+ * const index = await costumeIndex();
12
+ *
13
+ * const player = cachedBy((id: string) => fetchPlayer(id), { ttl: 60_000 });
14
+ * await player("123");
15
+ */
16
+
17
+ export interface CachedOptions {
18
+ /** How long (ms) a value is fresh. */
19
+ ttl: number;
20
+ /**
21
+ * How long (ms) past `ttl` a stale value may still be served while the
22
+ * refresh runs. Past it, the next caller waits. Default: forever.
23
+ */
24
+ staleFor?: number;
25
+ /** cachedBy only: the most keys held; the least recently used goes first. */
26
+ max?: number;
27
+ /** Called when a background refresh fails; the stale value stays. */
28
+ onError?: (error: unknown) => void;
29
+ }
30
+
31
+ interface Entry<T> {
32
+ value: T;
33
+ at: number;
34
+ }
35
+
36
+ export interface CachedFn<A extends unknown[], T> {
37
+ (...args: A): Promise<T>;
38
+ /** Drop one entry (or all with no argument); the next call refetches. */
39
+ invalidate(...args: A | []): void;
40
+ }
41
+
42
+ function build<A extends unknown[], T>(
43
+ fn: (...args: A) => Promise<T>,
44
+ keyOf: (args: A) => string,
45
+ opts: CachedOptions,
46
+ ): CachedFn<A, T> {
47
+ const { ttl, staleFor = Number.POSITIVE_INFINITY, max = 500, onError } = opts;
48
+ const entries = new Map<string, Entry<T>>();
49
+ const running = new Map<string, Promise<T>>();
50
+
51
+ function refresh(key: string, args: A): Promise<T> {
52
+ const existing = running.get(key);
53
+ if (existing) return existing;
54
+ const p = fn(...args).then(
55
+ (value) => {
56
+ running.delete(key);
57
+ entries.delete(key); // re-insert so insertion order = recency
58
+ entries.set(key, { value, at: Date.now() });
59
+ while (entries.size > max) {
60
+ const oldest = entries.keys().next().value as string;
61
+ entries.delete(oldest);
62
+ }
63
+ return value;
64
+ },
65
+ (e) => {
66
+ running.delete(key);
67
+ throw e;
68
+ },
69
+ );
70
+ running.set(key, p);
71
+ return p;
72
+ }
73
+
74
+ const call = ((...args: A): Promise<T> => {
75
+ const key = keyOf(args);
76
+ const hit = entries.get(key);
77
+ if (hit) {
78
+ const age = Date.now() - hit.at;
79
+ entries.delete(key); // a read counts as use
80
+ entries.set(key, hit);
81
+ if (age < ttl) return Promise.resolve(hit.value);
82
+ if (age < ttl + staleFor) {
83
+ refresh(key, args).catch((e) => onError?.(e));
84
+ return Promise.resolve(hit.value);
85
+ }
86
+ }
87
+ return refresh(key, args);
88
+ }) as CachedFn<A, T>;
89
+
90
+ call.invalidate = (...args: A | []) => {
91
+ if (args.length === 0) {
92
+ entries.clear();
93
+ return;
94
+ }
95
+ entries.delete(keyOf(args as A));
96
+ };
97
+ return call;
98
+ }
99
+
100
+ /** A value with no arguments, cached process-wide. */
101
+ export function cached<T>(
102
+ fn: () => Promise<T>,
103
+ opts: CachedOptions,
104
+ ): CachedFn<[], T> {
105
+ return build(fn, () => "", opts);
106
+ }
107
+
108
+ /** A value per argument list (compared as JSON), with an LRU cap. */
109
+ export function cachedBy<A extends unknown[], T>(
110
+ fn: (...args: A) => Promise<T>,
111
+ opts: CachedOptions,
112
+ ): CachedFn<A, T> {
113
+ return build(fn, (args) => JSON.stringify(args), opts);
114
+ }
@@ -1,4 +1,6 @@
1
1
  import { existsSync, mkdirSync } from "node:fs";
2
+ import { setServerTiming } from "../rendering/timing.ts";
3
+ import { preloadModules, startWarming, type Warmer } from "./warm.ts";
2
4
  import { isAbsolute, join } from "node:path";
3
5
  import { plugin as bunPlugin, type ServerWebSocket } from "bun";
4
6
  import { getDevModule } from "../dev/compile-module.ts";
@@ -66,6 +68,25 @@ function watchRoots(projectRoot: string, routesDir: string): string[] {
66
68
  return roots;
67
69
  }
68
70
 
71
+ /**
72
+ * ETags by file, keyed on size and modification time. Hashing the content on
73
+ * every request read the whole file and ran sha256 over it for each page
74
+ * view; the answer only changes when the file does.
75
+ */
76
+ const etags = new Map<string, { stamp: string; etag: string }>();
77
+
78
+ async function etagFor(file: ReturnType<typeof Bun.file>): Promise<string> {
79
+ const key = file.name ?? "";
80
+ const stamp = `${file.size}:${file.lastModified}`;
81
+ const hit = etags.get(key);
82
+ if (hit && hit.stamp === stamp) return hit.etag;
83
+ const hasher = new Bun.CryptoHasher("sha256");
84
+ hasher.update(await file.arrayBuffer());
85
+ const etag = `"${hasher.digest("hex").slice(0, 16)}"`;
86
+ etags.set(key, { stamp, etag });
87
+ return etag;
88
+ }
89
+
69
90
  /**
70
91
  * Serve a file from public/, or return null when the path is not one.
71
92
  *
@@ -102,9 +123,7 @@ async function servePublicAsset(
102
123
  if (policy === "revalidate") {
103
124
  // The hash of the content, so a revalidation can be answered with
104
125
  // 304 instead of the whole file.
105
- const hasher = new Bun.CryptoHasher("sha256");
106
- hasher.update(await file.arrayBuffer());
107
- const etag = `"${hasher.digest("hex").slice(0, 16)}"`;
126
+ const etag = await etagFor(file);
108
127
  headers["ETag"] = etag;
109
128
 
110
129
  // Compared here rather than left to Bun: a Bun.file body does not
@@ -208,6 +227,7 @@ export async function createServer(config: GrimoireConfig = {}) {
208
227
  const hmr = dev ? new HmrServer() : null;
209
228
 
210
229
  const aliases = finalConfig.alias ?? {};
230
+ setServerTiming(finalConfig.serverTiming ?? dev);
211
231
 
212
232
  if (dev) {
213
233
  const { ensureRuntimeBundle } = await import("../dev/runtime-bundle.ts");
@@ -915,20 +935,54 @@ export async function createServer(config: GrimoireConfig = {}) {
915
935
  // Bun.serve is called here rather than alongside the websocket config
916
936
  // because handleRequest is referenced before its declaration; function
917
937
  // hoisting makes that safe, and this keeps the two blocks readable.
938
+ // Wrapping is what makes afterResponse() mean "after the response",
939
+ // including for streaming responses: the tasks fire when the body
940
+ // finishes, not when the handler returns.
941
+ const fetchHandler = (req: Request) => withAfterResponse(req, handleRequest);
942
+
943
+ // Before the port opens, so the first visitor never pays for compiling a
944
+ // route: a worker only reports ready once this has finished.
945
+ const warmConfig = finalConfig.warm;
946
+ if (!dev && warmConfig?.preload !== false) {
947
+ const files = [
948
+ ...tree.routes,
949
+ ...tree.layouts,
950
+ ...tree.servers,
951
+ ...tree.errors,
952
+ ].map((rf: { filePath: string }) => rf.filePath);
953
+ const t0 = performance.now();
954
+ const loaded = await preloadModules(files, loader, (msg, err) =>
955
+ logger.warn(msg, err),
956
+ );
957
+ logger.info(
958
+ `preloaded ${loaded}/${new Set(files).size} route modules in ${Math.round(performance.now() - t0)}ms`,
959
+ );
960
+ }
961
+
918
962
  const server = Bun.serve({
919
963
  port,
920
964
  hostname: host,
921
- // Wrapping is what makes afterResponse() mean "after the response",
922
- // including for streaming responses: the tasks fire when the body
923
- // finishes, not when the handler returns.
924
- fetch: (req) => withAfterResponse(req, handleRequest),
965
+ fetch: fetchHandler,
925
966
  ...wsConfig,
926
967
  });
927
968
 
969
+ let warmer: Warmer | null = null;
970
+ if (!dev && warmConfig?.paths?.length) {
971
+ warmer = startWarming({
972
+ paths: warmConfig.paths,
973
+ every: warmConfig.every,
974
+ origin: `http://${host}:${server.port}`,
975
+ headers: finalConfig._warmHeaders,
976
+ handle: async (req) => fetchHandler(req),
977
+ log: (msg) => logger.info(msg),
978
+ });
979
+ }
980
+
928
981
  let stopping = false;
929
982
  const handleShutdown = async () => {
930
983
  if (stopping) return;
931
984
  stopping = true;
985
+ warmer?.stop();
932
986
  await runHook(plugins, "onStop", "shutdown");
933
987
  // Drain before stopping, so a task already registered for a response
934
988
  // that has been sent gets to finish rather than being killed with the
@@ -0,0 +1,91 @@
1
+ /**
2
+ * Cache warming for a production server.
3
+ *
4
+ * Two independent costs land on whoever visits first after a boot: importing
5
+ * each route's module (compiling it, and everything it imports), and whatever
6
+ * the route's own load functions cache in memory. `preloadModules` pays the
7
+ * first at startup; `startWarming` pays the second by requesting configured
8
+ * paths through the real request handler, so the app's own caches fill exactly
9
+ * as a visitor would fill them.
10
+ *
11
+ * Each `sigil start` worker is its own process with its own memory, which is
12
+ * why this lives in the server and not in a script that hits the public URL:
13
+ * one request would warm one worker and leave the rest cold.
14
+ */
15
+
16
+ export interface WarmConfig {
17
+ /** Paths requested after startup, one at a time, e.g. ["/costumes", "/songs"]. */
18
+ paths?: string[];
19
+ /** Request them again this often (ms) so in-memory TTL caches never lapse. */
20
+ every?: number;
21
+ /** Import every route module before the server accepts traffic. Default true. */
22
+ preload?: boolean;
23
+ }
24
+
25
+ type Loader = (path: string) => Promise<unknown>;
26
+
27
+ export async function preloadModules(
28
+ files: string[],
29
+ load: Loader,
30
+ warn: (msg: string, err: unknown) => void,
31
+ ): Promise<number> {
32
+ const unique = [...new Set(files)];
33
+ const results = await Promise.allSettled(unique.map((f) => load(f)));
34
+ let loaded = 0;
35
+ results.forEach((r, i) => {
36
+ if (r.status === "fulfilled") loaded++;
37
+ else warn(`could not preload ${unique[i]}:`, r.reason);
38
+ });
39
+ return loaded;
40
+ }
41
+
42
+ export interface Warmer {
43
+ stop(): void;
44
+ /** Resolves when the first pass over `paths` has finished. */
45
+ firstPass: Promise<void>;
46
+ }
47
+
48
+ export function startWarming(opts: {
49
+ paths: string[];
50
+ every?: number;
51
+ origin: string;
52
+ headers?: Record<string, string>;
53
+ handle: (req: Request) => Promise<Response>;
54
+ log: (msg: string) => void;
55
+ }): Warmer {
56
+ const { paths, every, origin, headers, handle, log } = opts;
57
+ let stopped = false;
58
+
59
+ async function pass(): Promise<void> {
60
+ for (const path of paths) {
61
+ if (stopped) return;
62
+ const t0 = performance.now();
63
+ try {
64
+ const res = await handle(new Request(new URL(path, origin), { headers }));
65
+ // drain the body: a streamed page and its deferred data only
66
+ // finish (and only fill their caches) when someone reads it all
67
+ await res.arrayBuffer();
68
+ log(`warmed ${path} (${res.status}) in ${Math.round(performance.now() - t0)}ms`);
69
+ } catch (e) {
70
+ log(`warming ${path} failed: ${e instanceof Error ? e.message : String(e)}`);
71
+ }
72
+ }
73
+ }
74
+
75
+ const firstPass = pass();
76
+ let timer: ReturnType<typeof setInterval> | undefined;
77
+ if (every && every > 0) {
78
+ timer = setInterval(() => {
79
+ void pass();
80
+ }, every);
81
+ // a warm timer must never keep a stopping process alive
82
+ (timer as { unref?: () => void }).unref?.();
83
+ }
84
+ return {
85
+ firstPass,
86
+ stop() {
87
+ stopped = true;
88
+ if (timer) clearInterval(timer);
89
+ },
90
+ };
91
+ }
@@ -27,6 +27,7 @@ export async function startWorker(options: WorkerOptions) {
27
27
  ...options.config,
28
28
  plugins: [workerAuthPlugin, ...plugins],
29
29
  _skipBuild: true,
30
+ _warmHeaders: { "X-Grimoire-Internal": secret },
30
31
  });
31
32
  }
32
33
 
package/src/types.ts CHANGED
@@ -312,7 +312,21 @@ export interface GrimoireConfig {
312
312
  alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
313
313
  cspNonce?: string; // CSP nonce for <script>/<style> tags
314
314
  bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
315
+ /**
316
+ * Send a `Server-Timing` header (load / render durations) on page
317
+ * responses. Default: on in dev, off in production.
318
+ */
319
+ serverTiming?: boolean;
315
320
  _skipBuild?: boolean;
321
+ /**
322
+ * Production cache warming. Route modules are imported before the server
323
+ * takes traffic; `paths` are then requested through the real handler (once
324
+ * per worker, and again every `every` ms) so in-memory caches are full
325
+ * before a visitor arrives.
326
+ */
327
+ warm?: import("./server/warm.ts").WarmConfig;
328
+ /** Set by the worker: headers the server's own warm-up requests carry. */
329
+ _warmHeaders?: Record<string, string>;
316
330
  }
317
331
 
318
332
  export function defineConfig(config: GrimoireConfig): GrimoireConfig {
@@ -23,6 +23,19 @@ describe("isContentAddressed", () => {
23
23
  expect(isContentAddressed("/style.deadbeef0123456789.css", "")).toBe(true);
24
24
  });
25
25
 
26
+ test("a bundler chunk name counts", () => {
27
+ // Shared chunks are named for their contents, and every page load
28
+ // fetches them. Without this they revalidated each time.
29
+ expect(isContentAddressed("/__grimoire__/chunk-jp4kgm87.js", "")).toBe(true);
30
+ expect(cacheControlFor("/__grimoire__/chunk-1pk15q3t.js", "")).toBe("immutable");
31
+ });
32
+
33
+ test("chunk- must be the whole stem, not a lookalike", () => {
34
+ expect(isContentAddressed("/chunk-list.js", "")).toBe(false);
35
+ expect(isContentAddressed("/img/hero-background.png", "")).toBe(false);
36
+ expect(isContentAddressed("/notchunk-abcdef12.js", "")).toBe(false);
37
+ });
38
+
26
39
  test("a bare filename does not count", () => {
27
40
  // The bug this policy exists to prevent: a year-long cache at a URL
28
41
  // that never changes, so an edited stylesheet is never seen.
@@ -0,0 +1,126 @@
1
+ import { describe, expect, test } from "bun:test";
2
+ import { cached, cachedBy } from "../src/server/cached.ts";
3
+
4
+ const tick = (ms: number) => Bun.sleep(ms);
5
+
6
+ describe("cached", () => {
7
+ test("returns the same value while fresh and builds once", async () => {
8
+ let n = 0;
9
+ const get = cached(async () => ++n, { ttl: 1000 });
10
+ expect(await get()).toBe(1);
11
+ expect(await get()).toBe(1);
12
+ expect(n).toBe(1);
13
+ });
14
+
15
+ test("concurrent first calls share one build", async () => {
16
+ let n = 0;
17
+ const get = cached(
18
+ async () => {
19
+ await tick(20);
20
+ return ++n;
21
+ },
22
+ { ttl: 1000 },
23
+ );
24
+ expect(await Promise.all([get(), get(), get()])).toEqual([1, 1, 1]);
25
+ expect(n).toBe(1);
26
+ });
27
+
28
+ test("an expired value is served at once while one refresh runs", async () => {
29
+ let n = 0;
30
+ const get = cached(
31
+ async () => {
32
+ await tick(30);
33
+ return ++n;
34
+ },
35
+ { ttl: 20 },
36
+ );
37
+ await get();
38
+ await tick(40);
39
+ const t0 = performance.now();
40
+ expect(await get()).toBe(1); // stale, instantly
41
+ expect(await get()).toBe(1); // refresh still in flight, still one
42
+ expect(performance.now() - t0).toBeLessThan(25);
43
+ await tick(50);
44
+ expect(n).toBe(2);
45
+ expect(await get()).toBe(2);
46
+ });
47
+
48
+ test("past staleFor the caller waits for the fresh value", async () => {
49
+ let n = 0;
50
+ const get = cached(async () => ++n, { ttl: 10, staleFor: 10 });
51
+ await get();
52
+ await tick(40);
53
+ expect(await get()).toBe(2);
54
+ });
55
+
56
+ test("a failed background refresh keeps the stale value and reports it", async () => {
57
+ let n = 0;
58
+ const errors: unknown[] = [];
59
+ const get = cached(
60
+ async () => {
61
+ if (++n > 1) throw new Error("upstream down");
62
+ return "v1";
63
+ },
64
+ { ttl: 10, onError: (e) => errors.push(e) },
65
+ );
66
+ await get();
67
+ await tick(20);
68
+ expect(await get()).toBe("v1");
69
+ await tick(10);
70
+ expect(errors).toHaveLength(1);
71
+ expect(await get()).toBe("v1");
72
+ });
73
+
74
+ test("a failed first build throws and is not cached", async () => {
75
+ let n = 0;
76
+ const get = cached(
77
+ async () => {
78
+ if (++n === 1) throw new Error("first fails");
79
+ return "ok";
80
+ },
81
+ { ttl: 1000 },
82
+ );
83
+ await expect(get()).rejects.toThrow("first fails");
84
+ expect(await get()).toBe("ok");
85
+ });
86
+
87
+ test("invalidate forces the next call to rebuild", async () => {
88
+ let n = 0;
89
+ const get = cached(async () => ++n, { ttl: 1000 });
90
+ await get();
91
+ get.invalidate();
92
+ expect(await get()).toBe(2);
93
+ });
94
+ });
95
+
96
+ describe("cachedBy", () => {
97
+ test("caches per argument and evicts the least recently used past max", async () => {
98
+ const calls: string[] = [];
99
+ const get = cachedBy(
100
+ async (id: string) => {
101
+ calls.push(id);
102
+ return id.toUpperCase();
103
+ },
104
+ { ttl: 1000, max: 2 },
105
+ );
106
+ await get("a");
107
+ await get("b");
108
+ await get("a"); // hit: "b" is now the least recently used
109
+ expect(calls).toEqual(["a", "b"]);
110
+ await get("c"); // pushes out "b", not "a"
111
+ await get("a");
112
+ expect(calls).toEqual(["a", "b", "c"]);
113
+ await get("b");
114
+ expect(calls).toEqual(["a", "b", "c", "b"]);
115
+ });
116
+
117
+ test("invalidate(key) drops only that key", async () => {
118
+ let n = 0;
119
+ const get = cachedBy(async (_id: string) => ++n, { ttl: 1000 });
120
+ await get("x");
121
+ await get("y");
122
+ get.invalidate("x");
123
+ expect(await get("y")).toBe(2);
124
+ expect(await get("x")).toBe(3);
125
+ });
126
+ });