@drupflare/spool 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +1557 -2
- package/dist/cdn/client.js +1 -0
- package/dist/cdn/location.d.ts +11 -0
- package/dist/cdn/location.js +15 -0
- package/dist/cdn/manifest.json +16 -0
- package/dist/cdn/spool-sw.js +1 -0
- package/dist/client/entry.d.ts +1 -0
- package/dist/client/entry.js +25 -0
- package/dist/client/index.d.ts +3 -0
- package/dist/client/index.js +2 -0
- package/dist/client/lifecycle.d.ts +10 -0
- package/dist/client/lifecycle.js +10 -0
- package/dist/client/loads.d.ts +16 -0
- package/dist/client/loads.js +41 -0
- package/dist/client/register.d.ts +34 -0
- package/dist/client/register.js +58 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/node/listener.d.ts +19 -0
- package/dist/node/listener.js +76 -0
- package/dist/protocol/artifact.d.ts +54 -0
- package/dist/protocol/artifact.js +79 -0
- package/dist/protocol/assembly.d.ts +34 -0
- package/dist/protocol/assembly.js +72 -0
- package/dist/protocol/beacon.d.ts +59 -0
- package/dist/protocol/beacon.js +86 -0
- package/dist/protocol/collector.d.ts +41 -0
- package/dist/protocol/collector.js +84 -0
- package/dist/protocol/config.d.ts +89 -0
- package/dist/protocol/config.js +13 -0
- package/dist/protocol/envelope.d.ts +47 -0
- package/dist/protocol/envelope.js +162 -0
- package/dist/protocol/errors.d.ts +7 -0
- package/dist/protocol/errors.js +9 -0
- package/dist/protocol/graph.d.ts +81 -0
- package/dist/protocol/graph.js +201 -0
- package/dist/protocol/index.d.ts +19 -0
- package/dist/protocol/index.js +19 -0
- package/dist/protocol/manifest.d.ts +29 -0
- package/dist/protocol/manifest.js +94 -0
- package/dist/protocol/normalise.d.ts +20 -0
- package/dist/protocol/normalise.js +29 -0
- package/dist/protocol/pattern.d.ts +12 -0
- package/dist/protocol/pattern.js +82 -0
- package/dist/protocol/provision.d.ts +100 -0
- package/dist/protocol/provision.js +105 -0
- package/dist/protocol/route.d.ts +179 -0
- package/dist/protocol/route.js +135 -0
- package/dist/protocol/sync.d.ts +31 -0
- package/dist/protocol/sync.js +87 -0
- package/dist/protocol/tag.d.ts +12 -0
- package/dist/protocol/tag.js +26 -0
- package/dist/protocol/template/compile.d.ts +35 -0
- package/dist/protocol/template/compile.js +82 -0
- package/dist/protocol/template/interpret.d.ts +9 -0
- package/dist/protocol/template/interpret.js +82 -0
- package/dist/protocol/vector.d.ts +32 -0
- package/dist/protocol/vector.js +56 -0
- package/dist/protocol/view.d.ts +110 -0
- package/dist/protocol/view.js +201 -0
- package/dist/proxy/eligible.d.ts +45 -0
- package/dist/proxy/eligible.js +96 -0
- package/dist/proxy/index.d.ts +4 -0
- package/dist/proxy/index.js +4 -0
- package/dist/proxy/proxy.d.ts +86 -0
- package/dist/proxy/proxy.js +388 -0
- package/dist/proxy/purge.d.ts +10 -0
- package/dist/proxy/purge.js +66 -0
- package/dist/proxy/tags.d.ts +8 -0
- package/dist/proxy/tags.js +36 -0
- package/dist/report/derive.d.ts +221 -0
- package/dist/report/derive.js +490 -0
- package/dist/report/economics.d.ts +14 -0
- package/dist/report/economics.js +24 -0
- package/dist/report/index.d.ts +8 -0
- package/dist/report/index.js +8 -0
- package/dist/report/inputs.d.ts +141 -0
- package/dist/report/inputs.js +216 -0
- package/dist/report/measurement.d.ts +48 -0
- package/dist/report/measurement.js +114 -0
- package/dist/report/model.d.ts +42 -0
- package/dist/report/model.js +74 -0
- package/dist/report/thirdparty.d.ts +62 -0
- package/dist/report/thirdparty.js +107 -0
- package/dist/report/traffic.d.ts +140 -0
- package/dist/report/traffic.js +228 -0
- package/dist/report/trim.d.ts +81 -0
- package/dist/report/trim.js +105 -0
- package/dist/server/beacon.d.ts +20 -0
- package/dist/server/beacon.js +47 -0
- package/dist/server/embedded.d.ts +6 -0
- package/dist/server/embedded.js +6 -0
- package/dist/server/ga4.d.ts +70 -0
- package/dist/server/ga4.js +165 -0
- package/dist/server/identity.d.ts +12 -0
- package/dist/server/identity.js +17 -0
- package/dist/server/index.d.ts +7 -0
- package/dist/server/index.js +7 -0
- package/dist/server/sink.d.ts +56 -0
- package/dist/server/sink.js +133 -0
- package/dist/server/size.d.ts +7 -0
- package/dist/server/size.js +18 -0
- package/dist/server/spool.d.ts +97 -0
- package/dist/server/spool.js +463 -0
- package/dist/server/stub.d.ts +9 -0
- package/dist/server/stub.js +19 -0
- package/dist/server/sync.d.ts +12 -0
- package/dist/server/sync.js +48 -0
- package/dist/server/work.d.ts +22 -0
- package/dist/server/work.js +30 -0
- package/dist/stores/durable-object.d.ts +19 -0
- package/dist/stores/durable-object.js +53 -0
- package/dist/stores/index.d.ts +2 -0
- package/dist/stores/index.js +2 -0
- package/dist/stores/memory.d.ts +4 -0
- package/dist/stores/memory.js +10 -0
- package/dist/stores/version-store.d.ts +11 -0
- package/dist/stores/version-store.js +1 -0
- package/dist/sw/analytics.d.ts +81 -0
- package/dist/sw/analytics.js +275 -0
- package/dist/sw/collect.d.ts +8 -0
- package/dist/sw/collect.js +33 -0
- package/dist/sw/core.d.ts +1 -0
- package/dist/sw/core.js +3 -0
- package/dist/sw/freshness.d.ts +15 -0
- package/dist/sw/freshness.js +20 -0
- package/dist/sw/graph/index.d.ts +67 -0
- package/dist/sw/graph/index.js +170 -0
- package/dist/sw/graph/invalidate.d.ts +23 -0
- package/dist/sw/graph/invalidate.js +109 -0
- package/dist/sw/graph/projections.d.ts +7 -0
- package/dist/sw/graph/projections.js +9 -0
- package/dist/sw/graph/records.d.ts +7 -0
- package/dist/sw/graph/records.js +9 -0
- package/dist/sw/graph/store.d.ts +32 -0
- package/dist/sw/graph/store.js +52 -0
- package/dist/sw/idb.d.ts +8 -0
- package/dist/sw/idb.js +117 -0
- package/dist/sw/index.d.ts +2 -0
- package/dist/sw/index.js +1 -0
- package/dist/sw/partition.d.ts +21 -0
- package/dist/sw/partition.js +137 -0
- package/dist/sw/policy.d.ts +8 -0
- package/dist/sw/policy.js +24 -0
- package/dist/sw/provision.d.ts +39 -0
- package/dist/sw/provision.js +61 -0
- package/dist/sw/render.d.ts +21 -0
- package/dist/sw/render.js +53 -0
- package/dist/sw/replica.d.ts +77 -0
- package/dist/sw/replica.js +299 -0
- package/dist/sw/router.d.ts +42 -0
- package/dist/sw/router.js +48 -0
- package/dist/sw/routing.d.ts +23 -0
- package/dist/sw/routing.js +48 -0
- package/dist/sw/runtime.d.ts +112 -0
- package/dist/sw/runtime.js +1070 -0
- package/dist/sw/scheduler.d.ts +83 -0
- package/dist/sw/scheduler.js +149 -0
- package/dist/sw/seal.d.ts +37 -0
- package/dist/sw/seal.js +183 -0
- package/dist/sw/serve.d.ts +15 -0
- package/dist/sw/serve.js +63 -0
- package/dist/sw/shadow.d.ts +16 -0
- package/dist/sw/shadow.js +27 -0
- package/dist/sw/static.d.ts +17 -0
- package/dist/sw/static.js +81 -0
- package/dist/sw/storage.d.ts +64 -0
- package/dist/sw/storage.js +34 -0
- package/dist/sw/thirdparty.d.ts +17 -0
- package/dist/sw/thirdparty.js +36 -0
- package/dist/trim/css.d.ts +38 -0
- package/dist/trim/css.js +328 -0
- package/dist/trim/index.d.ts +3 -0
- package/dist/trim/index.js +3 -0
- package/dist/trim/manifest.d.ts +67 -0
- package/dist/trim/manifest.js +134 -0
- package/dist/trim/tokens.d.ts +43 -0
- package/dist/trim/tokens.js +142 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +3 -0
- package/package.json +146 -5
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { PROTOCOL_VERSION } from './artifact.js';
|
|
2
|
+
import { ProtocolError } from './errors.js';
|
|
3
|
+
/** the header names, lowercase as `Headers` reports them */
|
|
4
|
+
export const HEADERS = {
|
|
5
|
+
protocol: 'spool-protocol',
|
|
6
|
+
artifact: 'spool-artifact',
|
|
7
|
+
invalidate: 'spool-invalidate',
|
|
8
|
+
clear: 'spool-clear',
|
|
9
|
+
vector: 'spool-vector',
|
|
10
|
+
partition: 'spool-partition',
|
|
11
|
+
vectorSeen: 'spool-vector-seen',
|
|
12
|
+
provision: 'spool-provision'
|
|
13
|
+
};
|
|
14
|
+
/** `Spool-Clear` token that wipes everything the worker holds */
|
|
15
|
+
export const CLEAR_ALL = '*';
|
|
16
|
+
const PARTITION = /^[A-Za-z0-9_-]{1,128}$/;
|
|
17
|
+
function bad(message) {
|
|
18
|
+
throw new ProtocolError('bad-header', message);
|
|
19
|
+
}
|
|
20
|
+
function integer(text, field) {
|
|
21
|
+
if (!/^\d{1,15}$/.test(text.trim()))
|
|
22
|
+
return bad(`${field} must be a non-negative integer`);
|
|
23
|
+
return Number(text);
|
|
24
|
+
}
|
|
25
|
+
function decode(text, field) {
|
|
26
|
+
try {
|
|
27
|
+
return decodeURIComponent(text);
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return bad(`${field} has a bad escape`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
function list(text) {
|
|
34
|
+
return text
|
|
35
|
+
.split(',')
|
|
36
|
+
.map((part) => part.trim())
|
|
37
|
+
.filter((part) => part !== '');
|
|
38
|
+
}
|
|
39
|
+
/** the header map for an envelope; `Spool-Protocol` is always present */
|
|
40
|
+
export function encodeEnvelope(envelope) {
|
|
41
|
+
const out = {
|
|
42
|
+
[HEADERS.protocol]: String(envelope.protocol ?? PROTOCOL_VERSION)
|
|
43
|
+
};
|
|
44
|
+
const { artifact, invalidate, clear, vector, seen, partition } = envelope;
|
|
45
|
+
if (artifact) {
|
|
46
|
+
out[HEADERS.artifact] = [
|
|
47
|
+
`id=${encodeURIComponent(artifact.id)}`,
|
|
48
|
+
`scope=${artifact.scope}`,
|
|
49
|
+
`deps=${artifact.deps.map(encodeURIComponent).join(',')}`,
|
|
50
|
+
`v=${artifact.version}`
|
|
51
|
+
].join('; ');
|
|
52
|
+
}
|
|
53
|
+
const changed = Object.entries(invalidate ?? {});
|
|
54
|
+
if (changed.length > 0) {
|
|
55
|
+
out[HEADERS.invalidate] = changed
|
|
56
|
+
.map(([t, v]) => `${encodeURIComponent(t)}=${v}`)
|
|
57
|
+
.join(', ');
|
|
58
|
+
}
|
|
59
|
+
if (clear && clear.length > 0)
|
|
60
|
+
out[HEADERS.clear] = clear.map(encodeURIComponent).join(', ');
|
|
61
|
+
if (vector !== undefined)
|
|
62
|
+
out[HEADERS.vector] = String(vector);
|
|
63
|
+
if (seen !== undefined)
|
|
64
|
+
out[HEADERS.vectorSeen] = String(seen);
|
|
65
|
+
if (partition !== undefined) {
|
|
66
|
+
if (!PARTITION.test(partition))
|
|
67
|
+
return bad('partition must be a base64url token');
|
|
68
|
+
out[HEADERS.partition] = partition;
|
|
69
|
+
}
|
|
70
|
+
return out;
|
|
71
|
+
}
|
|
72
|
+
/** sets every header of `envelope` on `headers`, replacing any spool header already there */
|
|
73
|
+
export function writeEnvelope(headers, envelope) {
|
|
74
|
+
for (const [name, value] of Object.entries(encodeEnvelope(envelope)))
|
|
75
|
+
headers.set(name, value);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The envelope of a response as the worker uses it. A malformed spool header drops every field
|
|
79
|
+
* but `Spool-Clear`, which is read on its own so a valid clear still applies and a malformed one
|
|
80
|
+
* reads as a full wipe. A response that names another protocol version is left alone.
|
|
81
|
+
*/
|
|
82
|
+
export function decodeEnvelopeOrClear(headers) {
|
|
83
|
+
try {
|
|
84
|
+
return decodeEnvelope(headers);
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
const version = headers.get(HEADERS.protocol)?.trim();
|
|
88
|
+
if (version && /^\d{1,15}$/.test(version) && Number(version) !== PROTOCOL_VERSION) {
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
const raw = headers.get(HEADERS.clear);
|
|
92
|
+
if (raw === null)
|
|
93
|
+
return undefined;
|
|
94
|
+
try {
|
|
95
|
+
return {
|
|
96
|
+
protocol: PROTOCOL_VERSION,
|
|
97
|
+
clear: list(raw).map((t) => decode(t, 'Spool-Clear'))
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
return { protocol: PROTOCOL_VERSION, clear: [CLEAR_ALL] };
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
/** reads the spool headers; throws `ProtocolError` on a malformed one */
|
|
106
|
+
export function decodeEnvelope(headers) {
|
|
107
|
+
const out = {};
|
|
108
|
+
const protocol = headers.get(HEADERS.protocol);
|
|
109
|
+
if (protocol !== null)
|
|
110
|
+
out.protocol = integer(protocol, 'Spool-Protocol');
|
|
111
|
+
const artifact = headers.get(HEADERS.artifact);
|
|
112
|
+
if (artifact !== null) {
|
|
113
|
+
const fields = new Map();
|
|
114
|
+
for (const part of artifact.split(';')) {
|
|
115
|
+
const eq = part.indexOf('=');
|
|
116
|
+
if (eq < 1)
|
|
117
|
+
return bad('Spool-Artifact has a field without a name');
|
|
118
|
+
fields.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
|
|
119
|
+
}
|
|
120
|
+
const id = fields.get('id');
|
|
121
|
+
const scope = fields.get('scope');
|
|
122
|
+
const version = fields.get('v');
|
|
123
|
+
if (id === undefined || version === undefined)
|
|
124
|
+
return bad('Spool-Artifact needs id and v');
|
|
125
|
+
if (scope !== 'public' && scope !== 'principal')
|
|
126
|
+
return bad('Spool-Artifact scope is unknown');
|
|
127
|
+
out.artifact = {
|
|
128
|
+
id: decode(id, 'Spool-Artifact id'),
|
|
129
|
+
scope,
|
|
130
|
+
deps: list(fields.get('deps') ?? '').map((d) => decode(d, 'Spool-Artifact deps')),
|
|
131
|
+
version: integer(version, 'Spool-Artifact v')
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
const invalidate = headers.get(HEADERS.invalidate);
|
|
135
|
+
if (invalidate !== null) {
|
|
136
|
+
out.invalidate = Object.fromEntries(list(invalidate).map((pair) => {
|
|
137
|
+
const eq = pair.lastIndexOf('=');
|
|
138
|
+
if (eq < 1)
|
|
139
|
+
return bad('Spool-Invalidate entries are tag=version');
|
|
140
|
+
return [
|
|
141
|
+
decode(pair.slice(0, eq), 'Spool-Invalidate tag'),
|
|
142
|
+
integer(pair.slice(eq + 1), 'Spool-Invalidate version')
|
|
143
|
+
];
|
|
144
|
+
}));
|
|
145
|
+
}
|
|
146
|
+
const clear = headers.get(HEADERS.clear);
|
|
147
|
+
if (clear !== null)
|
|
148
|
+
out.clear = list(clear).map((t) => decode(t, 'Spool-Clear'));
|
|
149
|
+
const vector = headers.get(HEADERS.vector);
|
|
150
|
+
if (vector !== null)
|
|
151
|
+
out.vector = integer(vector, 'Spool-Vector');
|
|
152
|
+
const seen = headers.get(HEADERS.vectorSeen);
|
|
153
|
+
if (seen !== null)
|
|
154
|
+
out.seen = integer(seen, 'Spool-Vector-Seen');
|
|
155
|
+
const partition = headers.get(HEADERS.partition);
|
|
156
|
+
if (partition !== null) {
|
|
157
|
+
if (!PARTITION.test(partition))
|
|
158
|
+
return bad('Spool-Partition must be a base64url token');
|
|
159
|
+
out.partition = partition;
|
|
160
|
+
}
|
|
161
|
+
return out;
|
|
162
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** why a protocol value was refused */
|
|
2
|
+
export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-beacon' | 'bad-template' | 'bad-manifest';
|
|
3
|
+
/** thrown for malformed protocol input; `code` names the family so callers can map it to a status */
|
|
4
|
+
export declare class ProtocolError extends Error {
|
|
5
|
+
readonly code: ProtocolErrorCode;
|
|
6
|
+
constructor(code: ProtocolErrorCode, message: string);
|
|
7
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/** a reference to a record, resolved against the replica when a page renders */
|
|
2
|
+
export type RecordRef = {
|
|
3
|
+
$record: string;
|
|
4
|
+
};
|
|
5
|
+
/** a reference to a projection, resolved against the replica when a page renders */
|
|
6
|
+
export type ProjectionRef = {
|
|
7
|
+
$projection: string;
|
|
8
|
+
};
|
|
9
|
+
/** what a page's data carries in place of a record or projection stored once elsewhere */
|
|
10
|
+
export type Ref = RecordRef | ProjectionRef;
|
|
11
|
+
/** an authoritative piece of data, stored once by id; its id is the tag that invalidates it */
|
|
12
|
+
export type RecordEntry = {
|
|
13
|
+
id: string;
|
|
14
|
+
/** the vector cursor read before the record was built */
|
|
15
|
+
version: number;
|
|
16
|
+
data: unknown;
|
|
17
|
+
};
|
|
18
|
+
/** a value derived from records, shared by every page that references it */
|
|
19
|
+
export type ProjectionEntry = {
|
|
20
|
+
id: string;
|
|
21
|
+
version: number;
|
|
22
|
+
/** record ids the projection reads, directly or through other projections */
|
|
23
|
+
deps: string[];
|
|
24
|
+
/** a tree that may reference records and other projections */
|
|
25
|
+
data: unknown;
|
|
26
|
+
};
|
|
27
|
+
/** the id lists {@link collectRefs} found */
|
|
28
|
+
export type RefSet = {
|
|
29
|
+
records: string[];
|
|
30
|
+
projections: string[];
|
|
31
|
+
};
|
|
32
|
+
/** the reference to put in a page's data for record `id` */
|
|
33
|
+
export declare function recordRef(id: string): RecordRef;
|
|
34
|
+
/** the reference to put in a page's data for projection `id` */
|
|
35
|
+
export declare function projectionRef(id: string): ProjectionRef;
|
|
36
|
+
/** whether `value` is exactly a reference, with no other keys */
|
|
37
|
+
export declare function isRef(value: unknown): value is Ref;
|
|
38
|
+
/** every record and projection id referenced anywhere in `value`, sorted and unique */
|
|
39
|
+
export declare function collectRefs(value: unknown): RefSet;
|
|
40
|
+
/** where {@link resolveRefs} looks references up */
|
|
41
|
+
export type RefLookup = {
|
|
42
|
+
record(id: string): RecordEntry | undefined;
|
|
43
|
+
projection(id: string): ProjectionEntry | undefined;
|
|
44
|
+
};
|
|
45
|
+
/** the tree with every reference replaced by what it points at, or the first one that is missing */
|
|
46
|
+
export type Resolved = {
|
|
47
|
+
ok: true;
|
|
48
|
+
value: unknown;
|
|
49
|
+
} | {
|
|
50
|
+
ok: false;
|
|
51
|
+
reason: string;
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* Replaces every reference in `value` with the record's data or the projection's resolved tree.
|
|
55
|
+
* A record's data is taken as is. A missing id or a projection that reaches itself is a refusal,
|
|
56
|
+
* so a page is never rendered with a hole in it.
|
|
57
|
+
*/
|
|
58
|
+
export declare function resolveRefs(value: unknown, lookup: RefLookup): Resolved;
|
|
59
|
+
/** validates one record from an artifact response */
|
|
60
|
+
export declare function parseRecordEntry(value: unknown): RecordEntry;
|
|
61
|
+
/** validates one projection from an artifact response */
|
|
62
|
+
export declare function parseProjectionEntry(value: unknown): ProjectionEntry;
|
|
63
|
+
/** what a load registered, stamped with the vector cursor it was read at */
|
|
64
|
+
export type Collected = {
|
|
65
|
+
records: RecordEntry[];
|
|
66
|
+
projections: ProjectionEntry[];
|
|
67
|
+
/** every record id and projection dependency, for the artifact's own `deps` */
|
|
68
|
+
deps: string[];
|
|
69
|
+
};
|
|
70
|
+
/** what a route's `load` calls to put records and projections into a page's data */
|
|
71
|
+
export type Collector = {
|
|
72
|
+
record(id: string, data: unknown): RecordRef;
|
|
73
|
+
projection(id: string, data: unknown, deps?: readonly string[]): ProjectionRef;
|
|
74
|
+
/** everything registered so far; throws when a projection reaches an unregistered or cyclic one */
|
|
75
|
+
collect(version: number): Collected;
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* A collector for one load. Registering an id twice is allowed only with identical data, because
|
|
79
|
+
* a record is the entity itself and cannot differ between the pages that show it.
|
|
80
|
+
*/
|
|
81
|
+
export declare function createCollector(): Collector;
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
import { ProtocolError } from './errors.js';
|
|
2
|
+
/** the reference to put in a page's data for record `id` */
|
|
3
|
+
export function recordRef(id) {
|
|
4
|
+
return { $record: id };
|
|
5
|
+
}
|
|
6
|
+
/** the reference to put in a page's data for projection `id` */
|
|
7
|
+
export function projectionRef(id) {
|
|
8
|
+
return { $projection: id };
|
|
9
|
+
}
|
|
10
|
+
function isPlain(value) {
|
|
11
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
12
|
+
}
|
|
13
|
+
/** whether `value` is exactly a reference, with no other keys */
|
|
14
|
+
export function isRef(value) {
|
|
15
|
+
if (!isPlain(value))
|
|
16
|
+
return false;
|
|
17
|
+
const keys = Object.keys(value);
|
|
18
|
+
if (keys.length !== 1)
|
|
19
|
+
return false;
|
|
20
|
+
const key = keys[0];
|
|
21
|
+
return (key === '$record' || key === '$projection') && typeof value[key] === 'string';
|
|
22
|
+
}
|
|
23
|
+
/** every record and projection id referenced anywhere in `value`, sorted and unique */
|
|
24
|
+
export function collectRefs(value) {
|
|
25
|
+
const records = new Set();
|
|
26
|
+
const projections = new Set();
|
|
27
|
+
const walk = (node) => {
|
|
28
|
+
if (Array.isArray(node))
|
|
29
|
+
return node.forEach(walk);
|
|
30
|
+
if (!isPlain(node))
|
|
31
|
+
return;
|
|
32
|
+
if (isRef(node)) {
|
|
33
|
+
if ('$record' in node)
|
|
34
|
+
records.add(node.$record);
|
|
35
|
+
else
|
|
36
|
+
projections.add(node.$projection);
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
Object.values(node).forEach(walk);
|
|
40
|
+
};
|
|
41
|
+
walk(value);
|
|
42
|
+
return { records: [...records].sort(), projections: [...projections].sort() };
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Replaces every reference in `value` with the record's data or the projection's resolved tree.
|
|
46
|
+
* A record's data is taken as is. A missing id or a projection that reaches itself is a refusal,
|
|
47
|
+
* so a page is never rendered with a hole in it.
|
|
48
|
+
*/
|
|
49
|
+
export function resolveRefs(value, lookup) {
|
|
50
|
+
const walk = (node, path) => {
|
|
51
|
+
if (Array.isArray(node))
|
|
52
|
+
return node.map((item) => walk(item, path));
|
|
53
|
+
if (!isPlain(node))
|
|
54
|
+
return node;
|
|
55
|
+
if (isRef(node)) {
|
|
56
|
+
if ('$record' in node) {
|
|
57
|
+
const record = lookup.record(node.$record);
|
|
58
|
+
if (!record)
|
|
59
|
+
throw new Error(`record ${node.$record} is not stored`);
|
|
60
|
+
return record.data;
|
|
61
|
+
}
|
|
62
|
+
const id = node.$projection;
|
|
63
|
+
if (path.includes(id))
|
|
64
|
+
throw new Error(`projection ${id} reaches itself`);
|
|
65
|
+
const projection = lookup.projection(id);
|
|
66
|
+
if (!projection)
|
|
67
|
+
throw new Error(`projection ${id} is not stored`);
|
|
68
|
+
return walk(projection.data, [...path, id]);
|
|
69
|
+
}
|
|
70
|
+
return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, walk(v, path)]));
|
|
71
|
+
};
|
|
72
|
+
try {
|
|
73
|
+
return { ok: true, value: walk(value, []) };
|
|
74
|
+
}
|
|
75
|
+
catch (error) {
|
|
76
|
+
return {
|
|
77
|
+
ok: false,
|
|
78
|
+
reason: error instanceof Error ? error.message : 'unresolved reference'
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
function bad(message) {
|
|
83
|
+
throw new ProtocolError('bad-artifact', message);
|
|
84
|
+
}
|
|
85
|
+
function version(value, field) {
|
|
86
|
+
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
|
|
87
|
+
return bad(`${field} version must be a non-negative integer`);
|
|
88
|
+
}
|
|
89
|
+
return value;
|
|
90
|
+
}
|
|
91
|
+
/** validates one record from an artifact response */
|
|
92
|
+
export function parseRecordEntry(value) {
|
|
93
|
+
if (!isPlain(value))
|
|
94
|
+
return bad('record must be an object');
|
|
95
|
+
if (typeof value['id'] !== 'string' || value['id'] === '')
|
|
96
|
+
return bad('record id');
|
|
97
|
+
if (!('data' in value))
|
|
98
|
+
return bad(`record ${value['id']} needs data`);
|
|
99
|
+
return { id: value['id'], version: version(value['version'], 'record'), data: value['data'] };
|
|
100
|
+
}
|
|
101
|
+
/** validates one projection from an artifact response */
|
|
102
|
+
export function parseProjectionEntry(value) {
|
|
103
|
+
if (!isPlain(value))
|
|
104
|
+
return bad('projection must be an object');
|
|
105
|
+
const { id, deps } = value;
|
|
106
|
+
if (typeof id !== 'string' || id === '')
|
|
107
|
+
return bad('projection id');
|
|
108
|
+
if (!Array.isArray(deps) || deps.some((d) => typeof d !== 'string')) {
|
|
109
|
+
return bad(`projection ${id} deps must be a list of strings`);
|
|
110
|
+
}
|
|
111
|
+
if (!('data' in value))
|
|
112
|
+
return bad(`projection ${id} needs data`);
|
|
113
|
+
return {
|
|
114
|
+
id,
|
|
115
|
+
version: version(value['version'], 'projection'),
|
|
116
|
+
deps: deps,
|
|
117
|
+
data: value['data']
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* A collector for one load. Registering an id twice is allowed only with identical data, because
|
|
122
|
+
* a record is the entity itself and cannot differ between the pages that show it.
|
|
123
|
+
*/
|
|
124
|
+
export function createCollector() {
|
|
125
|
+
const records = new Map();
|
|
126
|
+
const recordData = new Map();
|
|
127
|
+
const projections = new Map();
|
|
128
|
+
const checkId = (kind, id) => {
|
|
129
|
+
if (typeof id !== 'string' || id === '')
|
|
130
|
+
bad(`${kind} id must be a non-empty string`);
|
|
131
|
+
};
|
|
132
|
+
const text = (kind, id, data) => {
|
|
133
|
+
const json = JSON.stringify(data);
|
|
134
|
+
if (json === undefined)
|
|
135
|
+
bad(`${kind} ${id} data is not JSON`);
|
|
136
|
+
return json;
|
|
137
|
+
};
|
|
138
|
+
return {
|
|
139
|
+
record(id, data) {
|
|
140
|
+
checkId('record', id);
|
|
141
|
+
const json = text('record', id, data);
|
|
142
|
+
const prior = records.get(id);
|
|
143
|
+
if (prior !== undefined && prior !== json) {
|
|
144
|
+
bad(`record ${id} registered twice with different data`);
|
|
145
|
+
}
|
|
146
|
+
records.set(id, json);
|
|
147
|
+
recordData.set(id, data);
|
|
148
|
+
return recordRef(id);
|
|
149
|
+
},
|
|
150
|
+
projection(id, data, deps = []) {
|
|
151
|
+
checkId('projection', id);
|
|
152
|
+
const json = text('projection', id, data);
|
|
153
|
+
const prior = projections.get(id);
|
|
154
|
+
if (prior !== undefined && prior.text !== json) {
|
|
155
|
+
bad(`projection ${id} registered twice with different data`);
|
|
156
|
+
}
|
|
157
|
+
projections.set(id, { data, deps, text: json });
|
|
158
|
+
return projectionRef(id);
|
|
159
|
+
},
|
|
160
|
+
collect(vector) {
|
|
161
|
+
const closure = (id, path) => {
|
|
162
|
+
if (path.includes(id))
|
|
163
|
+
return bad(`projection ${id} reaches itself`);
|
|
164
|
+
const entry = projections.get(id);
|
|
165
|
+
if (!entry)
|
|
166
|
+
return bad(`projection ${id} is referenced but never registered`);
|
|
167
|
+
const refs = collectRefs(entry.data);
|
|
168
|
+
const out = new Set(entry.deps);
|
|
169
|
+
for (const record of refs.records) {
|
|
170
|
+
if (!records.has(record))
|
|
171
|
+
bad(`record ${record} is referenced but never registered`);
|
|
172
|
+
out.add(record);
|
|
173
|
+
}
|
|
174
|
+
for (const child of refs.projections) {
|
|
175
|
+
for (const dep of closure(child, [...path, id]))
|
|
176
|
+
out.add(dep);
|
|
177
|
+
}
|
|
178
|
+
return out;
|
|
179
|
+
};
|
|
180
|
+
const deps = new Set(records.keys());
|
|
181
|
+
const entries = [...projections.keys()].sort().map((id) => {
|
|
182
|
+
const reads = [...closure(id, [])].sort();
|
|
183
|
+
for (const dep of reads)
|
|
184
|
+
deps.add(dep);
|
|
185
|
+
return {
|
|
186
|
+
id,
|
|
187
|
+
version: vector,
|
|
188
|
+
deps: reads,
|
|
189
|
+
data: projections.get(id).data
|
|
190
|
+
};
|
|
191
|
+
});
|
|
192
|
+
return {
|
|
193
|
+
records: [...recordData.keys()]
|
|
194
|
+
.sort()
|
|
195
|
+
.map((id) => ({ id, version: vector, data: recordData.get(id) })),
|
|
196
|
+
projections: entries,
|
|
197
|
+
deps: [...deps].sort()
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
};
|
|
201
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export * from './artifact.js';
|
|
2
|
+
export * from './assembly.js';
|
|
3
|
+
export * from './beacon.js';
|
|
4
|
+
export * from './collector.js';
|
|
5
|
+
export * from './config.js';
|
|
6
|
+
export * from './envelope.js';
|
|
7
|
+
export * from './errors.js';
|
|
8
|
+
export * from './graph.js';
|
|
9
|
+
export * from './manifest.js';
|
|
10
|
+
export * from './normalise.js';
|
|
11
|
+
export * from './pattern.js';
|
|
12
|
+
export * from './provision.js';
|
|
13
|
+
export * from './route.js';
|
|
14
|
+
export * from './sync.js';
|
|
15
|
+
export * from './tag.js';
|
|
16
|
+
export * from './template/compile.js';
|
|
17
|
+
export * from './template/interpret.js';
|
|
18
|
+
export * from './vector.js';
|
|
19
|
+
export * from './view.js';
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export * from './artifact.js';
|
|
2
|
+
export * from './assembly.js';
|
|
3
|
+
export * from './beacon.js';
|
|
4
|
+
export * from './collector.js';
|
|
5
|
+
export * from './config.js';
|
|
6
|
+
export * from './envelope.js';
|
|
7
|
+
export * from './errors.js';
|
|
8
|
+
export * from './graph.js';
|
|
9
|
+
export * from './manifest.js';
|
|
10
|
+
export * from './normalise.js';
|
|
11
|
+
export * from './pattern.js';
|
|
12
|
+
export * from './provision.js';
|
|
13
|
+
export * from './route.js';
|
|
14
|
+
export * from './sync.js';
|
|
15
|
+
export * from './tag.js';
|
|
16
|
+
export * from './template/compile.js';
|
|
17
|
+
export * from './template/interpret.js';
|
|
18
|
+
export * from './vector.js';
|
|
19
|
+
export * from './view.js';
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type Freshness, type OfflineRule, type SerializedRoute, type SyncRule } from './route.js';
|
|
2
|
+
/** the schema number a `spool.json` carries */
|
|
3
|
+
export declare const MANIFEST_SCHEMA = 1;
|
|
4
|
+
/** longest `version` a manifest route may carry */
|
|
5
|
+
export declare const MAX_VERSION_CHARS = 256;
|
|
6
|
+
/** one file a site serves as is and the worker may keep */
|
|
7
|
+
export type ManifestRoute = {
|
|
8
|
+
/** the path, or a `:name` pattern; every path a pattern matches shares the one version */
|
|
9
|
+
pattern: string;
|
|
10
|
+
strategy: 'static';
|
|
11
|
+
/**
|
|
12
|
+
* What the file is at now: a content hash (`sha256-<base64>`, also `sha384-` and `sha512-`),
|
|
13
|
+
* an entity tag (`"abc"`), or any label. A hash and a tag are checked against the bytes
|
|
14
|
+
* fetched; a label is trusted. A changed value drops the stored copy.
|
|
15
|
+
*/
|
|
16
|
+
version: string;
|
|
17
|
+
freshness?: Partial<Freshness>;
|
|
18
|
+
offline?: OfflineRule;
|
|
19
|
+
sync?: SyncRule;
|
|
20
|
+
};
|
|
21
|
+
/** the `spool.json` a static site serves beside `spool-sw.js` */
|
|
22
|
+
export type Manifest = {
|
|
23
|
+
schema: typeof MANIFEST_SCHEMA;
|
|
24
|
+
routes: ManifestRoute[];
|
|
25
|
+
};
|
|
26
|
+
/** validates the JSON of a `spool.json`; the worker calls this before it replaces its routes */
|
|
27
|
+
export declare function parseManifest(value: unknown): Manifest;
|
|
28
|
+
/** the worker's routes for a manifest, with the defaults of a public route filled in */
|
|
29
|
+
export declare function manifestRoutes(manifest: Manifest): SerializedRoute[];
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { ProtocolError } from './errors.js';
|
|
2
|
+
import { checkPattern } from './pattern.js';
|
|
3
|
+
import { DEFAULT_FRESHNESS } from './route.js';
|
|
4
|
+
/** the schema number a `spool.json` carries */
|
|
5
|
+
export const MANIFEST_SCHEMA = 1;
|
|
6
|
+
/** longest `version` a manifest route may carry */
|
|
7
|
+
export const MAX_VERSION_CHARS = 256;
|
|
8
|
+
function bad(message) {
|
|
9
|
+
throw new ProtocolError('bad-manifest', message);
|
|
10
|
+
}
|
|
11
|
+
function isRecord(value) {
|
|
12
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
13
|
+
}
|
|
14
|
+
function parseRoute(value, index) {
|
|
15
|
+
const where = `routes[${index}]`;
|
|
16
|
+
if (!isRecord(value))
|
|
17
|
+
return bad(`${where} must be an object`);
|
|
18
|
+
const { pattern, strategy, version, freshness, offline, sync } = value;
|
|
19
|
+
if (typeof pattern !== 'string')
|
|
20
|
+
return bad(`${where}.pattern must be a string`);
|
|
21
|
+
try {
|
|
22
|
+
checkPattern(pattern);
|
|
23
|
+
}
|
|
24
|
+
catch (error) {
|
|
25
|
+
return bad(`${where}: ${error instanceof Error ? error.message : 'bad pattern'}`);
|
|
26
|
+
}
|
|
27
|
+
if (strategy !== 'static')
|
|
28
|
+
return bad(`${pattern}: strategy must be "static"`);
|
|
29
|
+
if (typeof version !== 'string' || version === '' || version.length > MAX_VERSION_CHARS) {
|
|
30
|
+
return bad(`${pattern}: version must be a string of 1 to ${MAX_VERSION_CHARS} characters`);
|
|
31
|
+
}
|
|
32
|
+
const out = { pattern, strategy, version };
|
|
33
|
+
if (freshness !== undefined) {
|
|
34
|
+
if (!isRecord(freshness))
|
|
35
|
+
return bad(`${pattern}: freshness must be an object`);
|
|
36
|
+
const { maxStale, mode } = freshness;
|
|
37
|
+
if (maxStale !== undefined) {
|
|
38
|
+
if (typeof maxStale !== 'number' || !Number.isFinite(maxStale) || maxStale <= 0) {
|
|
39
|
+
return bad(`${pattern}: freshness.maxStale must be a positive number of seconds`);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
if (mode !== undefined && mode !== 'hard' && mode !== 'soft') {
|
|
43
|
+
return bad(`${pattern}: freshness.mode must be "hard" or "soft"`);
|
|
44
|
+
}
|
|
45
|
+
out.freshness = {
|
|
46
|
+
...(maxStale === undefined ? {} : { maxStale }),
|
|
47
|
+
...(mode === undefined ? {} : { mode })
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
if (offline !== undefined) {
|
|
51
|
+
if (offline !== 'serve' && offline !== 'refuse') {
|
|
52
|
+
return bad(`${pattern}: offline must be "serve" or "refuse"`);
|
|
53
|
+
}
|
|
54
|
+
out.offline = offline;
|
|
55
|
+
}
|
|
56
|
+
if (sync !== undefined) {
|
|
57
|
+
if (sync !== 'background' && sync !== 'deferred') {
|
|
58
|
+
return bad(`${pattern}: sync must be "background" or "deferred"`);
|
|
59
|
+
}
|
|
60
|
+
out.sync = sync;
|
|
61
|
+
}
|
|
62
|
+
return out;
|
|
63
|
+
}
|
|
64
|
+
/** validates the JSON of a `spool.json`; the worker calls this before it replaces its routes */
|
|
65
|
+
export function parseManifest(value) {
|
|
66
|
+
if (!isRecord(value))
|
|
67
|
+
return bad('manifest must be an object');
|
|
68
|
+
if (value['schema'] !== MANIFEST_SCHEMA)
|
|
69
|
+
return bad('unsupported manifest schema');
|
|
70
|
+
const { routes } = value;
|
|
71
|
+
if (!Array.isArray(routes))
|
|
72
|
+
return bad('routes must be a list');
|
|
73
|
+
const parsed = routes.map(parseRoute);
|
|
74
|
+
const seen = new Set();
|
|
75
|
+
for (const route of parsed) {
|
|
76
|
+
if (seen.has(route.pattern))
|
|
77
|
+
return bad(`${route.pattern}: declared twice`);
|
|
78
|
+
seen.add(route.pattern);
|
|
79
|
+
}
|
|
80
|
+
return { schema: MANIFEST_SCHEMA, routes: parsed };
|
|
81
|
+
}
|
|
82
|
+
/** the worker's routes for a manifest, with the defaults of a public route filled in */
|
|
83
|
+
export function manifestRoutes(manifest) {
|
|
84
|
+
return manifest.routes.map((route) => ({
|
|
85
|
+
pattern: route.pattern,
|
|
86
|
+
strategy: 'static',
|
|
87
|
+
scope: 'public',
|
|
88
|
+
freshness: { ...DEFAULT_FRESHNESS.public, ...route.freshness },
|
|
89
|
+
persist: true,
|
|
90
|
+
offline: route.offline ?? 'serve',
|
|
91
|
+
sync: route.sync ?? 'background',
|
|
92
|
+
version: route.version
|
|
93
|
+
}));
|
|
94
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** what to blank out before comparing; each pattern is replaced wherever it matches */
|
|
2
|
+
export type NormaliseOptions = {
|
|
3
|
+
ignore?: readonly RegExp[];
|
|
4
|
+
};
|
|
5
|
+
/**
|
|
6
|
+
* Reduces markup to what two renders of the same page must share: comments removed, runs of
|
|
7
|
+
* whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
|
|
8
|
+
* blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
|
|
9
|
+
*/
|
|
10
|
+
export declare function normalise(html: string, options?: NormaliseOptions): string;
|
|
11
|
+
/** the verdict of {@link equivalent}; a mismatch names where the two first differ */
|
|
12
|
+
export type Equivalence = {
|
|
13
|
+
equal: true;
|
|
14
|
+
} | {
|
|
15
|
+
equal: false;
|
|
16
|
+
at: number;
|
|
17
|
+
reason: string;
|
|
18
|
+
};
|
|
19
|
+
/** whether two renders match after {@link normalise}; the reason quotes 80 characters of each */
|
|
20
|
+
export declare function equivalent(a: string, b: string, options?: NormaliseOptions): Equivalence;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
const IGNORED = '\u0000';
|
|
2
|
+
/**
|
|
3
|
+
* Reduces markup to what two renders of the same page must share: comments removed, runs of
|
|
4
|
+
* whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
|
|
5
|
+
* blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
|
|
6
|
+
*/
|
|
7
|
+
export function normalise(html, options = {}) {
|
|
8
|
+
let out = html.replace(/<!--[\s\S]*?-->/g, '');
|
|
9
|
+
for (const pattern of options.ignore ?? []) {
|
|
10
|
+
const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
|
|
11
|
+
out = out.replace(new RegExp(pattern.source, flags), IGNORED);
|
|
12
|
+
}
|
|
13
|
+
return out.replace(/\s+/g, ' ').replace(/>\s+</g, '><').trim();
|
|
14
|
+
}
|
|
15
|
+
/** whether two renders match after {@link normalise}; the reason quotes 80 characters of each */
|
|
16
|
+
export function equivalent(a, b, options = {}) {
|
|
17
|
+
const left = normalise(a, options);
|
|
18
|
+
const right = normalise(b, options);
|
|
19
|
+
if (left === right)
|
|
20
|
+
return { equal: true };
|
|
21
|
+
let at = 0;
|
|
22
|
+
while (at < left.length && left[at] === right[at])
|
|
23
|
+
at++;
|
|
24
|
+
return {
|
|
25
|
+
at,
|
|
26
|
+
equal: false,
|
|
27
|
+
reason: `diverges at ${at}: ${JSON.stringify(left.slice(at, at + 80))} vs ${JSON.stringify(right.slice(at, at + 80))}`
|
|
28
|
+
};
|
|
29
|
+
}
|