@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsv/overlay-express",
3
- "version": "2.4.1",
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.5",
49
- "@types/express": "^5.0.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.0.0",
51
+ "@types/node": "^26.1.1",
52
52
  "jest": "^30.4.2",
53
- "ts-jest": "^29.4.11",
54
- "ts-standard": "^12.0.2",
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
- "@bsv/sdk": "^2.1.3"
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.2.10",
69
- "mongodb": "^7.3.0",
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": "ts-standard --fix src/**/*.ts",
85
- "lint:ci": "ts-standard src/**/*.ts",
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",
@@ -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
- this.configureLookupServiceWithMongo('ls_ship', (db) => {
728
- const storage = new DiscoveryServices.SHIPStorage(db)
729
- const storageForLookup = this.banService === undefined
730
- ? storage
731
- : new BanAwareSHIPStorage(storage, this.banService, this.logger)
732
- return new DiscoveryServices.SHIPLookupService(storageForLookup as any)
733
- })
734
- this.configureLookupServiceWithMongo('ls_slap', (db) => {
735
- const storage = new DiscoveryServices.SLAPStorage(db)
736
- const storageForLookup = this.banService === undefined
737
- ? storage
738
- : new BanAwareSLAPStorage(storage, this.banService, this.logger)
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 = JSON.parse(topicsHeader)
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(req.body as number[])
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 { url } = req.body
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!.advertiser = mockAdvertiser
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
- await expect(chaintracks.isValidRootForHeight(header!.merkleRoot, height)).resolves.toBe(true)
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
- await expect(chaintracks.isValidRootForHeight(proof!.merkleRoot, proof!.blockHeight!)).resolves.toBe(true)
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
  })
@@ -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": "["tm_messagebox"]", // array of topic identifiers as stringified JSON
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
  \\\`\\\`\\\`