@bsv/overlay-express 2.4.2 → 2.5.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 (147) hide show
  1. package/LICENSE.txt +57 -27
  2. package/README.md +141 -56
  3. package/dist/cjs/mod.d.ts +11 -0
  4. package/dist/cjs/mod.d.ts.map +1 -0
  5. package/dist/cjs/mod.js.map +1 -1
  6. package/dist/cjs/package.json +26 -13
  7. package/dist/cjs/src/ArcadeProvider.d.ts +37 -0
  8. package/dist/cjs/src/ArcadeProvider.d.ts.map +1 -0
  9. package/dist/cjs/src/ArcadeProvider.js.map +1 -1
  10. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts +36 -0
  11. package/dist/cjs/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  12. package/dist/cjs/src/BanAwareDiscoveryStorage.js +5 -4
  13. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -1
  14. package/dist/cjs/src/BanAwareLookupWrapper.d.ts +31 -0
  15. package/dist/cjs/src/BanAwareLookupWrapper.d.ts.map +1 -0
  16. package/dist/cjs/src/BanAwareLookupWrapper.js +3 -2
  17. package/dist/cjs/src/BanAwareLookupWrapper.js.map +1 -1
  18. package/dist/cjs/src/BanAwareTopicManager.d.ts +28 -0
  19. package/dist/cjs/src/BanAwareTopicManager.d.ts.map +1 -0
  20. package/dist/cjs/src/BanAwareTopicManager.js +3 -2
  21. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -1
  22. package/dist/cjs/src/BanService.d.ts +79 -0
  23. package/dist/cjs/src/BanService.d.ts.map +1 -0
  24. package/dist/cjs/src/BanService.js +18 -5
  25. package/dist/cjs/src/BanService.js.map +1 -1
  26. package/dist/cjs/src/ChaintracksProvider.d.ts +29 -0
  27. package/dist/cjs/src/ChaintracksProvider.d.ts.map +1 -0
  28. package/dist/cjs/src/ChaintracksProvider.js +1 -1
  29. package/dist/cjs/src/ChaintracksProvider.js.map +1 -1
  30. package/dist/cjs/src/JanitorService.d.ts +135 -0
  31. package/dist/cjs/src/JanitorService.d.ts.map +1 -0
  32. package/dist/cjs/src/JanitorService.js +168 -48
  33. package/dist/cjs/src/JanitorService.js.map +1 -1
  34. package/dist/cjs/src/OverlayExpress.d.ts +472 -0
  35. package/dist/cjs/src/OverlayExpress.d.ts.map +1 -0
  36. package/dist/cjs/src/OverlayExpress.js +483 -193
  37. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  38. package/dist/cjs/src/OverlayMonitor.d.ts +197 -0
  39. package/dist/cjs/src/OverlayMonitor.d.ts.map +1 -0
  40. package/dist/cjs/src/OverlayMonitor.js +6 -4
  41. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  42. package/dist/cjs/src/ProviderChainBroadcaster.d.ts +18 -0
  43. package/dist/cjs/src/ProviderChainBroadcaster.d.ts.map +1 -0
  44. package/dist/cjs/src/ProviderChainBroadcaster.js +7 -3
  45. package/dist/cjs/src/ProviderChainBroadcaster.js.map +1 -1
  46. package/dist/cjs/src/ReorgStream.d.ts +74 -0
  47. package/dist/cjs/src/ReorgStream.d.ts.map +1 -0
  48. package/dist/cjs/src/ReorgStream.js +14 -6
  49. package/dist/cjs/src/ReorgStream.js.map +1 -1
  50. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  51. package/dist/cjs/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  52. package/dist/cjs/src/ResourceBoundedLookupWrapper.js +70 -0
  53. package/dist/cjs/src/ResourceBoundedLookupWrapper.js.map +1 -0
  54. package/dist/cjs/src/generalGuide.md.d.ts +3 -0
  55. package/dist/cjs/src/generalGuide.md.d.ts.map +1 -0
  56. package/dist/cjs/src/generalGuide.md.js.map +1 -1
  57. package/dist/cjs/src/makeUserInterface.d.ts +22 -0
  58. package/dist/cjs/src/makeUserInterface.d.ts.map +1 -0
  59. package/dist/cjs/src/makeUserInterface.js +4 -4
  60. package/dist/cjs/src/makeUserInterface.js.map +1 -1
  61. package/dist/cjs/src/security/edgePolicy.d.ts +84 -0
  62. package/dist/cjs/src/security/edgePolicy.d.ts.map +1 -0
  63. package/dist/cjs/src/security/edgePolicy.js +533 -0
  64. package/dist/cjs/src/security/edgePolicy.js.map +1 -0
  65. package/dist/esm/mod.js.map +1 -1
  66. package/dist/esm/src/ArcadeProvider.js.map +1 -1
  67. package/dist/esm/src/BanAwareDiscoveryStorage.js +5 -4
  68. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -1
  69. package/dist/esm/src/BanAwareLookupWrapper.js +3 -2
  70. package/dist/esm/src/BanAwareLookupWrapper.js.map +1 -1
  71. package/dist/esm/src/BanAwareTopicManager.js +3 -2
  72. package/dist/esm/src/BanAwareTopicManager.js.map +1 -1
  73. package/dist/esm/src/BanService.js +18 -5
  74. package/dist/esm/src/BanService.js.map +1 -1
  75. package/dist/esm/src/ChaintracksProvider.js +1 -1
  76. package/dist/esm/src/ChaintracksProvider.js.map +1 -1
  77. package/dist/esm/src/JanitorService.js +146 -19
  78. package/dist/esm/src/JanitorService.js.map +1 -1
  79. package/dist/esm/src/OverlayExpress.js +465 -176
  80. package/dist/esm/src/OverlayExpress.js.map +1 -1
  81. package/dist/esm/src/ProviderChainBroadcaster.js +7 -3
  82. package/dist/esm/src/ProviderChainBroadcaster.js.map +1 -1
  83. package/dist/esm/src/ReorgStream.js +14 -6
  84. package/dist/esm/src/ReorgStream.js.map +1 -1
  85. package/dist/esm/src/ResourceBoundedLookupWrapper.js +70 -0
  86. package/dist/esm/src/ResourceBoundedLookupWrapper.js.map +1 -0
  87. package/dist/esm/src/makeUserInterface.js +3 -4
  88. package/dist/esm/src/makeUserInterface.js.map +1 -1
  89. package/dist/esm/src/security/edgePolicy.js +522 -0
  90. package/dist/esm/src/security/edgePolicy.js.map +1 -0
  91. package/dist/types/mod.d.ts +1 -1
  92. package/dist/types/mod.d.ts.map +1 -1
  93. package/dist/types/src/ArcadeProvider.d.ts.map +1 -1
  94. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -1
  95. package/dist/types/src/BanAwareLookupWrapper.d.ts.map +1 -1
  96. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -1
  97. package/dist/types/src/BanService.d.ts +2 -4
  98. package/dist/types/src/BanService.d.ts.map +1 -1
  99. package/dist/types/src/ChaintracksProvider.d.ts.map +1 -1
  100. package/dist/types/src/JanitorService.d.ts +21 -1
  101. package/dist/types/src/JanitorService.d.ts.map +1 -1
  102. package/dist/types/src/OverlayExpress.d.ts +54 -2
  103. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  104. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  105. package/dist/types/src/ProviderChainBroadcaster.d.ts.map +1 -1
  106. package/dist/types/src/ReorgStream.d.ts.map +1 -1
  107. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts +26 -0
  108. package/dist/types/src/ResourceBoundedLookupWrapper.d.ts.map +1 -0
  109. package/dist/types/src/generalGuide.md.d.ts +1 -1
  110. package/dist/types/src/generalGuide.md.d.ts.map +1 -1
  111. package/dist/types/src/makeUserInterface.d.ts +1 -2
  112. package/dist/types/src/makeUserInterface.d.ts.map +1 -1
  113. package/dist/types/src/security/edgePolicy.d.ts +84 -0
  114. package/dist/types/src/security/edgePolicy.d.ts.map +1 -0
  115. package/package.json +47 -25
  116. package/dist/cjs/tsconfig.cjs.tsbuildinfo +0 -1
  117. package/dist/esm/tsconfig.esm.tsbuildinfo +0 -1
  118. package/dist/types/tsconfig.types.tsbuildinfo +0 -1
  119. package/mod.ts +0 -47
  120. package/src/ArcadeProvider.ts +0 -232
  121. package/src/BanAwareDiscoveryStorage.ts +0 -91
  122. package/src/BanAwareLookupWrapper.ts +0 -95
  123. package/src/BanAwareTopicManager.ts +0 -87
  124. package/src/BanService.ts +0 -154
  125. package/src/ChaintracksProvider.ts +0 -79
  126. package/src/JanitorService.ts +0 -423
  127. package/src/OverlayExpress.ts +0 -2479
  128. package/src/OverlayMonitor.ts +0 -817
  129. package/src/ProviderChainBroadcaster.ts +0 -108
  130. package/src/ReorgStream.ts +0 -221
  131. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +0 -131
  132. package/src/__tests__/BanAwareLookupWrapper.test.ts +0 -255
  133. package/src/__tests__/BanAwareTopicManager.test.ts +0 -132
  134. package/src/__tests__/BanService.test.ts +0 -310
  135. package/src/__tests__/InMemoryMigrationSource.test.ts +0 -11
  136. package/src/__tests__/JanitorService.test.ts +0 -941
  137. package/src/__tests__/OverlayExpress.test.ts +0 -1300
  138. package/src/__tests__/OverlayMonitor.test.ts +0 -255
  139. package/src/__tests__/OverlayProviders.live.test.ts +0 -43
  140. package/src/__tests__/OverlayProviders.test.ts +0 -123
  141. package/src/__tests__/README.md +0 -105
  142. package/src/__tests__/ReorgStream.test.ts +0 -66
  143. package/src/__tests__/makeUserInterface.test.ts +0 -193
  144. package/src/__tests__/setup.ts +0 -36
  145. package/src/auth-express-middleware.d.ts +0 -16
  146. package/src/generalGuide.md.ts +0 -74
  147. package/src/makeUserInterface.ts +0 -1224
