@drupflare/spool 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/README.md +499 -43
  2. package/dist/cdn/client.js +1 -1
  3. package/dist/cdn/manifest.json +7 -7
  4. package/dist/cdn/spool-sw.js +1 -1
  5. package/dist/client/activity.d.ts +37 -0
  6. package/dist/client/activity.js +114 -0
  7. package/dist/client/entry.js +34 -1
  8. package/dist/client/index.d.ts +1 -0
  9. package/dist/client/index.js +1 -0
  10. package/dist/client/register.d.ts +23 -1
  11. package/dist/client/register.js +53 -7
  12. package/dist/media/embeds.d.ts +3 -2
  13. package/dist/media/embeds.js +16 -1
  14. package/dist/protocol/config.d.ts +16 -1
  15. package/dist/protocol/config.js +3 -1
  16. package/dist/protocol/dataset.d.ts +183 -0
  17. package/dist/protocol/dataset.js +206 -0
  18. package/dist/protocol/envelope.d.ts +3 -0
  19. package/dist/protocol/envelope.js +14 -3
  20. package/dist/protocol/errors.d.ts +1 -1
  21. package/dist/protocol/graph.d.ts +23 -4
  22. package/dist/protocol/graph.js +34 -3
  23. package/dist/protocol/hash.d.ts +2 -0
  24. package/dist/protocol/hash.js +8 -0
  25. package/dist/protocol/index.d.ts +7 -0
  26. package/dist/protocol/index.js +7 -0
  27. package/dist/protocol/inline.d.ts +14 -0
  28. package/dist/protocol/inline.js +43 -0
  29. package/dist/protocol/navigation.d.ts +81 -0
  30. package/dist/protocol/navigation.js +249 -0
  31. package/dist/protocol/normalise.d.ts +4 -3
  32. package/dist/protocol/normalise.js +6 -4
  33. package/dist/protocol/plan.d.ts +100 -0
  34. package/dist/protocol/plan.js +661 -0
  35. package/dist/protocol/provision.d.ts +52 -1
  36. package/dist/protocol/provision.js +53 -5
  37. package/dist/protocol/query.d.ts +141 -0
  38. package/dist/protocol/query.js +252 -0
  39. package/dist/protocol/route.d.ts +85 -5
  40. package/dist/protocol/route.js +91 -0
  41. package/dist/protocol/write.d.ts +146 -0
  42. package/dist/protocol/write.js +101 -0
  43. package/dist/proxy/bases.d.ts +53 -0
  44. package/dist/proxy/bases.js +76 -0
  45. package/dist/proxy/index.d.ts +1 -0
  46. package/dist/proxy/index.js +1 -0
  47. package/dist/proxy/proxy.js +8 -2
  48. package/dist/report/capacity.d.ts +59 -0
  49. package/dist/report/capacity.js +76 -0
  50. package/dist/report/channels.d.ts +60 -0
  51. package/dist/report/channels.js +65 -0
  52. package/dist/report/dataset.d.ts +48 -0
  53. package/dist/report/dataset.js +93 -0
  54. package/dist/report/derive.d.ts +285 -0
  55. package/dist/report/derive.js +676 -1
  56. package/dist/report/economics.d.ts +11 -1
  57. package/dist/report/economics.js +19 -1
  58. package/dist/report/index.d.ts +5 -0
  59. package/dist/report/index.js +5 -0
  60. package/dist/report/inputs.d.ts +97 -0
  61. package/dist/report/inputs.js +133 -0
  62. package/dist/report/institution.d.ts +284 -0
  63. package/dist/report/institution.js +225 -0
  64. package/dist/report/ledger.d.ts +28 -0
  65. package/dist/report/ledger.js +30 -0
  66. package/dist/report/loops.d.ts +73 -0
  67. package/dist/report/loops.js +101 -0
  68. package/dist/report/measurement.d.ts +1 -1
  69. package/dist/report/measurement.js +6 -1
  70. package/dist/report/model.d.ts +2 -0
  71. package/dist/report/model.js +4 -0
  72. package/dist/report/thirdparty.d.ts +57 -0
  73. package/dist/report/thirdparty.js +111 -0
  74. package/dist/report/traffic.d.ts +11 -2
  75. package/dist/report/traffic.js +13 -3
  76. package/dist/report/trim.d.ts +56 -0
  77. package/dist/report/trim.js +83 -1
  78. package/dist/server/dataset.d.ts +48 -0
  79. package/dist/server/dataset.js +308 -0
  80. package/dist/server/embedded.d.ts +3 -3
  81. package/dist/server/embedded.js +3 -3
  82. package/dist/server/index.d.ts +3 -0
  83. package/dist/server/index.js +3 -0
  84. package/dist/server/spool.d.ts +40 -0
  85. package/dist/server/spool.js +184 -23
  86. package/dist/server/write.d.ts +27 -0
  87. package/dist/server/write.js +127 -0
  88. package/dist/sw/analytics.d.ts +6 -0
  89. package/dist/sw/analytics.js +14 -0
  90. package/dist/sw/dataset-sync.d.ts +76 -0
  91. package/dist/sw/dataset-sync.js +149 -0
  92. package/dist/sw/dataset.d.ts +91 -0
  93. package/dist/sw/dataset.js +318 -0
  94. package/dist/sw/graph/index.d.ts +31 -1
  95. package/dist/sw/graph/index.js +57 -5
  96. package/dist/sw/graph/invalidate.d.ts +15 -3
  97. package/dist/sw/graph/invalidate.js +42 -4
  98. package/dist/sw/idb.js +78 -9
  99. package/dist/sw/partition.d.ts +6 -1
  100. package/dist/sw/partition.js +21 -2
  101. package/dist/sw/principal-dataset.d.ts +64 -0
  102. package/dist/sw/principal-dataset.js +254 -0
  103. package/dist/sw/render.d.ts +8 -1
  104. package/dist/sw/render.js +28 -1
  105. package/dist/sw/replica.d.ts +14 -3
  106. package/dist/sw/replica.js +46 -5
  107. package/dist/sw/router.js +2 -2
  108. package/dist/sw/runtime.d.ts +43 -2
  109. package/dist/sw/runtime.js +440 -29
  110. package/dist/sw/seal.d.ts +13 -0
  111. package/dist/sw/seal.js +13 -4
  112. package/dist/sw/static.d.ts +18 -0
  113. package/dist/sw/static.js +84 -1
  114. package/dist/sw/storage.d.ts +51 -1
  115. package/dist/sw/storage.js +33 -1
  116. package/dist/sw/write.d.ts +107 -0
  117. package/dist/sw/write.js +442 -0
  118. package/package.json +5 -2
