@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
@@ -347,3 +347,118 @@ export const HOSTING_KWH_PER_SITE = {
347
347
  source: 'drupflare/worker docs/impact/energy/production-baseline.md: worst case, one small VPS, 2 vCPU, 15%'
348
348
  }
349
349
  };
350
+ const count = (value, column, term) => ({
351
+ value,
352
+ unit: 'requests',
353
+ layer: 'L1',
354
+ source: `review/model.json, column "${column}", ${term}`
355
+ });
356
+ const review = (value, what) => ({
357
+ value,
358
+ unit: 'requests',
359
+ layer: 'L1',
360
+ source: `review/REVIEW.md section 3, ${what}; Chromium, Firefox and WebKit; measured on 2026-11-18`
361
+ });
362
+ /** the request-law constants of `Q`, each a count from review/model.json or the review's constants table */
363
+ export const DEMAND = {
364
+ bootstrapWorker: count(2, 'min worker, Chromium', 'k'),
365
+ bootstrapNoWorker: count(1, 'min no worker, any engine', 'k'),
366
+ contact: count(1, 'min worker, Chromium', 'x'),
367
+ contactInLease: review(0, '"contact inside the lease", min worker column'),
368
+ write: review(1, '"write" row, min worker column'),
369
+ inPage: review(0, '"in-page view" row, min worker column'),
370
+ coldChromium: count(1, 'min worker, Chromium', 'cold'),
371
+ coldRoute: count(0, 'min worker + route, Chromium', 'cold'),
372
+ coldFirefox: count(0, 'min worker, Firefox', 'cold'),
373
+ coldWebkitMac: count(2, 'min worker, WebKit macOS', 'cold'),
374
+ coldWebkitLinux: count(1, 'min worker, WebKit Linux', 'cold'),
375
+ coldTls: {
376
+ value: 0,
377
+ unit: 'requests',
378
+ layer: 'L1',
379
+ source: 'review/REVIEW.md section 8, six cold restarts per engine against the deployed Worker; Chromium, Firefox and WebKit; measured on 2026-11-18; the count is Worker invocations'
380
+ },
381
+ warmChromium: count(0, 'min worker, Chromium', 'warm'),
382
+ warmFirefox: count(0, 'min worker, Firefox', 'warm'),
383
+ warmWebkitMac: count(1, 'min worker, WebKit macOS', 'warm'),
384
+ warmWebkitLinux: count(0, 'min worker, WebKit Linux', 'warm')
385
+ };
386
+ const retrofit = (value, unit, what) => ({
387
+ value,
388
+ unit,
389
+ layer: 'L1',
390
+ source: `drupflare Worker retrofit reading, ${what}`
391
+ });
392
+ /** counted views of the retrofit reading: one bootstrap, then the in-page and document views below */
393
+ export const RETROFIT_VIEWS = retrofit(121, 'views', 'counted views, warm static assets');
394
+ export const RETROFIT_IN_PAGE = retrofit(100, 'views', 'in-page views');
395
+ export const RETROFIT_DOCUMENTS = retrofit(20, 'views', 'document navigations');
396
+ /** requests that reached the origin over the retrofit views; WebKit includes its script check per navigation */
397
+ export const RETROFIT_ORIGIN = {
398
+ chromium: retrofit(4, 'requests', 'origin requests, Chromium'),
399
+ firefox: retrofit(4, 'requests', 'origin requests, Firefox'),
400
+ webkit: retrofit(23, 'requests', 'origin requests, WebKit')
401
+ };
402
+ /** Worker invocations over the retrofit views, per engine */
403
+ export const RETROFIT_WORKER = {
404
+ chromium: retrofit(4, 'calls', 'Worker invocations, Chromium'),
405
+ firefox: retrofit(4, 'calls', 'Worker invocations, Firefox'),
406
+ webkit: retrofit(6, 'calls', 'Worker invocations, WebKit')
407
+ };
408
+ const session = (value, what) => ({
409
+ value,
410
+ unit: 'views',
411
+ layer: 'L1',
412
+ source: `review/deploy/runs/2026-11-18T09-36-16-583Z/reading.json, ${what}; three engines; measured on 2026-11-18`
413
+ });
414
+ /** the deployed session of section 8: the rig's phases, one Worker invocation each for the first document */
415
+ export const SESSION = {
416
+ views: session(108, 'phases first-document, second-view-bootstrap, 100-held-reads, 5-documents and restart-document'),
417
+ heldReads: session(100, 'phase 100-held-reads'),
418
+ documents: session(5, 'phase 5-documents'),
419
+ restarts: session(1, 'phase restart-document')
420
+ };
421
+ const bench = (value, unit, what) => ({
422
+ value,
423
+ unit,
424
+ layer: 'L1',
425
+ source: `review/storage RESULTS.md, ${what}`
426
+ });
427
+ /** the device layouts at 1,000, 10,000 and 100,000 rows, on the M2 Pro bench */
428
+ export const STORAGE = {
429
+ rowsSmall: bench(1000, 'rows', 'synthetic site, 1,000 rows'),
430
+ rowsLarge: bench(10000, 'rows', 'synthetic site, 10,000 rows'),
431
+ rowsXl: bench(100000, 'rows', 'synthetic site, 100,000 rows, Chromium only'),
432
+ plainRowChromium: bench(794.3, 'B a row', '10k, usage, codex, Chromium'),
433
+ plainRowFirefox: bench(9373.2, 'B a row', '10k, usage, codex, Firefox'),
434
+ plainRowWebkit: bench(1754.5, 'B a row', '10k, usage, codex, WebKit'),
435
+ packedRowChromium: bench(121.2, 'B a row', '10k, usage, packed, Chromium'),
436
+ packedRowFirefox: bench(396.3, 'B a row', '10k, usage, packed, Firefox'),
437
+ packedRowWebkit: bench(115.4, 'B a row', '10k, usage, packed, WebKit'),
438
+ plainItemChromium: bench(61.7, 'ms', '10k, item p50, codex, Chromium'),
439
+ plainItemFirefox: bench(112, 'ms', '10k, item p50, codex, Firefox'),
440
+ plainItemWebkit: bench(65, 'ms', '10k, item p50, codex, WebKit'),
441
+ packedItemChromium: bench(1.7, 'ms', '10k, item p50, packed, Chromium'),
442
+ packedItemFirefox: bench(2, 'ms', '10k, item p50, packed, Firefox'),
443
+ packedItemWebkit: bench(2, 'ms', '10k, item p50, packed, WebKit'),
444
+ plainItemChromium100k: bench(675.3, 'ms', '100k, item p50, codex, Chromium'),
445
+ packedItemChromium100k: bench(2.7, 'ms', '100k, item p50, packed, Chromium'),
446
+ wirePacked: bench(1146591, 'B', '10k, wire, packed gzip blocks'),
447
+ wireBrotli: bench(293408, 'B', '10k, wire, one brotli stream of the plain seed')
448
+ };
449
+ const crawl = (value, unit, what) => ({
450
+ value,
451
+ unit,
452
+ layer: 'L1',
453
+ source: `review/radius RESULTS.md, ${what}`
454
+ });
455
+ /** the 300-page crawls behind the real-page figures; each total is summed over the pages */
456
+ export const CRAWL = {
457
+ pages: crawl(300, 'pages', 'max-pages cap, docs.drupflare.com and MDN Service Worker API'),
458
+ docsText: crawl(326886, 'B', 'solidBrotliBytes text, docs.drupflare.com, one stream'),
459
+ mdnText: crawl(532348, 'B', 'solidBrotliBytes text, MDN, one stream'),
460
+ docsHtml: crawl(505352, 'B', 'solidBrotliBytes html, docs.drupflare.com, one stream'),
461
+ mdnHtml: crawl(991858, 'B', 'solidBrotliBytes html, MDN, one stream'),
462
+ docsHtmlEach: crawl(1027054, 'B', 'brotliBytes per page, summed, docs.drupflare.com'),
463
+ mdnHtmlEach: crawl(5711674, 'B', 'brotliBytes per page, summed, MDN')
464
+ };
@@ -1,6 +1,6 @@
1
1
  import type { Layer } from './inputs.js';
