@drupflare/spool 0.2.0 → 0.4.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 +499 -43
- package/dist/cdn/client.js +1 -1
- package/dist/cdn/manifest.json +7 -7
- package/dist/cdn/spool-sw.js +1 -1
- package/dist/client/activity.d.ts +37 -0
- package/dist/client/activity.js +114 -0
- package/dist/client/entry.js +34 -1
- package/dist/client/index.d.ts +1 -0
- package/dist/client/index.js +1 -0
- package/dist/client/register.d.ts +23 -1
- package/dist/client/register.js +53 -7
- package/dist/media/embeds.d.ts +3 -2
- package/dist/media/embeds.js +16 -1
- package/dist/protocol/config.d.ts +16 -1
- package/dist/protocol/config.js +3 -1
- package/dist/protocol/dataset.d.ts +183 -0
- package/dist/protocol/dataset.js +206 -0
- package/dist/protocol/envelope.d.ts +3 -0
- package/dist/protocol/envelope.js +14 -3
- 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/hash.d.ts +2 -0
- package/dist/protocol/hash.js +8 -0
- package/dist/protocol/index.d.ts +7 -0
- package/dist/protocol/index.js +7 -0
- package/dist/protocol/inline.d.ts +14 -0
- package/dist/protocol/inline.js +43 -0
- package/dist/protocol/navigation.d.ts +81 -0
- package/dist/protocol/navigation.js +249 -0
- package/dist/protocol/normalise.d.ts +4 -3
- package/dist/protocol/normalise.js +6 -4
- package/dist/protocol/plan.d.ts +100 -0
- package/dist/protocol/plan.js +661 -0
- package/dist/protocol/provision.d.ts +52 -1
- package/dist/protocol/provision.js +53 -5
- package/dist/protocol/query.d.ts +141 -0
- package/dist/protocol/query.js +252 -0
- package/dist/protocol/route.d.ts +85 -5
- package/dist/protocol/route.js +91 -0
- package/dist/protocol/write.d.ts +146 -0
- package/dist/protocol/write.js +101 -0
- package/dist/proxy/bases.d.ts +53 -0
- package/dist/proxy/bases.js +76 -0
- package/dist/proxy/index.d.ts +1 -0
- package/dist/proxy/index.js +1 -0
- package/dist/proxy/proxy.js +8 -2
- package/dist/report/capacity.d.ts +59 -0
- package/dist/report/capacity.js +76 -0
- package/dist/report/channels.d.ts +60 -0
- package/dist/report/channels.js +65 -0
- package/dist/report/dataset.d.ts +48 -0
- package/dist/report/dataset.js +93 -0
- package/dist/report/derive.d.ts +285 -0
- package/dist/report/derive.js +676 -1
- package/dist/report/economics.d.ts +11 -1
- package/dist/report/economics.js +19 -1
- package/dist/report/index.d.ts +5 -0
- package/dist/report/index.js +5 -0
- package/dist/report/inputs.d.ts +97 -0
- package/dist/report/inputs.js +133 -0
- package/dist/report/institution.d.ts +284 -0
- package/dist/report/institution.js +225 -0
- package/dist/report/ledger.d.ts +28 -0
- package/dist/report/ledger.js +30 -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 +6 -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 +11 -2
- package/dist/report/traffic.js +13 -3
- package/dist/report/trim.d.ts +56 -0
- package/dist/report/trim.js +83 -1
- package/dist/server/dataset.d.ts +48 -0
- package/dist/server/dataset.js +308 -0
- package/dist/server/embedded.d.ts +3 -3
- package/dist/server/embedded.js +3 -3
- package/dist/server/index.d.ts +3 -0
- package/dist/server/index.js +3 -0
- package/dist/server/spool.d.ts +40 -0
- package/dist/server/spool.js +184 -23
- package/dist/server/write.d.ts +27 -0
- package/dist/server/write.js +127 -0
- package/dist/sw/analytics.d.ts +6 -0
- package/dist/sw/analytics.js +14 -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/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.js +78 -9
- package/dist/sw/partition.d.ts +6 -1
- package/dist/sw/partition.js +21 -2
- package/dist/sw/principal-dataset.d.ts +64 -0
- package/dist/sw/principal-dataset.js +254 -0
- package/dist/sw/render.d.ts +8 -1
- package/dist/sw/render.js +28 -1
- package/dist/sw/replica.d.ts +14 -3
- package/dist/sw/replica.js +46 -5
- package/dist/sw/router.js +2 -2
- package/dist/sw/runtime.d.ts +43 -2
- package/dist/sw/runtime.js +440 -29
- 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 +107 -0
- package/dist/sw/write.js +442 -0
- package/package.json +5 -2
package/dist/protocol/route.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { AssemblyBody, Scope } from './artifact.js';
|
|
2
2
|
import type { Collector } from './graph.js';
|
|
3
3
|
import { type Params } from './pattern.js';
|
|
4
|
+
import { type QuerySchema } from './query.js';
|
|
4
5
|
import { type CompiledTemplate, type TemplateSource } from './template/compile.js';
|
|
5
6
|
import type { Mode } from './view.js';
|
|
6
7
|
/**
|
|
@@ -17,14 +18,18 @@ export type Retention = 'persistent' | 'session';
|
|
|
17
18
|
export type FreshnessMode = 'hard' | 'soft';
|
|
18
19
|
/** the staleness contract of a route; `maxStale` is in seconds */
|
|
19
20
|
export type Freshness = {
|
|
21
|
+
/** seconds a copy may age before the mode applies */
|
|
20
22
|
maxStale: number;
|
|
23
|
+
/** what happens past maxStale: block on a sync, or show first and sync later */
|
|
21
24
|
mode: FreshnessMode;
|
|
22
25
|
};
|
|
23
26
|
/** whether the worker may show a snapshot it cannot validate because the network is down */
|
|
24
27
|
export type OfflineRule = 'serve' | 'refuse';
|
|
25
28
|
/** who is asking, as the app's `identity.resolve` reports it */
|
|
26
29
|
export type Identity = {
|
|
30
|
+
/** the principal's id, as identity.resolve reports it */
|
|
27
31
|
principal: string;
|
|
32
|
+
/** role names the principal holds; absent when none */
|
|
28
33
|
roles?: readonly string[];
|
|
29
34
|
};
|
|
30
35
|
/** when a soft route past its bound refreshes: right after the view, or at the next network moment */
|
|
@@ -34,24 +39,38 @@ export type SyncRule = 'background' | 'deferred';
|
|
|
34
39
|
* and return the reference to embed in the page's data; see {@link Collector}.
|
|
35
40
|
*/
|
|
36
41
|
export type RouteContext = {
|
|
42
|
+
/** the request being answered */
|
|
37
43
|
request: Request;
|
|
44
|
+
/** the request URL, parsed */
|
|
38
45
|
url: URL;
|
|
46
|
+
/** the values the route pattern captured */
|
|
39
47
|
params: Params;
|
|
48
|
+
/** the principal the app resolved for this request; null when none */
|
|
40
49
|
identity: Identity | null;
|
|
41
|
-
} & Pick<Collector, 'record' | 'projection'>;
|
|
50
|
+
} & Pick<Collector, 'record' | 'projection' | 'row'>;
|
|
42
51
|
/** public routes default to 15 minutes soft, principal routes to 5 minutes hard */
|
|
43
52
|
export declare const DEFAULT_FRESHNESS: Record<Scope, Freshness>;
|
|
44
|
-
/**
|
|
53
|
+
/**
|
|
54
|
+
* a page a route's catalogue suggests, with the share of devices expected to open it next and,
|
|
55
|
+
* when the share is an estimate, `n`, the observations behind it
|
|
56
|
+
*/
|
|
45
57
|
export type CatalogueGuess = {
|
|
58
|
+
/** the page path a device may open next */
|
|
46
59
|
path: string;
|
|
60
|
+
/** share of devices expected to open the page next, from 0 to 1 */
|
|
47
61
|
p: number;
|
|
62
|
+
/** observations behind p; absent when p is a fixed prior */
|
|
63
|
+
n?: number;
|
|
48
64
|
};
|
|
49
65
|
/** the declaration fields every strategy shares */
|
|
50
66
|
export type RouteCommon = {
|
|
67
|
+
/** public or principal; public when absent */
|
|
51
68
|
scope?: Scope;
|
|
69
|
+
/** overrides the scope's default maxStale and mode */
|
|
52
70
|
freshness?: Partial<Freshness>;
|
|
53
71
|
/** keep the artifact across worker restarts; default true */
|
|
54
72
|
persist?: boolean;
|
|
73
|
+
/** serve shows a snapshot offline, refuse does not; default follows the scope */
|
|
55
74
|
offline?: OfflineRule;
|
|
56
75
|
/** `shadow` renders locally and compares but never serves; the server's mode when absent */
|
|
57
76
|
mode?: Mode;
|
|
@@ -63,8 +82,12 @@ export type RouteCommon = {
|
|
|
63
82
|
retention?: Retention;
|
|
64
83
|
/** overrides the provisioning priors for this route when the server decides whether to ship it */
|
|
65
84
|
provision?: {
|
|
85
|
+
/** chance a provisioned artifact serves a later view; the server's prior when absent */
|
|
66
86
|
reuse?: number;
|
|
87
|
+
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
67
88
|
futureViews?: number;
|
|
89
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
90
|
+
maxBytes?: number;
|
|
68
91
|
};
|
|
69
92
|
/**
|
|
70
93
|
* Pages a device on this route may open next, each with the share of devices expected to
|
|
@@ -78,13 +101,26 @@ export type RouteCommon = {
|
|
|
78
101
|
};
|
|
79
102
|
/** a route answered by filling placeholders in a stored shell */
|
|
80
103
|
export type AssemblyRoute = RouteCommon & {
|
|
104
|
+
/** fills placeholders in a stored shell */
|
|
81
105
|
strategy: 'assembly';
|
|
106
|
+
/** returns the body that fills the shell's placeholders */
|
|
82
107
|
load(ctx: RouteContext): AssemblyBody | Promise<AssemblyBody>;
|
|
83
108
|
};
|
|
109
|
+
/** the declaration of a public route that answers query strings from a collection it holds */
|
|
110
|
+
export type QueryRoute = {
|
|
111
|
+
/**
|
|
112
|
+
* The query strings the worker answers from the stored collection. `load` then returns an
|
|
113
|
+
* object whose `list` key holds the array and which carries `proof: await datasetProof(items)`.
|
|
114
|
+
*/
|
|
115
|
+
query?: QuerySchema;
|
|
116
|
+
};
|
|
84
117
|
/** a route answered by rendering stored JSON through a compiled template */
|
|
85
|
-
export type TemplateRoute = RouteCommon & {
|
|
118
|
+
export type TemplateRoute = RouteCommon & QueryRoute & {
|
|
119
|
+
/** renders stored JSON through the template */
|
|
86
120
|
strategy: 'template';
|
|
121
|
+
/** the template source, compiled once when the route is defined */
|
|
87
122
|
template: TemplateSource;
|
|
123
|
+
/** returns the JSON the template renders */
|
|
88
124
|
load(ctx: RouteContext): unknown;
|
|
89
125
|
};
|
|
90
126
|
/**
|
|
@@ -94,10 +130,15 @@ export type TemplateRoute = RouteCommon & {
|
|
|
94
130
|
* is answered in `serve` mode only.
|
|
95
131
|
*/
|
|
96
132
|
export type StaticRoute = Omit<RouteCommon, 'scope' | 'persist' | 'mode' | 'retention'> & {
|
|
133
|
+
/** the file's response, stored and shown with no request */
|
|
97
134
|
strategy: 'static';
|
|
135
|
+
/** always absent; a static route is public */
|
|
98
136
|
scope?: undefined;
|
|
137
|
+
/** always absent; a static route is always kept */
|
|
99
138
|
persist?: undefined;
|
|
139
|
+
/** always absent; a static route has no mode */
|
|
100
140
|
mode?: undefined;
|
|
141
|
+
/** always absent; a static route has no load */
|
|
101
142
|
load?: undefined;
|
|
102
143
|
};
|
|
103
144
|
/**
|
|
@@ -105,16 +146,20 @@ export type StaticRoute = Omit<RouteCommon, 'scope' | 'persist' | 'mode' | 'rete
|
|
|
105
146
|
* `@drupflare/spool/sw` takes a renderer keyed by this pattern. Without one the worker refuses the
|
|
106
147
|
* local view and the network answers.
|
|
107
148
|
*/
|
|
108
|
-
export type ProjectionRoute = RouteCommon & {
|
|
149
|
+
export type ProjectionRoute = RouteCommon & QueryRoute & {
|
|
150
|
+
/** renders stored JSON with the renderer the bundled worker holds */
|
|
109
151
|
strategy: 'projection';
|
|
152
|
+
/** returns the JSON the renderer receives */
|
|
110
153
|
load(ctx: RouteContext): unknown;
|
|
111
154
|
};
|
|
112
155
|
/**
|
|
113
156
|
* A route for a JSON read. The worker answers a GET (not a navigation) from the stored value with
|
|
114
157
|
* `JSON.stringify`, so the application's own handler has to return the same JSON `load` does.
|
|
115
158
|
*/
|
|
116
|
-
export type DataRoute = RouteCommon & {
|
|
159
|
+
export type DataRoute = RouteCommon & QueryRoute & {
|
|
160
|
+
/** answers a GET with the stored JSON */
|
|
117
161
|
strategy: 'data';
|
|
162
|
+
/** returns the JSON the local answer serializes */
|
|
118
163
|
load(ctx: RouteContext): unknown;
|
|
119
164
|
/** the content type of the local answer; default `application/json` */
|
|
120
165
|
contentType?: string;
|
|
@@ -123,35 +168,65 @@ export type DataRoute = RouteCommon & {
|
|
|
123
168
|
export type RouteDeclaration = AssemblyRoute | TemplateRoute | StaticRoute | ProjectionRoute | DataRoute;
|
|
124
169
|
/** a validated route with every default applied */
|
|
125
170
|
export type Route = {
|
|
171
|
+
/** the path pattern the route matches */
|
|
126
172
|
pattern: string;
|
|
173
|
+
/** how the route is answered locally */
|
|
127
174
|
strategy: Strategy;
|
|
175
|
+
/** public or principal, after the default */
|
|
128
176
|
scope: Scope;
|
|
177
|
+
/** the staleness contract with every default applied */
|
|
129
178
|
freshness: Freshness;
|
|
179
|
+
/** whether the artifact survives a worker restart; true by default */
|
|
130
180
|
persist: boolean;
|
|
181
|
+
/** whether a snapshot may be shown while offline, after the default */
|
|
131
182
|
offline: OfflineRule;
|
|
183
|
+
/** serve or shadow; absent means the server decides */
|
|
132
184
|
mode?: Mode;
|
|
185
|
+
/** when a soft route past its bound refreshes */
|
|
133
186
|
sync: SyncRule;
|
|
187
|
+
/** at-rest key lifetime; set only on principal routes */
|
|
134
188
|
retention?: Retention;
|
|
189
|
+
/** content type of a data route's local answer */
|
|
135
190
|
contentType?: string;
|
|
191
|
+
/** provisioning priors that override the server's for this route */
|
|
136
192
|
provision?: {
|
|
193
|
+
/** chance a provisioned artifact serves a later view; the server's prior when absent */
|
|
137
194
|
reuse?: number;
|
|
195
|
+
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
138
196
|
futureViews?: number;
|
|
197
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
198
|
+
maxBytes?: number;
|
|
139
199
|
};
|
|
200
|
+
/** the compiled template of a template route */
|
|
140
201
|
template?: CompiledTemplate;
|
|
202
|
+
/** the route's catalogue function, when it declares one */
|
|
141
203
|
catalogue?: RouteCommon['catalogue'];
|
|
204
|
+
/** compressed bytes of the document the route renders */
|
|
142
205
|
documentBytes?: number;
|
|
206
|
+
/** query strings the worker answers from the stored collection */
|
|
207
|
+
query?: QuerySchema;
|
|
208
|
+
/** tags the artifact is built from; a change to one invalidates it */
|
|
143
209
|
depends(ctx: RouteContext): readonly string[] | Promise<readonly string[]>;
|
|
210
|
+
/** returns the data the artifact is built from */
|
|
144
211
|
load(ctx: RouteContext): unknown;
|
|
145
212
|
};
|
|
146
213
|
/** the part of a route the service worker needs; functions stay on the server */
|
|
147
214
|
export type SerializedRoute = {
|
|
215
|
+
/** the path pattern the route matches */
|
|
148
216
|
pattern: string;
|
|
217
|
+
/** how the route is answered locally */
|
|
149
218
|
strategy: Strategy;
|
|
219
|
+
/** public or principal */
|
|
150
220
|
scope: Scope;
|
|
221
|
+
/** the staleness contract, with maxStale in seconds */
|
|
151
222
|
freshness: Freshness;
|
|
223
|
+
/** whether the artifact survives a worker restart */
|
|
152
224
|
persist: boolean;
|
|
225
|
+
/** whether a snapshot may be shown while offline */
|
|
153
226
|
offline: OfflineRule;
|
|
227
|
+
/** serve or shadow; absent means the server decides */
|
|
154
228
|
mode?: Mode;
|
|
229
|
+
/** when a soft route past its bound refreshes */
|
|
155
230
|
sync: SyncRule;
|
|
156
231
|
/** a principal route's at-rest key; absent on a public route */
|
|
157
232
|
retention?: Retention;
|
|
@@ -161,6 +236,8 @@ export type SerializedRoute = {
|
|
|
161
236
|
version?: string;
|
|
162
237
|
/** the route declares a `catalogue`, so the worker asks for one when a flush goes out on it */
|
|
163
238
|
catalogue?: true;
|
|
239
|
+
/** the query strings the worker answers from the stored collection of a public route */
|
|
240
|
+
query?: QuerySchema;
|
|
164
241
|
};
|
|
165
242
|
/**
|
|
166
243
|
* Declares a route. Validates the pattern and the freshness contract, compiles a template, and
|
|
@@ -170,9 +247,12 @@ export type SerializedRoute = {
|
|
|
170
247
|
export declare function defineRoute(pattern: string, declaration: RouteDeclaration): Route;
|
|
171
248
|
/** the first route whose pattern fits `path`, with the params it captured */
|
|
172
249
|
export declare function matchRoute<T extends {
|
|
250
|
+
/** the pattern a route is matched by */
|
|
173
251
|
pattern: string;
|
|
174
252
|
}>(routes: readonly T[], path: string): {
|
|
253
|
+
/** the first route whose pattern matches the path */
|
|
175
254
|
route: T;
|
|
255
|
+
/** the values the pattern captured from the path */
|
|
176
256
|
params: Params;
|
|
177
257
|
} | null;
|
|
178
258
|
/** strips a route to what the service worker config carries */
|
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,6 +11,82 @@ export const DEFAULT_FRESHNESS = {
|
|
|
9
11
|
function bad(pattern, message) {
|
|
10
12
|
throw new ProtocolError('bad-route', `${pattern}: ${message}`);
|
|
11
13
|
}
|
|
14
|
+
const QUERY_KEYS = ['list', 'filter', 'sort', 'pageSize', 'key', 'dataset', 'plan'];
|
|
15
|
+
const RESERVED = ['sort', 'page'];
|
|
16
|
+
/** the validated copy of a route's `query`; throws `bad-route` for a schema the worker could not apply */
|
|
17
|
+
function checkQuery(pattern, value) {
|
|
18
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
19
|
+
return bad(pattern, 'query must be an object');
|
|
20
|
+
}
|
|
21
|
+
const given = value;
|
|
22
|
+
for (const key of Object.keys(given)) {
|
|
23
|
+
if (!QUERY_KEYS.includes(key))
|
|
24
|
+
return bad(pattern, `unknown query option "${key}"`);
|
|
25
|
+
}
|
|
26
|
+
const { list, filter, sort, pageSize } = given;
|
|
27
|
+
if (typeof list !== 'string' || list === '')
|
|
28
|
+
return bad(pattern, 'query.list must be a name');
|
|
29
|
+
if (list === 'proof' || list === 'query') {
|
|
30
|
+
return bad(pattern, `query.list cannot be "${list}", which the data already uses`);
|
|
31
|
+
}
|
|
32
|
+
const out = { list };
|
|
33
|
+
if (filter !== undefined) {
|
|
34
|
+
if (typeof filter !== 'object' || filter === null || Array.isArray(filter)) {
|
|
35
|
+
return bad(pattern, 'query.filter must be an object');
|
|
36
|
+
}
|
|
37
|
+
out.filter = {};
|
|
38
|
+
for (const [name, type] of Object.entries(filter)) {
|
|
39
|
+
if (name === '' || RESERVED.includes(name)) {
|
|
40
|
+
return bad(pattern, `query.filter cannot name "${name}"`);
|
|
41
|
+
}
|
|
42
|
+
if (type !== 'string' && type !== 'number') {
|
|
43
|
+
return bad(pattern, `query.filter.${name} must be "string" or "number"`);
|
|
44
|
+
}
|
|
45
|
+
out.filter[name] = type;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
if (sort !== undefined) {
|
|
49
|
+
if (!Array.isArray(sort))
|
|
50
|
+
return bad(pattern, 'query.sort must be a list of field names');
|
|
51
|
+
for (const field of sort) {
|
|
52
|
+
if (typeof field !== 'string' || field === '' || RESERVED.includes(field)) {
|
|
53
|
+
return bad(pattern, `query.sort cannot name ${JSON.stringify(field)}`);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
out.sort = [...sort];
|
|
57
|
+
}
|
|
58
|
+
if (pageSize !== undefined) {
|
|
59
|
+
if (typeof pageSize !== 'number' || !Number.isSafeInteger(pageSize) || pageSize < 1) {
|
|
60
|
+
return bad(pattern, 'query.pageSize must be a positive integer');
|
|
61
|
+
}
|
|
62
|
+
out.pageSize = pageSize;
|
|
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
|
+
}
|
|
88
|
+
return out;
|
|
89
|
+
}
|
|
12
90
|
/**
|
|
13
91
|
* Declares a route. Validates the pattern and the freshness contract, compiles a template, and
|
|
14
92
|
* fills the defaults: freshness by scope, and `offline` as `serve` for public, `refuse` for
|
|
@@ -95,6 +173,17 @@ export function defineRoute(pattern, declaration) {
|
|
|
95
173
|
if (declaration.strategy === 'data' && declaration.contentType) {
|
|
96
174
|
route.contentType = declaration.contentType;
|
|
97
175
|
}
|
|
176
|
+
const query = declaration.query;
|
|
177
|
+
if (query !== undefined) {
|
|
178
|
+
if (!['template', 'projection', 'data'].includes(declaration.strategy)) {
|
|
179
|
+
return bad(pattern, `a ${declaration.strategy} route cannot declare query`);
|
|
180
|
+
}
|
|
181
|
+
route.query = checkQuery(pattern, query);
|
|
182
|
+
// a principal route holds no collection of its own; only a principal dataset can back it
|
|
183
|
+
if (scope === 'principal' && (route.query.dataset === undefined || route.query.plan)) {
|
|
184
|
+
return bad(pattern, 'a principal route declares query only with query.dataset, without a plan');
|
|
185
|
+
}
|
|
186
|
+
}
|
|
98
187
|
if (declaration.strategy === 'template') {
|
|
99
188
|
if (!declaration.template)
|
|
100
189
|
return bad(pattern, 'a template route needs a template');
|
|
@@ -131,5 +220,7 @@ export function serializeRoute(route) {
|
|
|
131
220
|
out.type = route.contentType;
|
|
132
221
|
if (route.catalogue)
|
|
133
222
|
out.catalogue = true;
|
|
223
|
+
if (route.query)
|
|
224
|
+
out.query = structuredClone(route.query);
|
|
134
225
|
return out;
|
|
135
226
|
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import type { Identity } from './route.js';
|
|
2
|
+
/** the header that names one flush of one key; a retry of the same flush sends the same id */
|
|
3
|
+
export declare const WRITE_HEADERS: {
|
|
4
|
+
readonly id: "spool-write-id";
|
|
5
|
+
};
|
|
6
|
+
/** a write class name is 1 to 64 of letters, digits, `_` and `-` */
|
|
7
|
+
export declare const WRITE_NAME: RegExp;
|
|
8
|
+
/** the most characters in a key */
|
|
9
|
+
export declare const MAX_WRITE_KEY = 256;
|
|
10
|
+
/** the most bytes `maxBytes` may declare for one value's JSON body */
|
|
11
|
+
export declare const MAX_WRITE_BYTES = 1048576;
|
|
12
|
+
/** the most records `maxPending` may declare per class and partition */
|
|
13
|
+
export declare const MAX_WRITE_PENDING = 1000;
|
|
14
|
+
/** why a write was refused; the server maps each to a status and the page API returns it as `code` */
|
|
15
|
+
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';
|
|
16
|
+
/** the status the server answers each refusal with */
|
|
17
|
+
export declare const WRITE_STATUS: Record<WriteRefusalCode, number>;
|
|
18
|
+
/** a refusal the page API returns in place of throwing */
|
|
19
|
+
export type WriteRefusal = {
|
|
20
|
+
ok: false;
|
|
21
|
+
code: WriteRefusalCode;
|
|
22
|
+
message: string;
|
|
23
|
+
};
|
|
24
|
+
/** where one queued value stands on the device */
|
|
25
|
+
export type WriteState = 'pending' | 'flushing' | 'conflicted';
|
|
26
|
+
/** the server's newest version of a key and its value, when the site's `read` returned one */
|
|
27
|
+
export type WriteConflict = {
|
|
28
|
+
version: string;
|
|
29
|
+
value?: unknown;
|
|
30
|
+
};
|
|
31
|
+
/** what a page may see of one queued value: no local value, and the server's side of a conflict */
|
|
32
|
+
export type WriteStatus = {
|
|
33
|
+
name: string;
|
|
34
|
+
key: string;
|
|
35
|
+
state: WriteState;
|
|
36
|
+
/** the version the first edit since the last flush started from */
|
|
37
|
+
base: string;
|
|
38
|
+
queuedAt: number;
|
|
39
|
+
updatedAt: number;
|
|
40
|
+
/** bytes of the queued value's JSON */
|
|
41
|
+
bytes: number;
|
|
42
|
+
/** flushes that failed before the network answered */
|
|
43
|
+
attempts: number;
|
|
44
|
+
conflict?: WriteConflict;
|
|
45
|
+
/** the code of a refusal that stopped a flush for good; the record waits for `resolve` */
|
|
46
|
+
refusal?: WriteRefusalCode;
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* What one flush did, in counts only. `queued` is the records it tried, `flushed` the ones the server
|
|
50
|
+
* applied, `conflicted` the ones that ended in the `conflicted` state.
|
|
51
|
+
*/
|
|
52
|
+
export type WriteFlush = {
|
|
53
|
+
queued: number;
|
|
54
|
+
flushed: number;
|
|
55
|
+
conflicted: number;
|
|
56
|
+
};
|
|
57
|
+
/** the page API's answer to `write`: how many edits of this key since the last flush the queue holds */
|
|
58
|
+
export type WriteQueued = {
|
|
59
|
+
ok: true;
|
|
60
|
+
state: WriteState;
|
|
61
|
+
edits: number;
|
|
62
|
+
};
|
|
63
|
+
/** the page API's answer to `resolve` */
|
|
64
|
+
export type WriteResolved = {
|
|
65
|
+
ok: true;
|
|
66
|
+
flush?: WriteFlush;
|
|
67
|
+
server?: WriteConflict;
|
|
68
|
+
};
|
|
69
|
+
/** what the site's functions receive: the authenticated principal and the id of this flush */
|
|
70
|
+
export type WriteContext = {
|
|
71
|
+
identity: Identity;
|
|
72
|
+
/** the `Spool-Write-Id` of the request; a site may store it with the value to make `apply` atomic */
|
|
73
|
+
writeId: string;
|
|
74
|
+
};
|
|
75
|
+
type MaybePromise<T> = T | Promise<T>;
|
|
76
|
+
/** what `read` returns: the version of the key now, and its value when the page needs it for a conflict */
|
|
77
|
+
export type WriteRead = {
|
|
78
|
+
version: string;
|
|
79
|
+
value?: unknown;
|
|
80
|
+
};
|
|
81
|
+
/** what `apply` returns: the new version, or the version and value that beat this write */
|
|
82
|
+
export type WriteApplied = {
|
|
83
|
+
version: string;
|
|
84
|
+
} | {
|
|
85
|
+
conflict: WriteConflict;
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* The declaration `defineWrite` takes. Every write class is "the last value wins" for one key per
|
|
89
|
+
* principal, applied only when the version the device edited from is still current. There is no
|
|
90
|
+
* class for a comment, a cart, a payment, a counter, an inventory change or an audit record, and
|
|
91
|
+
* `kind` accepts nothing but `last-value`.
|
|
92
|
+
*/
|
|
93
|
+
export type WriteDeclaration = {
|
|
94
|
+
name: string;
|
|
95
|
+
/** `principal` only; a public write is refused */
|
|
96
|
+
scope: 'principal';
|
|
97
|
+
/** the compaction; `last-value` is the only kind there is */
|
|
98
|
+
kind?: 'last-value';
|
|
99
|
+
/** the pattern of the principal route this write edits; `createSpool` refuses a public route */
|
|
100
|
+
path: string;
|
|
101
|
+
/** the key this principal may write for this request; a device naming any other key is refused */
|
|
102
|
+
key(ctx: WriteContext, request: Request): MaybePromise<string>;
|
|
103
|
+
/** the key's version now, read when a flush that already applied is repeated */
|
|
104
|
+
read(ctx: WriteContext, key: string): MaybePromise<WriteRead>;
|
|
105
|
+
/**
|
|
106
|
+
* Writes `value` when the key is still at `expectedVersion` and returns the new version, or
|
|
107
|
+
* returns `{ conflict }` when it has moved. The check and the write must be one atomic step in
|
|
108
|
+
* the site's own storage.
|
|
109
|
+
*/
|
|
110
|
+
apply(ctx: WriteContext, key: string, value: unknown, expectedVersion: string): MaybePromise<WriteApplied>;
|
|
111
|
+
/** the most bytes of one value's JSON body */
|
|
112
|
+
maxBytes: number;
|
|
113
|
+
/** the most queued keys of this class one partition holds on a device */
|
|
114
|
+
maxPending: number;
|
|
115
|
+
};
|
|
116
|
+
/** a validated write class */
|
|
117
|
+
export type Write = Readonly<WriteDeclaration & {
|
|
118
|
+
kind: 'last-value';
|
|
119
|
+
}>;
|
|
120
|
+
/** what the worker needs of a class: the limits it enforces before anything is queued */
|
|
121
|
+
export type WriteConfig = {
|
|
122
|
+
name: string;
|
|
123
|
+
maxBytes: number;
|
|
124
|
+
maxPending: number;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* Declares a write class. Throws `bad-write` for a public scope, a kind other than `last-value`, a
|
|
128
|
+
* name or pattern that does not parse, a missing function or a limit that is not a positive
|
|
129
|
+
* integer within its cap.
|
|
130
|
+
*/
|
|
131
|
+
export declare function defineWrite(declaration: WriteDeclaration): Write;
|
|
132
|
+
/** the config entry the worker gets for a class */
|
|
133
|
+
export declare function serializeWrite(write: Write): WriteConfig;
|
|
134
|
+
/** whether `key` is a key the wire carries: a non-empty string of at most {@link MAX_WRITE_KEY} characters without NUL */
|
|
135
|
+
export declare function isWriteKey(key: unknown): key is string;
|
|
136
|
+
/** whether `version` is a version the wire carries */
|
|
137
|
+
export declare const isWriteVersion: (version: unknown) => version is string;
|
|
138
|
+
/** whether `id` is a write id the wire carries */
|
|
139
|
+
export declare const isWriteId: (id: unknown) => id is string;
|
|
140
|
+
/** the `If-Match` value for a version: a strong entity tag */
|
|
141
|
+
export declare const ifMatch: (version: string) => string;
|
|
142
|
+
/** the version in an `If-Match` value, or null when it is not one strong entity tag of a valid version */
|
|
143
|
+
export declare function readIfMatch(header: string | null): string | null;
|
|
144
|
+
/** a random write id: 22 base64url characters of 128 random bits */
|
|
145
|
+
export declare function newWriteId(): string;
|
|
146
|
+
export {};
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { ProtocolError } from './errors.js';
|
|
2
|
+
import { checkPattern } from './pattern.js';
|
|
3
|
+
/** the header that names one flush of one key; a retry of the same flush sends the same id */
|
|
4
|
+
export const WRITE_HEADERS = { id: 'spool-write-id' };
|
|
5
|
+
/** a write class name is 1 to 64 of letters, digits, `_` and `-` */
|
|
6
|
+
export const WRITE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
|
|
7
|
+
const VERSION = /^[A-Za-z0-9._:~-]{1,128}$/;
|
|
8
|
+
const WRITE_ID = /^[A-Za-z0-9_-]{16,64}$/;
|
|
9
|
+
/** the most characters in a key */
|
|
10
|
+
export const MAX_WRITE_KEY = 256;
|
|
11
|
+
/** the most bytes `maxBytes` may declare for one value's JSON body */
|
|
12
|
+
export const MAX_WRITE_BYTES = 1_048_576;
|
|
13
|
+
/** the most records `maxPending` may declare per class and partition */
|
|
14
|
+
export const MAX_WRITE_PENDING = 1000;
|
|
15
|
+
/** the status the server answers each refusal with */
|
|
16
|
+
export const WRITE_STATUS = {
|
|
17
|
+
'writes-off': 403,
|
|
18
|
+
'unknown-write': 404,
|
|
19
|
+
'bad-method': 405,
|
|
20
|
+
'bad-key': 400,
|
|
21
|
+
'missing-version': 428,
|
|
22
|
+
'bad-version': 400,
|
|
23
|
+
'bad-id': 400,
|
|
24
|
+
'bad-body': 400,
|
|
25
|
+
'too-large': 413,
|
|
26
|
+
'too-many': 429,
|
|
27
|
+
'id-reused': 422,
|
|
28
|
+
forbidden: 403,
|
|
29
|
+
'sign-in': 401,
|
|
30
|
+
'no-partition': 409,
|
|
31
|
+
'no-record': 404,
|
|
32
|
+
'not-conflicted': 409,
|
|
33
|
+
unavailable: 503
|
|
34
|
+
};
|
|
35
|
+
function bad(name, message) {
|
|
36
|
+
throw new ProtocolError('bad-write', `${name}: ${message}`);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Declares a write class. Throws `bad-write` for a public scope, a kind other than `last-value`, a
|
|
40
|
+
* name or pattern that does not parse, a missing function or a limit that is not a positive
|
|
41
|
+
* integer within its cap.
|
|
42
|
+
*/
|
|
43
|
+
export function defineWrite(declaration) {
|
|
44
|
+
const name = String(declaration?.name);
|
|
45
|
+
if (typeof declaration?.name !== 'string' || !WRITE_NAME.test(declaration.name)) {
|
|
46
|
+
return bad(name, 'a write name is 1 to 64 of letters, digits, _ and -');
|
|
47
|
+
}
|
|
48
|
+
const scope = declaration.scope;
|
|
49
|
+
if (scope !== 'principal') {
|
|
50
|
+
return bad(name, `scope must be "principal"; a "${scope}" write is never queued`);
|
|
51
|
+
}
|
|
52
|
+
const kind = declaration.kind ?? 'last-value';
|
|
53
|
+
if (kind !== 'last-value') {
|
|
54
|
+
return bad(name, `kind "${kind}" does not exist; the only kind is "last-value"`);
|
|
55
|
+
}
|
|
56
|
+
if (typeof declaration.path !== 'string')
|
|
57
|
+
return bad(name, 'path must be a route pattern');
|
|
58
|
+
checkPattern(declaration.path);
|
|
59
|
+
for (const fn of ['key', 'read', 'apply']) {
|
|
60
|
+
if (typeof declaration[fn] !== 'function')
|
|
61
|
+
return bad(name, `${fn} must be a function`);
|
|
62
|
+
}
|
|
63
|
+
const caps = { maxBytes: MAX_WRITE_BYTES, maxPending: MAX_WRITE_PENDING };
|
|
64
|
+
for (const limit of ['maxBytes', 'maxPending']) {
|
|
65
|
+
const value = declaration[limit];
|
|
66
|
+
if (!Number.isSafeInteger(value) || value < 1 || value > caps[limit]) {
|
|
67
|
+
return bad(name, `${limit} must be an integer from 1 to ${caps[limit]}`);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return Object.freeze({ ...declaration, kind: 'last-value' });
|
|
71
|
+
}
|
|
72
|
+
/** the config entry the worker gets for a class */
|
|
73
|
+
export function serializeWrite(write) {
|
|
74
|
+
return { name: write.name, maxBytes: write.maxBytes, maxPending: write.maxPending };
|
|
75
|
+
}
|
|
76
|
+
/** whether `key` is a key the wire carries: a non-empty string of at most {@link MAX_WRITE_KEY} characters without NUL */
|
|
77
|
+
export function isWriteKey(key) {
|
|
78
|
+
return (typeof key === 'string' &&
|
|
79
|
+
key.length > 0 &&
|
|
80
|
+
key.length <= MAX_WRITE_KEY &&
|
|
81
|
+
!key.includes('\u0000'));
|
|
82
|
+
}
|
|
83
|
+
/** whether `version` is a version the wire carries */
|
|
84
|
+
export const isWriteVersion = (version) => typeof version === 'string' && VERSION.test(version);
|
|
85
|
+
/** whether `id` is a write id the wire carries */
|
|
86
|
+
export const isWriteId = (id) => typeof id === 'string' && WRITE_ID.test(id);
|
|
87
|
+
/** the `If-Match` value for a version: a strong entity tag */
|
|
88
|
+
export const ifMatch = (version) => `"${version}"`;
|
|
89
|
+
/** the version in an `If-Match` value, or null when it is not one strong entity tag of a valid version */
|
|
90
|
+
export function readIfMatch(header) {
|
|
91
|
+
const match = header === null ? null : /^"([^"]*)"$/.exec(header.trim());
|
|
92
|
+
return match && isWriteVersion(match[1]) ? match[1] : null;
|
|
93
|
+
}
|
|
94
|
+
/** a random write id: 22 base64url characters of 128 random bits */
|
|
95
|
+
export function newWriteId() {
|
|
96
|
+
const bytes = crypto.getRandomValues(new Uint8Array(16));
|
|
97
|
+
let binary = '';
|
|
98
|
+
for (const byte of bytes)
|
|
99
|
+
binary += String.fromCharCode(byte);
|
|
100
|
+
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
|
|
101
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/** one file of a crawl: its URL, its kind and its plain compressed size */
|
|
2
|
+
export type BaseCandidate = {
|
|
3
|
+
/** the URL the file was crawled from */
|
|
4
|
+
url: string;
|
|
5
|
+
/** whether the file is a stylesheet or a script */
|
|
6
|
+
kind: 'style' | 'script';
|
|
7
|
+
/** compressed size of the file alone, with no dictionary, in bytes */
|
|
8
|
+
plain: number;
|
|
9
|
+
};
|
|
10
|
+
/** compressed size of `file` against `dictionary`, both indexes into the candidate list */
|
|
11
|
+
export type DeltaSize = (file: number, dictionary: number) => number | Promise<number>;
|
|
12
|
+
/**
|
|
13
|
+
* What a candidate base is scored on. `held` counts what the other files cost against it, for a
|
|
14
|
+
* visitor who already holds the base. `first-visit` adds the base's own plain size, for a visitor
|
|
15
|
+
* who loads every file of the group and has not held it. Neither weighs how often each file is
|
|
16
|
+
* requested or how long a browser keeps the base, so neither is a proven minimum of total transfer.
|
|
17
|
+
*/
|
|
18
|
+
export type BasePolicy = 'held' | 'first-visit';
|
|
19
|
+
export type BaseChoice = {
|
|
20
|
+
/** whether the base is a stylesheet or a script */
|
|
21
|
+
kind: 'style' | 'script';
|
|
22
|
+
/** the path up to the last slash that every member shares */
|
|
23
|
+
directory: string;
|
|
24
|
+
/** the URL of the chosen base file */
|
|
25
|
+
url: string;
|
|
26
|
+
/** how many files of the crawl share the directory and kind, the base included */
|
|
27
|
+
files: number;
|
|
28
|
+
/** mean bytes each other file costs against this base, capped at its plain size */
|
|
29
|
+
meanDelta: number;
|
|
30
|
+
};
|
|
31
|
+
/** the path of a URL up to and including its last slash */
|
|
32
|
+
export declare function dirOf(url: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* The member of `members` that minimizes the sum, over the other members, of the smaller of their
|
|
35
|
+
* delta against it and their plain size, plus the member's own plain size under `first-visit`.
|
|
36
|
+
* Ties keep the member listed first. `score` is the minimized sum and `others` its part without the
|
|
37
|
+
* base's own size.
|
|
38
|
+
*/
|
|
39
|
+
export declare function pickBase(members: readonly number[], delta: (file: number, dictionary: number) => number, plain: (file: number) => number, policy?: BasePolicy): {
|
|
40
|
+
best: number;
|
|
41
|
+
score: number;
|
|
42
|
+
others: number;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* One base per directory and kind, scored by `policy` (default `held`). Members are ordered by URL
|
|
46
|
+
* before scoring, so a tie goes to the URL that sorts first whatever the input order. A group of
|
|
47
|
+
* one file has no base.
|
|
48
|
+
*/
|
|
49
|
+
export declare function chooseBases(files: readonly BaseCandidate[], delta: DeltaSize, options?: {
|
|
50
|
+
policy?: BasePolicy;
|
|
51
|
+
}): Promise<BaseChoice[]>;
|
|
52
|
+
/** true for the exact pathnames of the chosen base URLs; a query string does not count */
|
|
53
|
+
export declare function baseMatcher(choices: readonly BaseChoice[]): (pathname: string) => boolean;
|