@bsv/overlay-express 2.1.0 → 2.2.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/mod.ts CHANGED
@@ -1,4 +1,13 @@
1
- export { default } from './src/OverlayExpress.js'
1
+ export {
2
+ default,
3
+ type EngineConfig,
4
+ type HealthCheckDefinition,
5
+ type HealthCheckHandler,
6
+ type HealthCheckResult,
7
+ type HealthConfig,
8
+ type HealthReport,
9
+ type HealthStatus
10
+ } from './src/OverlayExpress.js'
2
11
  export { BanService, type BannedRecord } from './src/BanService.js'
3
12
  export { BanAwareLookupWrapper } from './src/BanAwareLookupWrapper.js'
4
13
  export { JanitorService, type JanitorConfig, type JanitorReport, type HostHealthResult } from './src/JanitorService.js'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bsv/overlay-express",
3
- "version": "2.1.0",
3
+ "version": "2.2.0",
4
4
  "type": "module",
5
5
  "description": "BSV Blockchain Overlay Express",
6
6
  "main": "dist/cjs/mod.js",
@@ -161,7 +161,7 @@ export class JanitorService {
161
161
  }
162
162
 
163
163
  const data = await response.json()
164
- const healthy = data?.status === 'ok'
164
+ const healthy = (data?.status === 'ok' && data?.ready !== false) || (data?.ready === true && data?.live !== false)
165
165
  return { healthy, responseTimeMs, statusCode: response.status, error: healthy ? undefined : 'Unexpected response' }
