@bsv/overlay-express 2.2.1 → 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 (53) hide show
  1. package/README.md +33 -0
  2. package/dist/cjs/mod.js +10 -1
  3. package/dist/cjs/mod.js.map +1 -1
  4. package/dist/cjs/package.json +12 -11
  5. package/dist/cjs/src/BanAwareDiscoveryStorage.js +78 -0
  6. package/dist/cjs/src/BanAwareDiscoveryStorage.js.map +1 -0
  7. package/dist/cjs/src/BanAwareTopicManager.js +71 -0
  8. package/dist/cjs/src/BanAwareTopicManager.js.map +1 -0
  9. package/dist/cjs/src/OverlayExpress.js +375 -96
  10. package/dist/cjs/src/OverlayExpress.js.map +1 -1
  11. package/dist/cjs/src/OverlayMonitor.js +464 -0
  12. package/dist/cjs/src/OverlayMonitor.js.map +1 -0
  13. package/dist/cjs/src/ReorgStream.js +193 -0
  14. package/dist/cjs/src/ReorgStream.js.map +1 -0
  15. package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
  16. package/dist/esm/mod.js +3 -0
  17. package/dist/esm/mod.js.map +1 -1
  18. package/dist/esm/src/BanAwareDiscoveryStorage.js +79 -0
  19. package/dist/esm/src/BanAwareDiscoveryStorage.js.map +1 -0
  20. package/dist/esm/src/BanAwareTopicManager.js +71 -0
  21. package/dist/esm/src/BanAwareTopicManager.js.map +1 -0
  22. package/dist/esm/src/OverlayExpress.js +375 -94
  23. package/dist/esm/src/OverlayExpress.js.map +1 -1
  24. package/dist/esm/src/OverlayMonitor.js +458 -0
  25. package/dist/esm/src/OverlayMonitor.js.map +1 -0
  26. package/dist/esm/src/ReorgStream.js +190 -0
  27. package/dist/esm/src/ReorgStream.js.map +1 -0
  28. package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
  29. package/dist/types/mod.d.ts +4 -1
  30. package/dist/types/mod.d.ts.map +1 -1
  31. package/dist/types/src/BanAwareDiscoveryStorage.d.ts +36 -0
  32. package/dist/types/src/BanAwareDiscoveryStorage.d.ts.map +1 -0
  33. package/dist/types/src/BanAwareTopicManager.d.ts +28 -0
  34. package/dist/types/src/BanAwareTopicManager.d.ts.map +1 -0
  35. package/dist/types/src/OverlayExpress.d.ts +82 -4
  36. package/dist/types/src/OverlayExpress.d.ts.map +1 -1
  37. package/dist/types/src/OverlayMonitor.d.ts +169 -0
  38. package/dist/types/src/OverlayMonitor.d.ts.map +1 -0
  39. package/dist/types/src/ReorgStream.d.ts +74 -0
  40. package/dist/types/src/ReorgStream.d.ts.map +1 -0
  41. package/dist/types/tsconfig.types.tsbuildinfo +1 -1
  42. package/mod.ts +20 -1
  43. package/package.json +12 -11
  44. package/src/BanAwareDiscoveryStorage.ts +91 -0
  45. package/src/BanAwareTopicManager.ts +87 -0
  46. package/src/OverlayExpress.ts +461 -102
  47. package/src/OverlayMonitor.ts +657 -0
  48. package/src/ReorgStream.ts +221 -0
  49. package/src/__tests__/BanAwareDiscoveryStorage.test.ts +131 -0
  50. package/src/__tests__/BanAwareTopicManager.test.ts +132 -0
  51. package/src/__tests__/OverlayExpress.test.ts +86 -1
  52. package/src/__tests__/OverlayMonitor.test.ts +181 -0
  53. package/src/__tests__/ReorgStream.test.ts +66 -0
