@drupflare/spool 0.3.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 (206) hide show
  1. package/README.md +279 -1607
  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 +123 -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 +34 -2
  31. package/dist/client/register.js +64 -7
  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 +80 -1
  63. package/dist/protocol/config.js +31 -1
  64. package/dist/protocol/dataset.d.ts +189 -0
  65. package/dist/protocol/dataset.js +212 -0
  66. package/dist/protocol/envelope.d.ts +34 -1
  67. package/dist/protocol/envelope.js +16 -1
  68. package/dist/protocol/errors.d.ts +1 -1
  69. package/dist/protocol/graph.d.ts +23 -4
  70. package/dist/protocol/graph.js +34 -3
  71. package/dist/protocol/index-rows.d.ts +22 -0
  72. package/dist/protocol/index-rows.js +53 -0
  73. package/dist/protocol/index.d.ts +5 -0
  74. package/dist/protocol/index.js +5 -0
  75. package/dist/protocol/normalise.d.ts +4 -4
  76. package/dist/protocol/normalise.js +9 -5
  77. package/dist/protocol/plan.d.ts +100 -0
  78. package/dist/protocol/plan.js +661 -0
  79. package/dist/protocol/provision.d.ts +46 -0
  80. package/dist/protocol/provision.js +38 -0
  81. package/dist/protocol/query.d.ts +66 -5
  82. package/dist/protocol/query.js +103 -4
  83. package/dist/protocol/ring.d.ts +58 -0
  84. package/dist/protocol/ring.js +6 -0
  85. package/dist/protocol/route.d.ts +63 -13
  86. package/dist/protocol/route.js +126 -6
  87. package/dist/protocol/tag.d.ts +22 -2
  88. package/dist/protocol/tag.js +25 -4
  89. package/dist/protocol/view.d.ts +2 -0
  90. package/dist/protocol/view.js +8 -2
  91. package/dist/protocol/views.d.ts +6 -0
  92. package/dist/protocol/views.js +15 -0
  93. package/dist/protocol/write.d.ts +234 -0
  94. package/dist/protocol/write.js +343 -0
  95. package/dist/proxy/eligible.d.ts +22 -1
  96. package/dist/proxy/eligible.js +62 -15
  97. package/dist/proxy/proxy.js +28 -18
  98. package/dist/react-router/index.d.ts +20 -0
  99. package/dist/react-router/index.js +60 -0
  100. package/dist/react-router/pages.d.ts +34 -0
  101. package/dist/react-router/pages.js +83 -0
  102. package/dist/report/dataset.d.ts +48 -0
  103. package/dist/report/dataset.js +93 -0
  104. package/dist/report/demand.d.ts +49 -0
  105. package/dist/report/demand.js +60 -0
  106. package/dist/report/derive.d.ts +285 -0
  107. package/dist/report/derive.js +676 -1
  108. package/dist/report/economics.d.ts +66 -1
  109. package/dist/report/economics.js +208 -1
  110. package/dist/report/headline.d.ts +158 -0
  111. package/dist/report/headline.js +473 -0
  112. package/dist/report/index.d.ts +4 -0
  113. package/dist/report/index.js +4 -0
  114. package/dist/report/inputs.d.ts +176 -0
  115. package/dist/report/inputs.js +248 -0
  116. package/dist/report/institution.d.ts +188 -1
  117. package/dist/report/institution.js +146 -0
  118. package/dist/report/loops.d.ts +73 -0
  119. package/dist/report/loops.js +101 -0
  120. package/dist/report/measurement.d.ts +1 -1
  121. package/dist/report/measurement.js +7 -1
  122. package/dist/report/model.d.ts +2 -0
  123. package/dist/report/model.js +4 -0
  124. package/dist/report/thirdparty.d.ts +57 -0
  125. package/dist/report/thirdparty.js +111 -0
  126. package/dist/report/traffic.d.ts +8 -0
  127. package/dist/report/traffic.js +7 -0
  128. package/dist/report/trim.d.ts +56 -0
  129. package/dist/report/trim.js +83 -1
  130. package/dist/server/bundle.d.ts +55 -0
  131. package/dist/server/bundle.js +172 -0
  132. package/dist/server/dataset.d.ts +54 -0
  133. package/dist/server/dataset.js +355 -0
  134. package/dist/server/embedded.d.ts +7 -3
  135. package/dist/server/embedded.js +7 -3
  136. package/dist/server/index.d.ts +6 -0
  137. package/dist/server/index.js +6 -0
  138. package/dist/server/live-sockets.d.ts +54 -0
  139. package/dist/server/live-sockets.js +131 -0
  140. package/dist/server/live.d.ts +146 -0
  141. package/dist/server/live.js +228 -0
  142. package/dist/server/ring.d.ts +77 -0
  143. package/dist/server/ring.js +311 -0
  144. package/dist/server/spool.d.ts +158 -3
  145. package/dist/server/spool.js +578 -41
  146. package/dist/server/static.d.ts +42 -0
  147. package/dist/server/static.js +29 -0
  148. package/dist/server/stub.d.ts +43 -5
  149. package/dist/server/stub.js +126 -8
  150. package/dist/server/write.d.ts +49 -0
  151. package/dist/server/write.js +223 -0
  152. package/dist/stores/durable-object.d.ts +46 -0
  153. package/dist/stores/durable-object.js +114 -0
  154. package/dist/sw/analytics.d.ts +7 -1
  155. package/dist/sw/analytics.js +16 -2
  156. package/dist/sw/coverage.d.ts +6 -0
  157. package/dist/sw/coverage.js +34 -0
  158. package/dist/sw/dataset-sync.d.ts +76 -0
  159. package/dist/sw/dataset-sync.js +149 -0
  160. package/dist/sw/dataset.d.ts +91 -0
  161. package/dist/sw/dataset.js +318 -0
  162. package/dist/sw/family.d.ts +15 -0
  163. package/dist/sw/family.js +48 -0
  164. package/dist/sw/graph/index.d.ts +31 -1
  165. package/dist/sw/graph/index.js +57 -5
  166. package/dist/sw/graph/invalidate.d.ts +15 -3
  167. package/dist/sw/graph/invalidate.js +42 -4
  168. package/dist/sw/idb.d.ts +2 -0
  169. package/dist/sw/idb.js +80 -11
  170. package/dist/sw/index.d.ts +2 -0
  171. package/dist/sw/index.js +1 -0
  172. package/dist/sw/pack/store.d.ts +128 -0
  173. package/dist/sw/pack/store.js +737 -0
  174. package/dist/sw/partition.d.ts +6 -1
  175. package/dist/sw/partition.js +21 -2
  176. package/dist/sw/policy.d.ts +2 -0
  177. package/dist/sw/policy.js +11 -0
  178. package/dist/sw/principal-dataset.d.ts +64 -0
  179. package/dist/sw/principal-dataset.js +254 -0
  180. package/dist/sw/probe.d.ts +16 -0
  181. package/dist/sw/probe.js +25 -0
  182. package/dist/sw/render.d.ts +7 -2
  183. package/dist/sw/render.js +19 -5
  184. package/dist/sw/replica.d.ts +12 -3
  185. package/dist/sw/replica.js +40 -5
  186. package/dist/sw/router.d.ts +3 -2
  187. package/dist/sw/router.js +15 -2
  188. package/dist/sw/runtime.d.ts +90 -2
  189. package/dist/sw/runtime.js +857 -61
  190. package/dist/sw/scheduler.d.ts +6 -1
  191. package/dist/sw/scheduler.js +22 -5
  192. package/dist/sw/seal.d.ts +13 -0
  193. package/dist/sw/seal.js +13 -4
  194. package/dist/sw/static.d.ts +18 -0
  195. package/dist/sw/static.js +84 -1
  196. package/dist/sw/storage.d.ts +51 -1
  197. package/dist/sw/storage.js +33 -1
  198. package/dist/sw/write.d.ts +147 -0
  199. package/dist/sw/write.js +625 -0
  200. package/dist/version.d.ts +1 -1
  201. package/dist/version.js +1 -2
  202. package/dist/vite/index.d.ts +26 -0
  203. package/dist/vite/index.js +66 -0
  204. package/dist/vue/index.d.ts +36 -0
  205. package/dist/vue/index.js +53 -0
  206. package/package.json +65 -4
