@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,42 @@
1
+ /** where `publishStatic` writes its files: a host folder, an object store or memory */
2
+ export type StaticSink = {
3
+ put(path: string, bytes: Uint8Array, contentType: string): void | Promise<void>;
4
+ /** whether a file is already there; `publishStatic` leaves the immutable ones it finds alone */
5
+ has?(path: string): boolean | Promise<boolean>;
6
+ };
7
+ /** where the stub's site policy came from; `none` means the stub carries no `policy` field */
8
+ export type StaticPolicySource = 'call' | 'option' | 'page' | 'fallback' | 'none';
9
+ /** what `publishStatic` takes beside the sink */
10
+ export type PublishStaticOptions = {
11
+ /** the stub's site policy for this call, ahead of the `policy` option and a learned page; `{}` names no headers */
12
+ policy?: Record<string, string>;
13
+ /** the stub's site policy when the call, the option and a learned page give none */
14
+ fallbackPolicy?: Record<string, string>;
15
+ /** builds the pack at the store cursor first, as `publish(url)` does; ignored without `bundles` */
16
+ url?: URL;
17
+ /**
18
+ * With `cdn.worker`, reads the core's URL before anything is written and throws unless its bytes
19
+ * are this build's core. `true` uses the global `fetch`; pass a function to supply the read. Off
20
+ * by default, so a publish makes no request of its own.
21
+ */
22
+ verifyCore?: boolean | typeof fetch;
23
+ };
24
+ /** what `publishStatic` returns: the store cursor, the paths written and where the policy came from */
25
+ export type PublishStaticResult = {
26
+ version: number;
27
+ paths: string[];
28
+ policy: StaticPolicySource;
29
+ };
30
+ /** a sink that keeps every file in memory, with the paths it was asked to write in `puts` */
31
+ export declare function memoryStaticSink(): StaticSink & {
32
+ files: Map<string, {
33
+ bytes: Uint8Array;
34
+ contentType: string;
35
+ }>;
36
+ puts: string[];
37
+ };
38
+ /**
39
+ * The `_headers` file a static host reads: everything under `/.spool/` is immutable, and the stub
40
+ * lives for `maxAge` seconds, the same lease its own response names.
41
+ */
42
+ export declare function staticHeaders(maxAge: number): string;
@@ -0,0 +1,29 @@
1
+ /** a sink that keeps every file in memory, with the paths it was asked to write in `puts` */
2
+ export function memoryStaticSink() {
3
+ const files = new Map();
4
+ const puts = [];
5
+ return {
6
+ files,
7
+ puts,
8
+ put(path, bytes, contentType) {
9
+ puts.push(path);
10
+ files.set(path, { bytes, contentType });
11
+ },
12
+ has: (path) => files.has(path)
13
+ };
14
+ }
15
+ /**
16
+ * The `_headers` file a static host reads: everything under `/.spool/` is immutable, and the stub
17
+ * lives for `maxAge` seconds, the same lease its own response names.
18
+ */
19
+ export function staticHeaders(maxAge) {
20
+ return [
21
+ '/.spool/*',
22
+ ' Cache-Control: public, max-age=31536000, immutable',
23
+ '',
24
+ '/spool-sw.js',
25
+ ` Cache-Control: max-age=${maxAge}`,
26
+ ' Service-Worker-Allowed: /',
27
+ ''
28
+ ].join('\n');
29
+ }
@@ -1,9 +1,47 @@
1
- import type { SwConfig } from '../protocol/config.js';
1
+ import { type BundleDelta } from '../protocol/bundle.js';
2
+ import type { StubPack, SwConfig } from '../protocol/config.js';
3
+ import type { BundleStore } from './bundle.js';
4
+ /** the most versions back a worker script carries a delta from */
5
+ export declare const STUB_DELTAS = 4;
6
+ /** the most bytes of inline deltas a worker script carries; past it a device fetches one delta */
7
+ export declare const STUB_DELTA_BYTES = 16384;
2
8
  /** the worker script: the config as data, then the shared core or the site's own bundle */
3
9
  export declare function workerScript(config: SwConfig, core?: string): string;
