@drupflare/spool 0.0.0-stage → 0.2.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 (202) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1749 -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/media/embeds.d.ts +59 -0
  21. package/dist/media/embeds.js +120 -0
  22. package/dist/media/headers.d.ts +13 -0
  23. package/dist/media/headers.js +44 -0
  24. package/dist/media/html.d.ts +27 -0
  25. package/dist/media/html.js +93 -0
  26. package/dist/media/image.d.ts +222 -0
  27. package/dist/media/image.js +413 -0
  28. package/dist/media/index.d.ts +6 -0
  29. package/dist/media/index.js +6 -0
  30. package/dist/media/lazy.d.ts +26 -0
  31. package/dist/media/lazy.js +74 -0
  32. package/dist/media/responsive.d.ts +45 -0
  33. package/dist/media/responsive.js +98 -0
  34. package/dist/media/video.d.ts +30 -0
  35. package/dist/media/video.js +75 -0
  36. package/dist/node/listener.d.ts +19 -0
  37. package/dist/node/listener.js +76 -0
  38. package/dist/protocol/artifact.d.ts +54 -0
  39. package/dist/protocol/artifact.js +79 -0
  40. package/dist/protocol/assembly.d.ts +34 -0
  41. package/dist/protocol/assembly.js +72 -0
  42. package/dist/protocol/beacon.d.ts +59 -0
  43. package/dist/protocol/beacon.js +86 -0
  44. package/dist/protocol/collector.d.ts +41 -0
  45. package/dist/protocol/collector.js +84 -0
  46. package/dist/protocol/config.d.ts +89 -0
  47. package/dist/protocol/config.js +13 -0
  48. package/dist/protocol/envelope.d.ts +47 -0
  49. package/dist/protocol/envelope.js +162 -0
  50. package/dist/protocol/errors.d.ts +7 -0
  51. package/dist/protocol/errors.js +9 -0
  52. package/dist/protocol/graph.d.ts +81 -0
  53. package/dist/protocol/graph.js +201 -0
  54. package/dist/protocol/index.d.ts +19 -0
  55. package/dist/protocol/index.js +19 -0
  56. package/dist/protocol/manifest.d.ts +29 -0
  57. package/dist/protocol/manifest.js +94 -0
  58. package/dist/protocol/normalise.d.ts +20 -0
  59. package/dist/protocol/normalise.js +29 -0
  60. package/dist/protocol/pattern.d.ts +12 -0
  61. package/dist/protocol/pattern.js +82 -0
  62. package/dist/protocol/provision.d.ts +100 -0
  63. package/dist/protocol/provision.js +105 -0
  64. package/dist/protocol/route.d.ts +179 -0
  65. package/dist/protocol/route.js +135 -0
  66. package/dist/protocol/sync.d.ts +31 -0
  67. package/dist/protocol/sync.js +87 -0
  68. package/dist/protocol/tag.d.ts +12 -0
  69. package/dist/protocol/tag.js +26 -0
  70. package/dist/protocol/template/compile.d.ts +35 -0
  71. package/dist/protocol/template/compile.js +82 -0
  72. package/dist/protocol/template/interpret.d.ts +9 -0
  73. package/dist/protocol/template/interpret.js +82 -0
  74. package/dist/protocol/vector.d.ts +32 -0
  75. package/dist/protocol/vector.js +56 -0
  76. package/dist/protocol/view.d.ts +110 -0
  77. package/dist/protocol/view.js +201 -0
  78. package/dist/proxy/dictionary.d.ts +58 -0
  79. package/dist/proxy/dictionary.js +197 -0
  80. package/dist/proxy/eligible.d.ts +45 -0
  81. package/dist/proxy/eligible.js +96 -0
  82. package/dist/proxy/index.d.ts +5 -0
  83. package/dist/proxy/index.js +5 -0
  84. package/dist/proxy/proxy.d.ts +133 -0
  85. package/dist/proxy/proxy.js +507 -0
  86. package/dist/proxy/purge.d.ts +10 -0
  87. package/dist/proxy/purge.js +66 -0
  88. package/dist/proxy/tags.d.ts +8 -0
  89. package/dist/proxy/tags.js +36 -0
  90. package/dist/report/derive.d.ts +223 -0
  91. package/dist/report/derive.js +494 -0
  92. package/dist/report/economics.d.ts +14 -0
  93. package/dist/report/economics.js +24 -0
  94. package/dist/report/index.d.ts +9 -0
  95. package/dist/report/index.js +9 -0
  96. package/dist/report/inputs.d.ts +141 -0
  97. package/dist/report/inputs.js +216 -0
  98. package/dist/report/ledger.d.ts +169 -0
  99. package/dist/report/ledger.js +278 -0
  100. package/dist/report/measurement.d.ts +48 -0
  101. package/dist/report/measurement.js +117 -0
  102. package/dist/report/model.d.ts +42 -0
  103. package/dist/report/model.js +74 -0
  104. package/dist/report/thirdparty.d.ts +62 -0
  105. package/dist/report/thirdparty.js +107 -0
  106. package/dist/report/traffic.d.ts +140 -0
  107. package/dist/report/traffic.js +228 -0
  108. package/dist/report/trim.d.ts +81 -0
  109. package/dist/report/trim.js +105 -0
  110. package/dist/server/beacon.d.ts +20 -0
  111. package/dist/server/beacon.js +47 -0
  112. package/dist/server/embedded.d.ts +6 -0
  113. package/dist/server/embedded.js +6 -0
  114. package/dist/server/ga4.d.ts +70 -0
  115. package/dist/server/ga4.js +165 -0
  116. package/dist/server/identity.d.ts +12 -0
  117. package/dist/server/identity.js +17 -0
  118. package/dist/server/index.d.ts +7 -0
  119. package/dist/server/index.js +7 -0
  120. package/dist/server/sink.d.ts +56 -0
  121. package/dist/server/sink.js +133 -0
  122. package/dist/server/size.d.ts +7 -0
  123. package/dist/server/size.js +18 -0
  124. package/dist/server/spool.d.ts +97 -0
  125. package/dist/server/spool.js +463 -0
  126. package/dist/server/stub.d.ts +9 -0
  127. package/dist/server/stub.js +19 -0
  128. package/dist/server/sync.d.ts +12 -0
  129. package/dist/server/sync.js +48 -0
  130. package/dist/server/work.d.ts +22 -0
  131. package/dist/server/work.js +30 -0
  132. package/dist/stores/durable-object.d.ts +19 -0
  133. package/dist/stores/durable-object.js +53 -0
  134. package/dist/stores/index.d.ts +2 -0
  135. package/dist/stores/index.js +2 -0
  136. package/dist/stores/memory.d.ts +4 -0
  137. package/dist/stores/memory.js +10 -0
  138. package/dist/stores/version-store.d.ts +11 -0
  139. package/dist/stores/version-store.js +1 -0
  140. package/dist/sw/analytics.d.ts +81 -0
  141. package/dist/sw/analytics.js +275 -0
  142. package/dist/sw/collect.d.ts +8 -0
  143. package/dist/sw/collect.js +33 -0
  144. package/dist/sw/core.d.ts +1 -0
  145. package/dist/sw/core.js +3 -0
  146. package/dist/sw/freshness.d.ts +15 -0
  147. package/dist/sw/freshness.js +20 -0
  148. package/dist/sw/graph/index.d.ts +67 -0
  149. package/dist/sw/graph/index.js +170 -0
  150. package/dist/sw/graph/invalidate.d.ts +23 -0
  151. package/dist/sw/graph/invalidate.js +109 -0
  152. package/dist/sw/graph/projections.d.ts +7 -0
  153. package/dist/sw/graph/projections.js +9 -0
  154. package/dist/sw/graph/records.d.ts +7 -0
  155. package/dist/sw/graph/records.js +9 -0
  156. package/dist/sw/graph/store.d.ts +32 -0
  157. package/dist/sw/graph/store.js +52 -0
  158. package/dist/sw/idb.d.ts +8 -0
  159. package/dist/sw/idb.js +117 -0
  160. package/dist/sw/index.d.ts +2 -0
  161. package/dist/sw/index.js +1 -0
  162. package/dist/sw/partition.d.ts +21 -0
  163. package/dist/sw/partition.js +137 -0
  164. package/dist/sw/policy.d.ts +8 -0
  165. package/dist/sw/policy.js +24 -0
  166. package/dist/sw/provision.d.ts +39 -0
  167. package/dist/sw/provision.js +61 -0
  168. package/dist/sw/render.d.ts +21 -0
  169. package/dist/sw/render.js +53 -0
  170. package/dist/sw/replica.d.ts +77 -0
  171. package/dist/sw/replica.js +299 -0
  172. package/dist/sw/router.d.ts +42 -0
  173. package/dist/sw/router.js +48 -0
  174. package/dist/sw/routing.d.ts +23 -0
  175. package/dist/sw/routing.js +48 -0
  176. package/dist/sw/runtime.d.ts +112 -0
  177. package/dist/sw/runtime.js +1070 -0
  178. package/dist/sw/scheduler.d.ts +83 -0
  179. package/dist/sw/scheduler.js +149 -0
  180. package/dist/sw/seal.d.ts +37 -0
  181. package/dist/sw/seal.js +183 -0
  182. package/dist/sw/serve.d.ts +15 -0
  183. package/dist/sw/serve.js +63 -0
  184. package/dist/sw/shadow.d.ts +16 -0
  185. package/dist/sw/shadow.js +27 -0
  186. package/dist/sw/static.d.ts +17 -0
  187. package/dist/sw/static.js +81 -0
  188. package/dist/sw/storage.d.ts +64 -0
  189. package/dist/sw/storage.js +34 -0
  190. package/dist/sw/thirdparty.d.ts +17 -0
  191. package/dist/sw/thirdparty.js +36 -0
  192. package/dist/trim/css.d.ts +38 -0
  193. package/dist/trim/css.js +328 -0
  194. package/dist/trim/index.d.ts +3 -0
  195. package/dist/trim/index.js +3 -0
  196. package/dist/trim/manifest.d.ts +67 -0
  197. package/dist/trim/manifest.js +134 -0
  198. package/dist/trim/tokens.d.ts +47 -0
  199. package/dist/trim/tokens.js +142 -0
  200. package/dist/version.d.ts +2 -0
  201. package/dist/version.js +3 -0
  202. package/package.json +150 -5
