@sigil-dev/grimoire 0.9.11 → 0.9.12

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
@@ -19,6 +19,7 @@ export type {
19
19
  export { createHooks, sequence } from "./src/server/hooks";
20
20
  export type {
21
21
  BuiltinWorkerMode,
22
+ CliCommand,
22
23
  CoordinatorContext,
23
24
  GrimoireConfig,
24
25
  GrimoirePlugin,
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.11",
7
+ "version": "0.9.12",
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.11",
27
- "@sigil-dev/runtime": "0.9.11",
26
+ "@sigil-dev/compiler": "0.9.12",
27
+ "@sigil-dev/runtime": "0.9.12",
28
28
  "vite": "^8.0.16"
29
29
  },
30
30
  "peerDependencies": {
package/server.ts CHANGED
@@ -1,3 +1,4 @@
1
+ export { afterResponse } from "./src/server/after-response.ts";
1
2
  export { log } from "./src/logger/instance.ts";
2
3
  export { scanRoutes } from "./src/routing/scanner";
3
4
  export { createServer } from "./src/server";
@@ -0,0 +1,194 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { log } from "../logger/instance.ts";
3
+
4
+ const logger = log.scope("server");
5
+
6
+ /**
7
+ * Tasks collected for the in-flight request.
8
+ *
9
+ * AsyncLocalStorage is what makes afterResponse() work without threading a
10
+ * context argument through every function that might want to defer work.
11
+ * A plain module-level array would interleave badly under concurrency: two
12
+ * requests running at once could collect each other's tasks, and a task
13
+ * would run at the end of the wrong response.
14
+ */
15
+ interface RequestScope {
16
+ tasks: Array<() => unknown>;
17
+ /** Resolves when fire() has run every task, so drain can wait for this. */
18
+ flushed: Promise<void>;
19
+ markFlushed: () => void;
20
+ }
21
+ const scope = new AsyncLocalStorage<RequestScope>();
22
+
23
+ let inflight = new Set<Promise<unknown>>();
24
+ /**
25
+ * Flush promises for requests whose body has not finished streaming.
26
+ *
27
+ * Tracked separately from `inflight` because a task is not running yet while
28
+ * its response is still streaming — a shutdown that only waits on running
29
+ * work would return while queued work was still pending.
30
+ */
31
+ let unflushed = new Set<Promise<void>>();
32
+ let shuttingDown = false;
33
+
34
+ /**
35
+ * Run work after the response for the current request has been flushed.
36
+ *
37
+ * Does not block the response, and does not survive a restart — a task that
38
+ * has not finished is lost if the process exits. That makes this for work
39
+ * that is cheap and re-derivable: analytics, cache warming, a last-seen
40
+ * timestamp. Anything a user was promised belongs in a durable queue, and
41
+ * this is the call site to change when a job starts to matter.
42
+ *
43
+ * Errors are logged, never thrown. The response is already sent by the time
44
+ * a task runs, so a failure cannot be reported to anyone.
45
+ *
46
+ * Outside a request (at startup, in `init`) the task runs on the next
47
+ * microtask instead. That keeps the call valid anywhere without pretending
48
+ * there was a response to wait for.
49
+ */
50
+ export function afterResponse(fn: () => unknown): Promise<unknown> {
51
+ if (shuttingDown) {
52
+ return Promise.reject(
53
+ new Error("afterResponse() called during shutdown"),
54
+ );
55
+ }
56
+
57
+ // Wrap so a synchronous throw inside fn becomes a rejection instead of
58
+ // propagating out of the caller's await.
59
+ const run = async () => {
60
+ try {
61
+ await fn();
62
+ } catch (e) {
63
+ logger.error("afterResponse task failed:", e);
64
+ }
65
+ };
66
+
67
+ const current = scope.getStore();
68
+ if (!current) {
69
+ return track(run());
70
+ }
71
+
72
+ current.tasks.push(() => track(run()));
73
+ return Promise.resolve();
74
+ }
75
+
76
+ function deferred(): { flushed: Promise<void>; markFlushed: () => void } {
77
+ let mark!: () => void;
78
+ const flushed = new Promise<void>((resolve) => {
79
+ mark = resolve;
80
+ });
81
+ return { flushed, markFlushed: mark };
82
+ }
83
+
84
+ function track(p: Promise<unknown>): Promise<unknown> {
85
+ inflight.add(p);
86
+ p.finally(() => inflight.delete(p));
87
+ return p;
88
+ }
89
+
90
+ /**
91
+ * Run a handler inside a request scope, then fire the collected tasks once
92
+ * the response body has finished streaming.
93
+ *
94
+ * Wrapping the body is what makes "after the response" true for streaming
95
+ * responses: scheduling on the handler's return would run the task while
96
+ * the client is still receiving. Firing on the stream's end means a slow
97
+ * download does not start the work early.
98
+ */
99
+ export async function withAfterResponse(
100
+ req: Request,
101
+ handler: (req: Request) => Response | Promise<Response>,
102
+ ): Promise<Response> {
103
+ const requestScope: RequestScope = { tasks: [], ...deferred() };
104
+ unflushed.add(requestScope.flushed);
105
+ requestScope.flushed.finally(() => unflushed.delete(requestScope.flushed));
106
+ const response = await scope.run(requestScope, () => handler(req));
107
+
108
+ const fire = () => {
109
+ requestScope.markFlushed();
110
+ if (requestScope.tasks.length === 0) return;
111
+ // Copy first: a task may register another task.
112
+ const tasks = requestScope.tasks.splice(0);
113
+ for (const t of tasks) t();
114
+ };
115
+
116
+ if (!(response instanceof Response) || response.body === null) {
117
+ fire();
118
+ return response as Response;
119
+ }
120
+
121
+ const { readable, writable } = new TransformStream();
122
+ // Errors on the original body propagate, and the tasks still run: a
123
+ // client disconnecting mid-stream must not silently skip the work.
124
+ Promise.resolve(response.body)
125
+ .then((body) => body?.pipeTo(writable))
126
+ .catch(() => writable.abort())
127
+ .finally(fire);
128
+
129
+ return new Response(readable, {
130
+ status: response.status,
131
+ statusText: response.statusText,
132
+ headers: response.headers,
133
+ });
134
+ }
135
+
136
+ /**
137
+ * Wait for in-flight afterResponse tasks so a graceful shutdown does not
138
+ * abandon work already started. Subsequent registrations are rejected.
139
+ */
140
+ export async function drainAfterResponse(timeoutMs = 5000): Promise<void> {
141
+ shuttingDown = true;
142
+
143
+ const deadline = Date.now() + timeoutMs;
144
+ const timedOut = Symbol("timeout");
145
+
146
+ const waitFor = async <T>(work: Promise<T>): Promise<T | typeof timedOut> => {
147
+ const left = deadline - Date.now();
148
+ if (left <= 0) return timedOut;
149
+ let timer: ReturnType<typeof setTimeout> | undefined;
150
+ const result = await Promise.race([
151
+ work,
152
+ new Promise<typeof timedOut>((resolve) => {
153
+ timer = setTimeout(() => resolve(timedOut), left);
154
+ }),
155
+ ]);
156
+ if (timer) clearTimeout(timer);
157
+ return result;
158
+ };
159
+
160
+ // Two waits, not one. A task registered during a request is not in
161
+ // `inflight` until the response body has flushed and it actually
162
+ // starts, so draining only that set would return while a response was
163
+ // still streaming and its work was still queued.
164
+ const flushed = await waitFor(Promise.allSettled([...unflushed]));
165
+ if (flushed === timedOut) {
166
+ logger.warn(
167
+ `responses were still streaming after ${timeoutMs}ms; ` +
168
+ `afterResponse tasks for them will be lost`,
169
+ );
170
+ return;
171
+ }
172
+
173
+ if (inflight.size === 0) {
174
+ unflushed.clear();
175
+ return;
176
+ }
177
+
178
+ logger.info(`waiting for ${inflight.size} afterResponse task(s)...`);
179
+ const result = await waitFor(Promise.allSettled([...inflight]));
180
+ if (result === timedOut) {
181
+ logger.warn(
182
+ `afterResponse tasks did not finish within ${timeoutMs}ms, abandoning them`,
183
+ );
184
+ }
185
+ inflight.clear();
186
+ unflushed.clear();
187
+ }
188
+
189
+ /** Test-only: reset module state between cases. */
190
+ export function _resetAfterResponseForTest(): void {
191
+ inflight = new Set();
192
+ unflushed = new Set();
193
+ shuttingDown = false;
194
+ }
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The cache policy for files served out of public/.
3
+ *
4
+ * Extracted from the server so the decision can be tested without booting
5
+ * one, and so there is exactly one copy of it. A policy test that keeps its
6
+ * own duplicate of the logic passes forever regardless of what the server
7
+ * does, which is worse than having no test.
8
+ */
9
+
10
+ /**
11
+ * A URL that changes whenever its content changes: a build-stamped hash, or
12
+ * a version query the app bumps per deploy.
13
+ *
14
+ * `?v=` deliberately counts. A file that a caller knows to re-request under
15
+ * a new query is content-addressed by that query, and that is the same
16
+ * guarantee a hash gives — the URL is the key. Requiring a literal hash in
17
+ * the path would send every project that uses the query form back to
18
+ * revalidation for no reason.
19
+ */
20
+ export function isContentAddressed(pathname: string, search: string): boolean {
21
+ // /style.a1b2c3d4.css — a hash inserted before the extension.
22
+ if (/\.[0-9a-f]{8,}\.[a-z0-9]+$/i.test(pathname)) return true;
23
+ // A non-empty version query, e.g. /style.css?v=3. Deliberately does not
24
+ // treat `?` with an empty value as addressed: /style.css? is the same
25
+ // URL and would cache forever without ever changing.
26
+ return /[?&]v=[^&#]+/.test(search);
27
+ }
28
+
29
+ /** The `Cache-Control` for a public asset, by its URL. */
30
+ export function cacheControlFor(
31
+ pathname: string,
32
+ search: string,
33
+ ): "no-cache" | "immutable" | "revalidate" {
34
+ // The document is what references the assets. Caching it hard means
35
+ // serving stale references to assets that are long gone.
36
+ if (pathname === "/" || pathname.endsWith(".html")) return "no-cache";
37
+ if (isContentAddressed(pathname, search)) return "immutable";
38
+ // Cached, but revalidated every time. Costs a conditional request and
39
+ // guarantees a deploy is visible on the next load — the right trade for a
40
+ // file whose URL is not content-addressed.
41
+ return "revalidate";
42
+ }
43
+
44
+ export const CACHE_CONTROL: Record<
45
+ ReturnType<typeof cacheControlFor>,
46
+ string
47
+ > = {
48
+ "no-cache": "no-cache",
49
+ immutable: "public, max-age=31536000, immutable",
50
+ revalidate: "public, max-age=0, must-revalidate",
51
+ };