@@ -0,0 +1,225 @@
1
+ import { egridGPerKwh, electricityPrice, tonnesFromMwh, usdForMwh } from './economics.js';
2
+ import { EMBER_US_G_PER_KWH, FIRST_VIEW_BYTES, FIRST_VIEW_SHARE, GOAL_HIGH_SHARE, GOAL_SHARES, HOSTING_KWH_PER_SITE, REPEAT_VIEW_BYTES, SWD_V4, WATER_DIRECT, WATER_INDIRECT, WATER_INDIRECT_LBNL } from './inputs.js';
3
+ import { serverYearMWh } from './model.js';
4
+ import { mismatchesByRoute } from './traffic.js';
5
+ /** what the worker does not count; the trust block reads each as unknown, not as zero */
6
+ const NOT_COUNTED = ['proof failures', 'reseeds', 'rollbacks'];
7
+ /** the priced part of the ledger, or only the unpriced ids when no entry has an energy figure */
8
+ function physicalFrom(ledger) {
9
+ if (ledger.length === 0)
10
+ return null;
11
+ let mwh = 0;
12
+ let servers = 0;
13
+ const unpriced = [];
14
+ for (const entry of ledger) {
15
+ if (!Number.isFinite(entry.years) || entry.years <= 0) {
16
+ throw new RangeError(`${entry.id}: years must be a positive finite number`);
17
+ }
18
+ if (entry.evidence.trim() === '') {
19
+ throw new RangeError(`${entry.id}: evidence is required`);
20
+ }
21
+ if (entry.kind === 'instance' && entry.watts === undefined) {
22
+ unpriced.push(entry.id);
23
+ continue;
24
+ }
25
+ mwh += entry.years * serverYearMWh(entry.watts);
26
+ servers += entry.years;
27
+ }
28
+ if (servers === 0)
29
+ return { unpriced };
30
+ return { mwh, servers, unpriced, layer: 'L2' };
31
+ }
32
+ function observedFrom(observed) {
33
+ if (!observed)
34
+ return null;
35
+ for (const n of [observed.before, observed.after]) {
36
+ if (!Number.isFinite(n) || n < 0) {
37
+ throw new RangeError(`${observed.metric}: before and after must be non-negative finite numbers`);
38
+ }
39
+ }
40
+ return {
41
+ ...observed,
42
+ reduction: observed.before > 0 ? (observed.before - observed.after) / observed.before : null,
43
+ layer: 'L1'
44
+ };
45
+ }
46
+ function financialFrom(invoices) {
47
+ if (!invoices)
48
+ return null;
49
+ return {
50
+ currency: invoices.currency,
51
+ period: invoices.period,
52
+ saving: invoices.before - invoices.after,
53
+ layer: 'L1'
54
+ };
55
+ }
56
+ const SWD_TOTAL = SWD_V4.network.value + SWD_V4.datacentre.value + SWD_V4.device.value;
57
+ /** the share of spool's attributional saving that is data-centre energy: 0.055 of 0.194 kWh/GB */
58
+ const DATA_CENTRE_SHARE = SWD_V4.datacentre.value / SWD_TOTAL;
59
+ const DEVICE_SHARE = SWD_V4.device.value / SWD_TOTAL;
60
+ const NETWORK_SHARE = SWD_V4.network.value / SWD_TOTAL;
61
+ /** joules per byte at the SWD v4 total: kWh per GB, times J per kWh, over bytes per GB */
62
+ const J_PER_BYTE = (SWD_TOTAL * 3.6e6) / 1e9;
63
+ /** joules an average page view costs on the attributional basis: first views at their share, repeat views the rest */
64
+ function footprintJoulesPerView() {
65
+ const first = FIRST_VIEW_SHARE.central.value;
66
+ return J_PER_BYTE * (first * FIRST_VIEW_BYTES.value + (1 - first) * REPEAT_VIEW_BYTES.value);
67
+ }
68
+ /** the page-view footprint of `viewsPerYear` views, in MWh a year, on the attributional basis */
69
+ export function footprintMwh(viewsPerYear) {
70
+ return (viewsPerYear * footprintJoulesPerView()) / 3.6e9;
71
+ }
72
+ function economicsFrom(profile) {
73
+ if (!profile)
74
+ return null;
75
+ const industrial = electricityPrice(profile.state, 'industrial');
76
+ const commercial = electricityPrice(profile.state, 'commercial');
77
+ const dataCentreMwh = profile.attributionalMwh * DATA_CENTRE_SHARE;
78
+ return {
79
+ state: profile.state,
80
+ industrial,
81
+ commercial,
82
+ cases: [
83
+ ['peak', HOSTING_KWH_PER_SITE.peak],
84
+ ['production', HOSTING_KWH_PER_SITE.production],
85
+ ['floor', HOSTING_KWH_PER_SITE.floor]
86
+ ].map(([name, perSite]) => {
87
+ const mwh = (profile.sites * perSite.value) / 1000;
88
+ return {
89
+ name,
90
+ kwhPerSite: perSite.value,
91
+ mwh,
92
+ usdIndustrial: usdForMwh(mwh, industrial.value),
93
+ usdCommercial: usdForMwh(mwh, commercial.value)
94
+ };
95
+ }),
96
+ dataCentreMwh,
97
+ offMeterMwh: profile.attributionalMwh - dataCentreMwh,
98
+ layer: 'L2'
99
+ };
100
+ }
101
+ function storageFrom(inputs) {
102
+ if (!inputs)
103
+ return null;
104
+ for (const h of inputs.holdings) {
105
+ if (!Number.isFinite(h.bytes) || h.bytes < 0) {
106
+ throw new RangeError(`${h.dataset}: bytes must be a non-negative finite number`);
107
+ }
108
+ }
109
+ const held = { device: 0, server: 0 };
110
+ for (const h of inputs.holdings)
111
+ held[h.where] += h.bytes;
112
+ return {
113
+ budget: inputs.budget,
114
+ held,
115
+ within: {
116
+ device: held.device <= inputs.budget.device,
117
+ server: held.server <= inputs.budget.server
118
+ },
119
+ holdings: inputs.holdings,
120
+ layer: 'L1'
121
+ };
122
+ }
123
+ function trustFrom(views) {
124
+ if (!views)
125
+ return null;
126
+ const routes = mismatchesByRoute(views);
127
+ return {
128
+ views: views.length,
129
+ sampled: routes.reduce((n, r) => n + r.compared, 0),
130
+ mismatches: routes.reduce((n, r) => n + r.mismatches, 0),
131
+ refused: views.filter((v) => v.reason === 'refused' || v.reason === 'hard-refused').length,
132
+ fallbacks: views.filter((v) => v.reason === 'invalidated' || v.reason === 'stale-after-sync').length,
133
+ notCounted: NOT_COUNTED,
134
+ layer: 'L1'
135
+ };
136
+ }
137
+ function waterLitres(dataCentreMwh) {
138
+ const kwh = dataCentreMwh * 1000;
139
+ return {
140
+ directLitres: kwh * WATER_DIRECT.value,
141
+ indirectLitres: kwh * WATER_INDIRECT.value,
142
+ indirectLbnlLitres: kwh * WATER_INDIRECT_LBNL.value
143
+ };
144
+ }
145
+ function researchFrom(profile) {
146
+ if (!profile)
147
+ return null;
148
+ const att = profile.attributionalMwh;
149
+ const gPerKwh = egridGPerKwh(profile.subregion);
150
+ const footprint = footprintMwh(profile.viewsPerYear);
151
+ const goal = (share) => ({ share, kwh: footprint * share * 1000 });
152
+ return {
153
+ boundary: {
154
+ devices: { mwh: att * DEVICE_SHARE, share: DEVICE_SHARE },
155
+ networks: { mwh: att * NETWORK_SHARE, share: NETWORK_SHARE },
156
+ dataCentres: { mwh: att * DATA_CENTRE_SHARE, share: DATA_CENTRE_SHARE }
157
+ },
158
+ carbon: {
159
+ subregion: profile.subregion,
160
+ gPerKwh,
161
+ tonnes: tonnesFromMwh(att, gPerKwh),
162
+ ember: {
163
+ gPerKwh: EMBER_US_G_PER_KWH.value,
164
+ tonnes: tonnesFromMwh(att, EMBER_US_G_PER_KWH.value)
165
+ }
166
+ },
167
+ water: waterLitres(att * DATA_CENTRE_SHARE),
168
+ goal: {
169
+ viewsPerYear: profile.viewsPerYear,
170
+ footprintMwh: footprint,
171
+ rungs: GOAL_SHARES.map(goal),
172
+ high: goal(GOAL_HIGH_SHARE.value)
173
+ },
174
+ layer: 'L2'
175
+ };
176
+ }
177
+ /** sums energy and carbon across institutions and keeps water per institution */
178
+ export function rollUpInstitutions(rows) {
179
+ let mwh = 0;
180
+ let tonnes = 0;
181
+ const water = rows.map((row) => {
182
+ mwh += row.attributionalMwh;
183
+ tonnes += tonnesFromMwh(row.attributionalMwh, egridGPerKwh(row.subregion));
184
+ const { directLitres, indirectLitres } = waterLitres(row.attributionalMwh * DATA_CENTRE_SHARE);
185
+ return { name: row.name, directLitres, indirectLitres };
186
+ });
187
+ return { institutions: rows.length, mwh, tonnes, water };
188
+ }
189
+ export function institutionReport(inputs) {
190
+ const ledger = inputs.ledger ?? [];
191
+ const potential = inputs.plan
192
+ ? { plan: inputs.plan, layer: inputs.planLayer ?? 'L3' }
193
+ : null;
194
+ const blocks = {
195
+ economics: economicsFrom(inputs.institution),
196
+ storage: storageFrom(inputs.storage),
197
+ trust: trustFrom(inputs.views),
198
+ research: researchFrom(inputs.institution)
199
+ };
200
+ const found = physicalFrom(ledger);
201
+ if (!found || !('mwh' in found)) {
202
+ const unpriced = found?.unpriced ?? [];
203
+ return {
204
+ ...blocks,
205
+ observed: observedFrom(inputs.observed),
206
+ potential,
207
+ financial: financialFrom(inputs.invoices),
208
+ physical: null,
209
+ statement: 'No physical capacity saving demonstrated.' +
210
+ (unpriced.length > 0 ? ` Unpriced entries: ${unpriced.join(', ')}.` : '')
211
+ };
212
+ }
213
+ const servers = Number(found.servers.toPrecision(3)).toString();
214
+ const priced = ledger.length - found.unpriced.length;
215
+ const years = servers === '1' ? 'server-year' : 'server-years';
216
+ const entries = priced === 1 ? 'entry' : 'entries';
217
+ return {
218
+ ...blocks,
219
+ observed: observedFrom(inputs.observed),
220
+ potential,
221
+ financial: financialFrom(inputs.invoices),
222
+ physical: found,
223
+ statement: `Physical saving from ${servers} retired ${years} across ${priced} ledger ${entries}.`
224
+ };
225
+ }
@@ -163,6 +163,34 @@ export declare function activityFigures(rows: readonly Row[], limit?: number): {
163
163
  counts: Record<string, WindowCount>;
164
164
  arms: Record<string, ActivityArm | null>;
165
165
  };
