@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,79 @@
1
+ import { ProtocolError } from './errors.js';
2
+ import { isRef, parseProjectionEntry, parseRecordEntry } from './graph.js';
3
+ /** protocol version both halves speak; a response with another value is ignored by the worker */
4
+ export const PROTOCOL_VERSION = 1;
5
+ function bad(message) {
6
+ throw new ProtocolError('bad-artifact', message);
7
+ }
8
+ function isRecord(value) {
9
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
10
+ }
11
+ function textMap(value, field) {
12
+ if (value === undefined)
13
+ return undefined;
14
+ if (!isRecord(value))
15
+ return bad(`${field} must be an object`);
16
+ for (const v of Object.values(value)) {
17
+ if (typeof v !== 'string' && !isRef(v))
18
+ return bad(`${field} values must be strings or references`);
19
+ }
20
+ return value;
21
+ }
22
+ function entries(value, field, parse) {
23
+ if (value === undefined)
24
+ return undefined;
25
+ if (!Array.isArray(value))
26
+ return bad(`${field} must be a list`);
27
+ return value.map(parse);
28
+ }
29
+ /** validates JSON from `/.spool/artifact`; the worker calls this before it stores anything */
30
+ export function parseArtifact(value) {
31
+ if (!isRecord(value))
32
+ return bad('artifact must be an object');
33
+ if (value['protocol'] !== PROTOCOL_VERSION)
34
+ return bad('unsupported protocol version');
35
+ const { id, scope, deps, vector, strategy, body } = value;
36
+ if (typeof id !== 'string' || !id.startsWith('/'))
37
+ return bad('id must be a path');
38
+ if (scope !== 'public' && scope !== 'principal')
39
+ return bad('scope must be public or principal');
40
+ if (!Array.isArray(deps) || deps.some((d) => typeof d !== 'string')) {
41
+ return bad('deps must be a list of strings');
42
+ }
43
+ if (typeof vector !== 'number' || !Number.isSafeInteger(vector) || vector < 0) {
44
+ return bad('vector must be a non-negative integer');
45
+ }
46
+ if (!isRecord(body))
47
+ return bad('body must be an object');
48
+ const base = {
49
+ protocol: PROTOCOL_VERSION,
50
+ id,
51
+ scope,
52
+ deps: deps,
53
+ vector
54
+ };
55
+ const records = entries(value['records'], 'records', parseRecordEntry);
56
+ const projections = entries(value['projections'], 'projections', parseProjectionEntry);
57
+ if (records)
58
+ base.records = records;
59
+ if (projections)
60
+ base.projections = projections;
61
+ if (strategy === 'template' || strategy === 'projection' || strategy === 'data') {
62
+ if (!('data' in body))
63
+ return bad(`${strategy} body needs data`);
64
+ return { ...base, strategy, body: { data: body['data'] } };
65
+ }
66
+ if (strategy === 'assembly') {
67
+ if (typeof body['shell'] !== 'string')
68
+ return bad('assembly body needs a shell string');
69
+ const out = { shell: body['shell'] };
70
+ const fragments = textMap(body['fragments'], 'fragments');
71
+ const slots = textMap(body['slots'], 'slots');
72
+ if (fragments)
73
+ out.fragments = fragments;
74
+ if (slots)
75
+ out.slots = slots;
76
+ return { ...base, strategy, body: out };
77
+ }
78
+ return bad(`unknown strategy ${String(strategy)}`);
79
+ }
@@ -0,0 +1,34 @@
1
+ import type { AssemblyBody } from './artifact.js';
2
+ /** the markup a shell carries for a hole named `id`; `id` must not contain a double quote */
3
+ export declare function placeholder(id: string): string;
4
+ /** the token a shell carries for a named value */
5
+ export declare function slot(name: string): string;
6
+ /** every placeholder id in a shell, in document order */
7
+ export declare function placeholderIds(shell: string): string[];
8
+ /** every slot name in a shell, in document order */
9
+ export declare function slotNames(shell: string): string[];
10
+ /** what a fill produced and which names did not line up */
11
+ export type AssemblyResult = {
12
+ html: string;
13
+ filled: string[];
14
+ /** names the shell has that nothing answered */
15
+ unfilled: string[];
16
+ /** names supplied that the shell does not have */
17
+ unmatched: string[];
18
+ };
19
+ /**
20
+ * Fills a shell's placeholders with fragment markup by string replacement. An unfilled
21
+ * placeholder stays in place: dropping it would hide a region the shell and fragments disagree
22
+ * about.
23
+ */
24
+ export declare function assemble(shell: string, fragments: Readonly<Record<string, string>>): AssemblyResult;
25
+ /** fills a shell's slot tokens with named values; same contract as {@link assemble} */
26
+ export declare function fillSlots(shell: string, values: Readonly<Record<string, string>>): AssemblyResult;
27
+ /** the full page for an assembly body, or the reason it cannot be built locally */
28
+ export declare function renderAssembly(body: AssemblyBody): {
29
+ ok: true;
30
+ html: string;
31
+ } | {
32
+ ok: false;
33
+ reason: string;
34
+ };
@@ -0,0 +1,72 @@
1
+ const PLACEHOLDER = /<span data-spool-placeholder="([^"]*)"><\/span>/g;
2
+ const SLOT = /\{\{spool-slot:([A-Za-z0-9_.-]+)\}\}/g;
3
+ /** the markup a shell carries for a hole named `id`; `id` must not contain a double quote */
4
+ export function placeholder(id) {
5
+ return `<span data-spool-placeholder="${id}"></span>`;
6
+ }
7
+ /** the token a shell carries for a named value */
8
+ export function slot(name) {
9
+ return `{{spool-slot:${name}}}`;
10
+ }
11
+ /** every placeholder id in a shell, in document order */
12
+ export function placeholderIds(shell) {
13
+ return [...shell.matchAll(PLACEHOLDER)].map((m) => m[1]);
14
+ }
15
+ /** every slot name in a shell, in document order */
16
+ export function slotNames(shell) {
17
+ return [...shell.matchAll(SLOT)].map((m) => m[1]);
18
+ }
19
+ function fill(shell, pattern, values) {
20
+ const filled = [];
21
+ const unfilled = [];
22
+ const seen = new Set();
23
+ const html = shell.replace(pattern, (whole, id) => {
24
+ seen.add(id);
25
+ const value = Object.hasOwn(values, id) ? values[id] : undefined;
26
+ if (value === undefined) {
27
+ unfilled.push(id);
28
+ return whole;
29
+ }
30
+ filled.push(id);
31
+ return value;
32
+ });
33
+ const unmatched = Object.keys(values).filter((id) => !seen.has(id));
34
+ return { html, filled, unfilled, unmatched };
35
+ }
36
+ /**
37
+ * Fills a shell's placeholders with fragment markup by string replacement. An unfilled
38
+ * placeholder stays in place: dropping it would hide a region the shell and fragments disagree
39
+ * about.
40
+ */
41
+ export function assemble(shell, fragments) {
42
+ return fill(shell, PLACEHOLDER, fragments);
43
+ }
44
+ /** fills a shell's slot tokens with named values; same contract as {@link assemble} */
45
+ export function fillSlots(shell, values) {
46
+ return fill(shell, SLOT, values);
47
+ }
48
+ /** the full page for an assembly body, or the reason it cannot be built locally */
49
+ export function renderAssembly(body) {
50
+ const plain = (values) => {
51
+ const out = {};
52
+ for (const [name, value] of Object.entries(values ?? {})) {
53
+ if (typeof value !== 'string')
54
+ return null;
55
+ out[name] = value;
56
+ }
57
+ return out;
58
+ };
59
+ const fragmentText = plain(body.fragments);
60
+ const slotText = plain(body.slots);
61
+ if (!fragmentText || !slotText)
62
+ return { ok: false, reason: 'unresolved reference' };
63
+ const fragments = assemble(body.shell, fragmentText);
64
+ if (fragments.unfilled.length > 0) {
65
+ return { ok: false, reason: `unfilled placeholders: ${fragments.unfilled.join(', ')}` };
66
+ }
67
+ const slots = fillSlots(fragments.html, slotText);
68
+ if (slots.unfilled.length > 0) {
69
+ return { ok: false, reason: `unfilled slots: ${slots.unfilled.join(', ')}` };
70
+ }
71
+ return { ok: true, html: slots.html };
72
+ }
@@ -0,0 +1,59 @@
1
+ import { PROTOCOL_VERSION } from './artifact.js';
2
+ /**
3
+ * One request the worker held back: where it was going, what it carried and when it happened. A
4
+ * same-origin one leaves `origin` out. A request to another origin names it, with the `vendor`
5
+ * whose delay cap applies and, when `deliver` is `sink`, the server half forwards it.
6
+ */
7
+ export type BeaconEvent = {
8
+ path: string;
9
+ body: string;
10
+ contentType: string;
11
+ /** epoch milliseconds on the device */
12
+ at: number;
13
+ /** the query string of the original URL, with its leading `?` */
14
+ search?: string;
15
+ /** `GET` for a pixel beacon; absent means `POST` */
16
+ method?: 'GET';
17
+ /** the origin of a held cross-origin request; absent for the site's own */
18
+ origin?: string;
19
+ /** the collector entry that matched, which sets the age cap */
20
+ vendor?: string;
21
+ /** `sink` sends the event to the server half in the flush; absent, the worker replays it to its URL */
22
+ deliver?: 'sink';
23
+ /** epoch milliseconds after which the worker drops the event instead of sending it; never sent */
24
+ until?: number;
25
+ };
26
+ /**
27
+ * A flush's request for the catalogue of the page the visitor is on. `sweep` says the worker names
28
+ * the entries it holds and no page has opened at every required sync of a principal page, so a
29
+ * revoked one is dropped. The server sends principal entries only to a worker that says so.
30
+ */
31
+ export type CatalogueAsk = {
32
+ path: string;
33
+ sweep?: true;
34
+ };
35
+ /**
36
+ * The body of `/.spool/beacon`: every held request in one flush. `want` asks for the artifacts of
37
+ * these paths in the answer, so provisioning rides a request that is happening anyway, and
38
+ * `catalogue` asks for the entries a site suggests for the page the visitor is on.
39
+ */
40
+ export type BeaconBatch = {
41
+ protocol: typeof PROTOCOL_VERSION;
42
+ events: BeaconEvent[];
43
+ want?: string[];
44
+ catalogue?: CatalogueAsk;
45
+ };
46
+ /** most characters of the page path a catalogue request names */
47
+ export declare const MAX_CATALOGUE_PATH = 2048;
48
+ /** where the worker records events it dropped past a vendor's age cap; the body is `{vendor, count}` */
49
+ export declare const DROPPED_PATH = "/.spool/dropped";
50
+ /** the paths under `/.spool/` are spool's own and always travel in the flush */
51
+ export declare const OWN_PREFIX = "/.spool/";
52
+ /** the largest beacon body the worker holds or the server keeps in one event, in UTF-8 bytes */
53
+ export declare const MAX_BEACON_BYTES = 65536;
54
+ /** most events one flush may carry; the server refuses a larger batch */
55
+ export declare const MAX_BEACON_EVENTS = 500;
56
+ /** most artifact paths one flush may ask for */
57
+ export declare const MAX_WANT = 8;
58
+ /** validates a flush body */
59
+ export declare function parseBeaconBatch(value: unknown): BeaconBatch;
@@ -0,0 +1,86 @@
1
+ import { PROTOCOL_VERSION } from './artifact.js';
2
+ import { ProtocolError } from './errors.js';
3
+ /** most characters of the page path a catalogue request names */
4
+ export const MAX_CATALOGUE_PATH = 2048;
5
+ /** where the worker records events it dropped past a vendor's age cap; the body is `{vendor, count}` */
6
+ export const DROPPED_PATH = '/.spool/dropped';
7
+ /** the paths under `/.spool/` are spool's own and always travel in the flush */
8
+ export const OWN_PREFIX = '/.spool/';
9
+ /** the largest beacon body the worker holds or the server keeps in one event, in UTF-8 bytes */
10
+ export const MAX_BEACON_BYTES = 65_536;
11
+ /** most events one flush may carry; the server refuses a larger batch */
12
+ export const MAX_BEACON_EVENTS = 500;
13
+ /** most artifact paths one flush may ask for */
14
+ export const MAX_WANT = 8;
15
+ function bad(message) {
16
+ throw new ProtocolError('bad-beacon', message);
17
+ }
18
+ /** validates a flush body */
19
+ export function parseBeaconBatch(value) {
20
+ if (typeof value !== 'object' || value === null)
21
+ return bad('batch must be an object');
22
+ const v = value;
23
+ if (v['protocol'] !== PROTOCOL_VERSION)
24
+ return bad('unsupported protocol version');
25
+ if (!Array.isArray(v['events']))
26
+ return bad('events must be a list');
27
+ if (v['events'].length > MAX_BEACON_EVENTS)
28
+ return bad(`more than ${MAX_BEACON_EVENTS} events`);
29
+ const events = v['events'].map((raw) => {
30
+ const e = (raw ?? {});
31
+ if (typeof e['path'] !== 'string' || !e['path'].startsWith('/'))
32
+ return bad('event path');
33
+ if (typeof e['body'] !== 'string')
34
+ return bad('event body must be a string');
35
+ if (typeof e['contentType'] !== 'string')
36
+ return bad('event contentType must be a string');
37
+ if (typeof e['at'] !== 'number' || !Number.isFinite(e['at']))
38
+ return bad('event at');
39
+ const out = {
40
+ path: e['path'],
41
+ body: e['body'],
42
+ contentType: e['contentType'],
43
+ at: e['at']
44
+ };
45
+ for (const field of ['search', 'origin', 'vendor']) {
46
+ const value = e[field];
47
+ if (value === undefined)
48
+ continue;
49
+ if (typeof value !== 'string')
50
+ return bad(`event ${field} must be a string`);
51
+ out[field] = value;
52
+ }
53
+ if (e['method'] !== undefined) {
54
+ if (e['method'] !== 'GET')
55
+ return bad('event method must be GET');
56
+ out.method = 'GET';
57
+ }
58
+ if (e['deliver'] !== undefined) {
59
+ if (e['deliver'] !== 'sink')
60
+ return bad('event deliver must be sink');
61
+ out.deliver = 'sink';
62
+ }
63
+ return out;
64
+ });
65
+ const batch = { protocol: PROTOCOL_VERSION, events };
66
+ const want = v['want'];
67
+ if (want !== undefined) {
68
+ if (!Array.isArray(want) || want.length > MAX_WANT)
69
+ return bad(`want must be a list of at most ${MAX_WANT}`);
70
+ if (want.some((p) => typeof p !== 'string' || !p.startsWith('/')))
71
+ return bad('want paths');
72
+ batch.want = want;
73
+ }
74
+ const catalogue = v['catalogue'];
75
+ if (catalogue !== undefined) {
76
+ const ask = (catalogue ?? {});
77
+ const path = ask['path'];
78
+ if (typeof path !== 'string' || !path.startsWith('/') || path.length > MAX_CATALOGUE_PATH) {
79
+ return bad('catalogue path');
80
+ }
81
+ if (ask['sweep'] !== undefined && ask['sweep'] !== true)
82
+ return bad('catalogue sweep');
83
+ batch.catalogue = ask['sweep'] === true ? { path, sweep: true } : { path };
84
+ }
85
+ return batch;
86
+ }
@@ -0,0 +1,41 @@
1
+ /** how a replayed request carries the time the event happened */
2
+ export type StampKind = 'age-ms' | 'epoch-ms' | 'epoch-s' | 'datetime-utc';
3
+ /**
4
+ * A cross-origin analytics collector the worker holds instead of letting the page send it. The
5
+ * page gets an immediate empty answer; the event leaves on a network moment that happens anyway,
6
+ * inside `maxAgeMs`. Events older than that are dropped and counted, never sent late.
7
+ */
8
+ export type CollectorConfig = {
9
+ /** names the collector in drop counts and on the held event */
10
+ vendor: string;
11
+ /** the origin and path prefix of the collector's URL, such as `https://www.google-analytics.com/g/collect` */
12
+ match: string;
13
+ /** the vendor's backfill window less a margin, in milliseconds */
14
+ maxAgeMs: number;
15
+ /**
16
+ * `replay` sends the held request from the worker to its own URL with no cookies, so identity
17
+ * has to be in the payload. `sink` hands it to the server half in the flush, for a vendor that
18
+ * needs a secret the page must not hold.
19
+ */
20
+ delivery: 'replay' | 'sink';
21
+ /** a query parameter the replay sets to the event's time, for a vendor that accepts one */
22
+ stamp?: {
23
+ param: string;
24
+ kind: StampKind;
25
+ };
26
+ };
27
+ /** GA4 Measurement Protocol: backdating works up to 72 hours, and attribution wants 48 */
28
+ export declare const GA4_RECOMMENDED_MS: number;
29
+ /** the longest cap a `ga4` collector may declare */
30
+ export declare const GA4_HARD_MS: number;
31
+ /**
32
+ * The GA4 browser collector, forwarded through the server half because the Measurement Protocol
33
+ * needs an API secret the page must not hold. The cap is the 48-hour attribution window.
34
+ */
35
+ export declare const GA4_COLLECTOR: CollectorConfig;
36
+ /** validates collectors from a server config; a `ga4` cap past the 72-hour limit is refused */
37
+ export declare function checkCollectors(collectors: readonly CollectorConfig[]): void;
38
+ /** the collector whose `match` the URL falls under, or undefined */
39
+ export declare function matchCollector(collectors: readonly CollectorConfig[] | undefined, url: string): CollectorConfig | undefined;
40
+ /** `search` with the stamp parameter set to when the event happened, other parameters kept */
41
+ export declare function applyStamp(search: string, stamp: NonNullable<CollectorConfig['stamp']>, at: number, now: number): string;
@@ -0,0 +1,84 @@
1
+ import { ProtocolError } from './errors.js';
2
+ const HOUR = 3_600_000;
3
+ /** GA4 Measurement Protocol: backdating works up to 72 hours, and attribution wants 48 */
4
+ export const GA4_RECOMMENDED_MS = 48 * HOUR;
5
+ /** the longest cap a `ga4` collector may declare */
6
+ export const GA4_HARD_MS = 72 * HOUR;
7
+ /**
8
+ * The GA4 browser collector, forwarded through the server half because the Measurement Protocol
9
+ * needs an API secret the page must not hold. The cap is the 48-hour attribution window.
10
+ */
11
+ export const GA4_COLLECTOR = {
12
+ vendor: 'ga4',
13
+ match: 'https://www.google-analytics.com/g/collect',
14
+ maxAgeMs: GA4_RECOMMENDED_MS,
15
+ delivery: 'sink'
16
+ };
17
+ function bad(message) {
18
+ throw new ProtocolError('bad-route', message);
19
+ }
20
+ /** validates collectors from a server config; a `ga4` cap past the 72-hour limit is refused */
21
+ export function checkCollectors(collectors) {
22
+ const seen = new Set();
23
+ for (const c of collectors) {
24
+ if (!c.vendor)
25
+ bad('collector needs a vendor');
26
+ if (seen.has(c.vendor))
27
+ bad(`collector ${c.vendor} declared twice`);
28
+ seen.add(c.vendor);
29
+ let url;
30
+ try {
31
+ url = new URL(c.match);
32
+ }
33
+ catch {
34
+ return bad(`collector ${c.vendor}: match must be an absolute URL`);
35
+ }
36
+ if (url.protocol !== 'https:' && url.protocol !== 'http:') {
37
+ bad(`collector ${c.vendor}: match must be http or https`);
38
+ }
39
+ if (!Number.isFinite(c.maxAgeMs) || c.maxAgeMs <= 0) {
40
+ bad(`collector ${c.vendor}: maxAgeMs must be a positive number of milliseconds`);
41
+ }
42
+ if (c.vendor === 'ga4' && c.maxAgeMs > GA4_HARD_MS) {
43
+ bad('collector ga4: maxAgeMs is past the 72 hour Measurement Protocol limit');
44
+ }
45
+ if (c.delivery !== 'replay' && c.delivery !== 'sink') {
46
+ bad(`collector ${c.vendor}: delivery must be replay or sink`);
47
+ }
48
+ if (c.stamp && !['age-ms', 'epoch-ms', 'epoch-s', 'datetime-utc'].includes(c.stamp.kind)) {
49
+ bad(`collector ${c.vendor}: unknown stamp kind`);
50
+ }
51
+ }
52
+ }
53
+ /** the collector whose `match` the URL falls under, or undefined */
54
+ export function matchCollector(collectors, url) {
55
+ if (!collectors || collectors.length === 0)
56
+ return undefined;
57
+ let target;
58
+ try {
59
+ target = new URL(url);
60
+ }
61
+ catch {
62
+ return undefined;
63
+ }
64
+ return collectors.find((c) => {
65
+ const m = new URL(c.match);
66
+ return target.origin === m.origin && target.pathname.startsWith(m.pathname);
67
+ });
68
+ }
69
+ function stampValue(kind, at, now) {
70
+ if (kind === 'age-ms')
71
+ return String(Math.max(0, Math.round(now - at)));
72
+ if (kind === 'epoch-ms')
73
+ return String(Math.round(at));
74
+ if (kind === 'epoch-s')
75
+ return String(Math.floor(at / 1000));
76
+ return new Date(at).toISOString().slice(0, 19).replace('T', ' ');
77
+ }
78
+ /** `search` with the stamp parameter set to when the event happened, other parameters kept */
79
+ export function applyStamp(search, stamp, at, now) {
80
+ const params = new URLSearchParams(search);
81
+ params.set(stamp.param, stampValue(stamp.kind, at, now));
82
+ const text = params.toString();
83
+ return text === '' ? '' : `?${text}`;
84
+ }
@@ -0,0 +1,89 @@
1
+ import type { PROTOCOL_VERSION } from './artifact.js';
2
+ import type { CollectorConfig } from './collector.js';
3
+ import type { SerializedRoute } from './route.js';
4
+ import type { CompiledTemplate } from './template/compile.js';
5
+ import type { Mode } from './view.js';
6
+ /** every path under this prefix belongs to spool */
7
+ export declare const SPOOL_PREFIX = "/.spool/";
8
+ /** where the server answers sync, artifact and beacon requests, and where the worker script lives */
9
+ export declare const PATHS: {
10
+ readonly sync: "/.spool/sync";
11
+ readonly artifact: "/.spool/artifact";
12
+ readonly beacon: "/.spool/beacon";
13
+ readonly worker: "/spool-sw.js";
14
+ };
15
+ /** the same-origin path of the page runtime script for a given version */
16
+ export declare function clientPath(version: string): string;
17
+ /**
18
+ * Priors and the hot list for provisioning. Every number is a scenario assumption the operator
19
+ * replaces with its own telemetry; `hot` names paths to warm in priority order, riding the next
20
+ * beacon flush.
21
+ */
22
+ export type ProvisionConfig = {
23
+ reuse?: number;
24
+ futureViews?: number;
25
+ requestBytes?: number;
26
+ artifactBytes?: number;
27
+ avoidedBytes?: number;
28
+ /** rate of change per dependency tag, per day, before the worker has seen any */
29
+ changesPerDay?: number;
30
+ hot?: string[];
31
+ };
32
+ /**
33
+ * How the worker treats same-origin subresources. `cache` answers an immutable one from
34
+ * CacheStorage; `passthrough` leaves it to the browser's own cache with no worker involvement;
35
+ * `static-routing` asks the browser (`InstallEvent.addRoutes`) to send only navigations, beacons
36
+ * and routed paths to the worker and everything else to the network, and acts as `passthrough` where
37
+ * the API does not exist.
38
+ */
39
+ export type AssetMode = 'cache' | 'passthrough' | 'static-routing';
40
+ /**
41
+ * The opt-in worker cache for cross-origin files. Only an origin in `allow` is touched, and only a
42
+ * response the worker can read (a CORS answer) for a URL that looks versioned, or one the origin
43
+ * marks immutable, is kept. Everything else goes to the network untouched.
44
+ */
45
+ export type ThirdPartyConfig = {
46
+ /** origins whose GET requests the worker may answer from its copy, such as `https://fonts.gstatic.com` */
47
+ allow: string[];
48
+ /** extra patterns, as regular expression sources, that mark a URL as versioned */
49
+ versioned?: string[];
50
+ /** a copy of an unversioned file is checked again at a network moment once it is this old; default one day */
51
+ revalidateAfterMs?: number;
52
+ /** most files held; the oldest go first; default 64 */
53
+ maxEntries?: number;
54
+ /** keep opaque (no-cors) responses, which Chromium counts as about 7 MB each against quota; default false */
55
+ allowOpaque?: boolean;
56
+ };
57
+ /** what the server compiles into the worker script: routes, templates and the tag to inject */
58
+ export type SwConfig = {
59
+ protocol: typeof PROTOCOL_VERSION;
60
+ version: string;
61
+ routes: SerializedRoute[];
62
+ /** compiled templates keyed by route pattern */
63
+ templates: Record<string, CompiledTemplate>;
64
+ /** same-origin POST paths the worker queues and flushes in one request */
65
+ beacons: string[];
66
+ /** the exact script tag the server injects, so a local render matches a network one */
67
+ clientTag: string;
68
+ /** the mode for routes that do not name one; `serve` when absent */
69
+ mode?: Mode;
70
+ /** the share of views, 0 to 1, that run in shadow while the mode is `serve`; 0 when absent */
71
+ shadowSample?: number;
72
+ /** whether the worker queues a `spool.view` per page view; true when absent */
73
+ views?: boolean;
74
+ /** what the worker assumes before telemetry says otherwise, and which pages to warm */
75
+ provision?: ProvisionConfig;
76
+ /**
77
+ * The URL of a `spool.json`. Present, the worker has no spool server: it takes its routes from
78
+ * that file, checks it for changes in place of `/.spool/sync`, and sends no request to `/.spool/*`.
79
+ */
80
+ manifest?: string;
81
+ /** how same-origin subresources are handled; `cache` when absent */
82
+ assets?: AssetMode;
83
+ /** same-origin paths whose request ends the session: the worker wipes the principal store first */
84
+ logout?: string[];
85
+ /** cross-origin analytics collectors the worker holds and delivers later */
86
+ collectors?: CollectorConfig[];
87
+ /** the opt-in cache for versioned cross-origin files */
88
+ thirdParty?: ThirdPartyConfig;
89
+ };
@@ -0,0 +1,13 @@
1
+ /** every path under this prefix belongs to spool */
2
+ export const SPOOL_PREFIX = '/.spool/';
3
+ /** where the server answers sync, artifact and beacon requests, and where the worker script lives */
4
+ export const PATHS = {
5
+ sync: '/.spool/sync',
6
+ artifact: '/.spool/artifact',
7
+ beacon: '/.spool/beacon',
8
+ worker: '/spool-sw.js'
9
+ };
10
+ /** the same-origin path of the page runtime script for a given version */
11
+ export function clientPath(version) {
12
+ return `${SPOOL_PREFIX}${encodeURIComponent(version)}/client.js`;
13
+ }
@@ -0,0 +1,47 @@
1
+ import { type Scope } from './artifact.js';
2
+ /** the header names, lowercase as `Headers` reports them */
3
+ export declare const HEADERS: {
4
+ readonly protocol: "spool-protocol";
5
+ readonly artifact: "spool-artifact";
6
+ readonly invalidate: "spool-invalidate";
7
+ readonly clear: "spool-clear";
8
+ readonly vector: "spool-vector";
9
+ readonly partition: "spool-partition";
10
+ readonly vectorSeen: "spool-vector-seen";
11
+ readonly provision: "spool-provision";
12
+ };
13
+ /** `Spool-Clear` token that wipes everything the worker holds */
14
+ export declare const CLEAR_ALL = "*";
15
+ /** what a response says about the artifact it carries */
16
+ export type EnvelopeArtifact = {
17
+ id: string;
18
+ scope: Scope;
19
+ deps: string[];
20
+ /** the vector cursor the artifact reflects */
21
+ version: number;
22
+ };
23
+ /** every spool header of a response, decoded; an absent header is an absent field */
24
+ export type Envelope = {
25
+ protocol?: number;
26
+ artifact?: EnvelopeArtifact;
27
+ /** tag to the vector version at which it last changed */
28
+ invalidate?: Record<string, number>;
29
+ /** partition ids to wipe, or {@link CLEAR_ALL} */
30
+ clear?: string[];
31
+ vector?: number;
32
+ /** echo of the request's `Spool-Vector-Seen`: `invalidate` is the complete diff since this cursor */
33
+ seen?: number;
34
+ partition?: string;
35
+ };
36
+ /** the header map for an envelope; `Spool-Protocol` is always present */
37
+ export declare function encodeEnvelope(envelope: Envelope): Record<string, string>;
38
+ /** sets every header of `envelope` on `headers`, replacing any spool header already there */
39
+ export declare function writeEnvelope(headers: Headers, envelope: Envelope): void;
40
+ /**
41
+ * The envelope of a response as the worker uses it. A malformed spool header drops every field
42
+ * but `Spool-Clear`, which is read on its own so a valid clear still applies and a malformed one
43
+ * reads as a full wipe. A response that names another protocol version is left alone.
44
+ */
45
+ export declare function decodeEnvelopeOrClear(headers: Headers): Envelope | undefined;
46
+ /** reads the spool headers; throws `ProtocolError` on a malformed one */
47
+ export declare function decodeEnvelope(headers: Headers): Envelope;