@drupflare/spool 0.0.0-stage → 0.2.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 +1749 -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/media/embeds.d.ts +59 -0
- package/dist/media/embeds.js +120 -0
- package/dist/media/headers.d.ts +13 -0
- package/dist/media/headers.js +44 -0
- package/dist/media/html.d.ts +27 -0
- package/dist/media/html.js +93 -0
- package/dist/media/image.d.ts +222 -0
- package/dist/media/image.js +413 -0
- package/dist/media/index.d.ts +6 -0
- package/dist/media/index.js +6 -0
- package/dist/media/lazy.d.ts +26 -0
- package/dist/media/lazy.js +74 -0
- package/dist/media/responsive.d.ts +45 -0
- package/dist/media/responsive.js +98 -0
- package/dist/media/video.d.ts +30 -0
- package/dist/media/video.js +75 -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/dictionary.d.ts +58 -0
- package/dist/proxy/dictionary.js +197 -0
- package/dist/proxy/eligible.d.ts +45 -0
- package/dist/proxy/eligible.js +96 -0
- package/dist/proxy/index.d.ts +5 -0
- package/dist/proxy/index.js +5 -0
- package/dist/proxy/proxy.d.ts +133 -0
- package/dist/proxy/proxy.js +507 -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 +223 -0
- package/dist/report/derive.js +494 -0
- package/dist/report/economics.d.ts +14 -0
- package/dist/report/economics.js +24 -0
- package/dist/report/index.d.ts +9 -0
- package/dist/report/index.js +9 -0
- package/dist/report/inputs.d.ts +141 -0
- package/dist/report/inputs.js +216 -0
- package/dist/report/ledger.d.ts +169 -0
- package/dist/report/ledger.js +278 -0
- package/dist/report/measurement.d.ts +48 -0
- package/dist/report/measurement.js +117 -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 +47 -0
- package/dist/trim/tokens.js +142 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +3 -0
- package/package.json +150 -5
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** the values a pattern captured, keyed by parameter name */
|
|
2
|
+
export type Params = Record<string, string>;
|
|
3
|
+
/**
|
|
4
|
+
* Validates a spool path pattern: `/a/:b/c`, where `:name` captures one whole segment, and a final
|
|
5
|
+
* `**` matches any number of segments after the prefix, none included. A trailing slash is ignored
|
|
6
|
+
* on both sides of a match.
|
|
7
|
+
*/
|
|
8
|
+
export declare function checkPattern(pattern: string): void;
|
|
9
|
+
/** the captured params when `path` fits `pattern`, otherwise null */
|
|
10
|
+
export declare function matchPattern(pattern: string, path: string): Params | null;
|
|
11
|
+
/** the path a pattern produces for `params`; the inverse of {@link matchPattern} */
|
|
12
|
+
export declare function fillPattern(pattern: string, params: Params): string;
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { ProtocolError } from './errors.js';
|
|
2
|
+
const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
3
|
+
function segments(path) {
|
|
4
|
+
const trimmed = path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
|
|
5
|
+
return trimmed === '/' ? [] : trimmed.slice(1).split('/');
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Validates a spool path pattern: `/a/:b/c`, where `:name` captures one whole segment, and a final
|
|
9
|
+
* `**` matches any number of segments after the prefix, none included. A trailing slash is ignored
|
|
10
|
+
* on both sides of a match.
|
|
11
|
+
*/
|
|
12
|
+
export function checkPattern(pattern) {
|
|
13
|
+
if (!pattern.startsWith('/')) {
|
|
14
|
+
throw new ProtocolError('bad-pattern', `pattern must start with "/": ${pattern}`);
|
|
15
|
+
}
|
|
16
|
+
const seen = new Set();
|
|
17
|
+
const parts = segments(pattern);
|
|
18
|
+
for (const [at, part] of parts.entries()) {
|
|
19
|
+
if (part === '')
|
|
20
|
+
throw new ProtocolError('bad-pattern', `empty segment in ${pattern}`);
|
|
21
|
+
if (part === '**') {
|
|
22
|
+
if (at !== parts.length - 1) {
|
|
23
|
+
throw new ProtocolError('bad-pattern', `"**" must be the last segment in ${pattern}`);
|
|
24
|
+
}
|
|
25
|
+
continue;
|
|
26
|
+
}
|
|
27
|
+
if (!part.startsWith(':'))
|
|
28
|
+
continue;
|
|
29
|
+
const name = part.slice(1);
|
|
30
|
+
if (!NAME.test(name)) {
|
|
31
|
+
throw new ProtocolError('bad-pattern', `bad parameter name "${name}" in ${pattern}`);
|
|
32
|
+
}
|
|
33
|
+
if (seen.has(name)) {
|
|
34
|
+
throw new ProtocolError('bad-pattern', `duplicate parameter "${name}" in ${pattern}`);
|
|
35
|
+
}
|
|
36
|
+
seen.add(name);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
/** the captured params when `path` fits `pattern`, otherwise null */
|
|
40
|
+
export function matchPattern(pattern, path) {
|
|
41
|
+
const want = segments(pattern);
|
|
42
|
+
const got = segments(path);
|
|
43
|
+
const rest = want[want.length - 1] === '**';
|
|
44
|
+
if (rest)
|
|
45
|
+
want.pop();
|
|
46
|
+
if (rest ? got.length < want.length : want.length !== got.length)
|
|
47
|
+
return null;
|
|
48
|
+
const params = {};
|
|
49
|
+
for (let i = 0; i < want.length; i++) {
|
|
50
|
+
const expected = want[i];
|
|
51
|
+
const actual = got[i];
|
|
52
|
+
if (expected.startsWith(':')) {
|
|
53
|
+
if (actual === '')
|
|
54
|
+
return null;
|
|
55
|
+
try {
|
|
56
|
+
params[expected.slice(1)] = decodeURIComponent(actual);
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
else if (expected !== actual)
|
|
63
|
+
return null;
|
|
64
|
+
}
|
|
65
|
+
return params;
|
|
66
|
+
}
|
|
67
|
+
/** the path a pattern produces for `params`; the inverse of {@link matchPattern} */
|
|
68
|
+
export function fillPattern(pattern, params) {
|
|
69
|
+
const parts = segments(pattern).map((part) => {
|
|
70
|
+
if (part === '**') {
|
|
71
|
+
throw new ProtocolError('bad-pattern', `${pattern} has no single path to fill`);
|
|
72
|
+
}
|
|
73
|
+
if (!part.startsWith(':'))
|
|
74
|
+
return part;
|
|
75
|
+
const value = params[part.slice(1)];
|
|
76
|
+
if (value === undefined) {
|
|
77
|
+
throw new ProtocolError('bad-pattern', `missing parameter "${part.slice(1)}" for ${pattern}`);
|
|
78
|
+
}
|
|
79
|
+
return encodeURIComponent(value);
|
|
80
|
+
});
|
|
81
|
+
return `/${parts.join('/')}`;
|
|
82
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import type { ProvisionConfig } from './config.js';
|
|
2
|
+
/** a cost in the two units the model keeps apart: bytes moved and requests made */
|
|
3
|
+
export type Cost = {
|
|
4
|
+
bytes: number;
|
|
5
|
+
requests: number;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* What the worker assumes until the server's telemetry sets it. All six are scenario priors
|
|
9
|
+
* (L3), not measurements; `avoidedBytes` is the median repeat-view document a local view replaces
|
|
10
|
+
* (`DOCUMENT_BYTES` in `src/report/inputs.ts`, L1).
|
|
11
|
+
*/
|
|
12
|
+
export type ProvisionPrior = {
|
|
13
|
+
/** P_reuse: the chance a provisioned artifact serves a later view */
|
|
14
|
+
reuse: number;
|
|
15
|
+
/** N_future: later views one provisioned artifact serves */
|
|
16
|
+
futureViews: number;
|
|
17
|
+
/** what one request weighs in bytes, so requests and bytes share a scale */
|
|
18
|
+
requestBytes: number;
|
|
19
|
+
/** size of one artifact before the worker has fetched any */
|
|
20
|
+
artifactBytes: number;
|
|
21
|
+
/** bytes one local view keeps off the wire */
|
|
22
|
+
avoidedBytes: number;
|
|
23
|
+
/** how often one dependency tag changes, per day, before the worker has seen any */
|
|
24
|
+
changesPerDay: number;
|
|
25
|
+
};
|
|
26
|
+
/** the defaults a config without `provision` gets */
|
|
27
|
+
export declare const DEFAULT_PRIOR: ProvisionPrior;
|
|
28
|
+
/** the prior with whatever the config overrides */
|
|
29
|
+
export declare function priorFrom(config: ProvisionConfig | undefined): ProvisionPrior;
|
|
30
|
+
/** a cost as one number: its bytes plus `requestBytes` for each request */
|
|
31
|
+
export declare function weigh(cost: Cost, requestBytes: number): number;
|
|
32
|
+
/** something the worker could fetch ahead of the visit that needs it */
|
|
33
|
+
export type Opportunity = {
|
|
34
|
+
id: string;
|
|
35
|
+
/** `layout`, `template` and `asset` are shared by many pages; `route` is a page the server calls hot; `expansion` is a page the user has not asked for yet */
|
|
36
|
+
kind: 'layout' | 'template' | 'asset' | 'route' | 'expansion';
|
|
37
|
+
/** what fetching it costs, once */
|
|
38
|
+
provision: Cost;
|
|
39
|
+
/** what keeping it current costs over its life; none when omitted */
|
|
40
|
+
maintain?: Cost;
|
|
41
|
+
/** what each view served from it keeps off the wire */
|
|
42
|
+
avoided: Cost;
|
|
43
|
+
/** overrides {@link ProvisionPrior.futureViews} */
|
|
44
|
+
futureViews?: number;
|
|
45
|
+
/** overrides {@link ProvisionPrior.reuse} */
|
|
46
|
+
reuse?: number;
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* `P_reuse x N_future x C_avoided - C_provision - C_maintain`, each cost weighed in bytes. A
|
|
50
|
+
* positive number means fetching it ahead moves fewer bytes and requests than leaving it to the
|
|
51
|
+
* network.
|
|
52
|
+
*/
|
|
53
|
+
export declare function benefit(opportunity: Opportunity, prior?: ProvisionPrior): number;
|
|
54
|
+
/** an opportunity with the benefit {@link benefit} gave it */
|
|
55
|
+
export type Planned = Opportunity & {
|
|
56
|
+
benefit: number;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* What to fetch, in order: shared layout, templates and immutable assets, then hot routes, then
|
|
60
|
+
* incremental expansion, each group by benefit with the id as tie-break. An opportunity whose
|
|
61
|
+
* benefit is not positive is left out.
|
|
62
|
+
*/
|
|
63
|
+
export declare function plan(opportunities: readonly Opportunity[], prior?: ProvisionPrior): Planned[];
|
|
64
|
+
/** joules to move one byte: SWD v4, 0.194 kWh/GB over decimal GB (L2) */
|
|
65
|
+
export declare const JOULES_PER_BYTE = 0.0006984;
|
|
66
|
+
/** joules of the origin request a local view avoids (L1, `ORIGIN_J.conventional` in `src/report/inputs.ts`) */
|
|
67
|
+
export declare const ORIGIN_JOULES = 0.455;
|
|
68
|
+
/** the default cap on one catalogue bundle, in compressed bytes */
|
|
69
|
+
export declare const DEFAULT_CATALOGUE_BYTES = 32768;
|
|
70
|
+
/**
|
|
71
|
+
* The share of devices that must open a catalogue entry for it to repay its transfer:
|
|
72
|
+
* `k*E / (k*D + o)`, with `E` the entry's compressed bytes and `D` the document it replaces. At 1
|
|
73
|
+
* or above the entry never pays.
|
|
74
|
+
*/
|
|
75
|
+
export declare function entryBreakEven(entryBytes: number, documentBytes: number): number;
|
|
76
|
+
/** a page a catalogue could carry the data of, with what the break-even rule needs to weigh it */
|
|
77
|
+
export type EntryCandidate = {
|
|
78
|
+
path: string;
|
|
79
|
+
/** the predicted share of devices that will open the page, 0 to 1 */
|
|
80
|
+
p: number;
|
|
81
|
+
/** compressed bytes of the entry */
|
|
82
|
+
entryBytes: number;
|
|
83
|
+
/** bytes of the document the entry replaces */
|
|
84
|
+
documentBytes: number;
|
|
85
|
+
};
|
|
86
|
+
/**
|
|
87
|
+
* The candidates worth shipping: those whose `p` is at least their break-even, best expected net
|
|
88
|
+
* first, kept while their entry bytes fit under `capBytes`. A candidate that does not fit is
|
|
89
|
+
* skipped and a smaller one may still go. A path is chosen once. A candidate with a `p` outside 0
|
|
90
|
+
* to 1 or a negative or non-finite size is never chosen.
|
|
91
|
+
*/
|
|
92
|
+
export declare function chooseEntries(candidates: readonly EntryCandidate[], options: {
|
|
93
|
+
capBytes: number;
|
|
94
|
+
}): EntryCandidate[];
|
|
95
|
+
/**
|
|
96
|
+
* P_reuse from aggregate telemetry: the share of a route's views that found a stored copy, pulled
|
|
97
|
+
* toward the prior by `weight` pseudo-views so a few views do not decide it. The telemetry
|
|
98
|
+
* has no device identity, so this is a share of views, not of provisioned copies.
|
|
99
|
+
*/
|
|
100
|
+
export declare function smoothReuse(warmViews: number, coldViews: number, prior?: ProvisionPrior, weight?: number): number;
|