@bsv/overlay-express 2.3.0 → 2.3.1

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 (51) hide show
  1. package/dist/cjs/mod.js +7 -1
  2. package/dist/cjs/mod.js.map +1 -1
  3. package/dist/cjs/package.json +4 -4
  4. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  6. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  8. package/dist/cjs/src/OverlayExpress.js +348 -95
  9. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  10. package/dist/cjs/src/OverlayMonitor.js +166 -8
  11. package/dist/cjs/src/OverlayMonitor.js.map +1 -1
  12. package/dist/cjs/src/ReorgStream.js +193 -0
  13. package/dist/cjs/src/ReorgStream.js.map +1 -0
  14. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  15. package/dist/esm/mod.js +3 -1
  16. package/dist/esm/mod.js.map +1 -1
  17. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  19. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  20. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  21. package/dist/esm/src/OverlayExpress.js +348 -93
  22. package/dist/esm/src/OverlayExpress.js.map +1 -1
  23. package/dist/esm/src/OverlayMonitor.js +160 -6
  24. package/dist/esm/src/OverlayMonitor.js.map +1 -1
  25. package/dist/esm/src/ReorgStream.js +190 -0
  26. package/dist/esm/src/ReorgStream.js.map +1 -0
  27. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  28. package/dist/types/mod.d.ts +4 -2
  29. package/dist/types/mod.d.ts.map +1 -1
  30. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  32. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  34. package/dist/types/src/OverlayExpress.d.ts +76 -4
  35. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  36. package/dist/types/src/OverlayMonitor.d.ts +45 -1
  37. package/dist/types/src/OverlayMonitor.d.ts.map +1 -1
  38. package/dist/types/src/ReorgStream.d.ts +74 -0
  39. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  40. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  41. package/mod.ts +7 -1
  42. package/package.json +4 -4
  43. package/src/BanAwareDiscoveryStorage.ts +91 -0
  44. package/src/BanAwareTopicManager.ts +87 -0
  45. package/src/OverlayExpress.ts +431 -100
  46. package/src/OverlayMonitor.ts +219 -7
  47. package/src/ReorgStream.ts +221 -0
  48. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  49. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  50. package/src/__tests__/OverlayMonitor.test.ts +66 -1
  51. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -13,10 +13,20 @@ export interface OverlayLookupProbe {
13
13
  maxOutputs?: number
14
14
  }
15
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
+
16
25
  export interface OverlayMonitorTarget {
17
26
  name: string
18
27
  baseUrl: string
19
28
  probes: OverlayLookupProbe[]
29
+ anchorProbes?: OverlayAnchorProbe[]
20
30
  headers?: Record<string, string>
21
31
  }
22
32
 
@@ -25,6 +35,8 @@ export interface OverlayMonitorThresholds {
25
35
  beefBytes?: number
26
36
  txsWithoutProof?: number
27
37
  requireSubjectProof?: boolean
38
+ anchorTipLagBlocks?: number
39
+ expiredUnprovenCount?: number
28
40
  }
29
41
 
