@bsv/overlay-express 2.4.1 → 2.4.2
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/dist/cjs/package.json +16 -16
- package/dist/cjs/src/OverlayExpress.js +35 -17
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/src/generalGuide.md.js +1 -1
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/src/OverlayExpress.js +34 -17
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/src/generalGuide.md.js +1 -1
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/src/generalGuide.md.d.ts +1 -1
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/package.json +17 -17
- package/src/OverlayExpress.ts +40 -17
- package/src/__tests__/OverlayExpress.test.ts +159 -1
- package/src/__tests__/OverlayProviders.live.test.ts +6 -2
- package/src/generalGuide.md.ts +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bsv/overlay-express",
|
|
3
|
-
"version": "2.4.
|
|
3
|
+
"version": "2.4.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "BSV Blockchain Overlay Express",
|
|
6
6
|
"main": "dist/cjs/mod.js",
|
|
@@ -45,29 +45,29 @@
|
|
|
45
45
|
"homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay-express#readme",
|
|
46
46
|
"devDependencies": {
|
|
47
47
|
"@jest/globals": "^30.4.1",
|
|
48
|
-
"@types/body-parser": "^1.19.
|
|
49
|
-
"@types/express": "^5.0.
|
|
48
|
+
"@types/body-parser": "^1.19.6",
|
|
49
|
+
"@types/express": "^5.0.6",
|
|
50
50
|
"@types/jest": "^30.0.0",
|
|
51
|
-
"@types/node": "^26.
|
|
51
|
+
"@types/node": "^26.1.1",
|
|
52
52
|
"jest": "^30.4.2",
|
|
53
|
-
"ts-jest": "^29.4.
|
|
54
|
-
"
|
|
55
|
-
"ts2md": "^0.2.0",
|
|
53
|
+
"ts-jest": "^29.4.12",
|
|
54
|
+
"ts2md": "^0.2.8",
|
|
56
55
|
"tsconfig-to-dual-package": "^1.2.0",
|
|
57
56
|
"typescript": "^6.0.3",
|
|
58
|
-
"
|
|
57
|
+
"oxlint": "^1.75.0",
|
|
58
|
+
"@bsv/sdk": "^2.2.0"
|
|
59
59
|
},
|
|
60
60
|
"dependencies": {
|
|
61
|
-
"@bsv/auth-express-middleware": "^2.1.0",
|
|
62
|
-
"@bsv/overlay": "^2.1.0",
|
|
63
|
-
"@bsv/overlay-discovery-services": "^2.1.0",
|
|
64
|
-
"@bsv/wallet-toolbox-client": "^2.3.2",
|
|
65
61
|
"body-parser": "^2.3.0",
|
|
66
62
|
"chalk": "^5.6.2",
|
|
67
63
|
"express": "^5.2.1",
|
|
68
|
-
"knex": "^3.
|
|
69
|
-
"mongodb": "^7.
|
|
70
|
-
"uuid": "^14.0.1"
|
|
64
|
+
"knex": "^3.3.0",
|
|
65
|
+
"mongodb": "^7.5.0",
|
|
66
|
+
"uuid": "^14.0.1",
|
|
67
|
+
"@bsv/auth-express-middleware": "^2.1.2",
|
|
68
|
+
"@bsv/overlay": "^2.2.1",
|
|
69
|
+
"@bsv/overlay-discovery-services": "^2.1.1",
|
|
70
|
+
"@bsv/wallet-toolbox-client": "^2.4.4"
|
|
71
71
|
},
|
|
72
72
|
"peerDependencies": {
|
|
73
73
|
"@bsv/sdk": "^2.1.6"
|
|
@@ -81,8 +81,8 @@
|
|
|
81
81
|
"test": "jest",
|
|
82
82
|
"test:watch": "jest --watch",
|
|
83
83
|
"test:coverage": "jest --coverage",
|
|
84
|
-
"lint": "
|
|
85
|
-
"lint:ci": "
|
|
84
|
+
"lint": "oxlint src",
|
|
85
|
+
"lint:ci": "oxlint src",
|
|
86
86
|
"build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
|
|
87
87
|
"dev": "tsc -b -w",
|
|
88
88
|
"prepublish": "npm run build",
|
package/src/OverlayExpress.ts
CHANGED
|
@@ -188,6 +188,18 @@ interface BASMCapableEngine extends Engine {
|
|
|
188
188
|
revalidateRecentAnchors: (depth?: number) => Promise<any>
|
|
189
189
|
}
|
|
190
190
|
|
|
191
|
+
function parseTopicsHeader (header: string): string[] {
|
|
192
|
+
const value = header.trim()
|
|
193
|
+
const parsed: unknown = value.startsWith('[')
|
|
194
|
+
? JSON.parse(value)
|
|
195
|
+
: value.split(',').map(topic => topic.trim())
|
|
196
|
+
|
|
197
|
+
if (!Array.isArray(parsed) || parsed.some(topic => typeof topic !== 'string' || topic.length === 0)) {
|
|
198
|
+
throw new TypeError('Invalid x-topics header: expected a comma-separated list or JSON string array')
|
|
199
|
+
}
|
|
200
|
+
return parsed
|
|
201
|
+
}
|
|
202
|
+
|
|
191
203
|
/**
|
|
192
204
|
* OverlayExpress class provides an Express-based server for hosting Overlay Services.
|
|
193
205
|
* It allows configuration of various components like databases, topic managers, and lookup services.
|
|
@@ -722,22 +734,29 @@ export default class OverlayExpress {
|
|
|
722
734
|
const knex = this.ensureKnex()
|
|
723
735
|
|
|
724
736
|
if (autoConfigureShipSlap) {
|
|
737
|
+
const mongoDb = this.ensureMongo()
|
|
738
|
+
const shipStorage = new DiscoveryServices.SHIPStorage(mongoDb)
|
|
739
|
+
const slapStorage = new DiscoveryServices.SLAPStorage(mongoDb)
|
|
740
|
+
|
|
741
|
+
// Run the one-time discovery migration before the engine can accept
|
|
742
|
+
// traffic, so a failed unique-index build is a visible startup failure.
|
|
743
|
+
await shipStorage.ensureIndexes()
|
|
744
|
+
await slapStorage.ensureIndexes()
|
|
745
|
+
|
|
725
746
|
this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager())
|
|
726
747
|
this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager())
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
return new DiscoveryServices.SLAPLookupService(storageForLookup as any)
|
|
740
|
-
})
|
|
748
|
+
|
|
749
|
+
const shipStorageForLookup = this.banService === undefined
|
|
750
|
+
? shipStorage
|
|
751
|
+
: new BanAwareSHIPStorage(shipStorage, this.banService, this.logger)
|
|
752
|
+
const slapStorageForLookup = this.banService === undefined
|
|
753
|
+
? slapStorage
|
|
754
|
+
: new BanAwareSLAPStorage(slapStorage, this.banService, this.logger)
|
|
755
|
+
|
|
756
|
+
this.services.ls_ship = new DiscoveryServices.SHIPLookupService(shipStorageForLookup as any)
|
|
757
|
+
this.services.ls_slap = new DiscoveryServices.SLAPLookupService(slapStorageForLookup as any)
|
|
758
|
+
this.logger.log(chalk.blue('Configured lookup service ls_ship with MongoDB'))
|
|
759
|
+
this.logger.log(chalk.blue('Configured lookup service ls_slap with MongoDB'))
|
|
741
760
|
}
|
|
742
761
|
|
|
743
762
|
this.wrapBanAwareServices()
|
|
@@ -1467,9 +1486,13 @@ export default class OverlayExpress {
|
|
|
1467
1486
|
if (typeof topicsHeader !== 'string') {
|
|
1468
1487
|
throw new TypeError('Missing x-topics header')
|
|
1469
1488
|
}
|
|
1470
|
-
const topics =
|
|
1489
|
+
const topics = parseTopicsHeader(topicsHeader)
|
|
1490
|
+
const body = req.body
|
|
1491
|
+
if (body == null || typeof body[Symbol.iterator] !== 'function' || body.length === 0) {
|
|
1492
|
+
throw new TypeError('Missing or empty BEEF body')
|
|
1493
|
+
}
|
|
1471
1494
|
let offChainValues: number[] | undefined
|
|
1472
|
-
let beef = Array.from(
|
|
1495
|
+
let beef = Array.from(body as number[])
|
|
1473
1496
|
if (includesOffChain) {
|
|
1474
1497
|
const r = new Utils.Reader(beef)
|
|
1475
1498
|
const l = r.readVarIntNum()
|
|
@@ -1982,7 +2005,7 @@ export default class OverlayExpress {
|
|
|
1982
2005
|
this.app.post('/admin/health-check', checkAdminAuth as any, (req, res) => {
|
|
1983
2006
|
; (async () => {
|
|
1984
2007
|
try {
|
|
1985
|
-
const
|
|
2008
|
+
const url = req.body?.url
|
|
1986
2009
|
if (typeof url !== 'string' || url.length === 0) {
|
|
1987
2010
|
return res.status(400).json({ status: 'error', message: 'url is required' })
|
|
1988
2011
|
}
|
|
@@ -4,6 +4,7 @@ import Knex from 'knex'
|
|
|
4
4
|
import { MongoClient } from 'mongodb'
|
|
5
5
|
import { TopicManager, LookupService } from '@bsv/overlay'
|
|
6
6
|
import { ChainTracker } from '@bsv/sdk'
|
|
7
|
+
import * as DiscoveryServices from '@bsv/overlay-discovery-services'
|
|
7
8
|
|
|
8
9
|
// Mock dependencies
|
|
9
10
|
jest.mock('knex')
|
|
@@ -503,6 +504,43 @@ describe('OverlayExpress', () => {
|
|
|
503
504
|
expect(overlayExpress.services.ls_slap).toBeDefined()
|
|
504
505
|
})
|
|
505
506
|
|
|
507
|
+
it('should initialize SHIP/SLAP indexes before completing engine configuration', async () => {
|
|
508
|
+
const shipEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
|
|
509
|
+
const slapEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
|
|
510
|
+
;(DiscoveryServices.SHIPStorage as any).mockImplementationOnce(() => ({
|
|
511
|
+
ensureIndexes: shipEnsureIndexes
|
|
512
|
+
}))
|
|
513
|
+
;(DiscoveryServices.SLAPStorage as any).mockImplementationOnce(() => ({
|
|
514
|
+
ensureIndexes: slapEnsureIndexes
|
|
515
|
+
}))
|
|
516
|
+
|
|
517
|
+
await overlayExpress.configureEngine(true)
|
|
518
|
+
|
|
519
|
+
expect(shipEnsureIndexes).toHaveBeenCalledTimes(1)
|
|
520
|
+
expect(slapEnsureIndexes).toHaveBeenCalledTimes(1)
|
|
521
|
+
expect(overlayExpress.engine).toBeDefined()
|
|
522
|
+
})
|
|
523
|
+
|
|
524
|
+
it('should fail engine configuration when discovery index initialization fails', async () => {
|
|
525
|
+
const indexError = new Error('discovery index migration failed')
|
|
526
|
+
const shipEnsureIndexes = jest.fn<any>().mockRejectedValue(indexError)
|
|
527
|
+
const slapEnsureIndexes = jest.fn<any>().mockResolvedValue(undefined)
|
|
528
|
+
;(DiscoveryServices.SHIPStorage as any).mockImplementationOnce(() => ({
|
|
529
|
+
ensureIndexes: shipEnsureIndexes
|
|
530
|
+
}))
|
|
531
|
+
;(DiscoveryServices.SLAPStorage as any).mockImplementationOnce(() => ({
|
|
532
|
+
ensureIndexes: slapEnsureIndexes
|
|
533
|
+
}))
|
|
534
|
+
|
|
535
|
+
await expect(overlayExpress.configureEngine(true)).rejects.toThrow(indexError)
|
|
536
|
+
|
|
537
|
+
expect(shipEnsureIndexes).toHaveBeenCalledTimes(1)
|
|
538
|
+
expect(slapEnsureIndexes).not.toHaveBeenCalled()
|
|
539
|
+
expect(overlayExpress.engine).toBeUndefined()
|
|
540
|
+
expect(overlayExpress.services.ls_ship).toBeUndefined()
|
|
541
|
+
expect(overlayExpress.services.ls_slap).toBeUndefined()
|
|
542
|
+
})
|
|
543
|
+
|
|
506
544
|
it('should configure engine without auto SHIP/SLAP', async () => {
|
|
507
545
|
await overlayExpress.configureEngine(false)
|
|
508
546
|
|
|
@@ -746,6 +784,125 @@ describe('OverlayExpress', () => {
|
|
|
746
784
|
expect(listenSpy).toHaveBeenCalledWith(3000, expect.any(Function))
|
|
747
785
|
})
|
|
748
786
|
|
|
787
|
+
it('accepts canonical and legacy X-Topics formats on /submit', async () => {
|
|
788
|
+
const postSpy = jest.spyOn(instance.app, 'post')
|
|
789
|
+
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
790
|
+
callback()
|
|
791
|
+
return {} as any
|
|
792
|
+
})
|
|
793
|
+
await instance.start()
|
|
794
|
+
|
|
795
|
+
const route = postSpy.mock.calls.find(call => call[0] === '/submit')
|
|
796
|
+
const handler: any = route === undefined ? undefined : route[route.length - 1]
|
|
797
|
+
expect(handler).toBeDefined()
|
|
798
|
+
|
|
799
|
+
for (const topicsHeader of ['tm_foo,tm_bar', '["tm_foo","tm_bar"]']) {
|
|
800
|
+
const res: any = {
|
|
801
|
+
status: jest.fn().mockReturnThis(),
|
|
802
|
+
json: jest.fn().mockReturnThis()
|
|
803
|
+
}
|
|
804
|
+
handler?.({
|
|
805
|
+
headers: { 'x-topics': topicsHeader },
|
|
806
|
+
body: Buffer.from([1, 2, 3])
|
|
807
|
+
}, res)
|
|
808
|
+
await new Promise(resolve => setImmediate(resolve))
|
|
809
|
+
}
|
|
810
|
+
|
|
811
|
+
expect(mockEngine.submit).toHaveBeenCalledTimes(2)
|
|
812
|
+
for (const call of mockEngine.submit.mock.calls) {
|
|
813
|
+
expect(call[0]).toEqual({
|
|
814
|
+
beef: [1, 2, 3],
|
|
815
|
+
topics: ['tm_foo', 'tm_bar'],
|
|
816
|
+
offChainValues: undefined
|
|
817
|
+
})
|
|
818
|
+
}
|
|
819
|
+
})
|
|
820
|
+
|
|
821
|
+
it('returns a clean 400 for an empty /submit body', async () => {
|
|
822
|
+
const postSpy = jest.spyOn(instance.app, 'post')
|
|
823
|
+
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
824
|
+
callback()
|
|
825
|
+
return {} as any
|
|
826
|
+
})
|
|
827
|
+
const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
|
|
828
|
+
await instance.start()
|
|
829
|
+
|
|
830
|
+
const route = postSpy.mock.calls.find(call => call[0] === '/submit')
|
|
831
|
+
const handler: any = route === undefined ? undefined : route[route.length - 1]
|
|
832
|
+
const res: any = {
|
|
833
|
+
status: jest.fn().mockReturnThis(),
|
|
834
|
+
json: jest.fn().mockReturnThis()
|
|
835
|
+
}
|
|
836
|
+
handler?.({ headers: { 'x-topics': 'tm_foo' }, body: undefined }, res)
|
|
837
|
+
await new Promise(resolve => setImmediate(resolve))
|
|
838
|
+
|
|
839
|
+
expect(res.status).toHaveBeenCalledWith(400)
|
|
840
|
+
expect(res.json).toHaveBeenCalledWith({
|
|
841
|
+
status: 'error',
|
|
842
|
+
message: 'Missing or empty BEEF body'
|
|
843
|
+
})
|
|
844
|
+
expect(mockEngine.submit).not.toHaveBeenCalled()
|
|
845
|
+
consoleError.mockRestore()
|
|
846
|
+
})
|
|
847
|
+
|
|
848
|
+
it.each([
|
|
849
|
+
['', 'an empty comma-separated list'],
|
|
850
|
+
['tm_foo,', 'an empty comma-separated topic'],
|
|
851
|
+
['["tm_foo",42]', 'a JSON array containing a non-string topic']
|
|
852
|
+
])('returns a clean 400 when X-Topics is %s (%s)', async (topicsHeader) => {
|
|
853
|
+
const postSpy = jest.spyOn(instance.app, 'post')
|
|
854
|
+
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
855
|
+
callback()
|
|
856
|
+
return {} as any
|
|
857
|
+
})
|
|
858
|
+
const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
|
|
859
|
+
await instance.start()
|
|
860
|
+
|
|
861
|
+
const route = postSpy.mock.calls.find(call => call[0] === '/submit')
|
|
862
|
+
const handler: any = route === undefined ? undefined : route[route.length - 1]
|
|
863
|
+
const res: any = {
|
|
864
|
+
status: jest.fn().mockReturnThis(),
|
|
865
|
+
json: jest.fn().mockReturnThis()
|
|
866
|
+
}
|
|
867
|
+
handler?.({
|
|
868
|
+
headers: { 'x-topics': topicsHeader },
|
|
869
|
+
body: Buffer.from([1, 2, 3])
|
|
870
|
+
}, res)
|
|
871
|
+
await new Promise(resolve => setImmediate(resolve))
|
|
872
|
+
|
|
873
|
+
expect(res.status).toHaveBeenCalledWith(400)
|
|
874
|
+
expect(res.json).toHaveBeenCalledWith({
|
|
875
|
+
status: 'error',
|
|
876
|
+
message: 'Invalid x-topics header: expected a comma-separated list or JSON string array'
|
|
877
|
+
})
|
|
878
|
+
expect(mockEngine.submit).not.toHaveBeenCalled()
|
|
879
|
+
consoleError.mockRestore()
|
|
880
|
+
})
|
|
881
|
+
|
|
882
|
+
it('returns a clean 400 when /admin/health-check has no body', async () => {
|
|
883
|
+
const postSpy = jest.spyOn(instance.app, 'post')
|
|
884
|
+
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
885
|
+
callback()
|
|
886
|
+
return {} as any
|
|
887
|
+
})
|
|
888
|
+
await instance.start()
|
|
889
|
+
|
|
890
|
+
const route = postSpy.mock.calls.find(call => call[0] === '/admin/health-check')
|
|
891
|
+
const handler: any = route === undefined ? undefined : route[route.length - 1]
|
|
892
|
+
const res: any = {
|
|
893
|
+
status: jest.fn().mockReturnThis(),
|
|
894
|
+
json: jest.fn().mockReturnThis()
|
|
895
|
+
}
|
|
896
|
+
handler?.({ body: undefined }, res)
|
|
897
|
+
await new Promise(resolve => setImmediate(resolve))
|
|
898
|
+
|
|
899
|
+
expect(res.status).toHaveBeenCalledWith(400)
|
|
900
|
+
expect(res.json).toHaveBeenCalledWith({
|
|
901
|
+
status: 'error',
|
|
902
|
+
message: 'url is required'
|
|
903
|
+
})
|
|
904
|
+
})
|
|
905
|
+
|
|
749
906
|
it('should set up CORS middleware', async () => {
|
|
750
907
|
const useSpy = jest.spyOn(instance.app, 'use')
|
|
751
908
|
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
@@ -1060,7 +1217,8 @@ describe('OverlayExpress', () => {
|
|
|
1060
1217
|
revokeAdvertisements: jest.fn(),
|
|
1061
1218
|
parseAdvertisement: jest.fn()
|
|
1062
1219
|
}
|
|
1063
|
-
instance.engine
|
|
1220
|
+
if (instance.engine === undefined) throw new Error('improper test setup')
|
|
1221
|
+
instance.engine.advertiser = mockAdvertiser
|
|
1064
1222
|
|
|
1065
1223
|
jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
|
|
1066
1224
|
callback()
|
|
@@ -19,7 +19,8 @@ describeLive('Overlay providers live integration', () => {
|
|
|
19
19
|
expect(header?.height).toBe(height)
|
|
20
20
|
expect(header?.hash).toMatch(/^[0-9a-f]{64}$/)
|
|
21
21
|
expect(header?.merkleRoot).toMatch(/^[0-9a-f]{64}$/)
|
|
22
|
-
|
|
22
|
+
if (header === undefined) throw new Error('header was not returned')
|
|
23
|
+
await expect(chaintracks.isValidRootForHeight(header.merkleRoot, height)).resolves.toBe(true)
|
|
23
24
|
})
|
|
24
25
|
|
|
25
26
|
test('fetches and validates a real mined mainnet Arcade proof', async () => {
|
|
@@ -34,6 +35,9 @@ describeLive('Overlay providers live integration', () => {
|
|
|
34
35
|
expect(proof?.txid).toBe(txid)
|
|
35
36
|
expect(proof?.blockHeight).toBeGreaterThan(0)
|
|
36
37
|
expect(proof?.merkleRoot).toMatch(/^[0-9a-f]{64}$/)
|
|
37
|
-
|
|
38
|
+
if (proof === undefined || proof.blockHeight === undefined) {
|
|
39
|
+
throw new Error('complete proof was not returned')
|
|
40
|
+
}
|
|
41
|
+
await expect(chaintracks.isValidRootForHeight(proof.merkleRoot, proof.blockHeight)).resolves.toBe(true)
|
|
38
42
|
})
|
|
39
43
|
})
|
package/src/generalGuide.md.ts
CHANGED
|
@@ -10,7 +10,7 @@ A Topic Manager controls addition and removal of transaction outputs to an Overl
|
|
|
10
10
|
#### Request Headers
|
|
11
11
|
\\\`\\\`\\\`json
|
|
12
12
|
{
|
|
13
|
-
"x-topics": "
|
|
13
|
+
"x-topics": "tm_messagebox", // comma-separated topic identifiers
|
|
14
14
|
"x-includes-off-chain-values": "false" // string "true" or "false"
|
|
15
15
|
}
|
|
16
16
|
\\\`\\\`\\\`
|