166
+ /** a page with a pause hook, the same page without it, and the quiet page of the same setup */
167
+ export type ActivityPair = {
168
+ plain: string;
169
+ hook: string;
170
+ quiet: string;
171
+ };
172
+ /** the two pairs the rig measures: a loop off screen in a visible page, and a poll in a hidden tab */
173
+ export declare const ACTIVITY_PAIRS: readonly ActivityPair[];
174
+ /** what a pause hook did for one pair, in watts */
175
+ export type ActivityGain = {
176
+ pair: ActivityPair;
177
+ /** the same page without the hook less with it, over the arm medians; the range sets each page's extreme against the other's opposite */
178
+ saved: {
179
+ median: number;
180
+ min: number;
181
+ max: number;
182
+ };
183
+ /** what the page with the hook still draws above the quiet page */
184
+ residual: number;
185
+ };
186
+ /**
187
+ * Per pair, the watts a hook removes from the page it is on (the gain), and the watts that page
188
+ * still draws above a quiet one (the residual). A pair with an arm that has no kept window is left
189
+ * out. The quiet arm is not the baseline of the gain: a quiet page is where a perfect hook would end.
190
+ */
191
+ export declare function activityGains(arms: Readonly<Record<string, {
192
+ extraWatts: Spread;
193
+ } | null | undefined>>, pairs?: readonly ActivityPair[]): ActivityGain[];
166
194
  /** attributional joules for `bytes` (the same SWD v4 rate as the headline, no origin term: these are the same requests with fewer bytes) */
