@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.
- package/README.md +279 -1607
- 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 +123 -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 +34 -2
- package/dist/client/register.js +64 -7
- 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 +80 -1
- package/dist/protocol/config.js +31 -1
- package/dist/protocol/dataset.d.ts +189 -0
- package/dist/protocol/dataset.js +212 -0
- package/dist/protocol/envelope.d.ts +34 -1
- package/dist/protocol/envelope.js +16 -1
- package/dist/protocol/errors.d.ts +1 -1
- package/dist/protocol/graph.d.ts +23 -4
- package/dist/protocol/graph.js +34 -3
- package/dist/protocol/index-rows.d.ts +22 -0
- package/dist/protocol/index-rows.js +53 -0
- package/dist/protocol/index.d.ts +5 -0
- package/dist/protocol/index.js +5 -0
- package/dist/protocol/normalise.d.ts +4 -4
- package/dist/protocol/normalise.js +9 -5
- package/dist/protocol/plan.d.ts +100 -0
- package/dist/protocol/plan.js +661 -0
- package/dist/protocol/provision.d.ts +46 -0
- package/dist/protocol/provision.js +38 -0
- package/dist/protocol/query.d.ts +66 -5
- package/dist/protocol/query.js +103 -4
- package/dist/protocol/ring.d.ts +58 -0
- package/dist/protocol/ring.js +6 -0
- package/dist/protocol/route.d.ts +63 -13
- package/dist/protocol/route.js +126 -6
- 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 +234 -0
- package/dist/protocol/write.js +343 -0
- 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/dataset.d.ts +48 -0
- package/dist/report/dataset.js +93 -0
- package/dist/report/demand.d.ts +49 -0
- package/dist/report/demand.js +60 -0
- package/dist/report/derive.d.ts +285 -0
- package/dist/report/derive.js +676 -1
- package/dist/report/economics.d.ts +66 -1
- package/dist/report/economics.js +208 -1
- package/dist/report/headline.d.ts +158 -0
- package/dist/report/headline.js +473 -0
- package/dist/report/index.d.ts +4 -0
- package/dist/report/index.js +4 -0
- package/dist/report/inputs.d.ts +176 -0
- package/dist/report/inputs.js +248 -0
- package/dist/report/institution.d.ts +188 -1
- package/dist/report/institution.js +146 -0
- package/dist/report/loops.d.ts +73 -0
- package/dist/report/loops.js +101 -0
- package/dist/report/measurement.d.ts +1 -1
- package/dist/report/measurement.js +7 -1
- package/dist/report/model.d.ts +2 -0
- package/dist/report/model.js +4 -0
- package/dist/report/thirdparty.d.ts +57 -0
- package/dist/report/thirdparty.js +111 -0
- package/dist/report/traffic.d.ts +8 -0
- package/dist/report/traffic.js +7 -0
- package/dist/report/trim.d.ts +56 -0
- package/dist/report/trim.js +83 -1
- package/dist/server/bundle.d.ts +55 -0
- package/dist/server/bundle.js +172 -0
- package/dist/server/dataset.d.ts +54 -0
- package/dist/server/dataset.js +355 -0
- package/dist/server/embedded.d.ts +7 -3
- package/dist/server/embedded.js +7 -3
- package/dist/server/index.d.ts +6 -0
- package/dist/server/index.js +6 -0
- 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 +158 -3
- package/dist/server/spool.js +578 -41
- 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 +49 -0
- package/dist/server/write.js +223 -0
- package/dist/stores/durable-object.d.ts +46 -0
- package/dist/stores/durable-object.js +114 -0
- package/dist/sw/analytics.d.ts +7 -1
- package/dist/sw/analytics.js +16 -2
- package/dist/sw/coverage.d.ts +6 -0
- package/dist/sw/coverage.js +34 -0
- package/dist/sw/dataset-sync.d.ts +76 -0
- package/dist/sw/dataset-sync.js +149 -0
- package/dist/sw/dataset.d.ts +91 -0
- package/dist/sw/dataset.js +318 -0
- package/dist/sw/family.d.ts +15 -0
- package/dist/sw/family.js +48 -0
- package/dist/sw/graph/index.d.ts +31 -1
- package/dist/sw/graph/index.js +57 -5
- package/dist/sw/graph/invalidate.d.ts +15 -3
- package/dist/sw/graph/invalidate.js +42 -4
- package/dist/sw/idb.d.ts +2 -0
- package/dist/sw/idb.js +80 -11
- 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/partition.d.ts +6 -1
- package/dist/sw/partition.js +21 -2
- package/dist/sw/policy.d.ts +2 -0
- package/dist/sw/policy.js +11 -0
- package/dist/sw/principal-dataset.d.ts +64 -0
- package/dist/sw/principal-dataset.js +254 -0
- package/dist/sw/probe.d.ts +16 -0
- package/dist/sw/probe.js +25 -0
- package/dist/sw/render.d.ts +7 -2
- package/dist/sw/render.js +19 -5
- package/dist/sw/replica.d.ts +12 -3
- package/dist/sw/replica.js +40 -5
- package/dist/sw/router.d.ts +3 -2
- package/dist/sw/router.js +15 -2
- package/dist/sw/runtime.d.ts +90 -2
- package/dist/sw/runtime.js +857 -61
- package/dist/sw/scheduler.d.ts +6 -1
- package/dist/sw/scheduler.js +22 -5
- package/dist/sw/seal.d.ts +13 -0
- package/dist/sw/seal.js +13 -4
- package/dist/sw/static.d.ts +18 -0
- package/dist/sw/static.js +84 -1
- package/dist/sw/storage.d.ts +51 -1
- package/dist/sw/storage.js +33 -1
- package/dist/sw/write.d.ts +147 -0
- package/dist/sw/write.js +625 -0
- 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 +65 -4
package/dist/protocol/route.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { ProtocolError } from './errors.js';
|
|
2
2
|
import { checkPattern, matchPattern } from './pattern.js';
|
|
3
|
+
import { checkPlan } from './plan.js';
|
|
4
|
+
import { DATASET_NAME } from './query.js';
|
|
3
5
|
import { compileTemplate } from './template/compile.js';
|
|
4
6
|
/** public routes default to 15 minutes soft, principal routes to 5 minutes hard */
|
|
5
7
|
export const DEFAULT_FRESHNESS = {
|
|
@@ -9,7 +11,7 @@ export const DEFAULT_FRESHNESS = {
|
|
|
9
11
|
function bad(pattern, message) {
|
|
10
12
|
throw new ProtocolError('bad-route', `${pattern}: ${message}`);
|
|
11
13
|
}
|
|
12
|
-
const QUERY_KEYS = ['list', 'filter', 'sort', 'pageSize'];
|
|
14
|
+
const QUERY_KEYS = ['list', 'filter', 'sort', 'pageSize', 'key', 'dataset', 'plan'];
|
|
13
15
|
const RESERVED = ['sort', 'page'];
|
|
14
16
|
/** the validated copy of a route's `query`; throws `bad-route` for a schema the worker could not apply */
|
|
15
17
|
function checkQuery(pattern, value) {
|
|
@@ -59,8 +61,73 @@ function checkQuery(pattern, value) {
|
|
|
59
61
|
}
|
|
60
62
|
out.pageSize = pageSize;
|
|
61
63
|
}
|
|
64
|
+
const { key, dataset } = given;
|
|
65
|
+
if (key !== undefined) {
|
|
66
|
+
if (typeof key !== 'string' || key === '') {
|
|
67
|
+
return bad(pattern, 'query.key must be a field name');
|
|
68
|
+
}
|
|
69
|
+
out.key = key;
|
|
70
|
+
}
|
|
71
|
+
if (dataset !== undefined) {
|
|
72
|
+
if (typeof dataset !== 'string' || !DATASET_NAME.test(dataset)) {
|
|
73
|
+
return bad(pattern, 'query.dataset must be a dataset name');
|
|
74
|
+
}
|
|
75
|
+
if (key !== undefined)
|
|
76
|
+
return bad(pattern, 'query.key and query.dataset are exclusive');
|
|
77
|
+
out.dataset = dataset;
|
|
78
|
+
}
|
|
79
|
+
const { plan } = given;
|
|
80
|
+
if (plan !== undefined) {
|
|
81
|
+
if (dataset === undefined)
|
|
82
|
+
return bad(pattern, 'query.plan needs query.dataset');
|
|
83
|
+
if (filter !== undefined || sort !== undefined || pageSize !== undefined) {
|
|
84
|
+
return bad(pattern, 'query.plan replaces query.filter, query.sort and query.pageSize');
|
|
85
|
+
}
|
|
86
|
+
out.plan = checkPlan(pattern, plan);
|
|
87
|
+
}
|
|
62
88
|
return out;
|
|
63
89
|
}
|
|
90
|
+
/** the validated copy of a route's `family`; throws `bad-route` for a binding the worker could not apply */
|
|
91
|
+
function checkFamily(pattern, strategy, value, query, scope) {
|
|
92
|
+
if (strategy !== 'template' && strategy !== 'projection' && strategy !== 'data') {
|
|
93
|
+
return bad(pattern, `a ${strategy} route cannot declare family`);
|
|
94
|
+
}
|
|
95
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
96
|
+
return bad(pattern, 'family must be an object');
|
|
97
|
+
}
|
|
98
|
+
const { dataset, key } = value;
|
|
99
|
+
if (typeof dataset !== 'string' || !DATASET_NAME.test(dataset)) {
|
|
100
|
+
return bad(pattern, 'family.dataset must be a dataset name');
|
|
101
|
+
}
|
|
102
|
+
if (typeof key !== 'string' || key === '')
|
|
103
|
+
return bad(pattern, 'family.key must be a param name');
|
|
104
|
+
if (key === 'viewer.id' && scope !== 'principal') {
|
|
105
|
+
return bad(pattern, 'family.key "viewer.id" needs auth: \'principal\'');
|
|
106
|
+
}
|
|
107
|
+
if (key !== 'viewer.id' && !pattern.split('/').includes(`:${key}`)) {
|
|
108
|
+
return bad(pattern, `family.key "${key}" is not a param of the pattern`);
|
|
109
|
+
}
|
|
110
|
+
if (query !== undefined && query.dataset !== dataset) {
|
|
111
|
+
return bad(pattern, 'a family and a query must name the same dataset');
|
|
112
|
+
}
|
|
113
|
+
return { dataset, key };
|
|
114
|
+
}
|
|
115
|
+
/** the validated copy of a data route's `origin`; an absolute http or https origin with no path */
|
|
116
|
+
function checkOrigin(pattern, value) {
|
|
117
|
+
if (typeof value !== 'string')
|
|
118
|
+
return bad(pattern, 'origin must be a string');
|
|
119
|
+
let url;
|
|
120
|
+
try {
|
|
121
|
+
url = new URL(value);
|
|
122
|
+
}
|
|
123
|
+
catch {
|
|
124
|
+
return bad(pattern, `origin "${value}" is not a URL`);
|
|
125
|
+
}
|
|
126
|
+
if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.origin !== value) {
|
|
127
|
+
return bad(pattern, `origin "${value}" must be an http or https origin with no path`);
|
|
128
|
+
}
|
|
129
|
+
return value;
|
|
130
|
+
}
|
|
64
131
|
/**
|
|
65
132
|
* Declares a route. Validates the pattern and the freshness contract, compiles a template, and
|
|
66
133
|
* fills the defaults: freshness by scope, and `offline` as `serve` for public, `refuse` for
|
|
@@ -82,7 +149,16 @@ export function defineRoute(pattern, declaration) {
|
|
|
82
149
|
if (declaration.load !== undefined)
|
|
83
150
|
return bad(pattern, 'a static route has no load');
|
|
84
151
|
}
|
|
85
|
-
const
|
|
152
|
+
const auth = declaration.auth;
|
|
153
|
+
if (auth !== undefined && auth !== 'principal') {
|
|
154
|
+
return bad(pattern, `unknown auth "${String(auth)}"`);
|
|
155
|
+
}
|
|
156
|
+
if (auth !== undefined &&
|
|
157
|
+
declaration.scope !== undefined &&
|
|
158
|
+
declaration.scope !== 'principal') {
|
|
159
|
+
return bad(pattern, 'auth principal needs a principal scope');
|
|
160
|
+
}
|
|
161
|
+
const scope = auth === 'principal' ? 'principal' : (declaration.scope ?? 'public');
|
|
86
162
|
if (scope !== 'public' && scope !== 'principal')
|
|
87
163
|
return bad(pattern, `unknown scope "${scope}"`);
|
|
88
164
|
const freshness = { ...DEFAULT_FRESHNESS[scope], ...declaration.freshness };
|
|
@@ -105,11 +181,16 @@ export function defineRoute(pattern, declaration) {
|
|
|
105
181
|
declaration.mode !== 'shadow') {
|
|
106
182
|
return bad(pattern, `unknown mode "${String(declaration.mode)}"`);
|
|
107
183
|
}
|
|
108
|
-
|
|
184
|
+
const family = declaration.family;
|
|
185
|
+
const origin = declaration.origin;
|
|
186
|
+
if (declaration.strategy !== 'static' &&
|
|
187
|
+
family === undefined &&
|
|
188
|
+
origin === undefined &&
|
|
189
|
+
typeof declaration.load !== 'function') {
|
|
109
190
|
return bad(pattern, 'load is required');
|
|
110
191
|
}
|
|
111
192
|
const declared = declaration.strategy === 'static' ? undefined : declaration.retention;
|
|
112
|
-
const retention = declared ?? '
|
|
193
|
+
const retention = declared ?? 'persistent';
|
|
113
194
|
if (retention !== 'persistent' && retention !== 'session') {
|
|
114
195
|
return bad(pattern, `unknown retention "${String(retention)}"`);
|
|
115
196
|
}
|
|
@@ -149,12 +230,43 @@ export function defineRoute(pattern, declaration) {
|
|
|
149
230
|
}
|
|
150
231
|
const query = declaration.query;
|
|
151
232
|
if (query !== undefined) {
|
|
152
|
-
if (scope !== 'public')
|
|
153
|
-
return bad(pattern, 'query applies to a public route');
|
|
154
233
|
if (!['template', 'projection', 'data'].includes(declaration.strategy)) {
|
|
155
234
|
return bad(pattern, `a ${declaration.strategy} route cannot declare query`);
|
|
156
235
|
}
|
|
157
236
|
route.query = checkQuery(pattern, query);
|
|
237
|
+
// a principal route holds no collection of its own; only a principal dataset can back it
|
|
238
|
+
if (scope === 'principal' && (route.query.dataset === undefined || route.query.plan)) {
|
|
239
|
+
return bad(pattern, 'a principal route declares query only with query.dataset, without a plan');
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
if (family !== undefined) {
|
|
243
|
+
route.family = checkFamily(pattern, declaration.strategy, family, route.query, scope);
|
|
244
|
+
}
|
|
245
|
+
const navigation = declaration.navigation;
|
|
246
|
+
if (navigation !== undefined) {
|
|
247
|
+
if (family === undefined)
|
|
248
|
+
return bad(pattern, 'navigation applies to a family route');
|
|
249
|
+
if (navigation !== 'document') {
|
|
250
|
+
return bad(pattern, `unknown navigation "${String(navigation)}"`);
|
|
251
|
+
}
|
|
252
|
+
route.navigation = 'document';
|
|
253
|
+
}
|
|
254
|
+
if (origin !== undefined) {
|
|
255
|
+
if (declaration.strategy !== 'data')
|
|
256
|
+
return bad(pattern, 'only a data route declares origin');
|
|
257
|
+
if (family === undefined && route.query?.dataset === undefined) {
|
|
258
|
+
return bad(pattern, 'origin needs a family or a query over a dataset');
|
|
259
|
+
}
|
|
260
|
+
if (route.family?.key === 'viewer.id') {
|
|
261
|
+
return bad(pattern, 'family.key "viewer.id" is not available on a cross-origin route');
|
|
262
|
+
}
|
|
263
|
+
route.origin = checkOrigin(pattern, origin);
|
|
264
|
+
}
|
|
265
|
+
// viewer.id reads its row from the dataset, so only the other keys need a load
|
|
266
|
+
if (route.family &&
|
|
267
|
+
route.family.key !== 'viewer.id' &&
|
|
268
|
+
typeof declaration.load !== 'function') {
|
|
269
|
+
route.provisionable = false;
|
|
158
270
|
}
|
|
159
271
|
if (declaration.strategy === 'template') {
|
|
160
272
|
if (!declaration.template)
|
|
@@ -194,5 +306,13 @@ export function serializeRoute(route) {
|
|
|
194
306
|
out.catalogue = true;
|
|
195
307
|
if (route.query)
|
|
196
308
|
out.query = structuredClone(route.query);
|
|
309
|
+
if (route.family)
|
|
310
|
+
out.family = { ...route.family };
|
|
311
|
+
if (route.navigation)
|
|
312
|
+
out.navigation = route.navigation;
|
|
313
|
+
if (route.origin)
|
|
314
|
+
out.origin = route.origin;
|
|
315
|
+
if (route.provisionable === false)
|
|
316
|
+
out.provisionable = false;
|
|
197
317
|
return out;
|
|
198
318
|
}
|
package/dist/protocol/tag.d.ts
CHANGED
|
@@ -1,12 +1,32 @@
|
|
|
1
1
|
/** the attribute that marks the page runtime script, so it is never injected twice */
|
|
2
2
|
export declare const CLIENT_TAG_ATTR = "data-spool-client";
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* the script tag for the page runtime; `integrity` makes it a cross-origin, SRI-checked load, and
|
|
5
|
+
* `worker: 'never'` tells the page it must not ask for a worker, and `'always'` that it may ask on WebKit
|
|
6
|
+
*/
|
|
4
7
|
export declare function clientTag(options: {
|
|
5
8
|
src: string;
|
|
6
9
|
integrity?: string;
|
|
10
|
+
worker?: 'auto' | 'never' | 'always';
|
|
7
11
|
}): string;
|
|
12
|
+
/** the attribute that marks the inline gate, which stands in for the script tag on a second-view page */
|
|
13
|
+
export declare const GATE_ATTR = "data-spool-gate";
|
|
14
|
+
/**
|
|
15
|
+
* the inline gate in place of `clientTag`: `source` is the built gate script, and the attributes
|
|
16
|
+
* name the client it loads, with its integrity and worker mode. `held` lists the paths a click may
|
|
17
|
+
* load the boot script for: a prefix such as `/courses/` for a page with no query string, or `?` and a
|
|
18
|
+
* path for a list that answers a query string.
|
|
19
|
+
*/
|
|
20
|
+
export declare function gateTag(options: {
|
|
21
|
+
src: string;
|
|
22
|
+
integrity?: string;
|
|
23
|
+
worker?: 'auto' | 'never' | 'always';
|
|
24
|
+
held?: readonly string[];
|
|
25
|
+
/** the worker script's lease in seconds; the gate counts views inside one lease period */
|
|
26
|
+
lease?: number;
|
|
27
|
+
}, source: string): string;
|
|
8
28
|
/**
|
|
9
29
|
* Puts `tag` before `</head>`, else before `</body>`, else at the end. A page that already has
|
|
10
|
-
* the runtime tag is returned unchanged, so the server and the worker can both call this.
|
|
30
|
+
* the runtime tag or the gate is returned unchanged, so the server and the worker can both call this.
|
|
11
31
|
*/
|
|
12
32
|
export declare function injectClientTag(html: string, tag: string): string;
|
package/dist/protocol/tag.js
CHANGED
|
@@ -3,19 +3,40 @@ export const CLIENT_TAG_ATTR = 'data-spool-client';
|
|
|
3
3
|
function escapeAttr(value) {
|
|
4
4
|
return value.replace(/&/g, '&').replace(/"/g, '"').replace(/</g, '<');
|
|
5
5
|
}
|
|
6
|
-
/** the
|
|
6
|
+
/** the attribute for a worker mode; `auto` writes none, and a client that predates `always` reads it as `auto` */
|
|
7
|
+
function workerAttr(worker) {
|
|
8
|
+
return worker === 'never' || worker === 'always' ? ` data-spool-worker="${worker}"` : '';
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* the script tag for the page runtime; `integrity` makes it a cross-origin, SRI-checked load, and
|
|
12
|
+
* `worker: 'never'` tells the page it must not ask for a worker, and `'always'` that it may ask on WebKit
|
|
13
|
+
*/
|
|
7
14
|
export function clientTag(options) {
|
|
8
15
|
const sri = options.integrity
|
|
9
16
|
? ` integrity="${escapeAttr(options.integrity)}" crossorigin="anonymous"`
|
|
10
17
|
: '';
|
|
11
|
-
return `<script src="${escapeAttr(options.src)}"${sri} defer ${CLIENT_TAG_ATTR}></script>`;
|
|
18
|
+
return `<script src="${escapeAttr(options.src)}"${sri}${workerAttr(options.worker)} defer ${CLIENT_TAG_ATTR}></script>`;
|
|
19
|
+
}
|
|
20
|
+
/** the attribute that marks the inline gate, which stands in for the script tag on a second-view page */
|
|
21
|
+
export const GATE_ATTR = 'data-spool-gate';
|
|
22
|
+
/**
|
|
23
|
+
* the inline gate in place of `clientTag`: `source` is the built gate script, and the attributes
|
|
24
|
+
* name the client it loads, with its integrity and worker mode. `held` lists the paths a click may
|
|
25
|
+
* load the boot script for: a prefix such as `/courses/` for a page with no query string, or `?` and a
|
|
26
|
+
* path for a list that answers a query string.
|
|
27
|
+
*/
|
|
28
|
+
export function gateTag(options, source) {
|
|
29
|
+
const sri = options.integrity ? ` data-integrity="${escapeAttr(options.integrity)}"` : '';
|
|
30
|
+
const held = options.held?.length ? ` data-held="${escapeAttr(options.held.join(' '))}"` : '';
|
|
31
|
+
const lease = options.lease === undefined ? '' : ` data-lease="${options.lease}"`;
|
|
32
|
+
return `<script ${GATE_ATTR} data-src="${escapeAttr(options.src)}"${sri}${workerAttr(options.worker)}${held}${lease}>${source}</script>`;
|
|
12
33
|
}
|
|
13
34
|
/**
|
|
14
35
|
* Puts `tag` before `</head>`, else before `</body>`, else at the end. A page that already has
|
|
15
|
-
* the runtime tag is returned unchanged, so the server and the worker can both call this.
|
|
36
|
+
* the runtime tag or the gate is returned unchanged, so the server and the worker can both call this.
|
|
16
37
|
*/
|
|
17
38
|
export function injectClientTag(html, tag) {
|
|
18
|
-
if (html.includes(CLIENT_TAG_ATTR))
|
|
39
|
+
if (html.includes(CLIENT_TAG_ATTR) || html.includes(GATE_ATTR))
|
|
19
40
|
return html;
|
|
20
41
|
for (const close of [/<\/head\s*>/i, /<\/body\s*>/i]) {
|
|
21
42
|
const at = html.search(close);
|
package/dist/protocol/view.d.ts
CHANGED
|
@@ -51,6 +51,8 @@ export type ViewEvent = {
|
|
|
51
51
|
* bound on cross-origin network requests. Null until the page reports, and when it never does.
|
|
52
52
|
*/
|
|
53
53
|
crossOriginLoads: number | null;
|
|
54
|
+
/** packs this client installed, as the page last reported; absent until the page reports */
|
|
55
|
+
lifetimes?: number;
|
|
54
56
|
};
|
|
55
57
|
/** a view with the device time it was recorded at, epoch milliseconds */
|
|
56
58
|
export type TimedView = ViewEvent & {
|
package/dist/protocol/view.js
CHANGED
|
@@ -124,13 +124,17 @@ export function viewFromBeacon(event) {
|
|
|
124
124
|
}
|
|
125
125
|
if (typeof value !== 'object' || value === null)
|
|
126
126
|
return null;
|
|
127
|
-
const { id, tier, reason, staleSec, engine, scope, strategy, route, mismatch, swAgeMs, gapMs, from, crossOriginLoads } = value;
|
|
127
|
+
const { id, tier, reason, staleSec, engine, scope, strategy, route, mismatch, swAgeMs, gapMs, from, crossOriginLoads, lifetimes } = value;
|
|
128
128
|
if (typeof id !== 'string' || id === '' || id.length > 64)
|
|
129
129
|
return null;
|
|
130
130
|
if (crossOriginLoads !== null &&
|
|
131
131
|
(!Number.isSafeInteger(crossOriginLoads) || crossOriginLoads < 0)) {
|
|
132
132
|
return null;
|
|
133
133
|
}
|
|
134
|
+
if (lifetimes !== undefined &&
|
|
135
|
+
(!Number.isSafeInteger(lifetimes) || lifetimes < 0)) {
|
|
136
|
+
return null;
|
|
137
|
+
}
|
|
134
138
|
if (typeof tier !== 'string' || !TIERS.includes(tier))
|
|
135
139
|
return null;
|
|
136
140
|
if (typeof reason !== 'string' || !Object.hasOwn(REASON_TIER, reason))
|
|
@@ -165,6 +169,7 @@ export function viewFromBeacon(event) {
|
|
|
165
169
|
...(typeof from === 'string' && from !== '' && from.length <= MAX_ROUTE_CHARS
|
|
166
170
|
? { from }
|
|
167
171
|
: {}),
|
|
172
|
+
...(lifetimes === undefined ? {} : { lifetimes: lifetimes }),
|
|
168
173
|
at: event.at
|
|
169
174
|
};
|
|
170
175
|
}
|
|
@@ -177,7 +182,8 @@ export function engineOf(userAgent) {
|
|
|
177
182
|
return 'webkit';
|
|
178
183
|
if (/\bFirefox\//.test(userAgent))
|
|
179
184
|
return 'firefox';
|
|
180
|
-
|
|
185
|
+
// no leading boundary: headless Chromium names itself HeadlessChrome
|
|
186
|
+
if (/(?:Chrome|Chromium)\//.test(userAgent))
|
|
181
187
|
return 'chromium';
|
|
182
188
|
if (/\bSafari\//.test(userAgent))
|
|
183
189
|
return 'webkit';
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The view times a page keeps for the lease window, as the comma-separated text `spool:stamps` holds:
|
|
3
|
+
* the stored ones a lease period still covers, then `now`, the last three. A stamp at or after `now`,
|
|
4
|
+
* a full lease old, zero or not a number is outside. Not re-exported from the protocol index.
|
|
5
|
+
*/
|
|
6
|
+
export declare function viewStamps(stored: string, now: number, leaseMs: number): number[];
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The view times a page keeps for the lease window, as the comma-separated text `spool:stamps` holds:
|
|
3
|
+
* the stored ones a lease period still covers, then `now`, the last three. A stamp at or after `now`,
|
|
4
|
+
* a full lease old, zero or not a number is outside. Not re-exported from the protocol index.
|
|
5
|
+
*/
|
|
6
|
+
export function viewStamps(stored, now, leaseMs) {
|
|
7
|
+
return [
|
|
8
|
+
...stored
|
|
9
|
+
.split(',')
|
|
10
|
+
.filter(Boolean)
|
|
11
|
+
.map(Number)
|
|
12
|
+
.filter((t) => t >= 0 && t <= now && now - t < leaseMs),
|
|
13
|
+
now
|
|
14
|
+
].slice(-3);
|
|
15
|
+
}
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
import type { DatasetRow } from './dataset.js';
|
|
2
|
+
import { type Identity, type Route } from './route.js';
|
|
3
|
+
/** the header that names one flush of one key; a retry of the same flush sends the same id */
|
|
4
|
+
export declare const WRITE_HEADERS: {
|
|
5
|
+
readonly id: "spool-write-id";
|
|
6
|
+
readonly digest: "spool-write-digest";
|
|
7
|
+
};
|
|
8
|
+
/** a write class name is 1 to 64 of letters, digits, `_` and `-` */
|
|
9
|
+
export declare const WRITE_NAME: RegExp;
|
|
10
|
+
/** the most characters in a key */
|
|
11
|
+
export declare const MAX_WRITE_KEY = 256;
|
|
12
|
+
/** the most bytes `maxBytes` may declare for one value's JSON body */
|
|
13
|
+
export declare const MAX_WRITE_BYTES = 1048576;
|
|
14
|
+
/** the most records `maxPending` may declare per class and partition */
|
|
15
|
+
export declare const MAX_WRITE_PENDING = 1000;
|
|
16
|
+
/** why a write was refused; the server maps each to a status and the page API returns it as `code` */
|
|
17
|
+
export type WriteRefusalCode = 'writes-off' | 'unknown-write' | 'bad-method' | 'bad-key' | 'missing-version' | 'bad-version' | 'bad-id' | 'bad-body' | 'too-large' | 'too-many' | 'id-reused' | 'forbidden' | 'sign-in' | 'no-partition' | 'no-record' | 'not-conflicted' | 'unavailable';
|
|
18
|
+
/** the status the server answers each refusal with */
|
|
19
|
+
export declare const WRITE_STATUS: Record<WriteRefusalCode, number>;
|
|
20
|
+
/** a refusal the page API returns in place of throwing */
|
|
21
|
+
export type WriteRefusal = {
|
|
22
|
+
ok: false;
|
|
23
|
+
code: WriteRefusalCode;
|
|
24
|
+
message: string;
|
|
25
|
+
};
|
|
26
|
+
/** where one queued value stands on the device */
|
|
27
|
+
export type WriteState = 'pending' | 'flushing' | 'conflicted';
|
|
28
|
+
/** the server's newest version of a key and its value, when the site's `read` returned one */
|
|
29
|
+
export type WriteConflict = {
|
|
30
|
+
version: string;
|
|
31
|
+
value?: unknown;
|
|
32
|
+
};
|
|
33
|
+
/** what a page may see of one queued value: no local value, and the server's side of a conflict */
|
|
34
|
+
export type WriteStatus = {
|
|
35
|
+
name: string;
|
|
36
|
+
key: string;
|
|
37
|
+
state: WriteState;
|
|
38
|
+
/** the version the first edit since the last flush started from */
|
|
39
|
+
base: string;
|
|
40
|
+
queuedAt: number;
|
|
41
|
+
updatedAt: number;
|
|
42
|
+
/** bytes of the queued value's JSON */
|
|
43
|
+
bytes: number;
|
|
44
|
+
/** flushes that failed before the network answered */
|
|
45
|
+
attempts: number;
|
|
46
|
+
conflict?: WriteConflict;
|
|
47
|
+
/** the code of a refusal that stopped a flush for good; the record waits for `resolve` */
|
|
48
|
+
refusal?: WriteRefusalCode;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* What one flush did, in counts only. `queued` is the records it tried, `flushed` the ones the server
|
|
52
|
+
* applied, `conflicted` the ones that ended in the `conflicted` state.
|
|
53
|
+
*/
|
|
54
|
+
export type WriteFlush = {
|
|
55
|
+
queued: number;
|
|
56
|
+
flushed: number;
|
|
57
|
+
conflicted: number;
|
|
58
|
+
};
|
|
59
|
+
/** the page API's answer to `write`: how many edits of this key since the last flush the queue holds */
|
|
60
|
+
export type WriteQueued = {
|
|
61
|
+
ok: true;
|
|
62
|
+
state: WriteState;
|
|
63
|
+
edits: number;
|
|
64
|
+
};
|
|
65
|
+
/** the page API's answer to `resolve` */
|
|
66
|
+
export type WriteResolved = {
|
|
67
|
+
ok: true;
|
|
68
|
+
flush?: WriteFlush;
|
|
69
|
+
server?: WriteConflict;
|
|
70
|
+
};
|
|
71
|
+
/** what the site's functions receive: the authenticated principal and the id of this flush */
|
|
72
|
+
export type WriteContext = {
|
|
73
|
+
identity: Identity;
|
|
74
|
+
/** the `Spool-Write-Id` of the request; a site may store it with the value to make `apply` atomic */
|
|
75
|
+
writeId: string;
|
|
76
|
+
};
|
|
77
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
78
|
+
/** what `read` returns: the version of the key now, and its value when the page needs it for a conflict */
|
|
79
|
+
export type WriteRead = {
|
|
80
|
+
version: string;
|
|
81
|
+
value?: unknown;
|
|
82
|
+
};
|
|
83
|
+
/** what `apply` returns: the new version, or the version and value that beat this write */
|
|
84
|
+
export type WriteApplied = {
|
|
85
|
+
version: string;
|
|
86
|
+
} | {
|
|
87
|
+
conflict: WriteConflict;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* The declaration `defineWrite` takes. Every write class is "the last value wins" for one key per
|
|
91
|
+
* principal, applied only when the version the device edited from is still current. There is no
|
|
92
|
+
* class for a comment, a cart, a payment, a counter, an inventory change or an audit record, and
|
|
93
|
+
* `kind` accepts nothing but `last-value`.
|
|
94
|
+
*/
|
|
95
|
+
export type WriteDeclaration = {
|
|
96
|
+
name: string;
|
|
97
|
+
/** `principal` only; a public write is refused */
|
|
98
|
+
scope: 'principal';
|
|
99
|
+
/** the compaction; `last-value` is the only kind there is */
|
|
100
|
+
kind?: 'last-value';
|
|
101
|
+
/** the pattern of the principal route this write edits; `createSpool` refuses a public route */
|
|
102
|
+
path: string;
|
|
103
|
+
/** the key this principal may write for this request; a device naming any other key is refused */
|
|
104
|
+
key(ctx: WriteContext, request: Request): MaybePromise<string>;
|
|
105
|
+
/** the key's version now, read when a flush that already applied is repeated */
|
|
106
|
+
read(ctx: WriteContext, key: string): MaybePromise<WriteRead>;
|
|
107
|
+
/**
|
|
108
|
+
* Writes `value` when the key is still at `expectedVersion` and returns the new version, or
|
|
109
|
+
* returns `{ conflict }` when it has moved. The check and the write must be one atomic step in
|
|
110
|
+
* the site's own storage.
|
|
111
|
+
*/
|
|
112
|
+
apply(ctx: WriteContext, key: string, value: unknown, expectedVersion: string): MaybePromise<WriteApplied>;
|
|
113
|
+
/** the most bytes of one value's JSON body */
|
|
114
|
+
maxBytes: number;
|
|
115
|
+
/** the most queued keys of this class one partition holds on a device */
|
|
116
|
+
maxPending: number;
|
|
117
|
+
/**
|
|
118
|
+
* The longest a queued write of this class may wait before the worker flushes it. Unset keeps the
|
|
119
|
+
* flush at the next network moment, an explicit flush or a page hide. Set, the first queued write
|
|
120
|
+
* starts a deadline, and the flush at it sends every queued record: one request per key.
|
|
121
|
+
*/
|
|
122
|
+
maxDelayMs?: number;
|
|
123
|
+
};
|
|
124
|
+
/** a validated write class */
|
|
125
|
+
export type Write = Readonly<WriteDeclaration & {
|
|
126
|
+
kind: 'last-value';
|
|
127
|
+
}>;
|
|
128
|
+
/** what the worker needs of a class: the limits it enforces before anything is queued */
|
|
129
|
+
export type WriteConfig = {
|
|
130
|
+
name: string;
|
|
131
|
+
maxBytes: number;
|
|
132
|
+
maxPending: number;
|
|
133
|
+
maxDelayMs?: number;
|
|
134
|
+
};
|
|
135
|
+
/**
|
|
136
|
+
* Declares a write class, or with a route pattern a resource write: the request reaches the server
|
|
137
|
+
* once and the device applies the rows the server reports. A class throws `bad-write` for a public
|
|
138
|
+
* scope, a kind other than `last-value`, a name or pattern that does not parse, a missing function or
|
|
139
|
+
* a limit that is not a positive integer within its cap.
|
|
140
|
+
*/
|
|
141
|
+
export declare function defineWrite(pattern: string, declaration: ResourceWriteDeclaration): ResourceWrite;
|
|
142
|
+
export declare function defineWrite(declaration: WriteDeclaration): Write;
|
|
143
|
+
/** the config entry the worker gets for a class */
|
|
144
|
+
export declare function serializeWrite(write: Write): WriteConfig;
|
|
145
|
+
/** whether `key` is a key the wire carries: a non-empty string of at most {@link MAX_WRITE_KEY} characters without NUL */
|
|
146
|
+
export declare function isWriteKey(key: unknown): key is string;
|
|
147
|
+
/** whether `version` is a version the wire carries */
|
|
148
|
+
export declare const isWriteVersion: (version: unknown) => version is string;
|
|
149
|
+
/** whether `id` is a write id the wire carries */
|
|
150
|
+
export declare const isWriteId: (id: unknown) => id is string;
|
|
151
|
+
/** the `If-Match` value for a version: a strong entity tag */
|
|
152
|
+
export declare const ifMatch: (version: string) => string;
|
|
153
|
+
/** the version in an `If-Match` value, or null when it is not one strong entity tag of a valid version */
|
|
154
|
+
export declare function readIfMatch(header: string | null): string | null;
|
|
155
|
+
/** a random write id: 22 base64url characters of 128 random bits */
|
|
156
|
+
export declare function newWriteId(): string;
|
|
157
|
+
/** the methods a resource write may declare */
|
|
158
|
+
export declare const RESOURCE_METHODS: readonly ["POST", "PUT", "PATCH", "DELETE"];
|
|
159
|
+
/** how a declared write changes the held rows; `invalidate` marks the touched rows stale */
|
|
160
|
+
export declare const RESOURCE_APPLY: readonly ["response", "merge", "delete", "invalidate"];
|
|
161
|
+
export type ResourceMethod = (typeof RESOURCE_METHODS)[number];
|
|
162
|
+
export type ResourceApplyMode = (typeof RESOURCE_APPLY)[number];
|
|
163
|
+
/**
|
|
164
|
+
* The change a declared write makes to a row when it is not one of the modes. `set` writes a JSON
|
|
165
|
+
* constant, or the value at a dotted path of the request body when it is `{ body: '<path>' }`. `inc`
|
|
166
|
+
* adds a number to a numeric field, a missing field counting as 0. `unset` removes fields.
|
|
167
|
+
*/
|
|
168
|
+
export type ResourcePatch = {
|
|
169
|
+
set?: Readonly<Record<string, unknown>>;
|
|
170
|
+
inc?: Readonly<Record<string, number>>;
|
|
171
|
+
unset?: readonly string[];
|
|
172
|
+
};
|
|
173
|
+
export type ResourceApply = ResourceApplyMode | ResourcePatch;
|
|
174
|
+
/** what `defineWrite(pattern, ...)` takes */
|
|
175
|
+
export type ResourceWriteDeclaration = {
|
|
176
|
+
method: ResourceMethod;
|
|
177
|
+
/** the dataset the write changes; the server reports the changed rows of each public dataset */
|
|
178
|
+
dataset: string;
|
|
179
|
+
/** the route param whose value is the row's key */
|
|
180
|
+
key: string;
|
|
181
|
+
apply: ResourceApply;
|
|
182
|
+
/** the GET families the write changes, as route patterns */
|
|
183
|
+
updates: readonly string[];
|
|
184
|
+
/** the origin the write goes to when it is not the page's own; absent means same-origin only */
|
|
185
|
+
origin?: string;
|
|
186
|
+
};
|
|
187
|
+
/** a validated resource write; the worker gets these in its config */
|
|
188
|
+
export type ResourceWrite = Readonly<ResourceWriteDeclaration & {
|
|
189
|
+
pattern: string;
|
|
190
|
+
}>;
|
|
191
|
+
/** what `defineResource` returns: the item family and the writes that change it */
|
|
192
|
+
export type Resource = {
|
|
193
|
+
pattern: string;
|
|
194
|
+
dataset: string;
|
|
195
|
+
key: string;
|
|
196
|
+
routes: Route[];
|
|
197
|
+
writes: ResourceWrite[];
|
|
198
|
+
};
|
|
199
|
+
/**
|
|
200
|
+
* The row a declared patch makes of `row` for a request `body`. It is pure, so the worker and any caller
|
|
201
|
+
* get the same row. Returns undefined when a body path names no value or an `inc` field is not a number.
|
|
202
|
+
*/
|
|
203
|
+
export declare function applyPatch(row: DatasetRow, body: unknown, patch: ResourcePatch): DatasetRow | undefined;
|
|
204
|
+
/**
|
|
205
|
+
* Declares a resource. `GET <pattern>` is the collection of the dataset, with no query string; a query
|
|
206
|
+
* string is not answered locally. `GET <pattern>/:key` is a data family of the dataset; `POST <pattern>`
|
|
207
|
+
* inserts; `PUT` and `PATCH <pattern>/:key` replace and update; `DELETE <pattern>/:key` removes. Any
|
|
208
|
+
* `POST`, `PUT`, `PATCH` or `DELETE` of `<pattern>/:key/:action` is a write on that item. Every write
|
|
209
|
+
* updates the collection and the item.
|
|
210
|
+
*/
|
|
211
|
+
export declare function defineResource(pattern: string, declaration: {
|
|
212
|
+
dataset: string;
|
|
213
|
+
key: string;
|
|
214
|
+
origin?: string;
|
|
215
|
+
}): Resource;
|
|
216
|
+
/**
|
|
217
|
+
* The resource write a request matches: its method, a pattern that matches its path, and its origin.
|
|
218
|
+
* A write with no origin matches only the page's own origin; one with an origin matches that origin.
|
|
219
|
+
*/
|
|
220
|
+
export declare function writeFor(writes: readonly ResourceWrite[], method: string, url: URL, pageOrigin: string): ResourceWrite | undefined;
|
|
221
|
+
/**
|
|
222
|
+
* For each write a page made, the resource it couples to and the GET families it updates. A write that
|
|
223
|
+
* couples to no resource reports `resource: null` and no families; that is the uncovered case.
|
|
224
|
+
*/
|
|
225
|
+
export declare function couplingReport(writes: readonly {
|
|
226
|
+
method: string;
|
|
227
|
+
url: string;
|
|
228
|
+
}[], resources: readonly Resource[], pageOrigin: string): Array<{
|
|
229
|
+
method: string;
|
|
230
|
+
url: string;
|
|
231
|
+
resource: string | null;
|
|
232
|
+
families: string[];
|
|
233
|
+
}>;
|
|
234
|
+
export {};
|