@sigil-dev/grimoire 0.9.12 → 0.9.13
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 +4 -1
- package/package.json +3 -3
- package/src/client/deferred.ts +179 -0
- package/src/rendering/ssrPlugin.ts +16 -1
- package/src/server/coordinator.ts +26 -6
- package/src/server/index.ts +21 -1
- package/src/server/plugins.ts +35 -0
- package/src/types.ts +74 -0
- package/test/coordinator.test.ts +9 -0
- package/test/deferred.test.ts +256 -0
- package/test/parser-plugins.test.ts +92 -0
- package/test/plugin-services-context.test.ts +97 -0
- package/test/services.test.ts +90 -0
- package/test/streaming.test.ts +56 -0
- package/test/worker-context.test.ts +59 -0
- package/test/workspace-files.test.ts +146 -0
- package/test/workspace-versions.test.ts +131 -0
- package/.grimoire/_routes.ts +0 -4
- package/public/__grimoire__/client.js +0 -55
- package/public/__grimoire__/hydrate.js +0 -63
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.
|
|
7
|
+
"version": "0.9.13",
|
|
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.13",
|
|
27
|
+
"@sigil-dev/runtime": "0.9.13",
|
|
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
|
+
}
|
|
@@ -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
|
-
|
|
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,
|
|
@@ -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
|
|
297
|
-
// ours under a different case, both
|
|
298
|
-
// comma, and the secret check refused
|
|
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().
|
|
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
|
-
|
|
428
|
+
INTERNAL_HEADERS.has(key) ||
|
|
409
429
|
key === "upgrade" ||
|
|
410
430
|
key === "connection" ||
|
|
411
431
|
key === "host"
|
package/src/server/index.ts
CHANGED
|
@@ -30,7 +30,12 @@ import type {
|
|
|
30
30
|
RequestEvent,
|
|
31
31
|
ResolveFunction,
|
|
32
32
|
} from "./hooks";
|
|
33
|
-
import {
|
|
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");
|
|
@@ -311,6 +316,15 @@ export async function createServer(config: GrimoireConfig = {}) {
|
|
|
311
316
|
handleFetch: hooksHandleFetch,
|
|
312
317
|
} = await loadHooks(process.cwd());
|
|
313
318
|
|
|
319
|
+
// Resolved once at startup, not per request: services() may open a pool,
|
|
320
|
+
// and the object is immutable for the process lifetime, so building it
|
|
321
|
+
// inside handleRequest would open a connection per visitor.
|
|
322
|
+
//
|
|
323
|
+
// Before init(), so hooks.server.ts can use what plugins opened — a
|
|
324
|
+
// database for a warm-up query or a migration check is the usual case,
|
|
325
|
+
// and running init first meant it could only fail.
|
|
326
|
+
const services = await collectServices(plugins);
|
|
327
|
+
|
|
314
328
|
// Run init hook if present
|
|
315
329
|
await hooksInit?.();
|
|
316
330
|
|
|
@@ -331,6 +345,12 @@ export async function createServer(config: GrimoireConfig = {}) {
|
|
|
331
345
|
const locals: App.Locals = rawLocals
|
|
332
346
|
? ((await runDeserializeLocals(plugins, rawLocals)) ?? {})
|
|
333
347
|
: {};
|
|
348
|
+
// Plugin services sit under the request's own locals: what the app
|
|
349
|
+
// set (a session, a user) always wins over what a plugin declared,
|
|
350
|
+
// so a plugin cannot clobber auth by defining a common key.
|
|
351
|
+
for (const [key, value] of Object.entries(services)) {
|
|
352
|
+
if (!(key in locals)) locals[key] = value;
|
|
353
|
+
}
|
|
334
354
|
const url = new URL(req.url);
|
|
335
355
|
|
|
336
356
|
if (dev && url.pathname === "/__grimoire__/hmr") {
|
package/src/server/plugins.ts
CHANGED
|
@@ -39,6 +39,41 @@ export async function runHook<K extends FireAndForgetHook>(
|
|
|
39
39
|
}
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
+
/**
|
|
43
|
+
* Collect `services()` from every plugin, merged in plugin order.
|
|
44
|
+
*
|
|
45
|
+
* Called once at startup and cached by the caller: the result is shared by
|
|
46
|
+
* every request. `services` is a fire-and-forget hook, so it is kept out of
|
|
47
|
+
* HookArgs on purpose — its return value is used, unlike every other entry
|
|
48
|
+
* in that map.
|
|
49
|
+
*
|
|
50
|
+
* Each plugin is handed what the plugins before it already published, so a
|
|
51
|
+
* plugin can build on a resource another one owns. The SQL plugin opening the
|
|
52
|
+
* connection and a jobs plugin writing rows through it is the case that
|
|
53
|
+
* matters: without this, every consumer opens a second pool and the worker
|
|
54
|
+
* budget is split again by whoever registered first.
|
|
55
|
+
*
|
|
56
|
+
* The context is a snapshot, so a plugin registered before the one it needs
|
|
57
|
+
* sees nothing and reports that. It does not see its own contribution, and
|
|
58
|
+
* it cannot write into the result — a plugin that wants to publish does so by
|
|
59
|
+
* returning, which is what keeps the merge order predictable.
|
|
60
|
+
*/
|
|
61
|
+
export async function collectServices(
|
|
62
|
+
plugins: GrimoirePlugin[],
|
|
63
|
+
): Promise<Record<string, unknown>> {
|
|
64
|
+
const collected: Record<string, unknown> = {};
|
|
65
|
+
for (const plugin of plugins) {
|
|
66
|
+
if (!plugin.services) continue;
|
|
67
|
+
const provided = await plugin.services({ services: { ...collected } });
|
|
68
|
+
if (!provided) continue;
|
|
69
|
+
for (const [key, value] of Object.entries(provided)) {
|
|
70
|
+
if (value === undefined) continue;
|
|
71
|
+
collected[key] = value;
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
return collected;
|
|
75
|
+
}
|
|
76
|
+
|
|
42
77
|
export async function runRequestHooks(
|
|
43
78
|
plugins: GrimoirePlugin[],
|
|
44
79
|
req: Request,
|
package/src/types.ts
CHANGED
|
@@ -82,18 +82,92 @@ export interface PluginContext {
|
|
|
82
82
|
logger: ScopedLogger;
|
|
83
83
|
}
|
|
84
84
|
|
|
85
|
+
/**
|
|
86
|
+
* Which worker this process is, and how many there are.
|
|
87
|
+
*
|
|
88
|
+
* A plugin that creates one resource per worker — a connection pool, an
|
|
89
|
+
* embedded database handle — needs both numbers to divide a global budget
|
|
90
|
+
* correctly. `maxConnections: 20` across 4 workers is 5 each; a plugin that
|
|
91
|
+
* only knows its own index has no way to work that out and quietly opens 80.
|
|
92
|
+
*
|
|
93
|
+
* The coordinator sets both as env vars at spawn, so this resolves in a
|
|
94
|
+
* worker process. Running without a coordinator (`sigil dev`, or a single
|
|
95
|
+
* process) is one worker of one, which is the honest answer rather than a
|
|
96
|
+
* guess.
|
|
97
|
+
*/
|
|
98
|
+
export interface WorkerContext {
|
|
99
|
+
/** 0-based within this mode. 0 when there is no coordinator. */
|
|
100
|
+
workerId: number;
|
|
101
|
+
/** Total workers across all modes. At least 1. */
|
|
102
|
+
workers: number;
|
|
103
|
+
/** Whether the server is in development mode. */
|
|
104
|
+
dev: boolean;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function workerContext(env: Record<string, string | undefined> = process.env): WorkerContext {
|
|
108
|
+
const parsed = Number(env.GRIMOIRE_WORKER_INDEX);
|
|
109
|
+
const count = Number(env.GRIMOIRE_WORKER_COUNT);
|
|
110
|
+
return {
|
|
111
|
+
// A NaN here means no coordinator set them, which is one worker.
|
|
112
|
+
workerId: Number.isFinite(parsed) && parsed > 0 ? parsed - 1 : 0,
|
|
113
|
+
// Never 0: a budget divided by zero is Infinity, and a pool of
|
|
114
|
+
// Infinity is a crash at the first connection.
|
|
115
|
+
workers: Number.isFinite(count) && count > 0 ? count : 1,
|
|
116
|
+
dev: env.GRIMOIRE_MODE === "development",
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
85
120
|
export interface BuildResult {
|
|
86
121
|
success: boolean;
|
|
87
122
|
outputs: string[];
|
|
88
123
|
errors: string[];
|
|
89
124
|
}
|
|
90
125
|
|
|
126
|
+
export interface ServicesContext {
|
|
127
|
+
/**
|
|
128
|
+
* What the plugins before this one published, keyed the same way it will
|
|
129
|
+
* appear on `locals`. A snapshot: mutating it changes nothing.
|
|
130
|
+
*/
|
|
131
|
+
services: Record<string, unknown>;
|
|
132
|
+
}
|
|
133
|
+
|
|
91
134
|
export interface GrimoirePlugin {
|
|
92
135
|
name: string;
|
|
93
136
|
|
|
94
137
|
// plugin lifecycle
|
|
95
138
|
onPluginsResolved?(ctx: PluginContext): void | Promise<void>;
|
|
96
139
|
|
|
140
|
+
/**
|
|
141
|
+
* Expose values on `locals` for the whole app to use.
|
|
142
|
+
*
|
|
143
|
+
* Returns an object merged into the per-request `locals` before any
|
|
144
|
+
* route, load, action or +server.ts handler runs, so a route reaches it
|
|
145
|
+
* as `locals.<key>` with nothing imported and nothing exported from
|
|
146
|
+
* sigil.config.ts.
|
|
147
|
+
*
|
|
148
|
+
* The merge is shallow and runs in plugin order, so a later plugin
|
|
149
|
+
* overriding an earlier plugin's key wins — same rule as every other
|
|
150
|
+
* merge in the pipeline. It is collected once, at startup, and the same
|
|
151
|
+
* values are merged into every request, so a request-scoped value here
|
|
152
|
+
* is a mistake.
|
|
153
|
+
*
|
|
154
|
+
* This is the place to open a connection pool. It runs only where
|
|
155
|
+
* requests are served — `sigil dev` and each `sigil start` worker, not
|
|
156
|
+
* the coordinator or `sigil build`, which do run `config()` — and before
|
|
157
|
+
* hooks.server.ts `init()`, so `init` can use what it opened.
|
|
158
|
+
*
|
|
159
|
+
* `ctx.services` is what the plugins before this one published, so a
|
|
160
|
+
* plugin can build on a resource another plugin owns instead of opening
|
|
161
|
+
* a second one. Register the SQL plugin first and a consumer reads
|
|
162
|
+
* `ctx.services.db` — the same client, not a parallel pool.
|
|
163
|
+
*
|
|
164
|
+
* It is a snapshot taken before this plugin runs, so a plugin registered
|
|
165
|
+
* before the one it needs sees nothing. Plugins that must not depend on
|
|
166
|
+
* ordering should fail loudly when the key is absent rather than quietly
|
|
167
|
+
* open their own fallback.
|
|
168
|
+
*/
|
|
169
|
+
services?(ctx: ServicesContext): Record<string, unknown> | Promise<Record<string, unknown>>;
|
|
170
|
+
|
|
97
171
|
// server lifecycle
|
|
98
172
|
// we dont care about what the impl puts as websocket data therefore unknown.
|
|
99
173
|
onStart?(server: Server<unknown>): void | Promise<void>;
|
package/test/coordinator.test.ts
CHANGED
|
@@ -22,6 +22,8 @@ describe("coordinator", () => {
|
|
|
22
22
|
' message(ws, data) { ws.send("echo:" + data); },',
|
|
23
23
|
"};",
|
|
24
24
|
"export function GET({ request }) {",
|
|
25
|
+
' if (new URL(request.url).searchParams.has("nav"))',
|
|
26
|
+
' return new Response(request.headers.get("x-grimoire-navigate") ?? "none");',
|
|
25
27
|
' return new Response(request.headers.get("cookie") ?? "no cookie");',
|
|
26
28
|
"}",
|
|
27
29
|
].join("\n"),
|
|
@@ -55,6 +57,13 @@ describe("coordinator", () => {
|
|
|
55
57
|
expect(res.status).toBe(200);
|
|
56
58
|
});
|
|
57
59
|
|
|
60
|
+
test("client-side navigation reaches the worker with its header", async () => {
|
|
61
|
+
const res = await fetch(`http://127.0.0.1:${port}/echo?nav`, {
|
|
62
|
+
headers: { "x-grimoire-navigate": "1" },
|
|
63
|
+
});
|
|
64
|
+
expect(await res.text()).toBe("1");
|
|
65
|
+
});
|
|
66
|
+
|
|
58
67
|
test("relays WebSockets, including a message sent right on open", async () => {
|
|
59
68
|
const ws = new WebSocket(`ws://127.0.0.1:${port}/echo`);
|
|
60
69
|
const got: string[] = [];
|