@@ -0,0 +1,272 @@
1
+ import { PROTOCOL_VERSION } from '../protocol/artifact.js';
2
+ import { ProtocolError } from '../protocol/errors.js';
3
+ import { equivalent } from '../protocol/normalise.js';
4
+ import { matchRoute } from '../protocol/route.js';
5
+ import { renderLocal } from '../sw/render.js';
6
+ import { checkLease } from './contact.js';
7
+ // WebKit leaves the page at the 101st history call in 10 seconds, and replaceState counts too
8
+ const HISTORY_BUDGET = 90;
9
+ const HISTORY_WINDOW_MS = 10_000;
10
+ /** the route kinds whose local answer is an HTML page */
11
+ const PAGE_STRATEGIES = ['template', 'projection'];
12
+ /**
13
+ * Whether this page may answer `url` from the held rows. It checks the route and the renderer only;
14
+ * the row and the parameters are read later, so a `false` here is final and a `true` is a guess.
15
+ */
16
+ function answerable(route, url, options) {
17
+ if (route.navigation === 'document')
18
+ return false;
19
+ if (!PAGE_STRATEGIES.includes(route.strategy))
20
+ return false;
21
+ const custom = Object.hasOwn(options.renderers ?? {}, route.pattern);
22
+ const template = route.strategy === 'template' && Object.hasOwn(options.templates ?? {}, route.pattern);
23
+ if (!custom && !template)
24
+ return false;
25
+ if (route.family)
26
+ return url.search === '';
27
+ // a bare list URL is the origin's own page, which the held rows cannot reproduce
28
+ return (route.query?.dataset !== undefined && route.query.plan === undefined && url.search !== '');
29
+ }
30
+ /** a scan that a swap interrupts is retried once; the swap has committed by the retry */
31
+ async function scan(store, table) {
32
+ try {
33
+ return await store.scanTable(table);
34
+ }
35
+ catch (error) {
36
+ if (error instanceof ProtocolError && error.code === 'bad-sync')
37
+ return store.scanTable(table);
38
+ throw error;
39
+ }
40
+ }
41
+ /**
42
+ * The page's view of its held routes. `offers` answers at once from the routes it loaded; `render`
43
+ * reads the row or rows and returns the HTML, or null when the network must answer.
44
+ *
45
+ * @internal
46
+ */
47
+ export function createNavigator(options) {
48
+ const { store } = options;
49
+ const renderers = options.renderers ?? {};
50
+ const config = { templates: options.templates ?? {}, clientTag: options.clientTag ?? '' };
51
+ let routes = [];
52
+ let loaded = false;
53
+ let partial = false;
54
+ const ready = Promise.all([store.getRoutes(), store.head()])
55
+ .then(([held, head]) => {
56
+ routes = held;
57
+ partial = head?.partial === true;
58
+ loaded = true;
59
+ })
60
+ .catch(() => undefined);
61
+ return {
62
+ ready,
63
+ offers(url) {
64
+ if (!loaded)
65
+ return false;
66
+ const hit = matchRoute(routes, url.pathname);
67
+ return (hit !== null &&
68
+ !(partial && !hit.route.family) &&
69
+ answerable(hit.route, url, options));
70
+ },
71
+ async render(url) {
72
+ await ready;
73
+ const hit = matchRoute(routes, url.pathname);
74
+ if (!hit || !answerable(hit.route, url, options))
75
+ return null;
76
+ const { route, params } = hit;
77
+ const dataset = route.family?.dataset ?? route.query?.dataset;
78
+ if (dataset === undefined)
79
+ return null;
80
+ const head = await store.head();
81
+ if (!head?.tables.includes(dataset))
82
+ return null;
83
+ // a partial head holds the ring's rows, so a list read would show a part as the whole
84
+ if (head.partial && !route.family)
85
+ return null;
86
+ let data = {};
87
+ let rows;
88
+ if (route.family) {
89
+ const key = params[route.family.key];
90
+ const row = key === undefined ? undefined : await store.getRow(dataset, key);
91
+ if (row === undefined)
92
+ return null;
93
+ data = { params, row };
94
+ }
95
+ else {
96
+ rows = (await scan(store, dataset)).map(([, row]) => row);
97
+ }
98
+ const artifact = {
99
+ protocol: PROTOCOL_VERSION,
100
+ id: url.pathname,
101
+ scope: route.scope,
102
+ strategy: route.strategy,
103
+ deps: [],
104
+ vector: 0,
105
+ body: { data }
106
+ };
107
+ const rendered = await renderLocal(config, route, artifact, renderers, url.search.slice(1), rows);
108
+ return rendered.ok ? rendered.html : null;
109
+ }
110
+ };
111
+ }
112
+ /**
113
+ * Budgets the history entries of in-page moves. `take` reserves one entry before the page renders,
114
+ * so a click past {@link HISTORY_BUDGET} in a 10 second window is left to the browser as a document
115
+ * navigation. `push` writes the entry once the new content is in place.
116
+ *
117
+ * @internal
118
+ */
119
+ export function createHistoryWriter(history, now = Date.now) {
120
+ const takes = [];
121
+ return {
122
+ take() {
123
+ const at = now();
124
+ while (takes.length > 0 && at - takes[0] >= HISTORY_WINDOW_MS)
125
+ takes.shift();
126
+ if (takes.length >= HISTORY_BUDGET)
127
+ return false;
128
+ takes.push(at);
129
+ return true;
130
+ },
131
+ push(url) {
132
+ history.pushState(null, '', url);
133
+ }
134
+ };
135
+ }
136
+ /** the same-origin URL a plain click loads in place, or null when the browser should handle the click */
137
+ function linkUrl(event) {
138
+ if (event.defaultPrevented || event.button !== 0)
139
+ return null;
140
+ if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
141
+ return null;
142
+ const link = event.target?.closest?.('a[href]');
143
+ if (!link || link.hasAttribute('target') || link.hasAttribute('download'))
144
+ return null;
145
+ const url = new URL(link.getAttribute('href') ?? '', location.href);
146
+ if (url.origin !== location.origin)
147
+ return null;
148
+ if (url.hash !== '' && url.pathname === location.pathname && url.search === location.search) {
149
+ return null;
150
+ }
151
+ return url;
152
+ }
153
+ /** the same-origin GET URL a form submits to, or null when the browser should handle it */
154
+ function formUrl(event) {
155
+ const form = event.target;
156
+ if (!form || event.defaultPrevented || form.hasAttribute('target'))
157
+ return null;
158
+ if ((form.getAttribute('method') ?? 'get').toLowerCase() !== 'get')
159
+ return null;
160
+ const url = new URL(form.getAttribute('action') ?? location.href, location.href);
161
+ if (url.origin !== location.origin)
162
+ return null;
163
+ const params = new URLSearchParams();
164
+ for (const [name, value] of new FormData(form)) {
165
+ if (typeof value === 'string')
166
+ params.append(name, value);
167
+ }
168
+ url.search = params.toString();
169
+ return url;
170
+ }
171
+ /** replaces the swap element, the sidebar when both pages have one, and the title */
172
+ function swapPage(html) {
173
+ const next = new DOMParser().parseFromString(html, 'text/html');
174
+ const swapOf = (scope) => scope.querySelector('[data-spool-swap]') ?? scope.querySelector('main');
175
+ const target = swapOf(document);
176
+ const incoming = swapOf(next);
177
+ if (!target || !incoming)
178
+ throw new Error('the page has no swap element');
179
+ target.replaceWith(document.importNode(incoming, true));
180
+ const sidebar = document.querySelector('[data-spool-swap-sidebar]');
181
+ const nextSidebar = next.querySelector('[data-spool-swap-sidebar]');
182
+ if (sidebar && nextSidebar)
183
+ sidebar.replaceWith(document.importNode(nextSidebar, true));
184
+ document.title = next.title;
185
+ }
186
+ /**
187
+ * Answers same-origin link clicks, GET form submits and history moves to held routes from the
188
+ * page, with no request. Anything the held rows cannot answer goes to the browser as it would
189
+ * have. Dispatches `spool:navigated` on `window` after each local swap. Resolves `ready` once the
190
+ * routes are loaded; until then nothing is intercepted. `go` moves to `url` as a click would, and
191
+ * loads it as a document when the held rows cannot answer.
192
+ */
193
+ export function enableNavigation(options) {
194
+ const held = createNavigator(options);
195
+ const entries = createHistoryWriter(history);
196
+ let shown = new URL(location.href);
197
+ async function visit(url, push) {
198
+ checkLease();
199
+ const html = await held.render(url);
200
+ if (html === null)
201
+ return false;
202
+ swapPage(html);
203
+ if (push) {
204
+ entries.push(url.href);
205
+ const fragment = url.hash.slice(1);
206
+ const at = fragment ? document.getElementById(decodeURIComponent(fragment)) : null;
207
+ if (at)
208
+ at.scrollIntoView();
209
+ else
210
+ window.scrollTo(0, 0);
211
+ }
212
+ shown = url;
213
+ window.dispatchEvent(new CustomEvent('spool:navigated', { detail: { url: url.href, local: true } }));
214
+ return true;
215
+ }
216
+ // a failed local render hands the move to the browser, which loads the page as it always did
217
+ function go(url, push) {
218
+ const fallback = () => (push ? location.assign(url.href) : location.reload());
219
+ visit(url, push).then((done) => {
220
+ if (!done)
221
+ fallback();
222
+ }, fallback);
223
+ }
224
+ // a click the budget refuses is not prevented, so the browser loads it as a document
225
+ const onClick = (event) => {
226
+ const url = linkUrl(event);
227
+ if (!url || !held.offers(url) || !entries.take())
228
+ return;
229
+ event.preventDefault();
230
+ go(url, true);
231
+ };
232
+ const onSubmit = (event) => {
233
+ const url = formUrl(event);
234
+ if (!url || !held.offers(url) || !entries.take())
235
+ return;
236
+ event.preventDefault();
237
+ go(url, true);
238
+ };
239
+ const onPop = () => {
240
+ const url = new URL(location.href);
241
+ // a fragment move fires popstate too; the page already shows this path
242
+ if (url.pathname === shown.pathname && url.search === shown.search)
243
+ return;
244
+ go(url, false);
245
+ };
246
+ document.addEventListener('click', onClick);
247
+ document.addEventListener('submit', onSubmit);
248
+ window.addEventListener('popstate', onPop);
249
+ return {
250
+ ready: held.ready,
251
+ go: (url) => go(url, true),
252
+ stop() {
253
+ document.removeEventListener('click', onClick);
254
+ document.removeEventListener('submit', onSubmit);
255
+ window.removeEventListener('popstate', onPop);
256
+ }
257
+ };
258
+ }
259
+ /**
260
+ * The first difference between the page this device renders for `href` and the network's
261
+ * document for it, or null when they match after normalisation. A URL the device cannot answer
262
+ * is a difference too.
263
+ */
264
+ export async function compareToDocument(href, options) {
265
+ const url = new URL(href, location.href);
266
+ const local = await createNavigator(options).render(url);
267
+ if (local === null)
268
+ return `no held page for ${url.pathname}`;
269
+ const network = await (await fetch(url.href, { cache: 'no-store' })).text();
270
+ const verdict = equivalent(local, network);
271
+ return verdict.equal ? null : verdict.reason;
272
+ }
@@ -0,0 +1,2 @@
1
+ /** asks the storage manager for persistent storage; a refusal or a throw is `false` */
2
+ export declare function askPersistence(manager: Pick<StorageManager, 'persist' | 'persisted'> | undefined): Promise<boolean>;
@@ -0,0 +1,9 @@
1
+ /** asks the storage manager for persistent storage; a refusal or a throw is `false` */
2
+ export async function askPersistence(manager) {
3
+ try {
4
+ return (await manager?.persisted?.()) === true || (await manager?.persist?.()) === true;
5
+ }
6
+ catch {
7
+ return false;
8
+ }
9
+ }
@@ -1,4 +1,5 @@
1
- import type { Hello, Status } from '../sw/runtime.js';
1
+ import type { WriteFlush, WriteQueued, WriteRefusal, WriteResolved, WriteStatus } from '../protocol/write.js';
2
+ import type { Hello, LiveAck, LiveMessage, LiveState, Status } from '../sw/runtime.js';
2
3
  import { type Closable } from './lifecycle.js';