166
166
  } catch (error: any) {
167
167
  clearTimeout(timeout)
@@ -94,6 +94,51 @@ export interface EngineConfig {
94
94
  suppressDefaultSyncAdvertisements?: boolean
95
95
  }
96
96
 
97
+ export type HealthStatus = 'ok' | 'degraded' | 'error'
98
+
99
+ export interface HealthCheckResult {
100
+ name: string
101
+ scope: 'live' | 'ready'
102
+ status: HealthStatus
103
+ critical: boolean
104
+ message?: string
105
+ details?: Record<string, any>
106
+ durationMs: number
107
+ }
108
+
109
+ export type HealthCheckHandler = () => Promise<Omit<HealthCheckResult, 'name' | 'scope' | 'critical' | 'durationMs'> | void> | Omit<HealthCheckResult, 'name' | 'scope' | 'critical' | 'durationMs'> | void
110
+
111
+ export interface HealthCheckDefinition {
112
+ name: string
113
+ scope?: 'live' | 'ready'
114
+ critical?: boolean
115
+ handler: HealthCheckHandler
116
+ }
117
+
118
+ export interface HealthConfig {
119
+ includeDetails: boolean
120
+ timeoutMs: number
121
+ contextProvider?: () => Promise<Record<string, any> | undefined> | Record<string, any> | undefined
122
+ }
123
+
124
+ export interface HealthReport {
125
+ status: HealthStatus
126
+ live: boolean
127
+ ready: boolean
128
+ service: {
129
+ name: string
130
+ advertisableFQDN: string
131
+ port: number
132
+ network: 'main' | 'test'
133
+ startedAt?: string
134
+ uptimeMs: number
135
+ topicManagerCount: number
136
+ lookupServiceCount: number
137
+ }
138
+ checks: HealthCheckResult[]
139
+ context?: Record<string, any>
140
+ }
141
+
97
142
  /**
98
143
  * OverlayExpress class provides an Express-based server for hosting Overlay Services.
99
144
  * It allows configuration of various components like databases, topic managers, and lookup services.
@@ -118,6 +163,9 @@ export default class OverlayExpress {
118
163
  // MongoDB database
119
164
  mongoDb?: Db
120
165
 
166
+ // MongoDB client retained for health checks
167
+ mongoClient?: MongoClient
168
+
121
169
  // Network ('main' or 'test')
122
170
  network: 'main' | 'test' = 'main'
123
171
 
@@ -178,6 +226,18 @@ export default class OverlayExpress {
178
226
  // Server start time for uptime tracking
179
227
  private startTime?: Date
180
228
 
229
+ // Health endpoint configuration
230
+ healthConfig: HealthConfig = {
231
+ includeDetails: true,
232
+ timeoutMs: 5000
233
+ }
234
+
235
+ // Extra application-specific health checks
236
+ healthChecks: HealthCheckDefinition[] = []
237
+
238
+ // Lifecycle marker for readiness/liveness reporting
239
+ isListening: boolean = false
240
+
181
241
  /**
182
242
  * Constructs an instance of OverlayExpress.
183
243
  * @param name - The name of the service
@@ -237,6 +297,30 @@ export default class OverlayExpress {
237
297
  this.logger.log(chalk.blue('Janitor service has been configured.'))
238
298
  }
239
299
 
300
+ /**
301
+ * Configures health-report behavior.
302
+ */
303
+ configureHealth (config: Partial<HealthConfig>): void {
304
+ this.healthConfig = {
305
+ ...this.healthConfig,
306
+ ...config
307
+ }
308
+ this.logger.log(chalk.blue('Health reporting has been configured.'))
309
+ }
310
+
311
+ /**
312
+ * Registers an application-specific health check.
313
+ */
314
+ registerHealthCheck (definition: HealthCheckDefinition): void {
315
+ this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name)
316
+ this.healthChecks.push({
317
+ scope: 'ready',
318
+ critical: false,
319
+ ...definition
320
+ })
321
+ this.logger.log(chalk.blue(`Registered health check ${definition.name}`))
322
+ }
323
+
240
324
  /**
241
325
  * Configures the admin identity key for wallet-based admin detection.
242
326
  * When set, the frontend can compare the user's wallet identity key against this
@@ -330,6 +414,7 @@ export default class OverlayExpress {
330
414
  async configureMongo (connectionString: string): Promise<void> {
331
415
  const mongoClient = new MongoClient(connectionString)
332
416
  await mongoClient.connect()
417
+ this.mongoClient = mongoClient
333
418
  const db = mongoClient.db(`${this.name}_lookup_services`)
334
419
  this.mongoDb = db
335
420
 
@@ -616,6 +701,170 @@ export default class OverlayExpress {
616
701
  })
617
702
  }
618
703
 
704
+ private async runHealthCheck (
705
+ definition: Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }
706
+ ): Promise<HealthCheckResult> {
707
+ const startedAt = Date.now()
708
+
709
+ try {
710
+ const result = ((await Promise.race([
711
+ Promise.resolve(definition.handler()),
712
+ new Promise<never>((_, reject) => {
713
+ setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs)
714
+ })
715
+ ])) ?? {}) as {
716
+ status?: HealthStatus
717
+ message?: string
718
+ details?: Record<string, any>
719
+ }
720
+
721
+ return {
722
+ name: definition.name,
723
+ scope: definition.scope,
724
+ critical: definition.critical,
725
+ status: result.status ?? 'ok',
726
+ message: result.message,
727
+ details: result.details,
728
+ durationMs: Date.now() - startedAt
729
+ }
730
+ } catch (error) {
731
+ return {
732
+ name: definition.name,
733
+ scope: definition.scope,
734
+ critical: definition.critical,
735
+ status: 'error',
736
+ message: error instanceof Error ? error.message : 'Unknown health-check error',
737
+ durationMs: Date.now() - startedAt
738
+ }
739
+ }
740
+ }
741
+
742
+ private async collectHealthReport (mode: 'live' | 'ready' | 'full'): Promise<HealthReport> {
743
+ const definitions: Array<Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }> = [
744
+ {
745
+ name: 'process',
746
+ scope: 'live',
747
+ critical: true,
748
+ handler: async () => ({
749
+ status: 'ok',
750
+ details: {
751
+ listening: this.isListening
752
+ }
753
+ })
754
+ },
755
+ {
756
+ name: 'engine',
757
+ scope: 'ready',
758
+ critical: true,
759
+ handler: async () => {
760
+ if (typeof this.engine === 'undefined') {
761
+ throw new Error('Overlay engine is not configured')
762
+ }
763
+
764
+ return {
765
+ status: 'ok',
766
+ details: {
767
+ topicManagers: Object.keys(this.managers),
768
+ lookupServices: Object.keys(this.services)
769
+ }
770
+ }
771
+ }
772
+ },
773
+ {
774
+ name: 'knex',
775
+ scope: 'ready',
776
+ critical: true,
777
+ handler: async () => {
778
+ if (typeof this.knex === 'undefined') {
779
+ throw new Error('Knex is not configured')
780
+ }
781
+
782
+ await this.knex.raw('select 1 as ok')
783
+ return {
784
+ status: 'ok',
785
+ details: {
786
+ client: this.knex.client?.config?.client ?? 'unknown'
787
+ }
788
+ }
789
+ }
790
+ },
791
+ {
792
+ name: 'mongo',
793
+ scope: 'ready',
794
+ critical: true,
795
+ handler: async () => {
796
+ if (typeof this.mongoDb === 'undefined') {
797
+ throw new Error('MongoDB is not configured')
798
+ }
799
+
800
+ await this.mongoDb.command({ ping: 1 })
801
+ return {
802
+ status: 'ok',
803
+ details: {
804
+ database: this.mongoDb.databaseName
805
+ }
806
+ }
807
+ }
808
+ }
809
+ ]
810
+
811
+ for (const check of this.healthChecks) {
812
+ definitions.push({
813
+ name: check.name,
814
+ scope: check.scope ?? 'ready',
815
+ critical: check.critical ?? false,
816
+ handler: check.handler
817
+ })
818
+ }
819
+
820
+ const filteredDefinitions = definitions.filter((definition) => {
821
+ if (mode === 'full') {
822
+ return true
823
+ }
824
+
825
+ return definition.scope === mode
826
+ })
827
+
828
+ const checks = await Promise.all(filteredDefinitions.map(async definition => await this.runHealthCheck(definition)))
829
+ const liveChecks = checks.filter(check => check.scope === 'live')
830
+ const readyChecks = checks.filter(check => check.scope === 'ready')
831
+ const live = liveChecks.every(check => !check.critical || check.status === 'ok')
832
+ const ready = readyChecks.every(check => !check.critical || check.status === 'ok')
833
+
834
+ let status: HealthStatus = 'ok'
835
+ if (!live || !ready || checks.some(check => check.critical && check.status === 'error')) {
836
+ status = 'error'
837
+ } else if (checks.some(check => check.status !== 'ok')) {
838
+ status = 'degraded'
839
+ }
840
+
841
+ const context = typeof this.healthConfig.contextProvider === 'function'
842
+ ? await this.healthConfig.contextProvider()
843
+ : undefined
844
+
845
+ const report: HealthReport = {
846
+ status,
847
+ live,
848
+ ready,
849
+ service: {
850
+ name: this.name,
851
+ advertisableFQDN: this.advertisableFQDN,
852
+ port: this.port,
853
+ network: this.network,
854
+ startedAt: this.startTime?.toISOString(),
855
+ uptimeMs: typeof this.startTime === 'undefined' ? 0 : Date.now() - this.startTime.getTime(),
856
+ topicManagerCount: Object.keys(this.managers).length,
857
+ lookupServiceCount: Object.keys(this.services).length
858
+ },
859
+ checks: this.healthConfig.includeDetails
860
+ ? checks
861
+ : checks.map(({ details, ...check }) => check),
862
+ context
863
+ }
864
+
865
+ return report
866
+ }
867
+
619
868
  /**
620
869
  * Starts the Express server.
621
870
  * Sets up routes and begins listening on the configured port.
@@ -726,9 +975,41 @@ export default class OverlayExpress {
726
975
  }))
727
976
  })
728
977
 
729
- // Serve a health check endpoint
978
+ // Serve health check endpoints
979
+ this.app.get('/health/live', (_, res) => {
980
+ ; (async () => {
981
+ const report = await this.collectHealthReport('live')
982
+ return res.status(report.live ? 200 : 503).json(report)
983
+ })().catch((error) => {
984
+ res.status(500).json({
985
+ status: 'error',
986
+ message: error instanceof Error ? error.message : 'Unexpected error'
987
+ })
988
+ })
989
+ })
990
+
991
+ this.app.get('/health/ready', (_, res) => {
992
+ ; (async () => {
993
+ const report = await this.collectHealthReport('ready')
994
+ return res.status(report.ready ? 200 : 503).json(report)
995
+ })().catch((error) => {
996
+ res.status(500).json({
997
+ status: 'error',
998
+ message: error instanceof Error ? error.message : 'Unexpected error'
999
+ })
1000
+ })
1001
+ })
1002
+
730
1003
  this.app.get('/health', (_, res) => {
731
- res.status(200).json({ status: 'ok' })
1004
+ ; (async () => {
1005
+ const report = await this.collectHealthReport('full')
1006
+ return res.status(report.ready ? 200 : 503).json(report)
1007
+ })().catch((error) => {
1008
+ res.status(500).json({
1009
+ status: 'error',
1010
+ message: error instanceof Error ? error.message : 'Unexpected error'
1011
+ })
1012
+ })
732
1013
  })
733
1014
 
734
1015
  // List hosted topic managers and lookup services
@@ -1587,6 +1868,7 @@ export default class OverlayExpress {
1587
1868
 
1588
1869
  // Start listening on the configured port
1589
1870
  this.app.listen(this.port, () => {
1871
+ this.isListening = true
1590
1872
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`))
1591
1873
  })
1592
1874
  }
@@ -22,7 +22,11 @@ function createMockDbValue (): Record<string, any> {
22
22
  deleteOne: jest.fn<any>().mockResolvedValue({}),
23
23
  countDocuments: jest.fn<any>().mockResolvedValue(0)
24
24
  }
25
- return { collection: jest.fn<any>().mockReturnValue(mockCollection) }
25
+ return {
26
+ collection: jest.fn<any>().mockReturnValue(mockCollection),
27
+ command: jest.fn<any>().mockResolvedValue({ ok: 1 }),
28
+ databaseName: 'TestService_lookup_services'
29
+ }
26
30
  }
27
31
 
28
32
  describe('OverlayExpress', () => {
@@ -753,7 +757,21 @@ describe('OverlayExpress', () => {
753
757
  expect(corsMiddleware).toBeDefined()
754
758
  })
755
759
 
756
- it('should register health check route', async () => {
760
+ it('should register health check routes', async () => {
761
+ const getSpy = jest.spyOn(instance.app, 'get')
762
+ jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
763
+ callback()
764
+ return {} as any
765
+ })
766
+
767
+ await instance.start()
768
+
769
+ expect(getSpy.mock.calls.find(call => call[0] === '/health')).toBeDefined()
770
+ expect(getSpy.mock.calls.find(call => call[0] === '/health/live')).toBeDefined()
771
+ expect(getSpy.mock.calls.find(call => call[0] === '/health/ready')).toBeDefined()
772
+ })
773
+
774
+ it('should return detailed readiness health', async () => {
757
775
  const getSpy = jest.spyOn(instance.app, 'get')
758
776
  jest.spyOn(instance.app, 'listen').mockImplementation((port: any, callback: any) => {
759
777
  callback()
@@ -762,8 +780,28 @@ describe('OverlayExpress', () => {
762
780
 
763
781
  await instance.start()
764
782
 
765
- const healthRoute = getSpy.mock.calls.find(call => call[0] === '/health')
766
- expect(healthRoute).toBeDefined()
783
+ const readyRoute = getSpy.mock.calls.find(call => call[0] === '/health/ready')
784
+ const res = {
785
+ status: jest.fn().mockReturnThis(),
786
+ json: jest.fn()
787
+ }
788
+
789
+ readyRoute?.[1]({} as any, res as any)
790
+ await new Promise(resolve => setImmediate(resolve))
791
+
792
+ expect(res.status).toHaveBeenCalledWith(200)
793
+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
794
+ status: 'ok',
795
+ ready: true,
796
+ service: expect.objectContaining({
797
+ name: 'TestServer'
798
+ }),
799
+ checks: expect.arrayContaining([
800
+ expect.objectContaining({ name: 'engine', status: 'ok' }),
801
+ expect.objectContaining({ name: 'knex', status: 'ok' }),
802
+ expect.objectContaining({ name: 'mongo', status: 'ok' })
803
+ ])
804
+ }))
767
805
  })
768
806
 
769
807
  it('should register admin routes', async () => {
@@ -0,0 +1,16 @@
1
+ declare module '@bsv/auth-express-middleware' {
2
+ import type { RequestHandler } from 'express'
3
+
4
+ export interface AuthRequest {
5
+ auth?: {
6
+ identityKey?: string
7
+ certificates?: Array<{
8
+ certifier?: string
9
+ type?: string
10
+ decryptedFields?: Record<string, any>
11
+ }>
12
+ }
13
+ }
14
+
15
+ export function createAuthMiddleware (config: Record<string, any>): RequestHandler
16
+ }