@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
|
@@ -103,3 +103,49 @@ export declare function chooseEntries(candidates: readonly EntryCandidate[], opt
|
|
|
103
103
|
* has no device identity, so this is a share of views, not of provisioned copies.
|
|
104
104
|
*/
|
|
105
105
|
export declare function smoothReuse(warmViews: number, coldViews: number, prior?: ProvisionPrior, weight?: number): number;
|
|
106
|
+
/** the two controls a dataset must beat: the held page under v0.3, and a plain HTTP cache */
|
|
107
|
+
export type DatasetControl = 'v0.3' | 'native';
|
|
108
|
+
/** compressed sizes, in bytes, of one dataset and the two controls it is measured against */
|
|
109
|
+
export type DatasetInputs = {
|
|
110
|
+
/** the seed the device stores first */
|
|
111
|
+
seedBytes: number;
|
|
112
|
+
/** one update's patch */
|
|
113
|
+
patchBytes: number;
|
|
114
|
+
/** updates per day to the rows the dataset holds */
|
|
115
|
+
updatesPerDay: number;
|
|
116
|
+
/** v0.3: the seed of the held artifact and the bytes it refetches per update */
|
|
117
|
+
v03: {
|
|
118
|
+
seedBytes: number;
|
|
119
|
+
refetchBytes: number;
|
|
120
|
+
};
|
|
121
|
+
/** native: the bytes a plain HTTP cache still sends for each view */
|
|
122
|
+
nativeBytesPerView: number;
|
|
123
|
+
/** chance a stored copy survives the hold window; see {@link DATASET_DEFAULTS} */
|
|
124
|
+
survival?: number;
|
|
125
|
+
/** days a copy is held and kept current; see {@link DATASET_DEFAULTS} */
|
|
126
|
+
holdDays?: number;
|
|
127
|
+
};
|
|
128
|
+
/**
|
|
129
|
+
* Scenario values (L3). Safari clears script-written storage after 7 days without interaction
|
|
130
|
+
* (the window is published, L0); the survival of a copy inside that window is not measured.
|
|
131
|
+
*/
|
|
132
|
+
export declare const DATASET_DEFAULTS: {
|
|
133
|
+
readonly survival: 0.5;
|
|
134
|
+
readonly holdDays: 7;
|
|
135
|
+
};
|
|
136
|
+
export type DatasetBenefit = {
|
|
137
|
+
/** weighed bytes the dataset saves against each control; positive means it moves fewer */
|
|
138
|
+
net: Record<DatasetControl, number>;
|
|
139
|
+
/** the control with the smaller margin: the one the dataset must beat hardest */
|
|
140
|
+
controls: DatasetControl;
|
|
141
|
+
/** the dataset beats both controls */
|
|
142
|
+
ship: boolean;
|
|
143
|
+
};
|
|
144
|
+
/**
|
|
145
|
+
* Views a stored copy serves are `reuse x survival x futureViews`. A device fetches at most one
|
|
146
|
+
* patch per served view, so the fetches over the hold are `min(updates, views)`. Each control
|
|
147
|
+
* is compared on the same views: the margin against v0.3 is its seed and refetches less the
|
|
148
|
+
* dataset's; the margin against native is what a plain HTTP cache would still send for those
|
|
149
|
+
* views less the dataset's seed and patches. Requests weigh as {@link weigh} does.
|
|
150
|
+
*/
|
|
151
|
+
export declare function datasetBenefit(inputs: DatasetInputs, prior?: ProvisionPrior): DatasetBenefit;
|
|
@@ -113,3 +113,41 @@ export function chooseEntries(candidates, options) {
|
|
|
113
113
|
export function smoothReuse(warmViews, coldViews, prior = DEFAULT_PRIOR, weight = 10) {
|
|
114
114
|
return (prior.reuse * weight + warmViews) / (weight + warmViews + coldViews);
|
|
115
115
|
}
|
|
116
|
+
/**
|
|
117
|
+
* Scenario values (L3). Safari clears script-written storage after 7 days without interaction
|
|
118
|
+
* (the window is published, L0); the survival of a copy inside that window is not measured.
|
|
119
|
+
*/
|
|
120
|
+
export const DATASET_DEFAULTS = { survival: 0.5, holdDays: 7 };
|
|
121
|
+
/**
|
|
122
|
+
* Views a stored copy serves are `reuse x survival x futureViews`. A device fetches at most one
|
|
123
|
+
* patch per served view, so the fetches over the hold are `min(updates, views)`. Each control
|
|
124
|
+
* is compared on the same views: the margin against v0.3 is its seed and refetches less the
|
|
125
|
+
* dataset's; the margin against native is what a plain HTTP cache would still send for those
|
|
126
|
+
* views less the dataset's seed and patches. Requests weigh as {@link weigh} does.
|
|
127
|
+
*/
|
|
128
|
+
export function datasetBenefit(inputs, prior = DEFAULT_PRIOR) {
|
|
129
|
+
const survival = inputs.survival ?? DATASET_DEFAULTS.survival;
|
|
130
|
+
const holdDays = inputs.holdDays ?? DATASET_DEFAULTS.holdDays;
|
|
131
|
+
const sizes = [
|
|
132
|
+
inputs.seedBytes,
|
|
133
|
+
inputs.patchBytes,
|
|
134
|
+
inputs.updatesPerDay,
|
|
135
|
+
inputs.v03.seedBytes,
|
|
136
|
+
inputs.v03.refetchBytes,
|
|
137
|
+
inputs.nativeBytesPerView,
|
|
138
|
+
holdDays
|
|
139
|
+
];
|
|
140
|
+
if (!sizes.every(sound) || !(survival >= 0 && survival <= 1)) {
|
|
141
|
+
throw new RangeError('dataset sizes must be non-negative numbers and survival 0 to 1');
|
|
142
|
+
}
|
|
143
|
+
const w = (bytes) => weigh({ bytes, requests: 1 }, prior.requestBytes);
|
|
144
|
+
const views = prior.reuse * survival * prior.futureViews;
|
|
145
|
+
const fetches = Math.min(inputs.updatesPerDay * holdDays, views);
|
|
146
|
+
const dataset = w(inputs.seedBytes) + fetches * w(inputs.patchBytes);
|
|
147
|
+
const net = {
|
|
148
|
+
'v0.3': w(inputs.v03.seedBytes) + fetches * w(inputs.v03.refetchBytes) - dataset,
|
|
149
|
+
native: views * w(inputs.nativeBytesPerView) - dataset
|
|
150
|
+
};
|
|
151
|
+
const controls = net.native < net['v0.3'] ? 'native' : 'v0.3';
|
|
152
|
+
return { net, controls, ship: net[controls] > 0 };
|
|
153
|
+
}
|
package/dist/protocol/query.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { QueryPlan } from './plan.js';
|
|
1
2
|
/** how a query parameter is read when it filters a field */
|
|
2
3
|
export type QueryFilterType = 'string' | 'number';
|
|
3
4
|
/**
|
|
@@ -16,14 +17,46 @@ export type QuerySchema = {
|
|
|
16
17
|
sort?: readonly string[];
|
|
17
18
|
/** items per page; turns on the page parameter */
|
|
18
19
|
pageSize?: number;
|
|
20
|
+
/** field of each item that holds its dataset key; a list with a set proof needs it */
|
|
21
|
+
key?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Name of a dataset the device holds. The rows it holds are the collection, in ascending key
|
|
24
|
+
* order, so the route's data carries no list and no proof. Exclusive with `key`.
|
|
25
|
+
*/
|
|
26
|
+
dataset?: string;
|
|
27
|
+
/**
|
|
28
|
+
* A read-only plan over the held dataset: joins, conditions, groups and aggregates. Requires
|
|
29
|
+
* `dataset`; `list` names the key the result rows go under. See {@link QueryPlan}.
|
|
30
|
+
*/
|
|
31
|
+
plan?: QueryPlan;
|
|
19
32
|
};
|
|
20
|
-
/**
|
|
33
|
+
/**
|
|
34
|
+
* What a collection's `load` result carries so the worker can tell it holds every item the server
|
|
35
|
+
* sent. This is the ordered proof: a hash of the whole array in its order. {@link SetProof} is the
|
|
36
|
+
* order-independent one a dataset uses.
|
|
37
|
+
*/
|
|
21
38
|
export type DatasetProof = {
|
|
39
|
+
/** `ordered`; absent on every proof made before the set proof existed */
|
|
40
|
+
kind?: 'ordered';
|
|
22
41
|
/** number of items in the collection */
|
|
23
42
|
count: number;
|
|
24
43
|
/** hash of the collection's canonical JSON */
|
|
25
44
|
digest: string;
|
|
26
45
|
};
|
|
46
|
+
/**
|
|
47
|
+
* The proof of a dataset: the number of rows and the sum of every row's hash modulo 2^256, as 64
|
|
48
|
+
* lowercase hex digits. A sum does not depend on order, so a patch moves it by the hashes of the rows
|
|
49
|
+
* it replaces and adds, and neither side reads the whole collection to check a sync. It detects
|
|
50
|
+
* corruption, a missed apply and a half-applied patch. It is not a defence against a malicious
|
|
51
|
+
* server, which can send rows and a digest that agree.
|
|
52
|
+
*/
|
|
53
|
+
export type SetProof = {
|
|
54
|
+
kind: 'set';
|
|
55
|
+
/** number of rows in the collection */
|
|
56
|
+
count: number;
|
|
57
|
+
/** sum of the row hashes modulo 2^256, 64 hex digits */
|
|
58
|
+
digest: string;
|
|
59
|
+
};
|
|
27
60
|
/** the page of items a query selects, with the size of the filtered collection and the page count */
|
|
28
61
|
export type QueryResult = {
|
|
29
62
|
/** the items on this page */
|
|
@@ -52,8 +85,29 @@ export type Plain = Record<string, unknown>;
|
|
|
52
85
|
export declare function canonicalJson(value: unknown): string;
|
|
53
86
|
/** the proof a query route's `load` result carries for its collection */
|
|
54
87
|
export declare function datasetProof(items: readonly unknown[]): Promise<DatasetProof>;
|
|
55
|
-
/**
|
|
56
|
-
export declare
|
|
88
|
+
/** what a dataset's name may be; it never holds a `/`, which a row id uses to split name from key */
|
|
89
|
+
export declare const DATASET_NAME: RegExp;
|
|
90
|
+
/** the digest of an empty collection */
|
|
91
|
+
export declare const EMPTY_DIGEST: string;
|
|
92
|
+
/** the hash of one row: base64url SHA-256 of its key, a NUL, and its canonical JSON */
|
|
93
|
+
export declare function rowHash(key: string, row: unknown): Promise<string>;
|
|
94
|
+
/** `digest` plus the row hash `hash`, modulo 2^256 */
|
|
95
|
+
export declare function digestAdd(digest: string, hash: string): string;
|
|
96
|
+
/** `digest` minus the row hash `hash`, modulo 2^256 */
|
|
97
|
+
export declare function digestSub(digest: string, hash: string): string;
|
|
98
|
+
/** the set proof of rows by key; read every row once, so a patch should update it with {@link digestAdd} and {@link digestSub} */
|
|
99
|
+
export declare function setProof(rows: ReadonlyMap<string, unknown>): Promise<SetProof>;
|
|
100
|
+
/** whether `value` is shaped like a set proof */
|
|
101
|
+
export declare function isSetProof(value: unknown): value is SetProof;
|
|
102
|
+
/** reads the key of a row for a set proof; throws or returns a non-string for a row it cannot key */
|
|
103
|
+
export type KeyOf = (row: Plain) => string;
|
|
104
|
+
/** the {@link KeyOf} a route's `query.key` names: the item's own field, which must be a string */
|
|
105
|
+
export declare function keyField(schema: QuerySchema): KeyOf | undefined;
|
|
106
|
+
/**
|
|
107
|
+
* Whether `data` holds the collection at `schema.list` and a `proof` that matches it. A proof with
|
|
108
|
+
* `kind: 'set'` is checked with `keyOf`, which reads each row's key; without one it fails.
|
|
109
|
+
*/
|
|
110
|
+
export declare function verifyProof(schema: QuerySchema, data: unknown, keyOf?: KeyOf): Promise<boolean>;
|
|
57
111
|
/**
|
|
58
112
|
* Applies a query string to the collection in `data`: filters by equality, sorts stably (ties keep
|
|
59
113
|
* the stored order), and pages. Returns `null` for anything the schema does not declare, so the
|
|
@@ -67,7 +121,9 @@ export declare function evaluateQuery(schema: QuerySchema, data: unknown, search
|
|
|
67
121
|
* by the page's items and a `query` key added. Refuses when the proof fails or the query is not one
|
|
68
122
|
* the schema declares.
|
|
69
123
|
*/
|
|
70
|
-
export declare function shapeQuery(schema: QuerySchema, data: unknown, search: string): Promise<
|
|
124
|
+
export declare function shapeQuery(schema: QuerySchema, data: unknown, search: string, keyOf?: KeyOf): Promise<Shaped>;
|
|
125
|
+
/** what {@link shapeQuery} and {@link shapeRows} return */
|
|
126
|
+
export type Shaped = {
|
|
71
127
|
/** true when the query was answered from the stored collection */
|
|
72
128
|
ok: true;
|
|
73
129
|
/** the stored data with the page's items and the query view */
|
|
@@ -77,4 +133,9 @@ export declare function shapeQuery(schema: QuerySchema, data: unknown, search: s
|
|
|
77
133
|
ok: false;
|
|
78
134
|
/** why the query was refused */
|
|
79
135
|
reason: string;
|
|
80
|
-
}
|
|
136
|
+
};
|
|
137
|
+
/**
|
|
138
|
+
* {@link shapeQuery} without the proof check, for a collection the caller has already verified,
|
|
139
|
+
* such as the rows of a held dataset.
|
|
140
|
+
*/
|
|
141
|
+
export declare function shapeRows(schema: QuerySchema, data: unknown, search: string): Shaped;
|
package/dist/protocol/query.js
CHANGED
|
@@ -29,14 +29,106 @@ export function canonicalJson(value) {
|
|
|
29
29
|
export async function datasetProof(items) {
|
|
30
30
|
return { count: items.length, digest: await shellHash(canonicalJson(items)) };
|
|
31
31
|
}
|
|
32
|
-
/**
|
|
33
|
-
export
|
|
32
|
+
/** what a dataset's name may be; it never holds a `/`, which a row id uses to split name from key */
|
|
33
|
+
export const DATASET_NAME = /^[A-Za-z0-9._:-]{1,128}$/;
|
|
34
|
+
const MODULUS = 1n << 256n;
|
|
35
|
+
/** the digest of an empty collection */
|
|
36
|
+
export const EMPTY_DIGEST = '0'.repeat(64);
|
|
37
|
+
const DIGEST_FORM = /^[0-9a-f]{64}$/;
|
|
38
|
+
/** the hash of one row: base64url SHA-256 of its key, a NUL, and its canonical JSON */
|
|
39
|
+
export function rowHash(key, row) {
|
|
40
|
+
return shellHash(`${key}\0${canonicalJson(row)}`);
|
|
41
|
+
}
|
|
42
|
+
function hashValue(hash) {
|
|
43
|
+
if (!/^[A-Za-z0-9_-]{43}$/.test(hash))
|
|
44
|
+
throw new RangeError('not a row hash');
|
|
45
|
+
const binary = atob(hash.replace(/-/g, '+').replace(/_/g, '/') + '=');
|
|
46
|
+
let hex = '';
|
|
47
|
+
for (let i = 0; i < binary.length; i++)
|
|
48
|
+
hex += binary.charCodeAt(i).toString(16).padStart(2, '0');
|
|
49
|
+
return BigInt(`0x${hex}`);
|
|
50
|
+
}
|
|
51
|
+
function digestValue(digest) {
|
|
52
|
+
if (!DIGEST_FORM.test(digest))
|
|
53
|
+
throw new RangeError('not a set digest');
|
|
54
|
+
return BigInt(`0x${digest}`);
|
|
55
|
+
}
|
|
56
|
+
const digestText = (value) => (((value % MODULUS) + MODULUS) % MODULUS).toString(16).padStart(64, '0');
|
|
57
|
+
/** `digest` plus the row hash `hash`, modulo 2^256 */
|
|
58
|
+
export function digestAdd(digest, hash) {
|
|
59
|
+
return digestText(digestValue(digest) + hashValue(hash));
|
|
60
|
+
}
|
|
61
|
+
/** `digest` minus the row hash `hash`, modulo 2^256 */
|
|
62
|
+
export function digestSub(digest, hash) {
|
|
63
|
+
return digestText(digestValue(digest) - hashValue(hash));
|
|
64
|
+
}
|
|
65
|
+
/** the set proof of rows by key; read every row once, so a patch should update it with {@link digestAdd} and {@link digestSub} */
|
|
66
|
+
export async function setProof(rows) {
|
|
67
|
+
const hashes = await Promise.all([...rows].map(([key, row]) => rowHash(key, row)));
|
|
68
|
+
let sum = 0n;
|
|
69
|
+
for (const hash of hashes)
|
|
70
|
+
sum += hashValue(hash);
|
|
71
|
+
return { kind: 'set', count: rows.size, digest: digestText(sum) };
|
|
72
|
+
}
|
|
73
|
+
/** whether `value` is shaped like a set proof */
|
|
74
|
+
export function isSetProof(value) {
|
|
75
|
+
return (isPlain(value) &&
|
|
76
|
+
value['kind'] === 'set' &&
|
|
77
|
+
typeof value['count'] === 'number' &&
|
|
78
|
+
Number.isSafeInteger(value['count']) &&
|
|
79
|
+
value['count'] >= 0 &&
|
|
80
|
+
typeof value['digest'] === 'string' &&
|
|
81
|
+
DIGEST_FORM.test(value['digest']));
|
|
82
|
+
}
|
|
83
|
+
/** the {@link KeyOf} a route's `query.key` names: the item's own field, which must be a string */
|
|
84
|
+
export function keyField(schema) {
|
|
85
|
+
const field = schema.key;
|
|
86
|
+
if (field === undefined)
|
|
87
|
+
return undefined;
|
|
88
|
+
return (row) => {
|
|
89
|
+
const key = own(row, field);
|
|
90
|
+
if (typeof key !== 'string')
|
|
91
|
+
throw new TypeError(`${field} is not a string key`);
|
|
92
|
+
return key;
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
async function verifySet(items, proof, keyOf) {
|
|
96
|
+
if (proof.count !== items.length)
|
|
97
|
+
return false;
|
|
98
|
+
const rows = new Map();
|
|
99
|
+
for (const item of items) {
|
|
100
|
+
if (!isPlain(item))
|
|
101
|
+
return false;
|
|
102
|
+
let key;
|
|
103
|
+
try {
|
|
104
|
+
key = keyOf(item);
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return false;
|
|
108
|
+
}
|
|
109
|
+
if (typeof key !== 'string' || rows.has(key))
|
|
110
|
+
return false;
|
|
111
|
+
rows.set(key, item);
|
|
112
|
+
}
|
|
113
|
+
return (await setProof(rows)).digest === proof.digest;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Whether `data` holds the collection at `schema.list` and a `proof` that matches it. A proof with
|
|
117
|
+
* `kind: 'set'` is checked with `keyOf`, which reads each row's key; without one it fails.
|
|
118
|
+
*/
|
|
119
|
+
export async function verifyProof(schema, data, keyOf) {
|
|
34
120
|
if (!isPlain(data))
|
|
35
121
|
return false;
|
|
36
122
|
const items = own(data, schema.list);
|
|
37
123
|
const proof = own(data, 'proof');
|
|
38
124
|
if (!Array.isArray(items) || !isPlain(proof))
|
|
39
125
|
return false;
|
|
126
|
+
const kind = proof['kind'];
|
|
127
|
+
if (kind === 'set') {
|
|
128
|
+
return keyOf !== undefined && isSetProof(proof) && (await verifySet(items, proof, keyOf));
|
|
129
|
+
}
|
|
130
|
+
if (kind !== undefined && kind !== 'ordered')
|
|
131
|
+
return false;
|
|
40
132
|
if (proof['count'] !== items.length || typeof proof['digest'] !== 'string')
|
|
41
133
|
return false;
|
|
42
134
|
return (await shellHash(canonicalJson(items))) === proof['digest'];
|
|
@@ -141,9 +233,16 @@ export function evaluateQuery(schema, data, search) {
|
|
|
141
233
|
* by the page's items and a `query` key added. Refuses when the proof fails or the query is not one
|
|
142
234
|
* the schema declares.
|
|
143
235
|
*/
|
|
144
|
-
export async function shapeQuery(schema, data, search) {
|
|
145
|
-
if (!(await verifyProof(schema, data)))
|
|
236
|
+
export async function shapeQuery(schema, data, search, keyOf) {
|
|
237
|
+
if (!(await verifyProof(schema, data, keyOf)))
|
|
146
238
|
return { ok: false, reason: PROOF_MISMATCH };
|
|
239
|
+
return shapeRows(schema, data, search);
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* {@link shapeQuery} without the proof check, for a collection the caller has already verified,
|
|
243
|
+
* such as the rows of a held dataset.
|
|
244
|
+
*/
|
|
245
|
+
export function shapeRows(schema, data, search) {
|
|
147
246
|
const result = evaluateQuery(schema, data, search);
|
|
148
247
|
if (!result)
|
|
149
248
|
return { ok: false, reason: 'query is not one the route declares' };
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { BundleRows } from './bundle.js';
|
|
2
|
+
import type { SerializedRoute } from './route.js';
|
|
3
|
+
import type { CompiledTemplate } from './template/compile.js';
|
|
4
|
+
import type { ResourceWrite } from './write.js';
|
|
5
|
+
/** the id of the JSON script element that carries a ring in the first document */
|
|
6
|
+
export declare const RING_ELEMENT_ID = "spool-ring";
|
|
7
|
+
/** the id of the JSON script element that carries the declared writes of a page with no ring */
|
|
8
|
+
export declare const WRITES_ELEMENT_ID = "spool-writes";
|
|
9
|
+
/** the id of the element that carries a delta to a no-worker page that holds an older version */
|
|
10
|
+
export declare const DELTA_ELEMENT_ID = "spool-delta";
|
|
11
|
+
/** when a client fetches the pack and the worker: `second-view` is pack on view two, worker on view three */
|
|
12
|
+
export type BootstrapGate = 'first-view' | 'second-view';
|
|
13
|
+
/**
|
|
14
|
+
* whether a page registers the worker. `never` keeps every read in the page. `auto` registers it,
|
|
15
|
+
* except on WebKit for a page that carries a ring: WebKit checks the worker script on each
|
|
16
|
+
* navigation, which costs more than it saves. `always` registers it on WebKit too.
|
|
17
|
+
*/
|
|
18
|
+
export type WorkerMode = 'auto' | 'never' | 'always';
|
|
19
|
+
/**
|
|
20
|
+
* The records a first document carries so the second view needs no request: the entry page and
|
|
21
|
+
* its link neighbours up to a byte budget, the routes that render them, and where the full pack is.
|
|
22
|
+
* A ring is trusted as far as the document that carried it; the pack that follows is verified.
|
|
23
|
+
*/
|
|
24
|
+
export type Ring = {
|
|
25
|
+
protocol: 1;
|
|
26
|
+
/** the pack version the rows belong to */
|
|
27
|
+
version: number;
|
|
28
|
+
/** the set digest of the whole pack at that version */
|
|
29
|
+
digest: string;
|
|
30
|
+
/** absent on a gate page, where the boot script the ring names carries the routes and templates */
|
|
31
|
+
routes?: SerializedRoute[];
|
|
32
|
+
/** the compiled template of each route in `routes` that has one, keyed by route pattern; absent with `routes` */
|
|
33
|
+
templates?: Record<string, CompiledTemplate>;
|
|
34
|
+
/** rows by table, ascending by key */
|
|
35
|
+
tables: Record<string, BundleRows>;
|
|
36
|
+
/** true when the ring holds every row, so no pack is fetched */
|
|
37
|
+
complete: boolean;
|
|
38
|
+
bootstrap: BootstrapGate;
|
|
39
|
+
/** an `always` site writes `auto` here, so a client that predates `always` reads the ring as it does an `auto` one */
|
|
40
|
+
worker: 'auto' | 'never';
|
|
41
|
+
/** true when the site registers the worker on WebKit too (`workerMode: 'always'`); absent otherwise */
|
|
42
|
+
webkitWorker?: true;
|
|
43
|
+
/** where the pack is and how many bytes it is; absent when `complete` */
|
|
44
|
+
pack?: {
|
|
45
|
+
url: string;
|
|
46
|
+
bytes: number;
|
|
47
|
+
};
|
|
48
|
+
/** the worker script's lease in seconds; the worker's views inside one lease make the third; absent on an older ring */
|
|
49
|
+
lease?: number;
|
|
50
|
+
/**
|
|
51
|
+
* the boot script that carries the runtime, this pack, and on a gate page the routes and
|
|
52
|
+
* templates in one response; absent when the page loads the runtime by its own tag. A gate page
|
|
53
|
+
* adds `?r=<id>`, the id of those routes and templates, so a changed template is a new URL.
|
|
54
|
+
*/
|
|
55
|
+
boot?: string;
|
|
56
|
+
/** the declared resource writes, so a no-worker page can send them through `spool.fetch`; absent when none */
|
|
57
|
+
writes?: ResourceWrite[];
|
|
58
|
+
};
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** the id of the JSON script element that carries a ring in the first document */
|
|
2
|
+
export const RING_ELEMENT_ID = 'spool-ring';
|
|
3
|
+
/** the id of the JSON script element that carries the declared writes of a page with no ring */
|
|
4
|
+
export const WRITES_ELEMENT_ID = 'spool-writes';
|
|
5
|
+
/** the id of the element that carries a delta to a no-worker page that holds an older version */
|
|
6
|
+
export const DELTA_ELEMENT_ID = 'spool-delta';
|
package/dist/protocol/route.d.ts
CHANGED
|
@@ -1,7 +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
|
|
4
|
+
import { type QuerySchema } from './query.js';
|
|
5
5
|
import { type CompiledTemplate, type TemplateSource } from './template/compile.js';
|
|
6
6
|
import type { Mode } from './view.js';
|
|
7
7
|
/**
|
|
@@ -47,7 +47,7 @@ export type RouteContext = {
|
|
|
47
47
|
params: Params;
|
|
48
48
|
/** the principal the app resolved for this request; null when none */
|
|
49
49
|
identity: Identity | null;
|
|
50
|
-
} & Pick<Collector, 'record' | 'projection'>;
|
|
50
|
+
} & Pick<Collector, 'record' | 'projection' | 'row'>;
|
|
51
51
|
/** public routes default to 15 minutes soft, principal routes to 5 minutes hard */
|
|
52
52
|
export declare const DEFAULT_FRESHNESS: Record<Scope, Freshness>;
|
|
53
53
|
/**
|
|
@@ -66,6 +66,8 @@ export type CatalogueGuess = {
|
|
|
66
66
|
export type RouteCommon = {
|
|
67
67
|
/** public or principal; public when absent */
|
|
68
68
|
scope?: Scope;
|
|
69
|
+
/** `principal` is the same as `scope: 'principal'`; a conflicting scope is refused */
|
|
70
|
+
auth?: 'principal';
|
|
69
71
|
/** overrides the scope's default maxStale and mode */
|
|
70
72
|
freshness?: Partial<Freshness>;
|
|
71
73
|
/** keep the artifact across worker restarts; default true */
|
|
@@ -78,7 +80,7 @@ export type RouteCommon = {
|
|
|
78
80
|
sync?: SyncRule;
|
|
79
81
|
/** tags the artifact is built from; records and projections the load registers are added */
|
|
80
82
|
depends?(ctx: RouteContext): readonly string[] | Promise<readonly string[]>;
|
|
81
|
-
/** a principal route's at-rest key; default `session` */
|
|
83
|
+
/** a principal route's at-rest key; default `persistent`, `session` for a shared device */
|
|
82
84
|
retention?: Retention;
|
|
83
85
|
/** overrides the provisioning priors for this route when the server decides whether to ship it */
|
|
84
86
|
provision?: {
|
|
@@ -86,6 +88,8 @@ export type RouteCommon = {
|
|
|
86
88
|
reuse?: number;
|
|
87
89
|
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
88
90
|
futureViews?: number;
|
|
91
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
92
|
+
maxBytes?: number;
|
|
89
93
|
};
|
|
90
94
|
/**
|
|
91
95
|
* Pages a device on this route may open next, each with the share of devices expected to
|
|
@@ -112,14 +116,37 @@ export type QueryRoute = {
|
|
|
112
116
|
*/
|
|
113
117
|
query?: QuerySchema;
|
|
114
118
|
};
|
|
119
|
+
/**
|
|
120
|
+
* The held dataset row a template, projection or data route renders. The row is the one whose key
|
|
121
|
+
* is the value of the route param `key`. A template or renderer receives `{ params, row }`; a data
|
|
122
|
+
* route answers with the row's JSON.
|
|
123
|
+
*/
|
|
124
|
+
export type Family = {
|
|
125
|
+
/** the dataset the row is read from; it must be held on the device */
|
|
126
|
+
dataset: string;
|
|
127
|
+
/** the route param whose value is the row's key, such as `id` for `/courses/:id` */
|
|
128
|
+
key: string;
|
|
129
|
+
};
|
|
130
|
+
/** the fields a template or projection route takes; a family route needs no `load` */
|
|
131
|
+
export type FamilyRoute = {
|
|
132
|
+
/** binds the route to one held row; `load` is then optional */
|
|
133
|
+
family: Family;
|
|
134
|
+
/** `document` leaves this family's links and forms to the browser; absent, the page renders them */
|
|
135
|
+
navigation?: 'document';
|
|
136
|
+
/** returns the row the key names, which the server builds its own artifact from */
|
|
137
|
+
load?(ctx: RouteContext): unknown;
|
|
138
|
+
} | {
|
|
139
|
+
/** absent, so `load` returns the JSON the route renders */
|
|
140
|
+
family?: undefined;
|
|
141
|
+
/** returns the JSON the template or renderer receives */
|
|
142
|
+
load(ctx: RouteContext): unknown;
|
|
143
|
+
};
|
|
115
144
|
/** a route answered by rendering stored JSON through a compiled template */
|
|
116
|
-
export type TemplateRoute = RouteCommon & QueryRoute & {
|
|
145
|
+
export type TemplateRoute = RouteCommon & QueryRoute & FamilyRoute & {
|
|
117
146
|
/** renders stored JSON through the template */
|
|
118
147
|
strategy: 'template';
|
|
119
148
|
/** the template source, compiled once when the route is defined */
|
|
120
149
|
template: TemplateSource;
|
|
121
|
-
/** returns the JSON the template renders */
|
|
122
|
-
load(ctx: RouteContext): unknown;
|
|
123
150
|
};
|
|
124
151
|
/**
|
|
125
152
|
* A route for a file the application serves as is, such as a page or an asset with fixed bytes.
|
|
@@ -144,21 +171,26 @@ export type StaticRoute = Omit<RouteCommon, 'scope' | 'persist' | 'mode' | 'rete
|
|
|
144
171
|
* `@drupflare/spool/sw` takes a renderer keyed by this pattern. Without one the worker refuses the
|
|
145
172
|
* local view and the network answers.
|
|
146
173
|
*/
|
|
147
|
-
export type ProjectionRoute = RouteCommon & QueryRoute & {
|
|
174
|
+
export type ProjectionRoute = RouteCommon & QueryRoute & FamilyRoute & {
|
|
148
175
|
/** renders stored JSON with the renderer the bundled worker holds */
|
|
149
176
|
strategy: 'projection';
|
|
150
|
-
/** returns the JSON the renderer receives */
|
|
151
|
-
load(ctx: RouteContext): unknown;
|
|
152
177
|
};
|
|
153
178
|
/**
|
|
154
179
|
* A route for a JSON read. The worker answers a GET (not a navigation) from the stored value with
|
|
155
|
-
* `JSON.stringify`, so the application's own handler has to return the same JSON `load` does.
|
|
180
|
+
* `JSON.stringify`, so the application's own handler has to return the same JSON `load` does. With
|
|
181
|
+
* `family` the answer is the held row; with `origin` the GET may come from that other origin, and
|
|
182
|
+
* `query.dataset` without a `family` makes the collection of the dataset.
|
|
156
183
|
*/
|
|
157
|
-
export type DataRoute = RouteCommon & QueryRoute & {
|
|
184
|
+
export type DataRoute = RouteCommon & QueryRoute & FamilyRoute & {
|
|
158
185
|
/** answers a GET with the stored JSON */
|
|
159
186
|
strategy: 'data';
|
|
160
|
-
/**
|
|
161
|
-
|
|
187
|
+
/**
|
|
188
|
+
* the API origin a cross-origin family answers for; absent for the page's own origin. A public
|
|
189
|
+
* route answers from the public replica. A principal route (`scope` or `auth`) answers only a
|
|
190
|
+
* GET with an `Authorization` header, only from the signed-in partition, and stops when the
|
|
191
|
+
* partition is wiped; every other request goes to the API.
|
|
192
|
+
*/
|
|
193
|
+
origin?: string;
|
|
162
194
|
/** the content type of the local answer; default `application/json` */
|
|
163
195
|
contentType?: string;
|
|
164
196
|
};
|
|
@@ -192,6 +224,8 @@ export type Route = {
|
|
|
192
224
|
reuse?: number;
|
|
193
225
|
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
194
226
|
futureViews?: number;
|
|
227
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
228
|
+
maxBytes?: number;
|
|
195
229
|
};
|
|
196
230
|
/** the compiled template of a template route */
|
|
197
231
|
template?: CompiledTemplate;
|
|
@@ -201,6 +235,14 @@ export type Route = {
|
|
|
201
235
|
documentBytes?: number;
|
|
202
236
|
/** query strings the worker answers from the stored collection */
|
|
203
237
|
query?: QuerySchema;
|
|
238
|
+
/** the held dataset row the route renders, when it declares a family */
|
|
239
|
+
family?: Family;
|
|
240
|
+
/** `document` when the page leaves this family's links and forms to the browser */
|
|
241
|
+
navigation?: 'document';
|
|
242
|
+
/** the API origin a cross-origin data family answers for */
|
|
243
|
+
origin?: string;
|
|
244
|
+
/** `false` for a family route with no load, which has no artifact to provision */
|
|
245
|
+
provisionable?: false;
|
|
204
246
|
/** tags the artifact is built from; a change to one invalidates it */
|
|
205
247
|
depends(ctx: RouteContext): readonly string[] | Promise<readonly string[]>;
|
|
206
248
|
/** returns the data the artifact is built from */
|
|
@@ -234,6 +276,14 @@ export type SerializedRoute = {
|
|
|
234
276
|
catalogue?: true;
|
|
235
277
|
/** the query strings the worker answers from the stored collection of a public route */
|
|
236
278
|
query?: QuerySchema;
|
|
279
|
+
/** the held dataset row the page renders; the worker answers from it with no request */
|
|
280
|
+
family?: Family;
|
|
281
|
+
/** `document` when the page leaves this family's links and forms to the browser */
|
|
282
|
+
navigation?: 'document';
|
|
283
|
+
/** the API origin a cross-origin data family answers for */
|
|
284
|
+
origin?: string;
|
|
285
|
+
/** `false` for a family route with no load, which has no artifact to provision */
|
|
286
|
+
provisionable?: false;
|
|
237
287
|
};
|
|
238
288
|
/**
|
|
239
289
|
* Declares a route. Validates the pattern and the freshness contract, compiles a template, and
|