@drupflare/spool 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +1557 -2
  3. package/dist/cdn/client.js +1 -0
  4. package/dist/cdn/location.d.ts +11 -0
  5. package/dist/cdn/location.js +15 -0
  6. package/dist/cdn/manifest.json +16 -0
  7. package/dist/cdn/spool-sw.js +1 -0
  8. package/dist/client/entry.d.ts +1 -0
  9. package/dist/client/entry.js +25 -0
  10. package/dist/client/index.d.ts +3 -0
  11. package/dist/client/index.js +2 -0
  12. package/dist/client/lifecycle.d.ts +10 -0
  13. package/dist/client/lifecycle.js +10 -0
  14. package/dist/client/loads.d.ts +16 -0
  15. package/dist/client/loads.js +41 -0
  16. package/dist/client/register.d.ts +34 -0
  17. package/dist/client/register.js +58 -0
  18. package/dist/index.d.ts +2 -0
  19. package/dist/index.js +2 -0
  20. package/dist/node/listener.d.ts +19 -0
  21. package/dist/node/listener.js +76 -0
  22. package/dist/protocol/artifact.d.ts +54 -0
  23. package/dist/protocol/artifact.js +79 -0
  24. package/dist/protocol/assembly.d.ts +34 -0
  25. package/dist/protocol/assembly.js +72 -0
  26. package/dist/protocol/beacon.d.ts +59 -0
  27. package/dist/protocol/beacon.js +86 -0
  28. package/dist/protocol/collector.d.ts +41 -0
  29. package/dist/protocol/collector.js +84 -0
  30. package/dist/protocol/config.d.ts +89 -0
  31. package/dist/protocol/config.js +13 -0
  32. package/dist/protocol/envelope.d.ts +47 -0
  33. package/dist/protocol/envelope.js +162 -0
  34. package/dist/protocol/errors.d.ts +7 -0
  35. package/dist/protocol/errors.js +9 -0
  36. package/dist/protocol/graph.d.ts +81 -0
  37. package/dist/protocol/graph.js +201 -0
  38. package/dist/protocol/index.d.ts +19 -0
  39. package/dist/protocol/index.js +19 -0
  40. package/dist/protocol/manifest.d.ts +29 -0
  41. package/dist/protocol/manifest.js +94 -0
  42. package/dist/protocol/normalise.d.ts +20 -0
  43. package/dist/protocol/normalise.js +29 -0
  44. package/dist/protocol/pattern.d.ts +12 -0
  45. package/dist/protocol/pattern.js +82 -0
  46. package/dist/protocol/provision.d.ts +100 -0
  47. package/dist/protocol/provision.js +105 -0
  48. package/dist/protocol/route.d.ts +179 -0
  49. package/dist/protocol/route.js +135 -0
  50. package/dist/protocol/sync.d.ts +31 -0
  51. package/dist/protocol/sync.js +87 -0
  52. package/dist/protocol/tag.d.ts +12 -0
  53. package/dist/protocol/tag.js +26 -0
  54. package/dist/protocol/template/compile.d.ts +35 -0
  55. package/dist/protocol/template/compile.js +82 -0
  56. package/dist/protocol/template/interpret.d.ts +9 -0
  57. package/dist/protocol/template/interpret.js +82 -0
  58. package/dist/protocol/vector.d.ts +32 -0
  59. package/dist/protocol/vector.js +56 -0
  60. package/dist/protocol/view.d.ts +110 -0
  61. package/dist/protocol/view.js +201 -0
  62. package/dist/proxy/eligible.d.ts +45 -0
  63. package/dist/proxy/eligible.js +96 -0
  64. package/dist/proxy/index.d.ts +4 -0
  65. package/dist/proxy/index.js +4 -0
  66. package/dist/proxy/proxy.d.ts +86 -0
  67. package/dist/proxy/proxy.js +388 -0
  68. package/dist/proxy/purge.d.ts +10 -0
  69. package/dist/proxy/purge.js +66 -0
  70. package/dist/proxy/tags.d.ts +8 -0
  71. package/dist/proxy/tags.js +36 -0
  72. package/dist/report/derive.d.ts +221 -0
  73. package/dist/report/derive.js +490 -0
  74. package/dist/report/economics.d.ts +14 -0
  75. package/dist/report/economics.js +24 -0
  76. package/dist/report/index.d.ts +8 -0
  77. package/dist/report/index.js +8 -0
  78. package/dist/report/inputs.d.ts +141 -0
  79. package/dist/report/inputs.js +216 -0
  80. package/dist/report/measurement.d.ts +48 -0
  81. package/dist/report/measurement.js +114 -0
  82. package/dist/report/model.d.ts +42 -0
  83. package/dist/report/model.js +74 -0
  84. package/dist/report/thirdparty.d.ts +62 -0
  85. package/dist/report/thirdparty.js +107 -0
  86. package/dist/report/traffic.d.ts +140 -0
  87. package/dist/report/traffic.js +228 -0
  88. package/dist/report/trim.d.ts +81 -0
  89. package/dist/report/trim.js +105 -0
  90. package/dist/server/beacon.d.ts +20 -0
  91. package/dist/server/beacon.js +47 -0
  92. package/dist/server/embedded.d.ts +6 -0
  93. package/dist/server/embedded.js +6 -0
  94. package/dist/server/ga4.d.ts +70 -0
  95. package/dist/server/ga4.js +165 -0
  96. package/dist/server/identity.d.ts +12 -0
  97. package/dist/server/identity.js +17 -0
  98. package/dist/server/index.d.ts +7 -0
  99. package/dist/server/index.js +7 -0
  100. package/dist/server/sink.d.ts +56 -0
  101. package/dist/server/sink.js +133 -0
  102. package/dist/server/size.d.ts +7 -0
  103. package/dist/server/size.js +18 -0
  104. package/dist/server/spool.d.ts +97 -0
  105. package/dist/server/spool.js +463 -0
  106. package/dist/server/stub.d.ts +9 -0
  107. package/dist/server/stub.js +19 -0
  108. package/dist/server/sync.d.ts +12 -0
  109. package/dist/server/sync.js +48 -0
  110. package/dist/server/work.d.ts +22 -0
  111. package/dist/server/work.js +30 -0
  112. package/dist/stores/durable-object.d.ts +19 -0
  113. package/dist/stores/durable-object.js +53 -0
  114. package/dist/stores/index.d.ts +2 -0
  115. package/dist/stores/index.js +2 -0
  116. package/dist/stores/memory.d.ts +4 -0
  117. package/dist/stores/memory.js +10 -0
  118. package/dist/stores/version-store.d.ts +11 -0
  119. package/dist/stores/version-store.js +1 -0
  120. package/dist/sw/analytics.d.ts +81 -0
  121. package/dist/sw/analytics.js +275 -0
  122. package/dist/sw/collect.d.ts +8 -0
  123. package/dist/sw/collect.js +33 -0
  124. package/dist/sw/core.d.ts +1 -0
  125. package/dist/sw/core.js +3 -0
  126. package/dist/sw/freshness.d.ts +15 -0
  127. package/dist/sw/freshness.js +20 -0
  128. package/dist/sw/graph/index.d.ts +67 -0
  129. package/dist/sw/graph/index.js +170 -0
  130. package/dist/sw/graph/invalidate.d.ts +23 -0
  131. package/dist/sw/graph/invalidate.js +109 -0
  132. package/dist/sw/graph/projections.d.ts +7 -0
  133. package/dist/sw/graph/projections.js +9 -0
  134. package/dist/sw/graph/records.d.ts +7 -0
  135. package/dist/sw/graph/records.js +9 -0
  136. package/dist/sw/graph/store.d.ts +32 -0
  137. package/dist/sw/graph/store.js +52 -0
  138. package/dist/sw/idb.d.ts +8 -0
  139. package/dist/sw/idb.js +117 -0
  140. package/dist/sw/index.d.ts +2 -0
  141. package/dist/sw/index.js +1 -0
  142. package/dist/sw/partition.d.ts +21 -0
  143. package/dist/sw/partition.js +137 -0
  144. package/dist/sw/policy.d.ts +8 -0
  145. package/dist/sw/policy.js +24 -0
  146. package/dist/sw/provision.d.ts +39 -0
  147. package/dist/sw/provision.js +61 -0
  148. package/dist/sw/render.d.ts +21 -0
  149. package/dist/sw/render.js +53 -0
  150. package/dist/sw/replica.d.ts +77 -0
  151. package/dist/sw/replica.js +299 -0
  152. package/dist/sw/router.d.ts +42 -0
  153. package/dist/sw/router.js +48 -0
  154. package/dist/sw/routing.d.ts +23 -0
  155. package/dist/sw/routing.js +48 -0
  156. package/dist/sw/runtime.d.ts +112 -0
  157. package/dist/sw/runtime.js +1070 -0
  158. package/dist/sw/scheduler.d.ts +83 -0
  159. package/dist/sw/scheduler.js +149 -0
  160. package/dist/sw/seal.d.ts +37 -0
  161. package/dist/sw/seal.js +183 -0
  162. package/dist/sw/serve.d.ts +15 -0
  163. package/dist/sw/serve.js +63 -0
  164. package/dist/sw/shadow.d.ts +16 -0
  165. package/dist/sw/shadow.js +27 -0
  166. package/dist/sw/static.d.ts +17 -0
  167. package/dist/sw/static.js +81 -0
  168. package/dist/sw/storage.d.ts +64 -0
  169. package/dist/sw/storage.js +34 -0
  170. package/dist/sw/thirdparty.d.ts +17 -0
  171. package/dist/sw/thirdparty.js +36 -0
  172. package/dist/trim/css.d.ts +38 -0
  173. package/dist/trim/css.js +328 -0
  174. package/dist/trim/index.d.ts +3 -0
  175. package/dist/trim/index.js +3 -0
  176. package/dist/trim/manifest.d.ts +67 -0
  177. package/dist/trim/manifest.js +134 -0
  178. package/dist/trim/tokens.d.ts +43 -0
  179. package/dist/trim/tokens.js +142 -0
  180. package/dist/version.d.ts +2 -0
  181. package/dist/version.js +3 -0
  182. package/package.json +146 -5