@@ -1,817 +0,0 @@
1
- import { Beef, Transaction } from '@bsv/sdk'
2
-
3
- export interface OverlayMonitorLogger {
4
- log: (...args: any[]) => void
5
- warn: (...args: any[]) => void
6
- error: (...args: any[]) => void
7
- }
8
-
9
- export interface OverlayLookupProbe {
10
- name?: string
11
- service: string
12
- query: unknown
13
- maxOutputs?: number
14
- }
15
-
16
- export interface OverlayAnchorProbe {
17
- name?: string
18
- topic: string
19
- expectedTac?: string
20
- expectedBlockHeight?: number
21
- currentHeight?: number
22
- maxTipLagBlocks?: number
23
- }
24
-
25
- export interface OverlayMaintenanceConfig {
26
- adminToken?: string
27
- headers?: Record<string, string>
28
- maintainUnproven?: boolean | {
29
- topics?: string[]
30
- thresholdBlocks?: number
31
- }
32
- startBASMSync?: boolean
33
- janitor?: boolean
34
- }
35
-
36
- export interface OverlayMonitorTarget {
37
- name: string
38
- baseUrl: string
39
- probes: OverlayLookupProbe[]
40
- anchorProbes?: OverlayAnchorProbe[]
41
- maintenance?: OverlayMaintenanceConfig
42
- headers?: Record<string, string>
43
- }
44
-
45
- export interface OverlayMonitorThresholds {
46
- responseBytes?: number
47
- beefBytes?: number
48
- txsWithoutProof?: number
49
- requireSubjectProof?: boolean
50
- anchorTipLagBlocks?: number
51
- expiredUnprovenCount?: number
52
- }
53
-
54
- export interface OverlayMonitorConfig {
55
- targets: OverlayMonitorTarget[]
56
- thresholds?: OverlayMonitorThresholds
57
- intervalMs?: number
58
- /** Per-probe request timeout in milliseconds. Defaults to 30000. */
59
- timeoutMs?: number
60
- fetchImpl?: typeof fetch
61
- logger?: OverlayMonitorLogger
62
- onReport?: (report: OverlayMonitorReport) => Promise<void> | void
63
- now?: () => Date
64
- }
65
-
66
- export interface OverlayMonitorWarning {
67
- code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing' | 'anchor-tip-mismatch' | 'anchor-stale-height' | 'expired-unproven-state'
68
- message: string
69
- value: number | boolean
70
- threshold?: number | boolean
71
- outputIndex?: number
72
- txid?: string
73
- }
74
-
75
- export interface OverlayLookupOutputSummary {
76
- outputIndex: number
77
- txid?: string
78
- beefBytes: number
79
- txCount?: number
80
- proofCount?: number
81
- txsWithoutProof?: number
82
- subjectHasProof?: boolean
83
- subjectRawTxBytes?: number
84
- currentToSubjectRawRatio?: number
85
- contextBytes?: number
86
- error?: string
87
- }
88
-
89
- export interface OverlayLookupProbeResult {
90
- target: string
91
- url: string
92
- probe: string
93
- service: string
94
- status: number
95
- ok: boolean
96
- responseBytes: number
97
- outputCount: number
98
- analyzedOutputCount: number
99
- outputs: OverlayLookupOutputSummary[]
100
- warnings: OverlayMonitorWarning[]
101
- durationMs: number
102
- error?: string
103
- }
104
-
105
- export interface OverlayAnchorProbeResult {
106
- target: string
107
- url: string
108
- probe: string
109
- topic: string
110
- status: number
111
- ok: boolean
112
- responseBytes: number
113
- blockHeight?: number
114
- tac?: string
115
- warnings: OverlayMonitorWarning[]
116
- durationMs: number
117
- error?: string
118
- }
119
-
120
- export interface OverlayMaintenanceResult {
121
- target: string
122
- url: string
123
- operation: 'maintain-unproven' | 'start-basm-sync' | 'janitor'
124
- topic?: string
125
- status: number
126
- ok: boolean
127
- responseBytes: number
128
- durationMs: number
129
- data?: unknown
130
- error?: string
131
- }
132
-
133
- export interface OverlayMonitorReport {
134
- startedAt: Date
135
- completedAt: Date
136
- durationMs: number
137
- results: OverlayLookupProbeResult[]
138
- anchorResults: OverlayAnchorProbeResult[]
139
- maintenanceResults: OverlayMaintenanceResult[]
140
- summary: {
141
- targetCount: number
142
- probeCount: number
143
- anchorProbeCount: number
144
- maintenanceActionCount: number
145
- failedProbeCount: number
146
- failedMaintenanceActionCount: number
147
- responseBytes: number
148
- outputCount: number
149
- analyzedOutputCount: number
150
- outputsMissingSubjectProof: number
151
- warningCount: number
152
- }
153
- }
154
-
155
- interface AnalyzeOptions {
156
- target: string
157
- url: string
158
- probe: string
159
- service: string
160
- status: number
161
- ok: boolean
162
- responseBody: unknown
163
- responseBytes: number
164
- durationMs: number
165
- thresholds?: OverlayMonitorThresholds
166
- maxOutputs?: number
167
- error?: string
168
- }
169
-
170
- const defaultThresholds: Required<OverlayMonitorThresholds> = {
171
- responseBytes: 1024 * 1024,
172
- beefBytes: 64 * 1024,
173
- txsWithoutProof: 1,
174
- requireSubjectProof: true,
175
- anchorTipLagBlocks: 6,
176
- expiredUnprovenCount: 0
177
- }
178
-
179
- /**
180
- * OverlayMonitor runs generic Overlay Express /lookup probes and reports response
181
- * size plus BEEF proof shape. It is intended for long-running monitor workers or
182
- * scheduled jobs, analogous to a storage monitor but scoped to overlay health.
183
- */
184
- export class OverlayMonitor {
185
- private readonly targets: OverlayMonitorTarget[]
186
- private readonly thresholds: Required<OverlayMonitorThresholds>
187
- private readonly fetchImpl: typeof fetch
188
- private readonly logger: OverlayMonitorLogger
189
- private readonly onReport?: (report: OverlayMonitorReport) => Promise<void> | void
190
- private readonly now: () => Date
191
- private readonly intervalMs?: number
192
- private readonly timeoutMs: number
193
- private timer?: ReturnType<typeof setInterval>
194
- private running = false
195
-
196
- constructor (config: OverlayMonitorConfig) {
197
- this.targets = config.targets
198
- this.thresholds = { ...defaultThresholds, ...config.thresholds }
199
- // Bind to globalThis so calling through this.fetchImpl does not rebind `this`
200
- // (browser fetch throws "Illegal invocation" when invoked as a method).
201
- this.fetchImpl = config.fetchImpl ?? fetch.bind(globalThis)
202
- this.logger = config.logger ?? console
203
- this.onReport = config.onReport
204
- this.now = config.now ?? (() => new Date())
205
- this.intervalMs = config.intervalMs
206
- this.timeoutMs = config.timeoutMs ?? 30000
207
- }
208
-
209
- async runOnce (): Promise<OverlayMonitorReport> {
210
- const startedAt = this.now()
211
- const results: OverlayLookupProbeResult[] = []
212
- const anchorResults: OverlayAnchorProbeResult[] = []
213
- const maintenanceResults: OverlayMaintenanceResult[] = []
214
-
215
- for (const target of this.targets) {
216
- for (const probe of target.probes) {
217
- results.push(await this.runProbe(target, probe))
218
- }
219
- for (const probe of target.anchorProbes ?? []) {
220
- anchorResults.push(await this.runAnchorProbe(target, probe))
221
- }
222
- maintenanceResults.push(...await this.runMaintenance(target))
223
- }
224
-
225
- const completedAt = this.now()
226
- const report: OverlayMonitorReport = {
227
- startedAt,
228
- completedAt,
229
- durationMs: completedAt.getTime() - startedAt.getTime(),
230
- results,
231
- anchorResults,
232
- maintenanceResults,
233
- summary: summarize(results, anchorResults, maintenanceResults, this.targets.length)
234
- }
235
-
236
- await this.onReport?.(report)
237
- return report
238
- }
239
-
240
- start (): void {
241
- if (this.intervalMs === undefined) {
242
- throw new Error('intervalMs is required to start OverlayMonitor')
243
- }
244
- if (this.timer !== undefined) return
245
-
246
- this.timer = setInterval(() => {
247
- if (this.running) return
248
- this.running = true
249
- this.runOnce()
250
- .catch(error => {
251
- this.logger.error('OverlayMonitor run failed', error)
252
- })
253
- .finally(() => {
254
- this.running = false
255
- })
256
- }, this.intervalMs)
257
- }
258
-
259
- stop (): void {
260
- if (this.timer !== undefined) {
261
- clearInterval(this.timer)
262
- this.timer = undefined
263
- }
264
- }
265
-
266
- private async runProbe (target: OverlayMonitorTarget, probe: OverlayLookupProbe): Promise<OverlayLookupProbeResult> {
267
- const startedAt = this.now()
268
- const url = new URL('/lookup', target.baseUrl).toString()
269
- const controller = new AbortController()
270
- const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
271
-
272
- try {
273
- const response = await this.fetchImpl(url, {
274
- method: 'POST',
275
- headers: {
276
- Accept: 'application/json',
277
- 'Content-Type': 'application/json',
278
- ...target.headers
279
- },
280
- body: JSON.stringify({ service: probe.service, query: probe.query }),
281
- signal: controller.signal
282
- })
283
- const text = await response.text()
284
- const responseBytes = new TextEncoder().encode(text).length
285
- const completedAt = this.now()
286
-
287
- let body: unknown
288
- try {
289
- body = text.length === 0 ? {} : JSON.parse(text)
290
- } catch (error) {
291
- return makeFailedResult({
292
- target,
293
- probe,
294
- url,
295
- status: response.status,
296
- ok: response.ok,
297
- responseBytes,
298
- durationMs: completedAt.getTime() - startedAt.getTime(),
299
- error: error instanceof Error ? error.message : 'Invalid JSON response'
300
- })
301
- }
302
-
303
- return analyzeOverlayLookupResponse({
304
- target: target.name,
305
- url,
306
- probe: probe.name ?? probe.service,
307
- service: probe.service,
308
- status: response.status,
309
- ok: response.ok,
310
- responseBody: body,
311
- responseBytes,
312
- durationMs: completedAt.getTime() - startedAt.getTime(),
313
- thresholds: this.thresholds,
314
- maxOutputs: probe.maxOutputs
315
- })
316
- } catch (error) {
317
- const completedAt = this.now()
318
- const fallbackMessage = error instanceof Error ? error.message : 'Lookup probe failed'
319
- const message = controller.signal.aborted
320
- ? `Lookup probe timed out after ${this.timeoutMs}ms`
321
- : fallbackMessage
322
- return makeFailedResult({
323
- target,
324
- probe,
325
- url,
326
- status: 0,
327
- ok: false,
328
- responseBytes: 0,
329
- durationMs: completedAt.getTime() - startedAt.getTime(),
330
- error: message
331
- })
332
- } finally {
333
- clearTimeout(timeout)
334
- }
335
- }
336
-
337
- private async runAnchorProbe(target: OverlayMonitorTarget, probe: OverlayAnchorProbe): Promise<OverlayAnchorProbeResult> {
338
- const startedAt = this.now()
339
- const url = new URL('/requestTopicAnchorTip', target.baseUrl).toString()
340
- const controller = new AbortController()
341
- const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
342
-
343
- try {
344
- const response = await this.fetchImpl(url, {
345
- method: 'POST',
346
- headers: {
347
- Accept: 'application/json',
348
- 'Content-Type': 'application/json',
349
- 'x-bsv-topic': probe.topic,
350
- ...target.headers
351
- },
352
- body: JSON.stringify({}),
353
- signal: controller.signal
354
- })
355
- const text = await response.text()
356
- const responseBytes = new TextEncoder().encode(text).length
357
- const completedAt = this.now()
358
- let body: Record<string, unknown>
359
-
360
- try {
361
- body = text.length === 0 ? {} : JSON.parse(text)
362
- } catch (error) {
363
- return makeFailedAnchorResult({
364
- target,
365
- probe,
366
- url,
367
- status: response.status,
368
- ok: response.ok,
369
- responseBytes,
370
- durationMs: completedAt.getTime() - startedAt.getTime(),
371
- error: error instanceof Error ? error.message : 'Invalid JSON response'
372
- })
373
- }
374
-
375
- return analyzeOverlayAnchorTip({
376
- target: target.name,
377
- url,
378
- probe: probe.name ?? probe.topic,
379
- topic: probe.topic,
380
- status: response.status,
381
- ok: response.ok,
382
- responseBody: body,
383
- responseBytes,
384
- durationMs: completedAt.getTime() - startedAt.getTime(),
385
- thresholds: this.thresholds,
386
- expectedTac: probe.expectedTac,
387
- expectedBlockHeight: probe.expectedBlockHeight,
388
- currentHeight: probe.currentHeight,
389
- maxTipLagBlocks: probe.maxTipLagBlocks
390
- })
391
- } catch (error) {
392
- const completedAt = this.now()
393
- const fallbackMessage = error instanceof Error ? error.message : 'Anchor probe failed'
394
- const message = controller.signal.aborted
395
- ? `Anchor probe timed out after ${this.timeoutMs}ms`
396
- : fallbackMessage
397
- return makeFailedAnchorResult({
398
- target,
399
- probe,
400
- url,
401
- status: 0,
402
- ok: false,
403
- responseBytes: 0,
404
- durationMs: completedAt.getTime() - startedAt.getTime(),
405
- error: message
406
- })
407
- } finally {
408
- clearTimeout(timeout)
409
- }
410
- }
411
-
412
- private async runMaintenance(target: OverlayMonitorTarget): Promise<OverlayMaintenanceResult[]> {
413
- const maintenance = target.maintenance
414
- if (maintenance === undefined) return []
415
-
416
- const results: OverlayMaintenanceResult[] = []
417
- if (maintenance.startBASMSync === true) {
418
- results.push(await this.runMaintenanceRequest(target, maintenance, 'start-basm-sync', '/admin/startBASMSync', {}))
419
- }
420
- if (maintenance.maintainUnproven !== undefined && maintenance.maintainUnproven !== false) {
421
- const config = maintenance.maintainUnproven === true ? {} : maintenance.maintainUnproven
422
- const topics = config.topics !== undefined && config.topics.length > 0 ? config.topics : [undefined]
423
- for (const topic of topics) {
424
- results.push(await this.runMaintenanceRequest(
425
- target,
426
- maintenance,
427
- 'maintain-unproven',
428
- '/admin/maintainUnproven',
429
- {
430
- topic,
431
- thresholdBlocks: config.thresholdBlocks
432
- }
433
- ))
434
- }
435
- }
436
- if (maintenance.janitor === true) {
437
- results.push(await this.runMaintenanceRequest(target, maintenance, 'janitor', '/admin/janitor', {}))
438
- }
439
- return results
440
- }
441
-
442
- private async runMaintenanceRequest(
443
- target: OverlayMonitorTarget,
444
- maintenance: OverlayMaintenanceConfig,
445
- operation: OverlayMaintenanceResult['operation'],
446
- path: string,
447
- body: { topic?: string, thresholdBlocks?: number }
448
- ): Promise<OverlayMaintenanceResult> {
449
- const startedAt = this.now()
450
- const url = new URL(path, target.baseUrl).toString()
451
- const controller = new AbortController()
452
- const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
453
-
454
- try {
455
- const headers: Record<string, string> = {
456
- Accept: 'application/json',
457
- 'Content-Type': 'application/json',
458
- ...target.headers,
459
- ...maintenance.headers
460
- }
461
- if (maintenance.adminToken !== undefined && maintenance.adminToken !== '') {
462
- headers.Authorization = `Bearer ${maintenance.adminToken}`
463
- }
464
- const response = await this.fetchImpl(url, {
465
- method: 'POST',
466
- headers,
467
- body: JSON.stringify(stripUndefined(body)),
468
- signal: controller.signal
469
- })
470
- const text = await response.text()
471
- const responseBytes = new TextEncoder().encode(text).length
472
- const completedAt = this.now()
473
- let parsed: unknown
474
- try {
475
- parsed = text.length === 0 ? {} : JSON.parse(text)
476
- } catch (error) {
477
- return {
478
- target: target.name,
479
- url,
480
- operation,
481
- topic: body.topic,
482
- status: response.status,
483
- ok: false,
484
- responseBytes,
485
- durationMs: completedAt.getTime() - startedAt.getTime(),
486
- error: error instanceof Error ? error.message : 'Invalid JSON response'
487
- }
488
- }
489
- return {
490
- target: target.name,
491
- url,
492
- operation,
493
- topic: body.topic,
494
- status: response.status,
495
- ok: response.ok,
496
- responseBytes,
497
- durationMs: completedAt.getTime() - startedAt.getTime(),
498
- data: parsed,
499
- error: response.ok ? undefined : readErrorMessage(parsed)
500
- }
501
- } catch (error) {
502
- const completedAt = this.now()
503
- const fallbackMessage = error instanceof Error ? error.message : 'Maintenance request failed'
504
- const message = controller.signal.aborted
505
- ? `Maintenance request timed out after ${this.timeoutMs}ms`
506
- : fallbackMessage
507
- return {
508
- target: target.name,
509
- url,
510
- operation,
511
- topic: body.topic,
512
- status: 0,
513
- ok: false,
514
- responseBytes: 0,
515
- durationMs: completedAt.getTime() - startedAt.getTime(),
516
- error: message
517
- }
518
- } finally {
519
- clearTimeout(timeout)
520
- }
521
- }
522
- }
523
-
524
- export function analyzeOverlayAnchorTip(options: {
525
- target: string
526
- url: string
527
- probe: string
528
- topic: string
529
- status: number
530
- ok: boolean
531
- responseBody: Record<string, unknown>
532
- responseBytes: number
533
- durationMs: number
534
- thresholds?: OverlayMonitorThresholds
535
- expectedTac?: string
536
- expectedBlockHeight?: number
537
- currentHeight?: number
538
- maxTipLagBlocks?: number
539
- }): OverlayAnchorProbeResult {
540
- const thresholds = { ...defaultThresholds, ...options.thresholds }
541
- const blockHeight = typeof options.responseBody.blockHeight === 'number' ? options.responseBody.blockHeight : undefined
542
- const tac = typeof options.responseBody.tac === 'string' ? options.responseBody.tac : undefined
543
- let expiredUnprovenCount: number | undefined
544
- if (typeof options.responseBody.expiredUnprovenCount === 'number') {
545
- expiredUnprovenCount = options.responseBody.expiredUnprovenCount
546
- } else if (typeof options.responseBody.unprovenExpiredCount === 'number') {
547
- expiredUnprovenCount = options.responseBody.unprovenExpiredCount
548
- } else {
549
- expiredUnprovenCount = undefined
550
- }
551
- const warnings: OverlayMonitorWarning[] = []
552
-
553
- if (options.expectedTac !== undefined && tac !== undefined && tac !== options.expectedTac) {
554
- warnings.push({
555
- code: 'anchor-tip-mismatch',
556
- message: 'Topic anchor TAC does not match expected value',
557
- value: true,
558
- threshold: false
559
- })
560
- }
561
-
562
- const expectedHeight = options.expectedBlockHeight ?? options.currentHeight
563
- const maxLag = options.maxTipLagBlocks ?? thresholds.anchorTipLagBlocks
564
- if (expectedHeight !== undefined && blockHeight !== undefined && expectedHeight - blockHeight > maxLag) {
565
- warnings.push({
566
- code: 'anchor-stale-height',
567
- message: `Topic anchor tip is ${expectedHeight - blockHeight} blocks behind`,
568
- value: expectedHeight - blockHeight,
569
- threshold: maxLag
570
- })
571
- }
572
-
573
- if (expiredUnprovenCount !== undefined && expiredUnprovenCount > thresholds.expiredUnprovenCount) {
574
- warnings.push({
575
- code: 'expired-unproven-state',
576
- message: `Overlay reports ${expiredUnprovenCount} expired unproven transactions`,
577
- value: expiredUnprovenCount,
578
- threshold: thresholds.expiredUnprovenCount
579
- })
580
- }
581
-
582
- return {
583
- target: options.target,
584
- url: options.url,
585
- probe: options.probe,
586
- topic: options.topic,
587
- status: options.status,
588
- ok: options.ok,
589
- responseBytes: options.responseBytes,
590
- blockHeight,
591
- tac,
592
- warnings,
593
- durationMs: options.durationMs
594
- }
595
- }
596
-
597
- export function analyzeOverlayLookupResponse (options: AnalyzeOptions): OverlayLookupProbeResult {
598
- const thresholds = { ...defaultThresholds, ...options.thresholds }
599
- const outputs = extractOutputs(options.responseBody)
600
- const maxOutputs = options.maxOutputs ?? outputs.length
601
- const analyzedOutputs = outputs.slice(0, maxOutputs).map(analyzeOutput)
602
- const warnings: OverlayMonitorWarning[] = []
603
-
604
- if (options.responseBytes >= thresholds.responseBytes) {
605
- warnings.push({
606
- code: 'response-bytes',
607
- message: `Lookup response is ${options.responseBytes} bytes`,
608
- value: options.responseBytes,
609
- threshold: thresholds.responseBytes
610
- })
611
- }
612
-
613
- for (const output of analyzedOutputs) {
614
- addOutputWarnings(warnings, output, thresholds)
615
- }
616
-
617
- return {
618
- target: options.target,
619
- url: options.url,
620
- probe: options.probe,
621
- service: options.service,
622
- status: options.status,
623
- ok: options.ok,
624
- responseBytes: options.responseBytes,
625
- outputCount: outputs.length,
626
- analyzedOutputCount: analyzedOutputs.length,
627
- outputs: analyzedOutputs,
628
- warnings,
629
- durationMs: options.durationMs,
630
- error: options.error
631
- }
632
- }
633
-
634
- function makeFailedResult (options: {
635
- target: OverlayMonitorTarget
636
- probe: OverlayLookupProbe
637
- url: string
638
- status: number
639
- ok: boolean
640
- responseBytes: number
641
- durationMs: number
642
- error: string
643
- }): OverlayLookupProbeResult {
644
- return {
645
- target: options.target.name,
646
- url: options.url,
647
- probe: options.probe.name ?? options.probe.service,
648
- service: options.probe.service,
649
- status: options.status,
650
- ok: options.ok,
651
- responseBytes: options.responseBytes,
652
- outputCount: 0,
653
- analyzedOutputCount: 0,
654
- outputs: [],
655
- warnings: [],
656
- durationMs: options.durationMs,
657
- error: options.error
658
- }
659
- }
660
-
661
- function makeFailedAnchorResult(options: {
662
- target: OverlayMonitorTarget
663
- probe: OverlayAnchorProbe
664
- url: string
665
- status: number
666
- ok: boolean
667
- responseBytes: number
668
- durationMs: number
669
- error: string
670
- }): OverlayAnchorProbeResult {
671
- return {
672
- target: options.target.name,
673
- url: options.url,
674
- probe: options.probe.name ?? options.probe.topic,
675
- topic: options.probe.topic,
676
- status: options.status,
677
- ok: options.ok,
678
- responseBytes: options.responseBytes,
679
- warnings: [],
680
- durationMs: options.durationMs,
681
- error: options.error
682
- }
683
- }
684
-
685
- function summarize (
686
- results: OverlayLookupProbeResult[],
687
- anchorResults: OverlayAnchorProbeResult[],
688
- maintenanceResults: OverlayMaintenanceResult[],
689
- targetCount: number
690
- ): OverlayMonitorReport['summary'] {
691
- return {
692
- targetCount,
693
- probeCount: results.length,
694
- anchorProbeCount: anchorResults.length,
695
- maintenanceActionCount: maintenanceResults.length,
696
- failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length +
697
- anchorResults.filter(result => !result.ok || result.error !== undefined).length,
698
- failedMaintenanceActionCount: maintenanceResults.filter(result => !result.ok || result.error !== undefined).length,
699
- responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0) +
700
- anchorResults.reduce((sum, result) => sum + result.responseBytes, 0) +
701
- maintenanceResults.reduce((sum, result) => sum + result.responseBytes, 0),
702
- outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
703
- analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
704
- outputsMissingSubjectProof: results.reduce((sum, result) => {
705
- return sum + result.outputs.filter(output => output.subjectHasProof === false).length
706
- }, 0),
707
- warningCount: results.reduce((sum, result) => sum + result.warnings.length, 0) +
708
- anchorResults.reduce((sum, result) => sum + result.warnings.length, 0)
709
- }
710
- }
711
-
712
- function stripUndefined<T extends Record<string, unknown>>(value: T): Record<string, unknown> {
713
- return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined))
714
- }
715
-
716
- function readErrorMessage(body: unknown): string | undefined {
717
- if (typeof body !== 'object' || body === null) return undefined
718
- const message = (body as { message?: unknown }).message
719
- return typeof message === 'string' ? message : undefined
720
- }
721
-
722
- function extractOutputs (body: unknown): Array<Record<string, unknown>> {
723
- if (typeof body !== 'object' || body === null || !('outputs' in body)) return []
724
- const outputs = (body as { outputs?: unknown }).outputs
725
- if (!Array.isArray(outputs)) return []
726
- return outputs.filter((output): output is Record<string, unknown> => typeof output === 'object' && output !== null)
727
- }
728
-
729
- function analyzeOutput (output: Record<string, unknown>): OverlayLookupOutputSummary {
730
- const outputIndex = typeof output.outputIndex === 'number' ? output.outputIndex : -1
731
- const beef = readNumberArray(output.beef)
732
- const context = readNumberArray(output.context)
733
-
734
- if (beef === undefined) {
735
- return {
736
- outputIndex,
737
- beefBytes: 0,
738
- contextBytes: context?.length,
739
- error: 'Output did not include numeric BEEF'
740
- }
741
- }
742
-
743
- try {
744
- const subjectTx = Transaction.fromBEEF(beef)
745
- const txid = subjectTx.id('hex')
746
- const parsedBeef = Beef.fromBinary(beef)
747
- const subject = parsedBeef.findTxid(txid)
748
- const subjectRawTxBytes = subject?.rawTx?.length ?? subjectTx.toBinary().length
749
- const proofCount = parsedBeef.txs.filter(tx => tx.hasProof).length
750
- const txsWithoutProof = parsedBeef.txs.filter(tx => !tx.hasProof && !tx.isTxidOnly).length
751
-
752
- return {
753
- outputIndex,
754
- txid,
755
- beefBytes: beef.length,
756
- txCount: parsedBeef.txs.length,
757
- proofCount,
758
- txsWithoutProof,
759
- subjectHasProof: subject?.hasProof ?? false,
760
- subjectRawTxBytes,
761
- currentToSubjectRawRatio: subjectRawTxBytes > 0 ? beef.length / subjectRawTxBytes : undefined,
762
- contextBytes: context?.length
763
- }
764
- } catch (error) {
765
- return {
766
- outputIndex,
767
- beefBytes: beef.length,
768
- contextBytes: context?.length,
769
- error: error instanceof Error ? error.message : 'Failed to parse BEEF'
770
- }
771
- }
772
- }
773
-
774
- function addOutputWarnings (
775
- warnings: OverlayMonitorWarning[],
776
- output: OverlayLookupOutputSummary,
777
- thresholds: Required<OverlayMonitorThresholds>
778
- ): void {
779
- if (output.beefBytes >= thresholds.beefBytes) {
780
- warnings.push({
781
- code: 'beef-bytes',
782
- message: `Output BEEF is ${output.beefBytes} bytes`,
783
- value: output.beefBytes,
784
- threshold: thresholds.beefBytes,
785
- outputIndex: output.outputIndex,
786
- txid: output.txid
787
- })
788
- }
789
-
790
- if (typeof output.txsWithoutProof === 'number' && output.txsWithoutProof >= thresholds.txsWithoutProof) {
791
- warnings.push({
792
- code: 'txs-without-proof',
793
- message: `Output BEEF has ${output.txsWithoutProof} transactions without direct proof`,
794
- value: output.txsWithoutProof,
795
- threshold: thresholds.txsWithoutProof,
796
- outputIndex: output.outputIndex,
797
- txid: output.txid
798
- })
799
- }
800
-
801
- if (thresholds.requireSubjectProof && output.subjectHasProof === false) {
802
- warnings.push({
803
- code: 'subject-proof-missing',
804
- message: 'Output subject transaction does not have a direct Merkle proof',
805
- value: false,
806
- threshold: true,
807
- outputIndex: output.outputIndex,
808
- txid: output.txid
809
- })
810
- }
811
- }
812
-
813
- function readNumberArray (value: unknown): number[] | undefined {
814
- if (!Array.isArray(value)) return undefined
815
- if (!value.every(item => Number.isInteger(item) && item >= 0 && item <= 255)) return undefined
816
- return value
817
- }