@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,53 @@
1
+ import { DurableObject } from 'cloudflare:workers';
2
+ /**
3
+ * The version vector in a SQLite-backed Durable Object: one row per tag and one cursor row, so it
4
+ * survives eviction and restarts. Bind it as a Durable Object class and pass the namespace to
5
+ * {@link durableObjectStore}.
6
+ */
7
+ export class SpoolVersions extends DurableObject {
8
+ constructor(ctx, env) {
9
+ super(ctx, env);
10
+ const sql = ctx.storage.sql;
11
+ sql.exec('CREATE TABLE IF NOT EXISTS spool_tags (tag TEXT PRIMARY KEY, version INTEGER NOT NULL) WITHOUT ROWID');
12
+ sql.exec('CREATE TABLE IF NOT EXISTS spool_meta (id INTEGER PRIMARY KEY, cursor INTEGER NOT NULL)');
13
+ sql.exec('INSERT OR IGNORE INTO spool_meta (id, cursor) VALUES (0, 0)');
14
+ }
15
+ /** records a change to `tags` and returns the new cursor */
16
+ bump(tags) {
17
+ const sql = this.ctx.storage.sql;
18
+ return this.ctx.storage.transactionSync(() => {
19
+ const cursor = this.cursor();
20
+ if (tags.length === 0)
21
+ return cursor;
22
+ const next = cursor + 1;
23
+ for (const tag of new Set(tags)) {
24
+ sql.exec('INSERT INTO spool_tags (tag, version) VALUES (?, ?) ON CONFLICT (tag) DO UPDATE SET version = excluded.version', tag, next);
25
+ }
26
+ sql.exec('UPDATE spool_meta SET cursor = ? WHERE id = 0', next);
27
+ return next;
28
+ });
29
+ }
30
+ /** the cursor of the most recent bump */
31
+ cursor() {
32
+ return Number(this.ctx.storage.sql.exec('SELECT cursor FROM spool_meta WHERE id = 0').one()['cursor']);
33
+ }
34
+ /** every tag changed after `from`; see `VersionVector.diff` */
35
+ diff(from) {
36
+ const cursor = this.cursor();
37
+ const reset = from > cursor;
38
+ const rows = this.ctx.storage.sql
39
+ .exec('SELECT tag, version FROM spool_tags WHERE version > ?', reset ? 0 : from)
40
+ .toArray();
41
+ const changed = Object.fromEntries(rows.map((r) => [String(r['tag']), Number(r['version'])]));
42
+ return { cursor, changed, reset };
43
+ }
44
+ }
45
+ /** a {@link VersionStore} over one named instance of the {@link SpoolVersions} namespace */
46
+ export function durableObjectStore(namespace, name = 'spool') {
47
+ const stub = () => namespace.getByName(name);
48
+ return {
49
+ bump: (tags) => stub().bump([...tags]),
50
+ cursor: () => stub().cursor(),
51
+ diff: (from) => stub().diff(from)
52
+ };
53
+ }
@@ -0,0 +1,2 @@
1
+ export * from './memory.js';
2
+ export * from './version-store.js';
@@ -0,0 +1,2 @@
1
+ export * from './memory.js';
2
+ export * from './version-store.js';
@@ -0,0 +1,4 @@
1
+ import { type VectorSnapshot } from '../protocol/vector.js';
2
+ import type { VersionStore } from './version-store.js';
3
+ /** a store that lives as long as the process; fine for tests, single-instance Node and Bun */
4
+ export declare function memoryStore(initial?: VectorSnapshot): VersionStore;
@@ -0,0 +1,10 @@
1
+ import { VersionVector } from '../protocol/vector.js';
2
+ /** a store that lives as long as the process; fine for tests, single-instance Node and Bun */
3
+ export function memoryStore(initial) {
4
+ const vector = initial ? VersionVector.from(initial) : new VersionVector();
5
+ return {
6
+ bump: async (tags) => vector.bump(tags),
7
+ cursor: async () => vector.cursor,
8
+ diff: async (from) => vector.diff(from)
9
+ };
10
+ }
@@ -0,0 +1,11 @@
1
+ import type { VectorDiff } from '../protocol/vector.js';
2
+ /**
3
+ * Where the version vector lives. `bump` records a write and returns the new cursor; `diff` is
4
+ * every tag changed after a cursor. Implementations must keep the cursor monotonic across
5
+ * restarts, or workers holding a higher cursor are told to reset.
6
+ */
7
+ export interface VersionStore {
8
+ bump(tags: readonly string[]): Promise<number>;
9
+ cursor(): Promise<number>;
10
+ diff(from: number): Promise<VectorDiff>;
11
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,81 @@
1
+ import { MAX_BEACON_BYTES, type BeaconBatch, type BeaconEvent, type CatalogueAsk } from '../protocol/beacon.js';
2
+ import type { CollectorConfig } from '../protocol/collector.js';
3
+ import type { ReplicaStorage } from './storage.js';
4
+ /** a held request older than this goes out on its own flush, at most once per such window */
5
+ export declare const MAX_HOLD_MS: number;
6
+ /** views alone wait for this many to be held before a network moment sends them */
7
+ export declare const VIEW_BATCH = 20;
8
+ /** or until the oldest has been held this long */
9
+ export declare const VIEW_HOLD_MS: number;
10
+ /** a page's catalogue is asked for again after this long; the record survives a worker restart */
11
+ export declare const CATALOGUE_REASK_MS: number;
12
+ /** page paths whose last catalogue ask is kept */
13
+ export declare const MAX_CATALOGUE_ASKED = 256;
14
+ /** most events one request carries, so a long offline stretch never builds a body the server refuses */
15
+ export declare const FLUSH_CHUNK = 100;
16
+ /** how long a logout waits for the held same-origin requests to go out before it drops them */
17
+ export declare const LOGOUT_SEND_MS = 3000;
18
+ /** the vendor name a dropped same-origin request is counted under */
19
+ export declare const SAME_ORIGIN_VENDOR = "same-origin";
20
+ export { MAX_BEACON_BYTES };
21
+ /** what the queue needs from the outside world */
22
+ export type QueueDeps = {
23
+ storage: ReplicaStorage;
24
+ now(): number;
25
+ /** posts a batch; true when the server took it or refused it for good, false to retry later */
26
+ send(batch: BeaconBatch): Promise<boolean>;
27
+ /**
28
+ * sends one held request to the URL it was meant for; true when it was delivered or refused for
29
+ * good, false to retry later
30
+ */
31
+ replay(event: BeaconEvent): Promise<boolean>;
32
+ /** artifact paths to ask for with the next flush; sent once, with the first batch */
33
+ want?(): string[] | Promise<string[]>;
34
+ /**
35
+ * the catalogue to ask for, sent with the first batch of a flush unless that path was asked
36
+ * within {@link CATALOGUE_REASK_MS}. A due ask makes {@link BeaconQueue.flushAtMoment} flush
37
+ * and nothing else does, so it adds no request on a local view or with nothing held
38
+ */
39
+ catalogue?(): CatalogueAsk | undefined;
40
+ };
41
+ /**
42
+ * Holds beacon requests on the device. A beacon that reaches the network on its own wakes the
43
+ * radio, so the queue waits for a request that is happening anyway and leaves with it. Spool's
44
+ * own events travel in one batch to `/.spool/beacon`; a site's beacon is replayed to the URL it was
45
+ * meant for, with its method, content type and body, so the vendor receives what the page sent. An
46
+ * event past its age cap is dropped and counted, never sent late.
47
+ */
48
+ export declare class BeaconQueue {
49
+ #private;
50
+ /** events dropped past their age cap since the worker started, by vendor */
51
+ readonly dropped: Map<string, number>;
52
+ constructor(deps: QueueDeps);
53
+ /** queues an event the worker made itself, such as a view */
54
+ record(event: BeaconEvent): Promise<void>;
55
+ /**
56
+ * queues a beacon; false when it is binary or too large and should go to the network. A request
57
+ * to another origin passes the `collector` that matched it.
58
+ */
59
+ enqueue(request: Request, collector?: CollectorConfig): Promise<boolean>;
60
+ /** sends everything held in one request, or joins the flush already running */
61
+ flush(): Promise<boolean>;
62
+ /**
63
+ * Flushes at a network moment when it is worth a request: another site's beacon is held,
64
+ * artifacts are wanted, a catalogue ask is due, {@link VIEW_BATCH} views are held (their loads
65
+ * reports ride along), or the oldest has waited {@link VIEW_HOLD_MS}. A few views alone keep
66
+ * waiting for a later moment. With nothing held there is nothing to carry the ask, so no flush.
67
+ */
68
+ flushAtMoment(): Promise<boolean>;
69
+ /**
70
+ * Flushes on its own when the oldest held beacon is past {@link MAX_HOLD_MS}; looks hourly and
71
+ * at most once per such window. Both clocks are stored, so a worker restart does not reset them.
72
+ */
73
+ flushIfDue(): Promise<boolean>;
74
+ /**
75
+ * Sends the held same-origin requests now and drops whatever does not get through, counted under
76
+ * {@link SAME_ORIGIN_VENDOR}. A replay carries the browser's cookies, so after a logout it would
77
+ * be attributed to whoever signs in next. Run it while the session that made them is still the
78
+ * browser's. A request that fails, or a network that is down, loses the event for good.
79
+ */
80
+ sendSameOrigin(timeoutMs: number): Promise<void>;
81
+ }
@@ -0,0 +1,275 @@
1
+ import { PROTOCOL_VERSION } from '../protocol/artifact.js';
2
+ import { DROPPED_PATH, MAX_BEACON_BYTES, OWN_PREFIX } from '../protocol/beacon.js';
3
+ import { LOADS_PATH, VIEW_PATH } from '../protocol/view.js';
4
+ /** a held request older than this goes out on its own flush, at most once per such window */
5
+ export const MAX_HOLD_MS = 24 * 60 * 60 * 1000;
6
+ const CHECK_EVERY_MS = 60 * 60 * 1000;
7
+ /** views alone wait for this many to be held before a network moment sends them */
8
+ export const VIEW_BATCH = 20;
9
+ /** or until the oldest has been held this long */
10
+ export const VIEW_HOLD_MS = 60 * 60 * 1000;
11
+ /** a page's catalogue is asked for again after this long; the record survives a worker restart */
12
+ export const CATALOGUE_REASK_MS = 24 * 60 * 60 * 1000;
13
+ /** page paths whose last catalogue ask is kept */
14
+ export const MAX_CATALOGUE_ASKED = 256;
15
+ /** most events one request carries, so a long offline stretch never builds a body the server refuses */
16
+ export const FLUSH_CHUNK = 100;
17
+ /** how long a logout waits for the held same-origin requests to go out before it drops them */
18
+ export const LOGOUT_SEND_MS = 3000;
19
+ /** the vendor name a dropped same-origin request is counted under */
20
+ export const SAME_ORIGIN_VENDOR = 'same-origin';
21
+ export { MAX_BEACON_BYTES };
22
+ function within(promise, ms) {
23
+ let timer;
24
+ const late = new Promise((_, reject) => {
25
+ timer = setTimeout(() => reject(new Error('timed out')), ms);
26
+ });
27
+ return Promise.race([promise, late]).finally(() => clearTimeout(timer));
28
+ }
29
+ const encoder = new TextEncoder();
30
+ /** whether the flush to `/.spool/beacon` carries the event; the rest the worker replays itself */
31
+ const inBatch = (event) => event.path.startsWith(OWN_PREFIX) || event.deliver === 'sink';
32
+ /**
33
+ * Holds beacon requests on the device. A beacon that reaches the network on its own wakes the
34
+ * radio, so the queue waits for a request that is happening anyway and leaves with it. Spool's
35
+ * own events travel in one batch to `/.spool/beacon`; a site's beacon is replayed to the URL it was
36
+ * meant for, with its method, content type and body, so the vendor receives what the page sent. An
37
+ * event past its age cap is dropped and counted, never sent late.
38
+ */
39
+ export class BeaconQueue {
40
+ #deps;
41
+ #flushing = null;
42
+ #state;
43
+ /** events dropped past their age cap since the worker started, by vendor */
44
+ dropped = new Map();
45
+ constructor(deps) {
46
+ this.#deps = deps;
47
+ }
48
+ /** queues an event the worker made itself, such as a view */
49
+ async record(event) {
50
+ await this.#deps.storage.addBeacon(event);
51
+ }
52
+ /**
53
+ * queues a beacon; false when it is binary or too large and should go to the network. A request
54
+ * to another origin passes the `collector` that matched it.
55
+ */
56
+ async enqueue(request, collector) {
57
+ const get = request.method === 'GET';
58
+ const contentType = get ? '' : (request.headers.get('content-type') ?? 'text/plain');
59
+ if (/octet-stream|multipart|image\//i.test(contentType))
60
+ return false;
61
+ const body = get ? '' : await request.clone().text();
62
+ if (encoder.encode(body).length > MAX_BEACON_BYTES)
63
+ return false;
64
+ const url = new URL(request.url);
65
+ const at = this.#deps.now();
66
+ const event = { path: url.pathname, body, contentType, at };
67
+ if (url.search !== '')
68
+ event.search = url.search;
69
+ if (get)
70
+ event.method = 'GET';
71
+ if (collector) {
72
+ event.origin = url.origin;
73
+ event.vendor = collector.vendor;
74
+ event.until = at + collector.maxAgeMs;
75
+ if (collector.delivery === 'sink')
76
+ event.deliver = 'sink';
77
+ }
78
+ await this.#deps.storage.addBeacon(event);
79
+ return true;
80
+ }
81
+ /** sends everything held in one request, or joins the flush already running */
82
+ flush() {
83
+ this.#flushing ??= this.#run().finally(() => {
84
+ this.#flushing = null;
85
+ });
86
+ return this.#flushing;
87
+ }
88
+ /**
89
+ * Flushes at a network moment when it is worth a request: another site's beacon is held,
90
+ * artifacts are wanted, a catalogue ask is due, {@link VIEW_BATCH} views are held (their loads
91
+ * reports ride along), or the oldest has waited {@link VIEW_HOLD_MS}. A few views alone keep
92
+ * waiting for a later moment. With nothing held there is nothing to carry the ask, so no flush.
93
+ */
94
+ async flushAtMoment() {
95
+ await this.#expire();
96
+ const held = await this.#deps.storage.readBeacons();
97
+ if (held.length === 0)
98
+ return false;
99
+ const own = (path) => path === VIEW_PATH || path === LOADS_PATH || path === DROPPED_PATH;
100
+ const others = held.some((b) => !own(b.event.path));
101
+ const views = held.filter((b) => b.event.path === VIEW_PATH).length;
102
+ const wanted = ((await this.#deps.want?.()) ?? []).length > 0;
103
+ const asking = (await this.#due(this.#deps.catalogue?.())) !== undefined;
104
+ const oldest = Math.min(...held.map((b) => b.event.at));
105
+ const aged = this.#deps.now() - oldest >= VIEW_HOLD_MS;
106
+ if (others || wanted || asking || aged || views >= VIEW_BATCH)
107
+ return this.flush();
108
+ return false;
109
+ }
110
+ /**
111
+ * Flushes on its own when the oldest held beacon is past {@link MAX_HOLD_MS}; looks hourly and
112
+ * at most once per such window. Both clocks are stored, so a worker restart does not reset them.
113
+ */
114
+ async flushIfDue() {
115
+ const now = this.#deps.now();
116
+ const state = await this.#read();
117
+ // a stored time ahead of the clock cannot be trusted, so it counts as never
118
+ const checked = state.checkedAt > now ? -Infinity : state.checkedAt;
119
+ if (now - checked < CHECK_EVERY_MS)
120
+ return false;
121
+ state.checkedAt = now;
122
+ await this.#write(state);
123
+ await this.#expire();
124
+ const held = await this.#deps.storage.readBeacons();
125
+ const oldest = Math.min(...held.map((b) => b.event.at));
126
+ if (held.length === 0 || now - oldest < MAX_HOLD_MS)
127
+ return false;
128
+ const last = state.lastStandalone > now ? -Infinity : state.lastStandalone;
129
+ if (now - last < MAX_HOLD_MS)
130
+ return false;
131
+ state.lastStandalone = now;
132
+ await this.#write(state);
133
+ return this.flush();
134
+ }
135
+ async #read() {
136
+ this.#state ??= (await this.#deps.storage.getFlush()) ?? {
137
+ lastStandalone: -Infinity,
138
+ checkedAt: -Infinity
139
+ };
140
+ return this.#state;
141
+ }
142
+ async #write(state) {
143
+ await this.#deps.storage.setFlush(state);
144
+ }
145
+ /** removes the events past their cap and queues one `dropped` record per vendor */
146
+ async #expire() {
147
+ const { storage, now } = this.#deps;
148
+ const at = now();
149
+ const held = await storage.readBeacons();
150
+ const late = held.filter((b) => b.event.until !== undefined && b.event.until < at);
151
+ if (late.length === 0)
152
+ return;
153
+ await storage.removeBeacons(late.map((b) => b.key));
154
+ await this.#report(late.map(({ event }) => event.vendor ?? 'unknown'));
155
+ }
156
+ /** counts dropped events by vendor and queues one `dropped` record per vendor */
157
+ async #report(vendors) {
158
+ const counts = new Map();
159
+ for (const vendor of vendors)
160
+ counts.set(vendor, (counts.get(vendor) ?? 0) + 1);
161
+ for (const [vendor, count] of counts) {
162
+ this.dropped.set(vendor, (this.dropped.get(vendor) ?? 0) + count);
163
+ await this.#deps.storage.addBeacon({
164
+ path: DROPPED_PATH,
165
+ body: JSON.stringify({ vendor, count }),
166
+ contentType: 'application/json',
167
+ at: this.#deps.now()
168
+ });
169
+ }
170
+ }
171
+ /**
172
+ * Sends the held same-origin requests now and drops whatever does not get through, counted under
173
+ * {@link SAME_ORIGIN_VENDOR}. A replay carries the browser's cookies, so after a logout it would
174
+ * be attributed to whoever signs in next. Run it while the session that made them is still the
175
+ * browser's. A request that fails, or a network that is down, loses the event for good.
176
+ */
177
+ async sendSameOrigin(timeoutMs) {
178
+ if (this.#flushing)
179
+ await this.#flushing.catch(() => false);
180
+ const { storage, replay } = this.#deps;
181
+ const mine = (await storage.readBeacons()).filter(({ event }) => !inBatch(event) && event.origin === undefined);
182
+ if (mine.length === 0)
183
+ return;
184
+ await storage.removeBeacons(mine.map((b) => b.key));
185
+ let down = false;
186
+ const lost = [];
187
+ for (const { event } of mine) {
188
+ let delivered = false;
189
+ if (!down) {
190
+ try {
191
+ delivered = await within(replay(event), timeoutMs);
192
+ }
193
+ catch {
194
+ down = true;
195
+ }
196
+ }
197
+ if (!delivered)
198
+ lost.push(SAME_ORIGIN_VENDOR);
199
+ }
200
+ await this.#report(lost);
201
+ }
202
+ async #run() {
203
+ const { storage, send, replay, want, catalogue } = this.#deps;
204
+ await this.#expire();
205
+ const held = await storage.readBeacons();
206
+ if (held.length === 0)
207
+ return false;
208
+ let ok = true;
209
+ for (const b of held.filter((h) => !inBatch(h.event))) {
210
+ let delivered;
211
+ try {
212
+ delivered = await replay(b.event);
213
+ }
214
+ catch {
215
+ delivered = false;
216
+ }
217
+ if (delivered)
218
+ await storage.removeBeacons([b.key]);
219
+ else
220
+ ok = false;
221
+ }
222
+ const batched = held.filter((h) => inBatch(h.event));
223
+ let wanted = (await want?.()) ?? [];
224
+ let ask = await this.#due(catalogue?.());
225
+ if (batched.length === 0 && wanted.length === 0)
226
+ return ok;
227
+ let done = true;
228
+ for (let at = 0; at < Math.max(batched.length, 1); at += FLUSH_CHUNK) {
229
+ const chunk = batched.slice(at, at + FLUSH_CHUNK);
230
+ const batch = {
231
+ protocol: PROTOCOL_VERSION,
232
+ events: chunk.map(({ event: { until: _until, ...event } }) => event)
233
+ };
234
+ if (wanted.length > 0)
235
+ batch.want = wanted;
236
+ if (ask)
237
+ batch.catalogue = ask;
238
+ wanted = [];
239
+ ask = undefined;
240
+ try {
241
+ done = await send(batch);
242
+ }
243
+ catch {
244
+ done = false;
245
+ }
246
+ if (!done)
247
+ return false;
248
+ await storage.removeBeacons(chunk.map((b) => b.key));
249
+ if (batch.catalogue)
250
+ await this.#asked(batch.catalogue.path);
251
+ }
252
+ return ok && done;
253
+ }
254
+ /** `ask` unless its path was asked within {@link CATALOGUE_REASK_MS} */
255
+ async #due(ask) {
256
+ if (!ask)
257
+ return undefined;
258
+ const at = (await this.#read()).catalogue?.[ask.path];
259
+ const now = this.#deps.now();
260
+ // a stored time ahead of the clock cannot be trusted, so it counts as never
261
+ return at === undefined || at > now || now - at >= CATALOGUE_REASK_MS ? ask : undefined;
262
+ }
263
+ /** stores when `path` was asked, keeping the latest {@link MAX_CATALOGUE_ASKED} paths */
264
+ async #asked(path) {
265
+ const state = await this.#read();
266
+ const asked = { ...state.catalogue };
267
+ delete asked[path];
268
+ asked[path] = this.#deps.now();
269
+ const paths = Object.keys(asked);
270
+ for (const old of paths.slice(0, paths.length - MAX_CATALOGUE_ASKED))
271
+ delete asked[old];
272
+ state.catalogue = asked;
273
+ await this.#write(state);
274
+ }
275
+ }
@@ -0,0 +1,8 @@
1
+ /** the origin of a URL, or null when it is not one */
2
+ export declare function safeOrigin(value: string): string | null;
3
+ /**
4
+ * What the page gets for a collector hit the worker holds: an empty 204 for a POST, a one-pixel
5
+ * GIF for a GET. A CORS request also needs the allow headers, with the page's origin when the
6
+ * request carries credentials, since a wildcard fails there.
7
+ */
8
+ export declare function collectorAnswer(request: Request): Response;
@@ -0,0 +1,33 @@
1
+ /** the origin of a URL, or null when it is not one */
2
+ export function safeOrigin(value) {
3
+ try {
4
+ return new URL(value).origin;
5
+ }
6
+ catch {
7
+ return null;
8
+ }
9
+ }
10
+ const PIXEL = Uint8Array.from(atob('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'), (c) => c.charCodeAt(0));
11
+ /**
12
+ * What the page gets for a collector hit the worker holds: an empty 204 for a POST, a one-pixel
13
+ * GIF for a GET. A CORS request also needs the allow headers, with the page's origin when the
14
+ * request carries credentials, since a wildcard fails there.
15
+ */
16
+ export function collectorAnswer(request) {
17
+ const headers = new Headers();
18
+ if (request.mode === 'cors') {
19
+ const origin = request.headers.get('origin') ?? safeOrigin(request.referrer);
20
+ if (request.credentials === 'include' && origin) {
21
+ headers.set('access-control-allow-origin', origin);
22
+ headers.set('access-control-allow-credentials', 'true');
23
+ }
24
+ else
25
+ headers.set('access-control-allow-origin', '*');
26
+ }
27
+ if (request.method === 'GET') {
28
+ headers.set('content-type', 'image/gif');
29
+ headers.set('cache-control', 'no-store');
30
+ return new Response(PIXEL, { status: 200, headers });
31
+ }
32
+ return new Response(null, { status: 204, headers });
33
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import { manifestConfig, serve } from './serve.js';
2
+ const scope = self;
3
+ serve(scope.__SPOOL_CONFIG__ ?? manifestConfig(scope.location.href));
@@ -0,0 +1,15 @@
1
+ import type { Artifact } from '../protocol/artifact.js';
2
+ import type { Freshness } from '../protocol/route.js';
3
+ /** what to do with a stored artifact before showing it */
4
+ export type Verdict = 'serve' | 'sync-first' | 'serve-then-sync';
5
+ /**
6
+ * Applies a route's staleness contract. Within `maxStale` seconds of the last validation the
7
+ * artifact is shown as is. Past it, a hard route blocks on a required sync and a soft route shows
8
+ * the artifact and syncs once afterwards. A clock that moved backwards counts as past the bound,
9
+ * since the age cannot be known.
10
+ */
11
+ export declare function verdict(freshness: Freshness, validatedAt: number, now: number): Verdict;
12
+ /** when an artifact was last known good: its own fetch or the last sync, whichever is later */
13
+ export declare function validatedAt(fetchedAt: number, syncedAt: number): number;
14
+ /** whether no dependency of `artifact` has changed since the vector it was built at */
15
+ export declare function isCurrent(artifact: Artifact, tagVersion: (tag: string) => number): boolean;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Applies a route's staleness contract. Within `maxStale` seconds of the last validation the
3
+ * artifact is shown as is. Past it, a hard route blocks on a required sync and a soft route shows
4
+ * the artifact and syncs once afterwards. A clock that moved backwards counts as past the bound,
5
+ * since the age cannot be known.
6
+ */
7
+ export function verdict(freshness, validatedAt, now) {
8
+ const age = now >= validatedAt ? (now - validatedAt) / 1000 : Infinity;
9
+ if (age <= freshness.maxStale)
10
+ return 'serve';
11
+ return freshness.mode === 'hard' ? 'sync-first' : 'serve-then-sync';
12
+ }
13
+ /** when an artifact was last known good: its own fetch or the last sync, whichever is later */
14
+ export function validatedAt(fetchedAt, syncedAt) {
15
+ return Math.max(fetchedAt, syncedAt);
16
+ }
17
+ /** whether no dependency of `artifact` has changed since the vector it was built at */
18
+ export function isCurrent(artifact, tagVersion) {
19
+ return artifact.deps.every((dep) => tagVersion(dep) <= artifact.vector);
20
+ }
@@ -0,0 +1,67 @@
1
+ import type { Artifact } from '../../protocol/artifact.js';
2
+ import type { ReplicaStorage, StoredArtifact } from '../storage.js';
3
+ import { DependencyIndex } from './invalidate.js';
4
+ export { DependencyIndex } from './invalidate.js';
5
+ export { projectionStore, type ProjectionStore } from './projections.js';
6
+ export { recordStore, type RecordStore } from './records.js';
7
+ export { EntryStore, type EntryBacking } from './store.js';
8
+ /** what a change reached; every list is sorted */
9
+ export type Invalidated = {
10
+ records: string[];
11
+ projections: string[];
12
+ artifacts: string[];
13
+ };
14
+ /** a page with every reference resolved, or why it cannot be built from what is held */
15
+ export type Materialized = {
16
+ ok: true;
17
+ artifact: Artifact;
18
+ } | {
19
+ ok: false;
20
+ reason: string;
21
+ };
22
+ /** what the graph reads from the replica around it */
23
+ export type GraphDeps = {
24
+ storage: ReplicaStorage;
25
+ /** the newest version learned for a tag, 0 when none */
26
+ tagVersion(tag: string): number;
27
+ /** every stored artifact, read once to build the index on first use */
28
+ artifacts(): Promise<StoredArtifact[]>;
29
+ };
30
+ /** whether an artifact references anything in the graph */
31
+ export declare function usesGraph(artifact: Artifact): boolean;
32
+ /**
33
+ * Records and projections stored once, the index over them, and the rules that tie them to
34
+ * artifacts. Nothing is read from storage until {@link Graph.ensure}: a worker that wakes for a
35
+ * page with no references never touches it.
36
+ */
37
+ export declare class Graph {
38
+ #private;
39
+ readonly records: import("./records.js").RecordStore;
40
+ readonly projections: import("./projections.js").ProjectionStore;
41
+ readonly index: DependencyIndex;
42
+ constructor(deps: GraphDeps);
43
+ /** whether `ensure` has been called */
44
+ get loaded(): boolean;
45
+ /**
46
+ * Loads records and projections, builds the index from the stored artifacts, and drops what a
47
+ * change learned while the graph was asleep outdated. Resolves to the artifacts that lost a
48
+ * dependency on the first call and to nothing after.
49
+ */
50
+ ensure(): Promise<string[]>;
51
+ /** stores what an artifact brought and indexes the artifact's references */
52
+ put(artifact: Artifact, persist: boolean): Promise<void>;
53
+ /** forgets artifacts in the index; their records stay, so a refetch can reuse them */
54
+ forgetArtifacts(ids: readonly string[]): void;
55
+ /** records and projections held, with the version each is at, for an artifact request's `have` */
56
+ held(limit: number): Record<string, number>;
57
+ /**
58
+ * Applies tag versions learned from a sync. A record is dropped when its tag moved past its
59
+ * version. A projection is dropped when a tag it reads did, or when a projection it references
60
+ * was. Artifacts that reference anything dropped are reported, not removed: the replica owns them.
61
+ */
62
+ invalidate(changed: Readonly<Record<string, number>>): Promise<Invalidated>;
63
+ /** forgets everything in memory and in storage */
64
+ clear(): Promise<void>;
65
+ /** the artifact with every reference replaced by what the graph holds */
66
+ materialize(artifact: Artifact): Promise<Materialized>;
67
+ }