@@ -0,0 +1,181 @@
1
+ import { describe, it, expect, jest } from '@jest/globals'
2
+ import { Transaction } from '@bsv/sdk'
3
+ import { OverlayMonitor, analyzeOverlayAnchorTip, 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('reports stale and mismatched BASM anchor tips', () => {
91
+ const result = analyzeOverlayAnchorTip({
92
+ target: 'local-overlay',
93
+ url: 'https://overlay.example/requestTopicAnchorTip',
94
+ probe: 'anchors',
95
+ topic: 'tm_example',
96
+ status: 200,
97
+ ok: true,
98
+ responseBody: {
99
+ blockHeight: 850000,
100
+ tac: '11'.repeat(32),
101
+ expiredUnprovenCount: 2
102
+ },
103
+ responseBytes: 128,
104
+ durationMs: 5,
105
+ expectedTac: '22'.repeat(32),
106
+ currentHeight: 850020,
107
+ thresholds: {
108
+ anchorTipLagBlocks: 6,
109
+ expiredUnprovenCount: 0
110
+ }
111
+ })
112
+
113
+ expect(result.warnings.map(warning => warning.code)).toEqual([
114
+ 'anchor-tip-mismatch',
115
+ 'anchor-stale-height',
116
+ 'expired-unproven-state'
117
+ ])
118
+ })
119
+
120
+ it('runs configured anchor probes through Overlay Express BASM endpoints', async () => {
121
+ const responseBody = JSON.stringify({
122
+ topic: 'tm_example',
123
+ blockHeight: 850000,
124
+ tac: '11'.repeat(32)
125
+ })
126
+ const fetchImpl = jest.fn<typeof fetch>(async () => new Response(responseBody, { status: 200 }))
127
+ const monitor = new OverlayMonitor({
128
+ targets: [
129
+ {
130
+ name: 'local-overlay',
131
+ baseUrl: 'https://overlay.example',
132
+ probes: [],
133
+ anchorProbes: [
134
+ {
135
+ name: 'topic-tip',
136
+ topic: 'tm_example',
137
+ expectedTac: '11'.repeat(32)
138
+ }
139
+ ]
140
+ }
141
+ ],
142
+ fetchImpl
143
+ })
144
+
145
+ const report = await monitor.runOnce()
146
+
147
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/requestTopicAnchorTip', expect.objectContaining({
148
+ method: 'POST',
149
+ headers: expect.objectContaining({ 'x-bsv-topic': 'tm_example' })
150
+ }))
151
+ expect(report.summary.anchorProbeCount).toBe(1)
152
+ expect(report.anchorResults[0].warnings).toHaveLength(0)
153
+ })
154
+
155
+ it('aborts a probe that exceeds the configured timeout', async () => {
156
+ // Never resolves on its own; only settles when the abort signal fires.
157
+ const fetchImpl = jest.fn<typeof fetch>(async (_url, init) => await new Promise<Response>((_resolve, reject) => {
158
+ init?.signal?.addEventListener('abort', () => reject(new Error('aborted')))
159
+ }))
160
+ const monitor = new OverlayMonitor({
161
+ targets: [
162
+ {
163
+ name: 'slow-overlay',
164
+ baseUrl: 'https://overlay.example',
165
+ probes: [{ name: 'slow', service: 'ls_slow', query: {} }]
166
+ }
167
+ ],
168
+ fetchImpl,
169
+ timeoutMs: 10
170
+ })
171
+
172
+ const report = await monitor.runOnce()
173
+
174
+ expect(fetchImpl).toHaveBeenCalledWith('https://overlay.example/lookup', expect.objectContaining({
175
+ signal: expect.anything()
176
+ }))
177
+ expect(report.results[0].ok).toBe(false)
178
+ expect(report.results[0].error).toContain('timed out')
179
+ expect(report.summary.failedProbeCount).toBe(1)
180
+ })
181
+ })
@@ -0,0 +1,66 @@
1
+ import { parseReorgEvent, extractSseFrames } from '../ReorgStream.js'
2
+
3
+ const HASH_A = 'AABB000000000000000000000000000000000000000000000000000000000000'
4
+ const HASH_B = 'ccdd000000000000000000000000000000000000000000000000000000000000'
5
+
6
+ describe('parseReorgEvent', () => {
7
+ it('maps a go-chaintracks ReorgEvent to handleReorg input (normalizing hashes)', () => {
8
+ const event = JSON.stringify({
9
+ orphanedHashes: [HASH_A, HASH_B],
10
+ commonAncestor: { height: 100, hash: '00ff' },
11
+ newTip: { height: 103, hash: '11ee' },
12
+ depth: 3
13
+ })
14
+
15
+ const result = parseReorgEvent(event)
16
+
17
+ expect(result).toEqual({
18
+ orphanedBlockHashes: [HASH_A.toLowerCase(), HASH_B],
19
+ rebuildFromHeight: 101,
20
+ newTipHeight: 103
21
+ })
22
+ })
23
+
24
+ it('falls back to depth when commonAncestor is absent (reorg past pruned history)', () => {
25
+ const event = JSON.stringify({
26
+ orphanedHashes: [HASH_A],
27
+ commonAncestor: null,
28
+ newTip: { height: 103, hash: '11ee' },
29
+ depth: 3
30
+ })
31
+
32
+ const result = parseReorgEvent(event)
33
+
34
+ // 103 - 3 + 1 = 101
35
+ expect(result?.rebuildFromHeight).toBe(101)
36
+ expect(result?.newTipHeight).toBe(103)
37
+ })
38
+
39
+ it('returns null for malformed frames', () => {
40
+ expect(parseReorgEvent('not json')).toBeNull()
41
+ expect(parseReorgEvent(JSON.stringify({ orphanedHashes: [] }))).toBeNull() // no newTip
42
+ })
43
+ })
44
+
45
+ describe('extractSseFrames', () => {
46
+ it('extracts complete data frames and ignores keepalive comments', () => {
47
+ const buffer = 'data: {"a":1}\n\n: keepalive\n\ndata: {"b":2}\n\n'
48
+ const { events, rest } = extractSseFrames(buffer)
49
+ expect(events).toEqual(['{"a":1}', '{"b":2}'])
50
+ expect(rest).toBe('')
51
+ })
52
+
53
+ it('retains a partial trailing frame in rest', () => {
54
+ const buffer = 'data: {"a":1}\n\ndata: {"b":'
55
+ const { events, rest } = extractSseFrames(buffer)
56
+ expect(events).toEqual(['{"a":1}'])
57
+ expect(rest).toBe('data: {"b":')
58
+ })
59
+
60
+ it('concatenates multi-line data fields within one frame', () => {
61
+ const buffer = 'data: {"a":\ndata: 1}\n\n'
62
+ const { events, rest } = extractSseFrames(buffer)
63
+ expect(events).toEqual(['{"a":1}'])
64
+ expect(rest).toBe('')
65
+ })
66
+ })