30
42
  export interface OverlayMonitorConfig {
@@ -40,7 +52,7 @@ export interface OverlayMonitorConfig {
40
52
  }
41
53
 
42
54
  export interface OverlayMonitorWarning {
43
- code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing'
55
+ code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing' | 'anchor-tip-mismatch' | 'anchor-stale-height' | 'expired-unproven-state'
44
56
  message: string
45
57
  value: number | boolean
46
58
  threshold?: number | boolean
@@ -78,14 +90,31 @@ export interface OverlayLookupProbeResult {
78
90
  error?: string
79
91
  }
80
92
 
93
+ export interface OverlayAnchorProbeResult {
94
+ target: string
95
+ url: string
96
+ probe: string
97
+ topic: string
98
+ status: number
99
+ ok: boolean
100
+ responseBytes: number
101
+ blockHeight?: number
102
+ tac?: string
103
+ warnings: OverlayMonitorWarning[]
104
+ durationMs: number
105
+ error?: string
106
+ }
107
+
81
108
  export interface OverlayMonitorReport {
82
109
  startedAt: Date
83
110
  completedAt: Date
84
111
  durationMs: number
85
112
  results: OverlayLookupProbeResult[]
113
+ anchorResults: OverlayAnchorProbeResult[]
86
114
  summary: {
87
115
  targetCount: number
88
116
  probeCount: number
117
+ anchorProbeCount: number
89
118
  failedProbeCount: number
90
119
  responseBytes: number
91
120
  outputCount: number
@@ -114,7 +143,9 @@ const defaultThresholds: Required<OverlayMonitorThresholds> = {
114
143
  responseBytes: 1024 * 1024,
115
144
  beefBytes: 64 * 1024,
116
145
  txsWithoutProof: 1,
117
- requireSubjectProof: true
146
+ requireSubjectProof: true,
147
+ anchorTipLagBlocks: 6,
148
+ expiredUnprovenCount: 0
118
149
  }
119
150
 
120
151
  /**
@@ -150,11 +181,15 @@ export class OverlayMonitor {
150
181
  async runOnce (): Promise<OverlayMonitorReport> {
151
182
  const startedAt = this.now()
152
183
  const results: OverlayLookupProbeResult[] = []
184
+ const anchorResults: OverlayAnchorProbeResult[] = []
153
185
 
154
186
  for (const target of this.targets) {
155
187
  for (const probe of target.probes) {
156
188
  results.push(await this.runProbe(target, probe))
157
189
  }
190
+ for (const probe of target.anchorProbes ?? []) {
191
+ anchorResults.push(await this.runAnchorProbe(target, probe))
192
+ }
158
193
  }
159
194
 
160
195
  const completedAt = this.now()
@@ -163,7 +198,8 @@ export class OverlayMonitor {
163
198
  completedAt,
164
199
  durationMs: completedAt.getTime() - startedAt.getTime(),
165
200
  results,
166
- summary: summarize(results, this.targets.length)
201
+ anchorResults,
202
+ summary: summarize(results, anchorResults, this.targets.length)
167
203
  }
168
204
 
169
205
  await this.onReport?.(report)
@@ -266,6 +302,154 @@ export class OverlayMonitor {
266
302
  clearTimeout(timeout)
267
303
  }
268
304
  }
305
+
306
+ private async runAnchorProbe(target: OverlayMonitorTarget, probe: OverlayAnchorProbe): Promise<OverlayAnchorProbeResult> {
307
+ const startedAt = this.now()
308
+ const url = new URL('/requestTopicAnchorTip', target.baseUrl).toString()
309
+ const controller = new AbortController()
310
+ const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
311
+
312
+ try {
313
+ const response = await this.fetchImpl(url, {
314
+ method: 'POST',
315
+ headers: {
316
+ Accept: 'application/json',
317
+ 'Content-Type': 'application/json',
318
+ 'x-bsv-topic': probe.topic,
319
+ ...target.headers
320
+ },
321
+ body: JSON.stringify({}),
322
+ signal: controller.signal
323
+ })
324
+ const text = await response.text()
325
+ const responseBytes = new TextEncoder().encode(text).length
326
+ const completedAt = this.now()
327
+ let body: Record<string, unknown>
328
+
329
+ try {
330
+ body = text.length === 0 ? {} : JSON.parse(text)
331
+ } catch (error) {
332
+ return makeFailedAnchorResult({
333
+ target,
334
+ probe,
335
+ url,
336
+ status: response.status,
337
+ ok: response.ok,
338
+ responseBytes,
339
+ durationMs: completedAt.getTime() - startedAt.getTime(),
340
+ error: error instanceof Error ? error.message : 'Invalid JSON response'
341
+ })
342
+ }
343
+
344
+ return analyzeOverlayAnchorTip({
345
+ target: target.name,
346
+ url,
347
+ probe: probe.name ?? probe.topic,
348
+ topic: probe.topic,
349
+ status: response.status,
350
+ ok: response.ok,
351
+ responseBody: body,
352
+ responseBytes,
353
+ durationMs: completedAt.getTime() - startedAt.getTime(),
354
+ thresholds: this.thresholds,
355
+ expectedTac: probe.expectedTac,
356
+ expectedBlockHeight: probe.expectedBlockHeight,
357
+ currentHeight: probe.currentHeight,
358
+ maxTipLagBlocks: probe.maxTipLagBlocks
359
+ })
360
+ } catch (error) {
361
+ const completedAt = this.now()
362
+ const fallbackMessage = error instanceof Error ? error.message : 'Anchor probe failed'
363
+ const message = controller.signal.aborted
364
+ ? `Anchor probe timed out after ${this.timeoutMs}ms`
365
+ : fallbackMessage
366
+ return makeFailedAnchorResult({
367
+ target,
368
+ probe,
369
+ url,
370
+ status: 0,
371
+ ok: false,
372
+ responseBytes: 0,
373
+ durationMs: completedAt.getTime() - startedAt.getTime(),
374
+ error: message
375
+ })
376
+ } finally {
377
+ clearTimeout(timeout)
378
+ }
379
+ }
380
+ }
381
+
382
+ export function analyzeOverlayAnchorTip(options: {
383
+ target: string
384
+ url: string
385
+ probe: string
386
+ topic: string
387
+ status: number
388
+ ok: boolean
389
+ responseBody: Record<string, unknown>
390
+ responseBytes: number
391
+ durationMs: number
392
+ thresholds?: OverlayMonitorThresholds
393
+ expectedTac?: string
394
+ expectedBlockHeight?: number
395
+ currentHeight?: number
396
+ maxTipLagBlocks?: number
397
+ }): OverlayAnchorProbeResult {
398
+ const thresholds = { ...defaultThresholds, ...options.thresholds }
399
+ const blockHeight = typeof options.responseBody.blockHeight === 'number' ? options.responseBody.blockHeight : undefined
400
+ const tac = typeof options.responseBody.tac === 'string' ? options.responseBody.tac : undefined
401
+ let expiredUnprovenCount: number | undefined
402
+ if (typeof options.responseBody.expiredUnprovenCount === 'number') {
403
+ expiredUnprovenCount = options.responseBody.expiredUnprovenCount
404
+ } else if (typeof options.responseBody.unprovenExpiredCount === 'number') {
405
+ expiredUnprovenCount = options.responseBody.unprovenExpiredCount
406
+ } else {
407
+ expiredUnprovenCount = undefined
408
+ }
409
+ const warnings: OverlayMonitorWarning[] = []
410
+
411
+ if (options.expectedTac !== undefined && tac !== undefined && tac !== options.expectedTac) {
412
+ warnings.push({
413
+ code: 'anchor-tip-mismatch',
414
+ message: 'Topic anchor TAC does not match expected value',
415
+ value: true,
416
+ threshold: false
417
+ })
418
+ }
419
+
420
+ const expectedHeight = options.expectedBlockHeight ?? options.currentHeight
421
+ const maxLag = options.maxTipLagBlocks ?? thresholds.anchorTipLagBlocks
422
+ if (expectedHeight !== undefined && blockHeight !== undefined && expectedHeight - blockHeight > maxLag) {
423
+ warnings.push({
424
+ code: 'anchor-stale-height',
425
+ message: `Topic anchor tip is ${expectedHeight - blockHeight} blocks behind`,
426
+ value: expectedHeight - blockHeight,
427
+ threshold: maxLag
428
+ })
429
+ }
430
+
431
+ if (expiredUnprovenCount !== undefined && expiredUnprovenCount > thresholds.expiredUnprovenCount) {
432
+ warnings.push({
433
+ code: 'expired-unproven-state',
434
+ message: `Overlay reports ${expiredUnprovenCount} expired unproven transactions`,
435
+ value: expiredUnprovenCount,
436
+ threshold: thresholds.expiredUnprovenCount
437
+ })
438
+ }
439
+
440
+ return {
441
+ target: options.target,
442
+ url: options.url,
443
+ probe: options.probe,
444
+ topic: options.topic,
445
+ status: options.status,
446
+ ok: options.ok,
447
+ responseBytes: options.responseBytes,
448
+ blockHeight,
449
+ tac,
450
+ warnings,
451
+ durationMs: options.durationMs
452
+ }
269
453
  }
270
454
 
271
455
  export function analyzeOverlayLookupResponse (options: AnalyzeOptions): OverlayLookupProbeResult {
@@ -332,18 +516,46 @@ function makeFailedResult (options: {
332
516
  }
333
517
  }
334
518
 
335
- function summarize (results: OverlayLookupProbeResult[], targetCount: number): OverlayMonitorReport['summary'] {
519
+ function makeFailedAnchorResult(options: {
520
+ target: OverlayMonitorTarget
521
+ probe: OverlayAnchorProbe
522
+ url: string
523
+ status: number
524
+ ok: boolean
525
+ responseBytes: number
526
+ durationMs: number
527
+ error: string
528
+ }): OverlayAnchorProbeResult {
529
+ return {
530
+ target: options.target.name,
531
+ url: options.url,
532
+ probe: options.probe.name ?? options.probe.topic,
533
+ topic: options.probe.topic,
534
+ status: options.status,
535
+ ok: options.ok,
536
+ responseBytes: options.responseBytes,
537
+ warnings: [],
538
+ durationMs: options.durationMs,
539
+ error: options.error
540
+ }
541
+ }
542
+
543
+ function summarize (results: OverlayLookupProbeResult[], anchorResults: OverlayAnchorProbeResult[], targetCount: number): OverlayMonitorReport['summary'] {
336
544
  return {
337
545
  targetCount,
338
546
  probeCount: results.length,
339
- failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length,
340
- responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0),
547
+ anchorProbeCount: anchorResults.length,
548
+ failedProbeCount: results.filter(result => !result.ok || result.error !== undefined).length +
549
+ anchorResults.filter(result => !result.ok || result.error !== undefined).length,
550
+ responseBytes: results.reduce((sum, result) => sum + result.responseBytes, 0) +
551
+ anchorResults.reduce((sum, result) => sum + result.responseBytes, 0),
341
552
  outputCount: results.reduce((sum, result) => sum + result.outputCount, 0),
342
553
  analyzedOutputCount: results.reduce((sum, result) => sum + result.analyzedOutputCount, 0),
343
554
  outputsMissingSubjectProof: results.reduce((sum, result) => {
344
555
  return sum + result.outputs.filter(output => output.subjectHasProof === false).length
345
556
  }, 0),
346
- warningCount: results.reduce((sum, result) => sum + result.warnings.length, 0)
557
+ warningCount: results.reduce((sum, result) => sum + result.warnings.length, 0) +
558
+ anchorResults.reduce((sum, result) => sum + result.warnings.length, 0)
347
559
  }
348
560
  }
349
561
 
@@ -0,0 +1,221 @@
1
+ /**
2
+ * Consumes the go-chaintracks (Arcade) reorg SSE stream (`GET /v2/reorg/stream`)
3
+ * and normalizes each `ReorgEvent` into the overlay engine's `handleReorg` input.
4
+ *
5
+ * The stream emits `data: <JSON>\n\n` frames (no `event:`/`id:` lines) with
6
+ * `: keepalive` comment frames in between. Because there are no event ids, a
7
+ * reconnect cannot replay events missed while disconnected — so every (re)connect
8
+ * triggers an `onConnect` catch-up (the engine's revalidation sweep).
9
+ */
10
+
11
+ /** Input shape accepted by `Engine.handleReorg`. */
12
+ export interface ReorgHandlerInput {
13
+ orphanedBlockHashes: string[]
14
+ rebuildFromHeight: number
15
+ newTipHeight: number
16
+ }
17
+
18
+ /**
19
+ * Parses a single SSE data frame (a go-chaintracks `ReorgEvent` JSON document)
20
+ * into `handleReorg` input. Returns `null` for malformed frames.
21
+ *
22
+ * `ReorgEvent` = { orphanedHashes: string[], commonAncestor: BlockHeader|null,
23
+ * newTip: BlockHeader, depth: number }. Block hashes are go-sdk `chainhash.Hash`
24
+ * values marshaled as reversed (display) hex; they are lower-cased here to match
25
+ * the overlay's stored block hashes.
26
+ */
27
+ export function parseReorgEvent (frame: string): ReorgHandlerInput | null {
28
+ let event: any
29
+ try {
30
+ event = JSON.parse(frame)
31
+ } catch {
32
+ return null
33
+ }
34
+
35
+ const newTipHeight = event?.newTip?.height
36
+ if (typeof newTipHeight !== 'number') {
37
+ return null
38
+ }
39
+
40
+ const orphanedBlockHashes: string[] = Array.isArray(event.orphanedHashes)
41
+ ? event.orphanedHashes
42
+ .filter((hash: unknown): hash is string => typeof hash === 'string')
43
+ .map((hash: string) => hash.toLowerCase())
44
+ : []
45
+
46
+ const ancestorHeight: unknown = event?.commonAncestor?.height
47
+ const depth: unknown = event?.depth
48
+ let rebuildFromHeight: number
49
+ if (typeof ancestorHeight === 'number') {
50
+ rebuildFromHeight = ancestorHeight + 1
51
+ } else if (typeof depth === 'number') {
52
+ // No common ancestor (e.g. reorg deeper than retained history): fall back to
53
+ // the reported depth from the new tip.
54
+ rebuildFromHeight = Math.max(0, newTipHeight - depth + 1)
55
+ } else {
56
+ return null
57
+ }
58
+
59
+ return { orphanedBlockHashes, rebuildFromHeight, newTipHeight }
60
+ }
61
+
62
+ /**
63
+ * Splits an SSE byte buffer into complete event payloads. Frames are delimited by
64
+ * a blank line (`\n\n`); within a frame, `data:` lines are concatenated and
65
+ * comment lines (starting with `:`) are ignored. Any trailing partial frame is
66
+ * returned in `rest` for the next read.
67
+ */
68
+ export function extractSseFrames (buffer: string): { events: string[], rest: string } {
69
+ const events: string[] = []
70
+ let working = buffer
71
+ let boundary = working.indexOf('\n\n')
72
+ while (boundary !== -1) {
73
+ const block = working.slice(0, boundary)
74
+ working = working.slice(boundary + 2)
75
+ const dataLines: string[] = []
76
+ for (const line of block.split('\n')) {
77
+ if (line.startsWith(':')) {
78
+ continue
79
+ }
80
+ if (line.startsWith('data:')) {
81
+ dataLines.push(line.slice(5).replace(/^ /, ''))
82
+ }
83
+ }
84
+ if (dataLines.length > 0) {
85
+ events.push(dataLines.join(''))
86
+ }
87
+ boundary = working.indexOf('\n\n')
88
+ }
89
+ return { events, rest: working }
90
+ }
91
+
92
+ export interface ReorgSseAdapterOptions {
93
+ /** Reorg SSE URL, e.g. `https://arcade.example/v2/reorg/stream`. */
94
+ url: string
95
+ /** Invoked for each parsed reorg event. */
96
+ onReorg: (input: ReorgHandlerInput) => Promise<void>
97
+ /** Invoked on every (re)connect for catch-up, since the stream has no replay. */
98
+ onConnect?: () => Promise<void>
99
+ logger?: Pick<typeof console, 'log' | 'warn' | 'error'>
100
+ /** Delay before reconnecting after the stream ends or errors. */
101
+ reconnectDelayMs?: number
102
+ /** Injectable fetch (defaults to global fetch); aids testing. */
103
+ fetchImpl?: typeof fetch
104
+ }
105
+
106
+ /**
107
+ * Long-lived SSE client that keeps the overlay's BASM anchors reconciled with
108
+ * chain reorgs. Auto-reconnects with a fixed delay and runs a catch-up on connect.
109
+ */
110
+ export class ReorgSseAdapter {
111
+ private readonly url: string
112
+ private readonly onReorg: (input: ReorgHandlerInput) => Promise<void>
113
+ private readonly onConnect?: () => Promise<void>
114
+ private readonly logger: Pick<typeof console, 'log' | 'warn' | 'error'>
115
+ private readonly reconnectDelayMs: number
116
+ private readonly fetchImpl: typeof fetch
117
+ private controller?: AbortController
118
+ private stopped = false
119
+
120
+ constructor (options: ReorgSseAdapterOptions) {
121
+ this.url = options.url
122
+ this.onReorg = options.onReorg
123
+ this.onConnect = options.onConnect
124
+ this.logger = options.logger ?? console
125
+ this.reconnectDelayMs = options.reconnectDelayMs ?? 5000
126
+ this.fetchImpl = options.fetchImpl ?? fetch
127
+ }
128
+
129
+ /** Begins consuming the stream in the background. */
130
+ start (): void {
131
+ if (this.stopped) {
132
+ return
133
+ }
134
+ void this.runLoop()
135
+ }
136
+
137
+ /** Stops consuming and aborts any in-flight connection. */
138
+ stop (): void {
139
+ this.stopped = true
140
+ this.controller?.abort()
141
+ }
142
+
143
+ private async runLoop (): Promise<void> {
144
+ while (!this.stopped) {
145
+ try {
146
+ await this.connectOnce()
147
+ } catch (error) {
148
+ if (!this.stopped) {
149
+ this.logger.warn(`[BASM] reorg stream error: ${error instanceof Error ? error.message : String(error)}`)
150
+ }
151
+ }
152
+ if (this.stopped) {
153
+ break
154
+ }
155
+ await this.delay(this.reconnectDelayMs)
156
+ }
157
+ }
158
+
159
+ private async connectOnce (): Promise<void> {
160
+ this.controller = new AbortController()
161
+ const response = await this.fetchImpl(this.url, {
162
+ headers: { Accept: 'text/event-stream' },
163
+ signal: this.controller.signal
164
+ })
165
+ if (!response.ok || response.body == null) {
166
+ throw new Error(`reorg stream responded ${response.status}`)
167
+ }
168
+
169
+ // No event-id replay on this stream: catch up on (re)connect.
170
+ await this.runCatchUp()
171
+ await this.pumpEvents(response.body.getReader())
172
+ }
173
+
174
+ private async runCatchUp (): Promise<void> {
175
+ if (this.onConnect === undefined) {
176
+ return
177
+ }
178
+ try {
179
+ await this.onConnect()
180
+ } catch (error) {
181
+ this.logger.warn(`[BASM] reorg catch-up failed: ${error instanceof Error ? error.message : String(error)}`)
182
+ }
183
+ }
184
+
185
+ private async pumpEvents (reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
186
+ const decoder = new TextDecoder()
187
+ let buffer = ''
188
+ while (!this.stopped) {
189
+ const { value, done } = await reader.read()
190
+ if (done) {
191
+ break
192
+ }
193
+ buffer += decoder.decode(value, { stream: true })
194
+ const { events, rest } = extractSseFrames(buffer)
195
+ buffer = rest
196
+ for (const frame of events) {
197
+ await this.processReorgFrame(frame)
198
+ }
199
+ }
200
+ }
201
+
202
+ private async processReorgFrame (frame: string): Promise<void> {
203
+ const input = parseReorgEvent(frame)
204
+ if (input === null) {
205
+ this.logger.warn('[BASM] skipping malformed reorg frame')
206
+ return
207
+ }
208
+ try {
209
+ await this.onReorg(input)
210
+ } catch (error) {
211
+ this.logger.error(`[BASM] handleReorg failed: ${error instanceof Error ? error.message : String(error)}`)
212
+ }
213
+ }
214
+
215
+ private async delay (ms: number): Promise<void> {
216
+ await new Promise<void>(resolve => {
217
+ const timer = setTimeout(resolve, ms)
218
+ timer.unref?.()
219
+ })
220
+ }
221
+ }
@@ -0,0 +1,131 @@
1
+ import { describe, it, expect, jest, beforeEach } from '@jest/globals'
2
+ import { BanService } from '../BanService.js'
3
+ import { BanAwareSHIPStorage, BanAwareSLAPStorage } from '../BanAwareDiscoveryStorage.js'
4
+
5
+ describe('BanAwareDiscoveryStorage', () => {
6
+ let mockBanService: jest.Mocked<BanService>
7
+ let mockLogger: any
8
+
9
+ beforeEach(() => {
10
+ jest.clearAllMocks()
11
+ mockBanService = {
12
+ isOutpointBanned: jest.fn<any>().mockResolvedValue(false),
13
+ isDomainBanned: jest.fn<any>().mockResolvedValue(false)
14
+ } as any
15
+ mockLogger = {
16
+ log: jest.fn()
17
+ }
18
+ })
19
+
20
+ describe('BanAwareSHIPStorage', () => {
21
+ it('should block banned outpoints', async () => {
22
+ const wrapped = {
23
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
24
+ }
25
+ mockBanService.isOutpointBanned.mockResolvedValue(true)
26
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
27
+
28
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://good.example', 'tm_users')
29
+
30
+ expect(wrapped.storeSHIPRecord).not.toHaveBeenCalled()
31
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
32
+ })
33
+
34
+ it('should block banned domains', async () => {
35
+ const wrapped = {
36
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
37
+ }
38
+ mockBanService.isDomainBanned.mockResolvedValue(true)
39
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
40
+
41
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://banned.example', 'tm_users')
42
+
43
+ expect(wrapped.storeSHIPRecord).not.toHaveBeenCalled()
44
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
45
+ })
46
+
47
+ it('should delegate when not banned', async () => {
48
+ const wrapped = {
49
+ storeSHIPRecord: jest.fn<any>().mockResolvedValue(undefined)
50
+ }
51
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
52
+
53
+ await storage.storeSHIPRecord('txid', 1, 'identity', 'https://good.example', 'tm_users')
54
+
55
+ expect(wrapped.storeSHIPRecord).toHaveBeenCalledWith('txid', 1, 'identity', 'https://good.example', 'tm_users')
56
+ })
57
+
58
+ it('should delegate read and delete methods', async () => {
59
+ const wrapped = {
60
+ ensureIndexes: jest.fn<any>().mockResolvedValue(undefined),
61
+ hasDuplicateRecord: jest.fn<any>().mockResolvedValue(true),
62
+ deleteSHIPRecord: jest.fn<any>().mockResolvedValue(undefined),
63
+ findRecord: jest.fn<any>().mockResolvedValue([{ txid: 'a', outputIndex: 1 }]),
64
+ findAll: jest.fn<any>().mockResolvedValue([{ txid: 'b', outputIndex: 2 }])
65
+ }
66
+ const storage = new BanAwareSHIPStorage(wrapped as any, mockBanService, mockLogger)
67
+
68
+ await storage.ensureIndexes()
69
+ await expect(storage.hasDuplicateRecord('identity', 'https://good.example', 'tm_users')).resolves.toBe(true)
70
+ await storage.deleteSHIPRecord('txid', 1)
71
+ await expect(storage.findRecord({ domain: 'https://good.example' })).resolves.toEqual([{ txid: 'a', outputIndex: 1 }])
72
+ await expect(storage.findAll(10, 0, 'desc')).resolves.toEqual([{ txid: 'b', outputIndex: 2 }])
73
+ })
74
+ })
75
+
76
+ describe('BanAwareSLAPStorage', () => {
77
+ it('should block banned outpoints', async () => {
78
+ const wrapped = {
79
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
80
+ }
81
+ mockBanService.isOutpointBanned.mockResolvedValue(true)
82
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
83
+
84
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://good.example', 'ls_users')
85
+
86
+ expect(wrapped.storeSLAPRecord).not.toHaveBeenCalled()
87
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned outpoint'))
88
+ })
89
+
90
+ it('should block banned domains', async () => {
91
+ const wrapped = {
92
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
93
+ }
94
+ mockBanService.isDomainBanned.mockResolvedValue(true)
95
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
96
+
97
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://banned.example', 'ls_users')
98
+
99
+ expect(wrapped.storeSLAPRecord).not.toHaveBeenCalled()
100
+ expect(mockLogger.log).toHaveBeenCalledWith(expect.stringContaining('banned domain'))
101
+ })
102
+
103
+ it('should delegate when not banned', async () => {
104
+ const wrapped = {
105
+ storeSLAPRecord: jest.fn<any>().mockResolvedValue(undefined)
106
+ }
107
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
108
+
109
+ await storage.storeSLAPRecord('txid', 1, 'identity', 'https://good.example', 'ls_users')
110
+
111
+ expect(wrapped.storeSLAPRecord).toHaveBeenCalledWith('txid', 1, 'identity', 'https://good.example', 'ls_users')
112
+ })
113
+
114
+ it('should delegate read and delete methods', async () => {
115
+ const wrapped = {
116
+ ensureIndexes: jest.fn<any>().mockResolvedValue(undefined),
117
+ hasDuplicateRecord: jest.fn<any>().mockResolvedValue(true),
118
+ deleteSLAPRecord: jest.fn<any>().mockResolvedValue(undefined),
119
+ findRecord: jest.fn<any>().mockResolvedValue([{ txid: 'a', outputIndex: 1 }]),
120
+ findAll: jest.fn<any>().mockResolvedValue([{ txid: 'b', outputIndex: 2 }])
121
+ }
122
+ const storage = new BanAwareSLAPStorage(wrapped as any, mockBanService, mockLogger)
123
+
124
+ await storage.ensureIndexes()
125
+ await expect(storage.hasDuplicateRecord('identity', 'https://good.example', 'ls_users')).resolves.toBe(true)
126
+ await storage.deleteSLAPRecord('txid', 1)
127
+ await expect(storage.findRecord({ domain: 'https://good.example' })).resolves.toEqual([{ txid: 'a', outputIndex: 1 }])
128
+ await expect(storage.findAll(10, 0, 'desc')).resolves.toEqual([{ txid: 'b', outputIndex: 2 }])
129
+ })
130
+ })
131
+ })