@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.
Files changed (182) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1557 -2
  3. package/dist/cdn/client.js +1 -0
  4. package/dist/cdn/location.d.ts +11 -0
  5. package/dist/cdn/location.js +15 -0
  6. package/dist/cdn/manifest.json +16 -0
  7. package/dist/cdn/spool-sw.js +1 -0
  8. package/dist/client/entry.d.ts +1 -0
  9. package/dist/client/entry.js +25 -0
  10. package/dist/client/index.d.ts +3 -0
  11. package/dist/client/index.js +2 -0
  12. package/dist/client/lifecycle.d.ts +10 -0
  13. package/dist/client/lifecycle.js +10 -0
  14. package/dist/client/loads.d.ts +16 -0
  15. package/dist/client/loads.js +41 -0
  16. package/dist/client/register.d.ts +34 -0
  17. package/dist/client/register.js +58 -0
  18. package/dist/index.d.ts +2 -0
  19. package/dist/index.js +2 -0
  20. package/dist/node/listener.d.ts +19 -0
  21. package/dist/node/listener.js +76 -0
  22. package/dist/protocol/artifact.d.ts +54 -0
  23. package/dist/protocol/artifact.js +79 -0
  24. package/dist/protocol/assembly.d.ts +34 -0
  25. package/dist/protocol/assembly.js +72 -0
  26. package/dist/protocol/beacon.d.ts +59 -0
  27. package/dist/protocol/beacon.js +86 -0
  28. package/dist/protocol/collector.d.ts +41 -0
  29. package/dist/protocol/collector.js +84 -0
  30. package/dist/protocol/config.d.ts +89 -0
  31. package/dist/protocol/config.js +13 -0
  32. package/dist/protocol/envelope.d.ts +47 -0
  33. package/dist/protocol/envelope.js +162 -0
  34. package/dist/protocol/errors.d.ts +7 -0
  35. package/dist/protocol/errors.js +9 -0
  36. package/dist/protocol/graph.d.ts +81 -0
  37. package/dist/protocol/graph.js +201 -0
  38. package/dist/protocol/index.d.ts +19 -0
  39. package/dist/protocol/index.js +19 -0
  40. package/dist/protocol/manifest.d.ts +29 -0
  41. package/dist/protocol/manifest.js +94 -0
  42. package/dist/protocol/normalise.d.ts +20 -0
  43. package/dist/protocol/normalise.js +29 -0
  44. package/dist/protocol/pattern.d.ts +12 -0
  45. package/dist/protocol/pattern.js +82 -0
  46. package/dist/protocol/provision.d.ts +100 -0
  47. package/dist/protocol/provision.js +105 -0
  48. package/dist/protocol/route.d.ts +179 -0
  49. package/dist/protocol/route.js +135 -0
  50. package/dist/protocol/sync.d.ts +31 -0
  51. package/dist/protocol/sync.js +87 -0
  52. package/dist/protocol/tag.d.ts +12 -0
  53. package/dist/protocol/tag.js +26 -0
  54. package/dist/protocol/template/compile.d.ts +35 -0
  55. package/dist/protocol/template/compile.js +82 -0
  56. package/dist/protocol/template/interpret.d.ts +9 -0
  57. package/dist/protocol/template/interpret.js +82 -0
  58. package/dist/protocol/vector.d.ts +32 -0
  59. package/dist/protocol/vector.js +56 -0
  60. package/dist/protocol/view.d.ts +110 -0
  61. package/dist/protocol/view.js +201 -0
  62. package/dist/proxy/eligible.d.ts +45 -0
  63. package/dist/proxy/eligible.js +96 -0
  64. package/dist/proxy/index.d.ts +4 -0
  65. package/dist/proxy/index.js +4 -0
  66. package/dist/proxy/proxy.d.ts +86 -0
  67. package/dist/proxy/proxy.js +388 -0
  68. package/dist/proxy/purge.d.ts +10 -0
  69. package/dist/proxy/purge.js +66 -0
  70. package/dist/proxy/tags.d.ts +8 -0
  71. package/dist/proxy/tags.js +36 -0
  72. package/dist/report/derive.d.ts +221 -0
  73. package/dist/report/derive.js +490 -0
  74. package/dist/report/economics.d.ts +14 -0
  75. package/dist/report/economics.js +24 -0
  76. package/dist/report/index.d.ts +8 -0
  77. package/dist/report/index.js +8 -0
  78. package/dist/report/inputs.d.ts +141 -0
  79. package/dist/report/inputs.js +216 -0
  80. package/dist/report/measurement.d.ts +48 -0
  81. package/dist/report/measurement.js +114 -0
  82. package/dist/report/model.d.ts +42 -0
  83. package/dist/report/model.js +74 -0
  84. package/dist/report/thirdparty.d.ts +62 -0
  85. package/dist/report/thirdparty.js +107 -0
  86. package/dist/report/traffic.d.ts +140 -0
  87. package/dist/report/traffic.js +228 -0
  88. package/dist/report/trim.d.ts +81 -0
  89. package/dist/report/trim.js +105 -0
  90. package/dist/server/beacon.d.ts +20 -0
  91. package/dist/server/beacon.js +47 -0
  92. package/dist/server/embedded.d.ts +6 -0
  93. package/dist/server/embedded.js +6 -0
  94. package/dist/server/ga4.d.ts +70 -0
  95. package/dist/server/ga4.js +165 -0
  96. package/dist/server/identity.d.ts +12 -0
  97. package/dist/server/identity.js +17 -0
  98. package/dist/server/index.d.ts +7 -0
  99. package/dist/server/index.js +7 -0
  100. package/dist/server/sink.d.ts +56 -0
  101. package/dist/server/sink.js +133 -0
  102. package/dist/server/size.d.ts +7 -0
  103. package/dist/server/size.js +18 -0
  104. package/dist/server/spool.d.ts +97 -0
  105. package/dist/server/spool.js +463 -0
  106. package/dist/server/stub.d.ts +9 -0
  107. package/dist/server/stub.js +19 -0
  108. package/dist/server/sync.d.ts +12 -0
  109. package/dist/server/sync.js +48 -0
  110. package/dist/server/work.d.ts +22 -0
  111. package/dist/server/work.js +30 -0
  112. package/dist/stores/durable-object.d.ts +19 -0
  113. package/dist/stores/durable-object.js +53 -0
  114. package/dist/stores/index.d.ts +2 -0
  115. package/dist/stores/index.js +2 -0
  116. package/dist/stores/memory.d.ts +4 -0
  117. package/dist/stores/memory.js +10 -0
  118. package/dist/stores/version-store.d.ts +11 -0
  119. package/dist/stores/version-store.js +1 -0
  120. package/dist/sw/analytics.d.ts +81 -0
  121. package/dist/sw/analytics.js +275 -0
  122. package/dist/sw/collect.d.ts +8 -0
  123. package/dist/sw/collect.js +33 -0
  124. package/dist/sw/core.d.ts +1 -0
  125. package/dist/sw/core.js +3 -0
  126. package/dist/sw/freshness.d.ts +15 -0
  127. package/dist/sw/freshness.js +20 -0
  128. package/dist/sw/graph/index.d.ts +67 -0
  129. package/dist/sw/graph/index.js +170 -0
  130. package/dist/sw/graph/invalidate.d.ts +23 -0
  131. package/dist/sw/graph/invalidate.js +109 -0
  132. package/dist/sw/graph/projections.d.ts +7 -0
  133. package/dist/sw/graph/projections.js +9 -0
  134. package/dist/sw/graph/records.d.ts +7 -0
  135. package/dist/sw/graph/records.js +9 -0
  136. package/dist/sw/graph/store.d.ts +32 -0
  137. package/dist/sw/graph/store.js +52 -0
  138. package/dist/sw/idb.d.ts +8 -0
  139. package/dist/sw/idb.js +117 -0
  140. package/dist/sw/index.d.ts +2 -0
  141. package/dist/sw/index.js +1 -0
  142. package/dist/sw/partition.d.ts +21 -0
  143. package/dist/sw/partition.js +137 -0
  144. package/dist/sw/policy.d.ts +8 -0
  145. package/dist/sw/policy.js +24 -0
  146. package/dist/sw/provision.d.ts +39 -0
  147. package/dist/sw/provision.js +61 -0
  148. package/dist/sw/render.d.ts +21 -0
  149. package/dist/sw/render.js +53 -0
  150. package/dist/sw/replica.d.ts +77 -0
  151. package/dist/sw/replica.js +299 -0
  152. package/dist/sw/router.d.ts +42 -0
  153. package/dist/sw/router.js +48 -0
  154. package/dist/sw/routing.d.ts +23 -0
  155. package/dist/sw/routing.js +48 -0
  156. package/dist/sw/runtime.d.ts +112 -0
  157. package/dist/sw/runtime.js +1070 -0
  158. package/dist/sw/scheduler.d.ts +83 -0
  159. package/dist/sw/scheduler.js +149 -0
  160. package/dist/sw/seal.d.ts +37 -0
  161. package/dist/sw/seal.js +183 -0
  162. package/dist/sw/serve.d.ts +15 -0
  163. package/dist/sw/serve.js +63 -0
  164. package/dist/sw/shadow.d.ts +16 -0
  165. package/dist/sw/shadow.js +27 -0
  166. package/dist/sw/static.d.ts +17 -0
  167. package/dist/sw/static.js +81 -0
  168. package/dist/sw/storage.d.ts +64 -0
  169. package/dist/sw/storage.js +34 -0
  170. package/dist/sw/thirdparty.d.ts +17 -0
  171. package/dist/sw/thirdparty.js +36 -0
  172. package/dist/trim/css.d.ts +38 -0
  173. package/dist/trim/css.js +328 -0
  174. package/dist/trim/index.d.ts +3 -0
  175. package/dist/trim/index.js +3 -0
  176. package/dist/trim/manifest.d.ts +67 -0
  177. package/dist/trim/manifest.js +134 -0
  178. package/dist/trim/tokens.d.ts +43 -0
  179. package/dist/trim/tokens.js +142 -0
  180. package/dist/version.d.ts +2 -0
  181. package/dist/version.js +3 -0
  182. package/package.json +146 -5
