@drupflare/spool 0.0.0-stage → 0.1.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.
Files changed (182) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1557 -2
  3. package/dist/cdn/client.js +1 -0
  4. package/dist/cdn/location.d.ts +11 -0
  5. package/dist/cdn/location.js +15 -0
  6. package/dist/cdn/manifest.json +16 -0
  7. package/dist/cdn/spool-sw.js +1 -0
  8. package/dist/client/entry.d.ts +1 -0
  9. package/dist/client/entry.js +25 -0
  10. package/dist/client/index.d.ts +3 -0
  11. package/dist/client/index.js +2 -0
  12. package/dist/client/lifecycle.d.ts +10 -0
  13. package/dist/client/lifecycle.js +10 -0
  14. package/dist/client/loads.d.ts +16 -0
  15. package/dist/client/loads.js +41 -0
  16. package/dist/client/register.d.ts +34 -0
  17. package/dist/client/register.js +58 -0
  18. package/dist/index.d.ts +2 -0
  19. package/dist/index.js +2 -0
  20. package/dist/node/listener.d.ts +19 -0
  21. package/dist/node/listener.js +76 -0
  22. package/dist/protocol/artifact.d.ts +54 -0
  23. package/dist/protocol/artifact.js +79 -0
  24. package/dist/protocol/assembly.d.ts +34 -0
  25. package/dist/protocol/assembly.js +72 -0
  26. package/dist/protocol/beacon.d.ts +59 -0
  27. package/dist/protocol/beacon.js +86 -0
  28. package/dist/protocol/collector.d.ts +41 -0
  29. package/dist/protocol/collector.js +84 -0
  30. package/dist/protocol/config.d.ts +89 -0
  31. package/dist/protocol/config.js +13 -0
  32. package/dist/protocol/envelope.d.ts +47 -0
  33. package/dist/protocol/envelope.js +162 -0
  34. package/dist/protocol/errors.d.ts +7 -0
  35. package/dist/protocol/errors.js +9 -0
  36. package/dist/protocol/graph.d.ts +81 -0
  37. package/dist/protocol/graph.js +201 -0
  38. package/dist/protocol/index.d.ts +19 -0
  39. package/dist/protocol/index.js +19 -0
  40. package/dist/protocol/manifest.d.ts +29 -0
  41. package/dist/protocol/manifest.js +94 -0
  42. package/dist/protocol/normalise.d.ts +20 -0
  43. package/dist/protocol/normalise.js +29 -0
  44. package/dist/protocol/pattern.d.ts +12 -0
  45. package/dist/protocol/pattern.js +82 -0
  46. package/dist/protocol/provision.d.ts +100 -0
  47. package/dist/protocol/provision.js +105 -0
  48. package/dist/protocol/route.d.ts +179 -0
  49. package/dist/protocol/route.js +135 -0
  50. package/dist/protocol/sync.d.ts +31 -0
  51. package/dist/protocol/sync.js +87 -0
  52. package/dist/protocol/tag.d.ts +12 -0
  53. package/dist/protocol/tag.js +26 -0
  54. package/dist/protocol/template/compile.d.ts +35 -0
  55. package/dist/protocol/template/compile.js +82 -0
  56. package/dist/protocol/template/interpret.d.ts +9 -0
  57. package/dist/protocol/template/interpret.js +82 -0
  58. package/dist/protocol/vector.d.ts +32 -0
  59. package/dist/protocol/vector.js +56 -0
  60. package/dist/protocol/view.d.ts +110 -0
  61. package/dist/protocol/view.js +201 -0
  62. package/dist/proxy/eligible.d.ts +45 -0
  63. package/dist/proxy/eligible.js +96 -0
  64. package/dist/proxy/index.d.ts +4 -0
  65. package/dist/proxy/index.js +4 -0
  66. package/dist/proxy/proxy.d.ts +86 -0
  67. package/dist/proxy/proxy.js +388 -0
  68. package/dist/proxy/purge.d.ts +10 -0
  69. package/dist/proxy/purge.js +66 -0
  70. package/dist/proxy/tags.d.ts +8 -0
  71. package/dist/proxy/tags.js +36 -0
  72. package/dist/report/derive.d.ts +221 -0
  73. package/dist/report/derive.js +490 -0
  74. package/dist/report/economics.d.ts +14 -0
  75. package/dist/report/economics.js +24 -0
  76. package/dist/report/index.d.ts +8 -0
  77. package/dist/report/index.js +8 -0
  78. package/dist/report/inputs.d.ts +141 -0
  79. package/dist/report/inputs.js +216 -0
  80. package/dist/report/measurement.d.ts +48 -0
  81. package/dist/report/measurement.js +114 -0
  82. package/dist/report/model.d.ts +42 -0
  83. package/dist/report/model.js +74 -0
  84. package/dist/report/thirdparty.d.ts +62 -0
  85. package/dist/report/thirdparty.js +107 -0
  86. package/dist/report/traffic.d.ts +140 -0
  87. package/dist/report/traffic.js +228 -0
  88. package/dist/report/trim.d.ts +81 -0
  89. package/dist/report/trim.js +105 -0
  90. package/dist/server/beacon.d.ts +20 -0
  91. package/dist/server/beacon.js +47 -0
  92. package/dist/server/embedded.d.ts +6 -0
  93. package/dist/server/embedded.js +6 -0
  94. package/dist/server/ga4.d.ts +70 -0
  95. package/dist/server/ga4.js +165 -0
  96. package/dist/server/identity.d.ts +12 -0
  97. package/dist/server/identity.js +17 -0
  98. package/dist/server/index.d.ts +7 -0
  99. package/dist/server/index.js +7 -0
  100. package/dist/server/sink.d.ts +56 -0
  101. package/dist/server/sink.js +133 -0
  102. package/dist/server/size.d.ts +7 -0
  103. package/dist/server/size.js +18 -0
  104. package/dist/server/spool.d.ts +97 -0
  105. package/dist/server/spool.js +463 -0
  106. package/dist/server/stub.d.ts +9 -0
  107. package/dist/server/stub.js +19 -0
  108. package/dist/server/sync.d.ts +12 -0
  109. package/dist/server/sync.js +48 -0
  110. package/dist/server/work.d.ts +22 -0
  111. package/dist/server/work.js +30 -0
  112. package/dist/stores/durable-object.d.ts +19 -0
  113. package/dist/stores/durable-object.js +53 -0
  114. package/dist/stores/index.d.ts +2 -0
  115. package/dist/stores/index.js +2 -0
  116. package/dist/stores/memory.d.ts +4 -0
  117. package/dist/stores/memory.js +10 -0
  118. package/dist/stores/version-store.d.ts +11 -0
  119. package/dist/stores/version-store.js +1 -0
  120. package/dist/sw/analytics.d.ts +81 -0
  121. package/dist/sw/analytics.js +275 -0
  122. package/dist/sw/collect.d.ts +8 -0
  123. package/dist/sw/collect.js +33 -0
  124. package/dist/sw/core.d.ts +1 -0
  125. package/dist/sw/core.js +3 -0
  126. package/dist/sw/freshness.d.ts +15 -0
  127. package/dist/sw/freshness.js +20 -0
  128. package/dist/sw/graph/index.d.ts +67 -0
  129. package/dist/sw/graph/index.js +170 -0
  130. package/dist/sw/graph/invalidate.d.ts +23 -0
  131. package/dist/sw/graph/invalidate.js +109 -0
  132. package/dist/sw/graph/projections.d.ts +7 -0
  133. package/dist/sw/graph/projections.js +9 -0
  134. package/dist/sw/graph/records.d.ts +7 -0
  135. package/dist/sw/graph/records.js +9 -0
  136. package/dist/sw/graph/store.d.ts +32 -0
  137. package/dist/sw/graph/store.js +52 -0
  138. package/dist/sw/idb.d.ts +8 -0
  139. package/dist/sw/idb.js +117 -0
  140. package/dist/sw/index.d.ts +2 -0
  141. package/dist/sw/index.js +1 -0
  142. package/dist/sw/partition.d.ts +21 -0
  143. package/dist/sw/partition.js +137 -0
  144. package/dist/sw/policy.d.ts +8 -0
  145. package/dist/sw/policy.js +24 -0
  146. package/dist/sw/provision.d.ts +39 -0
  147. package/dist/sw/provision.js +61 -0
  148. package/dist/sw/render.d.ts +21 -0
  149. package/dist/sw/render.js +53 -0
  150. package/dist/sw/replica.d.ts +77 -0
  151. package/dist/sw/replica.js +299 -0
  152. package/dist/sw/router.d.ts +42 -0
  153. package/dist/sw/router.js +48 -0
  154. package/dist/sw/routing.d.ts +23 -0
  155. package/dist/sw/routing.js +48 -0
  156. package/dist/sw/runtime.d.ts +112 -0
  157. package/dist/sw/runtime.js +1070 -0
  158. package/dist/sw/scheduler.d.ts +83 -0
  159. package/dist/sw/scheduler.js +149 -0
  160. package/dist/sw/seal.d.ts +37 -0
  161. package/dist/sw/seal.js +183 -0
  162. package/dist/sw/serve.d.ts +15 -0
  163. package/dist/sw/serve.js +63 -0
  164. package/dist/sw/shadow.d.ts +16 -0
  165. package/dist/sw/shadow.js +27 -0
  166. package/dist/sw/static.d.ts +17 -0
  167. package/dist/sw/static.js +81 -0
  168. package/dist/sw/storage.d.ts +64 -0
  169. package/dist/sw/storage.js +34 -0
  170. package/dist/sw/thirdparty.d.ts +17 -0
  171. package/dist/sw/thirdparty.js +36 -0
  172. package/dist/trim/css.d.ts +38 -0
  173. package/dist/trim/css.js +328 -0
  174. package/dist/trim/index.d.ts +3 -0
  175. package/dist/trim/index.js +3 -0
  176. package/dist/trim/manifest.d.ts +67 -0
  177. package/dist/trim/manifest.js +134 -0
  178. package/dist/trim/tokens.d.ts +43 -0
  179. package/dist/trim/tokens.js +142 -0
  180. package/dist/version.d.ts +2 -0
  181. package/dist/version.js +3 -0
  182. package/package.json +146 -5
