@drupflare/spool 0.4.0 → 1.0.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 (162) hide show
  1. package/README.md +206 -1756
  2. package/dist/angular/index.d.ts +13 -0
  3. package/dist/angular/index.js +25 -0
  4. package/dist/angular/pages.d.ts +28 -0
  5. package/dist/angular/pages.js +85 -0
  6. package/dist/cdn/client.js +1 -1
  7. package/dist/cdn/location.d.ts +6 -0
  8. package/dist/cdn/location.js +8 -0
  9. package/dist/cdn/manifest.json +7 -7
  10. package/dist/cdn/spool-sw.js +1 -1
  11. package/dist/client/bootstrap.d.ts +57 -0
  12. package/dist/client/bootstrap.js +307 -0
  13. package/dist/client/contact.d.ts +24 -0
  14. package/dist/client/contact.js +66 -0
  15. package/dist/client/declared.d.ts +23 -0
  16. package/dist/client/declared.js +68 -0
  17. package/dist/client/entry.js +91 -2
  18. package/dist/client/gate.d.ts +1 -0
  19. package/dist/client/gate.js +148 -0
  20. package/dist/client/index.d.ts +25 -0
  21. package/dist/client/index.js +1 -0
  22. package/dist/client/live.d.ts +66 -0
  23. package/dist/client/live.js +225 -0
  24. package/dist/client/navigate-entry.d.ts +1 -0
  25. package/dist/client/navigate-entry.js +4 -0
  26. package/dist/client/navigate.d.ts +54 -0
  27. package/dist/client/navigate.js +272 -0
  28. package/dist/client/persist.d.ts +2 -0
  29. package/dist/client/persist.js +9 -0
  30. package/dist/client/register.d.ts +11 -1
  31. package/dist/client/register.js +19 -8
  32. package/dist/express/index.d.ts +11 -0
  33. package/dist/express/index.js +209 -0
  34. package/dist/hono/index.d.ts +19 -0
  35. package/dist/hono/index.js +49 -0
  36. package/dist/next/index.d.ts +33 -0
  37. package/dist/next/index.js +41 -0
  38. package/dist/next/pages.d.ts +22 -0
  39. package/dist/next/pages.js +39 -0
  40. package/dist/node/listener.d.ts +3 -0
  41. package/dist/node/listener.js +57 -2
  42. package/dist/nuxt/index.d.ts +22 -0
  43. package/dist/nuxt/index.js +104 -0
  44. package/dist/nuxt/pages.d.ts +26 -0
  45. package/dist/nuxt/pages.js +48 -0
  46. package/dist/nuxt/runtime/index.d.ts +24 -0
  47. package/dist/nuxt/runtime/index.js +58 -0
  48. package/dist/plugins/coverage.d.ts +14 -0
  49. package/dist/plugins/coverage.js +27 -0
  50. package/dist/plugins/mode.d.ts +19 -0
  51. package/dist/plugins/mode.js +20 -0
  52. package/dist/plugins/path.d.ts +16 -0
  53. package/dist/plugins/path.js +139 -0
  54. package/dist/plugins/report.d.ts +22 -0
  55. package/dist/plugins/report.js +18 -0
  56. package/dist/plugins/routes.d.ts +38 -0
  57. package/dist/plugins/routes.js +52 -0
  58. package/dist/plugins/static.d.ts +42 -0
  59. package/dist/plugins/static.js +97 -0
  60. package/dist/protocol/bundle.d.ts +111 -0
  61. package/dist/protocol/bundle.js +428 -0
  62. package/dist/protocol/config.d.ts +65 -1
  63. package/dist/protocol/config.js +28 -0
  64. package/dist/protocol/dataset.d.ts +6 -0
  65. package/dist/protocol/dataset.js +6 -0
  66. package/dist/protocol/envelope.d.ts +33 -1
  67. package/dist/protocol/envelope.js +15 -1
  68. package/dist/protocol/errors.d.ts +1 -1
  69. package/dist/protocol/index-rows.d.ts +22 -0
  70. package/dist/protocol/index-rows.js +53 -0
  71. package/dist/protocol/index.d.ts +2 -0
  72. package/dist/protocol/index.js +2 -0
  73. package/dist/protocol/normalise.d.ts +4 -4
  74. package/dist/protocol/normalise.js +9 -5
  75. package/dist/protocol/ring.d.ts +58 -0
  76. package/dist/protocol/ring.js +6 -0
  77. package/dist/protocol/route.d.ts +57 -11
  78. package/dist/protocol/route.js +95 -3
  79. package/dist/protocol/tag.d.ts +22 -2
  80. package/dist/protocol/tag.js +25 -4
  81. package/dist/protocol/view.d.ts +2 -0
  82. package/dist/protocol/view.js +8 -2
  83. package/dist/protocol/views.d.ts +6 -0
  84. package/dist/protocol/views.js +15 -0
  85. package/dist/protocol/write.d.ts +92 -4
  86. package/dist/protocol/write.js +251 -9
  87. package/dist/proxy/eligible.d.ts +22 -1
  88. package/dist/proxy/eligible.js +62 -15
  89. package/dist/proxy/proxy.js +28 -18
  90. package/dist/react-router/index.d.ts +20 -0
  91. package/dist/react-router/index.js +60 -0
  92. package/dist/react-router/pages.d.ts +34 -0
  93. package/dist/react-router/pages.js +83 -0
  94. package/dist/report/demand.d.ts +49 -0
  95. package/dist/report/demand.js +60 -0
  96. package/dist/report/economics.d.ts +55 -0
  97. package/dist/report/economics.js +189 -0
  98. package/dist/report/headline.d.ts +158 -0
  99. package/dist/report/headline.js +473 -0
  100. package/dist/report/index.d.ts +2 -0
  101. package/dist/report/index.js +2 -0
  102. package/dist/report/inputs.d.ts +79 -0
  103. package/dist/report/inputs.js +115 -0
  104. package/dist/report/measurement.d.ts +1 -1
  105. package/dist/report/measurement.js +5 -1
  106. package/dist/report/traffic.d.ts +8 -0
  107. package/dist/report/traffic.js +7 -0
  108. package/dist/server/bundle.d.ts +55 -0
  109. package/dist/server/bundle.js +172 -0
  110. package/dist/server/dataset.d.ts +8 -2
  111. package/dist/server/dataset.js +51 -4
  112. package/dist/server/embedded.d.ts +7 -3
  113. package/dist/server/embedded.js +7 -3
  114. package/dist/server/index.d.ts +5 -1
  115. package/dist/server/index.js +5 -1
  116. package/dist/server/live-sockets.d.ts +54 -0
  117. package/dist/server/live-sockets.js +131 -0
  118. package/dist/server/live.d.ts +146 -0
  119. package/dist/server/live.js +228 -0
  120. package/dist/server/ring.d.ts +77 -0
  121. package/dist/server/ring.js +311 -0
  122. package/dist/server/spool.d.ts +139 -4
  123. package/dist/server/spool.js +457 -28
  124. package/dist/server/static.d.ts +42 -0
  125. package/dist/server/static.js +29 -0
  126. package/dist/server/stub.d.ts +43 -5
  127. package/dist/server/stub.js +126 -8
  128. package/dist/server/write.d.ts +23 -1
  129. package/dist/server/write.js +96 -0
  130. package/dist/stores/durable-object.d.ts +46 -0
  131. package/dist/stores/durable-object.js +114 -0
  132. package/dist/sw/analytics.d.ts +1 -1
  133. package/dist/sw/analytics.js +2 -2
  134. package/dist/sw/coverage.d.ts +6 -0
  135. package/dist/sw/coverage.js +34 -0
  136. package/dist/sw/family.d.ts +15 -0
  137. package/dist/sw/family.js +48 -0
  138. package/dist/sw/idb.d.ts +2 -0
  139. package/dist/sw/idb.js +2 -2
  140. package/dist/sw/index.d.ts +2 -0
  141. package/dist/sw/index.js +1 -0
  142. package/dist/sw/pack/store.d.ts +128 -0
  143. package/dist/sw/pack/store.js +737 -0
  144. package/dist/sw/policy.d.ts +2 -0
  145. package/dist/sw/policy.js +11 -0
  146. package/dist/sw/probe.d.ts +16 -0
  147. package/dist/sw/probe.js +25 -0
  148. package/dist/sw/router.d.ts +3 -2
  149. package/dist/sw/router.js +15 -2
  150. package/dist/sw/runtime.d.ts +48 -1
  151. package/dist/sw/runtime.js +548 -68
  152. package/dist/sw/scheduler.d.ts +6 -1
  153. package/dist/sw/scheduler.js +22 -5
  154. package/dist/sw/write.d.ts +41 -1
  155. package/dist/sw/write.js +188 -5
  156. package/dist/version.d.ts +1 -1
  157. package/dist/version.js +1 -2
  158. package/dist/vite/index.d.ts +26 -0
  159. package/dist/vite/index.js +66 -0
  160. package/dist/vue/index.d.ts +36 -0
  161. package/dist/vue/index.js +53 -0
  162. package/package.json +64 -4