@@ -0,0 +1,463 @@
1
+ import { cdnClientUrl } from '../cdn/location.js';
2
+ import { parseArtifact, PROTOCOL_VERSION } from '../protocol/artifact.js';
3
+ import { checkCollectors } from '../protocol/collector.js';
4
+ import { clientPath, PATHS, SPOOL_PREFIX } from '../protocol/config.js';
5
+ import { HEADERS, writeEnvelope } from '../protocol/envelope.js';
6
+ import { ProtocolError } from '../protocol/errors.js';
7
+ import { collectRefs, createCollector } from '../protocol/graph.js';
8
+ import { checkPattern } from '../protocol/pattern.js';
9
+ import { benefit, chooseEntries, DEFAULT_CATALOGUE_BYTES, priorFrom } from '../protocol/provision.js';
10
+ import { matchRoute, serializeRoute } from '../protocol/route.js';
11
+ import { artifactTag, MAX_HAVE, parseHeld } from '../protocol/sync.js';
12
+ import { clientTag, injectClientTag } from '../protocol/tag.js';
13
+ import { VERSION } from '../version.js';
14
+ import { respondBeacon } from './beacon.js';
15
+ import { CLIENT_CORE } from './embedded.js';
16
+ import { partitionId } from './identity.js';
17
+ import { compressedSize } from './size.js';
18
+ import { workerResponse, workerScript } from './stub.js';
19
+ import { json, respondSync } from './sync.js';
20
+ /** most changed tags a response carries inline before the worker is left to ask `/.spool/sync` */
21
+ export const MAX_PIGGYBACK = 32;
22
+ /** most pages one catalogue request makes the server build, whatever its route suggests */
23
+ export const MAX_CATALOGUE_BUILD = 32;
24
+ /** the strategies whose artifact is data for a template or projection the device already holds */
25
+ const ENTRY_STRATEGIES = ['template', 'projection', 'data'];
26
+ function isHtml(response) {
27
+ return (response.headers.get('content-type') ?? '').toLowerCase().includes('text/html');
28
+ }
29
+ /** wires routes, a version store and the endpoints into one handler set */
30
+ export function createSpool(options) {
31
+ const { store, sink } = options;
32
+ const routes = [...options.routes];
33
+ const seen = new Set();
34
+ for (const route of routes) {
35
+ if (seen.has(route.pattern)) {
36
+ throw new ProtocolError('bad-route', `${route.pattern}: declared twice`);
37
+ }
38
+ seen.add(route.pattern);
39
+ }
40
+ const mode = options.mode ?? 'serve';
41
+ if (mode !== 'serve' && mode !== 'shadow') {
42
+ throw new ProtocolError('bad-route', `unknown mode "${String(mode)}"`);
43
+ }
44
+ const shadowSample = options.shadowSample ?? 0;
45
+ if (!(shadowSample >= 0 && shadowSample <= 1)) {
46
+ throw new ProtocolError('bad-route', 'shadowSample must be between 0 and 1');
47
+ }
48
+ const { work } = options;
49
+ const meter = options.meter ?? (() => performance.now());
50
+ const beacons = [...(options.beacons ?? [])];
51
+ for (const path of beacons) {
52
+ if (!path.startsWith('/') || path.startsWith(SPOOL_PREFIX)) {
53
+ throw new ProtocolError('bad-route', `beacon path ${path} must be outside ${SPOOL_PREFIX}`);
54
+ }
55
+ }
56
+ const logout = [...(options.logout ?? [])];
57
+ for (const path of logout) {
58
+ checkPattern(path);
59
+ if (path.startsWith(SPOOL_PREFIX)) {
60
+ throw new ProtocolError('bad-route', `logout path ${path} must be outside ${SPOOL_PREFIX}`);
61
+ }
62
+ }
63
+ const collectors = [...(options.collectors ?? [])];
64
+ checkCollectors(collectors);
65
+ const prior = priorFrom(options.provision);
66
+ const catalogueBytes = options.catalogueBytes ?? DEFAULT_CATALOGUE_BYTES;
67
+ if (!(Number.isFinite(catalogueBytes) && catalogueBytes >= 0)) {
68
+ throw new ProtocolError('bad-route', 'catalogueBytes must be a non-negative number');
69
+ }
70
+ const measure = options.catalogueSize ?? compressedSize;
71
+ const config = {
72
+ protocol: PROTOCOL_VERSION,
73
+ version: VERSION,
74
+ routes: routes.map(serializeRoute),
75
+ templates: Object.fromEntries(routes.flatMap((r) => (r.template ? [[r.pattern, r.template]] : []))),
76
+ beacons,
77
+ mode,
78
+ shadowSample,
79
+ clientTag: clientTag(options.cdn
80
+ ? {
81
+ src: options.cdn.url ?? cdnClientUrl(VERSION),
82
+ integrity: options.cdn.integrity
83
+ }
84
+ : { src: clientPath(VERSION) })
85
+ };
86
+ if (options.provision)
87
+ config.provision = options.provision;
88
+ if (options.assets)
89
+ config.assets = options.assets;
90
+ if (logout.length > 0)
91
+ config.logout = logout;
92
+ if (collectors.length > 0)
93
+ config.collectors = collectors;
94
+ if (options.thirdParty)
95
+ config.thirdParty = options.thirdParty;
96
+ if (options.views === false)
97
+ config.views = false;
98
+ let script;
99
+ const stub = () => workerResponse((script ??= workerScript(config, options.worker)));
100
+ const who = async (request) => options.identity ? await options.identity.resolve(request) : null;
101
+ const context = (request, url, params, identity, collector = createCollector()) => ({
102
+ request,
103
+ url,
104
+ params,
105
+ identity,
106
+ record: collector.record,
107
+ projection: collector.projection
108
+ });
109
+ /** drops the records and projections the worker already holds at a version no change has passed */
110
+ async function trim(artifact, have) {
111
+ const held = Object.values(have);
112
+ if (held.length === 0)
113
+ return artifact;
114
+ const diff = await store.diff(Math.min(...held));
115
+ if (diff.reset)
116
+ return artifact;
117
+ const moved = (tags, version) => tags.some((tag) => (diff.changed[tag] ?? 0) > version);
118
+ const holds = (id, tags) => Object.hasOwn(have, id) && !moved(tags, have[id]);
119
+ const out = { ...artifact };
120
+ if (artifact.records) {
121
+ out.records = artifact.records.filter((r) => !holds(r.id, [r.id]));
122
+ }
123
+ if (artifact.projections) {
124
+ out.projections = artifact.projections.filter((p) => !holds(p.id, p.deps));
125
+ }
126
+ return out;
127
+ }
128
+ async function buildArtifact(request, url, path, have = {}, weighed = false) {
129
+ if (!path.startsWith('/'))
130
+ throw new ProtocolError('bad-artifact', 'path must start with "/"');
131
+ const hit = matchRoute(routes, path);
132
+ if (!hit)
133
+ return { response: json({ error: 'no route' }, 404) };
134
+ if (hit.route.strategy === 'static') {
135
+ return { response: json({ error: 'a static route is not provisioned' }, 404) };
136
+ }
137
+ const identity = await who(request);
138
+ if (hit.route.scope === 'principal' && !identity) {
139
+ return { response: json({ error: 'sign in' }, 401) };
140
+ }
141
+ const vector = await store.cursor();
142
+ const collector = createCollector();
143
+ const ctx = context(request, new URL(path, url), hit.params, identity, collector);
144
+ const dependsOn = [...(await hit.route.depends(ctx))];
145
+ const loaded = await hit.route.load(ctx);
146
+ const body = hit.route.strategy === 'assembly' ? loaded : { data: loaded };
147
+ const collected = collector.collect(vector);
148
+ const stored = new Set([...collected.records.map((r) => r.id)]);
149
+ const known = new Set(collected.projections.map((p) => p.id));
150
+ const refs = collectRefs(body);
151
+ for (const id of refs.records) {
152
+ if (!stored.has(id)) {
153
+ throw new ProtocolError('bad-artifact', `${path} references record ${id} it did not register`);
154
+ }
155
+ }
156
+ for (const id of refs.projections) {
157
+ if (!known.has(id)) {
158
+ throw new ProtocolError('bad-artifact', `${path} references projection ${id} it did not register`);
159
+ }
160
+ }
161
+ const artifact = parseArtifact({
162
+ protocol: PROTOCOL_VERSION,
163
+ id: path,
164
+ scope: hit.route.scope,
165
+ strategy: hit.route.strategy,
166
+ deps: [...new Set([...dependsOn, ...collected.deps])],
167
+ vector,
168
+ body,
169
+ ...(collected.records.length > 0 ? { records: collected.records } : {}),
170
+ ...(collected.projections.length > 0 ? { projections: collected.projections } : {})
171
+ });
172
+ const trimmed = await trim(artifact, have);
173
+ if (weighed && hit.route.scope === 'public') {
174
+ const bytes = new TextEncoder().encode(JSON.stringify(trimmed)).length;
175
+ const mine = { ...prior, ...hit.route.provision };
176
+ const data = hit.route.strategy === 'data';
177
+ const worth = benefit({
178
+ id: path,
179
+ kind: 'route',
180
+ provision: { bytes, requests: 1 },
181
+ avoided: { bytes: data ? bytes : prior.avoidedBytes, requests: 1 }
182
+ }, mine);
183
+ if (worth <= 0)
184
+ return { declined: true };
185
+ }
186
+ const out = { artifact: trimmed };
187
+ if (identity && hit.route.scope === 'principal') {
188
+ out.partition = await partitionId(options.identity.secret, identity.principal);
189
+ }
190
+ return out;
191
+ }
192
+ async function respondArtifact(request, url) {
193
+ const path = url.searchParams.get('path') ?? '';
194
+ const raw = url.searchParams.get('have');
195
+ const built = await buildArtifact(request, url, path, raw === null ? {} : parseHeld(raw, MAX_HAVE), true);
196
+ if ('response' in built)
197
+ return built.response;
198
+ if ('declined' in built) {
199
+ return new Response(null, {
200
+ status: 204,
201
+ headers: { 'cache-control': 'no-store', [HEADERS.provision]: 'declined' }
202
+ });
203
+ }
204
+ const headers = { [HEADERS.protocol]: String(PROTOCOL_VERSION) };
205
+ if (built.artifact.scope === 'principal') {
206
+ headers['cache-control'] = 'private, no-store';
207
+ if (built.partition)
208
+ headers[HEADERS.partition] = built.partition;
209
+ }
210
+ return json(built.artifact, 200, headers);
211
+ }
212
+ /** the public artifacts a beacon flush asked for, for the paths this server can build */
213
+ const provide = (request) => async (paths) => {
214
+ const out = [];
215
+ for (const path of paths) {
216
+ let built;
217
+ try {
218
+ built = await buildArtifact(new Request(request.url, { headers: { accept: 'application/json' } }), new URL(request.url), path, {}, true);
219
+ }
220
+ catch {
221
+ continue;
222
+ }
223
+ if ('artifact' in built && built.artifact.scope === 'public')
224
+ out.push(built.artifact);
225
+ }
226
+ return out;
227
+ };
228
+ /**
229
+ * The entries to send a device on `ask.path`: the data of pages that route's `catalogue` suggests,
230
+ * kept when the share expected to open one reaches its break-even and the bundle stays under
231
+ * `catalogueBytes`. A failure sends nothing, so it never turns a flush into an error.
232
+ */
233
+ const catalogue = (request) => async (ask) => {
234
+ const none = { artifacts: [] };
235
+ try {
236
+ const here = matchRoute(routes, ask.path);
237
+ if (!here?.route.catalogue)
238
+ return none;
239
+ const headers = new Headers(request.headers);
240
+ headers.delete('content-type');
241
+ headers.delete('content-length');
242
+ headers.set('accept', 'application/json');
243
+ const probe = new Request(request.url, { headers });
244
+ const identity = await who(probe);
245
+ if (here.route.scope === 'principal' && !identity)
246
+ return none;
247
+ const url = new URL(request.url);
248
+ const ctx = context(probe, new URL(ask.path, url), here.params, identity);
249
+ const guesses = [...(await here.route.catalogue(ctx))]
250
+ .filter((g) => typeof g.path === 'string' &&
251
+ g.path.startsWith('/') &&
252
+ !g.path.startsWith(SPOOL_PREFIX) &&
253
+ !/[?#]/.test(g.path) &&
254
+ g.path !== ask.path &&
255
+ typeof g.p === 'number' &&
256
+ g.p > 0 &&
257
+ g.p <= 1)
258
+ .sort((a, b) => b.p - a.p);
259
+ const built = new Map();
260
+ const pool = [];
261
+ let attempts = 0;
262
+ for (const guess of guesses) {
263
+ if (attempts >= MAX_CATALOGUE_BUILD)
264
+ break;
265
+ if (built.has(guess.path))
266
+ continue;
267
+ const target = matchRoute(routes, guess.path);
268
+ if (!target || !ENTRY_STRATEGIES.includes(target.route.strategy))
269
+ continue;
270
+ if (target.route.scope === 'principal' && !ask.sweep)
271
+ continue;
272
+ attempts += 1;
273
+ let result;
274
+ try {
275
+ result = await buildArtifact(probe, url, guess.path);
276
+ }
277
+ catch {
278
+ continue;
279
+ }
280
+ if (!('artifact' in result))
281
+ continue;
282
+ // ponytail: records two entries share are sized and sent once per entry, dedupe if bundles repeat them
283
+ const entryBytes = await measure(new TextEncoder().encode(JSON.stringify(result.artifact)));
284
+ const documentBytes = target.route.documentBytes ??
285
+ (target.route.strategy === 'data' ? entryBytes : prior.avoidedBytes);
286
+ built.set(guess.path, result);
287
+ pool.push({ path: guess.path, p: guess.p, entryBytes, documentBytes });
288
+ }
289
+ const chosen = chooseEntries(pool, { capBytes: catalogueBytes });
290
+ const entries = chosen.flatMap((c) => built.get(c.path) ?? []);
291
+ const partition = entries.find((e) => e.partition !== undefined)?.partition;
292
+ return {
293
+ artifacts: entries.map((e) => e.artifact),
294
+ ...(partition !== undefined ? { partition } : {})
295
+ };
296
+ }
297
+ catch {
298
+ return none;
299
+ }
300
+ };
301
+ async function respond(request) {
302
+ const url = new URL(request.url);
303
+ if (!url.pathname.startsWith(SPOOL_PREFIX))
304
+ return undefined;
305
+ const began = work ? meter() : 0;
306
+ try {
307
+ return await answer(request, url);
308
+ }
309
+ finally {
310
+ if (work) {
311
+ const known = Object.values(PATHS).includes(url.pathname);
312
+ work.record(known ? url.pathname : '/.spool/*', meter() - began);
313
+ }
314
+ }
315
+ }
316
+ async function answer(request, url) {
317
+ try {
318
+ const get = request.method === 'GET' || request.method === 'HEAD';
319
+ if (url.pathname === PATHS.sync && get) {
320
+ const identity = await who(request);
321
+ const partition = identity && options.identity
322
+ ? await partitionId(options.identity.secret, identity.principal)
323
+ : undefined;
324
+ return await respondSync(url, store, partition);
325
+ }
326
+ if (url.pathname === PATHS.artifact && get)
327
+ return await respondArtifact(request, url);
328
+ if (url.pathname === PATHS.beacon) {
329
+ return await respondBeacon(request, sink, provide(request), catalogue(request));
330
+ }
331
+ if (url.pathname === clientPath(VERSION) && get) {
332
+ return new Response(CLIENT_CORE, {
333
+ headers: {
334
+ 'content-type': 'text/javascript; charset=utf-8',
335
+ 'cache-control': 'public, max-age=31536000, immutable'
336
+ }
337
+ });
338
+ }
339
+ return json({ error: 'not found' }, 404);
340
+ }
341
+ catch (error) {
342
+ if (error instanceof ProtocolError)
343
+ return json({ error: error.message }, 400);
344
+ return json({ error: 'internal error' }, 500);
345
+ }
346
+ }
347
+ async function decorate(request, response, decorateOptions = {}) {
348
+ if (response.status === 101)
349
+ return response;
350
+ const url = new URL(request.url);
351
+ const headers = new Headers(response.headers);
352
+ const envelope = {};
353
+ const read = request.method === 'GET' || request.method === 'HEAD';
354
+ const before = decorateOptions.vector ?? (await store.cursor());
355
+ envelope.vector = before;
356
+ const seenHeader = request.headers.get(HEADERS.vectorSeen);
357
+ if (read && seenHeader !== null) {
358
+ headers.append('vary', HEADERS.vectorSeen);
359
+ const from = /^\d{1,15}$/.test(seenHeader) ? Number(seenHeader) : -1;
360
+ delete envelope.vector;
361
+ if (from >= 0) {
362
+ const diff = await store.diff(from);
363
+ const count = Object.keys(diff.changed).length;
364
+ if (diff.reset) {
365
+ envelope.clear = ['*'];
366
+ envelope.vector = diff.cursor;
367
+ envelope.seen = from;
368
+ }
369
+ else if (count <= MAX_PIGGYBACK) {
370
+ envelope.invalidate = diff.changed;
371
+ envelope.vector = diff.cursor;
372
+ envelope.seen = from;
373
+ }
374
+ }
375
+ }
376
+ else if (!read) {
377
+ const diff = await store.diff(before);
378
+ const count = Object.keys(diff.changed).length;
379
+ if (diff.reset || count > MAX_PIGGYBACK)
380
+ envelope.clear = ['*'];
381
+ else if (count > 0)
382
+ envelope.invalidate = diff.changed;
383
+ envelope.vector = diff.cursor;
384
+ }
385
+ if (decorateOptions.clear)
386
+ envelope.clear = [...decorateOptions.clear];
387
+ const identity = options.identity ? await who(request) : null;
388
+ if (identity && options.identity && !headers.has(HEADERS.partition)) {
389
+ envelope.partition = await partitionId(options.identity.secret, identity.principal);
390
+ }
391
+ const hit = read && response.status === 200 ? matchRoute(routes, url.pathname) : null;
392
+ if (hit) {
393
+ headers.set('x-spool-route', hit.route.pattern);
394
+ headers.set('x-spool-mode', hit.route.mode ?? mode);
395
+ }
396
+ const kept = hit?.route.strategy === 'static' || hit?.route.strategy === 'data' || isHtml(response);
397
+ if (hit && kept && (hit.route.scope === 'public' || identity)) {
398
+ const ctx = context(request, url, hit.params, identity);
399
+ envelope.artifact = {
400
+ id: url.pathname,
401
+ scope: hit.route.scope,
402
+ deps: [...(await hit.route.depends(ctx))],
403
+ version: before
404
+ };
405
+ }
406
+ writeEnvelope(headers, envelope);
407
+ if (decorateOptions.hardReset)
408
+ headers.set('clear-site-data', '"storage"');
409
+ const tag = request.method === 'GET' &&
410
+ response.status === 200 &&
411
+ isHtml(response) &&
412
+ !response.headers.has('content-encoding');
413
+ if (!tag) {
414
+ return new Response(response.body, {
415
+ status: response.status,
416
+ statusText: response.statusText,
417
+ headers
418
+ });
419
+ }
420
+ const html = await response.text();
421
+ const tagged = injectClientTag(html, config.clientTag);
422
+ if (tagged !== html) {
423
+ headers.delete('content-length');
424
+ const etag = headers.get('etag');
425
+ if (etag && !etag.startsWith('W/'))
426
+ headers.set('etag', `W/${etag}`);
427
+ }
428
+ return new Response(tagged, {
429
+ status: response.status,
430
+ statusText: response.statusText,
431
+ headers
432
+ });
433
+ }
434
+ return {
435
+ config,
436
+ stub,
437
+ partition: async (principal) => {
438
+ if (!options.identity) {
439
+ throw new ProtocolError('bad-route', 'partition needs an identity option');
440
+ }
441
+ return partitionId(options.identity.secret, principal);
442
+ },
443
+ respond,
444
+ decorate,
445
+ async handle(request, next) {
446
+ const early = await respond(request);
447
+ if (early)
448
+ return early;
449
+ const url = new URL(request.url);
450
+ if (url.pathname === PATHS.worker && request.method === 'GET')
451
+ return stub();
452
+ const began = work ? meter() : 0;
453
+ const vector = await store.cursor();
454
+ const response = await decorate(request, await next(request), { vector });
455
+ if (work) {
456
+ const hit = matchRoute(routes, url.pathname);
457
+ work.record(hit ? hit.route.pattern : 'other', meter() - began);
458
+ }
459
+ return response;
460
+ },
461
+ invalidate: (tags, invalidateOptions = {}) => store.bump([...tags, ...(invalidateOptions.drop ?? []).map(artifactTag)])
462
+ };
463
+ }
@@ -0,0 +1,9 @@
1
+ import type { SwConfig } from '../protocol/config.js';
2
+ /** the worker script: the config as data, then the shared core or the site's own bundle */
3
+ export declare function workerScript(config: SwConfig, core?: string): string;
4
+ /**
5
+ * The `/spool-sw.js` response. The script lives a day in the browser's cache, which is what lets
6
+ * a controlled navigation skip the update check; a deploy changes the bytes and is picked up
7
+ * within that bound.
8
+ */
9
+ export declare function workerResponse(script: string): Response;
@@ -0,0 +1,19 @@
1
+ import { SW_CORE } from './embedded.js';
2
+ /** the worker script: the config as data, then the shared core or the site's own bundle */
3
+ export function workerScript(config, core = SW_CORE) {
4
+ return `self.__SPOOL_CONFIG__=${JSON.stringify(config)};\n${core}`;
5
+ }
6
+ /**
7
+ * The `/spool-sw.js` response. The script lives a day in the browser's cache, which is what lets
8
+ * a controlled navigation skip the update check; a deploy changes the bytes and is picked up
9
+ * within that bound.
10
+ */
11
+ export function workerResponse(script) {
12
+ return new Response(script, {
13
+ headers: {
14
+ 'content-type': 'text/javascript; charset=utf-8',
15
+ 'cache-control': 'max-age=86400',
16
+ 'service-worker-allowed': '/'
17
+ }
18
+ });
19
+ }
@@ -0,0 +1,12 @@
1
+ import type { VersionStore } from '../stores/version-store.js';
2
+ /** a JSON response that no cache may keep */
3
+ export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
4
+ /**
5
+ * Answers `/.spool/sync`. With `from=<n>` it is every tag changed after `n` and the artifacts
6
+ * dropped. With `need=<id>@<version>,...` it is only those ids whose version moved past the one
7
+ * the worker holds, which is the invalid part of what the next page reads and nothing else.
8
+ * `partition` is the partition id of the request's identity, sent as `Spool-Partition`; a server
9
+ * with an identity option passes none for a request that resolves to nobody, and the worker reads
10
+ * that as a sign-out.
11
+ */
12
+ export declare function respondSync(url: URL, store: VersionStore, partition?: string): Promise<Response>;
@@ -0,0 +1,48 @@
1
+ import { HEADERS } from '../protocol/envelope.js';
2
+ import { ProtocolError } from '../protocol/errors.js';
3
+ import { MAX_NEED, parseHeld, toSyncResponse } from '../protocol/sync.js';
4
+ /** a JSON response that no cache may keep */
5
+ export function json(body, status = 200, headers = {}) {
6
+ return new Response(JSON.stringify(body), {
7
+ status,
8
+ headers: { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers }
9
+ });
10
+ }
11
+ async function respondNeed(held, store, headers) {
12
+ const versions = Object.values(held);
13
+ if (versions.length === 0) {
14
+ const cursor = await store.cursor();
15
+ return json({ ...toSyncResponse({ cursor, changed: {}, reset: false }), partial: true }, 200, {
16
+ ...headers,
17
+ [HEADERS.vector]: String(cursor)
18
+ });
19
+ }
20
+ const diff = await store.diff(Math.min(...versions));
21
+ const behind = Math.max(...versions) > diff.cursor;
22
+ const changed = behind
23
+ ? {}
24
+ : Object.fromEntries(Object.entries(diff.changed).filter(([tag, version]) => Object.hasOwn(held, tag) && version > held[tag]));
25
+ return json({ ...toSyncResponse({ cursor: diff.cursor, changed, reset: behind }), partial: true }, 200, { ...headers, [HEADERS.vector]: String(diff.cursor) });
26
+ }
27
+ /**
28
+ * Answers `/.spool/sync`. With `from=<n>` it is every tag changed after `n` and the artifacts
29
+ * dropped. With `need=<id>@<version>,...` it is only those ids whose version moved past the one
30
+ * the worker holds, which is the invalid part of what the next page reads and nothing else.
31
+ * `partition` is the partition id of the request's identity, sent as `Spool-Partition`; a server
32
+ * with an identity option passes none for a request that resolves to nobody, and the worker reads
33
+ * that as a sign-out.
34
+ */
35
+ export async function respondSync(url, store, partition) {
36
+ const headers = { [HEADERS.protocol]: '1' };
37
+ if (partition !== undefined)
38
+ headers[HEADERS.partition] = partition;
39
+ const need = url.searchParams.get('need');
40
+ if (need !== null)
41
+ return respondNeed(parseHeld(need, MAX_NEED), store, headers);
42
+ const raw = url.searchParams.get('from') ?? '';
43
+ if (!/^\d{1,15}$/.test(raw)) {
44
+ throw new ProtocolError('bad-sync', 'from must be a non-negative integer');
45
+ }
46
+ const diff = await store.diff(Number(raw));
47
+ return json(toSyncResponse(diff), 200, { ...headers, [HEADERS.vector]: String(diff.cursor) });
48
+ }
@@ -0,0 +1,22 @@
1
+ import type { WorkSample } from '../report/traffic.js';
2
+ /** the origin's work per interval, kept in memory; `samples()` is what `Z_peak_work` reads */
3
+ export type WorkSeries = {
4
+ /** adds one request that took `busyMs` on `route`; `at` is epoch milliseconds, now when omitted */
5
+ record(route: string, busyMs: number, at?: number): void;
6
+ /** every kept interval, oldest first, the open one included */
7
+ samples(): WorkSample[];
8
+ clear(): void;
9
+ };
10
+ /** what {@link workSeries} takes */
11
+ export type WorkSeriesOptions = {
12
+ /** length of one interval; default 60 */
13
+ intervalSeconds?: number;
14
+ /** most intervals kept before the oldest is dropped; default 1440, a day at 60 s */
15
+ keep?: number;
16
+ now?: () => number;
17
+ };
18
+ /**
19
+ * Buckets requests by time. Each isolate or process keeps its own series, so an app that runs
20
+ * more than one reads `samples()` from each and concatenates them.
21
+ */
22
+ export declare function workSeries(options?: WorkSeriesOptions): WorkSeries;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Buckets requests by time. Each isolate or process keeps its own series, so an app that runs
3
+ * more than one reads `samples()` from each and concatenates them.
4
+ */
5
+ export function workSeries(options = {}) {
6
+ const seconds = options.intervalSeconds ?? 60;
7
+ const keep = options.keep ?? 1440;
8
+ const now = options.now ?? Date.now;
9
+ const buckets = new Map();
10
+ return {
11
+ record(route, busyMs, at = now()) {
12
+ const start = Math.floor(at / (seconds * 1000)) * seconds * 1000;
13
+ let sample = buckets.get(start);
14
+ if (!sample) {
15
+ sample = { start, seconds, busyMs: {}, requests: {} };
16
+ buckets.set(start, sample);
17
+ if (buckets.size > keep) {
18
+ const oldest = Math.min(...buckets.keys());
19
+ buckets.delete(oldest);
20
+ }
21
+ }
22
+ sample.busyMs[route] = (sample.busyMs[route] ?? 0) + busyMs;
23
+ sample.requests[route] = (sample.requests[route] ?? 0) + 1;
24
+ },
25
+ samples: () => [...buckets.values()]
26
+ .sort((a, b) => a.start - b.start)
27
+ .map((s) => ({ ...s, busyMs: { ...s.busyMs }, requests: { ...s.requests } })),
28
+ clear: () => buckets.clear()
29
+ };
30
+ }
@@ -0,0 +1,19 @@
1
+ import { DurableObject } from 'cloudflare:workers';
2
+ import type { VectorDiff } from '../protocol/vector.js';
3
+ import type { VersionStore } from './version-store.js';
4
+ /**
5
+ * The version vector in a SQLite-backed Durable Object: one row per tag and one cursor row, so it
6
+ * survives eviction and restarts. Bind it as a Durable Object class and pass the namespace to
7
+ * {@link durableObjectStore}.
8
+ */
9
+ export declare class SpoolVersions extends DurableObject {
10
+ constructor(ctx: DurableObjectState, env: Cloudflare.Env);
11
+ /** records a change to `tags` and returns the new cursor */
12
+ bump(tags: string[]): number;
13
+ /** the cursor of the most recent bump */
14
+ cursor(): number;
15
+ /** every tag changed after `from`; see `VersionVector.diff` */
16
+ diff(from: number): VectorDiff;
17
+ }
18
+ /** a {@link VersionStore} over one named instance of the {@link SpoolVersions} namespace */
19
+ export declare function durableObjectStore(namespace: DurableObjectNamespace<SpoolVersions>, name?: string): VersionStore;