@drupflare/spool 0.4.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 +206 -1756
- 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 +91 -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 +11 -1
- package/dist/client/register.js +19 -8
- 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 +65 -1
- package/dist/protocol/config.js +28 -0
- package/dist/protocol/dataset.d.ts +6 -0
- package/dist/protocol/dataset.js +6 -0
- package/dist/protocol/envelope.d.ts +33 -1
- package/dist/protocol/envelope.js +15 -1
- package/dist/protocol/errors.d.ts +1 -1
- package/dist/protocol/index-rows.d.ts +22 -0
- package/dist/protocol/index-rows.js +53 -0
- package/dist/protocol/index.d.ts +2 -0
- package/dist/protocol/index.js +2 -0
- package/dist/protocol/normalise.d.ts +4 -4
- package/dist/protocol/normalise.js +9 -5
- package/dist/protocol/ring.d.ts +58 -0
- package/dist/protocol/ring.js +6 -0
- package/dist/protocol/route.d.ts +57 -11
- package/dist/protocol/route.js +95 -3
- 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 +92 -4
- package/dist/protocol/write.js +251 -9
- 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/demand.d.ts +49 -0
- package/dist/report/demand.js +60 -0
- package/dist/report/economics.d.ts +55 -0
- package/dist/report/economics.js +189 -0
- package/dist/report/headline.d.ts +158 -0
- package/dist/report/headline.js +473 -0
- package/dist/report/index.d.ts +2 -0
- package/dist/report/index.js +2 -0
- package/dist/report/inputs.d.ts +79 -0
- package/dist/report/inputs.js +115 -0
- package/dist/report/measurement.d.ts +1 -1
- package/dist/report/measurement.js +5 -1
- package/dist/report/traffic.d.ts +8 -0
- package/dist/report/traffic.js +7 -0
- package/dist/server/bundle.d.ts +55 -0
- package/dist/server/bundle.js +172 -0
- package/dist/server/dataset.d.ts +8 -2
- package/dist/server/dataset.js +51 -4
- package/dist/server/embedded.d.ts +7 -3
- package/dist/server/embedded.js +7 -3
- package/dist/server/index.d.ts +5 -1
- package/dist/server/index.js +5 -1
- 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 +139 -4
- package/dist/server/spool.js +457 -28
- 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 +23 -1
- package/dist/server/write.js +96 -0
- package/dist/stores/durable-object.d.ts +46 -0
- package/dist/stores/durable-object.js +114 -0
- package/dist/sw/analytics.d.ts +1 -1
- package/dist/sw/analytics.js +2 -2
- package/dist/sw/coverage.d.ts +6 -0
- package/dist/sw/coverage.js +34 -0
- package/dist/sw/family.d.ts +15 -0
- package/dist/sw/family.js +48 -0
- package/dist/sw/idb.d.ts +2 -0
- package/dist/sw/idb.js +2 -2
- 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/policy.d.ts +2 -0
- package/dist/sw/policy.js +11 -0
- package/dist/sw/probe.d.ts +16 -0
- package/dist/sw/probe.js +25 -0
- package/dist/sw/router.d.ts +3 -2
- package/dist/sw/router.js +15 -2
- package/dist/sw/runtime.d.ts +48 -1
- package/dist/sw/runtime.js +548 -68
- package/dist/sw/scheduler.d.ts +6 -1
- package/dist/sw/scheduler.js +22 -5
- package/dist/sw/write.d.ts +41 -1
- package/dist/sw/write.js +188 -5
- 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 +64 -4
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The view times a page keeps for the lease window, as the comma-separated text `spool:stamps` holds:
|
|
3
|
+
* the stored ones a lease period still covers, then `now`, the last three. A stamp at or after `now`,
|
|
4
|
+
* a full lease old, zero or not a number is outside. Not re-exported from the protocol index.
|
|
5
|
+
*/
|
|
6
|
+
export function viewStamps(stored, now, leaseMs) {
|
|
7
|
+
return [
|
|
8
|
+
...stored
|
|
9
|
+
.split(',')
|
|
10
|
+
.filter(Boolean)
|
|
11
|
+
.map(Number)
|
|
12
|
+
.filter((t) => t >= 0 && t <= now && now - t < leaseMs),
|
|
13
|
+
now
|
|
14
|
+
].slice(-3);
|
|
15
|
+
}
|
package/dist/protocol/write.d.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type { DatasetRow } from './dataset.js';
|
|
2
|
+
import { type Identity, type Route } from './route.js';
|
|
2
3
|
/** the header that names one flush of one key; a retry of the same flush sends the same id */
|
|
3
4
|
export declare const WRITE_HEADERS: {
|
|
4
5
|
readonly id: "spool-write-id";
|
|
6
|
+
readonly digest: "spool-write-digest";
|
|
5
7
|
};
|
|
6
8
|
/** a write class name is 1 to 64 of letters, digits, `_` and `-` */
|
|
7
9
|
export declare const WRITE_NAME: RegExp;
|
|
@@ -112,6 +114,12 @@ export type WriteDeclaration = {
|
|
|
112
114
|
maxBytes: number;
|
|
113
115
|
/** the most queued keys of this class one partition holds on a device */
|
|
114
116
|
maxPending: number;
|
|
117
|
+
/**
|
|
118
|
+
* The longest a queued write of this class may wait before the worker flushes it. Unset keeps the
|
|
119
|
+
* flush at the next network moment, an explicit flush or a page hide. Set, the first queued write
|
|
120
|
+
* starts a deadline, and the flush at it sends every queued record: one request per key.
|
|
121
|
+
*/
|
|
122
|
+
maxDelayMs?: number;
|
|
115
123
|
};
|
|
116
124
|
/** a validated write class */
|
|
117
125
|
export type Write = Readonly<WriteDeclaration & {
|
|
@@ -122,12 +130,15 @@ export type WriteConfig = {
|
|
|
122
130
|
name: string;
|
|
123
131
|
maxBytes: number;
|
|
124
132
|
maxPending: number;
|
|
133
|
+
maxDelayMs?: number;
|
|
125
134
|
};
|
|
126
135
|
/**
|
|
127
|
-
* Declares a write class
|
|
128
|
-
*
|
|
129
|
-
*
|
|
136
|
+
* Declares a write class, or with a route pattern a resource write: the request reaches the server
|
|
137
|
+
* once and the device applies the rows the server reports. A class throws `bad-write` for a public
|
|
138
|
+
* scope, a kind other than `last-value`, a name or pattern that does not parse, a missing function or
|
|
139
|
+
* a limit that is not a positive integer within its cap.
|
|
130
140
|
*/
|
|
141
|
+
export declare function defineWrite(pattern: string, declaration: ResourceWriteDeclaration): ResourceWrite;
|
|
131
142
|
export declare function defineWrite(declaration: WriteDeclaration): Write;
|
|
132
143
|
/** the config entry the worker gets for a class */
|
|
133
144
|
export declare function serializeWrite(write: Write): WriteConfig;
|
|
@@ -143,4 +154,81 @@ export declare const ifMatch: (version: string) => string;
|
|
|
143
154
|
export declare function readIfMatch(header: string | null): string | null;
|
|
144
155
|
/** a random write id: 22 base64url characters of 128 random bits */
|
|
145
156
|
export declare function newWriteId(): string;
|
|
157
|
+
/** the methods a resource write may declare */
|
|
158
|
+
export declare const RESOURCE_METHODS: readonly ["POST", "PUT", "PATCH", "DELETE"];
|
|
159
|
+
/** how a declared write changes the held rows; `invalidate` marks the touched rows stale */
|
|
160
|
+
export declare const RESOURCE_APPLY: readonly ["response", "merge", "delete", "invalidate"];
|
|
161
|
+
export type ResourceMethod = (typeof RESOURCE_METHODS)[number];
|
|
162
|
+
export type ResourceApplyMode = (typeof RESOURCE_APPLY)[number];
|
|
163
|
+
/**
|
|
164
|
+
* The change a declared write makes to a row when it is not one of the modes. `set` writes a JSON
|
|
165
|
+
* constant, or the value at a dotted path of the request body when it is `{ body: '<path>' }`. `inc`
|
|
166
|
+
* adds a number to a numeric field, a missing field counting as 0. `unset` removes fields.
|
|
167
|
+
*/
|
|
168
|
+
export type ResourcePatch = {
|
|
169
|
+
set?: Readonly<Record<string, unknown>>;
|
|
170
|
+
inc?: Readonly<Record<string, number>>;
|
|
171
|
+
unset?: readonly string[];
|
|
172
|
+
};
|
|
173
|
+
export type ResourceApply = ResourceApplyMode | ResourcePatch;
|
|
174
|
+
/** what `defineWrite(pattern, ...)` takes */
|
|
175
|
+
export type ResourceWriteDeclaration = {
|
|
176
|
+
method: ResourceMethod;
|
|
177
|
+
/** the dataset the write changes; the server reports the changed rows of each public dataset */
|
|
178
|
+
dataset: string;
|
|
179
|
+
/** the route param whose value is the row's key */
|
|
180
|
+
key: string;
|
|
181
|
+
apply: ResourceApply;
|
|
182
|
+
/** the GET families the write changes, as route patterns */
|
|
183
|
+
updates: readonly string[];
|
|
184
|
+
/** the origin the write goes to when it is not the page's own; absent means same-origin only */
|
|
185
|
+
origin?: string;
|
|
186
|
+
};
|
|
187
|
+
/** a validated resource write; the worker gets these in its config */
|
|
188
|
+
export type ResourceWrite = Readonly<ResourceWriteDeclaration & {
|
|
189
|
+
pattern: string;
|
|
190
|
+
}>;
|
|
191
|
+
/** what `defineResource` returns: the item family and the writes that change it */
|
|
192
|
+
export type Resource = {
|
|
193
|
+
pattern: string;
|
|
194
|
+
dataset: string;
|
|
195
|
+
key: string;
|
|
196
|
+
routes: Route[];
|
|
197
|
+
writes: ResourceWrite[];
|
|
198
|
+
};
|
|
199
|
+
/**
|
|
200
|
+
* The row a declared patch makes of `row` for a request `body`. It is pure, so the worker and any caller
|
|
201
|
+
* get the same row. Returns undefined when a body path names no value or an `inc` field is not a number.
|
|
202
|
+
*/
|
|
203
|
+
export declare function applyPatch(row: DatasetRow, body: unknown, patch: ResourcePatch): DatasetRow | undefined;
|
|
204
|
+
/**
|
|
205
|
+
* Declares a resource. `GET <pattern>` is the collection of the dataset, with no query string; a query
|
|
206
|
+
* string is not answered locally. `GET <pattern>/:key` is a data family of the dataset; `POST <pattern>`
|
|
207
|
+
* inserts; `PUT` and `PATCH <pattern>/:key` replace and update; `DELETE <pattern>/:key` removes. Any
|
|
208
|
+
* `POST`, `PUT`, `PATCH` or `DELETE` of `<pattern>/:key/:action` is a write on that item. Every write
|
|
209
|
+
* updates the collection and the item.
|
|
210
|
+
*/
|
|
211
|
+
export declare function defineResource(pattern: string, declaration: {
|
|
212
|
+
dataset: string;
|
|
213
|
+
key: string;
|
|
214
|
+
origin?: string;
|
|
215
|
+
}): Resource;
|
|
216
|
+
/**
|
|
217
|
+
* The resource write a request matches: its method, a pattern that matches its path, and its origin.
|
|
218
|
+
* A write with no origin matches only the page's own origin; one with an origin matches that origin.
|
|
219
|
+
*/
|
|
220
|
+
export declare function writeFor(writes: readonly ResourceWrite[], method: string, url: URL, pageOrigin: string): ResourceWrite | undefined;
|
|
221
|
+
/**
|
|
222
|
+
* For each write a page made, the resource it couples to and the GET families it updates. A write that
|
|
223
|
+
* couples to no resource reports `resource: null` and no families; that is the uncovered case.
|
|
224
|
+
*/
|
|
225
|
+
export declare function couplingReport(writes: readonly {
|
|
226
|
+
method: string;
|
|
227
|
+
url: string;
|
|
228
|
+
}[], resources: readonly Resource[], pageOrigin: string): Array<{
|
|
229
|
+
method: string;
|
|
230
|
+
url: string;
|
|
231
|
+
resource: string | null;
|
|
232
|
+
families: string[];
|
|
233
|
+
}>;
|
|
146
234
|
export {};
|
package/dist/protocol/write.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { ProtocolError } from './errors.js';
|
|
2
|
-
import { checkPattern } from './pattern.js';
|
|
2
|
+
import { checkPattern, matchPattern } from './pattern.js';
|
|
3
|
+
import { defineRoute } from './route.js';
|
|
3
4
|
/** 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
|
+
export const WRITE_HEADERS = { id: 'spool-write-id', digest: 'spool-write-digest' };
|
|
5
6
|
/** a write class name is 1 to 64 of letters, digits, `_` and `-` */
|
|
6
7
|
export const WRITE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
|
|
7
8
|
const VERSION = /^[A-Za-z0-9._:~-]{1,128}$/;
|
|
@@ -35,12 +36,12 @@ export const WRITE_STATUS = {
|
|
|
35
36
|
function bad(name, message) {
|
|
36
37
|
throw new ProtocolError('bad-write', `${name}: ${message}`);
|
|
37
38
|
}
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
39
|
+
export function defineWrite(first, second) {
|
|
40
|
+
if (typeof first === 'string')
|
|
41
|
+
return defineResourceWrite(first, second);
|
|
42
|
+
return defineQueuedWrite(first);
|
|
43
|
+
}
|
|
44
|
+
function defineQueuedWrite(declaration) {
|
|
44
45
|
const name = String(declaration?.name);
|
|
45
46
|
if (typeof declaration?.name !== 'string' || !WRITE_NAME.test(declaration.name)) {
|
|
46
47
|
return bad(name, 'a write name is 1 to 64 of letters, digits, _ and -');
|
|
@@ -67,11 +68,16 @@ export function defineWrite(declaration) {
|
|
|
67
68
|
return bad(name, `${limit} must be an integer from 1 to ${caps[limit]}`);
|
|
68
69
|
}
|
|
69
70
|
}
|
|
71
|
+
const delay = declaration.maxDelayMs;
|
|
72
|
+
if (delay !== undefined && (!Number.isSafeInteger(delay) || delay < 0)) {
|
|
73
|
+
return bad(name, 'maxDelayMs must be a non-negative integer');
|
|
74
|
+
}
|
|
70
75
|
return Object.freeze({ ...declaration, kind: 'last-value' });
|
|
71
76
|
}
|
|
72
77
|
/** the config entry the worker gets for a class */
|
|
73
78
|
export function serializeWrite(write) {
|
|
74
|
-
|
|
79
|
+
const config = { name: write.name, maxBytes: write.maxBytes, maxPending: write.maxPending };
|
|
80
|
+
return write.maxDelayMs === undefined ? config : { ...config, maxDelayMs: write.maxDelayMs };
|
|
75
81
|
}
|
|
76
82
|
/** whether `key` is a key the wire carries: a non-empty string of at most {@link MAX_WRITE_KEY} characters without NUL */
|
|
77
83
|
export function isWriteKey(key) {
|
|
@@ -99,3 +105,239 @@ export function newWriteId() {
|
|
|
99
105
|
binary += String.fromCharCode(byte);
|
|
100
106
|
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
|
|
101
107
|
}
|
|
108
|
+
/** the methods a resource write may declare */
|
|
109
|
+
export const RESOURCE_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'];
|
|
110
|
+
/** how a declared write changes the held rows; `invalidate` marks the touched rows stale */
|
|
111
|
+
export const RESOURCE_APPLY = ['response', 'merge', 'delete', 'invalidate'];
|
|
112
|
+
function defineResourceWrite(pattern, declaration) {
|
|
113
|
+
checkPattern(pattern);
|
|
114
|
+
if (!declaration)
|
|
115
|
+
return bad(pattern, 'a resource write needs a declaration');
|
|
116
|
+
if (!RESOURCE_METHODS.includes(declaration.method)) {
|
|
117
|
+
return bad(pattern, `method must be one of ${RESOURCE_METHODS.join(', ')}`);
|
|
118
|
+
}
|
|
119
|
+
if (typeof declaration.dataset !== 'string' || declaration.dataset === '') {
|
|
120
|
+
return bad(pattern, 'dataset must be a dataset name');
|
|
121
|
+
}
|
|
122
|
+
if (typeof declaration.key !== 'string' || declaration.key === '') {
|
|
123
|
+
return bad(pattern, 'key must be a param name');
|
|
124
|
+
}
|
|
125
|
+
const apply = declaration.apply;
|
|
126
|
+
if (isObject(apply))
|
|
127
|
+
checkPatch(pattern, apply);
|
|
128
|
+
else if (typeof apply !== 'string' || !RESOURCE_APPLY.includes(apply)) {
|
|
129
|
+
return bad(pattern, `apply must be one of ${RESOURCE_APPLY.join(', ')}, or a patch`);
|
|
130
|
+
}
|
|
131
|
+
if (!Array.isArray(declaration.updates)) {
|
|
132
|
+
return bad(pattern, 'updates must be a list of route patterns');
|
|
133
|
+
}
|
|
134
|
+
for (const update of declaration.updates)
|
|
135
|
+
checkPattern(update);
|
|
136
|
+
if (declaration.origin !== undefined)
|
|
137
|
+
checkOrigin(pattern, declaration.origin);
|
|
138
|
+
return Object.freeze({ ...declaration, updates: [...declaration.updates], pattern });
|
|
139
|
+
}
|
|
140
|
+
const PATCH_KEYS = ['set', 'inc', 'unset'];
|
|
141
|
+
const UNSAFE_FIELDS = ['__proto__'];
|
|
142
|
+
const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
143
|
+
const isBodyRef = (value) => isObject(value) && Object.keys(value).length === 1 && typeof value.body === 'string';
|
|
144
|
+
function isJson(value) {
|
|
145
|
+
if (value === null || typeof value === 'string' || typeof value === 'boolean')
|
|
146
|
+
return true;
|
|
147
|
+
if (typeof value === 'number')
|
|
148
|
+
return Number.isFinite(value);
|
|
149
|
+
if (Array.isArray(value))
|
|
150
|
+
return value.every(isJson);
|
|
151
|
+
return isObject(value) && Object.values(value).every(isJson);
|
|
152
|
+
}
|
|
153
|
+
function checkField(pattern, field) {
|
|
154
|
+
if (typeof field !== 'string' ||
|
|
155
|
+
field === '' ||
|
|
156
|
+
field.includes('.') ||
|
|
157
|
+
UNSAFE_FIELDS.includes(field)) {
|
|
158
|
+
bad(pattern, `patch field "${String(field)}" must be a field name with no dot`);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
function checkPatch(pattern, patch) {
|
|
162
|
+
const keys = Object.keys(patch);
|
|
163
|
+
if (keys.length === 0)
|
|
164
|
+
bad(pattern, 'a patch needs set, inc or unset');
|
|
165
|
+
for (const key of keys) {
|
|
166
|
+
if (!PATCH_KEYS.includes(key))
|
|
167
|
+
bad(pattern, `patch key "${key}" is not set, inc or unset`);
|
|
168
|
+
}
|
|
169
|
+
if (patch.set !== undefined) {
|
|
170
|
+
if (!isObject(patch.set))
|
|
171
|
+
bad(pattern, 'set must be an object');
|
|
172
|
+
for (const [field, value] of Object.entries(patch.set)) {
|
|
173
|
+
checkField(pattern, field);
|
|
174
|
+
if (isBodyRef(value)) {
|
|
175
|
+
for (const segment of value.body.split('.'))
|
|
176
|
+
checkField(pattern, segment);
|
|
177
|
+
}
|
|
178
|
+
else if (!isJson(value)) {
|
|
179
|
+
bad(pattern, `set "${field}" must be a JSON value or { body: "<path>" }`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
if (patch.inc !== undefined) {
|
|
184
|
+
if (!isObject(patch.inc))
|
|
185
|
+
bad(pattern, 'inc must be an object');
|
|
186
|
+
for (const [field, amount] of Object.entries(patch.inc)) {
|
|
187
|
+
checkField(pattern, field);
|
|
188
|
+
if (typeof amount !== 'number' || !Number.isFinite(amount)) {
|
|
189
|
+
bad(pattern, `inc "${field}" must be a finite number`);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
if (patch.unset !== undefined) {
|
|
194
|
+
if (!Array.isArray(patch.unset))
|
|
195
|
+
bad(pattern, 'unset must be a list of field names');
|
|
196
|
+
for (const field of patch.unset)
|
|
197
|
+
checkField(pattern, field);
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
/** the JSON value at a dotted path of the body, or undefined when a segment is missing or not an object */
|
|
201
|
+
function readBodyPath(body, path) {
|
|
202
|
+
let at = body;
|
|
203
|
+
for (const segment of path.split('.')) {
|
|
204
|
+
if (!isObject(at) || !Object.prototype.hasOwnProperty.call(at, segment))
|
|
205
|
+
return undefined;
|
|
206
|
+
at = at[segment];
|
|
207
|
+
}
|
|
208
|
+
return at;
|
|
209
|
+
}
|
|
210
|
+
/**
|
|
211
|
+
* The row a declared patch makes of `row` for a request `body`. It is pure, so the worker and any caller
|
|
212
|
+
* get the same row. Returns undefined when a body path names no value or an `inc` field is not a number.
|
|
213
|
+
*/
|
|
214
|
+
export function applyPatch(row, body, patch) {
|
|
215
|
+
const next = { ...row };
|
|
216
|
+
for (const [field, value] of Object.entries(patch.set ?? {})) {
|
|
217
|
+
if (!isBodyRef(value)) {
|
|
218
|
+
next[field] = structuredClone(value);
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
const found = readBodyPath(body, value.body);
|
|
222
|
+
if (found === undefined)
|
|
223
|
+
return undefined;
|
|
224
|
+
next[field] = found;
|
|
225
|
+
}
|
|
226
|
+
for (const [field, amount] of Object.entries(patch.inc ?? {})) {
|
|
227
|
+
const held = next[field] === undefined ? 0 : next[field];
|
|
228
|
+
if (typeof held !== 'number')
|
|
229
|
+
return undefined;
|
|
230
|
+
next[field] = held + amount;
|
|
231
|
+
}
|
|
232
|
+
for (const field of patch.unset ?? [])
|
|
233
|
+
delete next[field];
|
|
234
|
+
return next;
|
|
235
|
+
}
|
|
236
|
+
function checkOrigin(pattern, origin) {
|
|
237
|
+
if (typeof origin !== 'string')
|
|
238
|
+
return bad(pattern, 'origin must be a string');
|
|
239
|
+
let parsed;
|
|
240
|
+
try {
|
|
241
|
+
parsed = new URL(origin);
|
|
242
|
+
}
|
|
243
|
+
catch {
|
|
244
|
+
return bad(pattern, `origin "${origin}" is not a URL`);
|
|
245
|
+
}
|
|
246
|
+
if (!['http:', 'https:'].includes(parsed.protocol) || parsed.origin !== origin) {
|
|
247
|
+
return bad(pattern, `origin "${origin}" must be an http or https origin with no path`);
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Declares a resource. `GET <pattern>` is the collection of the dataset, with no query string; a query
|
|
252
|
+
* string is not answered locally. `GET <pattern>/:key` is a data family of the dataset; `POST <pattern>`
|
|
253
|
+
* inserts; `PUT` and `PATCH <pattern>/:key` replace and update; `DELETE <pattern>/:key` removes. Any
|
|
254
|
+
* `POST`, `PUT`, `PATCH` or `DELETE` of `<pattern>/:key/:action` is a write on that item. Every write
|
|
255
|
+
* updates the collection and the item.
|
|
256
|
+
*/
|
|
257
|
+
export function defineResource(pattern, declaration) {
|
|
258
|
+
checkPattern(pattern);
|
|
259
|
+
const { dataset, key, origin } = declaration;
|
|
260
|
+
const item = `${pattern}/:${key}`;
|
|
261
|
+
const action = `${item}/:action`;
|
|
262
|
+
const families = [pattern, item];
|
|
263
|
+
const extra = origin === undefined ? {} : { origin };
|
|
264
|
+
const routes = [
|
|
265
|
+
defineRoute(pattern, {
|
|
266
|
+
strategy: 'data',
|
|
267
|
+
load: () => ({}),
|
|
268
|
+
query: { list: dataset, dataset },
|
|
269
|
+
...(origin === undefined ? {} : { origin })
|
|
270
|
+
}),
|
|
271
|
+
defineRoute(item, {
|
|
272
|
+
strategy: 'data',
|
|
273
|
+
family: { dataset, key },
|
|
274
|
+
...(origin === undefined ? {} : { origin })
|
|
275
|
+
})
|
|
276
|
+
];
|
|
277
|
+
const writes = [
|
|
278
|
+
defineResourceWrite(pattern, {
|
|
279
|
+
method: 'POST',
|
|
280
|
+
dataset,
|
|
281
|
+
key,
|
|
282
|
+
apply: 'response',
|
|
283
|
+
updates: families,
|
|
284
|
+
...extra
|
|
285
|
+
}),
|
|
286
|
+
defineResourceWrite(item, {
|
|
287
|
+
method: 'PUT',
|
|
288
|
+
dataset,
|
|
289
|
+
key,
|
|
290
|
+
apply: 'response',
|
|
291
|
+
updates: families,
|
|
292
|
+
...extra
|
|
293
|
+
}),
|
|
294
|
+
defineResourceWrite(item, {
|
|
295
|
+
method: 'PATCH',
|
|
296
|
+
dataset,
|
|
297
|
+
key,
|
|
298
|
+
apply: 'response',
|
|
299
|
+
updates: families,
|
|
300
|
+
...extra
|
|
301
|
+
}),
|
|
302
|
+
defineResourceWrite(item, {
|
|
303
|
+
method: 'DELETE',
|
|
304
|
+
dataset,
|
|
305
|
+
key,
|
|
306
|
+
apply: 'delete',
|
|
307
|
+
updates: families,
|
|
308
|
+
...extra
|
|
309
|
+
}),
|
|
310
|
+
...RESOURCE_METHODS.map((method) => defineResourceWrite(action, {
|
|
311
|
+
method,
|
|
312
|
+
dataset,
|
|
313
|
+
key,
|
|
314
|
+
apply: 'invalidate',
|
|
315
|
+
updates: families,
|
|
316
|
+
...extra
|
|
317
|
+
}))
|
|
318
|
+
];
|
|
319
|
+
return Object.freeze({ pattern, dataset, key, routes, writes });
|
|
320
|
+
}
|
|
321
|
+
/**
|
|
322
|
+
* The resource write a request matches: its method, a pattern that matches its path, and its origin.
|
|
323
|
+
* A write with no origin matches only the page's own origin; one with an origin matches that origin.
|
|
324
|
+
*/
|
|
325
|
+
export function writeFor(writes, method, url, pageOrigin) {
|
|
326
|
+
return writes.find((write) => write.method === method &&
|
|
327
|
+
matchPattern(write.pattern, url.pathname) !== null &&
|
|
328
|
+
url.origin === (write.origin ?? pageOrigin));
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* For each write a page made, the resource it couples to and the GET families it updates. A write that
|
|
332
|
+
* couples to no resource reports `resource: null` and no families; that is the uncovered case.
|
|
333
|
+
*/
|
|
334
|
+
export function couplingReport(writes, resources, pageOrigin) {
|
|
335
|
+
return writes.map(({ method, url }) => {
|
|
336
|
+
for (const resource of resources) {
|
|
337
|
+
const hit = writeFor(resource.writes, method, new URL(url), pageOrigin);
|
|
338
|
+
if (hit)
|
|
339
|
+
return { method, url, resource: resource.pattern, families: [...hit.updates] };
|
|
340
|
+
}
|
|
341
|
+
return { method, url, resource: null, families: [] };
|
|
342
|
+
});
|
|
343
|
+
}
|
package/dist/proxy/eligible.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
|
|
1
|
+
import type { Sink } from '../server/sink.js';
|
|
2
|
+
/** why spool will not keep a response on the device, from the proxy or `decorate` */
|
|
2
3
|
export type Decline = 'method' | 'query' | 'authorization' | 'cookie' | 'status' | 'type' | 'set-cookie' | 'private' | 'no-store' | 'vary' | 'tags' | 'size' | 'charset';
|
|
3
4
|
/** what the verdict reads; `principal` is a route the caller declared for a signed-in visitor */
|
|
4
5
|
export type Candidate = {
|
|
@@ -33,6 +34,12 @@ export declare function headerCharset(contentType: string | null): string | null
|
|
|
33
34
|
export declare function htmlCharset(headers: Headers, bytes: Uint8Array): string | null;
|
|
34
35
|
/** whether `charset` is UTF-8; a page that declares none is read as UTF-8 */
|
|
35
36
|
export declare function isUtf8(charset: string | null): boolean;
|
|
37
|
+
/**
|
|
38
|
+
* The first reason a response's own headers keep it from being kept: a `Set-Cookie` off the
|
|
39
|
+
* allowlist, `private` unless `principal`, `no-store`, or a `Vary` other than encoding or cookies.
|
|
40
|
+
* `decorate` runs it for a public route with an empty allowlist, so any cookie declines there.
|
|
41
|
+
*/
|
|
42
|
+
export declare function responseDecline(headers: Headers, publicCookies: ReadonlySet<string>, principal: boolean): Decline | null;
|
|
36
43
|
/**
|
|
37
44
|
* The first reason the response may not be answered locally, or `null` when it may. Everything
|
|
38
45
|
* here declines: a request with a cookie outside the allowlist or an `Authorization` header, a
|
|
@@ -43,3 +50,17 @@ export declare function isUtf8(charset: string | null): boolean;
|
|
|
43
50
|
* `private` rules do not apply to it.
|
|
44
51
|
*/
|
|
45
52
|
export declare function decline(input: Candidate, gate: Gate): Decline | null;
|
|
53
|
+
/** where a declined response is written to the sink, as JSON `{ kind: 'decline', reason, route, source }` */
|
|
54
|
+
export declare const DECLINE_PATH = "/.spool/decline";
|
|
55
|
+
/**
|
|
56
|
+
* Which check declined: `gate` is `decorate`'s check of an in-process response, `navigation` the
|
|
57
|
+
* proxy's check of the page a visitor asked for, `artifact` the proxy's check of the copy it fetches
|
|
58
|
+
* for `/.spool/artifact`. The proxy declines one page at both when a worker asks for its artifact.
|
|
59
|
+
*/
|
|
60
|
+
export type DeclineSource = 'gate' | 'navigation' | 'artifact';
|
|
61
|
+
/**
|
|
62
|
+
* Writes one decline event to `sink` and waits for it, as `/.spool/beacon` does. `route` is the
|
|
63
|
+
* declared route pattern, never the request path, so the event carries no id from a URL. A sink that
|
|
64
|
+
* throws or rejects never breaks the response. Does nothing without a sink.
|
|
65
|
+
*/
|
|
66
|
+
export declare function recordDecline(sink: Sink | undefined, reason: Decline, route: string, source: DeclineSource): Promise<void>;
|
package/dist/proxy/eligible.js
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* `Vary` members that do not change the body once cookies are checked by name. The four `next-router`
|
|
3
|
+
* and `rsc` names are the request headers Next uses to choose its RSC payload over the document; a
|
|
4
|
+
* response to a request without them is the same HTML for every visitor, and a payload response is
|
|
5
|
+
* not HTML, so `decorate` never keeps it.
|
|
6
|
+
*/
|
|
7
|
+
const STABLE_VARY = new Set([
|
|
8
|
+
'accept-encoding',
|
|
9
|
+
'cookie',
|
|
10
|
+
'rsc',
|
|
11
|
+
'next-router-state-tree',
|
|
12
|
+
'next-router-prefetch',
|
|
13
|
+
'next-router-segment-prefetch'
|
|
14
|
+
]);
|
|
3
15
|
/** the cookie names a `Cookie` header carries */
|
|
4
16
|
export function cookieNames(header) {
|
|
5
17
|
if (!header)
|
|
@@ -44,6 +56,27 @@ function directives(value) {
|
|
|
44
56
|
.map((part) => (part.split('=')[0] ?? '').trim().toLowerCase())
|
|
45
57
|
.filter((name) => name !== ''));
|
|
46
58
|
}
|
|
59
|
+
/**
|
|
60
|
+
* The first reason a response's own headers keep it from being kept: a `Set-Cookie` off the
|
|
61
|
+
* allowlist, `private` unless `principal`, `no-store`, or a `Vary` other than encoding or cookies.
|
|
62
|
+
* `decorate` runs it for a public route with an empty allowlist, so any cookie declines there.
|
|
63
|
+
*/
|
|
64
|
+
export function responseDecline(headers, publicCookies, principal) {
|
|
65
|
+
if (setsPrivateCookie(headers, publicCookies))
|
|
66
|
+
return 'set-cookie';
|
|
67
|
+
const control = directives(headers.get('cache-control'));
|
|
68
|
+
if (!principal && control.has('private'))
|
|
69
|
+
return 'private';
|
|
70
|
+
if (control.has('no-store'))
|
|
71
|
+
return 'no-store';
|
|
72
|
+
const vary = (headers.get('vary') ?? '')
|
|
73
|
+
.split(',')
|
|
74
|
+
.map((name) => name.trim().toLowerCase())
|
|
75
|
+
.filter((name) => name !== '');
|
|
76
|
+
if (vary.some((name) => !STABLE_VARY.has(name)))
|
|
77
|
+
return 'vary';
|
|
78
|
+
return null;
|
|
79
|
+
}
|
|
47
80
|
/**
|
|
48
81
|
* The first reason the response may not be answered locally, or `null` when it may. Everything
|
|
49
82
|
* here declines: a request with a cookie outside the allowlist or an `Authorization` header, a
|
|
@@ -74,19 +107,9 @@ export function decline(input, gate) {
|
|
|
74
107
|
// the stored copy is UTF-8 text, so a page in another charset would come back garbled
|
|
75
108
|
if (!input.data && !isUtf8(headerCharset(type)))
|
|
76
109
|
return 'charset';
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
if (!principal && control.has('private'))
|
|
81
|
-
return 'private';
|
|
82
|
-
if (control.has('no-store'))
|
|
83
|
-
return 'no-store';
|
|
84
|
-
const vary = (response.headers.get('vary') ?? '')
|
|
85
|
-
.split(',')
|
|
86
|
-
.map((name) => name.trim().toLowerCase())
|
|
87
|
-
.filter((name) => name !== '');
|
|
88
|
-
if (vary.some((name) => !STABLE_VARY.has(name)))
|
|
89
|
-
return 'vary';
|
|
110
|
+
const why = responseDecline(response.headers, gate.publicCookies, principal);
|
|
111
|
+
if (why)
|
|
112
|
+
return why;
|
|
90
113
|
if (input.tags.length > gate.maxTags)
|
|
91
114
|
return 'tags';
|
|
92
115
|
const length = Number(response.headers.get('content-length'));
|
|
@@ -94,3 +117,27 @@ export function decline(input, gate) {
|
|
|
94
117
|
return 'size';
|
|
95
118
|
return null;
|
|
96
119
|
}
|
|
120
|
+
/** where a declined response is written to the sink, as JSON `{ kind: 'decline', reason, route, source }` */
|
|
121
|
+
export const DECLINE_PATH = '/.spool/decline';
|
|
122
|
+
/**
|
|
123
|
+
* Writes one decline event to `sink` and waits for it, as `/.spool/beacon` does. `route` is the
|
|
124
|
+
* declared route pattern, never the request path, so the event carries no id from a URL. A sink that
|
|
125
|
+
* throws or rejects never breaks the response. Does nothing without a sink.
|
|
126
|
+
*/
|
|
127
|
+
export async function recordDecline(sink, reason, route, source) {
|
|
128
|
+
if (!sink)
|
|
129
|
+
return;
|
|
130
|
+
try {
|
|
131
|
+
await sink.write([
|
|
132
|
+
{
|
|
133
|
+
path: DECLINE_PATH,
|
|
134
|
+
body: JSON.stringify({ kind: 'decline', reason, route, source }),
|
|
135
|
+
contentType: 'application/json',
|
|
136
|
+
at: Date.now()
|
|
137
|
+
}
|
|
138
|
+
]);
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
// a failing sink never breaks a page
|
|
142
|
+
}
|
|
143
|
+
}
|