10
+ /** the line that stands in for the core in a stub whose core is served from `url` */
11
+ export declare function workerImport(url: string): string;
4
12
  /**
5
- * The `/spool-sw.js` response. The script lives a day in the browser's cache, which is what lets
6
- * a controlled navigation skip the update check; a deploy changes the bytes and is picked up
7
- * within that bound.
13
+ * Reads `url` and throws unless its bytes hash to `expected`, the `shellHash` of the core the stub
14
+ * names. A script imported by a worker has no integrity check in the browser, so this is the one
15
+ * place the bytes are compared with the build.
8
16
  */
9
- export declare function workerResponse(script: string): Response;
17
+ export declare function checkCore(url: string, expected: string, fetcher: typeof fetch): Promise<void>;
18
+ /**
19
+ * The `/spool-sw.js` response. `script` is awaited while the body streams, so the body can read the
20
+ * store. The script lives for `maxAge` seconds in the browser's cache, which is the lease: a check
21
+ * inside it is answered locally, and a deploy or a new version is picked up after it.
22
+ */
23
+ export declare function workerResponse(script: () => Promise<string>, maxAge: number): Response;
24
+ /** the strong validator of a worker script: the hash of its exact bytes, quoted */
25
+ export declare function workerEtag(text: string): Promise<string>;
26
+ /** whether an `If-None-Match` value names `etag`; weak comparison, so a `W/` copy a proxy made matches */
27
+ export declare function matchesEtag(header: string | null, etag: string): boolean;
28
+ /**
29
+ * The `/spool-sw.js` response to `request`, with an `ETag`. A matching `If-None-Match` gets a `304`
30
+ * with the same headers and no body, so a re-check after the lease costs a few hundred bytes when the
31
+ * script is unchanged. `HEAD` gets the headers alone. The script is read whole, once per version.
32
+ */
33
+ export declare function workerReply(request: Request, script: () => Promise<{
34
+ text: string;
35
+ etag: string;
36
+ }>, maxAge: number): Promise<Response>;
37
+ /** the packs of one store, read once per version; a version's bytes never change */
38
+ export type PackReader = {
39
+ /** the pack a worker script carries for `version`, or undefined when no pack is held for it */
40
+ stub(version: number): Promise<StubPack | undefined>;
41
+ /** the delta from `from` to `to`, or undefined unless both are held and `from` is older */
42
+ delta(from: number, to: number): Promise<BundleDelta | undefined>;
43
+ };
44
+ /** a reader over `bundles`; its memo keeps every pack it has read, so a long-lived site holds them all */
45
+ export declare function packReader(bundles: BundleStore): PackReader;
46
+ /** the response to `GET /.spool/bundle/delta/<from>/<to>`: the delta as JSON, or 404 for a pair not held */
47
+ export declare function respondDelta(reader: PackReader | undefined, path: string): Promise<Response>;
@@ -1,19 +1,137 @@
1
+ import { makeDelta, readBundle } from '../protocol/bundle.js';
2
+ import { shellHash } from '../protocol/hash.js';
1
3
  import { SW_CORE } from './embedded.js';
4
+ import { json } from './sync.js';
5
+ /** the most versions back a worker script carries a delta from */
6
+ export const STUB_DELTAS = 4;
7
+ /** the most bytes of inline deltas a worker script carries; past it a device fetches one delta */
8
+ export const STUB_DELTA_BYTES = 16_384;
9
+ const encoder = new TextEncoder();
2
10
  /** the worker script: the config as data, then the shared core or the site's own bundle */
3
11
  export function workerScript(config, core = SW_CORE) {
4
12
  return `self.__SPOOL_CONFIG__=${JSON.stringify(config)};\n${core}`;
5
13
  }
14
+ /** the line that stands in for the core in a stub whose core is served from `url` */
15
+ export function workerImport(url) {
16
+ return `importScripts(${JSON.stringify(url)});`;
17
+ }
18
+ /**
19
+ * Reads `url` and throws unless its bytes hash to `expected`, the `shellHash` of the core the stub
20
+ * names. A script imported by a worker has no integrity check in the browser, so this is the one
21
+ * place the bytes are compared with the build.
22
+ */
23
+ export async function checkCore(url, expected, fetcher) {
24
+ const response = await fetcher(url, { headers: { 'accept-encoding': 'identity' } });
25
+ if (response.status !== 200) {
26
+ throw new Error(`cannot read the worker core at ${url} (HTTP ${response.status})`);
27
+ }
28
+ const got = await shellHash(await response.text());
29
+ if (got !== expected) {
30
+ throw new Error(`the worker core at ${url} does not match this build (expected ${expected}, got ${got})`);
31
+ }
32
+ }
6
33
  /**
7
- * The `/spool-sw.js` response. The script lives a day in the browser's cache, which is what lets
8
- * a controlled navigation skip the update check; a deploy changes the bytes and is picked up
9
- * within that bound.
34
+ * The `/spool-sw.js` response. `script` is awaited while the body streams, so the body can read the
35
+ * store. The script lives for `maxAge` seconds in the browser's cache, which is the lease: a check
36
+ * inside it is answered locally, and a deploy or a new version is picked up after it.
10
37
  */