@@ -0,0 +1,141 @@
1
+ /** where a figure comes from: L0 published, L1 measured here, L2 derived from L0/L1, L3 scenario */
2
+ export type Layer = 'L0' | 'L1' | 'L2' | 'L3';
3
+ /** one model input, carried with its unit, layer and source so a table can print all three */
4
+ export type Input = {
5
+ value: number;
6
+ unit: string;
7
+ layer: Layer;
8
+ source: string;
9
+ };
10
+ /** Sustainable Web Design v4 operational intensities, the attributional headline's basis */
11
+ export declare const SWD_V4: {
12
+ readonly network: {
13
+ readonly value: 0.059;
14
+ readonly unit: "kWh/GB";
15
+ readonly layer: "L0";
16
+ readonly source: "sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)";
17
+ };
18
+ readonly datacentre: {
19
+ readonly value: 0.055;
20
+ readonly unit: "kWh/GB";
21
+ readonly layer: "L0";
22
+ readonly source: "sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)";
23
+ };
24
+ readonly device: {
25
+ readonly value: 0.08;
26
+ readonly unit: "kWh/GB";
27
+ readonly layer: "L0";
28
+ readonly source: "sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)";
29
+ };
30
+ };
31
+ /**
32
+ * Median bytes of the document request a default local view replaces, on a repeat view of an
33
+ * already-seen home page. Sub-resources are left out: an optimized HTTP cache already keeps static
34
+ * files, and the page's own API calls and third-party requests still leave during a local view.
35
+ */
36
+ export declare const DOCUMENT_BYTES: Input;
37
+ /** share of higher-ed web sessions on phones */
38
+ export declare const MOBILE_SHARE: Input;
39
+ /**
40
+ * Radio wake avoided per zero-network view on a phone. The headline uses `attributed`, which stays 0
41
+ * until a phone reading attributes a wake to a network view; the others are sensitivity values.
42
+ */
43
+ export declare const RADIO_J: {
44
+ readonly attributed: {
45
+ readonly value: 0;
46
+ readonly unit: "J";
47
+ readonly layer: "L1";
48
+ readonly source: "measurements/iphone/2026-10-19-{paced,radio}-cellular.json: no wake attributable to a network view or an isolated request";
49
+ };
50
+ readonly low: {
51
+ readonly value: 2;
52
+ readonly unit: "J";
53
+ readonly layer: "L3";
54
+ readonly source: "scenario";
55
+ };
56
+ readonly central: {
57
+ readonly value: 5;
58
+ readonly unit: "J";
59
+ readonly layer: "L3";
60
+ readonly source: "scenario";
61
+ };
62
+ readonly high: {
63
+ readonly value: 12;
64
+ readonly unit: "J";
65
+ readonly layer: "L0";
66
+ readonly source: "Thiagarajan et al. WWW 2012, 3G setup cost (full text)";
67
+ };
68
+ };
69
+ /** origin energy per avoided request */
70
+ export declare const ORIGIN_J: {
71
+ readonly conventional: {
72
+ readonly value: 0.455;
73
+ readonly unit: "J";
74
+ readonly layer: "L1";
75
+ readonly source: "drupflare/worker docs/impact.md, RAPL mix @40 views/s, regular host, idle subtracted";
76
+ };
77
+ readonly drupflare: {
78
+ readonly value: 0.0054;
79
+ readonly unit: "J";
80
+ readonly layer: "L2";
81
+ readonly source: "drupflare/worker docs/impact.md, energy per view at 10M views/month";
82
+ };
83
+ };
84
+ /** a host at 15% load on the SPECpower curve the worker's impact model uses */
85
+ export declare const SERVER_WATTS: Input;
86
+ /** colocation facility overhead */
87
+ export declare const PUE: Input;
88
+ /** monthly views the Workers free plan carries at one request per view */
89
+ export declare const FREE_TIER_VIEWS: Input;
90
+ /**
91
+ * Share of all views that are a device's first view of a page it has not seen, so they go to the
92
+ * network and move that page's new bytes. A scenario range: the low end is a new-visitor session
93
+ * share times the share of views that are not a session's entry; the high end is a phone study.
94
+ */
95
+ export declare const FIRST_VIEW_SHARE: {
96
+ readonly low: {
97
+ readonly value: 0.451;
98
+ readonly unit: "fraction";
99
+ readonly layer: "L3";
100
+ readonly source: "spool-survey-breakeven.md Part D: 79.8% new-visitor sessions (Study in the States, one .gov site, October 2021; labelled FT-C in the survey, not re-read here) x (1 - 1/2.3 pages per session, OHO 2023 benchmarks, web page), computed";
101
+ };
102
+ readonly central: {
103
+ readonly value: 0.6;
104
+ readonly unit: "fraction";
105
+ readonly layer: "L3";
106
+ readonly source: "spool-survey-breakeven.md Part D: the midpoint of the low and high values, a choice";
107
+ };
108
+ readonly high: {
109
+ readonly value: 0.75;
110
+ readonly unit: "fraction";
111
+ readonly layer: "L3";
112
+ readonly source: "LiveLab, Wang et al. TR1215-2011 (full text): on average 75% of the webpages 24 iPhone users visited were new visits";
113
+ };
114
+ };
115
+ /** share of origin load that is reads spool can answer, before a trace replaces it */
116
+ export declare const READ_SHARE: Input;
117
+ /** servers a redundant deployment keeps whatever the load */
118
+ export declare const SERVER_FLOOR: Input;
119
+ /** date the vendor pricing pages below were read */
120
+ export declare const PRICES_READ = "2026-10-19";
121
+ /** a host's published list prices for traffic a local view no longer sends */
122
+ export type HostPrice = {
123
+ name: string;
124
+ /** the tier the egress price is taken from */
125
+ tier: string;
126
+ page: string;
127
+ egress: Input;
128
+ bytesPerUnit: number;
129
+ freeAllowance?: Input;
130
+ requests?: Input;
131
+ };
132
+ /** list prices of hosts higher ed uses, first paid tier, USD, read from each vendor's own page */
133
+ export declare const HOSTS: readonly HostPrice[];
134
+ /** Pantheon bills traffic in unique visits, which no per-view figure converts to */
135
+ export declare const PANTHEON_OVERAGE: Input;
136
+ /** the three tiers, named by the share of annual views served with zero network */
137
+ export declare const TIERS: {
138
+ readonly meaningful: 0.3;
139
+ readonly major: 0.65;
140
+ readonly transformative: 0.9;
141
+ };
@@ -0,0 +1,216 @@
1
+ /** Sustainable Web Design v4 operational intensities, the attributional headline's basis */
2
+ export const SWD_V4 = {
3
+ network: {
4
+ value: 0.059,
5
+ unit: 'kWh/GB',
6
+ layer: 'L0',
7
+ source: 'sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)'
8
+ },
9
+ datacentre: {
10
+ value: 0.055,
11
+ unit: 'kWh/GB',
12
+ layer: 'L0',
13
+ source: 'sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)'
14
+ },
15
+ device: {
16
+ value: 0.08,
17
+ unit: 'kWh/GB',
18
+ layer: 'L0',
19
+ source: 'sustainablewebdesign.org/estimating-digital-emissions (web page read 2026-10-18)'
20
+ }
21
+ };
22
+ /**
23
+ * Median bytes of the document request a default local view replaces, on a repeat view of an
24
+ * already-seen home page. Sub-resources are left out: an optimized HTTP cache already keeps static
25
+ * files, and the page's own API calls and third-party requests still leave during a local view.
26
+ */
27
+ export const DOCUMENT_BYTES = {
28
+ value: 17_054,
29
+ unit: 'B',
30
+ layer: 'L1',
31
+ source: 'median repeat-view document request over every measurements/repeat-nav reading (Playwright + CDP, n=1 per site per reading)'
32
+ };
33
+ /** share of higher-ed web sessions on phones */
34
+ export const MOBILE_SHARE = {
35
+ value: 0.43,
36
+ unit: 'fraction',
37
+ layer: 'L0',
38
+ source: 'OHO, 2023 Google Analytics benchmarks for higher education websites, 2022 data: 43.2% mobile (web page)'
39
+ };
40
+ /**
41
+ * Radio wake avoided per zero-network view on a phone. The headline uses `attributed`, which stays 0
42
+ * until a phone reading attributes a wake to a network view; the others are sensitivity values.
43
+ */
44
+ export const RADIO_J = {
45
+ attributed: {
46
+ value: 0,
47
+ unit: 'J',
48
+ layer: 'L1',
49
+ source: 'measurements/iphone/2026-10-19-{paced,radio}-cellular.json: no wake attributable to a network view or an isolated request'
50
+ },
51
+ low: { value: 2, unit: 'J', layer: 'L3', source: 'scenario' },
52
+ central: { value: 5, unit: 'J', layer: 'L3', source: 'scenario' },
53
+ high: {
54
+ value: 12,
55
+ unit: 'J',
56
+ layer: 'L0',
57
+ source: 'Thiagarajan et al. WWW 2012, 3G setup cost (full text)'
58
+ }
59
+ };
60
+ /** origin energy per avoided request */
61
+ export const ORIGIN_J = {
62
+ conventional: {
63
+ value: 0.455,
64
+ unit: 'J',
65
+ layer: 'L1',
66
+ source: 'drupflare/worker docs/impact.md, RAPL mix @40 views/s, regular host, idle subtracted'
67
+ },
68
+ drupflare: {
69
+ value: 0.0054,
70
+ unit: 'J',
71
+ layer: 'L2',
72
+ source: 'drupflare/worker docs/impact.md, energy per view at 10M views/month'
73
+ }
74
+ };
75
+ /** a host at 15% load on the SPECpower curve the worker's impact model uses */
76
+ export const SERVER_WATTS = {
77
+ value: 282,
78
+ unit: 'W',
79
+ layer: 'L2',
80
+ source: 'drupflare/worker docs/impact.md, SPECpower Dell R6725 measured curve at 15% load'
81
+ };
82
+ /** colocation facility overhead */
83
+ export const PUE = {
84
+ value: 1.54,
85
+ unit: 'ratio',
86
+ layer: 'L0',
87
+ source: 'Uptime Institute average, as cited in drupflare/worker docs/impact.md'
88
+ };
89
+ /** monthly views the Workers free plan carries at one request per view */
90
+ export const FREE_TIER_VIEWS = {
91
+ value: 3_040_000,
92
+ unit: 'views/month',
93
+ layer: 'L2',
94
+ source: '100,000 Worker requests/day (Cloudflare, L0) x 30.4 days'
95
+ };
96
+ /**
97
+ * Share of all views that are a device's first view of a page it has not seen, so they go to the
98
+ * network and move that page's new bytes. A scenario range: the low end is a new-visitor session
99
+ * share times the share of views that are not a session's entry; the high end is a phone study.
100
+ */
101
+ export const FIRST_VIEW_SHARE = {
102
+ low: {
103
+ value: 0.451,
104
+ unit: 'fraction',
105
+ layer: 'L3',
106
+ source: 'spool-survey-breakeven.md Part D: 79.8% new-visitor sessions (Study in the States, one .gov site, October 2021; labelled FT-C in the survey, not re-read here) x (1 - 1/2.3 pages per session, OHO 2023 benchmarks, web page), computed'
107
+ },
108
+ central: {
109
+ value: 0.6,
110
+ unit: 'fraction',
111
+ layer: 'L3',
112
+ source: 'spool-survey-breakeven.md Part D: the midpoint of the low and high values, a choice'
113
+ },
114
+ high: {
115
+ value: 0.75,
116
+ unit: 'fraction',
117
+ layer: 'L3',
118
+ source: 'LiveLab, Wang et al. TR1215-2011 (full text): on average 75% of the webpages 24 iPhone users visited were new visits'
119
+ }
120
+ };
121
+ /** share of origin load that is reads spool can answer, before a trace replaces it */
122
+ export const READ_SHARE = { value: 0.9, unit: 'fraction', layer: 'L3', source: 'scenario' };
123
+ /** servers a redundant deployment keeps whatever the load */
124
+ export const SERVER_FLOOR = { value: 2, unit: 'servers', layer: 'L3', source: 'scenario' };
125
+ /** date the vendor pricing pages below were read */
126
+ export const PRICES_READ = '2026-10-19';
127
+ /** list prices of hosts higher ed uses, first paid tier, USD, read from each vendor's own page */
128
+ export const HOSTS = [
129
+ {
130
+ name: 'Cloudflare Workers (Standard plan)',
131
+ tier: 'Standard plan, requests past the included 10 million a month',
132
+ page: 'developers.cloudflare.com/workers/platform/pricing',
133
+ egress: {
134
+ value: 0,
135
+ unit: 'USD/GB',
136
+ layer: 'L0',
137
+ source: `developers.cloudflare.com/workers/platform/pricing (web page read ${PRICES_READ}): "no additional charges for data transfer (egress) or throughput (bandwidth)"`
138
+ },
139
+ bytesPerUnit: 1e9,
140
+ requests: {
141
+ value: 0.3,
142
+ unit: 'USD/million requests',
143
+ layer: 'L0',
144
+ source: `developers.cloudflare.com/workers/platform/pricing (web page read ${PRICES_READ}): 10 million included a month, then $0.30 per additional million; static asset requests are free`
145
+ }
146
+ },
147
+ {
148
+ name: 'AWS CloudFront (pay as you go)',
149
+ tier: 'United States, Mexico and Canada; the next 9 TB after the first free 1 TB',
150
+ page: 'aws.amazon.com/cloudfront/pricing/pay-as-you-go',
151
+ egress: {
152
+ value: 0.085,
153
+ unit: 'USD/GB',
154
+ layer: 'L0',
155
+ source: `aws.amazon.com/cloudfront/pricing/pay-as-you-go (web page read ${PRICES_READ}): data transfer out to internet, $0.085 per GB for the next 9 TB`
156
+ },
157
+ bytesPerUnit: 1e9,
158
+ freeAllowance: {
159
+ value: 1000,
160
+ unit: 'GB/month',
161
+ layer: 'L0',
162
+ source: `aws.amazon.com/cloudfront/pricing/pay-as-you-go (web page read ${PRICES_READ}): first 1 TB free`
163
+ },
164
+ requests: {
165
+ value: 1,
166
+ unit: 'USD/million requests',
167
+ layer: 'L2',
168
+ source: `aws.amazon.com/cloudfront/pricing/pay-as-you-go (web page read ${PRICES_READ}): HTTPS requests $0.0100 per 10,000 after 10 million free a month, times 100`
169
+ }
170
+ },
171
+ {
172
+ name: 'Microsoft Azure',
173
+ tier: 'default routing from North America or Europe; the next 10 TB after the first free 100 GB',
174
+ page: 'azure.microsoft.com/en-us/pricing/details/bandwidth',
175
+ egress: {
176
+ value: 0.087,
177
+ unit: 'USD/GB',
178
+ layer: 'L0',
179
+ source: `azure.microsoft.com/en-us/pricing/details/bandwidth (web page read ${PRICES_READ}): Microsoft Premium Global Network, $0.087 per GB for the next 10 TB`
180
+ },
181
+ bytesPerUnit: 1e9,
182
+ freeAllowance: {
183
+ value: 100,
184
+ unit: 'GB/month',
185
+ layer: 'L0',
186
+ source: `azure.microsoft.com/en-us/pricing/details/bandwidth (web page read ${PRICES_READ}): first 100 GB a month free`
187
+ }
188
+ },
189
+ {
190
+ name: 'Google Cloud (Premium Tier)',
191
+ tier: 'to North America, 1 to 1,024 GiB a month, per GiB',
192
+ page: 'cloud.google.com/vpc/network-pricing',
193
+ egress: {
194
+ value: 0.12,
195
+ unit: 'USD/GiB',
196
+ layer: 'L0',
197
+ source: `cloud.google.com/vpc/network-pricing (web page read ${PRICES_READ}): Premium Tier data transfer out to North America, 1 to 1,024 GiB a month, $0.12 per GiB`
198
+ },
199
+ bytesPerUnit: 2 ** 30,
200
+ freeAllowance: {
201
+ value: 1,
202
+ unit: 'GiB/month',
203
+ layer: 'L0',
204
+ source: `cloud.google.com/vpc/network-pricing (web page read ${PRICES_READ}): first 1 GiB a month free`
205
+ }
206
+ }
207
+ ];
208
+ /** Pantheon bills traffic in unique visits, which no per-view figure converts to */
209
+ export const PANTHEON_OVERAGE = {
210
+ value: 40,
211
+ unit: 'USD per 10,000 unique visits',
212
+ layer: 'L0',
213
+ source: `docs.pantheon.io/guides/account-mgmt/traffic/overages (web page read ${PRICES_READ}): a visit is an IP address and user agent over 24 hours; the page carries a notice that the automated overage program is paused`
214
+ };
215
+ /** the three tiers, named by the share of annual views served with zero network */
216
+ export const TIERS = { meaningful: 0.3, major: 0.65, transformative: 0.9 };
@@ -0,0 +1,48 @@
1
+ import type { Layer } from './inputs.js';
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"];
4
+ /** one of {@link RIGS} */
5
+ export type Rig = (typeof RIGS)[number];
6
+ /** the format version {@link parseMeasurement} reads */
7
+ export declare const MEASUREMENT_SCHEMA = 1;
8
+ /** one window or navigation as the rig recorded it: raw quantities, never a per-view figure */
9
+ export type Row = Record<string, unknown>;
10
+ /** one run of one rig, as stored in `measurements/<rig>/<date>[-<experiment>].json` */
11
+ export type Measurement = {
12
+ schema: typeof MEASUREMENT_SCHEMA;
13
+ rig: Rig;
14
+ /** the run date, UTC, `YYYY-MM-DD` */
15
+ date: string;
16
+ layer: Extract<Layer, 'L1'>;
17
+ /** what the run answers */
18
+ question: string;
19
+ /** what read the numbers */
20
+ instrument: string;
21
+ /** the hardware, with at least a `name` */
22
+ machine: Record<string, string | number>;
23
+ software: Record<string, string>;
24
+ /** windows, rounds, arm order, pacing and any emulation */
25
+ method: Record<string, unknown>;
26
+ /** rules for rows a reader must drop, with the reason */
27
+ exclusions: string[];
28
+ rows: Row[];
29
+ };
30
+ /** every problem a file has, so one read reports them all */
31
+ export declare class MeasurementError extends Error {
32
+ readonly problems: string[];
33
+ constructor(problems: string[], source?: string);
34
+ }
35
+ /** what a published file must not carry: the kinds of id or address found in `text` */
36
+ export declare function findLeaks(text: string): string[];
37
+ /** the problems with one measurement document, empty when it is valid */
38
+ export declare function measurementProblems(input: unknown): string[];
39
+ /** the document as a {@link Measurement}, or a {@link MeasurementError} naming every problem */
40
+ export declare function parseMeasurement(input: unknown, source?: string): Measurement;
41
+ /** {@link parseMeasurement} over JSON text, which also refuses ids and addresses a file must not carry */
42
+ export declare function parseMeasurementText(text: string, source?: string): Measurement;
43
+ /** where a run is stored, relative to `measurements/`: `<rig>/<date>[-<experiment>].json` */
44
+ export declare function measurementPath(measurement: Pick<Measurement, 'rig' | 'date'>, experiment?: string): string;
45
+ /** whether a path under `measurements/` matches the rig and date inside the file */
46
+ export declare function pathMatches(path: string, measurement: Pick<Measurement, 'rig' | 'date'>): boolean;
47
+ /** the file text a rig writes: tab indented, one trailing newline, `schema` first */
48
+ export declare function serialiseMeasurement(measurement: Omit<Measurement, 'schema'>): string;
@@ -0,0 +1,114 @@
1
+ /** the rigs that write to `measurements/<rig>/`, one folder each */
2
+ export const RIGS = [
3
+ 'repeat-nav',
4
+ 'on-wire',
5
+ 'zero-network',
6
+ 'device-cpu',
7
+ 'rapl',
8
+ 'iphone',
9
+ 'payload',
10
+ 'trim'
11
+ ];
12
+ /** the format version {@link parseMeasurement} reads */
13
+ export const MEASUREMENT_SCHEMA = 1;
14
+ /** every problem a file has, so one read reports them all */
15
+ export class MeasurementError extends Error {
16
+ problems;
17
+ constructor(problems, source) {
18
+ super(`${source ? `${source}: ` : ''}${problems.join('; ')}`);
19
+ this.name = 'MeasurementError';
20
+ this.problems = problems;
21
+ }
22
+ }
23
+ const DATE = /^\d{4}-\d{2}-\d{2}$/;
24
+ const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
25
+ const isText = (value) => typeof value === 'string' && value.trim() !== '';
26
+ /** a device id, a container id used as a key, or an address that is not loopback */
27
+ const LEAKS = [
28
+ ['a device id', /\b0000[0-9A-F]{4}-[0-9A-F]{16}\b/],
29
+ ['a container id', /"[0-9a-f]{12}":/],
30
+ ['an IP address', /\b(?!127\.0\.0\.1\b)(?:\d{1,3}\.){3}\d{1,3}\b/]
31
+ ];
32
+ /** what a published file must not carry: the kinds of id or address found in `text` */
33
+ export function findLeaks(text) {
34
+ return LEAKS.filter(([, pattern]) => pattern.test(text)).map(([name]) => name);
35
+ }
36
+ function validDate(text) {
37
+ if (!DATE.test(text))
38
+ return false;
39
+ const date = new Date(`${text}T00:00:00Z`);
40
+ return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(text);
41
+ }
42
+ /** the problems with one measurement document, empty when it is valid */
43
+ export function measurementProblems(input) {
44
+ if (!isRecord(input))
45
+ return ['the file is not a JSON object'];
46
+ const problems = [];
47
+ if (input.schema !== MEASUREMENT_SCHEMA)
48
+ problems.push(`schema must be ${MEASUREMENT_SCHEMA}`);
49
+ if (!RIGS.includes(input.rig))
50
+ problems.push(`rig must be one of ${RIGS.join(', ')}`);
51
+ if (typeof input.date !== 'string' || !validDate(input.date)) {
52
+ problems.push('date must be a real UTC date as YYYY-MM-DD');
53
+ }
54
+ if (input.layer !== 'L1')
55
+ problems.push('layer must be L1, readings here are measured');
56
+ for (const key of ['question', 'instrument']) {
57
+ if (!isText(input[key]))
58
+ problems.push(`${key} must be a non-empty string`);
59
+ }
60
+ const { machine, software } = input;
61
+ if (!isRecord(machine) || !isText(machine.name))
62
+ problems.push('machine needs a name');
63
+ else if (!Object.values(machine).every((v) => typeof v === 'string' || typeof v === 'number')) {
64
+ problems.push('machine values must be strings or numbers');
65
+ }
66
+ if (!isRecord(software) || !Object.values(software).every((v) => typeof v === 'string')) {
67
+ problems.push('software must map names to version strings');
68
+ }
69
+ if (!isRecord(input.method))
70
+ problems.push('method must be an object');
71
+ const { exclusions } = input;
72
+ if (!Array.isArray(exclusions) || !exclusions.every(isText)) {
73
+ problems.push('exclusions must be a list of reasons');
74
+ }
75
+ const { rows } = input;
76
+ if (!Array.isArray(rows) || rows.length === 0 || !rows.every(isRecord)) {
77
+ problems.push('rows must be a non-empty list of objects');
78
+ }
79
+ return problems;
80
+ }
81
+ /** the document as a {@link Measurement}, or a {@link MeasurementError} naming every problem */
82
+ export function parseMeasurement(input, source) {
83
+ const problems = measurementProblems(input);
84
+ if (problems.length > 0)
85
+ throw new MeasurementError(problems, source);
86
+ return input;
87
+ }
88
+ /** {@link parseMeasurement} over JSON text, which also refuses ids and addresses a file must not carry */
89
+ export function parseMeasurementText(text, source) {
90
+ let parsed;
91
+ try {
92
+ parsed = JSON.parse(text);
93
+ }
94
+ catch (error) {
95
+ throw new MeasurementError([`invalid JSON (${error.message})`], source);
96
+ }
97
+ const leaks = findLeaks(text).map((name) => `contains ${name}`);
98
+ if (leaks.length > 0)
99
+ throw new MeasurementError(leaks, source);
100
+ return parseMeasurement(parsed, source);
101
+ }
102
+ /** where a run is stored, relative to `measurements/`: `<rig>/<date>[-<experiment>].json` */
103
+ export function measurementPath(measurement, experiment) {
104
+ return `${measurement.rig}/${measurement.date}${experiment ? `-${experiment}` : ''}.json`;
105
+ }
106
+ /** whether a path under `measurements/` matches the rig and date inside the file */
107
+ export function pathMatches(path, measurement) {
108
+ const expected = `${measurement.rig}/${measurement.date}`;
109
+ return (path === `${expected}.json` || (path.startsWith(`${expected}-`) && path.endsWith('.json')));
110
+ }
111
+ /** the file text a rig writes: tab indented, one trailing newline, `schema` first */
112
+ export function serialiseMeasurement(measurement) {
113
+ return `${JSON.stringify({ schema: MEASUREMENT_SCHEMA, ...measurement }, null, '\t')}\n`;
114
+ }
@@ -0,0 +1,42 @@
1
+ /** SWD v4 network + data centre + device, in kWh/GB */
2
+ export declare function swdTotal(): number;
3
+ /** attributional joules for moving `bytes`, at `kwhPerGb` */
4
+ export declare function attributionalJoules(bytes: number, kwhPerGb?: number): number;
5
+ /** what one zero-network local view avoids, before a rig replaces the modelled terms */
6
+ export type ViewTerms = {
7
+ bytes: number;
8
+ originJ: number;
9
+ radioJ: number;
10
+ mobileShare: number;
11
+ };
12
+ /** the modelled defaults: the replaced document, a conventional origin, the attributed radio wake */
13
+ export declare const MODELLED_VIEW: ViewTerms;
14
+ /** joules avoided per local view: attributional bytes + origin request + radio wake on phones */
15
+ export declare function joulesPerView(terms?: ViewTerms): number;
16
+ /**
17
+ * Joules avoided per local view where the origin's own energy for that workload was measured. The
18
+ * measured joules replace SWD's data-centre term and the modelled origin request, so the figure
19
+ * keeps the network and device terms of the bytes, the measured origin joules and the radio wake.
20
+ */
21
+ export declare function joulesPerViewWithOrigin(originJ: number, terms?: Pick<ViewTerms, 'bytes' | 'radioJ' | 'mobileShare'>): number;
22
+ /** the data-centre term of the bytes in a view, the part measured origin joules replace */
23
+ export declare function dataCentreJoules(bytes?: number): number;
24
+ /** the views channel: annual views x local share x joules per local view, in MWh */
25
+ export declare function viewsChannelMWh(annualViews: number, localShare: number, jPerView?: number): number;
26
+ /** a year of one server's facility draw, in MWh */
27
+ export declare function serverYearMWh(watts?: number, pue?: number): number;
28
+ /** origin work removed at peak: local share x the share of load that is reads */
29
+ export declare function peakCut(localShare: number, readShare?: number): number;
30
+ /**
31
+ * Servers still needed after spool removes `cut` of the peak work.
32
+ *
33
+ * A sensitivity model only: a real institution is sized from its peak traces and SLOs, which this
34
+ * proportional rule does not see.
35
+ */
36
+ export declare function serversAfter(before: number, cut: number, floor?: number): number;
37
+ /** MWh a year from the servers the cut frees, if they are actually removed */
38
+ export declare function capacityMWh(before: number, cut: number, floor?: number, perServer?: number): number;
39
+ /** the smallest throughput-sized fleet whose freed servers plus the views channel reach `target` */
40
+ export declare function fleetFor(targetMWh: number, viewsMWh: number, cut: number, floor?: number, perServer?: number): number;
41
+ /** monthly views under the free request allowance when `localShare` of views make no request */
42
+ export declare function freeTierCeiling(localShare: number, localViewsPerSync?: number, base?: number): number;
@@ -0,0 +1,74 @@
1
+ import { DOCUMENT_BYTES, FREE_TIER_VIEWS, MOBILE_SHARE, ORIGIN_J, PUE, RADIO_J, READ_SHARE, SERVER_FLOOR, SERVER_WATTS, SWD_V4 } from './inputs.js';
2
+ const J_PER_KWH = 3.6e6;
3
+ const J_PER_MWH = 3.6e9;
4
+ const HOURS_PER_YEAR = 8760;
5
+ /** SWD v4 network + data centre + device, in kWh/GB */
6
+ export function swdTotal() {
7
+ return SWD_V4.network.value + SWD_V4.datacentre.value + SWD_V4.device.value;
8
+ }
9
+ /** attributional joules for moving `bytes`, at `kwhPerGb` */
10
+ export function attributionalJoules(bytes, kwhPerGb = swdTotal()) {
11
+ return (bytes / 1e9) * kwhPerGb * J_PER_KWH;
12
+ }
13
+ /** the modelled defaults: the replaced document, a conventional origin, the attributed radio wake */
14
+ export const MODELLED_VIEW = {
15
+ bytes: DOCUMENT_BYTES.value,
16
+ originJ: ORIGIN_J.conventional.value,
17
+ radioJ: RADIO_J.attributed.value,
18
+ mobileShare: MOBILE_SHARE.value
19
+ };
20
+ /** joules avoided per local view: attributional bytes + origin request + radio wake on phones */
21
+ export function joulesPerView(terms = MODELLED_VIEW) {
22
+ return attributionalJoules(terms.bytes) + terms.originJ + terms.mobileShare * terms.radioJ;
23
+ }
24
+ /**
25
+ * Joules avoided per local view where the origin's own energy for that workload was measured. The
26
+ * measured joules replace SWD's data-centre term and the modelled origin request, so the figure
27
+ * keeps the network and device terms of the bytes, the measured origin joules and the radio wake.
28
+ */
29
+ export function joulesPerViewWithOrigin(originJ, terms = MODELLED_VIEW) {
30
+ const outside = SWD_V4.network.value + SWD_V4.device.value;
31
+ return attributionalJoules(terms.bytes, outside) + originJ + terms.mobileShare * terms.radioJ;
32
+ }
33
+ /** the data-centre term of the bytes in a view, the part measured origin joules replace */
34
+ export function dataCentreJoules(bytes = DOCUMENT_BYTES.value) {
35
+ return attributionalJoules(bytes, SWD_V4.datacentre.value);
36
+ }
37
+ /** the views channel: annual views x local share x joules per local view, in MWh */
38
+ export function viewsChannelMWh(annualViews, localShare, jPerView = joulesPerView()) {
39
+ return (annualViews * localShare * jPerView) / J_PER_MWH;
40
+ }
41
+ /** a year of one server's facility draw, in MWh */
42
+ export function serverYearMWh(watts = SERVER_WATTS.value, pue = PUE.value) {
43
+ return (watts * pue * HOURS_PER_YEAR) / 1e6;
44
+ }
45
+ /** origin work removed at peak: local share x the share of load that is reads */
46
+ export function peakCut(localShare, readShare = READ_SHARE.value) {
47
+ return localShare * readShare;
48
+ }
49
+ /**
50
+ * Servers still needed after spool removes `cut` of the peak work.
51
+ *
52
+ * A sensitivity model only: a real institution is sized from its peak traces and SLOs, which this
53
+ * proportional rule does not see.
54
+ */
55
+ export function serversAfter(before, cut, floor = SERVER_FLOOR.value) {
56
+ return Math.max(floor, Math.ceil(before * (1 - cut)));
57
+ }
58
+ /** MWh a year from the servers the cut frees, if they are actually removed */
59
+ export function capacityMWh(before, cut, floor = SERVER_FLOOR.value, perServer = serverYearMWh()) {
60
+ return (before - serversAfter(before, cut, floor)) * perServer;
61
+ }
62
+ /** the smallest throughput-sized fleet whose freed servers plus the views channel reach `target` */
63
+ export function fleetFor(targetMWh, viewsMWh, cut, floor = SERVER_FLOOR.value, perServer = serverYearMWh()) {
64
+ if (cut <= 0)
65
+ throw new RangeError('a cut of zero frees no server');
66
+ let n = floor;
67
+ while (capacityMWh(n, cut, floor, perServer) + viewsMWh < targetMWh)
68
+ n++;
69
+ return n;
70
+ }
71
+ /** monthly views under the free request allowance when `localShare` of views make no request */
72
+ export function freeTierCeiling(localShare, localViewsPerSync = 20, base = FREE_TIER_VIEWS.value) {
73
+ return base / (1 - localShare + localShare / localViewsPerSync);
74
+ }