@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,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,5 +1,5 @@
1
1
  import type { WriteFlush, WriteQueued, WriteRefusal, WriteResolved, WriteStatus } from '../protocol/write.js';
2
- import type { Hello, Status } from '../sw/runtime.js';
2
+ import type { Hello, LiveAck, LiveMessage, LiveState, Status } from '../sw/runtime.js';
3
3
  import { type Closable } from './lifecycle.js';
4
4
  /** what `register` takes */
5
5
  export type RegisterOptions = {
@@ -28,6 +28,16 @@ export type SpoolClient = {
28
28
  reportLoads(id: string, count: number, origins?: Record<string, number>): void;
29
29
  /** whether the browser granted persistent storage, or null until the worker held a dataset and the page asked */
30
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>;
31
41
  /** closes `db` when the page is hidden, so the page stays eligible for the back/forward cache */
32
42
  track(db: Closable): () => void;
33
43
  /**
@@ -1,6 +1,8 @@
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';
4
6
  /** how long a flush may take to answer; the requests it sends are the wait */
5
7
  const FLUSH_WAIT_MS = 30_000;
6
8
  function ask(worker, message, timeoutMs) {
@@ -37,14 +39,7 @@ export async function register(options = {}) {
37
39
  if (asked)
38
40
  return;
39
41
  asked = true;
40
- const storage = options.storage ?? navigator.storage;
41
- try {
42
- granted =
43
- (await storage?.persisted?.()) === true || (await storage?.persist?.()) === true;
44
- }
45
- catch {
46
- granted = false;
47
- }
42
+ granted = await askPersistence(options.storage ?? navigator.storage);
48
43
  (options.target ?? window).dispatchEvent(new CustomEvent('spool:persisted', { detail: { granted } }));
49
44
  (worker ?? container.controller)?.postMessage({ type: 'spool:persisted', granted });
50
45
  };
@@ -53,14 +48,20 @@ export async function register(options = {}) {
53
48
  const data = event.data;
54
49
  if (data?.type === 'spool:persist')
55
50
  void persist();
51
+ if (data?.type === 'spool:contact' && typeof data.at === 'number')
52
+ markContact(data.at);
56
53
  if (data?.type === 'spool:written') {
57
54
  const { queued, flushed, conflicted } = data;
58
55
  (options.target ?? window).dispatchEvent(new CustomEvent('spool:written', { detail: { queued, flushed, conflicted } }));
59
56
  }
57
+ if (data?.type === 'spool:want-live') {
58
+ (options.target ?? window).dispatchEvent(new CustomEvent('spool:want-live'));
59
+ }
60
60
  if (data?.type !== 'spool:cleared')
61
61
  return;
62
62
  (options.target ?? window).dispatchEvent(new CustomEvent('spool:cleared', { detail: { reason: data.reason } }));
63
63
  });
64
+ const registeredAt = Date.now();
64
65
  await container.register(options.workerUrl ?? PATHS.worker, {
65
66
  scope: options.scope,
66
67
  updateViaCache: 'all'
@@ -71,6 +72,14 @@ export async function register(options = {}) {
71
72
  throw new Error('the worker is not active');
72
73
  worker = active;
73
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
+ }
74
83
  // a write call never throws: a worker that is gone or silent is a refusal like any other
75
84
  const askWrite = async (message, waitMs = timeout) => {
76
85
  try {
@@ -95,6 +104,8 @@ export async function register(options = {}) {
95
104
  origins
96
105
  }),
97
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),
98
109
  track: (db) => closeOnPageHide(db),
99
110
  write: (name, key, value, version) => askWrite({ type: 'spool:write', name, key, value, version }),
100
111
  flush: () => askWrite({ type: 'spool:flush' }, Math.max(timeout, FLUSH_WAIT_MS)),
@@ -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
+ }
@@ -0,0 +1,19 @@
1
+ import type { Spool } from '../server/spool.js';
2
+ /** the parts of a Hono context the middleware uses, so the package needs no `hono` types */
3
+ export type SpoolHonoContext = {
4
+ /** the request side of the Hono context */
5
+ req: {
6
+ /** the Fetch `Request` for the incoming request */
7
+ raw: Request;
8
+ };
9
+ /** the response the route produced, or `undefined` before one exists */
10
+ res: Response | undefined;
11
+ };
12
+ /**
13
+ * Hono middleware for a spool. Mount it with `app.use('*', spoolHono(spool))`. Spool's own paths
14
+ * are answered before the routes run. A declared write runs through `spool.handle`: the route
15
+ * answers it, and the answer carries `Spool-Delta` or the digest. A GET that a route answers with a
16
+ * 200 HTML page gets the envelope and the client tag. Every other response is left as the
17
+ * application made it.
18
+ */
19
+ export declare function spoolHono(spool: Spool): (c: SpoolHonoContext, next: () => Promise<void>) => Promise<Response | undefined>;
@@ -0,0 +1,49 @@
1
+ import { PATHS } from '../protocol/config.js';
2
+ import { HEADERS } from '../protocol/envelope.js';
3
+ import { writeFor } from '../protocol/write.js';
4
+ /**
5
+ * Hono middleware for a spool. Mount it with `app.use('*', spoolHono(spool))`. Spool's own paths
6
+ * are answered before the routes run. A declared write runs through `spool.handle`: the route
7
+ * answers it, and the answer carries `Spool-Delta` or the digest. A GET that a route answers with a
8
+ * 200 HTML page gets the envelope and the client tag. Every other response is left as the
9
+ * application made it.
10
+ */
11
+ export function spoolHono(spool) {
12
+ return async (c, next) => {
13
+ const request = c.req.raw;
14
+ if (new URL(request.url).pathname === PATHS.worker && request.method === 'GET') {
15
+ return spool.stub(request);
16
+ }
17
+ const early = await spool.respond(request);
18
+ if (early)
19
+ return early;
20
+ const url = new URL(request.url);
21
+ if (writeFor(spool.config.resourceWrites ?? [], request.method, url, url.origin)) {
22
+ const decorated = await spool.handle(request, async () => {
23
+ await next();
24
+ return c.res ?? new Response('not found', { status: 404 });
25
+ });
26
+ // the setter copies the old response's headers over the new one, so clear it first
27
+ c.res = undefined;
28
+ c.res = decorated;
29
+ return undefined;
30
+ }
31
+ await next();
32
+ const response = c.res;
33
+ if (!response)
34
+ return undefined;
35
+ if (!isHtmlPage(request, response) && !request.headers.has(HEADERS.have))
36
+ return undefined;
37
+ const decorated = await spool.decorate(request, response);
38
+ // the setter copies the old response's headers over the new one, so clear it first
39
+ c.res = undefined;
40
+ c.res = decorated;
41
+ return undefined;
42
+ };
43
+ }
44
+ function isHtmlPage(request, response) {
45
+ return (request.method === 'GET' &&
46
+ response.status === 200 &&
47
+ (response.headers.get('content-type') ?? '').toLowerCase().includes('text/html') &&
48
+ !response.headers.has('content-encoding'));
49
+ }