@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,107 @@
1
+ /**
2
+ * A short table of common third-party hosts. It is a starting point for a site to extend, not a
3
+ * claim about any vendor's behaviour: the class and remedy come from reading vendor documentation
4
+ * in the surveys and are not measured here.
5
+ */
6
+ export const KNOWN_ORIGINS = [
7
+ { suffix: 'google-analytics.com', class: 'analytics', remedy: 'defer' },
8
+ { suffix: 'analytics.google.com', class: 'analytics', remedy: 'defer' },
9
+ { suffix: 'googletagmanager.com', class: 'analytics', remedy: 'review' },
10
+ { suffix: 'cloudflareinsights.com', class: 'analytics', remedy: 'defer' },
11
+ { suffix: 'hotjar.com', class: 'analytics', remedy: 'review' },
12
+ { suffix: 'plausible.io', class: 'analytics', remedy: 'defer' },
13
+ { suffix: 'doubleclick.net', class: 'ads', remedy: 'network' },
14
+ { suffix: 'googlesyndication.com', class: 'ads', remedy: 'network' },
15
+ { suffix: 'onetrust.com', class: 'consent', remedy: 'network' },
16
+ { suffix: 'cookiebot.com', class: 'consent', remedy: 'network' },
17
+ { suffix: 'fonts.googleapis.com', class: 'fonts', remedy: 'self-host' },
18
+ { suffix: 'fonts.gstatic.com', class: 'fonts', remedy: 'cache' },
19
+ { suffix: 'cdnjs.cloudflare.com', class: 'cdn', remedy: 'cache' },
20
+ { suffix: 'cdn.jsdelivr.net', class: 'cdn', remedy: 'cache' },
21
+ { suffix: 'unpkg.com', class: 'cdn', remedy: 'cache' },
22
+ { suffix: 'youtube.com', class: 'video', remedy: 'network' },
23
+ { suffix: 'ytimg.com', class: 'video', remedy: 'network' },
24
+ { suffix: 'vimeo.com', class: 'video', remedy: 'network' },
25
+ { suffix: 'maps.googleapis.com', class: 'maps', remedy: 'network' },
26
+ { suffix: 'facebook.net', class: 'social', remedy: 'network' },
27
+ { suffix: 'twitter.com', class: 'social', remedy: 'network' },
28
+ { suffix: 'intercom.io', class: 'chat', remedy: 'network' },
29
+ { suffix: 'drift.com', class: 'chat', remedy: 'network' }
30
+ ];
31
+ /** the class and remedy of an origin: the longest table suffix its host ends with, else unknown */
32
+ export function classifyOrigin(origin, table = KNOWN_ORIGINS) {
33
+ let host;
34
+ try {
35
+ host = new URL(origin).hostname.toLowerCase();
36
+ }
37
+ catch {
38
+ return { class: 'unknown', remedy: 'review' };
39
+ }
40
+ let best;
41
+ for (const entry of table) {
42
+ if (host === entry.suffix || host.endsWith(`.${entry.suffix}`)) {
43
+ if (!best || entry.suffix.length > best.suffix.length)
44
+ best = entry;
45
+ }
46
+ }
47
+ return best
48
+ ? { class: best.class, remedy: best.remedy }
49
+ : { class: 'unknown', remedy: 'review' };
50
+ }
51
+ /**
52
+ * What blocks zero-network on this site: for each third-party origin the views that loaded from it,
53
+ * ranked by how many views it alone blocks. Pass the views from `viewsOf`, which joins each page's
54
+ * loads report to its view. The counts are an upper bound on network requests, since a cross-origin
55
+ * resource timing entry says nothing about cache hits without `Timing-Allow-Origin`.
56
+ */
57
+ export function thirdPartyReport(views, table = KNOWN_ORIGINS) {
58
+ const rows = new Map();
59
+ let reported = 0;
60
+ let clean = 0;
61
+ let unnamed = 0;
62
+ for (const view of views) {
63
+ if (view.crossOriginLoads === null)
64
+ continue;
65
+ reported += 1;
66
+ if (view.crossOriginLoads === 0) {
67
+ clean += 1;
68
+ continue;
69
+ }
70
+ const named = Object.entries(view.crossOriginOrigins ?? {});
71
+ if (named.length === 0) {
72
+ unnamed += 1;
73
+ continue;
74
+ }
75
+ for (const [origin, count] of named) {
76
+ const row = rows.get(origin) ?? { views: 0, loads: 0, solo: 0 };
77
+ row.views += 1;
78
+ row.loads += count;
79
+ if (named.length === 1)
80
+ row.solo += 1;
81
+ rows.set(origin, row);
82
+ }
83
+ }
84
+ return {
85
+ views: views.length,
86
+ reported,
87
+ clean,
88
+ blocked: reported - clean,
89
+ unnamed,
90
+ rows: [...rows]
91
+ .map(([origin, row]) => {
92
+ const kind = classifyOrigin(origin, table);
93
+ return {
94
+ origin,
95
+ class: kind.class,
96
+ remedy: kind.remedy,
97
+ views: row.views,
98
+ loads: row.loads,
99
+ share: row.views / reported,
100
+ soloViews: row.solo
101
+ };
102
+ })
103
+ .sort((a, b) => b.soloViews - a.soloViews ||
104
+ b.views - a.views ||
105
+ (a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0))
106
+ };
107
+ }
@@ -0,0 +1,140 @@
1
+ import { type Engine, type TimedView } from '../protocol/view.js';
2
+ /**
3
+ * Which views a measure reads. `served` takes the views the worker answered, where `Z` is real;
4
+ * `shadow` takes the views it only decided on, where `Z` is what serving would have been.
5
+ */
6
+ export type Basis = 'served' | 'shadow';
7
+ /** the server's work over one interval: handler milliseconds and request counts, by route */
8
+ export type WorkSample = {
9
+ /** epoch milliseconds the interval began */
10
+ start: number;
11
+ seconds: number;
12
+ busyMs: Record<string, number>;
13
+ requests: Record<string, number>;
14
+ };
15
+ /** the routes spool's own requests land on; their work is what spool costs the origin */
16
+ export declare const OVERHEAD_ROUTES: readonly string[];
17
+ /** `Z_annual` over the given window: strict zero-network views over all views, null with no views */
18
+ export declare function zAnnual(views: readonly TimedView[], basis?: Basis): number | null;
19
+ /** the three factors of `Z` for one group of views; each is null when its denominator is zero */
20
+ export type Factors = {
21
+ views: number;
22
+ local: number;
23
+ z: number | null;
24
+ /** views on a route the worker may serve, over all views */
25
+ pEligible: number | null;
26
+ /** of those, views with a stored copy */
27
+ pWarm: number | null;
28
+ /** of those, views shown with no request */
29
+ pUsable: number | null;
30
+ };
31
+ /** `P_eligible`, `P_warm` and `P_usable` as a chain: their product is `z` */
32
+ export declare function factors(views: readonly TimedView[], basis?: Basis): Factors;
33
+ /** {@link factors} for each engine that has views, in name order */
34
+ export declare function factorsByEngine(views: readonly TimedView[], basis?: Basis): Array<Factors & {
35
+ engine: Engine;
36
+ }>;
37
+ /** one UTC day of {@link zDaily} */
38
+ export type DailyZ = {
39
+ /** `YYYY-MM-DD`, UTC */
40
+ day: string;
41
+ views: number;
42
+ local: number;
43
+ /** requests to spool's own routes that day: syncs, artifact fetches and beacon flushes */
44
+ overhead: number;
45
+ /** local views less overhead requests, over all views; negative when spool cost more than it saved */
46
+ z: number | null;
47
+ };
48
+ /**
49
+ * `Z_daily`: each day's local views net of the requests spool itself sent the Worker, over that
50
+ * day's views. A local view removes one request; a sync, an artifact fetch or a flush adds one.
51
+ */
52
+ export declare function zDaily(views: readonly TimedView[], samples: readonly WorkSample[], basis?: Basis): DailyZ[];
53
+ /** what {@link zPeakWork} computed, with the terms it divided */
54
+ export type PeakWork = {
55
+ z: number | null;
56
+ /** how many intervals were taken as the busiest */
57
+ intervals: number;
58
+ /** origin work the local views avoided in those intervals, in handler milliseconds */
59
+ avoided: number;
60
+ /** handler milliseconds spent on spool's own routes in those intervals */
61
+ overhead: number;
62
+ /** origin work without spool: work done on other routes plus work avoided */
63
+ baseline: number;
64
+ /** local views that could not be priced: outside every interval, or on a route never answered */
65
+ unpriced: number;
66
+ };
67
+ /**
68
+ * `Z_peak_work`: over the busiest intervals, the origin work local views avoided less the work
69
+ * spool's own routes cost, over the work the origin would have done without spool. A local view
70
+ * is priced at the series-wide mean handler time of its route. Intervals are ranked by baseline
71
+ * work and `busiestShare` of them, at least one, are taken.
72
+ */
73
+ export declare function zPeakWork(views: readonly TimedView[], samples: readonly WorkSample[], options?: {
74
+ basis?: Basis;
75
+ busiestShare?: number;
76
+ }): PeakWork;
77
+ /** shadow results for one route */
78
+ export type RouteMismatches = {
79
+ route: string;
80
+ shadowViews: number;
81
+ /** views where a local render existed to compare */
82
+ compared: number;
83
+ mismatches: number;
84
+ };
85
+ /** shadow views, comparisons and mismatches per route, in route order */
86
+ export declare function mismatchesByRoute(views: readonly TimedView[]): RouteMismatches[];
87
+ /** what the worker's ledger holds per entry that the catalogue figures read */
88
+ export type CatalogueLedgerRow = {
89
+ id: string;
90
+ catalogueBytes: number;
91
+ catalogueViews: number;
92
+ };
93
+ /** what a catalogue sent, what a view used and what the views saved */
94
+ export type CatalogueFigures = {
95
+ /** entries the worker received in catalogue bundles */
96
+ sent: number;
97
+ /** entries that served a view with no request */
98
+ used: number;
99
+ /** views the catalogue answered locally */
100
+ hits: number;
101
+ /** views in the basis */
102
+ views: number;
103
+ /** `hits` over `views`; null with no views */
104
+ hitShare: number | null;
105
+ /** JSON bytes of the entries received, as the ledger counts them */
106
+ bytesSent: number;
107
+ /** `hits` times `documentBytes` */
108
+ bytesSaved: number;
109
+ /** `bytesSaved` less `bytesSent`; negative when the catalogue moved more than it kept off the wire */
110
+ bytesNet: number;
111
+ };
112
+ /**
113
+ * Catalogue figures from the views the sink holds and the worker's ledger entries. A view is a hit
114
+ * when its reason is `catalogue`; the ledger says how many entries arrived, how many served a view
115
+ * and what they weighed. `documentBytes` is what a hit keeps off the wire, `DOCUMENT_BYTES` (L1)
116
+ * unless the site knows its own, so `bytesSaved` is a scenario figure (L3) until shadow views
117
+ * measure the use share. The ledger counts uncompressed JSON text and a document is counted on
118
+ * the wire, so `bytesNet` compares unlike units.
119
+ */
120
+ export declare function catalogueFigures(views: readonly TimedView[], ledger: {
121
+ entries: readonly CatalogueLedgerRow[];
122
+ }, options?: {
123
+ basis?: Basis;
124
+ documentBytes?: number;
125
+ }): CatalogueFigures;
126
+ /** views that came from `from` and went to `route` */
127
+ export type Transition = {
128
+ from: string;
129
+ route: string;
130
+ views: number;
131
+ };
132
+ /** how many views came from each referrer, and the pairs; `from` may be a route pattern or `external` */
133
+ export type Transitions = {
134
+ pairs: Transition[];
135
+ byFrom: Record<string, number>;
136
+ };
137
+ /** counts per `(from, route)` pair and per `from`; a view with no `from` counts in neither */
138
+ export declare function transitions(views: readonly TimedView[]): Transitions;
139
+ /** the share of views from `from` that went to each route, in route order; empty when none came from it */
140
+ export declare function nextShare(views: readonly TimedView[], from: string): Record<string, number>;
@@ -0,0 +1,228 @@
1
+ import { funnelOf } from '../protocol/view.js';
2
+ import { DOCUMENT_BYTES } from './inputs.js';
3
+ /** the routes spool's own requests land on; their work is what spool costs the origin */
4
+ export const OVERHEAD_ROUTES = [
5
+ '/.spool/sync',
6
+ '/.spool/artifact',
7
+ '/.spool/beacon'
8
+ ];
9
+ const DAY_MS = 86_400_000;
10
+ const inBasis = (view, basis) => basis === 'shadow' ? view.tier === 'shadow' : view.tier !== 'shadow';
11
+ const isLocal = (view) => funnelOf(view) === 'local';
12
+ function ratio(part, whole) {
13
+ return whole === 0 ? null : part / whole;
14
+ }
15
+ /** `Z_annual` over the given window: strict zero-network views over all views, null with no views */
16
+ export function zAnnual(views, basis = 'served') {
17
+ const pool = views.filter((v) => inBasis(v, basis));
18
+ return ratio(pool.filter(isLocal).length, pool.length);
19
+ }
20
+ /** `P_eligible`, `P_warm` and `P_usable` as a chain: their product is `z` */
21
+ export function factors(views, basis = 'served') {
22
+ const pool = views.filter((v) => inBasis(v, basis));
23
+ const stages = pool.map(funnelOf);
24
+ const eligible = stages.filter((s) => s !== 'ineligible').length;
25
+ const warm = stages.filter((s) => s === 'unusable' || s === 'local').length;
26
+ const local = stages.filter((s) => s === 'local').length;
27
+ return {
28
+ views: pool.length,
29
+ local,
30
+ z: ratio(local, pool.length),
31
+ pEligible: ratio(eligible, pool.length),
32
+ pWarm: ratio(warm, eligible),
33
+ pUsable: ratio(local, warm)
34
+ };
35
+ }
36
+ /** {@link factors} for each engine that has views, in name order */
37
+ export function factorsByEngine(views, basis = 'served') {
38
+ const engines = [...new Set(views.filter((v) => inBasis(v, basis)).map((v) => v.engine))];
39
+ return engines.sort().map((engine) => ({
40
+ engine,
41
+ ...factors(views.filter((v) => v.engine === engine), basis)
42
+ }));
43
+ }
44
+ const dayOf = (ms) => new Date(Math.floor(ms / DAY_MS) * DAY_MS).toISOString().slice(0, 10);
45
+ /**
46
+ * `Z_daily`: each day's local views net of the requests spool itself sent the Worker, over that
47
+ * day's views. A local view removes one request; a sync, an artifact fetch or a flush adds one.
48
+ */
49
+ export function zDaily(views, samples, basis = 'served') {
50
+ const days = new Map();
51
+ const row = (day) => {
52
+ const found = days.get(day) ?? { views: 0, local: 0, overhead: 0 };
53
+ days.set(day, found);
54
+ return found;
55
+ };
56
+ for (const view of views) {
57
+ if (!inBasis(view, basis))
58
+ continue;
59
+ const entry = row(dayOf(view.at));
60
+ entry.views += 1;
61
+ if (isLocal(view))
62
+ entry.local += 1;
63
+ }
64
+ for (const sample of samples) {
65
+ const entry = row(dayOf(sample.start));
66
+ for (const route of OVERHEAD_ROUTES)
67
+ entry.overhead += sample.requests[route] ?? 0;
68
+ }
69
+ return [...days]
70
+ .sort(([a], [b]) => (a < b ? -1 : 1))
71
+ .map(([day, e]) => ({ day, ...e, z: ratio(e.local - e.overhead, e.views) }));
72
+ }
73
+ /** the index of the interval holding `at`, or -1; `ordered` is sorted by start */
74
+ function locate(ordered, at) {
75
+ let low = 0;
76
+ let high = ordered.length - 1;
77
+ while (low <= high) {
78
+ const mid = (low + high) >> 1;
79
+ const sample = ordered[mid];
80
+ if (at < sample.start)
81
+ high = mid - 1;
82
+ else if (at >= sample.start + sample.seconds * 1000)
83
+ low = mid + 1;
84
+ else
85
+ return mid;
86
+ }
87
+ return -1;
88
+ }
89
+ /**
90
+ * `Z_peak_work`: over the busiest intervals, the origin work local views avoided less the work
91
+ * spool's own routes cost, over the work the origin would have done without spool. A local view
92
+ * is priced at the series-wide mean handler time of its route. Intervals are ranked by baseline
93
+ * work and `busiestShare` of them, at least one, are taken.
94
+ */
95
+ export function zPeakWork(views, samples, options = {}) {
96
+ const basis = options.basis ?? 'served';
97
+ const share = options.busiestShare ?? 0.1;
98
+ const ordered = [...samples].sort((a, b) => a.start - b.start);
99
+ const busy = new Map();
100
+ const count = new Map();
101
+ for (const sample of ordered) {
102
+ for (const [route, ms] of Object.entries(sample.busyMs)) {
103
+ busy.set(route, (busy.get(route) ?? 0) + ms);
104
+ }
105
+ for (const [route, n] of Object.entries(sample.requests)) {
106
+ count.set(route, (count.get(route) ?? 0) + n);
107
+ }
108
+ }
109
+ const avoided = ordered.map(() => 0);
110
+ let unpriced = 0;
111
+ for (const view of views) {
112
+ if (!inBasis(view, basis) || !isLocal(view))
113
+ continue;
114
+ const at = locate(ordered, view.at);
115
+ const requests = count.get(view.route) ?? 0;
116
+ if (at < 0 || requests === 0) {
117
+ unpriced += 1;
118
+ continue;
119
+ }
120
+ avoided[at] = avoided[at] + busy.get(view.route) / requests;
121
+ }
122
+ const rows = ordered.map((sample, i) => {
123
+ let overhead = 0;
124
+ let actual = 0;
125
+ for (const [route, ms] of Object.entries(sample.busyMs)) {
126
+ if (OVERHEAD_ROUTES.includes(route))
127
+ overhead += ms;
128
+ else
129
+ actual += ms;
130
+ }
131
+ return {
132
+ start: sample.start,
133
+ avoided: avoided[i],
134
+ overhead,
135
+ baseline: actual + avoided[i]
136
+ };
137
+ });
138
+ const take = rows.length === 0 ? 0 : Math.max(1, Math.ceil(rows.length * share));
139
+ const busiest = [...rows]
140
+ .sort((a, b) => b.baseline - a.baseline || a.start - b.start)
141
+ .slice(0, take);
142
+ const sum = (pick) => busiest.reduce((total, r) => total + pick(r), 0);
143
+ const baseline = sum((r) => r.baseline);
144
+ const saved = sum((r) => r.avoided);
145
+ const spent = sum((r) => r.overhead);
146
+ return {
147
+ z: ratio(saved - spent, baseline),
148
+ intervals: take,
149
+ avoided: saved,
150
+ overhead: spent,
151
+ baseline,
152
+ unpriced
153
+ };
154
+ }
155
+ /** shadow views, comparisons and mismatches per route, in route order */
156
+ export function mismatchesByRoute(views) {
157
+ const routes = new Map();
158
+ for (const view of views) {
159
+ if (view.tier !== 'shadow')
160
+ continue;
161
+ const entry = routes.get(view.route) ?? {
162
+ route: view.route,
163
+ shadowViews: 0,
164
+ compared: 0,
165
+ mismatches: 0
166
+ };
167
+ entry.shadowViews += 1;
168
+ if (view.mismatch !== null)
169
+ entry.compared += 1;
170
+ if (view.mismatch === true)
171
+ entry.mismatches += 1;
172
+ routes.set(view.route, entry);
173
+ }
174
+ return [...routes.values()].sort((a, b) => (a.route < b.route ? -1 : 1));
175
+ }
176
+ /**
177
+ * Catalogue figures from the views the sink holds and the worker's ledger entries. A view is a hit
178
+ * when its reason is `catalogue`; the ledger says how many entries arrived, how many served a view
179
+ * and what they weighed. `documentBytes` is what a hit keeps off the wire, `DOCUMENT_BYTES` (L1)
180
+ * unless the site knows its own, so `bytesSaved` is a scenario figure (L3) until shadow views
181
+ * measure the use share. The ledger counts uncompressed JSON text and a document is counted on
182
+ * the wire, so `bytesNet` compares unlike units.
183
+ */
184
+ export function catalogueFigures(views, ledger, options = {}) {
185
+ const pool = views.filter((v) => inBasis(v, options.basis ?? 'served'));
186
+ const hits = pool.filter((v) => v.reason === 'catalogue').length;
187
+ const sent = ledger.entries.filter((e) => e.catalogueBytes > 0);
188
+ const bytesSent = sent.reduce((total, e) => total + e.catalogueBytes, 0);
189
+ const bytesSaved = hits * (options.documentBytes ?? DOCUMENT_BYTES.value);
190
+ return {
191
+ sent: sent.length,
192
+ used: ledger.entries.filter((e) => e.catalogueViews > 0).length,
193
+ hits,
194
+ views: pool.length,
195
+ hitShare: ratio(hits, pool.length),
196
+ bytesSent,
197
+ bytesSaved,
198
+ bytesNet: bytesSaved - bytesSent
199
+ };
200
+ }
201
+ /** counts per `(from, route)` pair and per `from`; a view with no `from` counts in neither */
202
+ export function transitions(views) {
203
+ const pairs = new Map();
204
+ const byFrom = Object.create(null);
205
+ for (const view of views) {
206
+ if (view.from === undefined)
207
+ continue;
208
+ const key = JSON.stringify([view.from, view.route]);
209
+ const entry = pairs.get(key) ?? { from: view.from, route: view.route, views: 0 };
210
+ entry.views += 1;
211
+ pairs.set(key, entry);
212
+ byFrom[view.from] = (byFrom[view.from] ?? 0) + 1;
213
+ }
214
+ const sorted = [...pairs.values()].sort((a, b) => a.from === b.from ? (a.route < b.route ? -1 : 1) : a.from < b.from ? -1 : 1);
215
+ return { pairs: sorted, byFrom };
216
+ }
217
+ /** the share of views from `from` that went to each route, in route order; empty when none came from it */
218
+ export function nextShare(views, from) {
219
+ const { pairs, byFrom } = transitions(views);
220
+ const total = byFrom[from];
221
+ const out = {};
222
+ if (!total)
223
+ return out;
224
+ for (const pair of pairs)
225
+ if (pair.from === from)
226
+ out[pair.route] = pair.views / total;
227
+ return out;
228
+ }
@@ -0,0 +1,81 @@
1
+ import type { Row } from './measurement.js';
2
+ /** the quartiles, median and mean of a list of per-page figures */
3
+ export type Quartiles = {
4
+ n: number;
5
+ p25: number;
6
+ median: number;
7
+ p75: number;
8
+ mean: number;
9
+ };
10
+ /** {@link Quartiles} of a list, or null when it is empty */
11
+ export declare function quartiles(values: readonly number[]): Quartiles | null;
12
+ /** bytes a trim saves on one kind of view, and the attributional joules those bytes carry */
13
+ export type TrimSaving = {
14
+ bytes: Quartiles;
15
+ joules: Quartiles;
16
+ };
17
+ /** what the trimmed experiment measured, per site and pooled */
18
+ export type TrimFigures = {
19
+ sites: Array<{
20
+ site: string;
21
+ cold: TrimSaving | null;
22
+ first: TrimSaving | null;
23
+ /** the share of the site's stylesheet bytes (brotli 5) the trim removes */
24
+ fileShare: number;
25
+ }>;
26
+ /** the home page of each site, a cold view */
27
+ cold: TrimSaving;
28
+ /** each internal page, the first view of it in a visit */
29
+ first: TrimSaving;
30
+ files: {
31
+ count: number;
32
+ trimmed: number;
33
+ br5: number;
34
+ trimmedBr5: number;
35
+ };
36
+ /** Oracle A: used rules the trimmed text lost */
37
+ rules: {
38
+ pages: number;
39
+ used: number;
40
+ falseRemovals: number;
41
+ offenders: string[];
42
+ };
43
+ /** Oracle B: pixels that differ from the original CSS, and the same page against itself */
44
+ render: {
45
+ pages: number;
46
+ errors: number;
47
+ /** pages whose trimmed screenshot equals the original to the pixel */
48
+ identical: number;
49
+ /** pages whose second screenshot of the original equals the first to the pixel */
50
+ controlIdentical: number;
51
+ /** pages where the trimmed arm differed by more pixels than the control did */
52
+ beyondControl: number;
53
+ /** pages where the trimmed arm differed and the control did not */
54
+ trimmedOnly: number;
55
+ maxTrimmed: number;
56
+ maxControl: number;
57
+ };
58
+ /** leave-one-out over the internal pages */
59
+ leaveOneOut: {
60
+ pages: number;
61
+ guardFired: number;
62
+ /** pages the guard let through that link a trimmed file, Oracle A on them */
63
+ unguarded: number;
64
+ unguardedRules: number;
65
+ falseRemovals: number;
66
+ pagesWithFalseRemovals: number;
67
+ };
68
+ };
69
+ /** the figures of a trimmed reading's rows */
70
+ export declare function trimFigures(rows: readonly Row[]): TrimFigures;
71
+ /** used share of one kind of same-origin file, at load and after one scroll, per page */
72
+ export type CoverageFigures = {
73
+ cssLoad: Quartiles | null;
74
+ cssScroll: Quartiles | null;
75
+ jsLoad: Quartiles | null;
76
+ jsScroll: Quartiles | null;
77
+ };
78
+ /** coverage shares of the coverage reading (`measurements/trim/<date>.json`), pooled over its pages */
79
+ export declare function coverageFigures(rows: readonly Row[]): CoverageFigures & {
80
+ pages: number;
81
+ };
@@ -0,0 +1,105 @@
1
+ import { quantile } from './derive.js';
2
+ import { attributionalJoules } from './model.js';
3
+ /** {@link Quartiles} of a list, or null when it is empty */
4
+ export function quartiles(values) {
5
+ if (values.length === 0)
6
+ return null;
7
+ return {
8
+ n: values.length,
9
+ p25: quantile(values, 0.25),
10
+ median: quantile(values, 0.5),
11
+ p75: quantile(values, 0.75),
12
+ mean: values.reduce((sum, v) => sum + v, 0) / values.length
13
+ };
14
+ }
15
+ function saving(bytes) {
16
+ const b = quartiles(bytes);
17
+ const j = quartiles(bytes.map((n) => attributionalJoules(n)));
18
+ return b && j ? { bytes: b, joules: j } : null;
19
+ }
20
+ const sitesOf = (rows) => rows;
21
+ const pixels = (cell) => cell && 'differing' in cell ? cell.differing : null;
22
+ /** the figures of a trimmed reading's rows */
23
+ export function trimFigures(rows) {
24
+ const sites = sitesOf(rows);
25
+ const home = (s) => s.pages.filter((p) => p.kind === 'home');
26
+ const internal = (s) => s.pages.filter((p) => p.kind === 'internal');
27
+ const bytesOf = (pages) => pages.map((p) => p.saved.br5Saved);
28
+ const pages = sites.flatMap((s) => s.pages);
29
+ const files = sites.flatMap((s) => s.files);
30
+ const cold = saving(sites.flatMap((s) => bytesOf(home(s))));
31
+ const first = saving(sites.flatMap((s) => bytesOf(internal(s))));
32
+ if (!cold || !first)
33
+ throw new RangeError('the reading has no home page or no internal page');
34
+ const lost = pages.flatMap((p) => p.oracleA.lost);
35
+ const shots = pages.flatMap((p) => (p.oracleB && 'control' in p.oracleB ? [p.oracleB] : []));
36
+ const pairs = shots.flatMap((s) => {
37
+ const control = pixels(s.control);
38
+ const trimmed = pixels(s.trimmed);
39
+ return control === null || trimmed === null ? [] : [{ control, trimmed }];
40
+ });
41
+ const loo = pages.flatMap((p) => (p.leaveOneOut ? [p.leaveOneOut] : []));
42
+ const checked = loo.flatMap((l) => (l.oracleA ? [l.oracleA] : []));
43
+ return {
44
+ sites: sites.map((s) => ({
45
+ site: s.site,
46
+ cold: saving(bytesOf(home(s))),
47
+ first: saving(bytesOf(internal(s))),
48
+ fileShare: 1 -
49
+ s.files.reduce((t, f) => t + f.trimmedBr5, 0) /
50
+ Math.max(1, s.files.reduce((t, f) => t + f.br5, 0))
51
+ })),
52
+ cold,
53
+ first,
54
+ files: {
55
+ count: files.length,
56
+ trimmed: files.filter((f) => f.trimmed).length,
57
+ br5: files.reduce((t, f) => t + f.br5, 0),
58
+ trimmedBr5: files.reduce((t, f) => t + f.trimmedBr5, 0)
59
+ },
60
+ rules: {
61
+ pages: pages.length,
62
+ used: pages.reduce((t, p) => t + p.oracleA.used, 0),
63
+ falseRemovals: lost.length,
64
+ offenders: lost.map((l) => `${l.file} ${l.selector}`)
65
+ },
66
+ render: {
67
+ pages: pairs.length,
68
+ errors: pages.filter((p) => p.oracleB !== null).length - pairs.length,
69
+ identical: pairs.filter((p) => p.trimmed === 0).length,
70
+ controlIdentical: pairs.filter((p) => p.control === 0).length,
71
+ beyondControl: pairs.filter((p) => p.trimmed > p.control).length,
72
+ trimmedOnly: pairs.filter((p) => p.trimmed > 0 && p.control === 0).length,
73
+ maxTrimmed: Math.max(0, ...pairs.map((p) => p.trimmed)),
74
+ maxControl: Math.max(0, ...pairs.map((p) => p.control))
75
+ },
76
+ leaveOneOut: {
77
+ pages: loo.length,
78
+ guardFired: loo.filter((l) => l.guardFired).length,
79
+ unguarded: checked.length,
80
+ unguardedRules: checked.reduce((t, c) => t + c.used, 0),
81
+ falseRemovals: checked.reduce((t, c) => t + c.falseRemovals, 0),
82
+ pagesWithFalseRemovals: checked.filter((c) => c.falseRemovals > 0).length
83
+ }
84
+ };
85
+ }
86
+ function shares(pages, kind, field) {
87
+ return pages.flatMap((page) => {
88
+ const same = page.files.filter((f) => f.origin === 'same' && f.kind === kind);
89
+ const total = same.reduce((t, f) => t + f.raw, 0);
90
+ return total > 0 ? [same.reduce((t, f) => t + f[field], 0) / total] : [];
91
+ });
92
+ }
93
+ /** coverage shares of the coverage reading (`measurements/trim/<date>.json`), pooled over its pages */
94
+ export function coverageFigures(rows) {
95
+ const pages = rows
96
+ .flatMap((r) => r.pages)
97
+ .filter((p) => p.ok === true);
98
+ return {
99
+ pages: pages.length,
100
+ cssLoad: quartiles(shares(pages, 'css', 'usedLoad')),
101
+ cssScroll: quartiles(shares(pages, 'css', 'usedScroll')),
102
+ jsLoad: quartiles(shares(pages, 'js', 'usedLoad')),
103
+ jsScroll: quartiles(shares(pages, 'js', 'usedScroll'))
104
+ };
105
+ }
@@ -0,0 +1,20 @@
1
+ import type { Artifact } from '../protocol/artifact.js';
2
+ import { type CatalogueAsk } from '../protocol/beacon.js';
3
+ import type { Sink } from './sink.js';
4
+ /** the largest flush body the server reads, in characters */
5
+ export declare const MAX_BEACON_BODY = 262144;
6
+ /** builds the public artifacts for the paths a flush asked for; paths it cannot serve are left out */
7
+ export type Provide = (paths: readonly string[]) => Promise<Artifact[]>;
8
+ /** the entries chosen for one catalogue request; `partition` is set when any is a principal entry */
9
+ export type Bundle = {
10
+ artifacts: Artifact[];
11
+ partition?: string;
12
+ };
13
+ /** chooses the entries for the page a flush named */
14
+ export type Catalogue = (ask: CatalogueAsk) => Promise<Bundle>;
15
+ /**
16
+ * Accepts a batched flush at `/.spool/beacon` and hands its events to the sink. A flush that
17
+ * asked for artifacts or a catalogue is answered with them in a 200; any other is a 204. A
18
+ * request with `Save-Data: on` is never sent a catalogue.
19
+ */
20
+ export declare function respondBeacon(request: Request, sink: Sink | undefined, provide?: Provide, catalogue?: Catalogue): Promise<Response>;