167
195
  export declare const ledgerJoules: (bytes: number) => number;
168
196
  /** megawatt-hours a year when `perView` joules are saved on a share of `views` views */
@@ -272,6 +272,36 @@ export function activityFigures(rows, limit = CONTAMINATION_MS_PER_S) {
272
272
  }
273
273
  return { idleWatts, noisyRounds: noisy.sort((a, b) => a - b), counts, arms };
274
274
  }
275
+ /** the two pairs the rig measures: a loop off screen in a visible page, and a poll in a hidden tab */
276
+ export const ACTIVITY_PAIRS = [
277
+ { plain: 'raf-off-plain', hook: 'raf-off-hook', quiet: 'quiet' },
278
+ { plain: 'poll-hidden-plain', hook: 'poll-hidden-hook', quiet: 'quiet-hidden' }
279
+ ];
280
+ /**
281
+ * Per pair, the watts a hook removes from the page it is on (the gain), and the watts that page
282
+ * still draws above a quiet one (the residual). A pair with an arm that has no kept window is left
283
+ * out. The quiet arm is not the baseline of the gain: a quiet page is where a perfect hook would end.
284
+ */
285
+ export function activityGains(arms, pairs = ACTIVITY_PAIRS) {
286
+ return pairs.flatMap((pair) => {
287
+ const plain = arms[pair.plain]?.extraWatts;
288
+ const hook = arms[pair.hook]?.extraWatts;
289
+ const quiet = arms[pair.quiet]?.extraWatts;
290
+ if (!plain || !hook || !quiet)
291
+ return [];
292
+ return [
293
+ {
294
+ pair,
295
+ saved: {
296
+ median: plain.median - hook.median,
297
+ min: plain.min - hook.max,
298
+ max: plain.max - hook.min
299
+ },
300
+ residual: hook.median - quiet.median
301
+ }
302
+ ];
303
+ });
304
+ }
275
305
  /** attributional joules for `bytes` (the same SWD v4 rate as the headline, no origin term: these are the same requests with fewer bytes) */
