@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
@@ -4,5 +4,7 @@ export declare const POLICY_HEADERS: readonly ["content-security-policy", "conte
4
4
  export declare const MAX_POLICY_PATHS = 128;
5
5
  /** header names and values, as stored in the replica meta */
6
6
  export type HeaderSet = Array<[string, string]>;
7
+ /** the pairs in `value` whose name is an allowed policy header, or undefined when `value` is not a list */
8
+ export declare function allowedPolicy(value: unknown): HeaderSet | undefined;
7
9
  /** the {@link POLICY_HEADERS} a response carries, possibly none */
8
10
  export declare function policyHeaders(headers: Headers): HeaderSet;
package/dist/sw/policy.js CHANGED
@@ -12,6 +12,17 @@ export const POLICY_HEADERS = [
12
12
  ];
13
13
  /** most paths whose own header set is kept, oldest dropped first */
14
14
  export const MAX_POLICY_PATHS = 128;
15
+ /** the pairs in `value` whose name is an allowed policy header, or undefined when `value` is not a list */
16
+ export function allowedPolicy(value) {
17
+ if (!Array.isArray(value))
18
+ return undefined;
19
+ const names = POLICY_HEADERS;
20
+ return value.filter((pair) => Array.isArray(pair) &&
21
+ pair.length === 2 &&
22
+ typeof pair[0] === 'string' &&
23
+ typeof pair[1] === 'string' &&
24
+ names.includes(pair[0]));
25
+ }
15
26
  /** the {@link POLICY_HEADERS} a response carries, possibly none */
16
27
  export function policyHeaders(headers) {
17
28
  const out = [];
@@ -0,0 +1,16 @@
1
+ /** what the worker's own fetch found in the disk cache: a hit, or a miss (any error is a miss) */
2
+ export type CacheProbe = 'hit' | 'miss';
3
+ /** a fetch that read from disk sends no body bytes over the wire, so its timing entry shows zero */
4
+ export declare function timingHit(entry: {
5
+ encodedBodySize: number;
6
+ } | undefined): CacheProbe;
7
+ /** subresources are forwarded only after a hit; until the probe answers the browser keeps them */
8
+ export declare function shouldForward(probe: CacheProbe | undefined): boolean;
9
+ /** the timing entry the worker's last fetch of `url` left in its own performance timeline */
10
+ export declare function resourceTiming(url: string): {
11
+ encodedBodySize: number;
12
+ } | undefined;
13
+ /** fetches an asset with `only-if-cached` and reads its timing; a rejected fetch is a miss */
14
+ export declare function probeCache(url: string, fetcher: (input: string, init: RequestInit) => Promise<Response>, timing: (url: string) => {
15
+ encodedBodySize: number;
16
+ } | undefined): Promise<CacheProbe>;
@@ -0,0 +1,25 @@
1
+ /** a fetch that read from disk sends no body bytes over the wire, so its timing entry shows zero */
2
+ export function timingHit(entry) {
3
+ return entry !== undefined && entry.encodedBodySize === 0 ? 'hit' : 'miss';
4
+ }
5
+ /** subresources are forwarded only after a hit; until the probe answers the browser keeps them */
6
+ export function shouldForward(probe) {
7
+ return probe === 'hit';
8
+ }
9
+ /** the timing entry the worker's last fetch of `url` left in its own performance timeline */
10
+ export function resourceTiming(url) {
11
+ return performance.getEntriesByName(url).at(-1);
12
+ }
13
+ /** fetches an asset with `only-if-cached` and reads its timing; a rejected fetch is a miss */
14
+ export async function probeCache(url, fetcher, timing) {
15
+ try {
16
+ const response = await fetcher(url, { cache: 'only-if-cached', mode: 'same-origin' });
17
+ await response.arrayBuffer();
18
+ if (!response.ok)
19
+ return 'miss';
20
+ return timingHit(timing(url));
21
+ }
22
+ catch {
23
+ return 'miss';
24
+ }
25
+ }
@@ -1,5 +1,5 @@
1
1
  import { type CollectorConfig } from '../protocol/collector.js';
2
- import type { SwConfig } from '../protocol/config.js';
2
+ import { type SwConfig } from '../protocol/config.js';
3
3
  import { type Params } from '../protocol/pattern.js';
4
4
  import { type SerializedRoute } from '../protocol/route.js';
5
5
  /** how the worker treats a request; a `static` hit keys its file by pathname plus query string */
@@ -34,7 +34,8 @@ export type Classified = {
34
34
  };
35
35
  /**
36
36
  * Sorts a request without touching it. A request to another origin is a held collector hit, a
37
- * file of an allowed third-party origin, or ignored so the browser handles it natively. A
37
+ * GET a data family answers for that origin, a file of an allowed third-party origin, or ignored so
38
+ * the browser handles it natively. A
38
39
  * same-origin one is a logout request, a queued beacon, a navigation on a declared route, a GET for
39
40
  * a JSON route, a GET for a subresource (cache-first when immutable), a GET of a file a static
40
41
  * route keeps, or a pass-through that the worker still observes for spool headers.
package/dist/sw/router.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { matchCollector } from '../protocol/collector.js';
2
+ import { LIVE_PATH } from '../protocol/config.js';
2
3
  import { matchPattern } from '../protocol/pattern.js';
3
4
  import { matchRoute } from '../protocol/route.js';
4
5
  /** whether `url` falls under an origin the worker may cache files from */
@@ -7,7 +8,8 @@ function thirdPartyOrigin(config, url) {
7
8
  }
8
9
  /**
9
10
  * Sorts a request without touching it. A request to another origin is a held collector hit, a
10
- * file of an allowed third-party origin, or ignored so the browser handles it natively. A
11
+ * GET a data family answers for that origin, a file of an allowed third-party origin, or ignored so
12
+ * the browser handles it natively. A
11
13
  * same-origin one is a logout request, a queued beacon, a navigation on a declared route, a GET for
12
14
  * a JSON route, a GET for a subresource (cache-first when immutable), a GET of a file a static
13
15
  * route keeps, or a pass-through that the worker still observes for spool headers.
@@ -19,10 +21,20 @@ export function classify(config, request, origin) {
19
21
  if (collector && (request.method === 'POST' || request.method === 'GET')) {
20
22
  return { kind: 'collector', collector };
21
23
  }
24
+ if (request.method === 'GET' && !request.headers.has('range')) {
25
+ const remote = config.routes.filter((route) => route.origin === url.origin);
26
+ const hit = matchRoute(remote, url.pathname);
27
+ if (hit?.route.strategy === 'data' && (url.search === '' || hit.route.query)) {
28
+ return { kind: 'data', route: hit.route, path: url.pathname };
29
+ }
30
+ }
22
31
  if (request.method === 'GET' && thirdPartyOrigin(config, url))
23
32
  return { kind: 'thirdparty' };
24
33
  return { kind: 'ignore' };
25
34
  }
35
+ // the stream is the browser's own long-lived request; the worker never sits in it
36
+ if (url.pathname === LIVE_PATH)
37
+ return { kind: 'ignore' };
26
38
  if (config.logout?.some((pattern) => matchPattern(pattern, url.pathname))) {
27
39
  return { kind: 'logout' };
28
40
  }
@@ -30,7 +42,8 @@ export function classify(config, request, origin) {
30
42
  return { kind: 'beacon' };
31
43
  if (request.method !== 'GET')
32
44
  return { kind: 'pass' };
33
- const hit = matchRoute(config.routes, url.pathname);
45
+ // a cross-origin family answers only its own origin's GETs, never the page's paths
46
+ const hit = matchRoute(config.routes.filter((route) => route.origin === undefined), url.pathname);
34
47
  // an artifact is keyed by path alone, so only a route with a query schema answers a query
35
48
  const queried = url.search !== '' && !hit?.route.query;
36
49
  if (request.mode !== 'navigate') {
@@ -1,12 +1,15 @@
1
1
  import { type AssetMode, type SwConfig } from '../protocol/config.js';
2
+ import { type LiveDelta } from '../protocol/envelope.js';
2
3
  import { type WriteFlush, type WriteQueued, type WriteRefusal, type WriteResolved, type WriteStatus } from '../protocol/write.js';
3
4
  import { type DatasetRefusal } from './dataset-sync.js';
5
+ import { type PackStore } from './pack/store.js';
4
6
  import type { PartitionHost } from './partition.js';
5
7
  import { Ledger, type LedgerEntry, type LedgerTotals } from './provision.js';
6
8
  import { type Renderers } from './render.js';
7
9
  import { Replica } from './replica.js';
8
10
  import { type RoutableInstall } from './routing.js';
9
11
  import type { DatasetMeta, ReplicaStorage } from './storage.js';
12
+ import { type WriteTimers } from './write.js';
10
13
  /** the slice of a `Cache` the runtime uses */
11
14
  export type CacheLike = {
12
15
  match(request: Request): Promise<Response | undefined>;
@@ -24,6 +27,11 @@ export type CachesLike = {
24
27
  export type RuntimeDeps = {
25
28
  config: SwConfig;
26
29
  storage: ReplicaStorage;
30
+ /**
31
+ * the pack store family routes read their rows from and a served pack is adopted into; default the
32
+ * browser's IndexedDB, and none where there is none, so family routes go to the network
33
+ */
34
+ pack?: PackStore;
27
35
  fetch(input: Request | string, init?: RequestInit): Promise<Response>;
28
36
  caches: CachesLike;
29
37
  /** the worker's own origin */
@@ -46,6 +54,10 @@ export type RuntimeDeps = {
46
54
  quota?: number;
47
55
  usage?: number;
48
56
  }>;
57
+ /** the timers the declared-write deadlines run on; default the global timers */
58
+ timers?: WriteTimers;
59
+ /** how long the second lease renewal waits for a page to open the stream before it renews; default 3000 */
60
+ liveWaitMs?: number;
49
61
  };
50
62
  /** the worker's answer to a page's `spool:hello` */
51
63
  export type Hello = {
@@ -53,6 +65,10 @@ export type Hello = {
53
65
  protocol: number;
54
66
  version: string;
55
67
  compatible: boolean;
68
+ /** seconds the browser holds the worker script; absent from a worker built before the lease */
69
+ lease?: number;
70
+ /** epoch milliseconds of the worker's last server answer; absent until it has one */
71
+ contact?: number;
56
72
  };
57
73
  /** the worker's answer to `spool:status` */
58
74
  export type Status = {
@@ -90,6 +106,37 @@ export type PartitionStatus = {
90
106
  /** the principal datasets held for this partition; always empty while the flag is off */
91
107
  datasets: DatasetMeta[];
92
108
  };
109
+ /**
110
+ * the worker's answer to `spool:live-state`: the site's stream setting (null when it has none), the
111
+ * partition held and the lowest cursor a side holds, which a stream starts its catch-up from
112
+ */
113
+ export type LiveState = {
114
+ type: 'spool:live-state';
115
+ live: NonNullable<SwConfig['live']> | null;
116
+ partition: string | null;
117
+ have: number | null;
118
+ };
119
+ /** what a page tells the worker it read from its stream; `partition` is the one the stream was opened for */
120
+ export type LiveMessage = {
121
+ partition: string | null;
122
+ } & ({
123
+ event: 'delta';
124
+ delta: LiveDelta;
125
+ } | {
126
+ event: 'lease';
127
+ leaseMs: number;
128
+ } | {
129
+ event: 'revoked';
130
+ }
131
+ /** a visible session began: the worker counts lease renewals from zero */
132
+ | {
133
+ event: 'session';
134
+ });
135
+ /** the worker's answer to `spool:live`: false when a delta did not follow the cursor the worker holds, so the page connects again */
136
+ export type LiveAck = {
137
+ type: 'spool:live';
138
+ ok: boolean;
139
+ };
93
140
  /** the worker's answer to `spool:assets`: the mode asked for and whether Static Routing took effect */
94
141
  export type AssetsStatus = {
95
142
  type: 'spool:assets';
@@ -135,7 +182,7 @@ export type WriteReply = {
135
182
  result: WriteResolved | WriteRefusal;
136
183
  };
137
184
  /** every reply the worker gives a page */
138
- export type Reply = WriteReply | Hello | Status | ViewId | DatasetStatus | GraphStatus | LedgerStatus | PartitionStatus | AssetsStatus | HeldStatus;
185
+ export type Reply = WriteReply | Hello | Status | ViewId | DatasetStatus | GraphStatus | LedgerStatus | PartitionStatus | LiveState | LiveAck | AssetsStatus | HeldStatus;
139
186
  /** the object `serve` wires to service worker events */
140
187
  export type Runtime = {
141
188
  /** a response promise for a request the worker handles, `undefined` for one it leaves alone */