2
2
  /** the rigs that write to `measurements/<rig>/`, one folder each */
3
- export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim", "link-assets", "image-crawl", "dictionary-size", "nav-replay", "first-payload", "embed-markup", "dataset-baseline", "avoidable-loops"];
3
+ export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim", "link-assets", "image-crawl", "dictionary-size", "nav-replay", "first-payload", "embed-markup", "dataset-baseline", "avoidable-loops", "storage", "demand", "examples", "static-host"];
4
4
  /** one of {@link RIGS} */
5
5
  export type Rig = (typeof RIGS)[number];
6
6
  /** the format version {@link parseMeasurement} reads */
@@ -15,7 +15,11 @@ export const RIGS = [
15
15
  'first-payload',
16
16
  'embed-markup',
17
17
  'dataset-baseline',
18
- 'avoidable-loops'
18
+ 'avoidable-loops',
19
+ 'storage',
20
+ 'demand',
21
+ 'examples',
22
+ 'static-host'
19
23
  ];
20
24
  /** the format version {@link parseMeasurement} reads */
21
25
  export const MEASUREMENT_SCHEMA = 1;
@@ -147,3 +147,11 @@ export declare function transitions(views: readonly TimedView[]): Transitions;
147
147
  export declare function nextShare(views: readonly TimedView[], from: string, options?: {
148
148
  first?: boolean;
149
149
  }): Record<string, number>;
