@bsv/overlay-express 2.1.1 → 2.2.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.
@@ -25,7 +25,7 @@ import { MongoClient, Db } from 'mongodb'
25
25
  import makeUserInterface, { type UIConfig } from './makeUserInterface.js'
26
26
  import * as DiscoveryServices from '@bsv/overlay-discovery-services'
27
27
  import chalk from 'chalk'
28
- import util from 'util'
28
+ import util from 'node:util'
29
29
  import { v4 as uuidv4 } from 'uuid'
30
30
  import { JanitorService, type JanitorReport } from './JanitorService.js'
31
31
  import { BanService } from './BanService.js'
@@ -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
@@ -309,7 +393,7 @@ export default class OverlayExpress {
309
393
 
310
394
  /**
311
395
  * Configure Knex (SQL) database connection.
312
- * @param config - Knex configuration object, or MySQL connection string (e.g. mysql://overlayAdmin:overlay123@mysql:3306/overlay).
396
+ * @param config - Knex configuration object, or a MySQL connection string loaded from configuration.
313
397
  */
314
398
  async configureKnex (config: Knex.Knex.Config | string): Promise<void> {
315
399
  if (typeof config === 'string') {
@@ -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
 
@@ -424,7 +509,6 @@ export default class OverlayExpress {
424
509
  const knex = this.ensureKnex()
425
510
 
426
511
  if (autoConfigureShipSlap) {
427
- // Auto-configure SHIP and SLAP services
428
512
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager())
429
513
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager())
430
514
  this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(
@@ -435,137 +519,109 @@ export default class OverlayExpress {
435
519
  ))
436
520
  }
437
521
 
438
- // Wrap SHIP/SLAP lookup services with ban-aware wrappers if BanService is available.
439
- // This prevents GASP from re-syncing tokens whose domains or outpoints have been banned.
440
- if (this.banService !== undefined) {
441
- if (this.services.ls_ship !== undefined) {
442
- this.services.ls_ship = new BanAwareLookupWrapper(
443
- this.services.ls_ship,
444
- this.banService,
445
- 'SHIP',
446
- this.logger
447
- )
448
- this.logger.log(chalk.blue('SHIP lookup service wrapped with ban-aware filter.'))
449
- }
450
- if (this.services.ls_slap !== undefined) {
451
- this.services.ls_slap = new BanAwareLookupWrapper(
452
- this.services.ls_slap,
453
- this.banService,
454
- 'SLAP',
455
- this.logger
456
- )
457
- this.logger.log(chalk.blue('SLAP lookup service wrapped with ban-aware filter.'))
458
- }
459
- }
460
-
461
- // Construct a default sync configuration, in case the user doesn't want GASP at all:
462
- let syncConfig: Record<string, string[] | 'SHIP' | false> = {}
463
- if (!this.enableGASPSync) {
464
- // For each manager, disable sync
465
- for (const managerName of Object.keys(this.managers)) {
466
- syncConfig[managerName] = false
467
- }
468
- } else {
469
- // If the user provided a syncConfiguration, use that. Otherwise default to an empty object.
470
- syncConfig = this.engineConfig.syncConfiguration ?? {}
471
- }
522
+ this.wrapBanAwareServices()
472
523
 
473
- // Build the actual Storage
524
+ const syncConfig = this.buildSyncConfig()
474
525
  const storage = new KnexStorage(knex)
475
- // Include the KnexStorage migrations
476
526
  this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun]
477
527
 
478
- // Prepare broadcaster if arcApiKey is set
479
- let broadcaster: Broadcaster | undefined
480
- if (typeof this.arcApiKey === 'string') {
481
- broadcaster = new ARC(
482
- // We hard-code some ARC URLs for now, but we should make this configurable later.
483
- this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com',
484
- {
485
- apiKey: this.arcApiKey
486
- })
487
- }
488
-
489
- // Prepare advertiser if not set by the user
490
- let advertiser: Advertiser | undefined = this.engineConfig.advertiser
491
- if (typeof advertiser === 'undefined') {
492
- try {
493
- advertiser = new DiscoveryServices.WalletAdvertiser(
494
- this.network,
495
- this.privateKey,
496
- this.network === 'test' // For now, we hard-code some storage servers. In the future, this needs to be configurable.
497
- ? 'https://staging-storage.babbage.systems'
498
- : 'https://storage.babbage.systems',
499
- // Until multiple protocols (like https+bsvauth+smf) are fully supported, HTTPS is the one to always use.
500
- `https://${this.advertisableFQDN}`
501
- )
502
- } catch (e) {
503
- this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled.`)
504
- }
505
- }
528
+ const broadcaster = this.buildBroadcaster()
529
+ const advertiser = await this.buildAdvertiser()
506
530
 
507
- // Construct the Engine with any advanced config overrides. Fallback to defaults.
508
531
  this.engine = new Engine(
509
532
  this.managers,
510
533
  this.services,
511
534
  storage,
512
- // chainTracker
513
- typeof this.engineConfig.chainTracker !== 'undefined'
514
- ? this.engineConfig.chainTracker
515
- : this.chainTracker,
516
- // hostingURL
535
+ this.engineConfig.chainTracker ?? this.chainTracker,
517
536
  `https://${this.advertisableFQDN}`,
518
- // shipTrackers
519
537
  this.network === 'test'
520
538
  ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
521
539
  : this.engineConfig.shipTrackers,
522
- // slapTrackers
523
- Array.isArray(this.engineConfig.slapTrackers)
524
- ? this.engineConfig.slapTrackers
525
- : this.network === 'test'
526
- ? DEFAULT_TESTNET_SLAP_TRACKERS
527
- : DEFAULT_SLAP_TRACKERS,
528
- // broadcaster
540
+ this.resolveSlapTrackers(),
529
541
  broadcaster ?? this.engineConfig.broadcaster,
530
- // advertiser
531
542
  advertiser,
532
- // syncConfiguration
533
543
  syncConfig,
534
- // logTime
535
544
  this.engineConfig.logTime ?? false,
536
- // logPrefix
537
545
  this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
538
- // throwOnBroadcastFailure
539
546
  this.engineConfig.throwOnBroadcastFailure ?? false,
540
- // overlayBroadcastFacilitator
541
547
  this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
542
- // logger
543
548
  this.logger,
544
- // suppressDefaultSyncAdvertisements
545
549
  this.engineConfig.suppressDefaultSyncAdvertisements ?? true
546
550
  )
547
551
 
548
- // Create the server wallet for BSV mutual authentication.
549
- // This uses the same private key as the WalletAdvertiser.
552
+ this.initServerWallet()
553
+ this.logger.log(chalk.green('Engine has been configured.'))
554
+ }
555
+
556
+ /** Wrap SHIP/SLAP with ban-aware filter if BanService is configured. */
557
+ private wrapBanAwareServices (): void {
558
+ if (this.banService === undefined) return
559
+ for (const key of ['ls_ship', 'ls_slap'] as const) {
560
+ if (this.services[key] !== undefined) {
561
+ const label = key === 'ls_ship' ? 'SHIP' : 'SLAP'
562
+ this.services[key] = new BanAwareLookupWrapper(this.services[key], this.banService, label, this.logger)
563
+ this.logger.log(chalk.blue(`${label} lookup service wrapped with ban-aware filter.`))
564
+ }
565
+ }
566
+ }
567
+
568
+ /** Build the sync config based on enableGASPSync and engineConfig. */
569
+ private buildSyncConfig (): Record<string, string[] | 'SHIP' | false> {
570
+ if (this.enableGASPSync) {
571
+ return this.engineConfig.syncConfiguration ?? {}
572
+ }
573
+ const syncConfig: Record<string, string[] | 'SHIP' | false> = {}
574
+ for (const name of Object.keys(this.managers)) {
575
+ syncConfig[name] = false
576
+ }
577
+ return syncConfig
578
+ }
579
+
580
+ /** Build the ARC broadcaster if an API key is configured. */
581
+ private buildBroadcaster (): Broadcaster | undefined {
582
+ if (typeof this.arcApiKey !== 'string') return undefined
583
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com'
584
+ return new ARC(arcUrl, { apiKey: this.arcApiKey })
585
+ }
586
+
587
+ /** Resolve the SLAP trackers from config or network defaults. */
588
+ private resolveSlapTrackers (): string[] | undefined {
589
+ if (Array.isArray(this.engineConfig.slapTrackers)) return this.engineConfig.slapTrackers
590
+ return this.network === 'test' ? DEFAULT_TESTNET_SLAP_TRACKERS : DEFAULT_SLAP_TRACKERS
591
+ }
592
+
593
+ /** Build the WalletAdvertiser (or use user-provided one). */
594
+ private async buildAdvertiser (): Promise<Advertiser | undefined> {
595
+ if (this.engineConfig.advertiser !== undefined) return this.engineConfig.advertiser
596
+ const storageBase = this.network === 'test'
597
+ ? 'https://staging-storage.babbage.systems'
598
+ : 'https://storage.babbage.systems'
599
+ try {
600
+ return new DiscoveryServices.WalletAdvertiser(
601
+ this.network,
602
+ this.privateKey,
603
+ storageBase,
604
+ `https://${this.advertisableFQDN}`
605
+ )
606
+ } catch (e) {
607
+ this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`)
608
+ return undefined
609
+ }
610
+ }
611
+
612
+ /** Initialize the server wallet for BSV mutual authentication. */
613
+ private initServerWallet (): void {
550
614
  try {
551
615
  const keyDeriver = new KeyDeriver(new PrivateKey(this.privateKey, 'hex'))
552
616
  const storageManager = new WalletStorageManager(keyDeriver.identityKey)
553
617
  const signer = new WalletSigner(this.network, keyDeriver, storageManager)
554
618
  const services = new Services(this.network)
555
- const wallet = new Wallet(signer, services)
556
- this.serverWallet = wallet
557
-
558
- // Auto-set the admin identity key from the server's own key if not configured
559
- if (typeof this.adminIdentityKey === 'undefined') {
560
- this.adminIdentityKey = keyDeriver.identityKey
561
- }
562
-
619
+ this.serverWallet = new Wallet(signer, services)
620
+ this.adminIdentityKey ??= keyDeriver.identityKey
563
621
  this.logger.log(chalk.blue('Server wallet initialized for BSV mutual authentication.'))
564
622
  } catch (e) {
565
- this.logger.log(chalk.yellow('Server wallet could not be initialized. BSV auth will not be available.'))
623
+ this.logger.log(chalk.yellow(`Server wallet could not be initialized. BSV auth will not be available. Reason: ${e}`))
566
624
  }
567
-
568
- this.logger.log(chalk.green('Engine has been configured.'))
569
625
  }
570
626
 
571
627
  /**
@@ -573,8 +629,8 @@ export default class OverlayExpress {
573
629
  * @throws Error if Knex is not configured
574
630
  */
575
631
  private ensureKnex (): Knex.Knex {
576
- if (typeof this.knex === 'undefined') {
577
- throw new Error('You must configure your SQL database with the .configureKnex() method first!')
632
+ if (this.knex === undefined) {
633
+ throw new TypeError('You must configure your SQL database with the .configureKnex() method first!')
578
634
  }
579
635
  return this.knex
580
636
  }
@@ -584,8 +640,8 @@ export default class OverlayExpress {
584
640
  * @throws Error if MongoDB is not configured
585
641
  */
586
642
  private ensureMongo (): Db {
587
- if (typeof this.mongoDb === 'undefined') {
588
- throw new Error('You must configure your MongoDB connection with the .configureMongo() method first!')
643
+ if (this.mongoDb === undefined) {
644
+ throw new TypeError('You must configure your MongoDB connection with the .configureMongo() method first!')
589
645
  }
590
646
  return this.mongoDb
591
647
  }
@@ -595,8 +651,8 @@ export default class OverlayExpress {
595
651
  * @throws Error if the Engine is not configured
596
652
  */
597
653
  private ensureEngine (): Engine {
598
- if (typeof this.engine === 'undefined') {
599
- throw new Error('You must configure your Overlay Services engine with the .configureEngine() method first!')
654
+ if (this.engine === undefined) {
655
+ throw new TypeError('You must configure your Overlay Services engine with the .configureEngine() method first!')
600
656
  }
601
657
  return this.engine
602
658
  }
@@ -616,6 +672,235 @@ export default class OverlayExpress {
616
672
  })
617
673
  }
618
674
 
675
+ /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
676
+ private async handleBanDomain (res: express.Response, value: string, reason?: string): Promise<express.Response> {
677
+ await this.banService!.banDomain(value, reason)
678
+ const db = this.ensureMongo()
679
+ const [shipDeleted, slapDeleted] = await Promise.all([
680
+ db.collection('shipRecords').deleteMany({ domain: value }),
681
+ db.collection('slapRecords').deleteMany({ domain: value })
682
+ ])
683
+ return res.status(200).json({
684
+ status: 'success',
685
+ message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
686
+ })
687
+ }
688
+
689
+ /** Parse outpoint string, ban it, and evict it from all lookup services. */
690
+ private async handleBanOutpoint (res: express.Response, engine: Engine, value: string, reason?: string): Promise<express.Response> {
691
+ const dotIndex = value.lastIndexOf('.')
692
+ if (dotIndex === -1) {
693
+ return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' })
694
+ }
695
+ const txid = value.substring(0, dotIndex)
696
+ const outputIndex = Number.parseInt(value.substring(dotIndex + 1))
697
+ if (Number.isNaN(outputIndex)) {
698
+ return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' })
699
+ }
700
+ await this.banService!.banOutpoint(txid, outputIndex, reason)
701
+ await this.evictFromServices(engine, txid, outputIndex)
702
+ return res.status(200).json({
703
+ status: 'success',
704
+ message: `Outpoint "${value}" banned and evicted from lookup services.`
705
+ })
706
+ }
707
+
708
+ /** Evict an output from a specific service or all services (silent per-service errors). */
709
+ private async evictFromServices (engine: Engine, txid: string, outputIndex: number, service?: string): Promise<void> {
710
+ if (typeof service === 'string') {
711
+ const svc = engine.lookupServices[service]
712
+ if (svc !== undefined) await svc.outputEvicted(txid, outputIndex)
713
+ return
714
+ }
715
+ for (const svc of Object.values(engine.lookupServices)) {
716
+ try { await svc.outputEvicted(txid, outputIndex) } catch { /* best-effort */ }
717
+ }
718
+ }
719
+
720
+ /** Look up the domain of an outpoint from SHIP or SLAP records. */
721
+ private async lookupDomainForOutpoint (txid: string, outputIndex: number): Promise<string | undefined> {
722
+ const db = this.ensureMongo()
723
+ const [shipRecord, slapRecord] = await Promise.all([
724
+ db.collection('shipRecords').findOne({ txid, outputIndex }),
725
+ db.collection('slapRecords').findOne({ txid, outputIndex })
726
+ ])
727
+ return (shipRecord?.domain ?? slapRecord?.domain) as string | undefined
728
+ }
729
+
730
+ /** Ban a domain and delete all SHIP/SLAP records for it. */
731
+ private async banDomainAndRemoveRecords (domain: string, reason: string): Promise<void> {
732
+ await this.banService!.banDomain(domain, reason)
733
+ const db = this.ensureMongo()
734
+ await Promise.all([
735
+ db.collection('shipRecords').deleteMany({ domain }),
736
+ db.collection('slapRecords').deleteMany({ domain })
737
+ ])
738
+ }
739
+
740
+ private async runHealthCheck (
741
+ definition: Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }
742
+ ): Promise<HealthCheckResult> {
743
+ const startedAt = Date.now()
744
+
745
+ try {
746
+ const result = ((await Promise.race([
747
+ Promise.resolve(definition.handler()),
748
+ new Promise<never>((_, reject) => {
749
+ setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs)
750
+ })
751
+ ])) ?? {}) as {
752
+ status?: HealthStatus
753
+ message?: string
754
+ details?: Record<string, any>
755
+ }
756
+
757
+ return {
758
+ name: definition.name,
759
+ scope: definition.scope,
760
+ critical: definition.critical,
761
+ status: result.status ?? 'ok',
762
+ message: result.message,
763
+ details: result.details,
764
+ durationMs: Date.now() - startedAt
765
+ }
766
+ } catch (error) {
767
+ return {
768
+ name: definition.name,
769
+ scope: definition.scope,
770
+ critical: definition.critical,
771
+ status: 'error',
772
+ message: error instanceof Error ? error.message : 'Unknown health-check error',
773
+ durationMs: Date.now() - startedAt
774
+ }
775
+ }
776
+ }
777
+
778
+ private async collectHealthReport (mode: 'live' | 'ready' | 'full'): Promise<HealthReport> {
779
+ const definitions: Array<Required<Pick<HealthCheckDefinition, 'name' | 'scope' | 'critical'>> & { handler: HealthCheckHandler }> = [
780
+ {
781
+ name: 'process',
782
+ scope: 'live',
783
+ critical: true,
784
+ handler: async () => ({
785
+ status: 'ok',
786
+ details: {
787
+ listening: this.isListening
788
+ }
789
+ })
790
+ },
791
+ {
792
+ name: 'engine',
793
+ scope: 'ready',
794
+ critical: true,
795
+ handler: async () => {
796
+ if (this.engine === undefined) {
797
+ throw new TypeError('Overlay engine is not configured')
798
+ }
799
+
800
+ return {
801
+ status: 'ok',
802
+ details: {
803
+ topicManagers: Object.keys(this.managers),
804
+ lookupServices: Object.keys(this.services)
805
+ }
806
+ }
807
+ }
808
+ },
809
+ {
810
+ name: 'knex',
811
+ scope: 'ready',
812
+ critical: true,
813
+ handler: async () => {
814
+ if (this.knex === undefined) {
815
+ throw new TypeError('Knex is not configured')
816
+ }
817
+
818
+ await this.knex.raw('select 1 as ok')
819
+ return {
820
+ status: 'ok',
821
+ details: {
822
+ client: this.knex.client?.config?.client ?? 'unknown'
823
+ }
824
+ }
825
+ }
826
+ },
827
+ {
828
+ name: 'mongo',
829
+ scope: 'ready',
830
+ critical: true,
831
+ handler: async () => {
832
+ if (this.mongoDb === undefined) {
833
+ throw new TypeError('MongoDB is not configured')
834
+ }
835
+
836
+ await this.mongoDb.command({ ping: 1 })
837
+ return {
838
+ status: 'ok',
839
+ details: {
840
+ database: this.mongoDb.databaseName
841
+ }
842
+ }
843
+ }
844
+ }
845
+ ]
846
+
847
+ for (const check of this.healthChecks) {
848
+ definitions.push({
849
+ name: check.name,
850
+ scope: check.scope ?? 'ready',
851
+ critical: check.critical ?? false,
852
+ handler: check.handler
853
+ })
854
+ }
855
+
856
+ const filteredDefinitions = definitions.filter((definition) => {
857
+ if (mode === 'full') {
858
+ return true
859
+ }
860
+
861
+ return definition.scope === mode
862
+ })
863
+
864
+ const checks = await Promise.all(filteredDefinitions.map(async definition => await this.runHealthCheck(definition)))
865
+ const liveChecks = checks.filter(check => check.scope === 'live')
866
+ const readyChecks = checks.filter(check => check.scope === 'ready')
867
+ const live = liveChecks.every(check => !check.critical || check.status === 'ok')
868
+ const ready = readyChecks.every(check => !check.critical || check.status === 'ok')
869
+
870
+ let status: HealthStatus = 'ok'
871
+ if (!live || !ready || checks.some(check => check.critical && check.status === 'error')) {
872
+ status = 'error'
873
+ } else if (checks.some(check => check.status !== 'ok')) {
874
+ status = 'degraded'
875
+ }
876
+
877
+ const context = typeof this.healthConfig.contextProvider === 'function'
878
+ ? await this.healthConfig.contextProvider()
879
+ : undefined
880
+
881
+ const report: HealthReport = {
882
+ status,
883
+ live,
884
+ ready,
885
+ service: {
886
+ name: this.name,
887
+ advertisableFQDN: this.advertisableFQDN,
888
+ port: this.port,
889
+ network: this.network,
890
+ startedAt: this.startTime?.toISOString(),
891
+ uptimeMs: this.startTime === undefined ? 0 : Date.now() - this.startTime.getTime(),
892
+ topicManagerCount: Object.keys(this.managers).length,
893
+ lookupServiceCount: Object.keys(this.services).length
894
+ },
895
+ checks: this.healthConfig.includeDetails
896
+ ? checks
897
+ : checks.map(({ details, ...check }) => check),
898
+ context
899
+ }
900
+
901
+ return report
902
+ }
903
+
619
904
  /**
620
905
  * Starts the Express server.
621
906
  * Sets up routes and begins listening on the configured port.
@@ -726,9 +1011,41 @@ export default class OverlayExpress {
726
1011
  }))
727
1012
  })
728
1013
 
729
- // Serve a health check endpoint
1014
+ // Serve health check endpoints
1015
+ this.app.get('/health/live', (_, res) => {
1016
+ ; (async () => {
1017
+ const report = await this.collectHealthReport('live')
1018
+ return res.status(report.live ? 200 : 503).json(report)
1019
+ })().catch((error) => {
1020
+ res.status(500).json({
1021
+ status: 'error',
1022
+ message: error instanceof Error ? error.message : 'Unexpected error'
1023
+ })
1024
+ })
1025
+ })
1026
+
1027
+ this.app.get('/health/ready', (_, res) => {
1028
+ ; (async () => {
1029
+ const report = await this.collectHealthReport('ready')
1030
+ return res.status(report.ready ? 200 : 503).json(report)
1031
+ })().catch((error) => {
1032
+ res.status(500).json({
1033
+ status: 'error',
1034
+ message: error instanceof Error ? error.message : 'Unexpected error'
1035
+ })
1036
+ })
1037
+ })
1038
+
730
1039
  this.app.get('/health', (_, res) => {
731
- res.status(200).json({ status: 'ok' })
1040
+ ; (async () => {
1041
+ const report = await this.collectHealthReport('full')
1042
+ return res.status(report.ready ? 200 : 503).json(report)
1043
+ })().catch((error) => {
1044
+ res.status(500).json({
1045
+ status: 'error',
1046
+ message: error instanceof Error ? error.message : 'Unexpected error'
1047
+ })
1048
+ })
732
1049
  })
733
1050
 
734
1051
  // List hosted topic managers and lookup services
@@ -821,7 +1138,7 @@ export default class OverlayExpress {
821
1138
  const topicsHeader = req.headers['x-topics']
822
1139
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true'
823
1140
  if (typeof topicsHeader !== 'string') {
824
- throw new Error('Missing x-topics header')
1141
+ throw new TypeError('Missing x-topics header')
825
1142
  }
826
1143
  const topics = JSON.parse(topicsHeader)
827
1144
  let offChainValues: number[] | undefined
@@ -1093,7 +1410,7 @@ export default class OverlayExpress {
1093
1410
  data: {
1094
1411
  nodeName: this.name,
1095
1412
  network: this.network,
1096
- uptime: this.startTime !== undefined ? Date.now() - this.startTime.getTime() : 0,
1413
+ uptime: this.startTime != null ? Date.now() - this.startTime.getTime() : 0,
1097
1414
  startedAt: this.startTime?.toISOString(),
1098
1415
  shipRecordCount: shipCount,
1099
1416
  slapRecordCount: slapCount,
@@ -1126,9 +1443,9 @@ export default class OverlayExpress {
1126
1443
  const collection = db.collection('shipRecords')
1127
1444
 
1128
1445
  const search = typeof req.query.search === 'string' ? req.query.search : undefined
1129
- const rawPage = parseInt(req.query.page as string, 10)
1446
+ const rawPage = Number.parseInt(req.query.page as string, 10)
1130
1447
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage)
1131
- const rawLimit = parseInt(req.query.limit as string, 10)
1448
+ const rawLimit = Number.parseInt(req.query.limit as string, 10)
1132
1449
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit))
1133
1450
  const skip = (page - 1) * limit
1134
1451
 
@@ -1172,9 +1489,9 @@ export default class OverlayExpress {
1172
1489
  const collection = db.collection('slapRecords')
1173
1490
 
1174
1491
  const search = typeof req.query.search === 'string' ? req.query.search : undefined
1175
- const rawPage = parseInt(req.query.page as string, 10)
1492
+ const rawPage = Number.parseInt(req.query.page as string, 10)
1176
1493
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage)
1177
- const rawLimit = parseInt(req.query.limit as string, 10)
1494
+ const rawLimit = Number.parseInt(req.query.limit as string, 10)
1178
1495
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit))
1179
1496
  const skip = (page - 1) * limit
1180
1497
 
@@ -1251,48 +1568,9 @@ export default class OverlayExpress {
1251
1568
  }
1252
1569
 
1253
1570
  if (type === 'domain') {
1254
- await this.banService.banDomain(value, reason)
1255
-
1256
- // Also remove any existing records for this domain from SHIP and SLAP
1257
- const db = this.ensureMongo()
1258
- const [shipDeleted, slapDeleted] = await Promise.all([
1259
- db.collection('shipRecords').deleteMany({ domain: value }),
1260
- db.collection('slapRecords').deleteMany({ domain: value })
1261
- ])
1262
-
1263
- return res.status(200).json({
1264
- status: 'success',
1265
- message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
1266
- })
1267
- } else {
1268
- // Parse outpoint: "txid.outputIndex"
1269
- const dotIndex = value.lastIndexOf('.')
1270
- if (dotIndex === -1) {
1271
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' })
1272
- }
1273
- const txid = value.substring(0, dotIndex)
1274
- const outputIndex = parseInt(value.substring(dotIndex + 1))
1275
- if (isNaN(outputIndex)) {
1276
- return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' })
1277
- }
1278
-
1279
- await this.banService.banOutpoint(txid, outputIndex, reason)
1280
-
1281
- // Also evict from lookup services
1282
- const services = Object.values(engine.lookupServices)
1283
- for (const service of services) {
1284
- try {
1285
- await service.outputEvicted(txid, outputIndex)
1286
- } catch {
1287
- continue
1288
- }
1289
- }
1290
-
1291
- return res.status(200).json({
1292
- status: 'success',
1293
- message: `Outpoint "${value}" banned and evicted from lookup services.`
1294
- })
1571
+ return await this.handleBanDomain(res, value, reason)
1295
1572
  }
1573
+ return await this.handleBanOutpoint(res, engine, value, reason)
1296
1574
  } catch (error) {
1297
1575
  return res.status(400).json({
1298
1576
  status: 'error',
@@ -1369,52 +1647,29 @@ export default class OverlayExpress {
1369
1647
  return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' })
1370
1648
  }
1371
1649
 
1372
- // Get the domain before removing (for ban option)
1650
+ // Look up domain before eviction if needed for banning
1373
1651
  let removedDomain: string | undefined
1374
1652
  if (shouldBanDomain === true || ban === true) {
1375
- const db = this.ensureMongo()
1376
- const shipRecord = await db.collection('shipRecords').findOne({ txid, outputIndex })
1377
- const slapRecord = await db.collection('slapRecords').findOne({ txid, outputIndex })
1378
- removedDomain = (shipRecord?.domain ?? slapRecord?.domain) as string | undefined
1653
+ removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex)
1379
1654
  }
1380
1655
 
1381
- // Evict from specified service or all services
1382
- if (typeof service === 'string') {
1383
- const svc = engine.lookupServices[service]
1384
- if (svc !== undefined) {
1385
- await svc.outputEvicted(txid, outputIndex)
1386
- }
1387
- } else {
1388
- const services = Object.values(engine.lookupServices)
1389
- for (const svc of services) {
1390
- try {
1391
- await svc.outputEvicted(txid, outputIndex)
1392
- } catch {
1393
- continue
1394
- }
1395
- }
1396
- }
1656
+ await this.evictFromServices(engine, txid, outputIndex, service)
1397
1657
 
1398
- // Ban the outpoint if requested
1399
1658
  if (ban === true && this.banService !== undefined) {
1400
1659
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain)
1401
1660
  }
1402
1661
 
1403
- // Ban the domain if requested
1404
1662
  if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
1405
- await this.banService.banDomain(removedDomain, 'Domain banned by admin via token removal')
1406
-
1407
- // Remove all records for this domain
1408
- const banDb = this.ensureMongo()
1409
- await Promise.all([
1410
- banDb.collection('shipRecords').deleteMany({ domain: removedDomain }),
1411
- banDb.collection('slapRecords').deleteMany({ domain: removedDomain })
1412
- ])
1663
+ await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal')
1413
1664
  }
1414
1665
 
1666
+ const banMsg = ban === true ? ' Outpoint banned.' : ''
1667
+ const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
1668
+ ? ` Domain "${removedDomain}" banned.`
1669
+ : ''
1415
1670
  return res.status(200).json({
1416
1671
  status: 'success',
1417
- message: `Token ${txid}.${outputIndex} removed.${ban === true ? ' Outpoint banned.' : ''}${shouldBanDomain === true && typeof removedDomain === 'string' ? ` Domain "${removedDomain}" banned.` : ''}`
1672
+ message: `Token ${txid}.${outputIndex} removed.${banMsg}${domainMsg}`
1418
1673
  })
1419
1674
  } catch (error) {
1420
1675
  return res.status(400).json({
@@ -1484,9 +1739,9 @@ export default class OverlayExpress {
1484
1739
  await service.outputEvicted(req.body.txid, req.body.outputIndex)
1485
1740
  } else {
1486
1741
  const services = Object.values(engine.lookupServices)
1487
- for (let i = 0; i < services.length; i++) {
1742
+ for (const service of services) {
1488
1743
  try {
1489
- await services[i].outputEvicted(req.body.txid, req.body.outputIndex)
1744
+ await service.outputEvicted(req.body.txid, req.body.outputIndex)
1490
1745
  } catch {
1491
1746
  continue
1492
1747
  }
@@ -1587,6 +1842,7 @@ export default class OverlayExpress {
1587
1842
 
1588
1843
  // Start listening on the configured port
1589
1844
  this.app.listen(this.port, () => {
1845
+ this.isListening = true
1590
1846
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`))
1591
1847
  })
1592
1848
  }