@barqjs/start 0.0.0-stage → 0.2.0-next.0

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.
Files changed (68) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +791 -2
  3. package/dist/client-BHyIiYxt.js +1527 -0
  4. package/dist/client-BHyIiYxt.js.map +1 -0
  5. package/dist/client-DHCV7yvQ.d.ts +440 -0
  6. package/dist/client-DHCV7yvQ.d.ts.map +1 -0
  7. package/dist/client.d.ts +3 -0
  8. package/dist/client.js +4 -0
  9. package/dist/env-qA8EyOr1.d.ts +49 -0
  10. package/dist/env-qA8EyOr1.d.ts.map +1 -0
  11. package/dist/env.d.ts +2 -0
  12. package/dist/env.js +44 -0
  13. package/dist/env.js.map +1 -0
  14. package/dist/index-Bm_-MTj6.d.ts +915 -0
  15. package/dist/index-Bm_-MTj6.d.ts.map +1 -0
  16. package/dist/index.d.ts +5 -0
  17. package/dist/index.js +6 -0
  18. package/dist/middleware-BdVlE8qm.d.ts +576 -0
  19. package/dist/middleware-BdVlE8qm.d.ts.map +1 -0
  20. package/dist/middleware.d.ts +2 -0
  21. package/dist/middleware.js +282 -0
  22. package/dist/middleware.js.map +1 -0
  23. package/dist/prerender.d.ts +98 -0
  24. package/dist/prerender.d.ts.map +1 -0
  25. package/dist/prerender.js +289 -0
  26. package/dist/prerender.js.map +1 -0
  27. package/dist/protocol.d.ts +58 -0
  28. package/dist/protocol.d.ts.map +1 -0
  29. package/dist/protocol.js +26 -0
  30. package/dist/protocol.js.map +1 -0
  31. package/dist/serve.d.ts +135 -0
  32. package/dist/serve.d.ts.map +1 -0
  33. package/dist/serve.js +223 -0
  34. package/dist/serve.js.map +1 -0
  35. package/dist/server-BV3xKmLa.js +1148 -0
  36. package/dist/server-BV3xKmLa.js.map +1 -0
  37. package/dist/server.d.ts +142 -0
  38. package/dist/server.d.ts.map +1 -0
  39. package/dist/server.js +1 -0
  40. package/dist/src-ChnB_xug.js +1140 -0
  41. package/dist/src-ChnB_xug.js.map +1 -0
  42. package/dist/static-fn-DgjNArBe.js +123 -0
  43. package/dist/static-fn-DgjNArBe.js.map +1 -0
  44. package/package.json +106 -4
  45. package/src/client.ts +672 -0
  46. package/src/context.ts +666 -0
  47. package/src/cookies.ts +229 -0
  48. package/src/env.ts +86 -0
  49. package/src/fn-error.ts +97 -0
  50. package/src/frames-client.ts +1216 -0
  51. package/src/frames-server.ts +464 -0
  52. package/src/frames.ts +285 -0
  53. package/src/index.ts +714 -0
  54. package/src/live-client.ts +50 -0
  55. package/src/live-server.ts +182 -0
  56. package/src/middleware.ts +994 -0
  57. package/src/prerender.ts +477 -0
  58. package/src/protocol.ts +61 -0
  59. package/src/rate-limit.ts +202 -0
  60. package/src/serve.ts +153 -0
  61. package/src/server.ts +990 -0
  62. package/src/session.ts +449 -0
  63. package/src/start-instance.ts +147 -0
  64. package/src/static-fn.ts +181 -0
  65. package/src/static.ts +302 -0
  66. package/src/stubs.ts +32 -0
  67. package/src/timing.ts +29 -0
  68. package/src/wire-types.ts +139 -0
