@drupflare/spool 0.3.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 +263 -41
- 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/entry.js +33 -1
- package/dist/client/register.d.ts +23 -1
- package/dist/client/register.js +53 -7
- 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 +1 -0
- package/dist/protocol/envelope.js +2 -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.d.ts +3 -0
- package/dist/protocol/index.js +3 -0
- 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/route.d.ts +6 -2
- package/dist/protocol/route.js +31 -3
- package/dist/protocol/write.d.ts +146 -0
- package/dist/protocol/write.js +101 -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 +2 -0
- package/dist/report/index.js +2 -0
- package/dist/report/inputs.d.ts +97 -0
- package/dist/report/inputs.js +133 -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 +3 -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/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 +2 -0
- package/dist/server/index.js +2 -0
- package/dist/server/spool.d.ts +20 -0
- package/dist/server/spool.js +126 -18
- 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 +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/runtime.d.ts +43 -2
- package/dist/sw/runtime.js +340 -24
- 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 +3 -2
|
@@ -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' };
|
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
|
/**
|
|
@@ -86,6 +86,8 @@ export type RouteCommon = {
|
|
|
86
86
|
reuse?: number;
|
|
87
87
|
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
88
88
|
futureViews?: number;
|
|
89
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
90
|
+
maxBytes?: number;
|
|
89
91
|
};
|
|
90
92
|
/**
|
|
91
93
|
* Pages a device on this route may open next, each with the share of devices expected to
|
|
@@ -192,6 +194,8 @@ export type Route = {
|
|
|
192
194
|
reuse?: number;
|
|
193
195
|
/** later views one provisioned artifact is expected to serve; the server's prior when absent */
|
|
194
196
|
futureViews?: number;
|
|
197
|
+
/** refuses an artifact whose stored JSON is over this many bytes; no budget when absent */
|
|
198
|
+
maxBytes?: number;
|
|
195
199
|
};
|
|
196
200
|
/** the compiled template of a template route */
|
|
197
201
|
template?: CompiledTemplate;
|
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,6 +61,30 @@ 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
|
}
|
|
64
90
|
/**
|
|
@@ -149,12 +175,14 @@ export function defineRoute(pattern, declaration) {
|
|
|
149
175
|
}
|
|
150
176
|
const query = declaration.query;
|
|
151
177
|
if (query !== undefined) {
|
|
152
|
-
if (scope !== 'public')
|
|
153
|
-
return bad(pattern, 'query applies to a public route');
|
|
154
178
|
if (!['template', 'projection', 'data'].includes(declaration.strategy)) {
|
|
155
179
|
return bad(pattern, `a ${declaration.strategy} route cannot declare query`);
|
|
156
180
|
}
|
|
157
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
|
+
}
|
|
158
186
|
}
|
|
159
187
|
if (declaration.strategy === 'template') {
|
|
160
188
|
if (!declaration.template)
|
|
@@ -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 {};
|