@bsv/overlay-express 2.2.0 → 2.3.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.
- package/README.md +33 -0
- package/dist/cjs/mod.js +4 -1
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +19 -15
- package/dist/cjs/src/BanService.js +2 -2
- package/dist/cjs/src/BanService.js.map +1 -1
- package/dist/cjs/src/OverlayExpress.js +191 -189
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/OverlayMonitor.js +306 -0
- package/dist/cjs/src/OverlayMonitor.js.map +1 -0
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +1 -0
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/BanService.js +2 -2
- package/dist/esm/src/BanService.js.map +1 -1
- package/dist/esm/src/OverlayExpress.js +186 -186
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/OverlayMonitor.js +304 -0
- package/dist/esm/src/OverlayMonitor.js.map +1 -0
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +1 -0
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/OverlayExpress.d.ts +29 -1
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/OverlayMonitor.d.ts +125 -0
- package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +13 -0
- package/package.json +32 -28
- package/src/BanService.ts +2 -2
- package/src/OverlayExpress.ts +199 -197
- package/src/OverlayMonitor.ts +445 -0
- package/src/__tests__/OverlayExpress.test.ts +86 -1
- package/src/__tests__/OverlayMonitor.test.ts +116 -0
|
@@ -0,0 +1,445 @@
|
|
|
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 OverlayMonitorTarget {
|
|
17
|
+
name: string
|
|
18
|
+
baseUrl: string
|
|
19
|
+
probes: OverlayLookupProbe[]
|
|
20
|
+
headers?: Record<string, string>
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export interface OverlayMonitorThresholds {
|
|
24
|
+
responseBytes?: number
|
|
25
|
+
beefBytes?: number
|
|
26
|
+
txsWithoutProof?: number
|
|
27
|
+
requireSubjectProof?: boolean
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface OverlayMonitorConfig {
|
|
31
|
+
targets: OverlayMonitorTarget[]
|
|
32
|
+
thresholds?: OverlayMonitorThresholds
|
|
33
|
+
intervalMs?: number
|
|
34
|
+
/** Per-probe request timeout in milliseconds. Defaults to 30000. */
|
|
35
|
+
timeoutMs?: number
|
|
36
|
+
fetchImpl?: typeof fetch
|
|
37
|
+
logger?: OverlayMonitorLogger
|
|
38
|
+
onReport?: (report: OverlayMonitorReport) => Promise<void> | void
|
|
39
|
+
now?: () => Date
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface OverlayMonitorWarning {
|
|
43
|
+
code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing'
|
|
44
|
+
message: string
|
|
45
|
+
value: number | boolean
|
|
46
|
+
threshold?: number | boolean
|
|
47
|
+
outputIndex?: number
|
|
48
|
+
txid?: string
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface OverlayLookupOutputSummary {
|
|
52
|
+
outputIndex: number
|
|
53
|
+
txid?: string
|
|
54
|
+
beefBytes: number
|
|
55
|
+
txCount?: number
|
|
56
|
+
proofCount?: number
|
|
57
|
+
txsWithoutProof?: number
|
|
58
|
+
subjectHasProof?: boolean
|
|
59
|
+
subjectRawTxBytes?: number
|
|
60
|
+
currentToSubjectRawRatio?: number
|
|
61
|
+
contextBytes?: number
|
|
62
|
+
error?: string
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface OverlayLookupProbeResult {
|
|
66
|
+
target: string
|
|
67
|
+
url: string
|
|
68
|
+
probe: string
|
|
69
|
+
service: string
|
|
70
|
+
status: number
|
|
71
|
+
ok: boolean
|
|
72
|
+
responseBytes: number
|
|
73
|
+
outputCount: number
|
|
74
|
+
analyzedOutputCount: number
|
|
75
|
+
outputs: OverlayLookupOutputSummary[]
|
|
76
|
+
warnings: OverlayMonitorWarning[]
|
|
77
|
+
durationMs: number
|
|
78
|
+
error?: string
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export interface OverlayMonitorReport {
|
|
82
|
+
startedAt: Date
|
|
83
|
+
completedAt: Date
|
|
84
|
+
durationMs: number
|
|
85
|
+
results: OverlayLookupProbeResult[]
|
|
86
|
+
summary: {
|
|
87
|
+
targetCount: number
|
|
88
|
+
probeCount: number
|
|
89
|
+
failedProbeCount: number
|
|
90
|
+
responseBytes: number
|
|
91
|
+
outputCount: number
|
|
92
|
+
analyzedOutputCount: number
|
|
93
|
+
outputsMissingSubjectProof: number
|
|
94
|
+
warningCount: number
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
interface AnalyzeOptions {
|
|
99
|
+
target: string
|
|
100
|
+
url: string
|
|
101
|
+
probe: string
|
|
102
|
+
service: string
|
|
103
|
+
status: number
|
|
104
|
+
ok: boolean
|
|
105
|
+
responseBody: unknown
|
|
106
|
+
responseBytes: number
|
|
107
|
+
durationMs: number
|
|
108
|
+
thresholds?: OverlayMonitorThresholds
|
|
109
|
+
maxOutputs?: number
|
|
110
|
+
error?: string
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
const defaultThresholds: Required<OverlayMonitorThresholds> = {
|
|
114
|
+
responseBytes: 1024 * 1024,
|
|
115
|
+
beefBytes: 64 * 1024,
|
|
116
|
+
txsWithoutProof: 1,
|
|
117
|
+
requireSubjectProof: true
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* OverlayMonitor runs generic Overlay Express /lookup probes and reports response
|
|
122
|
+
* size plus BEEF proof shape. It is intended for long-running monitor workers or
|
|
123
|
+
* scheduled jobs, analogous to a storage monitor but scoped to overlay health.
|
|
124
|
+
*/
|
|
125
|
+
export class OverlayMonitor {
|
|
126
|
+
private readonly targets: OverlayMonitorTarget[]
|
|
127
|
+
private readonly thresholds: Required<OverlayMonitorThresholds>
|
|
128
|
+
private readonly fetchImpl: typeof fetch
|
|
129
|
+
private readonly logger: OverlayMonitorLogger
|
|
130
|
+
private readonly onReport?: (report: OverlayMonitorReport) => Promise<void> | void
|
|
131
|
+
private readonly now: () => Date
|
|
132
|
+
private readonly intervalMs?: number
|
|
133
|
+
private readonly timeoutMs: number
|
|
134
|
+
private timer?: ReturnType<typeof setInterval>
|
|
135
|
+
private running = false
|
|
136
|
+
|
|
137
|
+
constructor (config: OverlayMonitorConfig) {
|
|
138
|
+
this.targets = config.targets
|
|
139
|
+
this.thresholds = { ...defaultThresholds, ...config.thresholds }
|
|
140
|
+
// Bind to globalThis so calling through this.fetchImpl does not rebind `this`
|
|
141
|
+
// (browser fetch throws "Illegal invocation" when invoked as a method).
|
|
142
|
+
this.fetchImpl = config.fetchImpl ?? fetch.bind(globalThis)
|
|
143
|
+
this.logger = config.logger ?? console
|
|
144
|
+
this.onReport = config.onReport
|
|
145
|
+
this.now = config.now ?? (() => new Date())
|
|
146
|
+
this.intervalMs = config.intervalMs
|
|
147
|
+
this.timeoutMs = config.timeoutMs ?? 30000
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
async runOnce (): Promise<OverlayMonitorReport> {
|
|
151
|
+
const startedAt = this.now()
|
|
152
|
+
const results: OverlayLookupProbeResult[] = []
|
|
153
|
+
|
|
154
|
+
for (const target of this.targets) {
|
|
155
|
+
for (const probe of target.probes) {
|
|
156
|
+
results.push(await this.runProbe(target, probe))
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
const completedAt = this.now()
|
|
161
|
+
const report: OverlayMonitorReport = {
|
|
162
|
+
startedAt,
|
|
163
|
+
completedAt,
|
|
164
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
165
|
+
results,
|
|
166
|
+
summary: summarize(results, this.targets.length)
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
await this.onReport?.(report)
|
|
170
|
+
return report
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
start (): void {
|
|
174
|
+
if (this.intervalMs === undefined) {
|
|
175
|
+
throw new Error('intervalMs is required to start OverlayMonitor')
|
|
176
|
+
}
|
|
177
|
+
if (this.timer !== undefined) return
|
|
178
|
+
|
|
179
|
+
this.timer = setInterval(() => {
|
|
180
|
+
if (this.running) return
|
|
181
|
+
this.running = true
|
|
182
|
+
this.runOnce()
|
|
183
|
+
.catch(error => {
|
|
184
|
+
this.logger.error('OverlayMonitor run failed', error)
|
|
185
|
+
})
|
|
186
|
+
.finally(() => {
|
|
187
|
+
this.running = false
|
|
188
|
+
})
|
|
189
|
+
}, this.intervalMs)
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
stop (): void {
|
|
193
|
+
if (this.timer !== undefined) {
|
|
194
|
+
clearInterval(this.timer)
|
|
195
|
+
this.timer = undefined
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
private async runProbe (target: OverlayMonitorTarget, probe: OverlayLookupProbe): Promise<OverlayLookupProbeResult> {
|
|
200
|
+
const startedAt = this.now()
|
|
201
|
+
const url = new URL('/lookup', target.baseUrl).toString()
|
|
202
|
+
const controller = new AbortController()
|
|
203
|
+
const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
|
|
204
|
+
|
|
205
|
+
try {
|
|
206
|
+
const response = await this.fetchImpl(url, {
|
|
207
|
+
method: 'POST',
|
|
208
|
+
headers: {
|
|
209
|
+
Accept: 'application/json',
|
|
210
|
+
'Content-Type': 'application/json',
|
|
211
|
+
...target.headers
|
|
212
|
+
},
|
|
213
|
+
body: JSON.stringify({ service: probe.service, query: probe.query }),
|
|
214
|
+
signal: controller.signal
|
|
215
|
+
})
|
|
216
|
+
const text = await response.text()
|
|
217
|
+
const responseBytes = new TextEncoder().encode(text).length
|
|
218
|
+
const completedAt = this.now()
|
|
219
|
+
|
|
220
|
+
let body: unknown
|
|
221
|
+
try {
|
|
222
|
+
body = text.length === 0 ? {} : JSON.parse(text)
|
|
223
|
+
} catch (error) {
|
|
224
|
+
return makeFailedResult({
|
|
225
|
+
target,
|
|
226
|
+
probe,
|
|
227
|
+
url,
|
|
228
|
+
status: response.status,
|
|
229
|
+
ok: response.ok,
|
|
230
|
+
responseBytes,
|
|
231
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
232
|
+
error: error instanceof Error ? error.message : 'Invalid JSON response'
|
|
233
|
+
})
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
return analyzeOverlayLookupResponse({
|
|
237
|
+
target: target.name,
|
|
238
|
+
url,
|
|
239
|
+
probe: probe.name ?? probe.service,
|
|
240
|
+
service: probe.service,
|
|
241
|
+
status: response.status,
|
|
242
|
+
ok: response.ok,
|
|
243
|
+
responseBody: body,
|
|
244
|
+
responseBytes,
|
|
245
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
246
|
+
thresholds: this.thresholds,
|
|
247
|
+
maxOutputs: probe.maxOutputs
|
|
248
|
+
})
|
|
249
|
+
} catch (error) {
|
|
250
|
+
const completedAt = this.now()
|
|
251
|
+
const fallbackMessage = error instanceof Error ? error.message : 'Lookup probe failed'
|
|
252
|
+
const message = controller.signal.aborted
|
|
253
|
+
? `Lookup probe timed out after ${this.timeoutMs}ms`
|
|
254
|
+
: fallbackMessage
|
|
255
|
+
return makeFailedResult({
|
|
256
|
+
target,
|
|
257
|
+
probe,
|
|
258
|
+
url,
|
|
259
|
+
status: 0,
|
|
260
|
+
ok: false,
|
|
261
|
+
responseBytes: 0,
|
|
262
|
+
durationMs: completedAt.getTime() - startedAt.getTime(),
|
|
263
|
+
error: message
|
|
264
|
+
})
|
|
265
|
+
} finally {
|
|
266
|
+
clearTimeout(timeout)
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
export function analyzeOverlayLookupResponse (options: AnalyzeOptions): OverlayLookupProbeResult {
|
|
272
|
+
const thresholds = { ...defaultThresholds, ...options.thresholds }
|
|
273
|
+
const outputs = extractOutputs(options.responseBody)
|
|
274
|
+
const maxOutputs = options.maxOutputs ?? outputs.length
|
|
275
|
+
const analyzedOutputs = outputs.slice(0, maxOutputs).map(analyzeOutput)
|
|
276
|
+
const warnings: OverlayMonitorWarning[] = []
|
|
277
|
+
|
|
278
|
+
if (options.responseBytes >= thresholds.responseBytes) {
|
|
279
|
+
warnings.push({
|
|
280
|
+
code: 'response-bytes',
|
|
281
|
+
message: `Lookup response is ${options.responseBytes} bytes`,
|
|
282
|
+
value: options.responseBytes,
|
|
283
|
+
threshold: thresholds.responseBytes
|
|
284
|
+
})
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
for (const output of analyzedOutputs) {
|
|
288
|
+
addOutputWarnings(warnings, output, thresholds)
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
return {
|
|
292
|
+
target: options.target,
|
|
293
|
+
url: options.url,
|
|
294
|
+
probe: options.probe,
|
|
295
|
+
service: options.service,
|
|
296
|
+
status: options.status,
|
|
297
|
+
ok: options.ok,
|
|
298
|
+
responseBytes: options.responseBytes,
|
|
299
|
+
outputCount: outputs.length,
|
|
300
|
+
analyzedOutputCount: analyzedOutputs.length,
|
|
301
|
+
outputs: analyzedOutputs,
|
|
302
|
+
warnings,
|
|
303
|
+
durationMs: options.durationMs,
|
|
304
|
+
error: options.error
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
function makeFailedResult (options: {
|
|
309
|
+
target: OverlayMonitorTarget
|
|
310
|
+
probe: OverlayLookupProbe
|
|
311
|
+
url: string
|
|
312
|
+
status: number
|
|
313
|
+
ok: boolean
|
|
314
|
+
responseBytes: number
|
|
315
|
+
durationMs: number
|
|
316
|
+
error: string
|
|
317
|
+
}): OverlayLookupProbeResult {
|
|
318
|
+
return {
|
|
319
|
+
target: options.target.name,
|
|
320
|
+
url: options.url,
|
|
321
|
+
probe: options.probe.name ?? options.probe.service,
|
|
322
|
+
service: options.probe.service,
|
|
323
|
+
status: options.status,
|
|
324
|
+
ok: options.ok,
|
|
325
|
+
responseBytes: options.responseBytes,
|
|
326
|
+
outputCount: 0,
|
|
327
|
+
analyzedOutputCount: 0,
|
|
328
|
+
outputs: [],
|
|
329
|
+
warnings: [],
|
|
330
|
+
durationMs: options.durationMs,
|
|
331
|
+
error: options.error
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
function summarize (results: OverlayLookupProbeResult[], targetCount: number): OverlayMonitorReport['summary'] {
|
|
336
|
+
return {
|
|
337
|
+
targetCount,
|
|
338
|
+
probeCount: results.length,
|
|
339
|
+
failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length,
|
|
340
|
+
responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0),
|
|
341
|
+
outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
|
|
342
|
+
analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
|
|
343
|
+
outputsMissingSubjectProof: results.reduce((sum, result) => {
|
|
344
|
+
return sum + result.outputs.filter(output => output.subjectHasProof === false).length
|
|
345
|
+
}, 0),
|
|
346
|
+
warningCount: results.reduce((sum, result) => sum + result.warnings.length, 0)
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
function extractOutputs (body: unknown): Array<Record<string, unknown>> {
|
|
351
|
+
if (typeof body !== 'object' || body === null || !('outputs' in body)) return []
|
|
352
|
+
const outputs = (body as { outputs?: unknown }).outputs
|
|
353
|
+
if (!Array.isArray(outputs)) return []
|
|
354
|
+
return outputs.filter((output): output is Record<string, unknown> => typeof output === 'object' && output !== null)
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
function analyzeOutput (output: Record<string, unknown>): OverlayLookupOutputSummary {
|
|
358
|
+
const outputIndex = typeof output.outputIndex === 'number' ? output.outputIndex : -1
|
|
359
|
+
const beef = readNumberArray(output.beef)
|
|
360
|
+
const context = readNumberArray(output.context)
|
|
361
|
+
|
|
362
|
+
if (beef === undefined) {
|
|
363
|
+
return {
|
|
364
|
+
outputIndex,
|
|
365
|
+
beefBytes: 0,
|
|
366
|
+
contextBytes: context?.length,
|
|
367
|
+
error: 'Output did not include numeric BEEF'
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
try {
|
|
372
|
+
const subjectTx = Transaction.fromBEEF(beef)
|
|
373
|
+
const txid = subjectTx.id('hex')
|
|
374
|
+
const parsedBeef = Beef.fromBinary(beef)
|
|
375
|
+
const subject = parsedBeef.findTxid(txid)
|
|
376
|
+
const subjectRawTxBytes = subject?.rawTx?.length ?? subjectTx.toBinary().length
|
|
377
|
+
const proofCount = parsedBeef.txs.filter(tx => tx.hasProof).length
|
|
378
|
+
const txsWithoutProof = parsedBeef.txs.filter(tx => !tx.hasProof && !tx.isTxidOnly).length
|
|
379
|
+
|
|
380
|
+
return {
|
|
381
|
+
outputIndex,
|
|
382
|
+
txid,
|
|
383
|
+
beefBytes: beef.length,
|
|
384
|
+
txCount: parsedBeef.txs.length,
|
|
385
|
+
proofCount,
|
|
386
|
+
txsWithoutProof,
|
|
387
|
+
subjectHasProof: subject?.hasProof ?? false,
|
|
388
|
+
subjectRawTxBytes,
|
|
389
|
+
currentToSubjectRawRatio: subjectRawTxBytes > 0 ? beef.length / subjectRawTxBytes : undefined,
|
|
390
|
+
contextBytes: context?.length
|
|
391
|
+
}
|
|
392
|
+
} catch (error) {
|
|
393
|
+
return {
|
|
394
|
+
outputIndex,
|
|
395
|
+
beefBytes: beef.length,
|
|
396
|
+
contextBytes: context?.length,
|
|
397
|
+
error: error instanceof Error ? error.message : 'Failed to parse BEEF'
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
function addOutputWarnings (
|
|
403
|
+
warnings: OverlayMonitorWarning[],
|
|
404
|
+
output: OverlayLookupOutputSummary,
|
|
405
|
+
thresholds: Required<OverlayMonitorThresholds>
|
|
406
|
+
): void {
|
|
407
|
+
if (output.beefBytes >= thresholds.beefBytes) {
|
|
408
|
+
warnings.push({
|
|
409
|
+
code: 'beef-bytes',
|
|
410
|
+
message: `Output BEEF is ${output.beefBytes} bytes`,
|
|
411
|
+
value: output.beefBytes,
|
|
412
|
+
threshold: thresholds.beefBytes,
|
|
413
|
+
outputIndex: output.outputIndex,
|
|
414
|
+
txid: output.txid
|
|
415
|
+
})
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
if (typeof output.txsWithoutProof === 'number' && output.txsWithoutProof >= thresholds.txsWithoutProof) {
|
|
419
|
+
warnings.push({
|
|
420
|
+
code: 'txs-without-proof',
|
|
421
|
+
message: `Output BEEF has ${output.txsWithoutProof} transactions without direct proof`,
|
|
422
|
+
value: output.txsWithoutProof,
|
|
423
|
+
threshold: thresholds.txsWithoutProof,
|
|
424
|
+
outputIndex: output.outputIndex,
|
|
425
|
+
txid: output.txid
|
|
426
|
+
})
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
if (thresholds.requireSubjectProof && output.subjectHasProof === false) {
|
|
430
|
+
warnings.push({
|
|
431
|
+
code: 'subject-proof-missing',
|
|
432
|
+
message: 'Output subject transaction does not have a direct Merkle proof',
|
|
433
|
+
value: false,
|
|
434
|
+
threshold: true,
|
|
435
|
+
outputIndex: output.outputIndex,
|
|
436
|
+
txid: output.txid
|
|
437
|
+
})
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
function readNumberArray (value: unknown): number[] | undefined {
|
|
442
|
+
if (!Array.isArray(value)) return undefined
|
|
443
|
+
if (!value.every(item => Number.isInteger(item) && item >= 0 && item <= 255)) return undefined
|
|
444
|
+
return value
|
|
445
|
+
}
|
|
@@ -872,6 +872,91 @@ describe('OverlayExpress', () => {
|
|
|
872
872
|
expect(postSpy.mock.calls.some(call => call[0] === '/arc-ingest')).toBe(false)
|
|
873
873
|
})
|
|
874
874
|
|
|
875
|
+
describe('ARC ingest callback token', () => {
|
|
876
|
+
const mockRes = (): any => {
|
|
877
|
+
const res: any = {}
|
|
878
|
+
res.status = jest.fn<any>().mockReturnValue(res)
|
|
879
|
+
res.json = jest.fn<any>().mockReturnValue(res)
|
|
880
|
+
return res
|
|
881
|
+
}
|
|
882
|
+
// Flush the async IIFE inside the /arc-ingest handler.
|
|
883
|
+
const flush = async (): Promise<void> => { await new Promise(resolve => setImmediate(resolve)) }
|
|
884
|
+
|
|
885
|
+
const captureArcIngestHandler = async (): Promise<any> => {
|
|
886
|
+
const postSpy = jest.spyOn(instance.app, 'post')
|
|
887
|
+
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
888
|
+
callback()
|
|
889
|
+
return {} as any
|
|
890
|
+
})
|
|
891
|
+
await instance.start()
|
|
892
|
+
const handler = postSpy.mock.calls.find(call => call[0] === '/arc-ingest')?.[1]
|
|
893
|
+
expect(handler).toBeDefined()
|
|
894
|
+
return handler
|
|
895
|
+
}
|
|
896
|
+
|
|
897
|
+
it('rejects a callback with no token when a token is configured', async () => {
|
|
898
|
+
instance.configureArcApiKey('test-arc-key')
|
|
899
|
+
instance.configureArcCallbackToken('secret-token')
|
|
900
|
+
const handler = await captureArcIngestHandler()
|
|
901
|
+
const res = mockRes()
|
|
902
|
+
|
|
903
|
+
handler({ headers: {}, body: {} }, res)
|
|
904
|
+
await flush()
|
|
905
|
+
|
|
906
|
+
expect(res.status).toHaveBeenCalledWith(401)
|
|
907
|
+
})
|
|
908
|
+
|
|
909
|
+
it('rejects a callback with an invalid token', async () => {
|
|
910
|
+
instance.configureArcApiKey('test-arc-key')
|
|
911
|
+
instance.configureArcCallbackToken('secret-token')
|
|
912
|
+
const handler = await captureArcIngestHandler()
|
|
913
|
+
const res = mockRes()
|
|
914
|
+
|
|
915
|
+
handler({ headers: { authorization: 'Bearer wrong-token' }, body: {} }, res)
|
|
916
|
+
await flush()
|
|
917
|
+
|
|
918
|
+
expect(res.status).toHaveBeenCalledWith(401)
|
|
919
|
+
})
|
|
920
|
+
|
|
921
|
+
it('accepts a callback with a valid Bearer token', async () => {
|
|
922
|
+
instance.configureArcApiKey('test-arc-key')
|
|
923
|
+
instance.configureArcCallbackToken('secret-token')
|
|
924
|
+
const handler = await captureArcIngestHandler()
|
|
925
|
+
const res = mockRes()
|
|
926
|
+
|
|
927
|
+
handler({ headers: { authorization: 'Bearer secret-token' }, body: {} }, res)
|
|
928
|
+
await flush()
|
|
929
|
+
|
|
930
|
+
expect(res.status).not.toHaveBeenCalledWith(401)
|
|
931
|
+
expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
|
|
932
|
+
})
|
|
933
|
+
|
|
934
|
+
it('accepts a callback with a valid x-callback-token header', async () => {
|
|
935
|
+
instance.configureArcApiKey('test-arc-key')
|
|
936
|
+
instance.configureArcCallbackToken('secret-token')
|
|
937
|
+
const handler = await captureArcIngestHandler()
|
|
938
|
+
const res = mockRes()
|
|
939
|
+
|
|
940
|
+
handler({ headers: { 'x-callback-token': 'secret-token' }, body: {} }, res)
|
|
941
|
+
await flush()
|
|
942
|
+
|
|
943
|
+
expect(res.status).not.toHaveBeenCalledWith(401)
|
|
944
|
+
expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
|
|
945
|
+
})
|
|
946
|
+
|
|
947
|
+
it('does not enforce a token when none is configured', async () => {
|
|
948
|
+
instance.configureArcApiKey('test-arc-key')
|
|
949
|
+
const handler = await captureArcIngestHandler()
|
|
950
|
+
const res = mockRes()
|
|
951
|
+
|
|
952
|
+
handler({ headers: {}, body: {} }, res)
|
|
953
|
+
await flush()
|
|
954
|
+
|
|
955
|
+
expect(res.status).not.toHaveBeenCalledWith(401)
|
|
956
|
+
expect(mockEngine.handleNewMerkleProof).toHaveBeenCalled()
|
|
957
|
+
})
|
|
958
|
+
})
|
|
959
|
+
|
|
875
960
|
it('should run knex migrations on start', async () => {
|
|
876
961
|
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
877
962
|
callback()
|
|
@@ -941,7 +1026,7 @@ describe('OverlayExpress', () => {
|
|
|
941
1026
|
revokeAdvertisements: jest.fn(),
|
|
942
1027
|
parseAdvertisement: jest.fn()
|
|
943
1028
|
}
|
|
944
|
-
instance.engine
|
|
1029
|
+
instance.engine!.advertiser = mockAdvertiser
|
|
945
1030
|
|
|
946
1031
|
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
947
1032
|
callback()
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import { describe, it, expect, jest } from '@jest/globals'
|
|
2
|
+
import { Transaction } from '@bsv/sdk'
|
|
3
|
+
import { OverlayMonitor, analyzeOverlayLookupResponse } from '../OverlayMonitor.js'
|
|
4
|
+
|
|
5
|
+
describe('OverlayMonitor', () => {
|
|
6
|
+
it('summarizes an empty lookup response', () => {
|
|
7
|
+
const result = analyzeOverlayLookupResponse({
|
|
8
|
+
target: 'local-overlay',
|
|
9
|
+
url: 'https://overlay.example/lookup',
|
|
10
|
+
probe: 'empty',
|
|
11
|
+
service: 'ls_empty',
|
|
12
|
+
status: 200,
|
|
13
|
+
ok: true,
|
|
14
|
+
responseBody: { outputs: [] },
|
|
15
|
+
responseBytes: 14,
|
|
16
|
+
durationMs: 5
|
|
17
|
+
})
|
|
18
|
+
|
|
19
|
+
expect(result.outputCount).toBe(0)
|
|
20
|
+
expect(result.analyzedOutputCount).toBe(0)
|
|
21
|
+
expect(result.warnings).toHaveLength(0)
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
it('reports missing subject proofs in returned BEEF', () => {
|
|
25
|
+
const tx = new Transaction(1, [], [], 0)
|
|
26
|
+
const result = analyzeOverlayLookupResponse({
|
|
27
|
+
target: 'local-overlay',
|
|
28
|
+
url: 'https://overlay.example/lookup',
|
|
29
|
+
probe: 'proof-shape',
|
|
30
|
+
service: 'ls_ship',
|
|
31
|
+
status: 200,
|
|
32
|
+
ok: true,
|
|
33
|
+
responseBody: {
|
|
34
|
+
outputs: [
|
|
35
|
+
{
|
|
36
|
+
outputIndex: 0,
|
|
37
|
+
beef: tx.toBEEF()
|
|
38
|
+
}
|
|
39
|
+
]
|
|
40
|
+
},
|
|
41
|
+
responseBytes: 512,
|
|
42
|
+
durationMs: 5
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
expect(result.outputs[0].txid).toBe(tx.id('hex'))
|
|
46
|
+
expect(result.outputs[0].subjectHasProof).toBe(false)
|
|
47
|
+
expect(result.outputs[0].txCount).toBe(1)
|
|
48
|
+
expect(result.warnings.map(warning => warning.code)).toContain('subject-proof-missing')
|
|
49
|
+
})
|
|
50
|
+
|
|
51
|
+
it('runs configured probes through Overlay Express lookup endpoints', async () => {
|
|
52
|
+
const tx = new Transaction(1, [], [], 0)
|
|
53
|
+
const responseBody = JSON.stringify({
|
|
54
|
+
outputs: [
|
|
55
|
+
{
|
|
56
|
+
outputIndex: 0,
|
|
57
|
+
beef: tx.toBEEF()
|
|
58
|
+
}
|
|
59
|
+
]
|
|
60
|
+
})
|
|
61
|
+
const fetchImpl = jest.fn<typeof fetch>(async () => new Response(responseBody, { status: 200 }))
|
|
62
|
+
const monitor = new OverlayMonitor({
|
|
63
|
+
targets: [
|
|
64
|
+
{
|
|
65
|
+
name: 'local-overlay',
|
|
66
|
+
baseUrl: 'https://overlay.example',
|
|
67
|
+
probes: [
|
|
68
|
+
{
|
|
69
|
+
name: 'ship',
|
|
70
|
+
service: 'ls_ship',
|
|
71
|
+
query: { topics: ['tm_example'] }
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
],
|
|
76
|
+
fetchImpl
|
|
77
|
+
})
|
|
78
|
+
|
|
79
|
+
const report = await monitor.runOnce()
|
|
80
|
+
|
|
81
|
+
expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/lookup', expect.objectContaining({
|
|
82
|
+
method: 'POST',
|
|
83
|
+
body: JSON.stringify({ service: 'ls_ship', query: { topics: ['tm_example'] } })
|
|
84
|
+
}))
|
|
85
|
+
expect(report.summary.targetCount).toBe(1)
|
|
86
|
+
expect(report.summary.probeCount).toBe(1)
|
|
87
|
+
expect(report.summary.outputsMissingSubjectProof).toBe(1)
|
|
88
|
+
})
|
|
89
|
+
|
|
90
|
+
it('aborts a probe that exceeds the configured timeout', async () => {
|
|
91
|
+
// Never resolves on its own; only settles when the abort signal fires.
|
|
92
|
+
const fetchImpl = jest.fn<typeof fetch>(async (_url, init) => await new Promise<Response>((_resolve, reject) => {
|
|
93
|
+
init?.signal?.addEventListener('abort', () => reject(new Error('aborted')))
|
|
94
|
+
}))
|
|
95
|
+
const monitor = new OverlayMonitor({
|
|
96
|
+
targets: [
|
|
97
|
+
{
|
|
98
|
+
name: 'slow-overlay',
|
|
99
|
+
baseUrl: 'https://overlay.example',
|
|
100
|
+
probes: [{ name: 'slow', service: 'ls_slow', query: {} }]
|
|
101
|
+
}
|
|
102
|
+
],
|
|
103
|
+
fetchImpl,
|
|
104
|
+
timeoutMs: 10
|
|
105
|
+
})
|
|
106
|
+
|
|
107
|
+
const report = await monitor.runOnce()
|
|
108
|
+
|
|
109
|
+
expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/lookup', expect.objectContaining({
|
|
110
|
+
signal: expect.anything()
|
|
111
|
+
}))
|
|
112
|
+
expect(report.results[0].ok).toBe(false)
|
|
113
|
+
expect(report.results[0].error).toContain('timed out')
|
|
114
|
+
expect(report.summary.failedProbeCount).toBe(1)
|
|
115
|
+
})
|
|
116
|
+
})
|