@@ -0,0 +1,477 @@
1
+ /**
2
+ * Static HTML, written by the SAME handler that serves a live request.
3
+ *
4
+ * The decision this file rests on, and the field is nearly unanimous on the
5
+ * other side of it: a prerendered page is `createPageHandler` with
6
+ * `stream: false`, NOT a streamed response buffered to a string.
7
+ *
8
+ * SvelteKit and Nitro — and so Solid Start, Nuxt and TanStack Start — prerender
9
+ * by calling the real handler and doing `Buffer.from(await res.arrayBuffer())`
10
+ * with streaming still on. Buffering does not undo streaming: the protocol is
11
+ * emitted at FLUSH time, so by the time you hold the bytes the placeholders and
12
+ * the swap scripts are already in them. A SvelteKit prerendered file, reproduced
13
+ * on 2.70.3, ships `<p>loading...</p>` as its static markup with
14
+ * `<script>…resolve(1, () => ["LATE_STREAMED_VALUE"])</script>` after `</html>`,
15
+ * for data that was fully known at build time.
16
+ *
17
+ * Astro is the exception and its fix is ten lines: a build-time subclass whose
18
+ * `resolveStreaming()` returns undefined. barq gets that for free, because
19
+ * `stream: false` is a different RENDERER — `renderPage` awaits `settle`, walks
20
+ * the seed with `settleNested`, and emits one `__BARQ_DATA__` script with no
21
+ * channel, no swap helper and no `<template>` anywhere.
22
+ */
23
+
24
+ import { mkdir, writeFile } from "node:fs/promises";
25
+ import { dirname, isAbsolute, join, relative, sep } from "node:path";
26
+
27
+ import { PRERENDER_HEADER, type ServerEntryModule } from "./protocol.ts";
28
+ import { STATIC_PREFIX, installStaticWriter } from "./static-fn.ts";
29
+
30
+ export type { ServerEntryModule };
31
+
32
+ export interface PrerenderRun {
33
+ readonly entry: ServerEntryModule;
34
+ readonly outDir: string;
35
+ readonly routes: readonly string[];
36
+ readonly crawl: boolean;
37
+ readonly concurrency: number;
38
+ readonly subfolderIndex: boolean;
39
+ readonly base: string;
40
+ /** Whether a path is prerendered at all. Asked with the normalised path. */
41
+ readonly filter?: (path: string) => boolean;
42
+ /**
43
+ * How many more times a page is asked for after its request throws or answers
44
+ * 5xx. Default 0.
45
+ *
46
+ * A 4xx is an answer, not a failure to answer: asking again gets it again.
47
+ */
48
+ readonly retryCount?: number;
49
+ /** Milliseconds to wait before each retry. Default 0. */
50
+ readonly retryDelay?: number;
51
+ /**
52
+ * Write a sitemap of what was prerendered.
53
+ *
54
+ * `host` is the origin the site is deployed at, which the build cannot know.
55
+ * `outputPath` is relative to `outDir` and defaults to `sitemap.xml`.
56
+ */
57
+ readonly sitemap?: PrerenderSitemap;
58
+ readonly log?: (message: string) => void;
59
+ }
60
+
61
+ export interface PrerenderSitemap {
62
+ readonly host: string;
63
+ readonly outputPath?: string;
64
+ }
65
+
66
+ export interface PrerenderResult {
67
+ readonly pages: PrerenderedPage[];
68
+ /** The sitemap's file, when one was asked for and a page belongs in it. */
69
+ readonly sitemap?: string;
70
+ /**
71
+ * The copy of the `/404` page at `<outDir>/404.html`, the name a static host
72
+ * serves for a path it has no file for.
73
+ *
74
+ * Absent when the page's own file is that one already. It has no entry in
75
+ * `pages`: it is a second name for a page that is listed there.
76
+ */
77
+ readonly notFoundFile?: string;
78
+ /** The files `staticFunctionMiddleware` answers were written to. */
79
+ readonly staticAnswers: readonly string[];
80
+ }
81
+
82
+ /** One prerendered page, as the build records it. */
83
+ export interface PrerenderedPage {
84
+ readonly path: string;
85
+ readonly file: string;
86
+ readonly status: number;
87
+ /**
88
+ * The response's own headers.
89
+ *
90
+ * Kept because a static host cannot recover them from a file, and every
91
+ * framework that drops them has an open issue about it — SvelteKit rescues
92
+ * `cache-control` alone into a `<meta http-equiv>` and leaves the rest
93
+ * unhandled, Nitro loses `content-type` on a generated feed.
94
+ *
95
+ * `writeAssetManifest` in `vite.ts` is what finally persists them, and
96
+ * `static.ts` is what serves a page with the status it was rendered as.
97
+ */
98
+ readonly headers: Record<string, string>;
99
+ }
100
+
101
+ function isHtml(response: Response): boolean {
102
+ return (response.headers.get("content-type") ?? "").includes("text/html");
103
+ }
104
+
105
+ /** The origin every prerender request is made against. It never leaves the build. */
106
+ const ORIGIN = "http://prerender.localhost";
107
+
108
+ /**
109
+ * A path, as the dedup key sees it.
110
+ *
111
+ * Trailing slashes are normalised and the query is DROPPED, both because of
112
+ * open bugs in the nearest prior art. TanStack's crawler appends a trailing
113
+ * slash without `respectQueryAndFragment`, so `/posts?page=2` becomes
114
+ * `/posts?page=2/`, re-serialises as `page=2%2F`, and every crawl step produces
115
+ * a URL nothing has seen, and the crawl never terminates. `/x` against `/x/` as
116
+ * two keys is a second open bug there. A query string has no effect on a statically
117
+ * exported page anyway, which is the note SvelteKit's crawler carries.
118
+ *
119
+ * THROUGH `new URL`, because the key is also what gets requested and what names
120
+ * the file. An `href` is whatever an author typed, and `/../../about` typed into
121
+ * a page is `/about` to every browser that follows it: resolved here, it is one
122
+ * key and one file, where the raw text is a second key and a path that climbs
123
+ * out of the output directory.
124
+ */
125
+ function normalize(path: string): string | null {
126
+ if (path.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(path)) return null;
127
+ const [withoutHash = ""] = path.split("#");
128
+ const [clean = ""] = withoutHash.split("?");
129
+ if (clean === "") return null;
130
+ let resolved: string;
131
+ try {
132
+ const url = new URL(clean, ORIGIN);
133
+ if (url.origin !== ORIGIN) return null;
134
+ resolved = url.pathname;
135
+ // Asked now so that a path which names no file is never queued.
136
+ decodeURI(resolved);
137
+ } catch {
138
+ return null;
139
+ }
140
+ const trimmed = resolved.length > 1 ? resolved.replace(/\/+$/, "") : resolved;
141
+ return trimmed === "" ? "/" : trimmed;
142
+ }
143
+
144
+ /** Same-origin `href`s and `src`s, which is what a crawl follows. */
145
+ function linksIn(html: string): string[] {
146
+ const out: string[] = [];
147
+ for (const match of html.matchAll(/<a\b[^>]*?\shref=["']([^"']+)["']/gi)) {
148
+ const href = match[1];
149
+ if (href !== undefined) out.push(href);
150
+ }
151
+ return out;
152
+ }
153
+
154
+ /**
155
+ * `/about` -> `dist/client/about/index.html`, or `about.html`.
156
+ *
157
+ * CONTAINMENT IS ASSERTED rather than assumed. {@link normalize} resolves dot
158
+ * segments, but the name on disk is the DECODED path, and decoding can produce
159
+ * a separator the URL never had: `..%5C` is one ordinary segment to a URL and a
160
+ * step upward to a Windows path.
161
+ */
162
+ function fileFor(path: string, outDir: string, subfolderIndex: boolean): string {
163
+ const clean = path.replace(/^\/+/, "");
164
+ let file: string;
165
+ if (clean === "") file = join(outDir, "index.html");
166
+ else if (clean.endsWith(".html")) file = join(outDir, clean);
167
+ else file = subfolderIndex ? join(outDir, clean, "index.html") : join(outDir, `${clean}.html`);
168
+ return contained(path, file, outDir);
169
+ }
170
+
171
+ function contained(what: string, file: string, outDir: string): string {
172
+ const inside = relative(outDir, file);
173
+ if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside)) {
174
+ throw new Error(
175
+ `The file for ${what} would be written outside the output directory, to \`${file}\`, so it was refused. ` +
176
+ "Use a path or an `outputPath` that stays inside the output directory, without `..` segments.",
177
+ );
178
+ }
179
+ return file;
180
+ }
181
+
182
+ /** The path every static host looks a missing page up under. */
183
+ const NOT_FOUND_PATH = "/404";
184
+
185
+ /** A count or a delay as given, or 0 for anything that is not a positive number. */
186
+ function whole(value: number | undefined): number {
187
+ return value !== undefined && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
188
+ }
189
+
190
+ function escapeXml(text: string): string {
191
+ return text
192
+ .replaceAll("&", "&amp;")
193
+ .replaceAll("<", "&lt;")
194
+ .replaceAll(">", "&gt;")
195
+ .replaceAll('"', "&quot;")
196
+ .replaceAll("'", "&apos;");
197
+ }
198
+
199
+ /**
200
+ * `<loc>` alone. A `<lastmod>` stamped with the build date, which is what the
201
+ * nearest prior art writes, tells a crawler every page changed on every deploy.
202
+ */
203
+ function sitemapXml(locations: readonly string[]): string {
204
+ const urls = locations.map((loc) => ` <url>\n <loc>${escapeXml(loc)}</loc>\n </url>\n`);
205
+ return (
206
+ '<?xml version="1.0" encoding="UTF-8"?>\n' +
207
+ '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
208
+ urls.join("") +
209
+ "</urlset>\n"
210
+ );
211
+ }
212
+
213
+ /**
214
+ * Render every reachable path and write it.
215
+ *
216
+ * Failures are COLLECTED and rethrown after the queue drains, never swallowed.
217
+ * TanStack's equivalent adds to its queue without awaiting and resolves on
218
+ * `onSettled` regardless of outcome, so their `failOnError` cannot fail a build
219
+ * and their `retryCount` is dead code. A build that emits a broken page
220
+ * and exits 0 is the failure a prerenderer exists to prevent.
221
+ */
222
+ export async function prerender(run: PrerenderRun): Promise<PrerenderResult> {
223
+ const build = run.entry.default?.createFetch;
224
+ if (typeof build !== "function") {
225
+ throw new Error(
226
+ "[barq-start] The `prerender` option is set, but the server entry's default export has no `createFetch`, so no page can be rendered to a static file. " +
227
+ "Use `export default createStartHandler()` from `@barqjs/router/server` in the server entry.",
228
+ );
229
+ }
230
+
231
+ const fetchPage = build({
232
+ stream: false,
233
+ // A prerendered page has no request. Refusing beats SvelteKit's shape, where
234
+ // `cookies.get` and `request.headers` silently answer null and the page is
235
+ // built from a build machine's idea of who is asking.
236
+ refuseRequest:
237
+ "getRequest() is not available while prerendering: this page is built once, for everyone. " +
238
+ "Move what needs a request behind a route that is not prerendered.",
239
+ // A nonce baked into a static file is a constant an attacker reads, which is
240
+ // the opposite of what a nonce is. SvelteKit bans `csp.mode: "nonce"` under
241
+ // prerender outright and React ships the same note on its static entry.
242
+ nonce: undefined,
243
+ });
244
+
245
+ // Asked before anything is rendered: a path that cannot be written is known
246
+ // from the configuration alone, and the whole site is a long wait to find out.
247
+ const sitemap =
248
+ run.sitemap === undefined
249
+ ? undefined
250
+ : {
251
+ host: run.sitemap.host.replace(/\/+$/, ""),
252
+ file: contained(
253
+ "the sitemap",
254
+ join(run.outDir, run.sitemap.outputPath ?? "sitemap.xml"),
255
+ run.outDir,
256
+ ),
257
+ };
258
+ const retries = whole(run.retryCount);
259
+ const retryDelay = whole(run.retryDelay);
260
+
261
+ const seen = new Set<string>();
262
+ const queue: string[] = [];
263
+ const pages: PrerenderedPage[] = [];
264
+ const failures: string[] = [];
265
+ // The URL paths, where `pages` holds the decoded names: a `<loc>` is a URL.
266
+ const listed: string[] = [];
267
+ let notFoundFile: string | undefined;
268
+
269
+ const enqueue = (path: string): void => {
270
+ const key = normalize(path);
271
+ if (key === null || seen.has(key)) return;
272
+ seen.add(key);
273
+ // After `seen`, so a path linked from every page is asked about once.
274
+ if (run.filter?.(key) === false) return;
275
+ queue.push(key);
276
+ };
277
+
278
+ const named = new Set<string>();
279
+ for (const route of run.routes.length > 0 ? run.routes : ["/"]) {
280
+ const key = normalize(route);
281
+ if (key !== null) named.add(key);
282
+ enqueue(route);
283
+ }
284
+
285
+ const ask = async (path: string): Promise<{ response: Response; html: string }> => {
286
+ for (let attempt = 0; ; attempt += 1) {
287
+ const last = attempt >= retries;
288
+ try {
289
+ const response = await fetchPage(new Request(`${ORIGIN}${path}`));
290
+ const html = await response.text();
291
+ if (response.status < 500 || last) return { response, html };
292
+ run.log?.(`${path} answered ${response.status}, asking again`);
293
+ } catch (reason) {
294
+ if (last) throw reason;
295
+ run.log?.(`${path} threw, asking again`);
296
+ }
297
+ if (retryDelay > 0) await new Promise((resolve) => setTimeout(resolve, retryDelay));
298
+ }
299
+ };
300
+
301
+ const one = async (path: string): Promise<void> => {
302
+ const { response, html } = await ask(path);
303
+ const crawledOnly = !named.has(path);
304
+ // A page the build NAMED and the application answers 404 for is the
305
+ // application's not-found page, asked for on purpose: it is written, with
306
+ // the status it was rendered as, for `static.ts` to serve. Anything else at
307
+ // 400 or above is a link to nowhere or a server that failed.
308
+ const notFoundPage = response.status === 404 && !crawledOnly && isHtml(response);
309
+ if (response.status >= 400 && !notFoundPage) {
310
+ failures.push(`${path} answered ${response.status}`);
311
+ return;
312
+ }
313
+ const declined = response.headers.get(PRERENDER_HEADER) === "0";
314
+ if (crawledOnly && declined) {
315
+ // Rendered to find its links, not to be written. A route that has not said
316
+ // `prerender` is a route the build has no business freezing.
317
+ if (run.crawl) followLinks(html);
318
+ return;
319
+ }
320
+ // The NAME, where `path` is the URL: `/caf%C3%A9` is `café/index.html` on
321
+ // disk and `/café` in the manifest, which is how `static.ts` looks it up.
322
+ const name = decodeURI(path);
323
+ const file = fileFor(name, run.outDir, run.subfolderIndex);
324
+ await mkdir(dirname(file), { recursive: true });
325
+ // Written as each page finishes rather than accumulated: holding ~300
326
+ // data-heavy pages to the end is a 2 GB heap, which SvelteKit shipped.
327
+ await writeFile(file, html, "utf8");
328
+ pages.push({
329
+ path: name,
330
+ file,
331
+ status: response.status,
332
+ headers: Object.fromEntries(response.headers),
333
+ });
334
+ run.log?.(`${path} -> ${file}`);
335
+ if (path === NOT_FOUND_PATH) {
336
+ const root = join(run.outDir, "404.html");
337
+ if (root !== file) {
338
+ await writeFile(root, html, "utf8");
339
+ notFoundFile = root;
340
+ }
341
+ } else if (response.ok) {
342
+ listed.push(path);
343
+ }
344
+ if (run.crawl && !notFoundPage) followLinks(html);
345
+ };
346
+
347
+ const followLinks = (html: string): void => {
348
+ for (const href of linksIn(html)) {
349
+ if (!href.startsWith("/")) continue;
350
+ const inside = run.base === "/" || href.startsWith(run.base);
351
+ if (inside) enqueue(run.base === "/" ? href : href.slice(run.base.length - 1));
352
+ }
353
+ };
354
+
355
+ // A POOL, not batches: a slot is refilled the moment its page finishes, so
356
+ // one slow page costs its own time rather than its whole batch's. The queue
357
+ // grows while it drains, since a crawled page adds what it links to.
358
+ const slots = Math.max(1, run.concurrency);
359
+ let next = 0;
360
+ let active = 0;
361
+ // A static server function's answer is written beside the pages that asked
362
+ // for it, under the name its client half will look for. One name holding two
363
+ // different calls would hand the second caller the first one's answer, so
364
+ // that stops the build rather than being written.
365
+ const answered = new Map<string, string>();
366
+ const staticAnswers: string[] = [];
367
+ installStaticWriter(async (key, identity, answer) => {
368
+ const before = answered.get(key);
369
+ if (before !== undefined && before !== identity) {
370
+ throw new Error(
371
+ `[barq-start] Two static server function calls share the cache name ${key}, so one would be answered with the other's result. ` +
372
+ "Pass a different input to one of them, or drop `staticFunctionMiddleware` from it.",
373
+ );
374
+ }
375
+ const file = contained(
376
+ "a static server function's answer",
377
+ join(run.outDir, STATIC_PREFIX.slice(1), `${key}.json`),
378
+ run.outDir,
379
+ );
380
+ if (before === undefined) {
381
+ answered.set(key, identity);
382
+ staticAnswers.push(file);
383
+ }
384
+ await mkdir(dirname(file), { recursive: true });
385
+ await writeFile(file, answer, "utf8");
386
+ });
387
+ await new Promise<void>((drained) => {
388
+ const fill = (): void => {
389
+ while (active < slots) {
390
+ const path = queue[next];
391
+ if (path === undefined) break;
392
+ next += 1;
393
+ active += 1;
394
+ one(path)
395
+ .catch((reason: unknown) => {
396
+ const message = (reason as { message?: string } | null)?.message ?? String(reason);
397
+ failures.push(`${path}: ${message}`);
398
+ })
399
+ .finally(() => {
400
+ active -= 1;
401
+ fill();
402
+ });
403
+ }
404
+ if (active === 0) drained();
405
+ };
406
+ fill();
407
+ }).finally(() => installStaticWriter(null));
408
+
409
+ if (failures.length > 0) {
410
+ throw new Error(
411
+ `[barq-start] ${failures.length} page(s) failed to prerender, so the build stopped before shipping a broken page:\n ` +
412
+ failures.join("\n "),
413
+ );
414
+ }
415
+
416
+ if (sitemap === undefined || listed.length === 0) return { pages, notFoundFile, staticAnswers };
417
+ const base = run.base.replace(/\/+$/, "");
418
+ await mkdir(dirname(sitemap.file), { recursive: true });
419
+ await writeFile(
420
+ sitemap.file,
421
+ sitemapXml(listed.toSorted().map((path) => `${sitemap.host}${base}${path}`)),
422
+ "utf8",
423
+ );
424
+ return { pages, sitemap: sitemap.file, notFoundFile, staticAnswers };
425
+ }
426
+
427
+ /** What {@link prerenderShell} is asked for. */
428
+ export interface ShellRun {
429
+ readonly entry: ServerEntryModule;
430
+ readonly outDir: string;
431
+ /** The path the shell is rendered at. `/` when omitted. */
432
+ readonly maskPath?: string;
433
+ /** Where it is written, relative to `outDir`. `_shell.html` when omitted. */
434
+ readonly outputPath?: string;
435
+ }
436
+
437
+ /**
438
+ * Write the SPA shell: the root route's document, with nothing under it
439
+ * rendered, for a server or a static host to answer every page path with.
440
+ *
441
+ * TanStack's SPA mode. The file is one request to the same handler, built with
442
+ * `shell: true`, so the shell is the application's own root route rather than a
443
+ * second document to keep in step with it.
444
+ */
445
+ export async function prerenderShell(run: ShellRun): Promise<string> {
446
+ const build = run.entry.default?.createFetch;
447
+ if (typeof build !== "function") {
448
+ throw new Error(
449
+ "[barq-start] SPA mode is on, but the server entry's default export has no `createFetch`, so the shell document cannot be rendered. " +
450
+ "Use `export default createStartHandler()` from `@barqjs/router/server` in the server entry.",
451
+ );
452
+ }
453
+ const file = contained(
454
+ "the SPA shell",
455
+ join(run.outDir, (run.outputPath ?? "_shell.html").replace(/^\/+/, "")),
456
+ run.outDir,
457
+ );
458
+ const fetchShell = build({
459
+ stream: false,
460
+ pages: true,
461
+ shell: true,
462
+ refuseRequest:
463
+ "[barq] `getRequest()` and the other request helpers are not available while the SPA shell is rendered: the shell is built once and served for every path, so there is no request to read. " +
464
+ "Read the request in a loader or a server function instead.",
465
+ nonce: undefined,
466
+ });
467
+ const response = await fetchShell(new Request(`${ORIGIN}${run.maskPath ?? "/"}`));
468
+ if (response.status >= 400 || !isHtml(response)) {
469
+ throw new Error(
470
+ `[barq-start] Rendering the SPA shell at \`${run.maskPath ?? "/"}\` answered ${response.status}${isHtml(response) ? "" : " without an HTML body"}, so no shell was written. ` +
471
+ "The root route's `shellComponent` has to render for that path: check the server output above for the error it threw.",
472
+ );
473
+ }
474
+ await mkdir(dirname(file), { recursive: true });
475
+ await writeFile(file, await response.text(), "utf8");
476
+ return file;
477
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * The server-entry contract: what a built `dist/server` module exports, and the
3
+ * one header the prerenderer and the page handler agree on.
4
+ *
5
+ * It is its own module because three parties need it and none of them may
6
+ * depend on the other two. `prerender.ts` reads the header and calls the entry;
7
+ * `@barqjs/router/server` writes the header; `vite.ts` generates an entry that
8
+ * has to match. Nothing here imports anything — no `node:fs`, no
9
+ * `node:async_hooks` — so the router, which runs on workerd as readily as on
10
+ * Node, can import it without dragging a runtime in.
11
+ *
12
+ * Before this existed the header was a string literal in two files.
13
+ */
14
+
15
+ /**
16
+ * The header a page handler answers with when it was built for a prerender.
17
+ *
18
+ * `"0"` means the matched route did not declare `prerender`, so a path the
19
+ * CRAWL found is rendered and discarded rather than written. A path the config
20
+ * named is always written — naming it is the declaration.
21
+ */
22
+ export const PRERENDER_HEADER = "x-barq-prerender";
23
+
24
+ /**
25
+ * What the built server entry has to export.
26
+ *
27
+ * ALL THREE HANG OFF `default`, because a default export is the only thing a
28
+ * one-line entry can provide and `export default createStartHandler()` is the
29
+ * whole file. They were named module exports, which is exactly why a
30
+ * hand-written entry had to be a transcription of the generated one: the build
31
+ * needs all three, and only the build does.
32
+ *
33
+ * `createFetch` beside `fetch` is the reason one declaration serves three
34
+ * callers: `stream` is fixed when the handler is built, so a prerenderer handed
35
+ * only `fetch` has nothing to build a non-streaming twin from — and a streamed
36
+ * response buffered to a string is not a static page, it is a static page with
37
+ * its placeholders and swap scripts baked in.
38
+ *
39
+ * `verifyChains` is the route-action chain check. It runs from inside the ssr
40
+ * bundle rather than from a Vite plugin because that is the only place that can
41
+ * see both halves: `resolve.noExternal` compiles `@barqjs/*` into that bundle,
42
+ * so the registry a plugin would import is a different, empty one, and the route
43
+ * definitions' `middleware` are closures that exist nowhere else. Living in
44
+ * APPLICATION source was never part of that — `@barqjs/router/server` is
45
+ * compiled into the same bundle, which is where it is now.
46
+ *
47
+ * Every member is optional so a project may default-export a bare `{ fetch }`
48
+ * and get a server with no prerender and no chain check, which is a legitimate
49
+ * thing to deploy.
50
+ */
51
+ export interface ServerEntryModule {
52
+ readonly default?: {
53
+ readonly fetch?: (request: Request) => Promise<Response>;
54
+ readonly createFetch?: (
55
+ extra: Record<string, unknown>,
56
+ ) => (request: Request) => Promise<Response>;
57
+ readonly verifyChains?: (
58
+ reachability: ReadonlyMap<string, ReadonlySet<string>>,
59
+ ) => string | Promise<string>;
60
+ };
61
+ }