276
306
  export const ledgerJoules = (bytes) => attributionalJoules(bytes);
277
307
  /** megawatt-hours a year when `perView` joules are saved on a share of `views` views */
@@ -0,0 +1,73 @@
1
+ import type { Row } from './measurement.js';
2
+ /** seconds in each window of the avoidable-loops crawl */
3
+ export declare const LOOP_WINDOW_S = 20;
4
+ /** the classes a page view can carry, in the order the table prints them */
5
+ export declare const LOOP_CLASSES: readonly ["visible-frame-loop", "hidden-frame-loop", "hidden-timer-loop", "poll", "autoplay", "css-animation", "any", "hidden-timer-any"];
6
+ export type LoopClass = (typeof LOOP_CLASSES)[number];
7
+ /** one second of a window: what the page did in it, as the crawl counted it */
8
+ export type LoopSecond = {
9
+ visibility: string;
10
+ raf: number;
11
+ timers: {
12
+ lt100: number;
13
+ lt1s: number;
14
+ gte1s: number;
15
+ };
16
+ calls: {
17
+ fetch: number;
18
+ xhr: number;
19
+ beacon: number;
20
+ websocket: number;
21
+ eventSource: number;
22
+ };
23
+ requests: {
24
+ same: Record<string, number>;
25
+ cross: Record<string, number>;
26
+ };
27
+ videoAdvancing: number;
28
+ infiniteAnimations: number;
29
+ /** the tab's state at the read: whether Chromium discarded its document, its readyState, and whether its URL changed since the window's first read */
30
+ state?: {
31
+ discarded: boolean;
32
+ ready: string;
33
+ moved: boolean;
34
+ };
35
+ };
36
+ export type LoopWindow = {
37
+ seconds: LoopSecond[];
38
+ };
39
+ /** the classes of one page, null for a page that did not load; a null class could not be measured */
40
+ export declare function loopClasses(page: Row): Record<LoopClass, boolean | null> | null;
41
+ /** Wilson score interval for `k` of `n` at 95%, null when `n` is 0 */
42
+ export declare function wilson(k: number, n: number): {
43
+ low: number;
44
+ high: number;
45
+ } | null;
46
+ export type LoopFigure = {
47
+ /** pages where the class could be measured */
48
+ n: number;
49
+ count: number;
50
+ share: number | null;
51
+ low: number | null;
52
+ high: number | null;
53
+ /** sites with a measured page for the class, and sites with at least one page that has it */
54
+ siteN: number;
55
+ siteCount: number;
56
+ };
57
+ export type LoopFigures = {
58
+ /** pages that loaded */
59
+ pages: number;
60
+ sites: number;
61
+ classes: Record<LoopClass, LoopFigure>;
62
+ };
63
+ /** the share of loaded pages, and of sites, that carry each class; `slice` takes the page rows by position */
64
+ export declare function loopFigures(rows: readonly Row[], slice?: {
65
+ from: number;
66
+ to: number;
67
+ }): LoopFigures;
68
+ /** the figures of all the page rows, and of the first `floor(n / 2)` and the rest, in row order */
69
+ export declare function halves(rows: readonly Row[]): {
70
+ all: LoopFigures;
71
+ first: LoopFigures;
72
+ second: LoopFigures;
73
+ };
@@ -0,0 +1,101 @@
1
+ /** seconds in each window of the avoidable-loops crawl */
2
+ export const LOOP_WINDOW_S = 20;
3
+ /** the window counts only when its page was in the state it was recorded in for this many seconds */
4
+ const VALID_SECONDS = 18;
5
+ /** a class holds when its condition holds on this many seconds of the window */
6
+ const NEEDED_SECONDS = 15;
7
+ const VISIBLE_FRAMES_PER_S = 20;
8
+ const HIDDEN_FRAMES_PER_S = 1;
9
+ const POLL_REQUESTS = 3;
10
+ /** the classes of the six primary loops, which `any` is the union of */
11
+ const PRIMARY = [
12
+ 'visible-frame-loop',
13
+ 'hidden-frame-loop',
14
+ 'hidden-timer-loop',
15
+ 'poll',
16
+ 'autoplay',
17
+ 'css-animation'
18
+ ];
19
+ /** the classes a page view can carry, in the order the table prints them */
20
+ export const LOOP_CLASSES = [...PRIMARY, 'any', 'hidden-timer-any'];
21
+ /** a window that holds `state` for enough of its seconds to count; null otherwise */
22
+ function usable(win, state) {
23
+ if (!win)
24
+ return null;
25
+ return win.seconds.filter((s) => s.visibility === state).length >= VALID_SECONDS ? win : null;
26
+ }
27
+ /** whether `test` holds for enough seconds of a usable window, null when the window is not usable */
28
+ function over(win, test, needed) {
29
+ if (!win)
30
+ return null;
31
+ return win.seconds.filter(test).length >= needed;
32
+ }
33
+ /** the classes of one page, null for a page that did not load; a null class could not be measured */
34
+ export function loopClasses(page) {
35
+ if (page.ok !== true)
36
+ return null;
37
+ const visible = usable(page.visible, 'visible');
38
+ const hidden = usable(page.hidden, 'hidden');
39
+ const requests = (s) => Object.values(s.requests.same).reduce((n, c) => n + c, 0) +
40
+ Object.values(s.requests.cross).reduce((n, c) => n + c, 0);
41
+ const classes = {
42
+ 'visible-frame-loop': over(visible, (s) => s.raf >= VISIBLE_FRAMES_PER_S, NEEDED_SECONDS),
43
+ 'hidden-frame-loop': over(hidden, (s) => s.raf >= HIDDEN_FRAMES_PER_S, NEEDED_SECONDS),
44
+ 'hidden-timer-loop': over(hidden, (s) => s.timers.gte1s >= 1, NEEDED_SECONDS),
45
+ poll: visible === null
46
+ ? null
47
+ : visible.seconds.reduce((n, s) => n + requests(s), 0) >= POLL_REQUESTS,
48
+ autoplay: over(visible, (s) => s.videoAdvancing > 0, 1),
49
+ 'css-animation': over(visible, (s) => s.infiniteAnimations > 0, 1),
50
+ 'hidden-timer-any': over(hidden, (s) => s.timers.lt100 + s.timers.lt1s + s.timers.gte1s >= 1, NEEDED_SECONDS),
51
+ any: null
52
+ };
53
+ const values = PRIMARY.map((c) => classes[c]);
54
+ classes.any = values.includes(true) ? true : values.includes(null) ? null : false;
55
+ return classes;
56
+ }
57
+ /** Wilson score interval for `k` of `n` at 95%, null when `n` is 0 */
58
+ export function wilson(k, n) {
59
+ if (n <= 0)
60
+ return null;
61
+ const z = 1.959964;
62
+ const z2 = z * z;
63
+ const p = k / n;
64
+ const center = (p + z2 / (2 * n)) / (1 + z2 / n);
65
+ const half = (z * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n))) / (1 + z2 / n);
66
+ return { low: Math.max(0, center - half), high: Math.min(1, center + half) };
67
+ }
68
+ /** the share of loaded pages, and of sites, that carry each class; `slice` takes the page rows by position */
69
+ export function loopFigures(rows, slice) {
70
+ const pages = rows.filter((row) => row.kind === 'page').slice(slice?.from, slice?.to);
71
+ const loaded = pages.flatMap((row) => {
72
+ const classes = loopClasses(row);
73
+ return classes === null ? [] : [{ site: String(row.site), classes }];
74
+ });
75
+ const out = {};
76
+ for (const cls of LOOP_CLASSES) {
77
+ const measured = loaded.filter((p) => p.classes[cls] !== null);
78
+ const hits = measured.filter((p) => p.classes[cls] === true);
79
+ const interval = wilson(hits.length, measured.length);
80
+ out[cls] = {
81
+ n: measured.length,
82
+ count: hits.length,
83
+ share: measured.length > 0 ? hits.length / measured.length : null,
84
+ low: interval?.low ?? null,
85
+ high: interval?.high ?? null,
86
+ siteN: new Set(measured.map((p) => p.site)).size,
87
+ siteCount: new Set(hits.map((p) => p.site)).size
88
+ };
89
+ }
90
+ return { pages: loaded.length, sites: new Set(loaded.map((p) => p.site)).size, classes: out };
91
+ }
92
+ /** the figures of all the page rows, and of the first `floor(n / 2)` and the rest, in row order */
93
+ export function halves(rows) {
94
+ const n = rows.filter((row) => row.kind === 'page').length;
95
+ const cut = Math.floor(n / 2);
96
+ return {
97
+ all: loopFigures(rows),
98
+ first: loopFigures(rows, { from: 0, to: cut }),
99
+ second: loopFigures(rows, { from: cut, to: n })
100
+ };
101
+ }
@@ -1,6 +1,6 @@
1
1
  import type { Layer } from './inputs.js';
