@drupflare/spool 0.4.0 → 1.0.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.
- package/README.md +206 -1756
- package/dist/angular/index.d.ts +13 -0
- package/dist/angular/index.js +25 -0
- package/dist/angular/pages.d.ts +28 -0
- package/dist/angular/pages.js +85 -0
- package/dist/cdn/client.js +1 -1
- package/dist/cdn/location.d.ts +6 -0
- package/dist/cdn/location.js +8 -0
- package/dist/cdn/manifest.json +7 -7
- package/dist/cdn/spool-sw.js +1 -1
- package/dist/client/bootstrap.d.ts +57 -0
- package/dist/client/bootstrap.js +307 -0
- package/dist/client/contact.d.ts +24 -0
- package/dist/client/contact.js +66 -0
- package/dist/client/declared.d.ts +23 -0
- package/dist/client/declared.js +68 -0
- package/dist/client/entry.js +91 -2
- package/dist/client/gate.d.ts +1 -0
- package/dist/client/gate.js +148 -0
- package/dist/client/index.d.ts +25 -0
- package/dist/client/index.js +1 -0
- package/dist/client/live.d.ts +66 -0
- package/dist/client/live.js +225 -0
- package/dist/client/navigate-entry.d.ts +1 -0
- package/dist/client/navigate-entry.js +4 -0
- package/dist/client/navigate.d.ts +54 -0
- package/dist/client/navigate.js +272 -0
- package/dist/client/persist.d.ts +2 -0
- package/dist/client/persist.js +9 -0
- package/dist/client/register.d.ts +11 -1
- package/dist/client/register.js +19 -8
- package/dist/express/index.d.ts +11 -0
- package/dist/express/index.js +209 -0
- package/dist/hono/index.d.ts +19 -0
- package/dist/hono/index.js +49 -0
- package/dist/next/index.d.ts +33 -0
- package/dist/next/index.js +41 -0
- package/dist/next/pages.d.ts +22 -0
- package/dist/next/pages.js +39 -0
- package/dist/node/listener.d.ts +3 -0
- package/dist/node/listener.js +57 -2
- package/dist/nuxt/index.d.ts +22 -0
- package/dist/nuxt/index.js +104 -0
- package/dist/nuxt/pages.d.ts +26 -0
- package/dist/nuxt/pages.js +48 -0
- package/dist/nuxt/runtime/index.d.ts +24 -0
- package/dist/nuxt/runtime/index.js +58 -0
- package/dist/plugins/coverage.d.ts +14 -0
- package/dist/plugins/coverage.js +27 -0
- package/dist/plugins/mode.d.ts +19 -0
- package/dist/plugins/mode.js +20 -0
- package/dist/plugins/path.d.ts +16 -0
- package/dist/plugins/path.js +139 -0
- package/dist/plugins/report.d.ts +22 -0
- package/dist/plugins/report.js +18 -0
- package/dist/plugins/routes.d.ts +38 -0
- package/dist/plugins/routes.js +52 -0
- package/dist/plugins/static.d.ts +42 -0
- package/dist/plugins/static.js +97 -0
- package/dist/protocol/bundle.d.ts +111 -0
- package/dist/protocol/bundle.js +428 -0
- package/dist/protocol/config.d.ts +65 -1
- package/dist/protocol/config.js +28 -0
- package/dist/protocol/dataset.d.ts +6 -0
- package/dist/protocol/dataset.js +6 -0
- package/dist/protocol/envelope.d.ts +33 -1
- package/dist/protocol/envelope.js +15 -1
- package/dist/protocol/errors.d.ts +1 -1
- package/dist/protocol/index-rows.d.ts +22 -0
- package/dist/protocol/index-rows.js +53 -0
- package/dist/protocol/index.d.ts +2 -0
- package/dist/protocol/index.js +2 -0
- package/dist/protocol/normalise.d.ts +4 -4
- package/dist/protocol/normalise.js +9 -5
- package/dist/protocol/ring.d.ts +58 -0
- package/dist/protocol/ring.js +6 -0
- package/dist/protocol/route.d.ts +57 -11
- package/dist/protocol/route.js +95 -3
- package/dist/protocol/tag.d.ts +22 -2
- package/dist/protocol/tag.js +25 -4
- package/dist/protocol/view.d.ts +2 -0
- package/dist/protocol/view.js +8 -2
- package/dist/protocol/views.d.ts +6 -0
- package/dist/protocol/views.js +15 -0
- package/dist/protocol/write.d.ts +92 -4
- package/dist/protocol/write.js +251 -9
- package/dist/proxy/eligible.d.ts +22 -1
- package/dist/proxy/eligible.js +62 -15
- package/dist/proxy/proxy.js +28 -18
- package/dist/react-router/index.d.ts +20 -0
- package/dist/react-router/index.js +60 -0
- package/dist/react-router/pages.d.ts +34 -0
- package/dist/react-router/pages.js +83 -0
- package/dist/report/demand.d.ts +49 -0
- package/dist/report/demand.js +60 -0
- package/dist/report/economics.d.ts +55 -0
- package/dist/report/economics.js +189 -0
- package/dist/report/headline.d.ts +158 -0
- package/dist/report/headline.js +473 -0
- package/dist/report/index.d.ts +2 -0
- package/dist/report/index.js +2 -0
- package/dist/report/inputs.d.ts +79 -0
- package/dist/report/inputs.js +115 -0
- package/dist/report/measurement.d.ts +1 -1
- package/dist/report/measurement.js +5 -1
- package/dist/report/traffic.d.ts +8 -0
- package/dist/report/traffic.js +7 -0
- package/dist/server/bundle.d.ts +55 -0
- package/dist/server/bundle.js +172 -0
- package/dist/server/dataset.d.ts +8 -2
- package/dist/server/dataset.js +51 -4
- package/dist/server/embedded.d.ts +7 -3
- package/dist/server/embedded.js +7 -3
- package/dist/server/index.d.ts +5 -1
- package/dist/server/index.js +5 -1
- package/dist/server/live-sockets.d.ts +54 -0
- package/dist/server/live-sockets.js +131 -0
- package/dist/server/live.d.ts +146 -0
- package/dist/server/live.js +228 -0
- package/dist/server/ring.d.ts +77 -0
- package/dist/server/ring.js +311 -0
- package/dist/server/spool.d.ts +139 -4
- package/dist/server/spool.js +457 -28
- package/dist/server/static.d.ts +42 -0
- package/dist/server/static.js +29 -0
- package/dist/server/stub.d.ts +43 -5
- package/dist/server/stub.js +126 -8
- package/dist/server/write.d.ts +23 -1
- package/dist/server/write.js +96 -0
- package/dist/stores/durable-object.d.ts +46 -0
- package/dist/stores/durable-object.js +114 -0
- package/dist/sw/analytics.d.ts +1 -1
- package/dist/sw/analytics.js +2 -2
- package/dist/sw/coverage.d.ts +6 -0
- package/dist/sw/coverage.js +34 -0
- package/dist/sw/family.d.ts +15 -0
- package/dist/sw/family.js +48 -0
- package/dist/sw/idb.d.ts +2 -0
- package/dist/sw/idb.js +2 -2
- package/dist/sw/index.d.ts +2 -0
- package/dist/sw/index.js +1 -0
- package/dist/sw/pack/store.d.ts +128 -0
- package/dist/sw/pack/store.js +737 -0
- package/dist/sw/policy.d.ts +2 -0
- package/dist/sw/policy.js +11 -0
- package/dist/sw/probe.d.ts +16 -0
- package/dist/sw/probe.js +25 -0
- package/dist/sw/router.d.ts +3 -2
- package/dist/sw/router.js +15 -2
- package/dist/sw/runtime.d.ts +48 -1
- package/dist/sw/runtime.js +548 -68
- package/dist/sw/scheduler.d.ts +6 -1
- package/dist/sw/scheduler.js +22 -5
- package/dist/sw/write.d.ts +41 -1
- package/dist/sw/write.js +188 -5
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -2
- package/dist/vite/index.d.ts +26 -0
- package/dist/vite/index.js +66 -0
- package/dist/vue/index.d.ts +36 -0
- package/dist/vue/index.js +53 -0
- package/package.json +64 -4
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
const CATCH_ALL = 'catch-all segment: ** captures no value';
|
|
2
|
+
const REPEAT = 'repeatable segment: spool has no repeatable segment';
|
|
3
|
+
const OPTIONAL = 'optional segment: spool has no optional segment';
|
|
4
|
+
const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
5
|
+
const PARAM = /^:([A-Za-z_][A-Za-z0-9_]*)$/;
|
|
6
|
+
const PLAIN = /^[A-Za-z0-9._~-]+$/;
|
|
7
|
+
const VUE_PARAM = /^:([^:()?+*]+)(\(\))?$/;
|
|
8
|
+
const VUE_CATCH_ALL = /\(\.\*\)\*$|\(\[\^\/\]\*\)\*$/;
|
|
9
|
+
const NEXT_PARAM = /^\[([A-Za-z_][A-Za-z0-9_]*)\]$/;
|
|
10
|
+
function network(reason) {
|
|
11
|
+
return { kind: 'network', reason };
|
|
12
|
+
}
|
|
13
|
+
function plain(segment) {
|
|
14
|
+
if (PLAIN.test(segment) && segment !== '.' && segment !== '..') {
|
|
15
|
+
return { kind: 'static', text: segment };
|
|
16
|
+
}
|
|
17
|
+
return network('static segment has a reserved or non-ASCII character');
|
|
18
|
+
}
|
|
19
|
+
// nuxt emits `:name()` for a file `[name].vue`; the empty pattern is the default one-segment match
|
|
20
|
+
function vuePart(segment) {
|
|
21
|
+
const param = VUE_PARAM.exec(segment);
|
|
22
|
+
if (param) {
|
|
23
|
+
const name = param[1] ?? '';
|
|
24
|
+
return NAME.test(name)
|
|
25
|
+
? { kind: 'param', text: `:${name}` }
|
|
26
|
+
: network('parameter name is not an identifier');
|
|
27
|
+
}
|
|
28
|
+
if (VUE_CATCH_ALL.test(segment))
|
|
29
|
+
return network(CATCH_ALL);
|
|
30
|
+
if (segment.endsWith('?'))
|
|
31
|
+
return network(OPTIONAL);
|
|
32
|
+
if (segment.startsWith(':') && /[+*]$/.test(segment))
|
|
33
|
+
return network(REPEAT);
|
|
34
|
+
if (segment.includes('('))
|
|
35
|
+
return network('custom regular expression in a segment');
|
|
36
|
+
return plain(segment);
|
|
37
|
+
}
|
|
38
|
+
function reactPart(segment) {
|
|
39
|
+
if (segment.includes('*'))
|
|
40
|
+
return network('splat segment: * captures no value');
|
|
41
|
+
if (segment.endsWith('?'))
|
|
42
|
+
return network(OPTIONAL);
|
|
43
|
+
if (segment.startsWith(':')) {
|
|
44
|
+
return PARAM.test(segment)
|
|
45
|
+
? { kind: 'param', text: segment }
|
|
46
|
+
: network('parameter is not a whole identifier segment');
|
|
47
|
+
}
|
|
48
|
+
if (/[(){}]/.test(segment))
|
|
49
|
+
return network('grouped segment');
|
|
50
|
+
return plain(segment);
|
|
51
|
+
}
|
|
52
|
+
function nextPart(segment) {
|
|
53
|
+
if (segment.startsWith('[...') || segment.startsWith('[[...'))
|
|
54
|
+
return network(CATCH_ALL);
|
|
55
|
+
const param = NEXT_PARAM.exec(segment);
|
|
56
|
+
if (param)
|
|
57
|
+
return { kind: 'param', text: `:${param[1] ?? ''}` };
|
|
58
|
+
if (segment.includes('['))
|
|
59
|
+
return network('dynamic segment mixed with text or not an identifier');
|
|
60
|
+
if (segment.startsWith('(')) {
|
|
61
|
+
return network('interception segment: (.) and (..) match another route');
|
|
62
|
+
}
|
|
63
|
+
return plain(segment);
|
|
64
|
+
}
|
|
65
|
+
function angularPart(segment) {
|
|
66
|
+
if (segment === '**')
|
|
67
|
+
return network('wildcard route: ** captures no value');
|
|
68
|
+
if (segment.startsWith(':')) {
|
|
69
|
+
return PARAM.test(segment)
|
|
70
|
+
? { kind: 'param', text: segment }
|
|
71
|
+
: network('parameter name is not an identifier');
|
|
72
|
+
}
|
|
73
|
+
if (/[*()]/.test(segment))
|
|
74
|
+
return network('unsupported segment');
|
|
75
|
+
return plain(segment);
|
|
76
|
+
}
|
|
77
|
+
// next drops route groups, parallel slots and the leaf `page` or `route`, as its own router does
|
|
78
|
+
function nextSegments(segments) {
|
|
79
|
+
return segments.filter((segment, at) => !(segment.startsWith('(') && segment.endsWith(')')) &&
|
|
80
|
+
!segment.startsWith('@') &&
|
|
81
|
+
!(at === segments.length - 1 && (segment === 'page' || segment === 'route')));
|
|
82
|
+
}
|
|
83
|
+
// a `/` inside parentheses is part of a pattern, such as the `([^/]*)*` of a nuxt catch-all
|
|
84
|
+
function segmentsOf(path) {
|
|
85
|
+
const out = [];
|
|
86
|
+
let depth = 0;
|
|
87
|
+
let current = '';
|
|
88
|
+
for (const char of path) {
|
|
89
|
+
if (char === '(')
|
|
90
|
+
depth++;
|
|
91
|
+
else if (char === ')')
|
|
92
|
+
depth = Math.max(0, depth - 1);
|
|
93
|
+
if (char === '/' && depth === 0) {
|
|
94
|
+
out.push(current);
|
|
95
|
+
current = '';
|
|
96
|
+
}
|
|
97
|
+
else {
|
|
98
|
+
current += char;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
out.push(current);
|
|
102
|
+
return out.filter((segment) => segment !== '');
|
|
103
|
+
}
|
|
104
|
+
function drive(segments, part) {
|
|
105
|
+
const out = [];
|
|
106
|
+
for (const segment of segments) {
|
|
107
|
+
const next = part(segment);
|
|
108
|
+
if (next.kind === 'network')
|
|
109
|
+
return { kind: 'network', reason: next.reason };
|
|
110
|
+
out.push(next.text);
|
|
111
|
+
}
|
|
112
|
+
const names = out.filter((text) => text.startsWith(':'));
|
|
113
|
+
if (new Set(names).size !== names.length) {
|
|
114
|
+
return { kind: 'network', reason: 'duplicate parameter name' };
|
|
115
|
+
}
|
|
116
|
+
return { kind: 'pattern', pattern: `/${out.join('/')}` };
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Converts a framework route path to a spool pattern. A static segment and a single-segment
|
|
120
|
+
* parameter convert; anything else returns `network` with the reason, never a pattern that would
|
|
121
|
+
* match a different set of URLs. Angular paths may omit the leading slash.
|
|
122
|
+
*/
|
|
123
|
+
export function toSpoolPattern(syntax, path) {
|
|
124
|
+
if (syntax !== 'angular' && !path.startsWith('/')) {
|
|
125
|
+
return { kind: 'network', reason: 'path must start with /' };
|
|
126
|
+
}
|
|
127
|
+
const segments = segmentsOf(path);
|
|
128
|
+
switch (syntax) {
|
|
129
|
+
case 'vue-router':
|
|
130
|
+
case 'nuxt':
|
|
131
|
+
return drive(segments, vuePart);
|
|
132
|
+
case 'react-router':
|
|
133
|
+
return drive(segments, reactPart);
|
|
134
|
+
case 'next':
|
|
135
|
+
return drive(nextSegments(segments), nextPart);
|
|
136
|
+
case 'angular':
|
|
137
|
+
return drive(segments, angularPart);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { Register } from './mode.js';
|
|
2
|
+
/** what the development report lists */
|
|
3
|
+
export type DevReport = {
|
|
4
|
+
/** routes registered, with the spool pattern each one was registered under */
|
|
5
|
+
registered: Array<{
|
|
6
|
+
pattern: string;
|
|
7
|
+
register: Register;
|
|
8
|
+
maxAge?: number;
|
|
9
|
+
}>;
|
|
10
|
+
/** pages left to the network, with the reason */
|
|
11
|
+
network: Array<{
|
|
12
|
+
path: string;
|
|
13
|
+
reason: string;
|
|
14
|
+
}>;
|
|
15
|
+
/**
|
|
16
|
+
* GET paths a page made that no family covered. Absent where the framework gives the report no
|
|
17
|
+
* requests to read (a build adapter, a config that never serves), so no count is printed.
|
|
18
|
+
*/
|
|
19
|
+
uncovered?: string[];
|
|
20
|
+
};
|
|
21
|
+
/** the text the development server prints for a report; one line per route or request */
|
|
22
|
+
export declare function formatDevReport(report: DevReport): string;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** the text the development server prints for a report; one line per route or request */
|
|
2
|
+
export function formatDevReport(report) {
|
|
3
|
+
const uncovered = report.uncovered;
|
|
4
|
+
const lines = [
|
|
5
|
+
`spool: ${report.registered.length} registered, ${report.network.length} left to the network${uncovered === undefined ? '' : `, ${uncovered.length} uncovered GET`}`
|
|
6
|
+
];
|
|
7
|
+
for (const route of report.registered) {
|
|
8
|
+
const age = route.maxAge === undefined ? '' : ` maxAge ${route.maxAge}s`;
|
|
9
|
+
lines.push(` registered ${route.pattern} ${route.register}${age}`);
|
|
10
|
+
}
|
|
11
|
+
for (const page of report.network) {
|
|
12
|
+
lines.push(` network ${page.path} ${page.reason}`);
|
|
13
|
+
}
|
|
14
|
+
for (const path of uncovered ?? []) {
|
|
15
|
+
lines.push(` uncovered GET ${path}`);
|
|
16
|
+
}
|
|
17
|
+
return lines.join('\n');
|
|
18
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { type Route, type RouteDeclaration } from '../protocol/route.js';
|
|
2
|
+
import type { Register } from './mode.js';
|
|
3
|
+
export type { Register, Registration } from './mode.js';
|
|
4
|
+
/** the fields of a framework registration the helper reads; every `pages.ts` registration has them */
|
|
5
|
+
export type PageLike = {
|
|
6
|
+
/** the framework's own path, such as `/articles/[id]` */
|
|
7
|
+
path: string;
|
|
8
|
+
/** the spool pattern; absent when the framework path does not convert */
|
|
9
|
+
pattern?: string;
|
|
10
|
+
register: Register;
|
|
11
|
+
reason: string;
|
|
12
|
+
};
|
|
13
|
+
/** a registered page no declaration covers, so no route exists for it and the network answers */
|
|
14
|
+
export type UncoveredPage = {
|
|
15
|
+
path: string;
|
|
16
|
+
pattern: string;
|
|
17
|
+
register: Register;
|
|
18
|
+
reason: string;
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Turns a framework's registrations into routes. `declarations` maps a spool pattern to what only
|
|
22
|
+
* the operator knows: the template or renderer, the family's dataset, the scope, `freshness`,
|
|
23
|
+
* `depends`. The helper adds no default of its own, so each declaration is the `defineRoute`
|
|
24
|
+
* declaration for its pattern.
|
|
25
|
+
*
|
|
26
|
+
* It checks both directions. A declaration whose pattern the framework did not register throws
|
|
27
|
+
* `bad-route` and names the pattern, which catches a typo and a page that was renamed or deleted.
|
|
28
|
+
* A registered pattern with no declaration gets no route (the network answers it) and comes back in
|
|
29
|
+
* `uncovered`, so print it. A declaration that reads a dataset (`family` or `query.dataset`) must set
|
|
30
|
+
* `scope` or `auth` itself: the helper never takes the default `public` for a dataset it did not
|
|
31
|
+
* see. A registration whose path did not convert has no pattern and cannot be declared. A pattern
|
|
32
|
+
* the framework lists twice gets one route. Routes come back in registration order, and the first
|
|
33
|
+
* one that matches a path answers it.
|
|
34
|
+
*/
|
|
35
|
+
export declare function routesFromPages(pages: readonly PageLike[], declarations: Readonly<Record<string, RouteDeclaration>>): {
|
|
36
|
+
routes: Route[];
|
|
37
|
+
uncovered: UncoveredPage[];
|
|
38
|
+
};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { ProtocolError } from '../protocol/errors.js';
|
|
2
|
+
import { defineRoute } from '../protocol/route.js';
|
|
3
|
+
/**
|
|
4
|
+
* Turns a framework's registrations into routes. `declarations` maps a spool pattern to what only
|
|
5
|
+
* the operator knows: the template or renderer, the family's dataset, the scope, `freshness`,
|
|
6
|
+
* `depends`. The helper adds no default of its own, so each declaration is the `defineRoute`
|
|
7
|
+
* declaration for its pattern.
|
|
8
|
+
*
|
|
9
|
+
* It checks both directions. A declaration whose pattern the framework did not register throws
|
|
10
|
+
* `bad-route` and names the pattern, which catches a typo and a page that was renamed or deleted.
|
|
11
|
+
* A registered pattern with no declaration gets no route (the network answers it) and comes back in
|
|
12
|
+
* `uncovered`, so print it. A declaration that reads a dataset (`family` or `query.dataset`) must set
|
|
13
|
+
* `scope` or `auth` itself: the helper never takes the default `public` for a dataset it did not
|
|
14
|
+
* see. A registration whose path did not convert has no pattern and cannot be declared. A pattern
|
|
15
|
+
* the framework lists twice gets one route. Routes come back in registration order, and the first
|
|
16
|
+
* one that matches a path answers it.
|
|
17
|
+
*/
|
|
18
|
+
export function routesFromPages(pages, declarations) {
|
|
19
|
+
const registered = new Map();
|
|
20
|
+
for (const page of pages) {
|
|
21
|
+
if (page.pattern !== undefined && !registered.has(page.pattern)) {
|
|
22
|
+
registered.set(page.pattern, { ...page, pattern: page.pattern });
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
const unknown = Object.keys(declarations).filter((pattern) => !registered.has(pattern));
|
|
26
|
+
if (unknown.length > 0) {
|
|
27
|
+
throw new ProtocolError('bad-route', `${unknown.join(', ')}: the framework registered no such route (registered: ${[...registered.keys()].join(', ') || 'none'})`);
|
|
28
|
+
}
|
|
29
|
+
const routes = [];
|
|
30
|
+
const uncovered = [];
|
|
31
|
+
for (const [pattern, page] of registered) {
|
|
32
|
+
const declaration = declarations[pattern];
|
|
33
|
+
if (declaration === undefined) {
|
|
34
|
+
uncovered.push({
|
|
35
|
+
path: page.path,
|
|
36
|
+
pattern,
|
|
37
|
+
register: page.register,
|
|
38
|
+
reason: page.reason
|
|
39
|
+
});
|
|
40
|
+
continue;
|
|
41
|
+
}
|
|
42
|
+
const reads = declaration.family !== undefined ||
|
|
43
|
+
declaration.query?.dataset !== undefined;
|
|
44
|
+
const declared = declaration.scope !== undefined ||
|
|
45
|
+
declaration.auth !== undefined;
|
|
46
|
+
if (reads && !declared) {
|
|
47
|
+
throw new ProtocolError('bad-route', `${pattern}: a route that reads a dataset must declare its scope: set scope to 'public' or 'principal'`);
|
|
48
|
+
}
|
|
49
|
+
routes.push(defineRoute(pattern, declaration));
|
|
50
|
+
}
|
|
51
|
+
return { routes, uncovered };
|
|
52
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { Spool } from '../server/spool.js';
|
|
2
|
+
/** what a build gives the `static` option of a plugin */
|
|
3
|
+
export type StaticBuildContext = {
|
|
4
|
+
/** the public directory the build wrote, where the static tier goes */
|
|
5
|
+
outDir: string;
|
|
6
|
+
};
|
|
7
|
+
/** the `static` option of a plugin that publishes the static tier at build time */
|
|
8
|
+
export type StaticBuildOptions = {
|
|
9
|
+
/**
|
|
10
|
+
* The instance to publish from, or a function that makes it from the build output. Default: the
|
|
11
|
+
* `spool` the plugin was given. A single-page app passes a function when its shell routes must
|
|
12
|
+
* hold the built `index.html`, because the instance made at config time holds the dev one.
|
|
13
|
+
*/
|
|
14
|
+
spool?: Spool | ((context: StaticBuildContext) => Spool | Promise<Spool>);
|
|
15
|
+
/**
|
|
16
|
+
* The site's security headers the worker replays on pages it renders locally; `{}` says the site
|
|
17
|
+
* sends none. Default: the `policy` option of the spool, the headers of a page it answered, then
|
|
18
|
+
* the `/*` block of the `_headers` file in the public directory. With none of them the stub
|
|
19
|
+
* names no policy, and a device makes one network view to learn it.
|
|
20
|
+
*/
|
|
21
|
+
policy?: Record<string, string>;
|
|
22
|
+
/** the origin the seed functions of the datasets receive; default `http://localhost/` */
|
|
23
|
+
url?: string | URL;
|
|
24
|
+
};
|
|
25
|
+
/** `false` turns the build step off, `true` or absent publishes with the defaults */
|
|
26
|
+
export type StaticOption = boolean | StaticBuildOptions;
|
|
27
|
+
/**
|
|
28
|
+
* The policy headers of the `/*` block of a `_headers` file, or undefined when it names none. A
|
|
29
|
+
* block that sends other headers says nothing about the policy, so it is not an empty policy.
|
|
30
|
+
*/
|
|
31
|
+
export declare function policyFromHeadersFile(text: string): Record<string, string> | undefined;
|
|
32
|
+
/**
|
|
33
|
+
* Publishes the static tier into `outDir` at the end of a build and logs one line. A failure
|
|
34
|
+
* rejects, so the build fails with the library's error; a build that hid a missing tier would ship a
|
|
35
|
+
* site that is slower than it looks. Does nothing when `option` is `false`.
|
|
36
|
+
*/
|
|
37
|
+
export declare function publishStaticBuild(input: {
|
|
38
|
+
spool: Spool;
|
|
39
|
+
option: StaticOption | undefined;
|
|
40
|
+
outDir: string;
|
|
41
|
+
log: (line: string) => void;
|
|
42
|
+
}): Promise<void>;
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { readFile, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { fileStaticSink } from '../node/listener.js';
|
|
4
|
+
import { POLICY_HEADERS } from '../sw/policy.js';
|
|
5
|
+
const isIndented = (line) => /^\s+\S/.test(line);
|
|
6
|
+
const isPathLine = (line) => line.trim() !== '' && !isIndented(line) && !line.startsWith('#');
|
|
7
|
+
/** the blocks of a `_headers` file: a path line and the indented lines under it */
|
|
8
|
+
function blocksOf(text) {
|
|
9
|
+
const blocks = [];
|
|
10
|
+
for (const line of text.split(/\r?\n/)) {
|
|
11
|
+
if (isPathLine(line))
|
|
12
|
+
blocks.push({ path: line.trim(), lines: [] });
|
|
13
|
+
else if (isIndented(line))
|
|
14
|
+
blocks.at(-1)?.lines.push(line.trim());
|
|
15
|
+
}
|
|
16
|
+
return blocks;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* The policy headers of the `/*` block of a `_headers` file, or undefined when it names none. A
|
|
20
|
+
* block that sends other headers says nothing about the policy, so it is not an empty policy.
|
|
21
|
+
*/
|
|
22
|
+
export function policyFromHeadersFile(text) {
|
|
23
|
+
const names = POLICY_HEADERS;
|
|
24
|
+
const out = {};
|
|
25
|
+
for (const block of blocksOf(text)) {
|
|
26
|
+
if (block.path !== '/*')
|
|
27
|
+
continue;
|
|
28
|
+
for (const line of block.lines) {
|
|
29
|
+
const at = line.indexOf(':');
|
|
30
|
+
if (at < 1)
|
|
31
|
+
continue;
|
|
32
|
+
const name = line.slice(0, at).trim().toLowerCase();
|
|
33
|
+
if (!names.includes(name))
|
|
34
|
+
continue;
|
|
35
|
+
const value = line.slice(at + 1).trim();
|
|
36
|
+
out[name] = out[name] === undefined ? value : `${out[name]}, ${value}`;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
return Object.keys(out).length > 0 ? out : undefined;
|
|
40
|
+
}
|
|
41
|
+
const OURS = new Set(['/.spool/*', '/spool-sw.js']);
|
|
42
|
+
/** `existing` with the blocks spool wrote before taken out, every other line kept as it was */
|
|
43
|
+
function withoutSpoolBlocks(existing) {
|
|
44
|
+
const kept = [];
|
|
45
|
+
let skipping = false;
|
|
46
|
+
for (const line of existing.split(/\r?\n/)) {
|
|
47
|
+
if (isPathLine(line))
|
|
48
|
+
skipping = OURS.has(line.trim());
|
|
49
|
+
else if (skipping && (isIndented(line) || line.trim() === ''))
|
|
50
|
+
continue;
|
|
51
|
+
else
|
|
52
|
+
skipping = false;
|
|
53
|
+
if (!skipping)
|
|
54
|
+
kept.push(line);
|
|
55
|
+
}
|
|
56
|
+
return kept.join('\n').trimEnd();
|
|
57
|
+
}
|
|
58
|
+
/** a sink for a directory whose `_headers` file the site may already own: spool's blocks are added to it */
|
|
59
|
+
function mergingSink(outDir) {
|
|
60
|
+
const files = fileStaticSink(outDir);
|
|
61
|
+
return {
|
|
62
|
+
has: (path) => files.has?.(path) ?? false,
|
|
63
|
+
async put(path, bytes, contentType) {
|
|
64
|
+
if (path !== '/_headers')
|
|
65
|
+
return files.put(path, bytes, contentType);
|
|
66
|
+
const existing = await readFile(join(outDir, path), 'utf8').catch(() => '');
|
|
67
|
+
const site = withoutSpoolBlocks(existing);
|
|
68
|
+
const ours = new TextDecoder().decode(bytes);
|
|
69
|
+
await writeFile(join(outDir, path), site === '' ? ours : `${site}\n\n${ours}`);
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* Publishes the static tier into `outDir` at the end of a build and logs one line. A failure
|
|
75
|
+
* rejects, so the build fails with the library's error; a build that hid a missing tier would ship a
|
|
76
|
+
* site that is slower than it looks. Does nothing when `option` is `false`.
|
|
77
|
+
*/
|
|
78
|
+
export async function publishStaticBuild(input) {
|
|
79
|
+
const { option, outDir, log } = input;
|
|
80
|
+
if (option === false)
|
|
81
|
+
return;
|
|
82
|
+
const settings = typeof option === 'object' ? option : {};
|
|
83
|
+
const spool = typeof settings.spool === 'function'
|
|
84
|
+
? await settings.spool({ outDir })
|
|
85
|
+
: (settings.spool ?? input.spool);
|
|
86
|
+
const headersFile = await readFile(join(outDir, '_headers'), 'utf8').catch(() => undefined);
|
|
87
|
+
const fallbackPolicy = headersFile === undefined ? undefined : policyFromHeadersFile(headersFile);
|
|
88
|
+
const { paths, policy } = await spool.publishStatic(mergingSink(outDir), {
|
|
89
|
+
url: new URL(settings.url ?? 'http://localhost/'),
|
|
90
|
+
...(settings.policy ? { policy: settings.policy } : {}),
|
|
91
|
+
...(fallbackPolicy ? { fallbackPolicy } : {})
|
|
92
|
+
});
|
|
93
|
+
log(`spool: wrote ${paths.length} static files to ${outDir}`);
|
|
94
|
+
if (policy === 'none') {
|
|
95
|
+
log('spool: no site policy found, so the stub names none and a device makes one network view to learn it; set static.policy to name it');
|
|
96
|
+
}
|
|
97
|
+
}
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import type { DatasetRow } from './dataset.js';
|
|
2
|
+
/** rows per block when the caller names no size */
|
|
3
|
+
export declare const BLOCK_ROWS = 128;
|
|
4
|
+
/** overlay rows past which a base pack is compacted; a default, not measured */
|
|
5
|
+
export declare const COMPACT_OVERLAY_ROWS = 1000;
|
|
6
|
+
/** overlay bytes past which a base pack is compacted; a default, not measured */
|
|
7
|
+
export declare const COMPACT_OVERLAY_BYTES = 65536;
|
|
8
|
+
/** the largest payload a frame may declare; a reader refuses a larger header before the payload */
|
|
9
|
+
export declare const MAX_BUNDLE_FRAME_BYTES = 8388608;
|
|
10
|
+
/** the most one block may inflate to; a reader refuses a larger block before it holds the bytes */
|
|
11
|
+
export declare const MAX_BUNDLE_BLOCK_BYTES = 1048576;
|
|
12
|
+
type Bytes = Uint8Array<ArrayBuffer>;
|
|
13
|
+
/** rows of one table, sorted by key in code unit order */
|
|
14
|
+
export type BundleRows = Array<[string, DatasetRow]>;
|
|
15
|
+
/** a version and the tables it holds; an empty table is not held */
|
|
16
|
+
export type BundleState = {
|
|
17
|
+
version: number;
|
|
18
|
+
tables: Record<string, BundleRows>;
|
|
19
|
+
};
|
|
20
|
+
/** one table's entry in the index: its row count, first key and the hash of each block */
|
|
21
|
+
export type BundleTableIndex = {
|
|
22
|
+
name: string;
|
|
23
|
+
rows: number;
|
|
24
|
+
first: string | null;
|
|
25
|
+
blocks: string[];
|
|
26
|
+
};
|
|
27
|
+
/** the index frame: the version, the set digest and every table's blocks, in table order */
|
|
28
|
+
export type BundleIndex = {
|
|
29
|
+
version: number;
|
|
30
|
+
codec: 'gzip';
|
|
31
|
+
blockRows: number;
|
|
32
|
+
digest: string;
|
|
33
|
+
tables: BundleTableIndex[];
|
|
34
|
+
};
|
|
35
|
+
/** the rows to put and the keys to remove in one table */
|
|
36
|
+
export type BundleDeltaTable = {
|
|
37
|
+
puts: BundleRows;
|
|
38
|
+
deletes: string[];
|
|
39
|
+
};
|
|
40
|
+
/** the change from `from` to `to`; `digest` is the set digest of the state it reaches */
|
|
41
|
+
export type BundleDelta = {
|
|
42
|
+
from: number;
|
|
43
|
+
to: number;
|
|
44
|
+
digest: string;
|
|
45
|
+
tables: Record<string, BundleDeltaTable>;
|
|
46
|
+
};
|
|
47
|
+
/** one frame of a pack: the index table and ordinal it carries, and its payload */
|
|
48
|
+
export type BundleFrame = {
|
|
49
|
+
table: number;
|
|
50
|
+
ordinal: number;
|
|
51
|
+
payload: Bytes;
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* The set digest of every table: the sum of each row's hash modulo 2^256, where a row's hash covers
|
|
55
|
+
* its table name and its key as well as its value. An empty table adds nothing.
|
|
56
|
+
*/
|
|
57
|
+
export declare function bundleDigest(tables: Record<string, BundleRows>): Promise<string>;
|
|
58
|
+
/**
|
|
59
|
+
* Encodes a state as a pack: an index frame, then one frame per block in table order. Empty tables
|
|
60
|
+
* are left out. Throws `bad-bundle` for a repeated key, a block size under one, or a block over
|
|
61
|
+
* `maxFrameBytes` or `MAX_BUNDLE_BLOCK_BYTES`, which a reader would refuse.
|
|
62
|
+
*/
|
|
63
|
+
export declare function buildPack(state: BundleState, blockRows?: number, maxFrameBytes?: number): Promise<{
|
|
64
|
+
index: BundleIndex;
|
|
65
|
+
bytes: Bytes;
|
|
66
|
+
}>;
|
|
67
|
+
/**
|
|
68
|
+
* Yields the frames of a pack as their bytes arrive, so a reader can verify and keep each block
|
|
69
|
+
* before the next one lands. Throws `bad-bundle` for a frame that is cut short, has a bad header,
|
|
70
|
+
* or declares a payload over `maxFrameBytes`; that check runs before the payload is read.
|
|
71
|
+
*/
|
|
72
|
+
export declare function readFrames(source: AsyncIterable<Bytes>, maxFrameBytes?: number): AsyncGenerator<BundleFrame>;
|
|
73
|
+
/**
|
|
74
|
+
* Checks one block frame against the index and returns its rows. The hash is checked before the
|
|
75
|
+
* block is decompressed, so a corrupt block is refused without being parsed.
|
|
76
|
+
*/
|
|
77
|
+
export declare function readBlock(index: BundleIndex, block: BundleFrame): Promise<BundleRows>;
|
|
78
|
+
/**
|
|
79
|
+
* Reads a whole pack, or a pack that arrives in chunks, and returns its index and state. Every
|
|
80
|
+
* block is checked as it lands, and the set digest is checked at the end. Throws `bad-bundle`.
|
|
81
|
+
*/
|
|
82
|
+
export declare function readBundle(source: Bytes | AsyncIterable<Bytes>, maxFrameBytes?: number): Promise<{
|
|
83
|
+
index: BundleIndex;
|
|
84
|
+
state: BundleState;
|
|
85
|
+
}>;
|
|
86
|
+
/** the change from `from` to `to`: puts for new or changed rows, deletes for rows that left */
|
|
87
|
+
export declare function makeDelta(from: BundleState, to: BundleState): Promise<BundleDelta>;
|
|
88
|
+
/**
|
|
89
|
+
* Applies a delta to the state at its `from` version and returns the state at `to`. Refuses a base
|
|
90
|
+
* at another version, and a result whose set digest is not the delta's.
|
|
91
|
+
*/
|
|
92
|
+
export declare function applyDelta(base: BundleState, delta: BundleDelta): Promise<BundleState>;
|
|
93
|
+
/**
|
|
94
|
+
* One delta equal to applying `deltas` in order. The deltas must chain: each `from` is the previous
|
|
95
|
+
* `to`. A key put and then removed becomes a tombstone, which a holder without the key ignores.
|
|
96
|
+
*/
|
|
97
|
+
export declare function mergeDeltas(deltas: readonly BundleDelta[]): BundleDelta;
|
|
98
|
+
/**
|
|
99
|
+
* whether a delta has more than {@link COMPACT_OVERLAY_ROWS} rows or
|
|
100
|
+
* {@link COMPACT_OVERLAY_BYTES} bytes of JSON
|
|
101
|
+
*/
|
|
102
|
+
export declare function compactionDue(delta: BundleDelta): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* Folds a delta into a base pack and returns the new pack, built with the base's block size. Its
|
|
105
|
+
* bytes equal {@link buildPack} run on the state the delta reaches.
|
|
106
|
+
*/
|
|
107
|
+
export declare function compactBundle(base: Bytes, overlay: BundleDelta): Promise<{
|
|
108
|
+
index: BundleIndex;
|
|
109
|
+
bytes: Bytes;
|
|
110
|
+
}>;
|
|
111
|
+
export {};
|