@drupflare/spool 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +1749 -2
- package/dist/cdn/client.js +1 -0
- package/dist/cdn/location.d.ts +11 -0
- package/dist/cdn/location.js +15 -0
- package/dist/cdn/manifest.json +16 -0
- package/dist/cdn/spool-sw.js +1 -0
- package/dist/client/entry.d.ts +1 -0
- package/dist/client/entry.js +25 -0
- package/dist/client/index.d.ts +3 -0
- package/dist/client/index.js +2 -0
- package/dist/client/lifecycle.d.ts +10 -0
- package/dist/client/lifecycle.js +10 -0
- package/dist/client/loads.d.ts +16 -0
- package/dist/client/loads.js +41 -0
- package/dist/client/register.d.ts +34 -0
- package/dist/client/register.js +58 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/media/embeds.d.ts +59 -0
- package/dist/media/embeds.js +120 -0
- package/dist/media/headers.d.ts +13 -0
- package/dist/media/headers.js +44 -0
- package/dist/media/html.d.ts +27 -0
- package/dist/media/html.js +93 -0
- package/dist/media/image.d.ts +222 -0
- package/dist/media/image.js +413 -0
- package/dist/media/index.d.ts +6 -0
- package/dist/media/index.js +6 -0
- package/dist/media/lazy.d.ts +26 -0
- package/dist/media/lazy.js +74 -0
- package/dist/media/responsive.d.ts +45 -0
- package/dist/media/responsive.js +98 -0
- package/dist/media/video.d.ts +30 -0
- package/dist/media/video.js +75 -0
- package/dist/node/listener.d.ts +19 -0
- package/dist/node/listener.js +76 -0
- package/dist/protocol/artifact.d.ts +54 -0
- package/dist/protocol/artifact.js +79 -0
- package/dist/protocol/assembly.d.ts +34 -0
- package/dist/protocol/assembly.js +72 -0
- package/dist/protocol/beacon.d.ts +59 -0
- package/dist/protocol/beacon.js +86 -0
- package/dist/protocol/collector.d.ts +41 -0
- package/dist/protocol/collector.js +84 -0
- package/dist/protocol/config.d.ts +89 -0
- package/dist/protocol/config.js +13 -0
- package/dist/protocol/envelope.d.ts +47 -0
- package/dist/protocol/envelope.js +162 -0
- package/dist/protocol/errors.d.ts +7 -0
- package/dist/protocol/errors.js +9 -0
- package/dist/protocol/graph.d.ts +81 -0
- package/dist/protocol/graph.js +201 -0
- package/dist/protocol/index.d.ts +19 -0
- package/dist/protocol/index.js +19 -0
- package/dist/protocol/manifest.d.ts +29 -0
- package/dist/protocol/manifest.js +94 -0
- package/dist/protocol/normalise.d.ts +20 -0
- package/dist/protocol/normalise.js +29 -0
- package/dist/protocol/pattern.d.ts +12 -0
- package/dist/protocol/pattern.js +82 -0
- package/dist/protocol/provision.d.ts +100 -0
- package/dist/protocol/provision.js +105 -0
- package/dist/protocol/route.d.ts +179 -0
- package/dist/protocol/route.js +135 -0
- package/dist/protocol/sync.d.ts +31 -0
- package/dist/protocol/sync.js +87 -0
- package/dist/protocol/tag.d.ts +12 -0
- package/dist/protocol/tag.js +26 -0
- package/dist/protocol/template/compile.d.ts +35 -0
- package/dist/protocol/template/compile.js +82 -0
- package/dist/protocol/template/interpret.d.ts +9 -0
- package/dist/protocol/template/interpret.js +82 -0
- package/dist/protocol/vector.d.ts +32 -0
- package/dist/protocol/vector.js +56 -0
- package/dist/protocol/view.d.ts +110 -0
- package/dist/protocol/view.js +201 -0
- package/dist/proxy/dictionary.d.ts +58 -0
- package/dist/proxy/dictionary.js +197 -0
- package/dist/proxy/eligible.d.ts +45 -0
- package/dist/proxy/eligible.js +96 -0
- package/dist/proxy/index.d.ts +5 -0
- package/dist/proxy/index.js +5 -0
- package/dist/proxy/proxy.d.ts +133 -0
- package/dist/proxy/proxy.js +507 -0
- package/dist/proxy/purge.d.ts +10 -0
- package/dist/proxy/purge.js +66 -0
- package/dist/proxy/tags.d.ts +8 -0
- package/dist/proxy/tags.js +36 -0
- package/dist/report/derive.d.ts +223 -0
- package/dist/report/derive.js +494 -0
- package/dist/report/economics.d.ts +14 -0
- package/dist/report/economics.js +24 -0
- package/dist/report/index.d.ts +9 -0
- package/dist/report/index.js +9 -0
- package/dist/report/inputs.d.ts +141 -0
- package/dist/report/inputs.js +216 -0
- package/dist/report/ledger.d.ts +169 -0
- package/dist/report/ledger.js +278 -0
- package/dist/report/measurement.d.ts +48 -0
- package/dist/report/measurement.js +117 -0
- package/dist/report/model.d.ts +42 -0
- package/dist/report/model.js +74 -0
- package/dist/report/thirdparty.d.ts +62 -0
- package/dist/report/thirdparty.js +107 -0
- package/dist/report/traffic.d.ts +140 -0
- package/dist/report/traffic.js +228 -0
- package/dist/report/trim.d.ts +81 -0
- package/dist/report/trim.js +105 -0
- package/dist/server/beacon.d.ts +20 -0
- package/dist/server/beacon.js +47 -0
- package/dist/server/embedded.d.ts +6 -0
- package/dist/server/embedded.js +6 -0
- package/dist/server/ga4.d.ts +70 -0
- package/dist/server/ga4.js +165 -0
- package/dist/server/identity.d.ts +12 -0
- package/dist/server/identity.js +17 -0
- package/dist/server/index.d.ts +7 -0
- package/dist/server/index.js +7 -0
- package/dist/server/sink.d.ts +56 -0
- package/dist/server/sink.js +133 -0
- package/dist/server/size.d.ts +7 -0
- package/dist/server/size.js +18 -0
- package/dist/server/spool.d.ts +97 -0
- package/dist/server/spool.js +463 -0
- package/dist/server/stub.d.ts +9 -0
- package/dist/server/stub.js +19 -0
- package/dist/server/sync.d.ts +12 -0
- package/dist/server/sync.js +48 -0
- package/dist/server/work.d.ts +22 -0
- package/dist/server/work.js +30 -0
- package/dist/stores/durable-object.d.ts +19 -0
- package/dist/stores/durable-object.js +53 -0
- package/dist/stores/index.d.ts +2 -0
- package/dist/stores/index.js +2 -0
- package/dist/stores/memory.d.ts +4 -0
- package/dist/stores/memory.js +10 -0
- package/dist/stores/version-store.d.ts +11 -0
- package/dist/stores/version-store.js +1 -0
- package/dist/sw/analytics.d.ts +81 -0
- package/dist/sw/analytics.js +275 -0
- package/dist/sw/collect.d.ts +8 -0
- package/dist/sw/collect.js +33 -0
- package/dist/sw/core.d.ts +1 -0
- package/dist/sw/core.js +3 -0
- package/dist/sw/freshness.d.ts +15 -0
- package/dist/sw/freshness.js +20 -0
- package/dist/sw/graph/index.d.ts +67 -0
- package/dist/sw/graph/index.js +170 -0
- package/dist/sw/graph/invalidate.d.ts +23 -0
- package/dist/sw/graph/invalidate.js +109 -0
- package/dist/sw/graph/projections.d.ts +7 -0
- package/dist/sw/graph/projections.js +9 -0
- package/dist/sw/graph/records.d.ts +7 -0
- package/dist/sw/graph/records.js +9 -0
- package/dist/sw/graph/store.d.ts +32 -0
- package/dist/sw/graph/store.js +52 -0
- package/dist/sw/idb.d.ts +8 -0
- package/dist/sw/idb.js +117 -0
- package/dist/sw/index.d.ts +2 -0
- package/dist/sw/index.js +1 -0
- package/dist/sw/partition.d.ts +21 -0
- package/dist/sw/partition.js +137 -0
- package/dist/sw/policy.d.ts +8 -0
- package/dist/sw/policy.js +24 -0
- package/dist/sw/provision.d.ts +39 -0
- package/dist/sw/provision.js +61 -0
- package/dist/sw/render.d.ts +21 -0
- package/dist/sw/render.js +53 -0
- package/dist/sw/replica.d.ts +77 -0
- package/dist/sw/replica.js +299 -0
- package/dist/sw/router.d.ts +42 -0
- package/dist/sw/router.js +48 -0
- package/dist/sw/routing.d.ts +23 -0
- package/dist/sw/routing.js +48 -0
- package/dist/sw/runtime.d.ts +112 -0
- package/dist/sw/runtime.js +1070 -0
- package/dist/sw/scheduler.d.ts +83 -0
- package/dist/sw/scheduler.js +149 -0
- package/dist/sw/seal.d.ts +37 -0
- package/dist/sw/seal.js +183 -0
- package/dist/sw/serve.d.ts +15 -0
- package/dist/sw/serve.js +63 -0
- package/dist/sw/shadow.d.ts +16 -0
- package/dist/sw/shadow.js +27 -0
- package/dist/sw/static.d.ts +17 -0
- package/dist/sw/static.js +81 -0
- package/dist/sw/storage.d.ts +64 -0
- package/dist/sw/storage.js +34 -0
- package/dist/sw/thirdparty.d.ts +17 -0
- package/dist/sw/thirdparty.js +36 -0
- package/dist/trim/css.d.ts +38 -0
- package/dist/trim/css.js +328 -0
- package/dist/trim/index.d.ts +3 -0
- package/dist/trim/index.js +3 -0
- package/dist/trim/manifest.d.ts +67 -0
- package/dist/trim/manifest.js +134 -0
- package/dist/trim/tokens.d.ts +47 -0
- package/dist/trim/tokens.js +142 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +3 -0
- package/package.json +150 -5
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { ProtocolError } from './errors.js';
|
|
2
|
+
const HOUR = 3_600_000;
|
|
3
|
+
/** GA4 Measurement Protocol: backdating works up to 72 hours, and attribution wants 48 */
|
|
4
|
+
export const GA4_RECOMMENDED_MS = 48 * HOUR;
|
|
5
|
+
/** the longest cap a `ga4` collector may declare */
|
|
6
|
+
export const GA4_HARD_MS = 72 * HOUR;
|
|
7
|
+
/**
|
|
8
|
+
* The GA4 browser collector, forwarded through the server half because the Measurement Protocol
|
|
9
|
+
* needs an API secret the page must not hold. The cap is the 48-hour attribution window.
|
|
10
|
+
*/
|
|
11
|
+
export const GA4_COLLECTOR = {
|
|
12
|
+
vendor: 'ga4',
|
|
13
|
+
match: 'https://www.google-analytics.com/g/collect',
|
|
14
|
+
maxAgeMs: GA4_RECOMMENDED_MS,
|
|
15
|
+
delivery: 'sink'
|
|
16
|
+
};
|
|
17
|
+
function bad(message) {
|
|
18
|
+
throw new ProtocolError('bad-route', message);
|
|
19
|
+
}
|
|
20
|
+
/** validates collectors from a server config; a `ga4` cap past the 72-hour limit is refused */
|
|
21
|
+
export function checkCollectors(collectors) {
|
|
22
|
+
const seen = new Set();
|
|
23
|
+
for (const c of collectors) {
|
|
24
|
+
if (!c.vendor)
|
|
25
|
+
bad('collector needs a vendor');
|
|
26
|
+
if (seen.has(c.vendor))
|
|
27
|
+
bad(`collector ${c.vendor} declared twice`);
|
|
28
|
+
seen.add(c.vendor);
|
|
29
|
+
let url;
|
|
30
|
+
try {
|
|
31
|
+
url = new URL(c.match);
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
return bad(`collector ${c.vendor}: match must be an absolute URL`);
|
|
35
|
+
}
|
|
36
|
+
if (url.protocol !== 'https:' && url.protocol !== 'http:') {
|
|
37
|
+
bad(`collector ${c.vendor}: match must be http or https`);
|
|
38
|
+
}
|
|
39
|
+
if (!Number.isFinite(c.maxAgeMs) || c.maxAgeMs <= 0) {
|
|
40
|
+
bad(`collector ${c.vendor}: maxAgeMs must be a positive number of milliseconds`);
|
|
41
|
+
}
|
|
42
|
+
if (c.vendor === 'ga4' && c.maxAgeMs > GA4_HARD_MS) {
|
|
43
|
+
bad('collector ga4: maxAgeMs is past the 72 hour Measurement Protocol limit');
|
|
44
|
+
}
|
|
45
|
+
if (c.delivery !== 'replay' && c.delivery !== 'sink') {
|
|
46
|
+
bad(`collector ${c.vendor}: delivery must be replay or sink`);
|
|
47
|
+
}
|
|
48
|
+
if (c.stamp && !['age-ms', 'epoch-ms', 'epoch-s', 'datetime-utc'].includes(c.stamp.kind)) {
|
|
49
|
+
bad(`collector ${c.vendor}: unknown stamp kind`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
/** the collector whose `match` the URL falls under, or undefined */
|
|
54
|
+
export function matchCollector(collectors, url) {
|
|
55
|
+
if (!collectors || collectors.length === 0)
|
|
56
|
+
return undefined;
|
|
57
|
+
let target;
|
|
58
|
+
try {
|
|
59
|
+
target = new URL(url);
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
return collectors.find((c) => {
|
|
65
|
+
const m = new URL(c.match);
|
|
66
|
+
return target.origin === m.origin && target.pathname.startsWith(m.pathname);
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
function stampValue(kind, at, now) {
|
|
70
|
+
if (kind === 'age-ms')
|
|
71
|
+
return String(Math.max(0, Math.round(now - at)));
|
|
72
|
+
if (kind === 'epoch-ms')
|
|
73
|
+
return String(Math.round(at));
|
|
74
|
+
if (kind === 'epoch-s')
|
|
75
|
+
return String(Math.floor(at / 1000));
|
|
76
|
+
return new Date(at).toISOString().slice(0, 19).replace('T', ' ');
|
|
77
|
+
}
|
|
78
|
+
/** `search` with the stamp parameter set to when the event happened, other parameters kept */
|
|
79
|
+
export function applyStamp(search, stamp, at, now) {
|
|
80
|
+
const params = new URLSearchParams(search);
|
|
81
|
+
params.set(stamp.param, stampValue(stamp.kind, at, now));
|
|
82
|
+
const text = params.toString();
|
|
83
|
+
return text === '' ? '' : `?${text}`;
|
|
84
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import type { PROTOCOL_VERSION } from './artifact.js';
|
|
2
|
+
import type { CollectorConfig } from './collector.js';
|
|
3
|
+
import type { SerializedRoute } from './route.js';
|
|
4
|
+
import type { CompiledTemplate } from './template/compile.js';
|
|
5
|
+
import type { Mode } from './view.js';
|
|
6
|
+
/** every path under this prefix belongs to spool */
|
|
7
|
+
export declare const SPOOL_PREFIX = "/.spool/";
|
|
8
|
+
/** where the server answers sync, artifact and beacon requests, and where the worker script lives */
|
|
9
|
+
export declare const PATHS: {
|
|
10
|
+
readonly sync: "/.spool/sync";
|
|
11
|
+
readonly artifact: "/.spool/artifact";
|
|
12
|
+
readonly beacon: "/.spool/beacon";
|
|
13
|
+
readonly worker: "/spool-sw.js";
|
|
14
|
+
};
|
|
15
|
+
/** the same-origin path of the page runtime script for a given version */
|
|
16
|
+
export declare function clientPath(version: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* Priors and the hot list for provisioning. Every number is a scenario assumption the operator
|
|
19
|
+
* replaces with its own telemetry; `hot` names paths to warm in priority order, riding the next
|
|
20
|
+
* beacon flush.
|
|
21
|
+
*/
|
|
22
|
+
export type ProvisionConfig = {
|
|
23
|
+
reuse?: number;
|
|
24
|
+
futureViews?: number;
|
|
25
|
+
requestBytes?: number;
|
|
26
|
+
artifactBytes?: number;
|
|
27
|
+
avoidedBytes?: number;
|
|
28
|
+
/** rate of change per dependency tag, per day, before the worker has seen any */
|
|
29
|
+
changesPerDay?: number;
|
|
30
|
+
hot?: string[];
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* How the worker treats same-origin subresources. `cache` answers an immutable one from
|
|
34
|
+
* CacheStorage; `passthrough` leaves it to the browser's own cache with no worker involvement;
|
|
35
|
+
* `static-routing` asks the browser (`InstallEvent.addRoutes`) to send only navigations, beacons
|
|
36
|
+
* and routed paths to the worker and everything else to the network, and acts as `passthrough` where
|
|
37
|
+
* the API does not exist.
|
|
38
|
+
*/
|
|
39
|
+
export type AssetMode = 'cache' | 'passthrough' | 'static-routing';
|
|
40
|
+
/**
|
|
41
|
+
* The opt-in worker cache for cross-origin files. Only an origin in `allow` is touched, and only a
|
|
42
|
+
* response the worker can read (a CORS answer) for a URL that looks versioned, or one the origin
|
|
43
|
+
* marks immutable, is kept. Everything else goes to the network untouched.
|
|
44
|
+
*/
|
|
45
|
+
export type ThirdPartyConfig = {
|
|
46
|
+
/** origins whose GET requests the worker may answer from its copy, such as `https://fonts.gstatic.com` */
|
|
47
|
+
allow: string[];
|
|
48
|
+
/** extra patterns, as regular expression sources, that mark a URL as versioned */
|
|
49
|
+
versioned?: string[];
|
|
50
|
+
/** a copy of an unversioned file is checked again at a network moment once it is this old; default one day */
|
|
51
|
+
revalidateAfterMs?: number;
|
|
52
|
+
/** most files held; the oldest go first; default 64 */
|
|
53
|
+
maxEntries?: number;
|
|
54
|
+
/** keep opaque (no-cors) responses, which Chromium counts as about 7 MB each against quota; default false */
|
|
55
|
+
allowOpaque?: boolean;
|
|
56
|
+
};
|
|
57
|
+
/** what the server compiles into the worker script: routes, templates and the tag to inject */
|
|
58
|
+
export type SwConfig = {
|
|
59
|
+
protocol: typeof PROTOCOL_VERSION;
|
|
60
|
+
version: string;
|
|
61
|
+
routes: SerializedRoute[];
|
|
62
|
+
/** compiled templates keyed by route pattern */
|
|
63
|
+
templates: Record<string, CompiledTemplate>;
|
|
64
|
+
/** same-origin POST paths the worker queues and flushes in one request */
|
|
65
|
+
beacons: string[];
|
|
66
|
+
/** the exact script tag the server injects, so a local render matches a network one */
|
|
67
|
+
clientTag: string;
|
|
68
|
+
/** the mode for routes that do not name one; `serve` when absent */
|
|
69
|
+
mode?: Mode;
|
|
70
|
+
/** the share of views, 0 to 1, that run in shadow while the mode is `serve`; 0 when absent */
|
|
71
|
+
shadowSample?: number;
|
|
72
|
+
/** whether the worker queues a `spool.view` per page view; true when absent */
|
|
73
|
+
views?: boolean;
|
|
74
|
+
/** what the worker assumes before telemetry says otherwise, and which pages to warm */
|
|
75
|
+
provision?: ProvisionConfig;
|
|
76
|
+
/**
|
|
77
|
+
* The URL of a `spool.json`. Present, the worker has no spool server: it takes its routes from
|
|
78
|
+
* that file, checks it for changes in place of `/.spool/sync`, and sends no request to `/.spool/*`.
|
|
79
|
+
*/
|
|
80
|
+
manifest?: string;
|
|
81
|
+
/** how same-origin subresources are handled; `cache` when absent */
|
|
82
|
+
assets?: AssetMode;
|
|
83
|
+
/** same-origin paths whose request ends the session: the worker wipes the principal store first */
|
|
84
|
+
logout?: string[];
|
|
85
|
+
/** cross-origin analytics collectors the worker holds and delivers later */
|
|
86
|
+
collectors?: CollectorConfig[];
|
|
87
|
+
/** the opt-in cache for versioned cross-origin files */
|
|
88
|
+
thirdParty?: ThirdPartyConfig;
|
|
89
|
+
};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** every path under this prefix belongs to spool */
|
|
2
|
+
export const SPOOL_PREFIX = '/.spool/';
|
|
3
|
+
/** where the server answers sync, artifact and beacon requests, and where the worker script lives */
|
|
4
|
+
export const PATHS = {
|
|
5
|
+
sync: '/.spool/sync',
|
|
6
|
+
artifact: '/.spool/artifact',
|
|
7
|
+
beacon: '/.spool/beacon',
|
|
8
|
+
worker: '/spool-sw.js'
|
|
9
|
+
};
|
|
10
|
+
/** the same-origin path of the page runtime script for a given version */
|
|
11
|
+
export function clientPath(version) {
|
|
12
|
+
return `${SPOOL_PREFIX}${encodeURIComponent(version)}/client.js`;
|
|
13
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { type Scope } from './artifact.js';
|
|
2
|
+
/** the header names, lowercase as `Headers` reports them */
|
|
3
|
+
export declare const HEADERS: {
|
|
4
|
+
readonly protocol: "spool-protocol";
|
|
5
|
+
readonly artifact: "spool-artifact";
|
|
6
|
+
readonly invalidate: "spool-invalidate";
|
|
7
|
+
readonly clear: "spool-clear";
|
|
8
|
+
readonly vector: "spool-vector";
|
|
9
|
+
readonly partition: "spool-partition";
|
|
10
|
+
readonly vectorSeen: "spool-vector-seen";
|
|
11
|
+
readonly provision: "spool-provision";
|
|
12
|
+
};
|
|
13
|
+
/** `Spool-Clear` token that wipes everything the worker holds */
|
|
14
|
+
export declare const CLEAR_ALL = "*";
|
|
15
|
+
/** what a response says about the artifact it carries */
|
|
16
|
+
export type EnvelopeArtifact = {
|
|
17
|
+
id: string;
|
|
18
|
+
scope: Scope;
|
|
19
|
+
deps: string[];
|
|
20
|
+
/** the vector cursor the artifact reflects */
|
|
21
|
+
version: number;
|
|
22
|
+
};
|
|
23
|
+
/** every spool header of a response, decoded; an absent header is an absent field */
|
|
24
|
+
export type Envelope = {
|
|
25
|
+
protocol?: number;
|
|
26
|
+
artifact?: EnvelopeArtifact;
|
|
27
|
+
/** tag to the vector version at which it last changed */
|
|
28
|
+
invalidate?: Record<string, number>;
|
|
29
|
+
/** partition ids to wipe, or {@link CLEAR_ALL} */
|
|
30
|
+
clear?: string[];
|
|
31
|
+
vector?: number;
|
|
32
|
+
/** echo of the request's `Spool-Vector-Seen`: `invalidate` is the complete diff since this cursor */
|
|
33
|
+
seen?: number;
|
|
34
|
+
partition?: string;
|
|
35
|
+
};
|
|
36
|
+
/** the header map for an envelope; `Spool-Protocol` is always present */
|
|
37
|
+
export declare function encodeEnvelope(envelope: Envelope): Record<string, string>;
|
|
38
|
+
/** sets every header of `envelope` on `headers`, replacing any spool header already there */
|
|
39
|
+
export declare function writeEnvelope(headers: Headers, envelope: Envelope): void;
|
|
40
|
+
/**
|
|
41
|
+
* The envelope of a response as the worker uses it. A malformed spool header drops every field
|
|
42
|
+
* but `Spool-Clear`, which is read on its own so a valid clear still applies and a malformed one
|
|
43
|
+
* reads as a full wipe. A response that names another protocol version is left alone.
|
|
44
|
+
*/
|
|
45
|
+
export declare function decodeEnvelopeOrClear(headers: Headers): Envelope | undefined;
|
|
46
|
+
/** reads the spool headers; throws `ProtocolError` on a malformed one */
|
|
47
|
+
export declare function decodeEnvelope(headers: Headers): Envelope;
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { PROTOCOL_VERSION } from './artifact.js';
|
|
2
|
+
import { ProtocolError } from './errors.js';
|
|
3
|
+
/** the header names, lowercase as `Headers` reports them */
|
|
4
|
+
export const HEADERS = {
|
|
5
|
+
protocol: 'spool-protocol',
|
|
6
|
+
artifact: 'spool-artifact',
|
|
7
|
+
invalidate: 'spool-invalidate',
|
|
8
|
+
clear: 'spool-clear',
|
|
9
|
+
vector: 'spool-vector',
|
|
10
|
+
partition: 'spool-partition',
|
|
11
|
+
vectorSeen: 'spool-vector-seen',
|
|
12
|
+
provision: 'spool-provision'
|
|
13
|
+
};
|
|
14
|
+
/** `Spool-Clear` token that wipes everything the worker holds */
|
|
15
|
+
export const CLEAR_ALL = '*';
|
|
16
|
+
const PARTITION = /^[A-Za-z0-9_-]{1,128}$/;
|
|
17
|
+
function bad(message) {
|
|
18
|
+
throw new ProtocolError('bad-header', message);
|
|
19
|
+
}
|
|
20
|
+
function integer(text, field) {
|
|
21
|
+
if (!/^\d{1,15}$/.test(text.trim()))
|
|
22
|
+
return bad(`${field} must be a non-negative integer`);
|
|
23
|
+
return Number(text);
|
|
24
|
+
}
|
|
25
|
+
function decode(text, field) {
|
|
26
|
+
try {
|
|
27
|
+
return decodeURIComponent(text);
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return bad(`${field} has a bad escape`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
function list(text) {
|
|
34
|
+
return text
|
|
35
|
+
.split(',')
|
|
36
|
+
.map((part) => part.trim())
|
|
37
|
+
.filter((part) => part !== '');
|
|
38
|
+
}
|
|
39
|
+
/** the header map for an envelope; `Spool-Protocol` is always present */
|
|
40
|
+
export function encodeEnvelope(envelope) {
|
|
41
|
+
const out = {
|
|
42
|
+
[HEADERS.protocol]: String(envelope.protocol ?? PROTOCOL_VERSION)
|
|
43
|
+
};
|
|
44
|
+
const { artifact, invalidate, clear, vector, seen, partition } = envelope;
|
|
45
|
+
if (artifact) {
|
|
46
|
+
out[HEADERS.artifact] = [
|
|
47
|
+
`id=${encodeURIComponent(artifact.id)}`,
|
|
48
|
+
`scope=${artifact.scope}`,
|
|
49
|
+
`deps=${artifact.deps.map(encodeURIComponent).join(',')}`,
|
|
50
|
+
`v=${artifact.version}`
|
|
51
|
+
].join('; ');
|
|
52
|
+
}
|
|
53
|
+
const changed = Object.entries(invalidate ?? {});
|
|
54
|
+
if (changed.length > 0) {
|
|
55
|
+
out[HEADERS.invalidate] = changed
|
|
56
|
+
.map(([t, v]) => `${encodeURIComponent(t)}=${v}`)
|
|
57
|
+
.join(', ');
|
|
58
|
+
}
|
|
59
|
+
if (clear && clear.length > 0)
|
|
60
|
+
out[HEADERS.clear] = clear.map(encodeURIComponent).join(', ');
|
|
61
|
+
if (vector !== undefined)
|
|
62
|
+
out[HEADERS.vector] = String(vector);
|
|
63
|
+
if (seen !== undefined)
|
|
64
|
+
out[HEADERS.vectorSeen] = String(seen);
|
|
65
|
+
if (partition !== undefined) {
|
|
66
|
+
if (!PARTITION.test(partition))
|
|
67
|
+
return bad('partition must be a base64url token');
|
|
68
|
+
out[HEADERS.partition] = partition;
|
|
69
|
+
}
|
|
70
|
+
return out;
|
|
71
|
+
}
|
|
72
|
+
/** sets every header of `envelope` on `headers`, replacing any spool header already there */
|
|
73
|
+
export function writeEnvelope(headers, envelope) {
|
|
74
|
+
for (const [name, value] of Object.entries(encodeEnvelope(envelope)))
|
|
75
|
+
headers.set(name, value);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* The envelope of a response as the worker uses it. A malformed spool header drops every field
|
|
79
|
+
* but `Spool-Clear`, which is read on its own so a valid clear still applies and a malformed one
|
|
80
|
+
* reads as a full wipe. A response that names another protocol version is left alone.
|
|
81
|
+
*/
|
|
82
|
+
export function decodeEnvelopeOrClear(headers) {
|
|
83
|
+
try {
|
|
84
|
+
return decodeEnvelope(headers);
|
|
85
|
+
}
|
|
86
|
+
catch {
|
|
87
|
+
const version = headers.get(HEADERS.protocol)?.trim();
|
|
88
|
+
if (version && /^\d{1,15}$/.test(version) && Number(version) !== PROTOCOL_VERSION) {
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
const raw = headers.get(HEADERS.clear);
|
|
92
|
+
if (raw === null)
|
|
93
|
+
return undefined;
|
|
94
|
+
try {
|
|
95
|
+
return {
|
|
96
|
+
protocol: PROTOCOL_VERSION,
|
|
97
|
+
clear: list(raw).map((t) => decode(t, 'Spool-Clear'))
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
catch {
|
|
101
|
+
return { protocol: PROTOCOL_VERSION, clear: [CLEAR_ALL] };
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
/** reads the spool headers; throws `ProtocolError` on a malformed one */
|
|
106
|
+
export function decodeEnvelope(headers) {
|
|
107
|
+
const out = {};
|
|
108
|
+
const protocol = headers.get(HEADERS.protocol);
|
|
109
|
+
if (protocol !== null)
|
|
110
|
+
out.protocol = integer(protocol, 'Spool-Protocol');
|
|
111
|
+
const artifact = headers.get(HEADERS.artifact);
|
|
112
|
+
if (artifact !== null) {
|
|
113
|
+
const fields = new Map();
|
|
114
|
+
for (const part of artifact.split(';')) {
|
|
115
|
+
const eq = part.indexOf('=');
|
|
116
|
+
if (eq < 1)
|
|
117
|
+
return bad('Spool-Artifact has a field without a name');
|
|
118
|
+
fields.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
|
|
119
|
+
}
|
|
120
|
+
const id = fields.get('id');
|
|
121
|
+
const scope = fields.get('scope');
|
|
122
|
+
const version = fields.get('v');
|
|
123
|
+
if (id === undefined || version === undefined)
|
|
124
|
+
return bad('Spool-Artifact needs id and v');
|
|
125
|
+
if (scope !== 'public' && scope !== 'principal')
|
|
126
|
+
return bad('Spool-Artifact scope is unknown');
|
|
127
|
+
out.artifact = {
|
|
128
|
+
id: decode(id, 'Spool-Artifact id'),
|
|
129
|
+
scope,
|
|
130
|
+
deps: list(fields.get('deps') ?? '').map((d) => decode(d, 'Spool-Artifact deps')),
|
|
131
|
+
version: integer(version, 'Spool-Artifact v')
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
const invalidate = headers.get(HEADERS.invalidate);
|
|
135
|
+
if (invalidate !== null) {
|
|
136
|
+
out.invalidate = Object.fromEntries(list(invalidate).map((pair) => {
|
|
137
|
+
const eq = pair.lastIndexOf('=');
|
|
138
|
+
if (eq < 1)
|
|
139
|
+
return bad('Spool-Invalidate entries are tag=version');
|
|
140
|
+
return [
|
|
141
|
+
decode(pair.slice(0, eq), 'Spool-Invalidate tag'),
|
|
142
|
+
integer(pair.slice(eq + 1), 'Spool-Invalidate version')
|
|
143
|
+
];
|
|
144
|
+
}));
|
|
145
|
+
}
|
|
146
|
+
const clear = headers.get(HEADERS.clear);
|
|
147
|
+
if (clear !== null)
|
|
148
|
+
out.clear = list(clear).map((t) => decode(t, 'Spool-Clear'));
|
|
149
|
+
const vector = headers.get(HEADERS.vector);
|
|
150
|
+
if (vector !== null)
|
|
151
|
+
out.vector = integer(vector, 'Spool-Vector');
|
|
152
|
+
const seen = headers.get(HEADERS.vectorSeen);
|
|
153
|
+
if (seen !== null)
|
|
154
|
+
out.seen = integer(seen, 'Spool-Vector-Seen');
|
|
155
|
+
const partition = headers.get(HEADERS.partition);
|
|
156
|
+
if (partition !== null) {
|
|
157
|
+
if (!PARTITION.test(partition))
|
|
158
|
+
return bad('Spool-Partition must be a base64url token');
|
|
159
|
+
out.partition = partition;
|
|
160
|
+
}
|
|
161
|
+
return out;
|
|
162
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** why a protocol value was refused */
|
|
2
|
+
export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-beacon' | 'bad-template' | 'bad-manifest';
|
|
3
|
+
/** thrown for malformed protocol input; `code` names the family so callers can map it to a status */
|
|
4
|
+
export declare class ProtocolError extends Error {
|
|
5
|
+
readonly code: ProtocolErrorCode;
|
|
6
|
+
constructor(code: ProtocolErrorCode, message: string);
|
|
7
|
+
}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/** a reference to a record, resolved against the replica when a page renders */
|
|
2
|
+
export type RecordRef = {
|
|
3
|
+
$record: string;
|
|
4
|
+
};
|
|
5
|
+
/** a reference to a projection, resolved against the replica when a page renders */
|
|
6
|
+
export type ProjectionRef = {
|
|
7
|
+
$projection: string;
|
|
8
|
+
};
|
|
9
|
+
/** what a page's data carries in place of a record or projection stored once elsewhere */
|
|
10
|
+
export type Ref = RecordRef | ProjectionRef;
|
|
11
|
+
/** an authoritative piece of data, stored once by id; its id is the tag that invalidates it */
|
|
12
|
+
export type RecordEntry = {
|
|
13
|
+
id: string;
|
|
14
|
+
/** the vector cursor read before the record was built */
|
|
15
|
+
version: number;
|
|
16
|
+
data: unknown;
|
|
17
|
+
};
|
|
18
|
+
/** a value derived from records, shared by every page that references it */
|
|
19
|
+
export type ProjectionEntry = {
|
|
20
|
+
id: string;
|
|
21
|
+
version: number;
|
|
22
|
+
/** record ids the projection reads, directly or through other projections */
|
|
23
|
+
deps: string[];
|
|
24
|
+
/** a tree that may reference records and other projections */
|
|
25
|
+
data: unknown;
|
|
26
|
+
};
|
|
27
|
+
/** the id lists {@link collectRefs} found */
|
|
28
|
+
export type RefSet = {
|
|
29
|
+
records: string[];
|
|
30
|
+
projections: string[];
|
|
31
|
+
};
|
|
32
|
+
/** the reference to put in a page's data for record `id` */
|
|
33
|
+
export declare function recordRef(id: string): RecordRef;
|
|
34
|
+
/** the reference to put in a page's data for projection `id` */
|
|
35
|
+
export declare function projectionRef(id: string): ProjectionRef;
|
|
36
|
+
/** whether `value` is exactly a reference, with no other keys */
|
|
37
|
+
export declare function isRef(value: unknown): value is Ref;
|
|
38
|
+
/** every record and projection id referenced anywhere in `value`, sorted and unique */
|
|
39
|
+
export declare function collectRefs(value: unknown): RefSet;
|
|
40
|
+
/** where {@link resolveRefs} looks references up */
|
|
41
|
+
export type RefLookup = {
|
|
42
|
+
record(id: string): RecordEntry | undefined;
|
|
43
|
+
projection(id: string): ProjectionEntry | undefined;
|
|
44
|
+
};
|
|
45
|
+
/** the tree with every reference replaced by what it points at, or the first one that is missing */
|
|
46
|
+
export type Resolved = {
|
|
47
|
+
ok: true;
|
|
48
|
+
value: unknown;
|
|
49
|
+
} | {
|
|
50
|
+
ok: false;
|
|
51
|
+
reason: string;
|
|
52
|
+
};
|
|
53
|
+
/**
|
|
54
|
+
* Replaces every reference in `value` with the record's data or the projection's resolved tree.
|
|
55
|
+
* A record's data is taken as is. A missing id or a projection that reaches itself is a refusal,
|
|
56
|
+
* so a page is never rendered with a hole in it.
|
|
57
|
+
*/
|
|
58
|
+
export declare function resolveRefs(value: unknown, lookup: RefLookup): Resolved;
|
|
59
|
+
/** validates one record from an artifact response */
|
|
60
|
+
export declare function parseRecordEntry(value: unknown): RecordEntry;
|
|
61
|
+
/** validates one projection from an artifact response */
|
|
62
|
+
export declare function parseProjectionEntry(value: unknown): ProjectionEntry;
|
|
63
|
+
/** what a load registered, stamped with the vector cursor it was read at */
|
|
64
|
+
export type Collected = {
|
|
65
|
+
records: RecordEntry[];
|
|
66
|
+
projections: ProjectionEntry[];
|
|
67
|
+
/** every record id and projection dependency, for the artifact's own `deps` */
|
|
68
|
+
deps: string[];
|
|
69
|
+
};
|
|
70
|
+
/** what a route's `load` calls to put records and projections into a page's data */
|
|
71
|
+
export type Collector = {
|
|
72
|
+
record(id: string, data: unknown): RecordRef;
|
|
73
|
+
projection(id: string, data: unknown, deps?: readonly string[]): ProjectionRef;
|
|
74
|
+
/** everything registered so far; throws when a projection reaches an unregistered or cyclic one */
|
|
75
|
+
collect(version: number): Collected;
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* A collector for one load. Registering an id twice is allowed only with identical data, because
|
|
79
|
+
* a record is the entity itself and cannot differ between the pages that show it.
|
|
80
|
+
*/
|
|
81
|
+
export declare function createCollector(): Collector;
|