@bsv/overlay-express 2.2.1 → 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 +11 -10
- package/dist/cjs/src/OverlayExpress.js +27 -1
- 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/OverlayExpress.js +27 -1
- 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 +6 -0
- 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 +11 -10
- package/src/OverlayExpress.ts +30 -2
- package/src/OverlayMonitor.ts +445 -0
- package/src/__tests__/OverlayExpress.test.ts +86 -1
- package/src/__tests__/OverlayMonitor.test.ts +116 -0
package/mod.ts
CHANGED
|
@@ -11,3 +11,16 @@ export {
|
|
|
11
11
|
export { BanService, type BannedRecord } from './src/BanService.js'
|
|
12
12
|
export { BanAwareLookupWrapper } from './src/BanAwareLookupWrapper.js'
|
|
13
13
|
export { JanitorService, type JanitorConfig, type JanitorReport, type HostHealthResult } from './src/JanitorService.js'
|
|
14
|
+
export {
|
|
15
|
+
OverlayMonitor,
|
|
16
|
+
analyzeOverlayLookupResponse,
|
|
17
|
+
type OverlayLookupOutputSummary,
|
|
18
|
+
type OverlayLookupProbe,
|
|
19
|
+
type OverlayLookupProbeResult,
|
|
20
|
+
type OverlayMonitorConfig,
|
|
21
|
+
type OverlayMonitorLogger,
|
|
22
|
+
type OverlayMonitorReport,
|
|
23
|
+
type OverlayMonitorTarget,
|
|
24
|
+
type OverlayMonitorThresholds,
|
|
25
|
+
type OverlayMonitorWarning
|
|
26
|
+
} from './src/OverlayMonitor.js'
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bsv/overlay-express",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "BSV Blockchain Overlay Express",
|
|
6
6
|
"main": "dist/cjs/mod.js",
|
|
@@ -44,29 +44,30 @@
|
|
|
44
44
|
},
|
|
45
45
|
"homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express#readme",
|
|
46
46
|
"devDependencies": {
|
|
47
|
-
"@jest/globals": "^30.
|
|
47
|
+
"@jest/globals": "^30.4.1",
|
|
48
48
|
"@types/body-parser": "^1.19.5",
|
|
49
49
|
"@types/express": "^5.0.0",
|
|
50
50
|
"@types/jest": "^30.0.0",
|
|
51
|
-
"
|
|
52
|
-
"
|
|
51
|
+
"@types/node": "^25.9.1",
|
|
52
|
+
"jest": "^30.4.2",
|
|
53
|
+
"ts-jest": "^29.4.11",
|
|
53
54
|
"ts-standard": "^12.0.2",
|
|
54
55
|
"ts2md": "^0.2.0",
|
|
55
56
|
"tsconfig-to-dual-package": "^1.2.0",
|
|
56
|
-
"typescript": "^
|
|
57
|
+
"typescript": "^6.0.3"
|
|
57
58
|
},
|
|
58
59
|
"dependencies": {
|
|
59
|
-
"@bsv/auth-express-middleware": "^2.0.
|
|
60
|
-
"@bsv/overlay": "^2.0.
|
|
60
|
+
"@bsv/auth-express-middleware": "^2.0.6",
|
|
61
|
+
"@bsv/overlay": "^2.0.3",
|
|
61
62
|
"@bsv/overlay-discovery-services": "^2.0.3",
|
|
62
|
-
"@bsv/sdk": "^2.1.
|
|
63
|
+
"@bsv/sdk": "^2.1.3",
|
|
63
64
|
"@bsv/wallet-toolbox-client": "^2.1.28",
|
|
64
65
|
"body-parser": "^2.2.2",
|
|
65
66
|
"chalk": "^5.6.2",
|
|
66
67
|
"express": "^5.2.1",
|
|
67
|
-
"knex": "^3.
|
|
68
|
+
"knex": "^3.2.10",
|
|
68
69
|
"mongodb": "^7.1.0",
|
|
69
|
-
"uuid": "^
|
|
70
|
+
"uuid": "^14.0.0"
|
|
70
71
|
},
|
|
71
72
|
"scripts": {
|
|
72
73
|
"test": "jest",
|
package/src/OverlayExpress.ts
CHANGED
|
@@ -189,6 +189,9 @@ export default class OverlayExpress {
|
|
|
189
189
|
// ARC API Key
|
|
190
190
|
arcApiKey: string | undefined = undefined
|
|
191
191
|
|
|
192
|
+
// Optional ARC callback token for /arc-ingest notifications
|
|
193
|
+
arcCallbackToken: string | undefined = undefined
|
|
194
|
+
|
|
192
195
|
// Verbose request logging
|
|
193
196
|
verboseRequestLogging: boolean = false
|
|
194
197
|
|
|
@@ -372,6 +375,15 @@ export default class OverlayExpress {
|
|
|
372
375
|
this.logger.log(chalk.blue('ARC API key has been configured.'))
|
|
373
376
|
}
|
|
374
377
|
|
|
378
|
+
/**
|
|
379
|
+
* Configures the ARC callback token expected by /arc-ingest.
|
|
380
|
+
* @param token - The token ARC should present when posting callback notifications.
|
|
381
|
+
*/
|
|
382
|
+
configureArcCallbackToken (token: string): void {
|
|
383
|
+
this.arcCallbackToken = token
|
|
384
|
+
this.logger.log(chalk.blue('ARC callback token has been configured.'))
|
|
385
|
+
}
|
|
386
|
+
|
|
375
387
|
/**
|
|
376
388
|
* Enables or disables GASP synchronization (high-level setting).
|
|
377
389
|
* This is a broad toggle that can be overridden or customized through syncConfiguration.
|
|
@@ -581,7 +593,11 @@ export default class OverlayExpress {
|
|
|
581
593
|
private buildBroadcaster (): Broadcaster | undefined {
|
|
582
594
|
if (typeof this.arcApiKey !== 'string') return undefined
|
|
583
595
|
const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
|
|
584
|
-
return new ARC(arcUrl, {
|
|
596
|
+
return new ARC(arcUrl, {
|
|
597
|
+
apiKey: this.arcApiKey,
|
|
598
|
+
callbackUrl: `https://${this.advertisableFQDN}/arc-ingest`,
|
|
599
|
+
callbackToken: this.arcCallbackToken
|
|
600
|
+
})
|
|
585
601
|
}
|
|
586
602
|
|
|
587
603
|
/** Resolve the SLAP trackers from config or network defaults. */
|
|
@@ -1253,6 +1269,18 @@ export default class OverlayExpress {
|
|
|
1253
1269
|
this.app.post('/arc-ingest', (req, res) => {
|
|
1254
1270
|
; (async () => {
|
|
1255
1271
|
try {
|
|
1272
|
+
if (typeof this.arcCallbackToken === 'string' && this.arcCallbackToken.length > 0) {
|
|
1273
|
+
const authorization = req.headers.authorization
|
|
1274
|
+
const headerToken = Array.isArray(authorization) ? authorization[0] : authorization
|
|
1275
|
+
const xCallbackToken = req.headers['x-callback-token']
|
|
1276
|
+
const callbackToken = Array.isArray(xCallbackToken) ? xCallbackToken[0] : xCallbackToken
|
|
1277
|
+
const bearerToken = typeof headerToken === 'string' && headerToken.startsWith('Bearer ')
|
|
1278
|
+
? headerToken.slice('Bearer '.length)
|
|
1279
|
+
: headerToken
|
|
1280
|
+
if (bearerToken !== this.arcCallbackToken && callbackToken !== this.arcCallbackToken) {
|
|
1281
|
+
return res.status(401).json({ status: 'error', message: 'Unauthorized callback' })
|
|
1282
|
+
}
|
|
1283
|
+
}
|
|
1256
1284
|
const { txid, merklePath: merklePathHex, blockHeight } = req.body
|
|
1257
1285
|
const merklePath = MerklePath.fromHex(merklePathHex)
|
|
1258
1286
|
await engine.handleNewMerkleProof(txid, merklePath, blockHeight)
|
|
@@ -1351,7 +1379,7 @@ export default class OverlayExpress {
|
|
|
1351
1379
|
*/
|
|
1352
1380
|
const checkAdminAuth = (req: express.Request, res: express.Response, next: express.NextFunction): void => {
|
|
1353
1381
|
// Method 1: BSV mutual authentication (identity key match)
|
|
1354
|
-
const authReq = req as AuthRequest
|
|
1382
|
+
const authReq = req as unknown as AuthRequest
|
|
1355
1383
|
if (
|
|
1356
1384
|
typeof this.adminIdentityKey === 'string' &&
|
|
1357
1385
|
authReq.auth !== undefined &&
|
|
@@ -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()
|