@@ -0,0 +1,311 @@
1
+ import { readBundle } from '../protocol/bundle.js';
2
+ import { BUNDLE_PREFIX, COOKIES } from '../protocol/config.js';
3
+ import { DELTA_ELEMENT_ID, RING_ELEMENT_ID, WRITES_ELEMENT_ID } from '../protocol/ring.js';
4
+ import { matchRoute, serializeRoute } from '../protocol/route.js';
5
+ /** the ring's byte budget when `createSpool` names none; a default, not measured */
6
+ export const RING_BYTES = 24_576;
7
+ const encoder = new TextEncoder();
8
+ const bytesOf = (text) => encoder.encode(text).length;
9
+ const pathIndexes = new WeakMap();
10
+ /** each dataset's `path:<dataset>` rows by row key, so a row finds its concrete paths */
11
+ function pathIndex(tables) {
12
+ const held = pathIndexes.get(tables);
13
+ if (held)
14
+ return held;
15
+ const out = new Map();
16
+ for (const [name, rows] of Object.entries(tables)) {
17
+ if (!name.startsWith('path:'))
18
+ continue;
19
+ const byKey = new Map();
20
+ for (const [path, value] of rows) {
21
+ const key = String(value['key']);
22
+ byKey.set(key, [...(byKey.get(key) ?? []), [name, path, value]]);
23
+ }
24
+ out.set(name.slice('path:'.length), byKey);
25
+ }
26
+ pathIndexes.set(tables, out);
27
+ return out;
28
+ }
29
+ function rowAt(rows, key) {
30
+ if (!rows)
31
+ return undefined;
32
+ let low = 0;
33
+ let high = rows.length - 1;
34
+ while (low <= high) {
35
+ const mid = (low + high) >> 1;
36
+ const entry = rows[mid];
37
+ if (!entry)
38
+ return undefined;
39
+ if (entry[0] === key)
40
+ return entry[1];
41
+ if (entry[0] < key)
42
+ low = mid + 1;
43
+ else
44
+ high = mid - 1;
45
+ }
46
+ return undefined;
47
+ }
48
+ /** a row with its concrete paths and its query row: everything a page of it needs from the pack */
49
+ function recordOf(tables, paths, dataset, key) {
50
+ const row = rowAt(tables[dataset], key);
51
+ if (row === undefined)
52
+ return undefined;
53
+ const query = rowAt(tables[`query:${dataset}`], key);
54
+ return [
55
+ [dataset, key, row],
56
+ ...(paths.get(dataset)?.get(key) ?? []),
57
+ ...(query === undefined ? [] : [[`query:${dataset}`, key, query]])
58
+ ];
59
+ }
60
+ /** the rows a page joins, one record each, in the order the plan declares its joins */
61
+ function joinedOf(tables, paths, route, row) {
62
+ const out = [];
63
+ for (const join of route.query?.plan?.join ?? []) {
64
+ const [from, to] = join.on;
65
+ const value = row[from];
66
+ if (value === undefined)
67
+ continue;
68
+ if (to === null) {
69
+ const record = typeof value === 'string'
70
+ ? recordOf(tables, paths, join.dataset, value)
71
+ : undefined;
72
+ if (record)
73
+ out.push(record);
74
+ continue;
75
+ }
76
+ for (const [key, other] of tables[join.dataset] ?? []) {
77
+ if (other[to] !== value)
78
+ continue;
79
+ const record = recordOf(tables, paths, join.dataset, key);
80
+ if (record)
81
+ out.push(record);
82
+ }
83
+ }
84
+ return out;
85
+ }
86
+ /** every string value of a row, in the order the row holds them */
87
+ function stringsOf(value, out = []) {
88
+ if (typeof value === 'string')
89
+ out.push(value);
90
+ else if (Array.isArray(value))
91
+ for (const item of value)
92
+ stringsOf(item, out);
93
+ else if (value && typeof value === 'object') {
94
+ for (const item of Object.values(value))
95
+ stringsOf(item, out);
96
+ }
97
+ return out;
98
+ }
99
+ /** the public family and query routes a ring or a boot script carries, serialized, with their templates */
100
+ function ringRoutes(declared) {
101
+ const routes = declared.filter((route) => route.scope === 'public' && (route.family || route.query));
102
+ const templates = Object.fromEntries(routes.flatMap((route) => route.template ? [[route.pattern, route.template]] : []));
103
+ return { routes, serialized: routes.map(serializeRoute), templates };
104
+ }
105
+ /** the shape of `declared`; its id is 12 hex characters of the SHA-256 of the routes and templates */
106
+ export async function bootShape(declared) {
107
+ const { serialized, templates } = ringRoutes(declared);
108
+ const hash = await crypto.subtle.digest('SHA-256', encoder.encode(JSON.stringify([serialized, templates])));
109
+ const id = [...new Uint8Array(hash).subarray(0, 6)]
110
+ .map((byte) => byte.toString(16).padStart(2, '0'))
111
+ .join('');
112
+ return { id, routes: serialized, templates };
113
+ }
114
+ /**
115
+ * Builds the ring for one family page: its row and the rows its links reach, breadth first, until
116
+ * the next record would pass `ringBytes`. The entry row, the routes and their templates are always
117
+ * held: they count against the budget but are never dropped. Returns `undefined` for a path no
118
+ * public family route matches, or whose row the pack does not hold. A `slim` ring does not depend
119
+ * on the page: it is the same for every path, and `undefined` only when no public route reads data.
120
+ */
121
+ export function buildRing(options) {
122
+ const { routes, serialized, templates } = ringRoutes(options.routes);
123
+ const writes = options.writes ?? [];
124
+ const worker = {
125
+ worker: options.worker === 'never' ? 'never' : 'auto',
126
+ ...(options.worker === 'always' ? { webkitWorker: true } : {})
127
+ };
128
+ if (options.slim) {
129
+ if (routes.length === 0)
130
+ return undefined;
131
+ return {
132
+ protocol: 1,
133
+ version: options.version,
134
+ digest: options.digest,
135
+ tables: {},
136
+ complete: false,
137
+ bootstrap: options.bootstrap,
138
+ ...worker,
139
+ ...(options.boot ? { boot: options.boot } : {}),
140
+ ...(options.lease === undefined ? {} : { lease: options.lease }),
141
+ pack: { url: `${BUNDLE_PREFIX}${options.version}`, bytes: options.packBytes },
142
+ ...(writes.length > 0 ? { writes: [...writes] } : {})
143
+ };
144
+ }
145
+ const entry = matchRoute(routes, options.path);
146
+ const family = entry?.route.family;
147
+ if (!entry || !family)
148
+ return undefined;
149
+ const tables = options.tables;
150
+ const paths = pathIndex(tables);
151
+ const rowKey = entry.params[family.key];
152
+ const first = rowKey === undefined ? undefined : recordOf(tables, paths, family.dataset, rowKey);
153
+ if (!first)
154
+ return undefined;
155
+ const held = new Map();
156
+ let used = bytesOf(JSON.stringify(serialized)) +
157
+ bytesOf(JSON.stringify(templates)) +
158
+ bytesOf(JSON.stringify(writes));
159
+ const admit = (record, force = false) => {
160
+ const fresh = record.filter(([table, key]) => !held.get(table)?.has(key));
161
+ const size = fresh.reduce((sum, [, key, row]) => sum + bytesOf(JSON.stringify([key, row])), 0);
162
+ if (!force && used + size > options.ringBytes)
163
+ return false;
164
+ for (const [table, key, row] of fresh) {
165
+ const rows = held.get(table) ?? new Map();
166
+ rows.set(key, row);
167
+ held.set(table, rows);
168
+ }
169
+ used += size;
170
+ return true;
171
+ };
172
+ admit(first, true);
173
+ const seen = new Set([`${family.dataset}\n${rowKey}`]);
174
+ const pages = [
175
+ { route: entry.route, row: first[0]?.[2] ?? {} }
176
+ ];
177
+ let open = true;
178
+ for (let i = 0; i < pages.length && open; i++) {
179
+ const page = pages[i];
180
+ for (const record of joinedOf(tables, paths, page.route, page.row)) {
181
+ if (!admit(record)) {
182
+ open = false;
183
+ break;
184
+ }
185
+ }
186
+ for (const value of stringsOf(page.row)) {
187
+ if (!open)
188
+ break;
189
+ const path = value.split(/[?#]/)[0] ?? '';
190
+ const hit = path.startsWith('/') ? matchRoute(routes, path) : null;
191
+ const linked = hit?.route.family;
192
+ const key = linked ? hit?.params[linked.key] : undefined;
193
+ if (!hit || !linked || key === undefined)
194
+ continue;
195
+ const id = `${linked.dataset}\n${key}`;
196
+ if (seen.has(id))
197
+ continue;
198
+ const record = recordOf(tables, paths, linked.dataset, key);
199
+ if (!record)
200
+ continue;
201
+ if (!admit(record)) {
202
+ open = false;
203
+ break;
204
+ }
205
+ seen.add(id);
206
+ pages.push({ route: hit.route, row: record[0]?.[2] ?? {} });
207
+ }
208
+ }
209
+ const out = {};
210
+ let heldRows = 0;
211
+ for (const [table, rows] of held) {
212
+ const sorted = [...rows].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
213
+ out[table] = sorted;
214
+ heldRows += sorted.length;
215
+ }
216
+ const totalRows = Object.values(tables).reduce((sum, rows) => sum + rows.length, 0);
217
+ const complete = heldRows === totalRows;
218
+ const ring = {
219
+ protocol: 1,
220
+ version: options.version,
221
+ digest: options.digest,
222
+ routes: serialized,
223
+ templates,
224
+ tables: out,
225
+ complete,
226
+ bootstrap: options.bootstrap,
227
+ ...worker,
228
+ ...(options.boot ? { boot: options.boot } : {}),
229
+ ...(options.lease === undefined ? {} : { lease: options.lease }),
230
+ ...(writes.length > 0 ? { writes: [...writes] } : {})
231
+ };
232
+ if (!complete)
233
+ ring.pack = { url: `${BUNDLE_PREFIX}${options.version}`, bytes: options.packBytes };
234
+ return ring;
235
+ }
236
+ /**
237
+ * The paths a click may load the boot script for: the part of each public template family
238
+ * pattern before its first parameter, and `?` plus the path of each list that answers a query
239
+ * string. The page runtime answers only these, so a click anywhere else stays a document load.
240
+ */
241
+ export function gatePaths(routes) {
242
+ const out = new Set();
243
+ for (const route of routes) {
244
+ if (route.scope !== 'public' || route.strategy !== 'template' || !route.template)
245
+ continue;
246
+ if (route.navigation === 'document')
247
+ continue;
248
+ const param = route.pattern.search(/:|\*\*/);
249
+ let path = '';
250
+ if (route.family)
251
+ path = param < 0 ? route.pattern : route.pattern.slice(0, param);
252
+ else if (param < 0 &&
253
+ route.query?.dataset !== undefined &&
254
+ route.query.plan === undefined) {
255
+ path = `?${route.pattern}`;
256
+ }
257
+ if (path && !/\s/.test(path))
258
+ out.add(path);
259
+ }
260
+ return [...out];
261
+ }
262
+ /** the script element that carries the declared writes of a page with no ring; `<` becomes a `\u` escape */
263
+ export function writesElement(writes) {
264
+ const json = JSON.stringify(writes).replace(/</g, '\\u003c');
265
+ return `<script type="application/json" id="${WRITES_ELEMENT_ID}">${json}</script>`;
266
+ }
267
+ /** the script element that carries `ring`; `<` becomes a `\u` escape, so no row can close it */
268
+ export function ringElement(ring) {
269
+ const json = JSON.stringify(ring).replace(/</g, '\\u003c');
270
+ return `<script type="application/json" id="${RING_ELEMENT_ID}">${json}</script>`;
271
+ }
272
+ /** the held version a request names in its cookie, or undefined */
273
+ export function heldVersion(cookie) {
274
+ const match = cookie && new RegExp(`(?:^|;\\s*)${COOKIES.held}=(\\d{1,15})(?:;|$)`).exec(cookie);
275
+ return match ? Number(match[1]) : undefined;
276
+ }
277
+ /** the script element that carries the delta from `from` to `to`; no `text` makes a pointer the client fetches */
278
+ export function deltaElement(from, to, text) {
279
+ const json = (text ?? '').replace(/</g, '\\u003c');
280
+ return `<script type="application/json" id="${DELTA_ELEMENT_ID}" data-from="${from}" data-to="${to}">${json}</script>`;
281
+ }
282
+ /** `html` with `element` before `</head>`, else before `</body>`, else at the end */
283
+ export function placeRing(html, element) {
284
+ for (const close of [/<\/head\s*>/i, /<\/body\s*>/i]) {
285
+ const at = html.search(close);
286
+ if (at >= 0)
287
+ return html.slice(0, at) + element + html.slice(at);
288
+ }
289
+ return html + element;
290
+ }
291
+ /**
292
+ * The pack the store holds at a version, read once and kept until the version moves. A version
293
+ * with no stored pack answers `undefined` and is not kept.
294
+ */
295
+ export function ringPacks(bundles) {
296
+ let held;
297
+ return async (version) => {
298
+ if (held?.version === version)
299
+ return held.pack;
300
+ const bytes = await bundles.get(version);
301
+ if (bytes === undefined)
302
+ return undefined;
303
+ const pack = readBundle(bytes).then(({ index, state }) => ({
304
+ digest: index.digest,
305
+ tables: state.tables,
306
+ bytes: bytes.length
307
+ }));
308
+ held = { version, pack };
309
+ return pack;
310
+ };
311
+ }
@@ -1,13 +1,17 @@
1
1
  import { type CollectorConfig } from '../protocol/collector.js';
2
2
  import { type AssetMode, type ProvisionConfig, type SwConfig, type ThirdPartyConfig } from '../protocol/config.js';
3
3
  import type { Dataset } from '../protocol/dataset.js';
4
+ import { type BootstrapGate, type WorkerMode } from '../protocol/ring.js';
4
5
  import { type Route } from '../protocol/route.js';
5
6
  import type { Mode } from '../protocol/view.js';
6
- import { type Write } from '../protocol/write.js';
7
+ import { type Resource, type Write } from '../protocol/write.js';
7
8
  import type { VersionStore } from '../stores/version-store.js';
9
+ import { type BundleStore } from './bundle.js';
8
10
  import { type IdentityOptions } from './identity.js';
11
+ import { type LiveOptions } from './live.js';
9
12
  import type { Sink } from './sink.js';
10
13
  import { type Sizer } from './size.js';
14
+ import { type PublishStaticOptions, type PublishStaticResult, type StaticSink } from './static.js';
11
15
  import type { WorkSeries } from './work.js';
12
16
  /** most changed tags a response carries inline before the worker is left to ask `/.spool/sync` */
13
17
  export declare const MAX_PIGGYBACK = 32;
@@ -16,6 +20,12 @@ export declare const MAX_CATALOGUE_BUILD = 32;
16
20
  /** what `createSpool` takes */
17
21
  export type SpoolOptions = {
18
22
  routes: readonly Route[];
23
+ /**
24
+ * Resources from `defineResource`: their item families join `routes`, and their writes are sent to
25
+ * the server and answered with the rows they changed as `Spool-Delta`. Needs `bundles` for the
26
+ * device to keep its pack current; the writes themselves work without it.
27
+ */
28
+ resources?: readonly Resource[];
19
29
  store: VersionStore;
20
30
  /** public datasets `/.spool/dataset` answers, each by its own name */
21
31
  datasets?: readonly Dataset[];
@@ -41,10 +51,21 @@ export type SpoolOptions = {
41
51
  * serve the page runtime from a CDN with SRI; omitted, it is served from
42
52
  * `/.spool/<version>/client.js`. `url` defaults to this version's `cdn.drupflare.com` build,
43
53
  * whose `integrity` is in the release notes and in `dist/cdn/manifest.json`.
54
+ *
55
+ * `worker` also moves the worker core to the CDN: the stub becomes the config and one
56
+ * `importScripts` line, a few KB in place of the core, and the core is fetched from
57
+ * `worker.url`, or from this version's `cdn.drupflare.com` build when `worker` is `true`. A
58
+ * browser has no integrity check for an imported script, so the site trusts the CDN host with a
59
+ * script that can answer every request of the origin. Off by default. A site with a custom
60
+ * `worker` bundle must give `worker.url`. `publishStatic` checks the served bytes with
61
+ * `verifyCore`.
44
62
  */
45
63
  cdn?: {
46
64
  url?: string;
47
65
  integrity: string;
66
+ worker?: boolean | {
67
+ url: string;
68
+ };
48
69
  };
49
70
  /** same-origin POST paths the worker queues and flushes in one request */
50
71
  beacons?: readonly string[];
@@ -52,7 +73,10 @@ export type SpoolOptions = {
52
73
  mode?: Mode;
53
74
  /** the share of views, 0 to 1, that run in shadow while the mode is `serve`; default 0 */
54
75
  shadowSample?: number;
55
- /** whether the worker queues a `spool.view` per page view; default true */
76
+ /**
77
+ * whether the worker queues a `spool.view` per page view; default true with a `sink`, false
78
+ * without one
79
+ */
56
80
  views?: boolean;
57
81
  /** records the time each request took, by route; read it with `work.samples()` */
58
82
  work?: WorkSeries;
@@ -93,6 +117,77 @@ export type SpoolOptions = {
93
117
  * renderers)` from `@drupflare/spool/sw`; it finds the config in `self.__SPOOL_CONFIG__`
94
118
  */
95
119
  worker?: string;
120
+ /** where `buildBundle` keeps packs; `GET /.spool/bundle/<version>` answers 404 without it */
121
+ bundles?: BundleStore;
122
+ /**
123
+ * `maxAge`, in seconds, is the lease of `/spool-sw.js` in the browser's cache; default one day.
124
+ * A check inside it costs nothing, and after it one request brings the version and its changes.
125
+ * A floor applies on top of the lease: Chromium checked the stub on the first document navigation
126
+ * after each 24 hours whatever `maxAge` was (measured in Chromium only, with the wall clock shifted),
127
+ * so a lease longer than a day does not cut the checks. A stub that changed at that check installs,
128
+ * which is the contact.
129
+ */
130
+ freshness?: {
131
+ maxAge?: number;
132
+ };
133
+ /**
134
+ * A counter the stub carries, a non-negative integer or a function that returns one, read on each stub
135
+ * request. The stub's bytes change when it does, so advance it at each publish or each lease period.
136
+ * Absent, the stub's bytes are the same as before the option existed.
137
+ */
138
+ stamp?: number | (() => number);
139
+ /**
140
+ * Options for the packs `publish` builds. `ringBytes` is the budget of the ring on each
141
+ * family page, default 24,576 and not measured. `blockRows` is rows per block, default 128.
142
+ * `maxBytes` is the most compressed bytes of one block, at most the reader's frame cap.
143
+ */
144
+ bundle?: {
145
+ ringBytes?: number;
146
+ blockRows?: number;
147
+ maxBytes?: number;
148
+ };
149
+ /**
150
+ * Security headers a pack or delta response names for a device that holds no site policy. Names
151
+ * are limited to the policy list. Default: the headers of the last HTML page this server answered.
152
+ * `{}` names no headers. With neither, `publishStatic` writes a stub with no policy field.
153
+ */
154
+ policy?: Record<string, string>;
155
+ /**
156
+ * When the device fetches the pack: `second-view` on the second view, the default, or `first-view`.
157
+ * The ring in the first document is the same either way.
158
+ */
159
+ bootstrap?: BootstrapGate;
160
+ /**
161
+ * How a second-view page loads the runtime. `inline` (default) puts a small gate in place of the
162
+ * script tag. The gate waits for the first click or GET form submit that the held pages answer,
163
+ * then loads one script that carries the runtime and the pack, in place of the document that
164
+ * click would have fetched, so a visitor never makes more requests than the site without
165
+ * spool. A page with no ring, or whose ring names no boot script (`cdn` is set), loads the
166
+ * runtime from the second view. `script` keeps the tag, for a page whose CSP forbids inline
167
+ * scripts. A first-view site always uses the tag.
168
+ */
169
+ clientTag?: 'inline' | 'script';
170
+ /**
171
+ * `never` keeps every read in the page: the ring names no worker and the page registers none.
172
+ * `auto` (default) registers the worker, except on WebKit for a page that carries a ring: WebKit
173
+ * checks the worker script on each navigation (WebKit bug 332455), so those pages keep every
174
+ * read in the page. `always` registers the worker on WebKit too.
175
+ */
176
+ workerMode?: WorkerMode;
177
+ /**
178
+ * The stream a visible page holds open at `/.spool/live`, for the principal lease and its
179
+ * revocation and, with `public`, for pushed tag changes. A page with a principal partition and a
180
+ * stream sends no renewal while it reads, and a revoked session reaches it in milliseconds. `false`
181
+ * is off; `true` and an object are on; absent, it is on when `identity` is set on a host that is one
182
+ * process (Node, Bun, Deno) and off on Workers, where the stream needs a hub every isolate can
183
+ * reach: pass `durableObjectHub` from `@drupflare/spool/stores/durable-object`. A page without
184
+ * the stream renews at its route's bound as before. The default is off for public freshness.
185
+ * By default the policy is adaptive: the first lease renewal of a visible session is an ordinary
186
+ * request and the second becomes the stream, so a visitor who loads documents never opens one.
187
+ * `'always'` (or `{ mode: 'always' }`) opens at login and whenever a tab becomes visible, for an
188
+ * app that stays open.
189
+ */
190
+ live?: boolean | 'always' | LiveOptions;
96
191
  };
97
192
  /** per-call overrides for {@link Spool.decorate} */
98
193
  export type DecorateOptions = {
@@ -109,6 +204,8 @@ export type DecorateOptions = {
109
204
  * `assembly` route and the body is tagged HTML.
110
205
  */
111
206
  assembled?: string;
207
+ /** set when the caller has judged the response, so `decorate` skips the public-route gate */
208
+ judged?: boolean;
112
209
  };
113
210
  /** what `createSpool` returns */
114
211
  export type Spool = {
@@ -116,20 +213,58 @@ export type Spool = {
116
213
  handle(request: Request, next: (request: Request) => Response | Promise<Response>): Promise<Response>;
117
214
  /** a `Response` for `/.spool/*`, `undefined` for anything else */
118
215
  respond(request: Request): Promise<Response | undefined>;
119
- /** adds the envelope headers and the client tag to a response the app produced */
216
+ /**
217
+ * adds the envelope headers and the client tag to a response the app produced. A public route's
218
+ * response that sets a cookie, is `private` or `no-store`, or varies by anything but encoding and
219
+ * cookies is returned unchanged.
220
+ */
120
221
  decorate(request: Request, response: Response, options?: DecorateOptions): Promise<Response>;
121
222
  /** bumps the vector after a write; `drop` also removes artifacts by id */
122
223
  invalidate(tags: readonly string[], options?: {
123
224
  drop?: readonly string[];
124
225
  }): Promise<number>;
226
+ /**
227
+ * Builds the pack at the store cursor and keeps it in `bundles`.
228
+ * Returns `{ version, bytes }`. A version already holding other
229
+ * bytes is refused, so call `invalidate` after a data change.
230
+ * `url` is what the seed functions receive.
231
+ */
232
+ publish(url: URL): Promise<{
233
+ version: number;
234
+ bytes: number;
235
+ }>;
236
+ /**
237
+ * Writes the static tier to `sink`: the page runtime, the stub, the packs held for the store cursor and
238
+ * the deltas to it, and a `_headers` file. A host that serves these files answers them with no Worker
239
+ * invocation. Packs and runtime are immutable, so a sink that reports them with `has` keeps the ones
240
+ * already there. Build the packs with `publish` first. Each pack also gets its boot script, unless `cdn` is set.
241
+ * The stub names the site policy in this order: `options.policy`, the `policy` option of
242
+ * `createSpool`, the headers of the last HTML page answered, `options.fallbackPolicy`. With none of
243
+ * them the stub carries no `policy` field, and a device renders locally after one network view that
244
+ * teaches it the headers; `policy: 'none'` in the result says so. `{}` names a known-empty policy.
245
+ * `options.url` builds the pack at the cursor first. Returns the store cursor, the paths written
246
+ * and the policy source.
247
+ */
248
+ publishStatic(sink: StaticSink, options?: PublishStaticOptions): Promise<PublishStaticResult>;
125
249
  /**
126
250
  * The `Spool-Partition` value for a principal. A login or account-switch handler sets it on its
127
251
  * own response, since the request it answers still carries the old identity: the worker then
128
252
  * swaps its store before any local view can read the old one.
129
253
  */
130
254
  partition(principal: string): Promise<string>;
131
- /** the `/spool-sw.js` response */
255
+ /**
256
+ * Ends the live streams of a principal's partition: each gets `revoked` and closes, and the page
257
+ * wipes the partition. Call it where the app ends a session on the server (a ban, a logout on
258
+ * another device, a sweep of expired sessions). It does nothing while `live` is off.
259
+ */
260
+ revoke(principal: string): Promise<void>;
261
+ /**
262
+ * The `/spool-sw.js` response. Pass the request to get an `ETag` and a `304` for a matching
263
+ * `If-None-Match`, so a re-check of an unchanged script after the lease costs a few hundred bytes.
264
+ * With no request the response has no validator, as before.
265
+ */
132
266
  stub(): Response;
267
+ stub(request: Request): Promise<Response>;
133
268
  /** the config embedded in the worker script */
134
269
  readonly config: SwConfig;
135
270
  };