@@ -0,0 +1,201 @@
1
+ /** the tier a reason has when the worker serves; a shadow view keeps the reason and drops the tier */
2
+ export const REASON_TIER = {
3
+ cold: 'network',
4
+ principal: 'network',
5
+ fresh: 'local',
6
+ catalogue: 'local',
7
+ 'soft-deferred': 'local',
8
+ 'soft-sync': 'local-revalidate',
9
+ 'hard-sync': 'local-revalidate',
10
+ 'offline-stale': 'local-revalidate',
11
+ invalidated: 'fallback',
12
+ 'stale-after-sync': 'fallback',
13
+ 'hard-refused': 'fallback',
14
+ refused: 'fallback'
15
+ };
16
+ /** longest route pattern a view may name; a longer one is not read as a view */
17
+ export const MAX_ROUTE_CHARS = 256;
18
+ /** the `from` of a view whose referrer is another origin */
19
+ export const FROM_EXTERNAL = 'external';
20
+ /** the `path` a view carries inside a beacon batch */
21
+ export const VIEW_PATH = '/.spool/view';
22
+ /** the `path` of the page's later report of a view's cross-origin loads */
23
+ export const LOADS_PATH = '/.spool/loads';
24
+ /** most origins a loads report names; the page keeps the busiest */
25
+ export const MAX_LOAD_ORIGINS = 32;
26
+ /** a loads report as a queued beacon */
27
+ export function loadsToBeacon(view, count, at, origins) {
28
+ return {
29
+ path: LOADS_PATH,
30
+ body: JSON.stringify(origins && Object.keys(origins).length > 0 ? { view, count, origins } : { view, count }),
31
+ contentType: 'application/json',
32
+ at
33
+ };
34
+ }
35
+ /** the report inside a beacon, or null when it is another request or does not validate */
36
+ export function loadsFromBeacon(event) {
37
+ if (event.path !== LOADS_PATH)
38
+ return null;
39
+ try {
40
+ const { view, count, origins } = JSON.parse(event.body);
41
+ if (typeof view !== 'string' || view === '' || view.length > 64)
42
+ return null;
43
+ if (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0)
44
+ return null;
45
+ if (origins === undefined)
46
+ return { view, count, at: event.at };
47
+ if (typeof origins !== 'object' || origins === null || Array.isArray(origins))
48
+ return null;
49
+ const entries = Object.entries(origins);
50
+ if (entries.length > MAX_LOAD_ORIGINS)
51
+ return null;
52
+ for (const [name, n] of entries) {
53
+ if (name.length > 253 || typeof n !== 'number' || !Number.isSafeInteger(n) || n < 1) {
54
+ return null;
55
+ }
56
+ }
57
+ return { view, count, at: event.at, origins: origins };
58
+ }
59
+ catch {
60
+ return null;
61
+ }
62
+ }
63
+ /**
64
+ * The views in `events` with their cross-origin counts filled in from the loads reports among
65
+ * them. A report that arrives in a later batch than its view needs the whole stream, so pass every
66
+ * event; the last report for a view wins. A view with no report keeps null.
67
+ */
68
+ export function viewsWithLoads(events) {
69
+ const counts = new Map();
70
+ const named = new Map();
71
+ for (const event of events) {
72
+ const report = loadsFromBeacon(event);
73
+ if (!report)
74
+ continue;
75
+ counts.set(report.view, report.count);
76
+ if (report.origins)
77
+ named.set(report.view, report.origins);
78
+ else
79
+ named.delete(report.view);
80
+ }
81
+ return events.flatMap((event) => {
82
+ const view = viewFromBeacon(event);
83
+ if (!view)
84
+ return [];
85
+ const count = counts.get(view.id);
86
+ if (count === undefined)
87
+ return [view];
88
+ const origins = named.get(view.id);
89
+ return [
90
+ {
91
+ ...view,
92
+ crossOriginLoads: count,
93
+ ...(origins ? { crossOriginOrigins: origins } : {})
94
+ }
95
+ ];
96
+ });
97
+ }
98
+ const STRATEGIES = ['assembly', 'template', 'static', 'projection', 'data'];
99
+ const TIERS = [
100
+ 'local',
101
+ 'local-revalidate',
102
+ 'network',
103
+ 'fallback',
104
+ 'shadow'
105
+ ];
106
+ const ENGINES = ['chromium', 'firefox', 'webkit', 'other'];
107
+ /** the view as a queued beacon, so it rides the same flush as every other held request */
108
+ export function viewToBeacon(view, at) {
109
+ return { path: VIEW_PATH, body: JSON.stringify(view), contentType: 'application/json', at };
110
+ }
111
+ function nullableNumber(value) {
112
+ return value === null || (typeof value === 'number' && Number.isFinite(value));
113
+ }
114
+ /** the view inside a beacon, or null when it is another request or does not validate */
115
+ export function viewFromBeacon(event) {
116
+ if (event.path !== VIEW_PATH)
117
+ return null;
118
+ let value;
119
+ try {
120
+ value = JSON.parse(event.body);
121
+ }
122
+ catch {
123
+ return null;
124
+ }
125
+ if (typeof value !== 'object' || value === null)
126
+ return null;
127
+ const { id, tier, reason, staleSec, engine, scope, strategy, route, mismatch, swAgeMs, gapMs, from, crossOriginLoads } = value;
128
+ if (typeof id !== 'string' || id === '' || id.length > 64)
129
+ return null;
130
+ if (crossOriginLoads !== null &&
131
+ (!Number.isSafeInteger(crossOriginLoads) || crossOriginLoads < 0)) {
132
+ return null;
133
+ }
134
+ if (typeof tier !== 'string' || !TIERS.includes(tier))
135
+ return null;
136
+ if (typeof reason !== 'string' || !Object.hasOwn(REASON_TIER, reason))
137
+ return null;
138
+ if (typeof engine !== 'string' || !ENGINES.includes(engine))
139
+ return null;
140
+ if (scope !== 'public' && scope !== 'principal')
141
+ return null;
142
+ if (!STRATEGIES.includes(strategy))
143
+ return null;
144
+ if (typeof route !== 'string' || route.length > MAX_ROUTE_CHARS)
145
+ return null;
146
+ if (mismatch !== null && typeof mismatch !== 'boolean')
147
+ return null;
148
+ if (!nullableNumber(staleSec) || !nullableNumber(gapMs))
149
+ return null;
150
+ if (typeof swAgeMs !== 'number' || !Number.isFinite(swAgeMs))
151
+ return null;
152
+ return {
153
+ id,
154
+ crossOriginLoads: crossOriginLoads,
155
+ tier: tier,
156
+ reason: reason,
157
+ staleSec,
158
+ engine: engine,
159
+ scope,
160
+ strategy: strategy,
161
+ route,
162
+ mismatch,
163
+ swAgeMs,
164
+ gapMs,
165
+ ...(typeof from === 'string' && from !== '' && from.length <= MAX_ROUTE_CHARS
166
+ ? { from }
167
+ : {}),
168
+ at: event.at
169
+ };
170
+ }
171
+ /**
172
+ * The engine behind a user agent. Every browser on iOS runs WebKit, whatever its name says, so
173
+ * the iOS tokens are checked first.
174
+ */
175
+ export function engineOf(userAgent) {
176
+ if (/\b(?:CriOS|FxiOS|EdgiOS|OPiOS)\//.test(userAgent))
177
+ return 'webkit';
178
+ if (/\bFirefox\//.test(userAgent))
179
+ return 'firefox';
180
+ if (/\b(?:Chrome|Chromium)\//.test(userAgent))
181
+ return 'chromium';
182
+ if (/\bSafari\//.test(userAgent))
183
+ return 'webkit';
184
+ return 'other';
185
+ }
186
+ /**
187
+ * Where a view stopped: on a route the worker never serves (`ineligible`), with nothing stored
188
+ * (`cold`), with a copy it could not show without the network (`unusable`), or shown with no
189
+ * request (`local`). A view is local only when no cross-origin resource loaded during it, which the
190
+ * page must have reported as 0: a count above 0 or no report makes it `unusable`, whatever the worker
191
+ * did. A shadow view that would have been local but rendered differently from the network is
192
+ * `unusable` too.
193
+ */
194
+ export function funnelOf(view) {
195
+ if (view.reason === 'principal')
196
+ return 'ineligible';
197
+ if (view.reason === 'cold')
198
+ return 'cold';
199
+ const strict = REASON_TIER[view.reason] === 'local' && view.mismatch !== true;
200
+ return strict && view.crossOriginLoads === 0 ? 'local' : 'unusable';
201
+ }
@@ -0,0 +1,45 @@
1
+ /** why the proxy will not keep a response on the device */
2
+ export type Decline = 'method' | 'query' | 'authorization' | 'cookie' | 'status' | 'type' | 'set-cookie' | 'private' | 'no-store' | 'vary' | 'tags' | 'size' | 'charset';
3
+ /** what the verdict reads; `principal` is a route the caller declared for a signed-in visitor */
4
+ export type Candidate = {
5
+ method: string;
6
+ /** the search part of the page URL, empty when there is none */
7
+ search: string;
8
+ /** the headers of the request the visitor made */
9
+ requestHeaders: Headers;
10
+ response: Response;
11
+ /** the tags the response named, before any default */
12
+ tags: readonly string[];
13
+ /** a `data` route answers any content type, a page must be HTML */
14
+ data: boolean;
15
+ principal: boolean;
16
+ };
17
+ /** the limits the verdict applies */
18
+ export type Gate = {
19
+ publicCookies: ReadonlySet<string>;
20
+ maxTags: number;
21
+ maxBytes: number;
22
+ };
23
+ /** the cookie names a `Cookie` header carries */
24
+ export declare function cookieNames(header: string | null): string[];
25
+ /** whether a response sets a cookie whose name is not on the allowlist */
26
+ export declare function setsPrivateCookie(headers: Headers, publicCookies: ReadonlySet<string>): boolean;
27
+ /** the lowercase `charset` a `Content-Type` value names, or null */
28
+ export declare function headerCharset(contentType: string | null): string | null;
29
+ /**
30
+ * The lowercase charset an HTML response declares, from its `Content-Type` or else a `<meta>` in
31
+ * its first 1024 bytes, or null when it declares none.
32
+ */
33
+ export declare function htmlCharset(headers: Headers, bytes: Uint8Array): string | null;
34
+ /** whether `charset` is UTF-8; a page that declares none is read as UTF-8 */
35
+ export declare function isUtf8(charset: string | null): boolean;
36
+ /**
37
+ * The first reason the response may not be answered locally, or `null` when it may. Everything
38
+ * here declines: a request with a cookie outside the allowlist or an `Authorization` header, a
39
+ * query string, a non-200, a body that is not HTML, a page whose `Content-Type` names a charset
40
+ * other than UTF-8, a `Set-Cookie` off the allowlist, `private`, `no-store`, a `Vary`
41
+ * that is not about encoding or cookies, and more tags than the gate allows. A `principal` route
42
+ * stands for a visitor the caller's `identity` resolves, so the cookie, `Authorization` and
43
+ * `private` rules do not apply to it.
44
+ */
45
+ export declare function decline(input: Candidate, gate: Gate): Decline | null;
@@ -0,0 +1,96 @@
1
+ /** `Vary` members that do not change the body once cookies are checked by name */
2
+ const STABLE_VARY = new Set(['accept-encoding', 'cookie']);
3
+ /** the cookie names a `Cookie` header carries */
4
+ export function cookieNames(header) {
5
+ if (!header)
6
+ return [];
7
+ return header
8
+ .split(';')
9
+ .map((part) => part.split('=')[0]?.trim() ?? '')
10
+ .filter((name) => name !== '');
11
+ }
12
+ /** whether a response sets a cookie whose name is not on the allowlist */
13
+ export function setsPrivateCookie(headers, publicCookies) {
14
+ return headers
15
+ .getSetCookie()
16
+ .some((line) => !publicCookies.has(line.split('=')[0]?.trim() ?? ''));
17
+ }
18
+ const UTF8_LABELS = new Set(['utf-8', 'utf8', 'unicode-1-1-utf-8']);
19
+ /** the lowercase `charset` a `Content-Type` value names, or null */
20
+ export function headerCharset(contentType) {
21
+ const match = /;\s*charset\s*=\s*"?([^";\s]+)/i.exec(contentType ?? '');
22
+ return match ? match[1].toLowerCase() : null;
23
+ }
24
+ /**
25
+ * The lowercase charset an HTML response declares, from its `Content-Type` or else a `<meta>` in
26
+ * its first 1024 bytes, or null when it declares none.
27
+ */
28
+ export function htmlCharset(headers, bytes) {
29
+ const header = headerCharset(headers.get('content-type'));
30
+ if (header)
31
+ return header;
32
+ const head = String.fromCharCode(...bytes.subarray(0, 1024));
33
+ const meta = /<meta[^>]+charset\s*=\s*["']?([^"'\s/>;]+)/i.exec(head);
34
+ return meta ? meta[1].toLowerCase() : null;
35
+ }
36
+ /** whether `charset` is UTF-8; a page that declares none is read as UTF-8 */
37
+ export function isUtf8(charset) {
38
+ return charset === null || UTF8_LABELS.has(charset);
39
+ }
40
+ /** the lowercase directive names of a `Cache-Control` value; a `private="x"` counts as `private` */
41
+ function directives(value) {
42
+ return new Set((value ?? '')
43
+ .split(',')
44
+ .map((part) => (part.split('=')[0] ?? '').trim().toLowerCase())
45
+ .filter((name) => name !== ''));
46
+ }
47
+ /**
48
+ * The first reason the response may not be answered locally, or `null` when it may. Everything
49
+ * here declines: a request with a cookie outside the allowlist or an `Authorization` header, a
50
+ * query string, a non-200, a body that is not HTML, a page whose `Content-Type` names a charset
51
+ * other than UTF-8, a `Set-Cookie` off the allowlist, `private`, `no-store`, a `Vary`
52
+ * that is not about encoding or cookies, and more tags than the gate allows. A `principal` route
53
+ * stands for a visitor the caller's `identity` resolves, so the cookie, `Authorization` and
54
+ * `private` rules do not apply to it.
55
+ */
56
+ export function decline(input, gate) {
57
+ const { response, principal } = input;
58
+ if (input.method !== 'GET' && input.method !== 'HEAD')
59
+ return 'method';
60
+ if (input.search !== '')
61
+ return 'query';
62
+ if (!principal) {
63
+ if (input.requestHeaders.has('authorization'))
64
+ return 'authorization';
65
+ const cookies = cookieNames(input.requestHeaders.get('cookie'));
66
+ if (cookies.some((name) => !gate.publicCookies.has(name)))
67
+ return 'cookie';
68
+ }
69
+ if (response.status !== 200)
70
+ return 'status';
71
+ const type = (response.headers.get('content-type') ?? '').toLowerCase();
72
+ if (!input.data && !type.includes('text/html'))
73
+ return 'type';
74
+ // the stored copy is UTF-8 text, so a page in another charset would come back garbled
75
+ if (!input.data && !isUtf8(headerCharset(type)))
76
+ return 'charset';
77
+ if (setsPrivateCookie(response.headers, gate.publicCookies))
78
+ return 'set-cookie';
79
+ const control = directives(response.headers.get('cache-control'));
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';
90
+ if (input.tags.length > gate.maxTags)
91
+ return 'tags';
92
+ const length = Number(response.headers.get('content-length'));
93
+ if (Number.isFinite(length) && length > gate.maxBytes)
94
+ return 'size';
95
+ return null;
96
+ }
@@ -0,0 +1,4 @@
1
+ export * from './eligible.js';
2
+ export * from './proxy.js';
3
+ export * from './purge.js';
4
+ export * from './tags.js';
@@ -0,0 +1,4 @@
1
+ export * from './eligible.js';
2
+ export * from './proxy.js';
3
+ export * from './purge.js';
4
+ export * from './tags.js';
@@ -0,0 +1,86 @@
1
+ import { type AssemblyRoute, type DataRoute } from '../protocol/route.js';
2
+ import { type Spool, type SpoolOptions } from '../server/spool.js';
3
+ import { type TrimManifest } from '../trim/index.js';
4
+ /**
5
+ * A route the proxy answers locally, declared like a `createSpool` route minus `load`: the proxy
6
+ * loads the page from the origin. A `data` route parses the origin's JSON. `depends` adds tags to
7
+ * the ones the origin sent.
8
+ */
9
+ export type ProxyRoute = ({
10
+ pattern: string;
11
+ strategy?: 'assembly';
12
+ } & Omit<AssemblyRoute, 'strategy' | 'load'>) | ({
13
+ pattern: string;
14
+ strategy: 'data';
15
+ } & Omit<DataRoute, 'strategy' | 'load'>);
16
+ /** what `spoolProxy` takes */
17
+ export type ProxyOptions = {
18
+ /** the origin to forward to, such as `https://origin.internal`; no path */
19
+ origin: string | URL;
20
+ /**
21
+ * the options `createSpool` takes, minus `routes`: the worker's route list is fixed when the
22
+ * spool is created, and the proxy puts its own catch-all route there
23
+ */
24
+ spool: Omit<SpoolOptions, 'routes'>;
25
+ /** routes that override the default of one public `assembly` route per path; they match first */
26
+ routes?: readonly ProxyRoute[];
27
+ /**
28
+ * cookie names that carry no identity, such as a bot-check or load-balancer cookie: they do not
29
+ * make a request ineligible, and setting them does not clear the device; default none
30
+ */
31
+ publicCookies?: readonly string[];
32
+ /** keep the tag headers on what the browser receives; default false */
33
+ exposeTags?: boolean;
34
+ /** most tags one response may name before it is not kept; default 512 */
35
+ maxTags?: number;
36
+ /** largest page body kept, in bytes; default 2 MiB */
37
+ maxBytes?: number;
38
+ /** patterns blanked before a page is hashed, such as a per-render form token */
39
+ ignore?: readonly RegExp[];
40
+ /** most pages whose last body hash is remembered, the oldest going first; default 10,000 */
41
+ maxRemembered?: number;
42
+ /** the shared secret `POST /.spool/purge` requires; without one every purge is refused */
43
+ purgeSecret?: string;
44
+ /** how requests reach the origin; default global `fetch`. A Workers service binding passes its `fetch` */
45
+ fetch?: (request: Request) => Promise<Response>;
46
+ /**
47
+ * trimmed stylesheets from `buildTrimManifest`. A same-origin stylesheet in the manifest is
48
+ * answered with its trimmed text when the origin's bytes still hash to the manifest's `source`,
49
+ * and every HTML page is checked against the guard first. Without it nothing is trimmed.
50
+ */
51
+ trim?: TrimManifest;
52
+ };
53
+ /** what the proxy counted since it started: trimmed answers, hash mismatches and guard firings */
54
+ export type TrimStats = {
55
+ served: number;
56
+ mismatched: number;
57
+ guarded: number;
58
+ };
59
+ /** where the proxy writes a guard firing or a hash mismatch to the sink, as JSON `{ kind, ... }` */
60
+ export declare const TRIM_PATH = "/.spool/trim";
61
+ /** the Fetch handler `spoolProxy` returns, with the spool it built */
62
+ export type SpoolProxy = {
63
+ (request: Request): Promise<Response>;
64
+ readonly spool: Spool;
65
+ /** live counters; all zero when `trim` is not set */
66
+ readonly trim: Readonly<TrimStats>;
67
+ };
68
+ /**
69
+ * A Fetch handler that sits in front of an origin that cannot load the library, such as PHP or a
70
+ * Drupal site with no module, and gives it local page views.
71
+ *
72
+ * `/.spool/*` and `/spool-sw.js` are answered here. Everything else goes to the origin with its
73
+ * method, headers and body, and redirects are passed through. A GET or HEAD without `Authorization`
74
+ * or a cookie outside `publicCookies`, answered 200 as `text/html` with no `Set-Cookie`, `private`
75
+ * or `no-store`, is decorated so the worker can keep it; anything else is forwarded untouched.
76
+ * The tags the origin sends in `Cache-Tag`, `Surrogate-Key`, `X-Drupal-Cache-Tags` or `xkey`
77
+ * become the page's dependencies, and a page with none depends on its own path.
78
+ *
79
+ * Limits: the proxy sees finished HTML, so an artifact is the whole page, the replica holds no
80
+ * records, and two pages never share a fragment. A page is invalidated by `POST /.spool/purge`, or
81
+ * when the proxy sees its body change, and it stays on a device until its route's `maxStale` runs
82
+ * out and the next sync reports the change. Freshness is therefore bounded by `maxStale` plus the
83
+ * time a purge takes to arrive. The memory of last-seen bodies lives in the instance: a restart
84
+ * forgets it, and each instance of a scaled-out proxy keeps its own.
85
+ */
86
+ export declare function spoolProxy(options: ProxyOptions): SpoolProxy;