150
+ /**
151
+ * The share `h` of a baseline's requests a deployment holds back, and its multiplier (baseline over
152
+ * requests), from the baseline request count and the requests that reached the origin.
153
+ */
154
+ export declare function retrofitRatio(baseline: number, requests: number): {
155
+ h: number;
156
+ multiplier: number;
157
+ };
@@ -236,3 +236,10 @@ export function nextShare(views, from, options = {}) {
236
236
  out[pair.route] = pair.views / total;
237
237
  return out;
238
238
  }
239
+ /**
240
+ * The share `h` of a baseline's requests a deployment holds back, and its multiplier (baseline over
241
+ * requests), from the baseline request count and the requests that reached the origin.
242
+ */
243
+ export function retrofitRatio(baseline, requests) {
244
+ return { h: 1 - requests / baseline, multiplier: baseline / requests };
245
+ }
@@ -0,0 +1,55 @@
1
+ import { type BundleIndex, type BundleRows } from '../protocol/bundle.js';
2
+ import type { Dataset } from '../protocol/dataset.js';
3
+ import type { Route } from '../protocol/route.js';
4
+ import type { BootShape } from './ring.js';
5
+ /** where built packs are kept, by version; a version's bytes never change once stored */
6
+ export interface BundleStore {
7
+ put(version: number, bytes: Uint8Array<ArrayBuffer>): Promise<void>;
8
+ get(version: number): Promise<Uint8Array<ArrayBuffer> | undefined>;
9
+ }
10
+ /** a store that lives as long as the process; fine for tests and single-instance Node */
11
+ export declare function memoryBundleStore(): BundleStore;
12
+ /** what `buildBundle` takes */
13
+ export type BuildBundleOptions = {
14
+ store: BundleStore;
15
+ /** the datasets given to createSpool; a principal dataset is left out, since a pack is public */
16
+ datasets: readonly Dataset[];
17
+ /** the version the pack is built for; the caller keeps it unique per content */
18
+ version: number;
19
+ /** the URL the datasets' seed functions receive; their path and origin only */
20
+ url: URL;
21
+ /** rows per block; the protocol default when absent */
22
+ blockRows?: number;
23
+ /** the routes the pack answers; their path and query index tables go into the pack */
24
+ routes?: readonly Route[];
25
+ /** most compressed bytes of one block; the frame cap a reader accepts when absent */
26
+ maxBytes?: number;
27
+ };
28
+ /** what `buildBundle` returns */
29
+ export type BuiltBundle = {
30
+ version: number;
31
+ index: BundleIndex;
32
+ bytes: Uint8Array<ArrayBuffer>;
33
+ };
34
+ /**
35
+ * The index tables the public routes need. A family route adds `path:<dataset>`, each row's
36
+ * concrete path mapped to its key. A query route adds `query:<dataset>`, each row's filter and sort
37
+ * fields. A plan, a principal route and a pattern with a param other than the key add nothing.
38
+ */
39
+ export declare function indexTables(routes: readonly Route[], tables: Record<string, BundleRows>): Record<string, BundleRows>;
40
+ /**
41
+ * Builds the pack of the public datasets at `version` and keeps it in `store`. A version that
42
+ * already holds other bytes is refused, since its URL is served as immutable. A site with no
43
+ * dataset builds an empty pack.
44
+ */
45
+ export declare function buildBundle(options: BuildBundleOptions): Promise<BuiltBundle>;
46
+ /** the response to `GET /.spool/bundle/<version>`: the pack bytes, or 404 for a version not held */
47
+ export declare function respondBundle(store: BundleStore | undefined, version: string): Promise<Response>;
48
+ /**
49
+ * The response to `GET /.spool/<runtime>/boot/<version>.js`: `code`, the page runtime and the
50
+ * navigation script, after a line that hands the pack at `version` to the runtime as base64. One
51
+ * script tag then installs the runtime and the pack in one request. With a `shape` the same line
52
+ * also hands over the routes and templates, so no document has to carry them. 404 for a version
53
+ * not held.
54
+ */
55
+ export declare function respondBoot(store: BundleStore | undefined, version: string, code: string, shape?: BootShape): Promise<Response>;
@@ -0,0 +1,172 @@
1
+ import { buildPack } from '../protocol/bundle.js';
2
+ import { ProtocolError } from '../protocol/errors.js';
3
+ import { indexPlan, indexRowsOf } from '../protocol/index-rows.js';
4
+ import { canonicalJson } from '../protocol/query.js';
5
+ import { json } from './sync.js';
6
+ /** a store that lives as long as the process; fine for tests and single-instance Node */
7
+ export function memoryBundleStore() {
8
+ const held = new Map();
9
+ return {
10
+ put: async (version, bytes) => {
11
+ held.set(version, bytes);
12
+ },
13
+ get: async (version) => held.get(version)
14
+ };
15
+ }
16
+ const encoder = new TextEncoder();
17
+ async function seedRows(dataset, ctx) {
18
+ const rows = [];
19
+ let bytes = 0;
20
+ const take = (row) => {
21
+ const key = dataset.key(row);
22
+ if (typeof key !== 'string') {
23
+ throw new ProtocolError('bad-dataset', `${dataset.name}: a row key must be a string`);
24
+ }
25
+ rows.push([key, row]);
26
+ bytes += encoder.encode(canonicalJson(row)).length;
27
+ if (rows.length > dataset.maxRows || bytes > dataset.maxBytes) {
28
+ throw new ProtocolError('dataset-limit', `${dataset.name}: over the seed limit`);
29
+ }
30
+ };
31
+ const add = (item) => {
32
+ if (Array.isArray(item))
33
+ for (const row of item)
34
+ take(row);
35
+ else
36
+ take(item);
37
+ };
38
+ const result = await dataset.seed(ctx);
39
+ if (Array.isArray(result))
40
+ for (const item of result)
41
+ add(item);
42
+ else if (Symbol.asyncIterator in Object(result)) {
43
+ for await (const item of result)
44
+ add(item);
45
+ }
46
+ else
47
+ for (const item of result)
48
+ add(item);
49
+ return rows;
50
+ }
51
+ function sameBytes(a, b) {
52
+ if (a.length !== b.length)
53
+ return false;
54
+ for (let i = 0; i < a.length; i++)
55
+ if (a[i] !== b[i])
56
+ return false;
57
+ return true;
58
+ }
59
+ /**
60
+ * The index tables the public routes need. A family route adds `path:<dataset>`, each row's
61
+ * concrete path mapped to its key. A query route adds `query:<dataset>`, each row's filter and sort
62
+ * fields. A plan, a principal route and a pattern with a param other than the key add nothing.
63
+ */
64
+ export function indexTables(routes, tables) {
65
+ const held = (dataset, pattern) => {
66
+ if (!Object.hasOwn(tables, dataset)) {
67
+ throw new ProtocolError('bad-bundle', `${pattern}: ${dataset} is not a public dataset`);
68
+ }
69
+ };
70
+ for (const route of routes) {
71
+ if (route.scope !== 'public')
72
+ continue;
73
+ if (route.family)
74
+ held(route.family.dataset, route.pattern);
75
+ if (route.query?.dataset !== undefined && route.query.plan === undefined) {
76
+ held(route.query.dataset, route.pattern);
77
+ }
78
+ }
79
+ const plan = indexPlan(routes);
80
+ const pathDatasets = [...new Set(plan.paths.map((path) => path.dataset))];
81
+ const datasets = new Set([...pathDatasets, ...plan.fields.keys()]);
82
+ const out = {};
83
+ for (const dataset of pathDatasets)
84
+ out[`path:${dataset}`] = [];
85
+ for (const dataset of plan.fields.keys())
86
+ out[`query:${dataset}`] = [];
87
+ for (const name of Object.keys(out)) {
88
+ if (Object.hasOwn(tables, name)) {
89
+ throw new ProtocolError('bad-bundle', `${name} is already a table of the pack`);
90
+ }
91
+ }
92
+ for (const dataset of datasets) {
93
+ for (const [key, row] of tables[dataset] ?? []) {
94
+ for (const [table, rowKey, value] of indexRowsOf(plan, dataset, key, row)) {
95
+ if (value !== null)
96
+ out[table]?.push([rowKey, value]);
97
+ }
98
+ }
99
+ }
100
+ return out;
101
+ }
102
+ /**
103
+ * Builds the pack of the public datasets at `version` and keeps it in `store`. A version that
104
+ * already holds other bytes is refused, since its URL is served as immutable. A site with no
105
+ * dataset builds an empty pack.
106
+ */
107
+ export async function buildBundle(options) {
108
+ const ctx = { request: new Request(options.url), url: options.url };
109
+ const tables = {};
110
+ for (const dataset of options.datasets) {
111
+ if (dataset.scope !== 'public')
112
+ continue;
113
+ if (Object.hasOwn(tables, dataset.name)) {
114
+ throw new ProtocolError('bad-dataset', `${dataset.name}: declared twice`);
115
+ }
116
+ tables[dataset.name] = await seedRows(dataset, ctx);
117
+ }
118
+ const { index, bytes } = await buildPack({
119
+ version: options.version,
120
+ tables: { ...tables, ...indexTables(options.routes ?? [], tables) }
121
+ }, options.blockRows, options.maxBytes);
122
+ const held = await options.store.get(options.version);
123
+ if (held === undefined)
124
+ await options.store.put(options.version, bytes);
125
+ else if (!sameBytes(held, bytes)) {
126
+ throw new ProtocolError('bad-bundle', `bundle ${options.version} already holds other bytes`);
127
+ }
128
+ return { version: options.version, index, bytes };
129
+ }
130
+ /** the response to `GET /.spool/bundle/<version>`: the pack bytes, or 404 for a version not held */
131
+ export async function respondBundle(store, version) {
132
+ const number = /^\d{1,15}$/.test(version) ? Number(version) : undefined;
133
+ const bytes = store && number !== undefined ? await store.get(number) : undefined;
134
+ if (bytes === undefined)
135
+ return json({ error: 'no bundle' }, 404);
136
+ return new Response(bytes, {
137
+ headers: {
138
+ 'content-type': 'application/octet-stream',
139
+ 'cache-control': 'public, max-age=31536000, immutable'
140
+ }
141
+ });
142
+ }
143
+ /** base64 of `bytes`, built in slices so the argument list of `fromCharCode` stays small */
144
+ function base64(bytes) {
145
+ let text = '';
146
+ for (let at = 0; at < bytes.length; at += 0x8000) {
147
+ text += String.fromCharCode(...bytes.subarray(at, at + 0x8000));
148
+ }
149
+ return btoa(text);
150
+ }
151
+ /**
152
+ * The response to `GET /.spool/<runtime>/boot/<version>.js`: `code`, the page runtime and the
153
+ * navigation script, after a line that hands the pack at `version` to the runtime as base64. One
154
+ * script tag then installs the runtime and the pack in one request. With a `shape` the same line
155
+ * also hands over the routes and templates, so no document has to carry them. 404 for a version
156
+ * not held.
157
+ */
158
+ export async function respondBoot(store, version, code, shape) {
159
+ const number = /^\d{1,15}$/.test(version) ? Number(version) : undefined;
160
+ const bytes = store && number !== undefined ? await store.get(number) : undefined;
161
+ if (bytes === undefined || number === undefined)
162
+ return json({ error: 'no bundle' }, 404);
163
+ const boot = '(globalThis.__SPOOL_BOOT__=globalThis.__SPOOL_BOOT__||{})';
164
+ const given = shape ? `${boot}.shape=${JSON.stringify(shape)};` : '';
165
+ const hand = `${given}${boot}.pack={version:${number},data:"${base64(bytes)}"};\n`;
166
+ return new Response(hand + code, {
167
+ headers: {
168
+ 'content-type': 'text/javascript; charset=utf-8',
169
+ 'cache-control': 'public, max-age=31536000, immutable'
170
+ }
171
+ });
172
+ }
@@ -1,4 +1,4 @@
1
- import { type Dataset, type DatasetContext, type DatasetRequest, type DatasetResponse } from '../protocol/dataset.js';
1
+ import { type Dataset, type DatasetContext, type DatasetRequest, type DatasetResponse, type DatasetRow } from '../protocol/dataset.js';
2
2
  import { type DatasetInputs, type ProvisionPrior } from '../protocol/provision.js';
