@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.
- package/README.md +206 -1756
- package/dist/angular/index.d.ts +13 -0
- package/dist/angular/index.js +25 -0
- package/dist/angular/pages.d.ts +28 -0
- package/dist/angular/pages.js +85 -0
- package/dist/cdn/client.js +1 -1
- package/dist/cdn/location.d.ts +6 -0
- package/dist/cdn/location.js +8 -0
- package/dist/cdn/manifest.json +7 -7
- package/dist/cdn/spool-sw.js +1 -1
- package/dist/client/bootstrap.d.ts +57 -0
- package/dist/client/bootstrap.js +307 -0
- package/dist/client/contact.d.ts +24 -0
- package/dist/client/contact.js +66 -0
- package/dist/client/declared.d.ts +23 -0
- package/dist/client/declared.js +68 -0
- package/dist/client/entry.js +91 -2
- package/dist/client/gate.d.ts +1 -0
- package/dist/client/gate.js +148 -0
- package/dist/client/index.d.ts +25 -0
- package/dist/client/index.js +1 -0
- package/dist/client/live.d.ts +66 -0
- package/dist/client/live.js +225 -0
- package/dist/client/navigate-entry.d.ts +1 -0
- package/dist/client/navigate-entry.js +4 -0
- package/dist/client/navigate.d.ts +54 -0
- package/dist/client/navigate.js +272 -0
- package/dist/client/persist.d.ts +2 -0
- package/dist/client/persist.js +9 -0
- package/dist/client/register.d.ts +11 -1
- package/dist/client/register.js +19 -8
- package/dist/express/index.d.ts +11 -0
- package/dist/express/index.js +209 -0
- package/dist/hono/index.d.ts +19 -0
- package/dist/hono/index.js +49 -0
- package/dist/next/index.d.ts +33 -0
- package/dist/next/index.js +41 -0
- package/dist/next/pages.d.ts +22 -0
- package/dist/next/pages.js +39 -0
- package/dist/node/listener.d.ts +3 -0
- package/dist/node/listener.js +57 -2
- package/dist/nuxt/index.d.ts +22 -0
- package/dist/nuxt/index.js +104 -0
- package/dist/nuxt/pages.d.ts +26 -0
- package/dist/nuxt/pages.js +48 -0
- package/dist/nuxt/runtime/index.d.ts +24 -0
- package/dist/nuxt/runtime/index.js +58 -0
- package/dist/plugins/coverage.d.ts +14 -0
- package/dist/plugins/coverage.js +27 -0
- package/dist/plugins/mode.d.ts +19 -0
- package/dist/plugins/mode.js +20 -0
- package/dist/plugins/path.d.ts +16 -0
- package/dist/plugins/path.js +139 -0
- package/dist/plugins/report.d.ts +22 -0
- package/dist/plugins/report.js +18 -0
- package/dist/plugins/routes.d.ts +38 -0
- package/dist/plugins/routes.js +52 -0
- package/dist/plugins/static.d.ts +42 -0
- package/dist/plugins/static.js +97 -0
- package/dist/protocol/bundle.d.ts +111 -0
- package/dist/protocol/bundle.js +428 -0
- package/dist/protocol/config.d.ts +65 -1
- package/dist/protocol/config.js +28 -0
- package/dist/protocol/dataset.d.ts +6 -0
- package/dist/protocol/dataset.js +6 -0
- package/dist/protocol/envelope.d.ts +33 -1
- package/dist/protocol/envelope.js +15 -1
- package/dist/protocol/errors.d.ts +1 -1
- package/dist/protocol/index-rows.d.ts +22 -0
- package/dist/protocol/index-rows.js +53 -0
- package/dist/protocol/index.d.ts +2 -0
- package/dist/protocol/index.js +2 -0
- package/dist/protocol/normalise.d.ts +4 -4
- package/dist/protocol/normalise.js +9 -5
- package/dist/protocol/ring.d.ts +58 -0
- package/dist/protocol/ring.js +6 -0
- package/dist/protocol/route.d.ts +57 -11
- package/dist/protocol/route.js +95 -3
- package/dist/protocol/tag.d.ts +22 -2
- package/dist/protocol/tag.js +25 -4
- package/dist/protocol/view.d.ts +2 -0
- package/dist/protocol/view.js +8 -2
- package/dist/protocol/views.d.ts +6 -0
- package/dist/protocol/views.js +15 -0
- package/dist/protocol/write.d.ts +92 -4
- package/dist/protocol/write.js +251 -9
- package/dist/proxy/eligible.d.ts +22 -1
- package/dist/proxy/eligible.js +62 -15
- package/dist/proxy/proxy.js +28 -18
- package/dist/react-router/index.d.ts +20 -0
- package/dist/react-router/index.js +60 -0
- package/dist/react-router/pages.d.ts +34 -0
- package/dist/react-router/pages.js +83 -0
- package/dist/report/demand.d.ts +49 -0
- package/dist/report/demand.js +60 -0
- package/dist/report/economics.d.ts +55 -0
- package/dist/report/economics.js +189 -0
- package/dist/report/headline.d.ts +158 -0
- package/dist/report/headline.js +473 -0
- package/dist/report/index.d.ts +2 -0
- package/dist/report/index.js +2 -0
- package/dist/report/inputs.d.ts +79 -0
- package/dist/report/inputs.js +115 -0
- package/dist/report/measurement.d.ts +1 -1
- package/dist/report/measurement.js +5 -1
- package/dist/report/traffic.d.ts +8 -0
- package/dist/report/traffic.js +7 -0
- package/dist/server/bundle.d.ts +55 -0
- package/dist/server/bundle.js +172 -0
- package/dist/server/dataset.d.ts +8 -2
- package/dist/server/dataset.js +51 -4
- package/dist/server/embedded.d.ts +7 -3
- package/dist/server/embedded.js +7 -3
- package/dist/server/index.d.ts +5 -1
- package/dist/server/index.js +5 -1
- package/dist/server/live-sockets.d.ts +54 -0
- package/dist/server/live-sockets.js +131 -0
- package/dist/server/live.d.ts +146 -0
- package/dist/server/live.js +228 -0
- package/dist/server/ring.d.ts +77 -0
- package/dist/server/ring.js +311 -0
- package/dist/server/spool.d.ts +139 -4
- package/dist/server/spool.js +457 -28
- package/dist/server/static.d.ts +42 -0
- package/dist/server/static.js +29 -0
- package/dist/server/stub.d.ts +43 -5
- package/dist/server/stub.js +126 -8
- package/dist/server/write.d.ts +23 -1
- package/dist/server/write.js +96 -0
- package/dist/stores/durable-object.d.ts +46 -0
- package/dist/stores/durable-object.js +114 -0
- package/dist/sw/analytics.d.ts +1 -1
- package/dist/sw/analytics.js +2 -2
- package/dist/sw/coverage.d.ts +6 -0
- package/dist/sw/coverage.js +34 -0
- package/dist/sw/family.d.ts +15 -0
- package/dist/sw/family.js +48 -0
- package/dist/sw/idb.d.ts +2 -0
- package/dist/sw/idb.js +2 -2
- package/dist/sw/index.d.ts +2 -0
- package/dist/sw/index.js +1 -0
- package/dist/sw/pack/store.d.ts +128 -0
- package/dist/sw/pack/store.js +737 -0
- package/dist/sw/policy.d.ts +2 -0
- package/dist/sw/policy.js +11 -0
- package/dist/sw/probe.d.ts +16 -0
- package/dist/sw/probe.js +25 -0
- package/dist/sw/router.d.ts +3 -2
- package/dist/sw/router.js +15 -2
- package/dist/sw/runtime.d.ts +48 -1
- package/dist/sw/runtime.js +548 -68
- package/dist/sw/scheduler.d.ts +6 -1
- package/dist/sw/scheduler.js +22 -5
- package/dist/sw/write.d.ts +41 -1
- package/dist/sw/write.js +188 -5
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -2
- package/dist/vite/index.d.ts +26 -0
- package/dist/vite/index.js +66 -0
- package/dist/vue/index.d.ts +36 -0
- package/dist/vue/index.js +53 -0
- package/package.json +64 -4
package/dist/server/index.d.ts
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
|
+
export * from '../plugins/routes.js';
|
|
1
2
|
export { defineDataset } from '../protocol/dataset.js';
|
|
2
3
|
export { datasetProof } from '../protocol/query.js';
|
|
3
4
|
export { defineRoute } from '../protocol/route.js';
|
|
4
|
-
export { defineWrite } from '../protocol/write.js';
|
|
5
|
+
export { defineResource, defineWrite } from '../protocol/write.js';
|
|
6
|
+
export { buildBundle, memoryBundleStore, type BuildBundleOptions, type BuiltBundle, type BundleStore } from './bundle.js';
|
|
5
7
|
export * from './ga4.js';
|
|
6
8
|
export * from './identity.js';
|
|
9
|
+
export { memoryHub, type LiveFrame, type LiveHub, type LiveOpen, type LiveOptions, type LiveStats, type MemoryHub, type MemoryHubOptions } from './live.js';
|
|
7
10
|
export * from './sink.js';
|
|
8
11
|
export * from './size.js';
|
|
9
12
|
export * from './spool.js';
|
|
13
|
+
export * from './static.js';
|
|
10
14
|
export * from './work.js';
|
package/dist/server/index.js
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
|
+
export * from '../plugins/routes.js';
|
|
1
2
|
export { defineDataset } from '../protocol/dataset.js';
|
|
2
3
|
export { datasetProof } from '../protocol/query.js';
|
|
3
4
|
export { defineRoute } from '../protocol/route.js';
|
|
4
|
-
export { defineWrite } from '../protocol/write.js';
|
|
5
|
+
export { defineResource, defineWrite } from '../protocol/write.js';
|
|
6
|
+
export { buildBundle, memoryBundleStore } from './bundle.js';
|
|
5
7
|
export * from './ga4.js';
|
|
6
8
|
export * from './identity.js';
|
|
9
|
+
export { memoryHub } from './live.js';
|
|
7
10
|
export * from './sink.js';
|
|
8
11
|
export * from './size.js';
|
|
9
12
|
export * from './spool.js';
|
|
13
|
+
export * from './static.js';
|
|
10
14
|
export * from './work.js';
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { LiveDelta } from '../protocol/envelope.js';
|
|
2
|
+
import { type LiveOpen } from './live.js';
|
|
3
|
+
/** the part of a hibernatable `WebSocket` the hub uses */
|
|
4
|
+
export type LiveSocket = {
|
|
5
|
+
send(text: string): void;
|
|
6
|
+
close(code?: number, reason?: string): void;
|
|
7
|
+
serializeAttachment(value: unknown): void;
|
|
8
|
+
deserializeAttachment(): unknown;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* @internal what the hub needs from a Durable Object: `SpoolLive` fills it from `ctx`, a test fills
|
|
12
|
+
* it with fakes whose sockets outlive the hub, as the runtime's do
|
|
13
|
+
*/
|
|
14
|
+
export type SocketHost = {
|
|
15
|
+
pair(): [client: LiveSocket, server: LiveSocket];
|
|
16
|
+
accept(server: LiveSocket, tags: string[]): void;
|
|
17
|
+
sockets(tag?: string): LiveSocket[];
|
|
18
|
+
autoResponse(request: string, response: string): void;
|
|
19
|
+
alarm: {
|
|
20
|
+
get(): Promise<number | null>;
|
|
21
|
+
set(at: number): Promise<void>;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
/** what a socket needs at open; the rest of {@link LiveOpen} belongs to the SSE hub */
|
|
25
|
+
export type SocketOpen = Pick<LiveOpen, 'partition' | 'first' | 'leaseMs' | 'maxAgeMs'>;
|
|
26
|
+
/** the request header that carries {@link SocketOpen} from the Worker to the object, since a GET upgrade has no body */
|
|
27
|
+
export declare const SOCKET_OPEN_HEADER = "x-spool-open";
|
|
28
|
+
/** the encoded opening header is at most this long, a bound chosen here and not read from the platform */
|
|
29
|
+
export declare const SOCKET_OPEN_MAX = 8192;
|
|
30
|
+
/** the opening request as a header value, or null when it is longer than {@link SOCKET_OPEN_MAX} */
|
|
31
|
+
export declare function encodeOpen(init: SocketOpen): string | null;
|
|
32
|
+
/** reads {@link encodeOpen}; undefined for anything that is not a well-formed opening request */
|
|
33
|
+
export declare function decodeOpen(header: string | null): SocketOpen | undefined;
|
|
34
|
+
/**
|
|
35
|
+
* The socket half of a Durable Object hub. Nothing here holds a timer, so an idle object can
|
|
36
|
+
* hibernate: a socket's partition is its tag, its lease and expiry are its attachment, and a ping
|
|
37
|
+
* is answered with a `lease` frame by the runtime's auto-response, which does not wake the object.
|
|
38
|
+
* `maxAge` is the one thing that needs the object awake, so it runs from a single alarm set to the
|
|
39
|
+
* earliest expiry. Build it again after a wake and call `restore`.
|
|
40
|
+
*/
|
|
41
|
+
export declare function hibernatingSockets(host: SocketHost, now?: () => number): {
|
|
42
|
+
/** registers the ping auto-response again from a socket that survived a hibernation */
|
|
43
|
+
restore(): void;
|
|
44
|
+
/** accepts a socket and writes the frames SSE writes at open; returns the end for the client */
|
|
45
|
+
open(init: SocketOpen): Promise<LiveSocket>;
|
|
46
|
+
/** the same answer the auto-response gives, for a runtime that does not give it */
|
|
47
|
+
message(ws: LiveSocket, data: string | ArrayBuffer): void;
|
|
48
|
+
/** sends a delta to every open socket */
|
|
49
|
+
publish(delta: LiveDelta): void;
|
|
50
|
+
/** sends `revoked` to every socket of `partition` and closes it */
|
|
51
|
+
revoke(partition: string): void;
|
|
52
|
+
/** closes the sockets past their maximum age and sets the alarm for the next expiry */
|
|
53
|
+
alarm(): Promise<void>;
|
|
54
|
+
};
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { LIVE_PING } from '../protocol/config.js';
|
|
2
|
+
import { frameText } from './live.js';
|
|
3
|
+
/** the request header that carries {@link SocketOpen} from the Worker to the object, since a GET upgrade has no body */
|
|
4
|
+
export const SOCKET_OPEN_HEADER = 'x-spool-open';
|
|
5
|
+
/** the encoded opening header is at most this long, a bound chosen here and not read from the platform */
|
|
6
|
+
export const SOCKET_OPEN_MAX = 8192;
|
|
7
|
+
const tagOf = (partition) => (partition === null ? 'public' : `p:${partition}`);
|
|
8
|
+
const leaseFrame = (leaseMs) => frameText({ event: 'lease', data: { leaseMs } });
|
|
9
|
+
/** the opening request as a header value, or null when it is longer than {@link SOCKET_OPEN_MAX} */
|
|
10
|
+
export function encodeOpen(init) {
|
|
11
|
+
const { partition, first, leaseMs, maxAgeMs } = init;
|
|
12
|
+
const bytes = new TextEncoder().encode(JSON.stringify({ partition, first, leaseMs, maxAgeMs }));
|
|
13
|
+
let binary = '';
|
|
14
|
+
for (const byte of bytes)
|
|
15
|
+
binary += String.fromCharCode(byte);
|
|
16
|
+
const header = btoa(binary);
|
|
17
|
+
return header.length > SOCKET_OPEN_MAX ? null : header;
|
|
18
|
+
}
|
|
19
|
+
/** reads {@link encodeOpen}; undefined for anything that is not a well-formed opening request */
|
|
20
|
+
export function decodeOpen(header) {
|
|
21
|
+
if (!header)
|
|
22
|
+
return undefined;
|
|
23
|
+
try {
|
|
24
|
+
const binary = atob(header);
|
|
25
|
+
const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
|
|
26
|
+
const v = JSON.parse(new TextDecoder().decode(bytes));
|
|
27
|
+
const frames = v['first'];
|
|
28
|
+
const frame = (f) => typeof f === 'object' &&
|
|
29
|
+
f !== null &&
|
|
30
|
+
typeof f.event === 'string' &&
|
|
31
|
+
'data' in f;
|
|
32
|
+
if ((v['partition'] !== null && typeof v['partition'] !== 'string') ||
|
|
33
|
+
!Array.isArray(frames) ||
|
|
34
|
+
!frames.every(frame) ||
|
|
35
|
+
typeof v['leaseMs'] !== 'number' ||
|
|
36
|
+
!(v['leaseMs'] > 0) ||
|
|
37
|
+
typeof v['maxAgeMs'] !== 'number' ||
|
|
38
|
+
!(v['maxAgeMs'] >= 0)) {
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
return {
|
|
42
|
+
partition: v['partition'],
|
|
43
|
+
first: frames,
|
|
44
|
+
leaseMs: v['leaseMs'],
|
|
45
|
+
maxAgeMs: v['maxAgeMs']
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
catch {
|
|
49
|
+
return undefined;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The socket half of a Durable Object hub. Nothing here holds a timer, so an idle object can
|
|
54
|
+
* hibernate: a socket's partition is its tag, its lease and expiry are its attachment, and a ping
|
|
55
|
+
* is answered with a `lease` frame by the runtime's auto-response, which does not wake the object.
|
|
56
|
+
* `maxAge` is the one thing that needs the object awake, so it runs from a single alarm set to the
|
|
57
|
+
* earliest expiry. Build it again after a wake and call `restore`.
|
|
58
|
+
*/
|
|
59
|
+
export function hibernatingSockets(host, now = Date.now) {
|
|
60
|
+
const attachment = (ws) => ws.deserializeAttachment();
|
|
61
|
+
const quiet = (fn) => {
|
|
62
|
+
try {
|
|
63
|
+
fn();
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
// a socket that closed since it was listed
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
return {
|
|
70
|
+
/** registers the ping auto-response again from a socket that survived a hibernation */
|
|
71
|
+
restore() {
|
|
72
|
+
const first = host.sockets()[0];
|
|
73
|
+
const kept = first ? attachment(first) : null;
|
|
74
|
+
if (kept)
|
|
75
|
+
host.autoResponse(LIVE_PING, leaseFrame(kept.leaseMs));
|
|
76
|
+
},
|
|
77
|
+
/** accepts a socket and writes the frames SSE writes at open; returns the end for the client */
|
|
78
|
+
async open(init) {
|
|
79
|
+
const [client, server] = host.pair();
|
|
80
|
+
host.accept(server, [tagOf(init.partition)]);
|
|
81
|
+
const expires = init.maxAgeMs > 0 ? now() + init.maxAgeMs : 0;
|
|
82
|
+
server.serializeAttachment({ leaseMs: init.leaseMs, expires });
|
|
83
|
+
host.autoResponse(LIVE_PING, leaseFrame(init.leaseMs));
|
|
84
|
+
for (const frame of init.first)
|
|
85
|
+
server.send(frameText(frame));
|
|
86
|
+
server.send(leaseFrame(init.leaseMs));
|
|
87
|
+
if (expires > 0) {
|
|
88
|
+
const set = await host.alarm.get();
|
|
89
|
+
if (set === null || set > expires)
|
|
90
|
+
await host.alarm.set(expires);
|
|
91
|
+
}
|
|
92
|
+
return client;
|
|
93
|
+
},
|
|
94
|
+
/** the same answer the auto-response gives, for a runtime that does not give it */
|
|
95
|
+
message(ws, data) {
|
|
96
|
+
const kept = attachment(ws);
|
|
97
|
+
if (data === LIVE_PING && kept)
|
|
98
|
+
quiet(() => ws.send(leaseFrame(kept.leaseMs)));
|
|
99
|
+
},
|
|
100
|
+
/** sends a delta to every open socket */
|
|
101
|
+
publish(delta) {
|
|
102
|
+
const text = frameText({ event: 'delta', data: delta });
|
|
103
|
+
for (const ws of host.sockets())
|
|
104
|
+
quiet(() => ws.send(text));
|
|
105
|
+
},
|
|
106
|
+
/** sends `revoked` to every socket of `partition` and closes it */
|
|
107
|
+
revoke(partition) {
|
|
108
|
+
const text = frameText({ event: 'revoked', data: {} });
|
|
109
|
+
for (const ws of host.sockets(tagOf(partition))) {
|
|
110
|
+
quiet(() => ws.send(text));
|
|
111
|
+
quiet(() => ws.close(1000, 'revoked'));
|
|
112
|
+
}
|
|
113
|
+
},
|
|
114
|
+
/** closes the sockets past their maximum age and sets the alarm for the next expiry */
|
|
115
|
+
async alarm() {
|
|
116
|
+
const at = now();
|
|
117
|
+
let next = 0;
|
|
118
|
+
for (const ws of host.sockets()) {
|
|
119
|
+
const expires = attachment(ws)?.expires ?? 0;
|
|
120
|
+
if (expires === 0)
|
|
121
|
+
continue;
|
|
122
|
+
if (expires <= at)
|
|
123
|
+
quiet(() => ws.close(1000, 'max age'));
|
|
124
|
+
else
|
|
125
|
+
next = next === 0 ? expires : Math.min(next, expires);
|
|
126
|
+
}
|
|
127
|
+
if (next > 0)
|
|
128
|
+
await host.alarm.set(next);
|
|
129
|
+
}
|
|
130
|
+
};
|
|
131
|
+
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import type { LiveDelta, LiveEventName, LiveEvents } from '../protocol/envelope.js';
|
|
2
|
+
import type { VersionStore } from '../stores/version-store.js';
|
|
3
|
+
/** what a hub needs to open one stream; everything but `signal` and `valid` crosses a Durable Object as JSON */
|
|
4
|
+
export type LiveOpen = {
|
|
5
|
+
/** the principal partition id the page holds; null for a public stream */
|
|
6
|
+
partition: string | null;
|
|
7
|
+
/** events written first, in order: `hello` and the catch-up `delta` */
|
|
8
|
+
first: LiveFrame[];
|
|
9
|
+
/** how long each `lease` event grants, in milliseconds; a lease follows `first` and then every half of it */
|
|
10
|
+
leaseMs: number;
|
|
11
|
+
/** milliseconds between keepalive comments */
|
|
12
|
+
keepaliveMs: number;
|
|
13
|
+
/** the stream closes after this long, so the next connect resolves the identity again; 0 never */
|
|
14
|
+
maxAgeMs: number;
|
|
15
|
+
/** the request's abort signal; a stream closes when it aborts */
|
|
16
|
+
signal?: AbortSignal;
|
|
17
|
+
/**
|
|
18
|
+
* Called at each lease tick of a partition stream; false ends the session at once with `revoked`.
|
|
19
|
+
* A hub that runs in another isolate cannot take a function, so it ignores this and relies on
|
|
20
|
+
* {@link LiveHub.revoke} and `maxAgeMs`.
|
|
21
|
+
*/
|
|
22
|
+
valid?: () => boolean | Promise<boolean>;
|
|
23
|
+
/**
|
|
24
|
+
* true when the request is a WebSocket upgrade. A hub with `sockets` answers it with a socket;
|
|
25
|
+
* any other hub ignores it and answers the stream, which makes the page fall back to SSE.
|
|
26
|
+
*/
|
|
27
|
+
socket?: boolean;
|
|
28
|
+
};
|
|
29
|
+
/** one event as it goes on the wire */
|
|
30
|
+
export type LiveFrame = {
|
|
31
|
+
[N in LiveEventName]: {
|
|
32
|
+
event: N;
|
|
33
|
+
data: LiveEvents[N];
|
|
34
|
+
};
|
|
35
|
+
}[LiveEventName];
|
|
36
|
+
/**
|
|
37
|
+
* Where open streams live. `open` answers a stream `Response`; `publish` sends a delta to every open
|
|
38
|
+
* stream; `revoke` sends `revoked` to every stream of a partition and closes it. The in-process
|
|
39
|
+
* {@link memoryHub} fits a host that is one long-lived process. A Worker needs a hub every isolate
|
|
40
|
+
* can reach, which is the Durable Object hub in `@drupflare/spool/stores/durable-object`.
|
|
41
|
+
* `sockets` is true for a hub that also answers a WebSocket upgrade at the same path; the site's
|
|
42
|
+
* config then tells pages to try a socket first.
|
|
43
|
+
*/
|
|
44
|
+
export interface LiveHub {
|
|
45
|
+
readonly sockets?: boolean;
|
|
46
|
+
open(init: LiveOpen): Response | Promise<Response>;
|
|
47
|
+
publish(delta: LiveDelta): void | Promise<void>;
|
|
48
|
+
revoke(partition: string): void | Promise<void>;
|
|
49
|
+
}
|
|
50
|
+
/** what an in-process hub counts, for a test and for the cost figures */
|
|
51
|
+
export type LiveStats = {
|
|
52
|
+
/** streams open now */
|
|
53
|
+
open: number;
|
|
54
|
+
opened: number;
|
|
55
|
+
closed: number;
|
|
56
|
+
/** bytes of `:k` comments written */
|
|
57
|
+
keepaliveBytes: number;
|
|
58
|
+
/** bytes of events written */
|
|
59
|
+
eventBytes: number;
|
|
60
|
+
/** `lease` events written */
|
|
61
|
+
leases: number;
|
|
62
|
+
};
|
|
63
|
+
/** an in-process hub that also reports its counts */
|
|
64
|
+
export type MemoryHub = LiveHub & {
|
|
65
|
+
stats(): LiveStats;
|
|
66
|
+
};
|
|
67
|
+
/** the SSE text of one event */
|
|
68
|
+
export declare function frameText(frame: LiveFrame): string;
|
|
69
|
+
/**
|
|
70
|
+
* @internal a test seam: `beforeWrite` runs before each write to a connection, `writes` counting
|
|
71
|
+
* from 1, and a throw there detaches the connection like a failed socket write
|
|
72
|
+
*/
|
|
73
|
+
export type MemoryHubOptions = {
|
|
74
|
+
beforeWrite?(info: {
|
|
75
|
+
partition: string | null;
|
|
76
|
+
writes: number;
|
|
77
|
+
}): void;
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* A hub that holds its streams in this process. A keepalive comment goes to each connection every
|
|
81
|
+
* `keepaliveMs`; a connection whose write throws, whose client cancels or whose request aborts is
|
|
82
|
+
* detached.
|
|
83
|
+
*/
|
|
84
|
+
export declare function memoryHub(options?: MemoryHubOptions): MemoryHub;
|
|
85
|
+
/** the response headers of a stream: no cache keeps it and a proxy in front of it passes bytes through */
|
|
86
|
+
export declare const LIVE_HEADERS: {
|
|
87
|
+
readonly 'content-type': "text/event-stream; charset=utf-8";
|
|
88
|
+
readonly 'cache-control': "no-store";
|
|
89
|
+
readonly 'x-accel-buffering': "no";
|
|
90
|
+
};
|
|
91
|
+
/** the `hello` and catch-up `delta` frames for a page that holds `have`, read from `store` */
|
|
92
|
+
export declare function openingFrames(store: VersionStore, have: number | null): Promise<LiveFrame[]>;
|
|
93
|
+
/**
|
|
94
|
+
* Wraps `store` so every bump also publishes its delta. The delta of one bump is exactly the tags it
|
|
95
|
+
* changed, from the cursor before it to the one it returned; a page that finds a gap between its
|
|
96
|
+
* cursor and a delta's `from` stops trusting the stream and asks again.
|
|
97
|
+
*/
|
|
98
|
+
export declare function publishing(store: VersionStore, hub: LiveHub): VersionStore;
|
|
99
|
+
/**
|
|
100
|
+
* The `live` option of `createSpool`. `hub` is where streams live; omitted, an in-process hub, which
|
|
101
|
+
* only suits one long-lived process. `public` also pushes tag changes to pages that hold no
|
|
102
|
+
* principal partition. Seconds: `lease` is what each lease event grants (default 120), `keepalive`
|
|
103
|
+
* the gap between comments (default 25) and `maxAge` how long one stream lives before the page
|
|
104
|
+
* connects again and the identity is resolved again (default 3600; 0 never).
|
|
105
|
+
*
|
|
106
|
+
* `mode` decides when a page opens its stream. `adaptive`, the default, makes the first lease
|
|
107
|
+
* renewal of a visible session an ordinary request and replaces the second with the stream, so a
|
|
108
|
+
* visitor who loads documents, each a short page lifetime, never opens one and pays what it pays
|
|
109
|
+
* without the option. `always` opens at login and whenever a tab becomes visible, for an app that
|
|
110
|
+
* stays open. `live: 'always'` is the same as `{ mode: 'always' }`.
|
|
111
|
+
*
|
|
112
|
+
* A hub with `sockets`, such as `durableObjectHub(ns, { hibernate: true })`, also answers a WebSocket
|
|
113
|
+
* upgrade at the same path, and pages open a socket first. `keepalive` and `maxAge` still apply to
|
|
114
|
+
* SSE streams; a socket has no keepalive comment, since its ping is the page's, and ends at `maxAge`.
|
|
115
|
+
*/
|
|
116
|
+
export type LiveOptions = {
|
|
117
|
+
hub?: LiveHub;
|
|
118
|
+
mode?: 'adaptive' | 'always';
|
|
119
|
+
public?: boolean;
|
|
120
|
+
lease?: number;
|
|
121
|
+
keepalive?: number;
|
|
122
|
+
maxAge?: number;
|
|
123
|
+
};
|
|
124
|
+
/** what `createSpool` runs with, once the option and the runtime are read */
|
|
125
|
+
export type LiveSettings = {
|
|
126
|
+
hub: LiveHub;
|
|
127
|
+
mode: 'adaptive' | 'always';
|
|
128
|
+
public: boolean;
|
|
129
|
+
leaseMs: number;
|
|
130
|
+
keepaliveMs: number;
|
|
131
|
+
maxAgeMs: number;
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* Reads `live`. `false` is off. `true` and an object are on, with an in-process hub unless one is
|
|
135
|
+
* given. Absent, it is on for a site with an `identity` option on a host that is one process, and
|
|
136
|
+
* off on Workers, where an in-process hub only reaches its own isolate.
|
|
137
|
+
*/
|
|
138
|
+
export declare function liveSettings(options: {
|
|
139
|
+
live?: boolean | 'always' | LiveOptions;
|
|
140
|
+
identity?: unknown;
|
|
141
|
+
}): LiveSettings | undefined;
|
|
142
|
+
/** the `have` and `partition` query values of a live request */
|
|
143
|
+
export declare function parseLiveQuery(url: URL): {
|
|
144
|
+
have: number | null;
|
|
145
|
+
partition: string | null;
|
|
146
|
+
};
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
import { PROTOCOL_VERSION } from '../protocol/artifact.js';
|
|
2
|
+
import { ProtocolError } from '../protocol/errors.js';
|
|
3
|
+
import { toSyncResponse } from '../protocol/sync.js';
|
|
4
|
+
const encoder = new TextEncoder();
|
|
5
|
+
const KEEPALIVE = encoder.encode(':k\n\n');
|
|
6
|
+
/** unread frames after which a stream is taken for dead and closed */
|
|
7
|
+
const STALLED = 8;
|
|
8
|
+
/** the SSE text of one event */
|
|
9
|
+
export function frameText(frame) {
|
|
10
|
+
return `event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`;
|
|
11
|
+
}
|
|
12
|
+
/** unref a timer where the runtime has the call, so an idle stream never holds a process open */
|
|
13
|
+
function quiet(timer) {
|
|
14
|
+
timer.unref?.();
|
|
15
|
+
return timer;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* A hub that holds its streams in this process. A keepalive comment goes to each connection every
|
|
19
|
+
* `keepaliveMs`; a connection whose write throws, whose client cancels or whose request aborts is
|
|
20
|
+
* detached.
|
|
21
|
+
*/
|
|
22
|
+
export function memoryHub(options = {}) {
|
|
23
|
+
const conns = new Set();
|
|
24
|
+
const stats = {
|
|
25
|
+
open: 0,
|
|
26
|
+
opened: 0,
|
|
27
|
+
closed: 0,
|
|
28
|
+
keepaliveBytes: 0,
|
|
29
|
+
eventBytes: 0,
|
|
30
|
+
leases: 0
|
|
31
|
+
};
|
|
32
|
+
return {
|
|
33
|
+
stats: () => ({ ...stats, open: conns.size }),
|
|
34
|
+
open(init) {
|
|
35
|
+
let conn;
|
|
36
|
+
let done = false;
|
|
37
|
+
const timers = [];
|
|
38
|
+
const finish = () => {
|
|
39
|
+
if (done)
|
|
40
|
+
return;
|
|
41
|
+
done = true;
|
|
42
|
+
for (const timer of timers)
|
|
43
|
+
clearInterval(timer);
|
|
44
|
+
if (conn)
|
|
45
|
+
conns.delete(conn);
|
|
46
|
+
stats.closed += 1;
|
|
47
|
+
};
|
|
48
|
+
const stream = new ReadableStream({
|
|
49
|
+
start(controller) {
|
|
50
|
+
let writes = 0;
|
|
51
|
+
const write = (bytes) => {
|
|
52
|
+
if (done)
|
|
53
|
+
return;
|
|
54
|
+
// a client that is gone but not reported (seen under `wrangler dev`) stops reading
|
|
55
|
+
if ((controller.desiredSize ?? 1) <= -STALLED)
|
|
56
|
+
return conn?.end();
|
|
57
|
+
try {
|
|
58
|
+
options.beforeWrite?.({
|
|
59
|
+
partition: init.partition,
|
|
60
|
+
writes: (writes += 1)
|
|
61
|
+
});
|
|
62
|
+
controller.enqueue(bytes);
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
finish();
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
const self = {
|
|
69
|
+
partition: init.partition,
|
|
70
|
+
send(frame) {
|
|
71
|
+
const bytes = encoder.encode(frameText(frame));
|
|
72
|
+
stats.eventBytes += bytes.byteLength;
|
|
73
|
+
if (frame.event === 'lease')
|
|
74
|
+
stats.leases += 1;
|
|
75
|
+
write(bytes);
|
|
76
|
+
},
|
|
77
|
+
end() {
|
|
78
|
+
finish();
|
|
79
|
+
try {
|
|
80
|
+
controller.close();
|
|
81
|
+
}
|
|
82
|
+
catch {
|
|
83
|
+
// already closed by the client
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
conn = self;
|
|
88
|
+
conns.add(self);
|
|
89
|
+
stats.opened += 1;
|
|
90
|
+
for (const frame of init.first)
|
|
91
|
+
self.send(frame);
|
|
92
|
+
const lease = async () => {
|
|
93
|
+
if (init.partition !== null && init.valid) {
|
|
94
|
+
let live = false;
|
|
95
|
+
try {
|
|
96
|
+
live = await init.valid();
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
live = false;
|
|
100
|
+
}
|
|
101
|
+
if (!live) {
|
|
102
|
+
self.send({ event: 'revoked', data: {} });
|
|
103
|
+
return self.end();
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
self.send({ event: 'lease', data: { leaseMs: init.leaseMs } });
|
|
107
|
+
};
|
|
108
|
+
void lease();
|
|
109
|
+
timers.push(quiet(setInterval(() => void lease(), Math.max(1, init.leaseMs / 2))));
|
|
110
|
+
timers.push(quiet(setInterval(() => {
|
|
111
|
+
stats.keepaliveBytes += KEEPALIVE.byteLength;
|
|
112
|
+
write(KEEPALIVE);
|
|
113
|
+
}, init.keepaliveMs)));
|
|
114
|
+
if (init.maxAgeMs > 0) {
|
|
115
|
+
const limit = quiet(setTimeout(() => self.end(), init.maxAgeMs));
|
|
116
|
+
timers.push(limit);
|
|
117
|
+
}
|
|
118
|
+
init.signal?.addEventListener('abort', () => self.end(), { once: true });
|
|
119
|
+
},
|
|
120
|
+
cancel: finish
|
|
121
|
+
});
|
|
122
|
+
return new Response(stream, { headers: LIVE_HEADERS });
|
|
123
|
+
},
|
|
124
|
+
publish(delta) {
|
|
125
|
+
for (const conn of conns)
|
|
126
|
+
conn.send({ event: 'delta', data: delta });
|
|
127
|
+
},
|
|
128
|
+
revoke(partition) {
|
|
129
|
+
for (const conn of [...conns]) {
|
|
130
|
+
if (conn.partition !== partition)
|
|
131
|
+
continue;
|
|
132
|
+
conn.send({ event: 'revoked', data: {} });
|
|
133
|
+
conn.end();
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
/** the response headers of a stream: no cache keeps it and a proxy in front of it passes bytes through */
|
|
139
|
+
export const LIVE_HEADERS = {
|
|
140
|
+
'content-type': 'text/event-stream; charset=utf-8',
|
|
141
|
+
'cache-control': 'no-store',
|
|
142
|
+
'x-accel-buffering': 'no'
|
|
143
|
+
};
|
|
144
|
+
/** the `hello` and catch-up `delta` frames for a page that holds `have`, read from `store` */
|
|
145
|
+
export async function openingFrames(store, have) {
|
|
146
|
+
const diff = await store.diff(have ?? (await store.cursor()));
|
|
147
|
+
const from = have ?? diff.cursor;
|
|
148
|
+
return [
|
|
149
|
+
{ event: 'hello', data: { protocol: PROTOCOL_VERSION, cursor: diff.cursor } },
|
|
150
|
+
{ event: 'delta', data: { ...toSyncResponse(diff), from } }
|
|
151
|
+
];
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Wraps `store` so every bump also publishes its delta. The delta of one bump is exactly the tags it
|
|
155
|
+
* changed, from the cursor before it to the one it returned; a page that finds a gap between its
|
|
156
|
+
* cursor and a delta's `from` stops trusting the stream and asks again.
|
|
157
|
+
*/
|
|
158
|
+
export function publishing(store, hub) {
|
|
159
|
+
return {
|
|
160
|
+
cursor: () => store.cursor(),
|
|
161
|
+
diff: (from) => store.diff(from),
|
|
162
|
+
async bump(tags) {
|
|
163
|
+
const cursor = await store.bump(tags);
|
|
164
|
+
const changed = [...new Set(tags)];
|
|
165
|
+
if (changed.length === 0)
|
|
166
|
+
return cursor;
|
|
167
|
+
const delta = {
|
|
168
|
+
...toSyncResponse({
|
|
169
|
+
cursor,
|
|
170
|
+
changed: Object.fromEntries(changed.map((tag) => [tag, cursor])),
|
|
171
|
+
reset: false
|
|
172
|
+
}),
|
|
173
|
+
from: cursor - 1
|
|
174
|
+
};
|
|
175
|
+
try {
|
|
176
|
+
await hub.publish(delta);
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
// a stream that missed this delta sees the gap in the next one
|
|
180
|
+
}
|
|
181
|
+
return cursor;
|
|
182
|
+
}
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
const onWorkers = () => typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers';
|
|
186
|
+
/**
|
|
187
|
+
* Reads `live`. `false` is off. `true` and an object are on, with an in-process hub unless one is
|
|
188
|
+
* given. Absent, it is on for a site with an `identity` option on a host that is one process, and
|
|
189
|
+
* off on Workers, where an in-process hub only reaches its own isolate.
|
|
190
|
+
*/
|
|
191
|
+
export function liveSettings(options) {
|
|
192
|
+
const live = options.live;
|
|
193
|
+
if (live === false)
|
|
194
|
+
return undefined;
|
|
195
|
+
if (live === undefined && (options.identity === undefined || onWorkers()))
|
|
196
|
+
return undefined;
|
|
197
|
+
const given = typeof live === 'object' ? live : live === 'always' ? { mode: 'always' } : {};
|
|
198
|
+
if (given.mode !== undefined && given.mode !== 'adaptive' && given.mode !== 'always') {
|
|
199
|
+
throw new ProtocolError('bad-route', 'live.mode must be adaptive or always');
|
|
200
|
+
}
|
|
201
|
+
const seconds = (name, value, fallback, min) => {
|
|
202
|
+
const v = value ?? fallback;
|
|
203
|
+
if (!(Number.isFinite(v) && v >= min)) {
|
|
204
|
+
throw new ProtocolError('bad-route', `live.${name} must be a number of at least ${min}`);
|
|
205
|
+
}
|
|
206
|
+
return v * 1000;
|
|
207
|
+
};
|
|
208
|
+
return {
|
|
209
|
+
hub: given.hub ?? memoryHub(),
|
|
210
|
+
mode: given.mode ?? 'adaptive',
|
|
211
|
+
public: given.public === true,
|
|
212
|
+
leaseMs: seconds('lease', given.lease, 120, 1),
|
|
213
|
+
keepaliveMs: seconds('keepalive', given.keepalive, 25, 1),
|
|
214
|
+
maxAgeMs: seconds('maxAge', given.maxAge, 3600, 0)
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
/** the `have` and `partition` query values of a live request */
|
|
218
|
+
export function parseLiveQuery(url) {
|
|
219
|
+
const have = url.searchParams.get('have');
|
|
220
|
+
if (have !== null && !/^\d{1,15}$/.test(have)) {
|
|
221
|
+
throw new ProtocolError('bad-sync', 'have must be a non-negative integer');
|
|
222
|
+
}
|
|
223
|
+
const partition = url.searchParams.get('partition');
|
|
224
|
+
if (partition !== null && !/^[A-Za-z0-9_-]{1,128}$/.test(partition)) {
|
|
225
|
+
throw new ProtocolError('bad-sync', 'partition must be a base64url token');
|
|
226
|
+
}
|
|
227
|
+
return { have: have === null ? null : Number(have), partition };
|
|
228
|
+
}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import type { BundleRows } from '../protocol/bundle.js';
|
|
2
|
+
import { type BootstrapGate, type Ring, type WorkerMode } from '../protocol/ring.js';
|
|
3
|
+
import { type Route, type SerializedRoute } from '../protocol/route.js';
|
|
4
|
+
import type { CompiledTemplate } from '../protocol/template/compile.js';
|
|
5
|
+
import type { ResourceWrite } from '../protocol/write.js';
|
|
6
|
+
import type { BundleStore } from './bundle.js';
|
|
7
|
+
/** the ring's byte budget when `createSpool` names none; a default, not measured */
|
|
8
|
+
export declare const RING_BYTES = 24576;
|
|
9
|
+
/** a stored pack as a ring reads it: its digest, its rows by table and its byte length */
|
|
10
|
+
export type RingPack = {
|
|
11
|
+
digest: string;
|
|
12
|
+
tables: Record<string, BundleRows>;
|
|
13
|
+
bytes: number;
|
|
14
|
+
};
|
|
15
|
+
export type RingOptions = {
|
|
16
|
+
/** the pathname of the page the ring is for */
|
|
17
|
+
path: string;
|
|
18
|
+
version: number;
|
|
19
|
+
digest: string;
|
|
20
|
+
/** the declared routes; only the public family and query routes take part */
|
|
21
|
+
routes: readonly Route[];
|
|
22
|
+
tables: Record<string, BundleRows>;
|
|
23
|
+
/** the byte length of the pack the ring falls back to */
|
|
24
|
+
packBytes: number;
|
|
25
|
+
ringBytes: number;
|
|
26
|
+
bootstrap: BootstrapGate;
|
|
27
|
+
worker: WorkerMode;
|
|
28
|
+
/** the boot script path the ring names, when the page loads its runtime through the gate */
|
|
29
|
+
boot?: string;
|
|
30
|
+
/** the worker script's lease in seconds, carried so the page counts views inside one lease */
|
|
31
|
+
lease?: number;
|
|
32
|
+
/**
|
|
33
|
+
* a ring with no rows, routes or templates: the pack location and the boot script only. The
|
|
34
|
+
* boot script carries the pack, the routes and the templates, so none of them rides in every
|
|
35
|
+
* document or is installed twice.
|
|
36
|
+
*/
|
|
37
|
+
slim?: boolean;
|
|
38
|
+
/** the declared resource writes; they count against the budget as the routes do */
|
|
39
|
+
writes?: readonly ResourceWrite[];
|
|
40
|
+
};
|
|
41
|
+
/** the routes and templates a boot script carries, with `id`, a digest of both */
|
|
42
|
+
export type BootShape = {
|
|
43
|
+
id: string;
|
|
44
|
+
routes: SerializedRoute[];
|
|
45
|
+
templates: Record<string, CompiledTemplate>;
|
|
46
|
+
};
|
|
47
|
+
/** the shape of `declared`; its id is 12 hex characters of the SHA-256 of the routes and templates */
|
|
48
|
+
export declare function bootShape(declared: readonly Route[]): Promise<BootShape>;
|
|
49
|
+
/**
|
|
50
|
+
* Builds the ring for one family page: its row and the rows its links reach, breadth first, until
|
|
51
|
+
* the next record would pass `ringBytes`. The entry row, the routes and their templates are always
|
|
52
|
+
* held: they count against the budget but are never dropped. Returns `undefined` for a path no
|
|
53
|
+
* public family route matches, or whose row the pack does not hold. A `slim` ring does not depend
|
|
54
|
+
* on the page: it is the same for every path, and `undefined` only when no public route reads data.
|
|
55
|
+
*/
|
|
56
|
+
export declare function buildRing(options: RingOptions): Ring | undefined;
|
|
57
|
+
/**
|
|
58
|
+
* The paths a click may load the boot script for: the part of each public template family
|
|
59
|
+
* pattern before its first parameter, and `?` plus the path of each list that answers a query
|
|
60
|
+
* string. The page runtime answers only these, so a click anywhere else stays a document load.
|
|
61
|
+
*/
|
|
62
|
+
export declare function gatePaths(routes: readonly Route[]): string[];
|
|
63
|
+
/** the script element that carries the declared writes of a page with no ring; `<` becomes a `\u` escape */
|
|
64
|
+
export declare function writesElement(writes: readonly ResourceWrite[]): string;
|
|
65
|
+
/** the script element that carries `ring`; `<` becomes a `\u` escape, so no row can close it */
|
|
66
|
+
export declare function ringElement(ring: Ring): string;
|
|
67
|
+
/** the held version a request names in its cookie, or undefined */
|
|
68
|
+
export declare function heldVersion(cookie: string | null): number | undefined;
|
|
69
|
+
/** the script element that carries the delta from `from` to `to`; no `text` makes a pointer the client fetches */
|
|
70
|
+
export declare function deltaElement(from: number, to: number, text?: string): string;
|
|
71
|
+
/** `html` with `element` before `</head>`, else before `</body>`, else at the end */
|
|
72
|
+
export declare function placeRing(html: string, element: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* The pack the store holds at a version, read once and kept until the version moves. A version
|
|
75
|
+
* with no stored pack answers `undefined` and is not kept.
|
|
76
|
+
*/
|
|
77
|
+
export declare function ringPacks(bundles: BundleStore): (version: number) => Promise<RingPack | undefined>;
|