@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 +1 -0
- package/package.json +3 -3
- package/server.ts +1 -0
- package/src/server/after-response.ts +194 -0
- package/src/server/asset-cache.ts +51 -0
- package/src/server/index.ts +572 -467
- package/src/server/worker.ts +13 -1
- package/src/types.ts +44 -1
- package/test/after-response.test.ts +113 -0
- package/test/asset-cache-policy.test.ts +83 -0
package/index.ts
CHANGED
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.
|
|
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.
|
|
27
|
-
"@sigil-dev/runtime": "0.9.
|
|
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
|
@@ -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
|
+
};
|