3
3
  import type { Identity } from '../protocol/route.js';
4
4
  /**
@@ -35,6 +35,12 @@ export type Admission = {
35
35
  prior: ProvisionPrior;
36
36
  stats: Map<string, DatasetStats>;
37
37
  };
38
+ /**
39
+ * The fields of a row one viewer may hold, from the dataset's `fields`. A family dataset with no
40
+ * `fields` gives the viewer its own row whole and refuses any other row; a dataset no family reads
41
+ * has no view and every row goes out whole.
42
+ */
43
+ export declare function viewOf(dataset: Dataset, viewer: Identity, family?: boolean): ((row: DatasetRow) => DatasetRow) | undefined;
38
44
  /** who is asking a principal dataset, and the `Spool-Partition` value that names them */
39
45
  export type DatasetPrincipal = {
40
46
  identity: Identity;
@@ -45,4 +51,4 @@ export type DatasetPrincipal = {
45
51
  * first seed only while `datasetBenefit` says it beats both controls, and otherwise answers `409`
46
52
  * with the control that bound.
47
53
  */
48
- export declare function respondDataset(request: Request, url: URL, datasets: ReadonlyMap<string, Dataset>, admission: Admission, who?: () => Promise<DatasetPrincipal | null>): Promise<Response>;
54
+ export declare function respondDataset(request: Request, url: URL, datasets: ReadonlyMap<string, Dataset>, admission: Admission, who: (() => Promise<DatasetPrincipal | null>) | undefined, families: ReadonlySet<string>): Promise<Response>;
@@ -235,19 +235,66 @@ async function measurePatch(dataset, stats, ctx) {
235
235
  if (!body.reset)
236
236
  stats.patchBytes = await gzipBytes(JSON.stringify(body));
237
237
  }
238
+ /**
239
+ * The fields of a row one viewer may hold, from the dataset's `fields`. A family dataset with no
240
+ * `fields` gives the viewer its own row whole and refuses any other row; a dataset no family reads
241
+ * has no view and every row goes out whole.
242
+ */
243
+ export function viewOf(dataset, viewer, family = false) {
244
+ const { fields } = dataset;
245
+ if (fields === undefined) {
246
+ if (!family)
247
+ return undefined;
248
+ return (row) => {
249
+ if (dataset.key(row) === viewer.principal)
250
+ return row;
251
+ return bad(dataset, 'a row of another principal needs a fields function');
252
+ };
253
+ }
254
+ return (row) => {
255
+ const names = fields.call(dataset, viewer, row);
256
+ if (!Array.isArray(names) || names.some((name) => typeof name !== 'string')) {
257
+ return bad(dataset, 'fields must return a list of field names');
258
+ }
259
+ const out = {};
260
+ for (const name of names)
261
+ if (Object.hasOwn(row, name))
262
+ out[name] = row[name];
263
+ return out;
264
+ };
265
+ }
266
+ /**
267
+ * The body with each row cut to the viewer's fields. A proof is taken again over the cut rows, since
268
+ * the backend's proof covers the whole row and the device checks the rows it holds against it.
269
+ */
270
+ async function viewed(dataset, body, ctx, view) {
271
+ const puts = body.puts.map(({ key, row }) => ({ key, row: view(row) }));
272
+ if (body.proof === undefined)
273
+ return { ...body, puts };
274
+ const all = new Map();
275
+ for await (const raw of rowsOf(dataset, ctx)) {
276
+ const [key, row] = keyed(dataset, raw);
277
+ all.set(key, view(row));
278
+ }
279
+ return { ...body, puts, proof: await setProof(all) };
280
+ }
238
281
  /**
239
282
  * Answers a principal dataset. Everything the dataset's functions see comes from the identity the
240
283
  * server resolved, never from the URL, and a request with no identity gets `401`. The answer is
241
284
  * never shared-cacheable and names the partition it belongs to, which the device checks before it
242
285
  * applies a row.
243
286
  */
244
- async function respondPrincipalDataset(request, url, dataset, ask, who) {
287
+ async function respondPrincipalDataset(request, url, dataset, ask, who, families) {
245
288
  const caller = who ? await who() : null;
246
289
  if (!caller)
247
290
  return json({ error: 'sign in' }, 401, { 'cache-control': 'private, no-store' });
248
291
  let body;
249
292
  try {
250
- body = await answerDataset(dataset, ask, { request, url, principal: caller.identity });
293
+ const ctx = { request, url, principal: caller.identity };
294
+ body = await answerDataset(dataset, ask, ctx);
295
+ const view = viewOf(dataset, caller.identity, families.has(dataset.name));
296
+ if (view)
297
+ body = await viewed(dataset, body, ctx, view);
251
298
  }
252
299
  catch (error) {
253
300
  if (error instanceof ProtocolError && error.code === 'dataset-forbidden') {
@@ -266,13 +313,13 @@ async function respondPrincipalDataset(request, url, dataset, ask, who) {
266
313
  * first seed only while `datasetBenefit` says it beats both controls, and otherwise answers `409`
267
314
  * with the control that bound.
268
315
  */
269
- export async function respondDataset(request, url, datasets, admission, who) {
316
+ export async function respondDataset(request, url, datasets, admission, who, families) {
270
317
  const ask = parseDatasetRequest(url.searchParams);
271
318
  const dataset = datasets.get(ask.name);
272
319
  if (!dataset)
273
320
  return json({ error: 'no dataset' }, 404);
274
321
  if (dataset.scope === 'principal')
275
- return respondPrincipalDataset(request, url, dataset, ask, who);
322
+ return respondPrincipalDataset(request, url, dataset, ask, who, families);
276
323
  const ctx = { request, url };
277
324
  if (dataset.provision !== 'auto') {
278
325
  const body = await answerDataset(dataset, ask, ctx);