2
2
  /** the rigs that write to `measurements/<rig>/`, one folder each */
3
- export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim", "link-assets", "image-crawl", "dictionary-size"];
3
+ export declare const RIGS: readonly ["repeat-nav", "on-wire", "zero-network", "device-cpu", "rapl", "iphone", "payload", "trim", "link-assets", "image-crawl", "dictionary-size", "nav-replay", "first-payload", "embed-markup", "dataset-baseline", "avoidable-loops"];
4
4
  /** one of {@link RIGS} */
5
5
  export type Rig = (typeof RIGS)[number];
6
6
  /** the format version {@link parseMeasurement} reads */
@@ -10,7 +10,12 @@ export const RIGS = [
10
10
  'trim',
11
11
  'link-assets',
12
12
  'image-crawl',
13
- 'dictionary-size'
13
+ 'dictionary-size',
14
+ 'nav-replay',
15
+ 'first-payload',
16
+ 'embed-markup',
17
+ 'dataset-baseline',
18
+ 'avoidable-loops'
14
19
  ];
15
20
  /** the format version {@link parseMeasurement} reads */
16
21
  export const MEASUREMENT_SCHEMA = 1;
@@ -23,6 +23,8 @@ export declare function joulesPerViewWithOrigin(originJ: number, terms?: Pick<Vi
23
23
  export declare function dataCentreJoules(bytes?: number): number;
24
24
  /** the views channel: annual views x local share x joules per local view, in MWh */
25
25
  export declare function viewsChannelMWh(annualViews: number, localShare: number, jPerView?: number): number;
26
+ /** the reporting unit: kWh per million views when each view takes `joules` */
27
+ export declare function kwhPerMv(joules: number): number;
26
28
  /** a year of one server's facility draw, in MWh */
27
29
  export declare function serverYearMWh(watts?: number, pue?: number): number;
28
30
  /** origin work removed at peak: local share x the share of load that is reads */
@@ -38,6 +38,10 @@ export function dataCentreJoules(bytes = DOCUMENT_BYTES.value) {
38
38
  export function viewsChannelMWh(annualViews, localShare, jPerView = joulesPerView()) {
39
39
  return (annualViews * localShare * jPerView) / J_PER_MWH;
40
40
  }
41
+ /** the reporting unit: kWh per million views when each view takes `joules` */
42
+ export function kwhPerMv(joules) {
43
+ return (joules * 1e6) / J_PER_KWH;
44
+ }
41
45
  /** a year of one server's facility draw, in MWh */
42
46
  export function serverYearMWh(watts = SERVER_WATTS.value, pue = PUE.value) {
43
47
  return (watts * pue * HOURS_PER_YEAR) / 1e6;
@@ -1,4 +1,5 @@
1
1
  import type { TimedView } from '../protocol/view.js';
2
+ import type { Row } from './measurement.js';
2
3
  /** what a third-party origin is for, as far as the table below knows */
3
4
  export type OriginClass = 'analytics' | 'ads' | 'consent' | 'fonts' | 'cdn' | 'video' | 'maps' | 'social' | 'chat' | 'unknown';
4
5
  /**
@@ -53,6 +54,62 @@ export type ThirdPartyReport = {
53
54
  /** origins by `soloViews`, then `views`, then name */
54
55
  rows: ThirdPartyRow[];
55
56
  };
57
+ /** how long a third-party response may be kept without asking its origin */
58
+ export type Cacheability = 'immutable' | 'long' | 'short' | 'uncacheable';
59
+ /**
60
+ * The class of one recorded response from its cache headers. `immutable` is an `immutable`
61
+ * directive or a max-age of a year; `long` a max-age of a day up to a year; `short` a max-age under
62
+ * a day, or a validator with no freshness; `uncacheable` a `no-store`, or neither freshness nor a
63
+ * validator. The reading keeps `expires` as a flag only, so it is not read.
64
+ */
65
+ export declare function cacheability(response: Row): Cacheability;
66
+ /** third-party network bytes and requests of one repeat view, by cacheability */
67
+ export type CacheSplit = {
68
+ bytes: Record<Cacheability, number>;
69
+ requests: Record<Cacheability, number>;
70
+ /** third-party network bytes */
71
+ total: number;
72
+ /** bytes from a cache-remedy origin that is immutable or long: what a worker could answer */
73
+ answerable: number;
74
+ /** bytes, and immutable or long bytes, by origin class and remedy, keyed `class|remedy` */
75
+ byOrigin: Record<string, {
76
+ bytes: number;
77
+ longLived: number;
78
+ }>;
79
+ };
80
+ /**
81
+ * The third-party requests of one repeat view that reached the network, split by cacheability.
82
+ * First-party requests and requests the browser cache answered are left out, as in `splitRequestBytes`.
83
+ */
84
+ export declare function thirdPartyCacheSplit(requests: readonly Row[]): CacheSplit;
85
+ /** {@link thirdPartyCacheSplit} for each site's loaded home-page repeat view, picked as `repeatSplitBySite` picks it */
86
+ export declare function thirdPartyCacheBySite(rows: readonly Row[]): Map<string, CacheSplit>;
87
+ /** cross-site figures of {@link CacheSplit}s; shares are over the sites that had third-party bytes */
88
+ export type CacheabilityFigures = {
89
+ /** sites with a loaded repeat view */
90
+ sites: number;
91
+ /** sites whose repeat view had third-party network bytes */
92
+ withThirdParty: number;
93
+ /** each class's share of a site's third-party bytes, and its pooled share */
94
+ shares: Record<Cacheability, {
95
+ median: number;
96
+ mean: number;
97
+ pooled: number;
98
+ }>;
99
+ /** answerable bytes per site, over every site, zero included */
100
+ answerableBytes: {
101
+ median: number;
102
+ mean: number;
103
+ };
104
+ /** answerable bytes as a share of a site's third-party bytes, and pooled */
105
+ answerableShare: {
106
+ median: number;
107
+ mean: number;
108
+ pooled: number;
109
+ };
110
+ };
111
+ /** the median, mean and pooled figures of the splits, one per class and for the answerable bytes */
112
+ export declare function cacheabilityFigures(splits: readonly CacheSplit[]): CacheabilityFigures;
56
113
  /**
57
114
  * What blocks zero-network on this site: for each third-party origin the views that loaded from it,
58
115
  * ranked by how many views it alone blocks. Pass the views from `viewsOf`, which joins each page's