@@ -0,0 +1,413 @@
1
+ import { ProtocolError } from '../protocol/errors.js';
2
+ import { sourceHash } from '../trim/manifest.js';
3
+ import { mergeList, signalsOf } from './headers.js';
4
+ import { resolveLazyOptions } from './lazy.js';
5
+ import { RESPONSIVE_PARAM, resolveResponsiveOptions, takeWidth } from './responsive.js';
6
+ /** the oldest tinyimg that turns an EXIF-rotated JPEG upright; 1.1.0 and earlier leave it sideways */
7
+ export const TINYIMG_MIN_VERSION = [1, 1, 1];
8
+ /** the version text of a module that reports one older than {@link TINYIMG_MIN_VERSION}, else null */
9
+ function tooOld(module) {
10
+ const version = module?.version;
11
+ if (!Array.isArray(version) || version.length !== 3 || !version.every(Number.isInteger)) {
12
+ return null;
13
+ }
14
+ for (const [at, need] of TINYIMG_MIN_VERSION.entries()) {
15
+ const have = version[at];
16
+ if (have !== need)
17
+ return have < need ? version.join('.') : null;
18
+ }
19
+ return null;
20
+ }
21
+ /**
22
+ * An {@link ImageEncoder} over tinyimg. It passes `fit: 'scale-down'` when a width is set, which
23
+ * keeps tinyimg from upscaling, passes `lossless` and `budgetMs` when the proxy sets them, and
24
+ * returns the bytes of the result. A module whose `version` is older than
25
+ * {@link TINYIMG_MIN_VERSION} is refused with a `ProtocolError`, since converting an EXIF-rotated
26
+ * JPEG with it would serve the picture sideways. A module that reports no version is accepted.
27
+ */
28
+ export function tinyimgEncoder(binding) {
29
+ const old = tooOld(binding.module);
30
+ if (old !== null) {
31
+ throw new ProtocolError('bad-route', `tinyimg ${old} leaves an EXIF-rotated JPEG sideways; use ${TINYIMG_MIN_VERSION.join('.')} or later`);
32
+ }
33
+ return async (input, { format, quality, width, lossless, budgetMs }) => {
34
+ const out = await binding.transform(binding.module, input, {
35
+ format,
36
+ quality,
37
+ ...(width === undefined ? {} : { width, fit: 'scale-down' }),
38
+ ...(lossless ? { lossless: true } : {}),
39
+ ...(budgetMs === undefined ? {} : { budgetMs })
40
+ });
41
+ return { bytes: out.bytes() };
42
+ };
43
+ }
44
+ /** an in-memory {@link ImageCache} that drops the least recently used entry past `maxBytes` */
45
+ export function memoryImageCache(maxBytes) {
46
+ if (!Number.isInteger(maxBytes) || maxBytes < 1) {
47
+ throw new ProtocolError('bad-route', 'image cache maxBytes must be a positive integer');
48
+ }
49
+ const entries = new Map();
50
+ let size = 0;
51
+ return {
52
+ get(key) {
53
+ const hit = entries.get(key);
54
+ if (hit) {
55
+ entries.delete(key);
56
+ entries.set(key, hit);
57
+ }
58
+ return hit;
59
+ },
60
+ set(key, bytes) {
61
+ if (bytes.length > maxBytes)
62
+ return;
63
+ const old = entries.get(key);
64
+ if (old)
65
+ size -= old.length;
66
+ entries.delete(key);
67
+ entries.set(key, bytes);
68
+ size += bytes.length;
69
+ for (const [oldest, held] of entries) {
70
+ if (size <= maxBytes)
71
+ break;
72
+ entries.delete(oldest);
73
+ size -= held.length;
74
+ }
75
+ }
76
+ };
77
+ }
78
+ /** the largest PNG, in bytes, that `png: 'auto'` encodes both ways */
79
+ export const PNG_AUTO_BYTES = 200_000;
80
+ /** the Vary entries a converted image answers with */
81
+ export const IMAGE_VARY = [
82
+ 'Accept',
83
+ 'Save-Data',
84
+ 'Sec-CH-Width',
85
+ 'Sec-CH-DPR',
86
+ 'Sec-CH-Viewport-Width',
87
+ 'ECT'
88
+ ];
89
+ /** the client hints an HTML response asks the browser to send on later image requests */
90
+ export const IMAGE_HINTS = [
91
+ 'Sec-CH-DPR',
92
+ 'Sec-CH-Width',
93
+ 'Sec-CH-Viewport-Width',
94
+ 'ECT'
95
+ ];
96
+ const MAX_WIDTH = 16384;
97
+ const DEFAULT_MAX_WIDTH = 2560;
98
+ const DEFAULT_TIMEOUT_MS = 10_000;
99
+ const DEFAULT_CACHE_BYTES = 64 * 1024 * 1024;
100
+ function integerIn(value, low, high, name) {
101
+ if (!Number.isInteger(value) || value < low || value > high) {
102
+ throw new ProtocolError('bad-route', `images ${name} must be an integer from ${low} to ${high}`);
103
+ }
104
+ return value;
105
+ }
106
+ /** applies the defaults to `options` and refuses a value out of range with `ProtocolError('bad-route')` */
107
+ export function resolveImageOptions(options) {
108
+ const quality = {
109
+ default: integerIn(options.quality?.default ?? 80, 1, 100, 'quality.default'),
110
+ saveData: integerIn(options.quality?.saveData ?? 65, 1, 100, 'quality.saveData'),
111
+ slow: integerIn(options.quality?.slow ?? 70, 1, 100, 'quality.slow')
112
+ };
113
+ const minBytes = integerIn(options.minBytes ?? 4096, 0, Number.MAX_SAFE_INTEGER, 'minBytes');
114
+ const maxBytes = integerIn(options.maxBytes ?? 15_000_000, 1, Number.MAX_SAFE_INTEGER, 'maxBytes');
115
+ if (minBytes > maxBytes) {
116
+ throw new ProtocolError('bad-route', 'images minBytes must not exceed maxBytes');
117
+ }
118
+ const fallback = options.width?.fallback;
119
+ const ceiling = options.maxWidth === undefined ? DEFAULT_MAX_WIDTH : options.maxWidth;
120
+ const checked = ceiling === false ? false : integerIn(ceiling, 1, MAX_WIDTH, 'maxWidth');
121
+ const timeout = options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : options.timeoutMs;
122
+ const png = options.png ?? 'lossy';
123
+ if (png !== 'lossy' && png !== 'auto' && png !== 'lossless') {
124
+ throw new ProtocolError('bad-route', "images png must be 'lossy', 'auto' or 'lossless'");
125
+ }
126
+ return {
127
+ encoder: options.encoder,
128
+ quality,
129
+ minBytes,
130
+ maxBytes,
131
+ width: fallback !== undefined
132
+ ? { fallback: integerIn(fallback, 1, MAX_WIDTH, 'width.fallback') }
133
+ : checked === false
134
+ ? {}
135
+ : { fallback: checked },
136
+ timeoutMs: timeout === false ? false : integerIn(timeout, 1, Number.MAX_SAFE_INTEGER, 'timeoutMs'),
137
+ png,
138
+ responsive: options.responsive ? resolveResponsiveOptions(options.responsive) : false,
139
+ lazy: options.lazy ? resolveLazyOptions(options.lazy) : false,
140
+ hints: options.hints !== false,
141
+ paths: options.paths ?? /\.(?:jpe?g|png)$/i
142
+ };
143
+ }
144
+ /** a converter with the options resolved, an empty cache and zeroed counters */
145
+ export function createImageConverter(options) {
146
+ const resolved = resolveImageOptions(options);
147
+ return {
148
+ options: resolved,
149
+ cache: options.cache === false
150
+ ? undefined
151
+ : (options.cache ?? memoryImageCache(DEFAULT_CACHE_BYTES)),
152
+ stats: {
153
+ converted: 0,
154
+ bytesIn: 0,
155
+ bytesOut: 0,
156
+ cacheHits: 0,
157
+ coalesced: 0,
158
+ lazied: 0,
159
+ responsive: 0,
160
+ skipped: {}
161
+ },
162
+ running: new Map()
163
+ };
164
+ }
165
+ function positive(value) {
166
+ if (value === null || !/^\s*\d+\s*$/.test(value))
167
+ return null;
168
+ const n = Number(value);
169
+ return n > 0 && n <= MAX_WIDTH ? n : null;
170
+ }
171
+ /**
172
+ * The WebP quality and width ceiling for one request, from its headers. `Save-Data: on` picks
173
+ * `quality.saveData`, else an `ECT` of `slow-2g`, `2g` or `3g` picks `quality.slow`, else
174
+ * `quality.default`. The width is `Sec-CH-Width`, else `Sec-CH-Viewport-Width` times `Sec-CH-DPR`
175
+ * rounded up, else `width.fallback`; a value that is not a positive number of at most 16384 is
176
+ * ignored.
177
+ */
178
+ export function imageVariant(headers, options = {}) {
179
+ const signals = signalsOf(headers);
180
+ const quality = signals.saveData
181
+ ? (options.quality?.saveData ?? 65)
182
+ : signals.slow
183
+ ? (options.quality?.slow ?? 70)
184
+ : (options.quality?.default ?? 80);
185
+ let width = positive(headers.get('sec-ch-width'));
186
+ if (width === null) {
187
+ const viewport = positive(headers.get('sec-ch-viewport-width'));
188
+ const ratio = Number(headers.get('sec-ch-dpr'));
189
+ if (viewport !== null && Number.isFinite(ratio) && ratio > 0) {
190
+ const scaled = Math.ceil(viewport * ratio);
191
+ if (scaled <= MAX_WIDTH)
192
+ width = scaled;
193
+ }
194
+ }
195
+ width ??= options.width?.fallback ?? null;
196
+ return width === null ? { quality } : { quality, width };
197
+ }
198
+ function skip(converter, why) {
199
+ const { skipped } = converter.stats;
200
+ skipped[why] = (skipped[why] ?? 0) + 1;
201
+ }
202
+ /**
203
+ * The request-side tests: a `GET` whose path matches `paths`, that accepts `image/webp` and carries
204
+ * no `Range` or `Authorization`. A request that fails one is counted under `path`, `accept`,
205
+ * `range` or `authorization` and `false` comes back; a method other than `GET` is not an image
206
+ * request and is not counted. The proxy forwards a request that passes without its conditional
207
+ * headers, so the origin sends the whole file.
208
+ */
209
+ export function imageRequest(converter, request) {
210
+ if (request.method !== 'GET')
211
+ return false;
212
+ const { paths } = converter.options;
213
+ paths.lastIndex = 0;
214
+ if (!paths.test(new URL(request.url).pathname))
215
+ return skipBecause(converter, 'path');
216
+ if (!(request.headers.get('accept') ?? '').toLowerCase().includes('image/webp')) {
217
+ return skipBecause(converter, 'accept');
218
+ }
219
+ if (request.headers.has('range'))
220
+ return skipBecause(converter, 'range');
221
+ if (request.headers.has('authorization'))
222
+ return skipBecause(converter, 'authorization');
223
+ return true;
224
+ }
225
+ /**
226
+ * The query string the origin should see for `url`: with `responsive` set and a pathname that
227
+ * `paths` matches, every `spool-w` parameter is removed, so the origin never sees a parameter
228
+ * only the proxy reads; otherwise `url.search` as it is.
229
+ */
230
+ export function originSearch(converter, url) {
231
+ const { responsive, paths } = converter.options;
232
+ if (!responsive || !url.search.includes(RESPONSIVE_PARAM))
233
+ return url.search;
234
+ paths.lastIndex = 0;
235
+ return paths.test(url.pathname) ? takeWidth(url.search, responsive.widths).search : url.search;
236
+ }
237
+ function skipBecause(converter, why) {
238
+ skip(converter, why);
239
+ return false;
240
+ }
241
+ function magicOf(bytes) {
242
+ if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
243
+ return 'image/jpeg';
244
+ const png = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
245
+ return png.every((byte, at) => bytes[at] === byte) ? 'image/png' : null;
246
+ }
247
+ function hex(hash) {
248
+ return [...atob(hash.slice('sha256-'.length)).slice(0, 8)]
249
+ .map((char) => char.charCodeAt(0).toString(16).padStart(2, '0'))
250
+ .join('');
251
+ }
252
+ function matches(header, etag) {
253
+ if (header === null)
254
+ return false;
255
+ const opaque = etag.slice(2);
256
+ return header
257
+ .split(',')
258
+ .map((part) => part.trim())
259
+ .some((part) => part === '*' || part.replace(/^W\//, '') === opaque);
260
+ }
261
+ /**
262
+ * The encoded bytes for `key`, or `'failed'` when the encoder threw or returned nothing, or
263
+ * `'timeout'` when it ran past `timeoutMs`. A request for a key that is already encoding waits for
264
+ * that encode instead of starting another. The encode caches its own result when it finishes, so
265
+ * one that outlives its waiters still serves the next request.
266
+ */
267
+ async function encode(converter, key, bytes, quality, width, mode) {
268
+ const { options, stats, cache, running } = converter;
269
+ let task = running.get(key);
270
+ if (task) {
271
+ stats.coalesced++;
272
+ }
273
+ else {
274
+ const budget = options.timeoutMs === false ? {} : { budgetMs: options.timeoutMs };
275
+ const run = async (lossless) => (await options.encoder(bytes, {
276
+ format: 'webp',
277
+ quality,
278
+ ...(width === undefined ? {} : { width }),
279
+ ...(lossless ? { lossless: true } : {}),
280
+ ...budget
281
+ })).bytes;
282
+ const started = (async () => {
283
+ let out;
284
+ if (mode === 'auto') {
285
+ // a failed arm loses to the other; both failing fails the encode
286
+ const arms = await Promise.allSettled([run(false), run(true)]);
287
+ const made = arms.flatMap((arm) => arm.status === 'fulfilled' && arm.value.length > 0 ? [arm.value] : []);
288
+ if (made.length === 0)
289
+ throw new Error('the encoder returned no bytes');
290
+ out = made.reduce((best, next) => (next.length < best.length ? next : best));
291
+ }
292
+ else {
293
+ out = await run(mode === 'lossless');
294
+ if (out.length === 0)
295
+ throw new Error('the encoder returned no bytes');
296
+ }
297
+ cache?.set(key, out);
298
+ return out;
299
+ })();
300
+ task = started;
301
+ running.set(key, started);
302
+ const clear = () => {
303
+ if (running.get(key) === started)
304
+ running.delete(key);
305
+ };
306
+ started.then(clear, clear);
307
+ }
308
+ const limit = options.timeoutMs;
309
+ if (limit === false) {
310
+ return task.catch(() => 'failed');
311
+ }
312
+ let timer;
313
+ const expired = new Promise((resolve) => {
314
+ timer = setTimeout(() => resolve('timeout'), limit);
315
+ });
316
+ try {
317
+ return await Promise.race([task, expired]);
318
+ }
319
+ catch {
320
+ return 'failed';
321
+ }
322
+ finally {
323
+ if (timer !== undefined)
324
+ clearTimeout(timer);
325
+ }
326
+ }
327
+ /**
328
+ * Answers one origin response to a request that passed {@link imageRequest}: a `200` JPEG or PNG
329
+ * that sets no cookie and is between `minBytes` and `maxBytes` becomes WebP, and anything else
330
+ * comes back as it was. The conversion keeps the origin's `Cache-Control`, merges {@link IMAGE_VARY}
331
+ * into `Vary`, sets a weak `ETag` from the origin bytes, the quality and the width, and answers
332
+ * `304` when the request's `If-None-Match` matches it. `X-Spool-Image` reads
333
+ * `<bytesIn>-><bytesOut>; q=<quality>; w=<width or 0>`. With `responsive`, a listed `spool-w` in the
334
+ * request URL lowers the width to at most that value; an unlisted one is ignored. A PNG follows
335
+ * `png`.
336
+ *
337
+ * The origin is fetched for every request, so a visitor only ever gets the bytes the origin sent
338
+ * that visitor. An encoder that throws, runs past `timeoutMs`, or produces output that is not
339
+ * smaller serves the origin's bytes with a `200`. The response never fails because of the
340
+ * conversion. Simultaneous requests for the same bytes, quality and width share one encoder call.
341
+ */
342
+ export async function convertImage(converter, request, upstream) {
343
+ const { options, stats, cache } = converter;
344
+ if (upstream.status !== 200)
345
+ return skipWith(converter, 'status', upstream);
346
+ const type = (upstream.headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase();
347
+ if (type !== 'image/jpeg' && type !== 'image/png')
348
+ return skipWith(converter, 'type', upstream);
349
+ if (upstream.headers.getSetCookie().length > 0)
350
+ return skipWith(converter, 'set-cookie', upstream);
351
+ const declared = upstream.headers.get('content-length');
352
+ if (declared !== null && Number(declared) > options.maxBytes) {
353
+ return skipWith(converter, 'size-max', upstream);
354
+ }
355
+ const bytes = new Uint8Array(await upstream.arrayBuffer());
356
+ const original = () => new Response(bytes, {
357
+ status: upstream.status,
358
+ statusText: upstream.statusText,
359
+ headers: upstream.headers
360
+ });
361
+ if (magicOf(bytes) !== type)
362
+ return skipWith(converter, 'type', original());
363
+ if (bytes.length < options.minBytes)
364
+ return skipWith(converter, 'size-min', original());
365
+ if (bytes.length > options.maxBytes)
366
+ return skipWith(converter, 'size-max', original());
367
+ const variant = imageVariant(request.headers, options);
368
+ const { quality } = variant;
369
+ let { width } = variant;
370
+ if (options.responsive) {
371
+ const asked = takeWidth(new URL(request.url).search, options.responsive.widths).width;
372
+ if (asked !== undefined)
373
+ width = width === undefined ? asked : Math.min(width, asked);
374
+ }
375
+ // only a PNG has a mode, and `auto` stays lossy above the size it encodes both ways
376
+ const mode = type === 'image/png' && (options.png !== 'auto' || bytes.length < PNG_AUTO_BYTES)
377
+ ? options.png
378
+ : 'lossy';
379
+ const hash = await sourceHash(bytes);
380
+ const etag = `W/"${hex(hash)}-${quality}-${width ?? 0}${mode === 'lossy' ? '' : `-${mode}`}"`;
381
+ const headers = new Headers(upstream.headers);
382
+ headers.set('content-type', 'image/webp');
383
+ headers.delete('content-length');
384
+ headers.delete('accept-ranges');
385
+ mergeList(headers, 'vary', IMAGE_VARY);
386
+ headers.set('etag', etag);
387
+ if (matches(request.headers.get('if-none-match'), etag)) {
388
+ skip(converter, 'not-modified');
389
+ return new Response(null, { status: 304, headers });
390
+ }
391
+ const key = `${hash}|${quality}|${width ?? 0}${mode === 'lossy' ? '' : `|${mode}`}`;
392
+ let out = cache?.get(key);
393
+ if (out) {
394
+ stats.cacheHits++;
395
+ }
396
+ else {
397
+ const result = await encode(converter, key, bytes, quality, width, mode);
398
+ if (typeof result === 'string')
399
+ return skipWith(converter, result, original());
400
+ out = result;
401
+ }
402
+ if (out.length >= bytes.length)
403
+ return skipWith(converter, 'larger', original());
404
+ headers.set('x-spool-image', `${bytes.length}->${out.length}; q=${quality}; w=${width ?? 0}`);
405
+ stats.converted++;
406
+ stats.bytesIn += bytes.length;
407
+ stats.bytesOut += out.length;
408
+ return new Response(out, { status: 200, statusText: upstream.statusText, headers });
409
+ }
410
+ function skipWith(converter, why, response) {
411
+ skip(converter, why);
412
+ return response;
413
+ }
@@ -0,0 +1,6 @@
1
+ export * from './embeds.js';
2
+ export { signalsOf, type MediaSignals } from './headers.js';
3
+ export * from './image.js';
4
+ export * from './lazy.js';
5
+ export * from './responsive.js';
6
+ export * from './video.js';
@@ -0,0 +1,6 @@
1
+ export * from './embeds.js';
2
+ export { signalsOf } from './headers.js';
3
+ export * from './image.js';
4
+ export * from './lazy.js';
5
+ export * from './responsive.js';
6
+ export * from './video.js';
@@ -0,0 +1,26 @@
1
+ /**
2
+ * What `images.lazy` does to `<img>` and `<iframe>` start tags. `skip` is how many `<img>` tags at
3
+ * the top of the page keep loading at once, since the first images are the likeliest to be in the
4
+ * first viewport; default 2. `iframes` adds `loading="lazy"` to `<iframe>` tags too; default false.
5
+ */
6
+ export type LazyOptions = {
7
+ skip?: number;
8
+ iframes?: boolean;
9
+ };
10
+ /** `LazyOptions` with every default applied */
11
+ export type ResolvedLazyOptions = Required<LazyOptions>;
12
+ /** applies the defaults to `options` and refuses a `skip` that is not a whole number of 0 or more */
13
+ export declare function resolveLazyOptions(options?: LazyOptions): ResolvedLazyOptions;
14
+ /**
15
+ * Adds `loading="lazy"` and `decoding="async"` to the `<img>` tags of `html` after the first
16
+ * `skip`, and `loading="lazy"` to `<iframe>` tags with `iframes`, and says how many tags changed.
17
+ * Tags inside `<head>`, `<noscript>` or an HTML comment are neither counted nor edited. A tag that
18
+ * has `loading`, `fetchpriority`, `data-src`, `data-srcset` or a `data-lazy*` attribute, that sits
19
+ * inside a `<header>`, or whose `src` a `<link rel="preload" as="image">` names, is counted toward
20
+ * `skip` and left alone. A tag that already has `decoding` keeps it. Everything outside the edited
21
+ * start tags stays byte for byte, and the edits are ASCII.
22
+ */
23
+ export declare function rewriteLazy(html: string, options?: LazyOptions): {
24
+ html: string;
25
+ rewritten: number;
26
+ };
@@ -0,0 +1,74 @@
1
+ import { ProtocolError } from '../protocol/errors.js';
2
+ import { tagsOf } from '../trim/tokens.js';
3
+ import { appendAttributes, applyEdits, commentRanges, elementRanges, find, headRange, noscriptRanges, within } from './html.js';
4
+ /** applies the defaults to `options` and refuses a `skip` that is not a whole number of 0 or more */
5
+ export function resolveLazyOptions(options = {}) {
6
+ const skip = options.skip ?? 2;
7
+ if (!Number.isInteger(skip) || skip < 0) {
8
+ throw new ProtocolError('bad-route', 'images lazy.skip must be a whole number of 0 or more');
9
+ }
10
+ return { skip, iframes: options.iframes === true };
11
+ }
12
+ /** a tag that says it loads some other way: its own `loading` or `fetchpriority`, or a lazy-loading library's data attribute */
13
+ function opted(tag) {
14
+ if (find(tag, 'loading') || find(tag, 'fetchpriority'))
15
+ return true;
16
+ return tag.attributes.some((a) => a.name === 'data-src' || a.name === 'data-srcset' || a.name.startsWith('data-lazy'));
17
+ }
18
+ /** the `href` of every `<link rel="preload" as="image">` in `tags` */
19
+ function preloaded(tags) {
20
+ const hrefs = new Set();
21
+ for (const tag of tags) {
22
+ if (tag.name !== 'link')
23
+ continue;
24
+ const rel = (find(tag, 'rel')?.value ?? '').toLowerCase().split(/\s+/);
25
+ const as = (find(tag, 'as')?.value ?? '').trim().toLowerCase();
26
+ const href = find(tag, 'href')?.value.trim();
27
+ if (rel.includes('preload') && as === 'image' && href)
28
+ hrefs.add(href);
29
+ }
30
+ return hrefs;
31
+ }
32
+ /**
33
+ * Adds `loading="lazy"` and `decoding="async"` to the `<img>` tags of `html` after the first
34
+ * `skip`, and `loading="lazy"` to `<iframe>` tags with `iframes`, and says how many tags changed.
35
+ * Tags inside `<head>`, `<noscript>` or an HTML comment are neither counted nor edited. A tag that
36
+ * has `loading`, `fetchpriority`, `data-src`, `data-srcset` or a `data-lazy*` attribute, that sits
37
+ * inside a `<header>`, or whose `src` a `<link rel="preload" as="image">` names, is counted toward
38
+ * `skip` and left alone. A tag that already has `decoding` keeps it. Everything outside the edited
39
+ * start tags stays byte for byte, and the edits are ASCII.
40
+ */
41
+ export function rewriteLazy(html, options = {}) {
42
+ const { skip, iframes } = resolveLazyOptions(options);
43
+ const tags = tagsOf(html);
44
+ const comments = commentRanges(html);
45
+ const noscripts = noscriptRanges(html, tags);
46
+ const head = headRange(html, tags);
47
+ const headers = elementRanges(html, tags, 'header');
48
+ const preloads = preloaded(tags);
49
+ const edits = [];
50
+ let seen = 0;
51
+ let rewritten = 0;
52
+ for (const tag of tags) {
53
+ if (tag.name !== 'img' && !(iframes && tag.name === 'iframe'))
54
+ continue;
55
+ if (html[tag.end] !== '>')
56
+ continue;
57
+ if (within(comments, tag.start) || within(noscripts, tag.start))
58
+ continue;
59
+ if (head && tag.start >= head[0] && tag.start < head[1])
60
+ continue;
61
+ if (tag.name === 'img' && seen++ < skip)
62
+ continue;
63
+ if (opted(tag) || within(headers, tag.start))
64
+ continue;
65
+ if (tag.name === 'img' && preloads.has((find(tag, 'src')?.value ?? '').trim()))
66
+ continue;
67
+ const added = ['loading="lazy"'];
68
+ if (tag.name === 'img' && !find(tag, 'decoding'))
69
+ added.push('decoding="async"');
70
+ edits.push(appendAttributes(html, tag, added));
71
+ rewritten++;
72
+ }
73
+ return { html: applyEdits(html, edits), rewritten };
74
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * What `images.responsive` adds to an `<img>`: one `srcset` candidate per width, each the image's
3
+ * own URL with `spool-w=<width>`, and `sizes` when the tag has none. `widths` is a fixed list, since
4
+ * the proxy only answers a width from it; default 320, 480, 640, 960, 1280 and 1920. `sizes` defaults
5
+ * to `100vw`, which asks for the widest candidate the screen can use, so name the real layout width
6
+ * here for a site whose images fill less of the page.
7
+ */
8
+ export type ResponsiveOptions = {
9
+ widths?: readonly number[];
10
+ sizes?: string;
11
+ };
12
+ /** `ResponsiveOptions` with every default applied, the widths sorted and unique */
13
+ export type ResolvedResponsiveOptions = {
14
+ widths: readonly number[];
15
+ sizes: string;
16
+ };
17
+ /** the query parameter that names a width; the proxy removes it before the request reaches the origin */
18
+ export declare const RESPONSIVE_PARAM = "spool-w";
19
+ /** applies the defaults to `options` and refuses a width or a `sizes` it cannot use with a `ProtocolError` */
20
+ export declare function resolveResponsiveOptions(options?: ResponsiveOptions): ResolvedResponsiveOptions;
21
+ /**
22
+ * The query string with every `spool-w` parameter removed, and the width the last one named when it
23
+ * is one of `widths`. A value that is not a listed width is dropped without a width, so the request
24
+ * is answered as if it had none.
25
+ */
26
+ export declare function takeWidth(search: string, widths: readonly number[]): {
27
+ search: string;
28
+ width?: number;
29
+ };
30
+ /**
31
+ * Adds `srcset` (and `sizes`, when absent) to the `<img>` tags of `html` whose `src` is a
32
+ * same-origin URL that `paths` matches, and says how many tags changed. A tag that has `srcset`,
33
+ * `data-src` or `data-srcset`, sits inside `<picture>`, `<noscript>`, `<head>` or an HTML comment,
34
+ * names no usable `src` (empty, a data URL, another origin, a path `paths` does not match, one that
35
+ * already carries `spool-w`, or one with a space, comma, quote or fragment in it) is left alone. The
36
+ * original `src` stays as the fallback. `pageUrl` resolves a relative `src`. Everything outside the
37
+ * edited start tags stays byte for byte, and the edits are ASCII.
38
+ */
39
+ export declare function rewriteResponsive(html: string, options: ResponsiveOptions, context: {
40
+ pageUrl: string;
41
+ paths: RegExp;
42
+ }): {
43
+ html: string;
44
+ rewritten: number;
45
+ };
@@ -0,0 +1,98 @@
1
+ import { ProtocolError } from '../protocol/errors.js';
2
+ import { tagsOf } from '../trim/tokens.js';
3
+ import { appendAttributes, applyEdits, commentRanges, elementRanges, find, headRange, noscriptRanges, within } from './html.js';
4
+ /** the query parameter that names a width; the proxy removes it before the request reaches the origin */
5
+ export const RESPONSIVE_PARAM = 'spool-w';
6
+ const DEFAULT_WIDTHS = [320, 480, 640, 960, 1280, 1920];
7
+ const MAX_WIDTH = 16384;
8
+ /** applies the defaults to `options` and refuses a width or a `sizes` it cannot use with a `ProtocolError` */
9
+ export function resolveResponsiveOptions(options = {}) {
10
+ const widths = options.widths ?? DEFAULT_WIDTHS;
11
+ if (widths.length === 0 ||
12
+ !widths.every((w) => Number.isInteger(w) && w >= 1 && w <= MAX_WIDTH)) {
13
+ throw new ProtocolError('bad-route', `images responsive.widths must be a list of integers from 1 to ${MAX_WIDTH}`);
14
+ }
15
+ const sizes = (options.sizes ?? '100vw').trim();
16
+ if (sizes === '' || /[\u0000-\u001f]/.test(sizes)) {
17
+ throw new ProtocolError('bad-route', 'images responsive.sizes must be a non-empty single line');
18
+ }
19
+ return { widths: [...new Set(widths)].sort((a, b) => a - b), sizes };
20
+ }
21
+ /**
22
+ * The query string with every `spool-w` parameter removed, and the width the last one named when it
23
+ * is one of `widths`. A value that is not a listed width is dropped without a width, so the request
24
+ * is answered as if it had none.
25
+ */
26
+ export function takeWidth(search, widths) {
27
+ if (!search.includes(RESPONSIVE_PARAM))
28
+ return { search };
29
+ const kept = [];
30
+ let width;
31
+ for (const piece of search.slice(1).split('&')) {
32
+ const [name, value] = piece.split('=');
33
+ if (name !== RESPONSIVE_PARAM) {
34
+ kept.push(piece);
35
+ }
36
+ else if (value !== undefined &&
37
+ /^\d{1,5}$/.test(value) &&
38
+ widths.includes(Number(value))) {
39
+ width = Number(value);
40
+ }
41
+ }
42
+ const rest = kept.length > 0 ? `?${kept.join('&')}` : '';
43
+ return width === undefined ? { search: rest } : { search: rest, width };
44
+ }
45
+ const escape = (text) => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
46
+ /**
47
+ * Adds `srcset` (and `sizes`, when absent) to the `<img>` tags of `html` whose `src` is a
48
+ * same-origin URL that `paths` matches, and says how many tags changed. A tag that has `srcset`,
49
+ * `data-src` or `data-srcset`, sits inside `<picture>`, `<noscript>`, `<head>` or an HTML comment,
50
+ * names no usable `src` (empty, a data URL, another origin, a path `paths` does not match, one that
51
+ * already carries `spool-w`, or one with a space, comma, quote or fragment in it) is left alone. The
52
+ * original `src` stays as the fallback. `pageUrl` resolves a relative `src`. Everything outside the
53
+ * edited start tags stays byte for byte, and the edits are ASCII.
54
+ */
55
+ export function rewriteResponsive(html, options, context) {
56
+ const { widths, sizes } = resolveResponsiveOptions(options);
57
+ const page = new URL(context.pageUrl);
58
+ const tags = tagsOf(html);
59
+ const comments = commentRanges(html);
60
+ const noscripts = noscriptRanges(html, tags);
61
+ const pictures = elementRanges(html, tags, 'picture');
62
+ const head = headRange(html, tags);
63
+ const edits = [];
64
+ for (const tag of tags) {
65
+ if (tag.name !== 'img' || html[tag.end] !== '>')
66
+ continue;
67
+ if (within(comments, tag.start) || within(noscripts, tag.start))
68
+ continue;
69
+ if (within(pictures, tag.start))
70
+ continue;
71
+ if (head && tag.start >= head[0] && tag.start < head[1])
72
+ continue;
73
+ if (find(tag, 'srcset') || find(tag, 'data-src') || find(tag, 'data-srcset'))
74
+ continue;
75
+ const src = (find(tag, 'src')?.value ?? '').trim();
76
+ if (src === '' || /[\s,"'<>#]/.test(src))
77
+ continue;
78
+ let target;
79
+ try {
80
+ target = new URL(src.replace(/&amp;/gi, '&'), page);
81
+ }
82
+ catch {
83
+ continue;
84
+ }
85
+ if (target.origin !== page.origin || target.searchParams.has(RESPONSIVE_PARAM))
86
+ continue;
87
+ context.paths.lastIndex = 0;
88
+ if (!context.paths.test(target.pathname))
89
+ continue;
90
+ const joint = src.includes('?') ? '&amp;' : '?';
91
+ const candidates = widths.map((w) => `${src}${joint}${RESPONSIVE_PARAM}=${w} ${w}w`);
92
+ const added = [`srcset="${candidates.join(', ')}"`];
93
+ if (!find(tag, 'sizes'))
94
+ added.push(`sizes="${escape(sizes)}"`);
95
+ edits.push(appendAttributes(html, tag, added));
96
+ }
97
+ return { html: applyEdits(html, edits), rewritten: edits.length };
98
+ }