@bsv/overlay-express 2.1.1 → 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/README.md +30 -0
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +1 -1
- package/dist/cjs/src/JanitorService.js +1 -1
- package/dist/cjs/src/JanitorService.js.map +1 -1
- package/dist/cjs/src/OverlayExpress.js +216 -2
- package/dist/cjs/src/OverlayExpress.js.map +1 -1
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/JanitorService.js +1 -1
- package/dist/esm/src/JanitorService.js.map +1 -1
- package/dist/esm/src/OverlayExpress.js +215 -2
- package/dist/esm/src/OverlayExpress.js.map +1 -1
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +1 -1
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/OverlayExpress.d.ts +54 -1
- package/dist/types/src/OverlayExpress.d.ts.map +1 -1
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/mod.ts +10 -1
- package/package.json +1 -1
- package/src/JanitorService.ts +1 -1
- package/src/OverlayExpress.ts +284 -2
- package/src/__tests__/OverlayExpress.test.ts +42 -4
- package/src/auth-express-middleware.d.ts +16 -0
package/mod.ts
CHANGED
|
@@ -1,4 +1,13 @@
|
|
|
1
|
-
export {
|
|
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
package/src/JanitorService.ts
CHANGED
|
@@ -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)
|
package/src/OverlayExpress.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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 {
|
|
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
|
|
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
|
|
766
|
-
|
|
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
|
+
}
|