3
4
  /** what `register` takes */
4
5
  export type RegisterOptions = {
@@ -9,8 +10,10 @@ export type RegisterOptions = {
9
10
  helloTimeoutMs?: number;
10
11
  /** the container to register on; default `navigator.serviceWorker` */
11
12
  container?: ServiceWorkerContainer;
12
- /** where `spool:cleared` is dispatched; default `window` */
13
+ /** where `spool:cleared` and `spool:persisted` are dispatched; default `window` */
13
14
  target?: Pick<EventTarget, 'dispatchEvent'>;
15
+ /** the storage manager asked for persistence; default `navigator.storage` */
16
+ storage?: Pick<StorageManager, 'persist' | 'persisted'>;
14
17
  };
15
18
  /** the page's handle on the worker */
16
19
  export type SpoolClient = {
@@ -23,8 +26,37 @@ export type SpoolClient = {
23
26
  view(path?: string): Promise<string | null>;
24
27
  /** tells the worker how many cross-origin resources the page loaded, for view `id`, and from which origins */
25
28
  reportLoads(id: string, count: number, origins?: Record<string, number>): void;
29
+ /** whether the browser granted persistent storage, or null until the worker held a dataset and the page asked */
30
+ persisted(): boolean | null;
31
+ /**
32
+ * the stream setting of the site, the partition the worker holds and the cursor a stream starts from
33
+ * @internal
34
+ */
35
+ liveState(): Promise<LiveState>;
36
+ /**
37
+ * tells the worker what the page read from its stream; undefined when the worker did not answer
38
+ * @internal
39
+ */
40
+ liveEvent(message: LiveMessage): Promise<LiveAck | undefined>;
26
41
  /** closes `db` when the page is hidden, so the page stays eligible for the back/forward cache */
27
42
  track(db: Closable): () => void;
43
+ /**
44
+ * Queues `value` as the newest for a declared write class and key, edited from `version`. Never
45
+ * throws: it answers a refusal with a `code` while declared writes are off, the class is not
46
+ * declared or no principal is signed in.
47
+ */
48
+ write(name: string, key: string, value: unknown, version: string): Promise<WriteQueued | WriteRefusal>;
49
+ /** sends every queued value now, one request per key; call it before a logout navigation */
50
+ flush(): Promise<({
51
+ ok: true;
52
+ } & WriteFlush) | WriteRefusal>;
53
+ /** the state of each queued value of the signed-in partition, without the values */
54
+ writes(): Promise<{
55
+ ok: true;
56
+ writes: WriteStatus[];
57
+ } | WriteRefusal>;
58
+ /** settles a conflicted key with the local value (re-based and flushed) or the server's */
59
+ resolve(name: string, key: string, use: 'local' | 'server'): Promise<WriteResolved | WriteRefusal>;
28
60
  };
29
61
  /**
30
62
  * Registers the worker with `updateViaCache: 'all'`, so a controlled navigation skips the script
@@ -1,6 +1,10 @@
1
1
  import { PROTOCOL_VERSION } from '../protocol/artifact.js';
2
2
  import { PATHS } from '../protocol/config.js';
3
+ import { checkLease, holdLease, markContact } from './contact.js';
3
4
  import { closeOnPageHide } from './lifecycle.js';
5
+ import { askPersistence } from './persist.js';
6
+ /** how long a flush may take to answer; the requests it sends are the wait */
7
+ const FLUSH_WAIT_MS = 30_000;
4
8
  function ask(worker, message, timeoutMs) {
5
9
  return new Promise((resolve, reject) => {
6
10
  const channel = new MessageChannel();
@@ -26,33 +30,86 @@ export async function register(options = {}) {
26
30
  if (!container)
27
31
  return null;
28
32
  const timeout = options.helloTimeoutMs ?? 5000;
33
+ let granted = null;
34
+ let asked = false;
35
+ let worker;
36
+ // persist() is Window-only, so the worker asks a page once after it first holds a dataset; the
37
+ // grant covers IndexedDB the worker writes. Nothing waits on the answer.
38
+ const persist = async () => {
39
+ if (asked)
40
+ return;
41
+ asked = true;
42
+ granted = await askPersistence(options.storage ?? navigator.storage);
43
+ (options.target ?? window).dispatchEvent(new CustomEvent('spool:persisted', { detail: { granted } }));
44
+ (worker ?? container.controller)?.postMessage({ type: 'spool:persisted', granted });
45
+ };
29
46
  // the worker tells every page when it wipes the principal store, so a page can blank what it shows
30
47
  container.addEventListener?.('message', (event) => {
31
48
  const data = event.data;
49
+ if (data?.type === 'spool:persist')
50
+ void persist();
51
+ if (data?.type === 'spool:contact' && typeof data.at === 'number')
52
+ markContact(data.at);
53
+ if (data?.type === 'spool:written') {
54
+ const { queued, flushed, conflicted } = data;
55
+ (options.target ?? window).dispatchEvent(new CustomEvent('spool:written', { detail: { queued, flushed, conflicted } }));
56
+ }
57
+ if (data?.type === 'spool:want-live') {
58
+ (options.target ?? window).dispatchEvent(new CustomEvent('spool:want-live'));
59
+ }
32
60
  if (data?.type !== 'spool:cleared')
33
61
  return;
34
62
  (options.target ?? window).dispatchEvent(new CustomEvent('spool:cleared', { detail: { reason: data.reason } }));
35
63
  });
64
+ const registeredAt = Date.now();
36
65
  await container.register(options.workerUrl ?? PATHS.worker, {
37
66
  scope: options.scope,
38
67
  updateViaCache: 'all'
39
68
  });
40
69
  const registration = await container.ready;
41
- const worker = registration.active;
42
- if (!worker)
70
+ const active = registration.active;
71
+ if (!active)
43
72
  throw new Error('the worker is not active');
44
- const hello = await ask(worker, { type: 'spool:hello', protocol: PROTOCOL_VERSION }, timeout);
73
+ worker = active;
74
+ const hello = await ask(active, { type: 'spool:hello', protocol: PROTOCOL_VERSION }, timeout);
75
+ if (hello.lease !== undefined) {
76
+ holdLease(registration, hello.lease);
77
+ // register() just ran the update check; a second one reaches the network in WebKit
78
+ markContact(registeredAt);
79
+ if (hello.contact !== undefined)
80
+ markContact(hello.contact);
81
+ checkLease();
82
+ }
83
+ // a write call never throws: a worker that is gone or silent is a refusal like any other
84
+ const askWrite = async (message, waitMs = timeout) => {
85
+ try {
86
+ const reply = await ask(registration.active ?? active, message, waitMs);
87
+ if (reply?.type === message.type)
88
+ return reply.result;
89
+ }
90
+ catch {
91
+ // falls through to the refusal
92
+ }
93
+ return { ok: false, code: 'unavailable', message: 'the worker did not answer' };
94
+ };
45
95
  return {
46
96
  registration,
47
97
  hello,
48
- status: () => ask(registration.active ?? worker, { type: 'spool:status' }, timeout),
49
- view: async (path = location.pathname) => (await ask(registration.active ?? worker, { type: 'spool:view', path }, timeout)).id,
50
- reportLoads: (id, count, origins) => (registration.active ?? worker).postMessage({
98
+ status: () => ask(registration.active ?? active, { type: 'spool:status' }, timeout),
99
+ view: async (path = location.pathname) => (await ask(registration.active ?? active, { type: 'spool:view', path }, timeout)).id,
100
+ reportLoads: (id, count, origins) => (registration.active ?? active).postMessage({
51
101
  type: 'spool:loads',
52
102
  view: id,
53
103
  count,
54
104
  origins
55
105
  }),
56
- track: (db) => closeOnPageHide(db)
106
+ persisted: () => granted,
107
+ liveState: () => ask(registration.active ?? active, { type: 'spool:live-state' }, timeout),
108
+ liveEvent: (message) => ask(registration.active ?? active, { type: 'spool:live', ...message }, timeout).catch(() => undefined),
109
+ track: (db) => closeOnPageHide(db),
110
+ write: (name, key, value, version) => askWrite({ type: 'spool:write', name, key, value, version }),
111
+ flush: () => askWrite({ type: 'spool:flush' }, Math.max(timeout, FLUSH_WAIT_MS)),
112
+ writes: () => askWrite({ type: 'spool:writes' }),
113
+ resolve: (name, key, use) => askWrite({ type: 'spool:resolve', name, key, use }, Math.max(timeout, FLUSH_WAIT_MS))
57
114
  };
58
115
  }
@@ -0,0 +1,11 @@
1
+ import type { IncomingMessage, ServerResponse } from 'node:http';
2
+ import type { Spool } from '../server/spool.js';
3
+ /** the continuation an Express middleware calls; pass an error to fail the request */
4
+ export type Next = (error?: unknown) => void;
5
+ /**
6
+ * Express middleware for a spool. Mount it with `app.use` before the routes. Spool's own paths are
7
+ * answered here. A declared write runs through `spool.handle`: the application's handler answers it,
8
+ * and the answer carries `Spool-Delta` or the digest. A GET that the application answers with a 200
9
+ * HTML page gets the envelope and the client tag. Every other request reaches the application untouched.
10
+ */
11
+ export declare function spoolExpress(spool: Spool): (req: IncomingMessage, res: ServerResponse, next: Next) => Promise<void>;
@@ -0,0 +1,209 @@
1
+ import { toRequest, writeResponse } from '../node/listener.js';
2
+ import { PATHS, SPOOL_PREFIX } from '../protocol/config.js';
3
+ import { HEADERS } from '../protocol/envelope.js';
4
+ import { writeFor } from '../protocol/write.js';
5
+ /**
6
+ * Express middleware for a spool. Mount it with `app.use` before the routes. Spool's own paths are
7
+ * answered here. A declared write runs through `spool.handle`: the application's handler answers it,
8
+ * and the answer carries `Spool-Delta` or the digest. A GET that the application answers with a 200
9
+ * HTML page gets the envelope and the client tag. Every other request reaches the application untouched.
10
+ */
11
+ export function spoolExpress(spool) {
12
+ return async (req, res, next) => {
13
+ const path = new URL(req.url ?? '/', 'http://localhost').pathname;
14
+ if (path === PATHS.worker && req.method === 'GET') {
15
+ await writeResponse(res, await spool.stub(toRequest(req, res)));
16
+ return;
17
+ }
18
+ if (path.startsWith(SPOOL_PREFIX)) {
19
+ const early = await spool.respond(toRequest(req, res));
20
+ if (early) {
21
+ await writeResponse(res, early, req.method === 'HEAD');
22
+ return;
23
+ }
24
+ }
25
+ if (req.method !== 'GET') {
26
+ const request = requestHead(req);
27
+ const url = new URL(request.url);
28
+ if (writeFor(spool.config.resourceWrites ?? [], request.method, url, url.origin)) {
29
+ const saved = res.getHeaders();
30
+ try {
31
+ await writeResponse(res, await spool.handle(request, () => replyOf(res, next)));
32
+ }
33
+ catch (error) {
34
+ if (res.headersSent)
35
+ res.destroy(error instanceof Error ? error : undefined);
36
+ else {
37
+ restoreHeaders(res, saved);
38
+ next(error);
39
+ }
40
+ }
41
+ return;
42
+ }
43
+ }
44
+ if (req.method === 'GET')
45
+ holdForEnvelope(spool, req, res, next);
46
+ next();
47
+ };
48
+ }
49
+ /**
50
+ * Holds a GET reply's writes until it ends. A 200 HTML reply goes through `spool.decorate`; any
51
+ * other reply is written through as the application made it.
52
+ */
53
+ function holdForEnvelope(spool, req, res, next) {
54
+ const { write, end } = res;
55
+ const request = toRequest(req, res);
56
+ const held = [];
57
+ let holding;
58
+ const restoreHead = captureWriteHead(res);
59
+ const restore = () => {
60
+ res.write = write;
61
+ res.end = end;
62
+ restoreHead();
63
+ };
64
+ const holds = () => {
65
+ if (holding === undefined) {
66
+ holding = isHtmlReply(res) || req.headers[HEADERS.have] !== undefined;
67
+ }
68
+ return holding;
69
+ };
70
+ res.write = ((chunk, ...args) => {
71
+ if (!holds()) {
72
+ restore();
73
+ return Reflect.apply(write, res, [chunk, ...args]);
74
+ }
75
+ held.push(toBuffer(chunk, args[0]));
76
+ const callback = args.at(-1);
77
+ if (typeof callback === 'function')
78
+ process.nextTick(callback);
79
+ return true;
80
+ });
81
+ res.end = ((chunk, ...args) => {
82
+ if (!holds()) {
83
+ restore();
84
+ return Reflect.apply(end, res, [chunk, ...args]);
85
+ }
86
+ const done = typeof chunk === 'function' ? chunk : args.at(-1);
87
+ if (chunk !== undefined && typeof chunk !== 'function')
88
+ held.push(toBuffer(chunk, args[0]));
89
+ restore();
90
+ sendWithEnvelope(spool, request, res, Buffer.concat(held).toString()).then(() => {
91
+ if (typeof done === 'function')
92
+ done();
93
+ }, (error) => {
94
+ if (res.headersSent)
95
+ res.destroy(error instanceof Error ? error : undefined);
96
+ else
97
+ next(error);
98
+ });
99
+ return res;
100
+ });
101
+ }
102
+ /**
103
+ * The request's URL and headers as a Fetch `Request` without a body. `toRequest` wraps `req` as a body
104
+ * stream, which would take the stream from the application's own body parser.
105
+ */
106
+ function requestHead(req) {
107
+ const encrypted = req.socket.encrypted === true;
108
+ const origin = `${encrypted ? 'https' : 'http'}://${req.headers.host ?? 'localhost'}`;
109
+ const headers = new Headers();
110
+ for (const [name, value] of Object.entries(req.headers)) {
111
+ if (value === undefined)
112
+ continue;
113
+ for (const v of Array.isArray(value) ? value : [value])
114
+ headers.append(name, v);
115
+ }
116
+ return new Request(new URL(req.url ?? '/', origin), { method: req.method, headers });
117
+ }
118
+ /** runs the rest of the Express chain and resolves with the reply it writes, held back from the socket */
119
+ function replyOf(res, next) {
120
+ return new Promise((resolve) => {
121
+ const { write, end } = res;
122
+ const held = [];
123
+ const restoreHead = captureWriteHead(res);
124
+ res.write = ((chunk, ...args) => {
125
+ held.push(toBuffer(chunk, args[0]));
126
+ const callback = args.at(-1);
127
+ if (typeof callback === 'function')
128
+ process.nextTick(callback);
129
+ return true;
130
+ });
131
+ res.end = ((chunk, ...args) => {
132
+ res.write = write;
133
+ res.end = end;
134
+ restoreHead();
135
+ if (chunk !== undefined && typeof chunk !== 'function')
136
+ held.push(toBuffer(chunk, args[0]));
137
+ const done = typeof chunk === 'function' ? chunk : args.at(-1);
138
+ if (typeof done === 'function')
139
+ process.nextTick(done);
140
+ resolve(replyResponse(res, held));
141
+ return res;
142
+ });
143
+ next();
144
+ });
145
+ }
146
+ const NULL_BODY_STATUS = new Set([101, 103, 204, 205, 304]);
147
+ function replyResponse(res, held) {
148
+ const empty = NULL_BODY_STATUS.has(res.statusCode) || held.length === 0;
149
+ return new Response(empty ? null : Buffer.concat(held), {
150
+ status: res.statusCode,
151
+ headers: headersOf(res)
152
+ });
153
+ }
154
+ /**
155
+ * Turns `res.writeHead(status, headers)` into `statusCode` and `setHeader` calls until the returned
156
+ * function runs. The real writeHead would fix the header block, and the adapter writes the reply
157
+ * itself later; Node's implicit header write uses the same headers.
158
+ */
159
+ function captureWriteHead(res) {
160
+ const writeHead = res.writeHead;
161
+ res.writeHead = ((status, ...rest) => {
162
+ res.statusCode = status;
163
+ const headers = typeof rest[0] === 'string' ? rest[1] : rest[0];
164
+ if (headers && typeof headers === 'object' && !Array.isArray(headers)) {
165
+ for (const [name, value] of Object.entries(headers)) {
166
+ if (value !== undefined)
167
+ res.setHeader(name, value);
168
+ }
169
+ }
170
+ return res;
171
+ });
172
+ return () => {
173
+ res.writeHead = writeHead;
174
+ };
175
+ }
176
+ function restoreHeaders(res, saved) {
177
+ for (const name of res.getHeaderNames())
178
+ res.removeHeader(name);
179
+ for (const [name, value] of Object.entries(saved)) {
180
+ if (value !== undefined)
181
+ res.setHeader(name, value);
182
+ }
183
+ }
184
+ function headersOf(res) {
185
+ const headers = new Headers();
186
+ for (const [name, value] of Object.entries(res.getHeaders())) {
187
+ for (const item of Array.isArray(value) ? value : [value]) {
188
+ if (item !== undefined)
189
+ headers.append(name, String(item));
190
+ }
191
+ }
192
+ return headers;
193
+ }
194
+ function isHtmlReply(res) {
195
+ const type = String(res.getHeader('content-type') ?? '').toLowerCase();
196
+ return (res.statusCode === 200 && type.includes('text/html') && !res.hasHeader('content-encoding'));
197
+ }
198
+ async function sendWithEnvelope(spool, request, res, body) {
199
+ const headers = headersOf(res);
200
+ const response = await spool.decorate(request, new Response(body, { status: res.statusCode, headers }));
201
+ for (const name of res.getHeaderNames())
202
+ res.removeHeader(name);
203
+ await writeResponse(res, response);
204
+ }
205
+ function toBuffer(chunk, encoding) {
206
+ if (typeof chunk !== 'string')
207
+ return Buffer.from(chunk);
208
+ return Buffer.from(chunk, typeof encoding === 'string' ? encoding : 'utf8');
209
+ }