@barqjs/start 0.0.0-stage → 0.2.0-next.1
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/LICENSE +21 -0
- package/README.md +817 -2
- package/dist/client-BsyxVCyu.js +1554 -0
- package/dist/client-BsyxVCyu.js.map +1 -0
- package/dist/client-DidH0F2e.d.ts +450 -0
- package/dist/client-DidH0F2e.d.ts.map +1 -0
- package/dist/client.d.ts +25 -0
- package/dist/client.js +4 -0
- package/dist/env-Bhk_aIkx.d.ts +47 -0
- package/dist/env-Bhk_aIkx.d.ts.map +1 -0
- package/dist/env.d.ts +2 -0
- package/dist/env.js +43 -0
- package/dist/env.js.map +1 -0
- package/dist/index-B4o7eyCr.d.ts +925 -0
- package/dist/index-B4o7eyCr.d.ts.map +1 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +6 -0
- package/dist/middleware-B-tI8QHQ.d.ts +574 -0
- package/dist/middleware-B-tI8QHQ.d.ts.map +1 -0
- package/dist/middleware.d.ts +2 -0
- package/dist/middleware.js +281 -0
- package/dist/middleware.js.map +1 -0
- package/dist/prerender.d.ts +118 -0
- package/dist/prerender.d.ts.map +1 -0
- package/dist/prerender.js +289 -0
- package/dist/prerender.js.map +1 -0
- package/dist/protocol.d.ts +56 -0
- package/dist/protocol.d.ts.map +1 -0
- package/dist/protocol.js +25 -0
- package/dist/protocol.js.map +1 -0
- package/dist/serve.d.ts +144 -0
- package/dist/serve.d.ts.map +1 -0
- package/dist/serve.js +221 -0
- package/dist/serve.js.map +1 -0
- package/dist/server-DG6jb_NA.js +1253 -0
- package/dist/server-DG6jb_NA.js.map +1 -0
- package/dist/server.d.ts +159 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +1 -0
- package/dist/src-odXG7kLA.js +1151 -0
- package/dist/src-odXG7kLA.js.map +1 -0
- package/dist/static-fn-CXjJi-It.js +122 -0
- package/dist/static-fn-CXjJi-It.js.map +1 -0
- package/package.json +106 -4
- package/src/client.ts +698 -0
- package/src/context.ts +699 -0
- package/src/cookies.ts +229 -0
- package/src/env.ts +86 -0
- package/src/fn-error.ts +121 -0
- package/src/frames-client.ts +1220 -0
- package/src/frames-server.ts +464 -0
- package/src/frames.ts +285 -0
- package/src/index.ts +740 -0
- package/src/live-client.ts +50 -0
- package/src/live-server.ts +292 -0
- package/src/middleware.ts +994 -0
- package/src/prerender.ts +477 -0
- package/src/protocol.ts +61 -0
- package/src/rate-limit.ts +202 -0
- package/src/serve.ts +153 -0
- package/src/server.ts +1026 -0
- package/src/session.ts +449 -0
- package/src/start-instance.ts +147 -0
- package/src/static-fn.ts +181 -0
- package/src/static.ts +302 -0
- package/src/stubs.ts +32 -0
- package/src/timing.ts +29 -0
- package/src/wire-types.ts +138 -0
package/src/prerender.ts
ADDED
|
@@ -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("&", "&")
|
|
193
|
+
.replaceAll("<", "<")
|
|
194
|
+
.replaceAll(">", ">")
|
|
195
|
+
.replaceAll('"', """)
|
|
196
|
+
.replaceAll("'", "'");
|
|
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
|
+
}
|
package/src/protocol.ts
ADDED
|
@@ -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
|
+
}
|