11
- export function workerResponse(script) {
12
- return new Response(script, {
38
+ export function workerResponse(script, maxAge) {
39
+ const body = new ReadableStream({
40
+ async start(controller) {
41
+ controller.enqueue(encoder.encode(await script()));
42
+ controller.close();
43
+ }
44
+ });
45
+ return new Response(body, { headers: workerHeaders(maxAge) });
46
+ }
47
+ function workerHeaders(maxAge) {
48
+ return {
49
+ 'content-type': 'text/javascript; charset=utf-8',
50
+ 'cache-control': `max-age=${maxAge}`,
51
+ 'service-worker-allowed': '/'
52
+ };
53
+ }
54
+ /** the strong validator of a worker script: the hash of its exact bytes, quoted */
55
+ export async function workerEtag(text) {
56
+ return `"${await shellHash(text)}"`;
57
+ }
58
+ /** whether an `If-None-Match` value names `etag`; weak comparison, so a `W/` copy a proxy made matches */
59
+ export function matchesEtag(header, etag) {
60
+ if (!header)
61
+ return false;
62
+ const tag = (value) => value.trim().replace(/^W\//, '');
63
+ return header.split(',').some((value) => tag(value) === '*' || tag(value) === tag(etag));
64
+ }
65
+ /**
66
+ * The `/spool-sw.js` response to `request`, with an `ETag`. A matching `If-None-Match` gets a `304`
67
+ * with the same headers and no body, so a re-check after the lease costs a few hundred bytes when the
68
+ * script is unchanged. `HEAD` gets the headers alone. The script is read whole, once per version.
69
+ */
70
+ export async function workerReply(request, script, maxAge) {
71
+ const { text, etag } = await script();
72
+ const headers = { ...workerHeaders(maxAge), etag };
73
+ if (matchesEtag(request.headers.get('if-none-match'), etag)) {
74
+ return new Response(null, { status: 304, headers });
75
+ }
76
+ return new Response(request.method === 'HEAD' ? null : text, { headers });
77
+ }
78
+ /** a reader over `bundles`; its memo keeps every pack it has read, so a long-lived site holds them all */
79
+ export function packReader(bundles) {
80
+ const read = new Map();
81
+ async function packAt(version) {
82
+ if (version < 0)
83
+ return undefined;
84
+ const held = read.get(version);
85
+ if (held)
86
+ return held;
87
+ const bytes = await bundles.get(version);
88
+ if (bytes === undefined)
89
+ return undefined;
90
+ const pack = readBundle(bytes);
91
+ read.set(version, pack);
92
+ return pack;
93
+ }
94
+ return {
95
+ async stub(version) {
96
+ const to = await packAt(version);
97
+ if (!to)
98
+ return undefined;
99
+ const deltas = [];
100
+ let bytes = 0;
101
+ for (let back = 1; back <= STUB_DELTAS; back++) {
102
+ const from = await packAt(version - back);
103
+ if (!from)
104
+ continue;
105
+ const delta = await makeDelta(from.state, to.state);
106
+ const size = encoder.encode(JSON.stringify(delta)).length;
107
+ if (bytes + size > STUB_DELTA_BYTES)
108
+ break;
109
+ bytes += size;
110
+ deltas.push(delta);
111
+ }
112
+ return { version, digest: to.index.digest, deltas };
113
+ },
114
+ async delta(from, to) {
115
+ if (from >= to)
116
+ return undefined;
117
+ const base = await packAt(from);
118
+ const target = await packAt(to);
119
+ if (!base || !target)
120
+ return undefined;
121
+ return makeDelta(base.state, target.state);
122
+ }
123
+ };
124
+ }
125
+ /** the response to `GET /.spool/bundle/delta/<from>/<to>`: the delta as JSON, or 404 for a pair not held */
126
+ export async function respondDelta(reader, path) {
127
+ const match = /^(\d{1,15})\/(\d{1,15})$/.exec(path);
128
+ const delta = reader && match ? await reader.delta(Number(match[1]), Number(match[2])) : undefined;
129
+ if (!delta)
130
+ return json({ error: 'no delta' }, 404);
131
+ return new Response(JSON.stringify(delta), {
13
132
  headers: {
14
- 'content-type': 'text/javascript; charset=utf-8',
15
- 'cache-control': 'max-age=86400',
16
- 'service-worker-allowed': '/'
133
+ 'content-type': 'application/json',
134
+ 'cache-control': 'public, max-age=31536000, immutable'
17
135
  }
18
136
  });
19
137
  }
@@ -0,0 +1,49 @@
1
+ import type { Dataset } from '../protocol/dataset.js';
2
+ import type { Identity, Route } from '../protocol/route.js';
3
+ import { type Write } from '../protocol/write.js';
4
+ import type { VersionStore } from '../stores/version-store.js';
5
+ import { type BundleStore } from './bundle.js';
6
+ /** how many `(class, principal, key)` slots the server remembers an applied write id for */
7
+ export declare const DEFAULT_REMEMBER = 10000;
8
+ /** what {@link createWriteServer} takes */
9
+ export type WriteServerOptions = {
10
+ /** false answers every request with `writes-off` */
11
+ enabled: boolean;
12
+ writes: readonly Write[];
13
+ /** slots whose last applied id is remembered, oldest forgotten first; default {@link DEFAULT_REMEMBER} */
14
+ remember?: number;
15
+ };
16
+ /** the handler `createSpool` routes `PUT /.spool/write` to */
17
+ export type WriteServer = {
18
+ respond(request: Request, identity: Identity | null): Promise<Response>;
19
+ };
20
+ /**
21
+ * Answers `PUT /.spool/write?name=<n>&key=<k>` with `If-Match: "<version>"` and a `Spool-Write-Id`.
22
+ * It checks the declaration, the principal, the key the site derives for that principal, the version
23
+ * header and the body size before `apply` runs, and runs one request per `(class, principal, key)` at
24
+ * a time. The last applied write id of each slot is kept in memory: a repeat of that id and body
25
+ * answers 200 with the current version and applies nothing, and the same id with another body is
26
+ * refused. Memory is per server instance, so a deployment with several instances needs the site's
27
+ * `apply` to store `ctx.writeId` with the value to keep a retry that lands on another instance from
28
+ * reading as a conflict.
29
+ */
30
+ export declare function createWriteServer(options: WriteServerOptions): WriteServer;
31
+ /** the most bytes a `Spool-Delta` header may carry; past it the worker fetches the delta route */
32
+ export declare const DELTA_HEADER_BYTES = 16384;
33
+ /** what {@link createResourceWrites} takes */
34
+ export type ResourceWriteOptions = {
35
+ datasets: ReadonlyMap<string, Dataset>;
36
+ store: VersionStore;
37
+ bundles: BundleStore;
38
+ /** the site's routes; their index tables go into every pack a write builds, as `publish` does */
39
+ routes: readonly Route[];
40
+ blockRows?: number;
41
+ maxBytes?: number;
42
+ };
43
+ /**
44
+ * Runs a declared resource write's handler and, when it answers 2xx, attaches the rows the handler
45
+ * changed as `Spool-Delta`. The store moves to the version of the new pack, and that pack is kept, so the
46
+ * delta route and the worker script can reach it. Writes run one at a time, so each starts from the pack
47
+ * the one before it left.
48
+ */
49
+ export declare function createResourceWrites(options: ResourceWriteOptions): (request: Request, next: (request: Request) => Response | Promise<Response>) => Promise<Response>;
@@ -0,0 +1,223 @@
1
+ import { buildPack, bundleDigest, makeDelta, readBundle } from '../protocol/bundle.js';
2
+ import { HEADERS } from '../protocol/envelope.js';
3
+ import { ProtocolError } from '../protocol/errors.js';
4
+ import { shellHash } from '../protocol/hash.js';
5
+ import { isWriteId, isWriteKey, readIfMatch, WRITE_HEADERS, WRITE_STATUS } from '../protocol/write.js';
6
+ import { buildBundle, indexTables, memoryBundleStore } from './bundle.js';
7
+ import { json } from './sync.js';
8
+ /** how many `(class, principal, key)` slots the server remembers an applied write id for */
9
+ export const DEFAULT_REMEMBER = 10_000;
10
+ const refuse = (code, error, headers = {}) => json({ code, error }, WRITE_STATUS[code], headers);
11
+ /** the body as text, or null when it is longer than `max` bytes; stops reading once it is */
12
+ async function readBounded(request, max) {
13
+ const declared = Number(request.headers.get('content-length') ?? Number.NaN);
14
+ if (declared > max)
15
+ return null;
16
+ if (!request.body)
17
+ return '';
18
+ const reader = request.body.getReader();
19
+ const chunks = [];
20
+ let total = 0;
21
+ for (;;) {
22
+ const { done, value } = await reader.read();
23
+ if (done)
24
+ break;
25
+ total += value.byteLength;
26
+ if (total > max) {
27
+ await reader.cancel();
28
+ return null;
29
+ }
30
+ chunks.push(value);
31
+ }
32
+ const whole = new Uint8Array(total);
33
+ let at = 0;
34
+ for (const chunk of chunks) {
35
+ whole.set(chunk, at);
36
+ at += chunk.byteLength;
37
+ }
38
+ return new TextDecoder().decode(whole);
39
+ }
40
+ /**
41
+ * Answers `PUT /.spool/write?name=<n>&key=<k>` with `If-Match: "<version>"` and a `Spool-Write-Id`.
42
+ * It checks the declaration, the principal, the key the site derives for that principal, the version
43
+ * header and the body size before `apply` runs, and runs one request per `(class, principal, key)` at
44
+ * a time. The last applied write id of each slot is kept in memory: a repeat of that id and body
45
+ * answers 200 with the current version and applies nothing, and the same id with another body is
46
+ * refused. Memory is per server instance, so a deployment with several instances needs the site's
47
+ * `apply` to store `ctx.writeId` with the value to keep a retry that lands on another instance from
48
+ * reading as a conflict.
49
+ */
50
+ export function createWriteServer(options) {
51
+ const byName = new Map(options.writes.map((write) => [write.name, write]));
52
+ const limit = options.remember ?? DEFAULT_REMEMBER;
53
+ const applied = new Map();
54
+ const locks = new Map();
55
+ const remember = (slot, entry) => {
56
+ applied.delete(slot);
57
+ applied.set(slot, entry);
58
+ while (applied.size > limit)
59
+ applied.delete(applied.keys().next().value);
60
+ };
61
+ /** runs `fn` after every earlier request for the same slot */
62
+ function exclusive(slot, fn) {
63
+ const run = (locks.get(slot) ?? Promise.resolve()).then(fn, fn);
64
+ const tail = run.catch(() => undefined);
65
+ locks.set(slot, tail);
66
+ void tail.then(() => {
67
+ if (locks.get(slot) === tail)
68
+ locks.delete(slot);
69
+ });
70
+ return run;
71
+ }
72
+ return {
73
+ async respond(request, identity) {
74
+ if (!options.enabled)
75
+ return refuse('writes-off', 'declared writes are off');
76
+ if (request.method !== 'PUT') {
77
+ return refuse('bad-method', 'use PUT', { allow: 'PUT' });
78
+ }
79
+ const url = new URL(request.url);
80
+ const write = byName.get(url.searchParams.get('name') ?? '');
81
+ if (!write)
82
+ return refuse('unknown-write', 'no such write class');
83
+ if (!identity)
84
+ return refuse('sign-in', 'sign in to write');
85
+ const key = url.searchParams.get('key');
86
+ if (!isWriteKey(key))
87
+ return refuse('bad-key', 'key is missing or malformed');
88
+ const id = request.headers.get(WRITE_HEADERS.id);
89
+ if (!isWriteId(id))
90
+ return refuse('bad-id', 'Spool-Write-Id is missing or malformed');
91
+ const header = request.headers.get('if-match');
92
+ if (header === null)
93
+ return refuse('missing-version', 'If-Match is required');
94
+ const version = readIfMatch(header);
95
+ if (version === null)
96
+ return refuse('bad-version', 'If-Match is not one version');
97
+ const ctx = { identity, writeId: id };
98
+ if ((await write.key(ctx, request)) !== key) {
99
+ return refuse('forbidden', 'that key is not yours');
100
+ }
101
+ const text = await readBounded(request, write.maxBytes);
102
+ if (text === null)
103
+ return refuse('too-large', `the body is over ${write.maxBytes} bytes`);
104
+ let value;
105
+ try {
106
+ const body = JSON.parse(text);
107
+ if (typeof body !== 'object' || body === null || !('value' in body))
108
+ throw new Error();
109
+ value = body.value;
110
+ }
111
+ catch {
112
+ return refuse('bad-body', 'the body must be JSON of the form {"value": ...}');
113
+ }
114
+ const slot = `${write.name}\u0000${identity.principal}\u0000${key}`;
115
+ return exclusive(slot, async () => {
116
+ const hash = await shellHash(text);
117
+ const last = applied.get(slot);
118
+ if (last?.id === id) {
119
+ if (last.hash !== hash)
120
+ return refuse('id-reused', 'that id was used for another body');
121
+ return json({ version: (await write.read(ctx, key)).version });
122
+ }
123
+ const result = await write.apply(ctx, key, value, version);
124
+ if ('conflict' in result)
125
+ return json({ code: 'conflict', conflict: result.conflict }, 412);
126
+ remember(slot, { id, hash });
127
+ return json({ version: result.version });
128
+ });
129
+ }
130
+ };
131
+ }
132
+ /** the most bytes a `Spool-Delta` header may carry; past it the worker fetches the delta route */
133
+ export const DELTA_HEADER_BYTES = 16_384;
134
+ /**
135
+ * Runs a declared resource write's handler and, when it answers 2xx, attaches the rows the handler
136
+ * changed as `Spool-Delta`. The store moves to the version of the new pack, and that pack is kept, so the
137
+ * delta route and the worker script can reach it. Writes run one at a time, so each starts from the pack
138
+ * the one before it left.
139
+ */
140
+ export function createResourceWrites(options) {
141
+ let tail = Promise.resolve();
142
+ return (request, next) => {
143
+ const run = tail.then(() => runResourceWrite(request, next, options));
144
+ tail = run.catch(() => undefined);
145
+ return run;
146
+ };
147
+ }
148
+ /** the rows of one public dataset, read in full; for a dataset whose `changes` answers `reset` */
149
+ async function reseed(dataset, url) {
150
+ const scratch = memoryBundleStore();
151
+ await buildBundle({ store: scratch, datasets: [dataset], version: 0, url });
152
+ const bytes = await scratch.get(0);
153
+ if (!bytes)
154
+ throw new ProtocolError('bad-bundle', `${dataset.name}: the reseed stored no pack`);
155
+ return (await readBundle(bytes)).state.tables[dataset.name] ?? [];
156
+ }
157
+ async function runResourceWrite(request, next, { datasets, store, bundles, routes, blockRows, maxBytes }) {
158
+ const url = new URL(request.url);
159
+ const ctx = { request, url };
160
+ const publics = [...datasets.values()].filter((dataset) => dataset.scope === 'public');
161
+ const before = await store.cursor();
162
+ const heads = new Map();
163
+ for (const dataset of publics)
164
+ heads.set(dataset.name, (await dataset.head(ctx)).cursor);
165
+ if (!(await bundles.get(before))) {
166
+ await buildBundle({
167
+ store: bundles,
168
+ datasets: publics,
169
+ routes,
170
+ version: before,
171
+ url,
172
+ blockRows,
173
+ maxBytes
174
+ });
175
+ }
176
+ const bytes = await bundles.get(before);
177
+ const response = await next(request);
178
+ if (!bytes || !response.ok)
179
+ return response;
180
+ const base = await readBundle(bytes);
181
+ const tables = {};
182
+ for (const dataset of publics)
183
+ tables[dataset.name] = base.state.tables[dataset.name] ?? [];
184
+ const moved = [];
185
+ for (const dataset of publics) {
186
+ const change = await dataset.changes(heads.get(dataset.name), ctx);
187
+ if (change === 'reset') {
188
+ tables[dataset.name] = await reseed(dataset, url);
189
+ moved.push(dataset.name);
190
+ continue;
191
+ }
192
+ if (change.puts.length === 0 && change.deletes.length === 0)
193
+ continue;
194
+ const rows = new Map(tables[dataset.name] ?? []);
195
+ for (const { key } of change.deletes)
196
+ rows.delete(key);
197
+ if (change.puts.length > 0) {
198
+ for (const row of await dataset.read(change.puts, ctx))
199
+ rows.set(dataset.key(row), row);
200
+ }
201
+ tables[dataset.name] = [...rows];
202
+ moved.push(dataset.name);
203
+ }
204
+ if (moved.length === 0)
205
+ return response;
206
+ const to = await store.bump(moved);
207
+ const state = { version: to, tables: { ...tables, ...indexTables(routes, tables) } };
208
+ const built = await buildPack(state, blockRows, maxBytes);
209
+ await bundles.put(to, built.bytes);
210
+ const text = JSON.stringify(await makeDelta(base.state, state));
211
+ const headers = new Headers(response.headers);
212
+ if (new TextEncoder().encode(text).length <= DELTA_HEADER_BYTES) {
213
+ headers.set(HEADERS.delta, text);
214
+ }
215
+ else {
216
+ headers.set(WRITE_HEADERS.digest, await bundleDigest(state.tables));
217
+ }
218
+ return new Response(response.body, {
219
+ status: response.status,
220
+ statusText: response.statusText,
221
+ headers
222
+ });
223
+ }
@@ -1,5 +1,7 @@
1
1
  import { DurableObject } from 'cloudflare:workers';
2
+ import type { LiveDelta } from '../protocol/envelope.js';
2
3
  import type { VectorDiff } from '../protocol/vector.js';
4
+ import { type LiveHub, type LiveStats } from '../server/live.js';
3
5
  import type { VersionStore } from './version-store.js';
4
6
  /**
5
7
  * The version vector in a SQLite-backed Durable Object: one row per tag and one cursor row, so it
@@ -17,3 +19,47 @@ export declare class SpoolVersions extends DurableObject {
17
19
  }
18
20
  /** a {@link VersionStore} over one named instance of the {@link SpoolVersions} namespace */
19
21
  export declare function durableObjectStore(namespace: DurableObjectNamespace<SpoolVersions>, name?: string): VersionStore;
22
+ /**
23
+ * The live streams of every isolate, held by one Durable Object: a page's `/.spool/live` request
24
+ * is forwarded here and its response is the stream, so a bump or a revocation from any isolate
25
+ * reaches every open page. The object stays in memory while a stream is open and is billed for
26
+ * that duration. One instance serves every stream of a site, which is its ceiling. Bind it as a
27
+ * Durable Object class and pass the namespace to {@link durableObjectHub}.
28
+ *
29
+ * A WebSocket upgrade is accepted with the Hibernation API when the hub sets `hibernate`. Those
30
+ * sockets hold no timer, so while no SSE stream is open the object hibernates between a publish, a
31
+ * revoke, a maximum-age alarm and a message that is not a ping.
32
+ */
33
+ export declare class SpoolLive extends DurableObject {
34
+ #private;
35
+ constructor(ctx: DurableObjectState, env: Cloudflare.Env);
36
+ fetch(request: Request): Promise<Response>;
37
+ /** sends a delta to every open stream and socket */
38
+ publish(delta: LiveDelta): void;
39
+ /** sends `revoked` to every stream and socket of `partition` and closes them */
40
+ revoke(partition: string): void;
41
+ webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void;
42
+ webSocketClose(ws: WebSocket, code: number): void;
43
+ webSocketError(ws: WebSocket): void;
44
+ alarm(): Promise<void>;
45
+ /** what this object has counted since it started */
46
+ stats(): LiveStats;
47
+ }
48
+ /** the options of {@link durableObjectHub} */
49
+ export type DurableObjectHubOptions = {
50
+ /** which instance of the namespace holds the streams; default `spool` */
51
+ name?: string;
52
+ /**
53
+ * Accept a page's WebSocket upgrade with the Hibernation API instead of holding an SSE response.
54
+ * The site's config then tells pages to open a socket, and a page whose upgrade fails falls back
55
+ * to SSE. Default false.
56
+ */
57
+ hibernate?: boolean;
58
+ };
59
+ /**
60
+ * A {@link LiveHub} over one named instance of the {@link SpoolLive} namespace. The hub cannot
61
+ * call back into the app, so a session the app ends is revoked with `spool.revoke`, and one it
62
+ * forgets to revoke is cut off when its stream reaches `maxAge`. The second argument is the
63
+ * instance name or {@link DurableObjectHubOptions}.
64
+ */
65
+ export declare function durableObjectHub(namespace: DurableObjectNamespace<SpoolLive>, options?: string | DurableObjectHubOptions): LiveHub;