@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.
@@ -7,7 +7,7 @@ import { MongoClient } from 'mongodb';
7
7
  import makeUserInterface from './makeUserInterface.js';
8
8
  import * as DiscoveryServices from '@bsv/overlay-discovery-services';
9
9
  import chalk from 'chalk';
10
- import util from 'util';
10
+ import util from 'node:util';
11
11
  import { v4 as uuidv4 } from 'uuid';
12
12
  import { JanitorService } from './JanitorService.js';
13
13
  import { BanService } from './BanService.js';
@@ -69,6 +69,8 @@ export default class OverlayExpress {
69
69
  migrationsToRun = [];
70
70
  // MongoDB database
71
71
  mongoDb;
72
+ // MongoDB client retained for health checks
73
+ mongoClient;
72
74
  // Network ('main' or 'test')
73
75
  network = 'main';
74
76
  // If no custom ChainTracker is configured, default is a WhatsOnChain instance
@@ -109,6 +111,15 @@ export default class OverlayExpress {
109
111
  serverWallet;
110
112
  // Server start time for uptime tracking
111
113
  startTime;
114
+ // Health endpoint configuration
115
+ healthConfig = {
116
+ includeDetails: true,
117
+ timeoutMs: 5000
118
+ };
119
+ // Extra application-specific health checks
120
+ healthChecks = [];
121
+ // Lifecycle marker for readiness/liveness reporting
122
+ isListening = false;
112
123
  /**
113
124
  * Constructs an instance of OverlayExpress.
114
125
  * @param name - The name of the service
@@ -161,6 +172,28 @@ export default class OverlayExpress {
161
172
  };
162
173
  this.logger.log(chalk.blue('Janitor service has been configured.'));
163
174
  }
175
+ /**
176
+ * Configures health-report behavior.
177
+ */
178
+ configureHealth(config) {
179
+ this.healthConfig = {
180
+ ...this.healthConfig,
181
+ ...config
182
+ };
183
+ this.logger.log(chalk.blue('Health reporting has been configured.'));
184
+ }
185
+ /**
186
+ * Registers an application-specific health check.
187
+ */
188
+ registerHealthCheck(definition) {
189
+ this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name);
190
+ this.healthChecks.push({
191
+ scope: 'ready',
192
+ critical: false,
193
+ ...definition
194
+ });
195
+ this.logger.log(chalk.blue(`Registered health check ${definition.name}`));
196
+ }
164
197
  /**
165
198
  * Configures the admin identity key for wallet-based admin detection.
166
199
  * When set, the frontend can compare the user's wallet identity key against this
@@ -226,7 +259,7 @@ export default class OverlayExpress {
226
259
  }
227
260
  /**
228
261
  * Configure Knex (SQL) database connection.
229
- * @param config - Knex configuration object, or MySQL connection string (e.g. mysql://overlayAdmin:overlay123@mysql:3306/overlay).
262
+ * @param config - Knex configuration object, or a MySQL connection string loaded from configuration.
230
263
  */
231
264
  async configureKnex(config) {
232
265
  if (typeof config === 'string') {
@@ -246,6 +279,7 @@ export default class OverlayExpress {
246
279
  async configureMongo(connectionString) {
247
280
  const mongoClient = new MongoClient(connectionString);
248
281
  await mongoClient.connect();
282
+ this.mongoClient = mongoClient;
249
283
  const db = mongoClient.db(`${this.name}_lookup_services`);
250
284
  this.mongoDb = db;
251
285
  // Initialize the BanService
@@ -328,126 +362,96 @@ export default class OverlayExpress {
328
362
  async configureEngine(autoConfigureShipSlap = true) {
329
363
  const knex = this.ensureKnex();
330
364
  if (autoConfigureShipSlap) {
331
- // Auto-configure SHIP and SLAP services
332
365
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
333
366
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
334
367
  this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(new DiscoveryServices.SHIPStorage(db)));
335
368
  this.configureLookupServiceWithMongo('ls_slap', (db) => new DiscoveryServices.SLAPLookupService(new DiscoveryServices.SLAPStorage(db)));
336
369
  }
337
- // Wrap SHIP/SLAP lookup services with ban-aware wrappers if BanService is available.
338
- // This prevents GASP from re-syncing tokens whose domains or outpoints have been banned.
339
- if (this.banService !== undefined) {
340
- if (this.services.ls_ship !== undefined) {
341
- this.services.ls_ship = new BanAwareLookupWrapper(this.services.ls_ship, this.banService, 'SHIP', this.logger);
342
- this.logger.log(chalk.blue('SHIP lookup service wrapped with ban-aware filter.'));
343
- }
344
- if (this.services.ls_slap !== undefined) {
345
- this.services.ls_slap = new BanAwareLookupWrapper(this.services.ls_slap, this.banService, 'SLAP', this.logger);
346
- this.logger.log(chalk.blue('SLAP lookup service wrapped with ban-aware filter.'));
370
+ this.wrapBanAwareServices();
371
+ const syncConfig = this.buildSyncConfig();
372
+ const storage = new KnexStorage(knex);
373
+ this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun];
374
+ const broadcaster = this.buildBroadcaster();
375
+ const advertiser = await this.buildAdvertiser();
376
+ this.engine = new Engine(this.managers, this.services, storage, this.engineConfig.chainTracker ?? this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
377
+ ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
378
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster ?? this.engineConfig.broadcaster, advertiser, syncConfig, this.engineConfig.logTime ?? false, this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ', this.engineConfig.throwOnBroadcastFailure ?? false, this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(), this.logger, this.engineConfig.suppressDefaultSyncAdvertisements ?? true);
379
+ this.initServerWallet();
380
+ this.logger.log(chalk.green('Engine has been configured.'));
381
+ }
382
+ /** Wrap SHIP/SLAP with ban-aware filter if BanService is configured. */
383
+ wrapBanAwareServices() {
384
+ if (this.banService === undefined)
385
+ return;
386
+ for (const key of ['ls_ship', 'ls_slap']) {
387
+ if (this.services[key] !== undefined) {
388
+ const label = key === 'ls_ship' ? 'SHIP' : 'SLAP';
389
+ this.services[key] = new BanAwareLookupWrapper(this.services[key], this.banService, label, this.logger);
390
+ this.logger.log(chalk.blue(`${label} lookup service wrapped with ban-aware filter.`));
347
391
  }
348
392
  }
349
- // Construct a default sync configuration, in case the user doesn't want GASP at all:
350
- let syncConfig = {};
351
- if (!this.enableGASPSync) {
352
- // For each manager, disable sync
353
- for (const managerName of Object.keys(this.managers)) {
354
- syncConfig[managerName] = false;
355
- }
393
+ }
394
+ /** Build the sync config based on enableGASPSync and engineConfig. */
395
+ buildSyncConfig() {
396
+ if (this.enableGASPSync) {
397
+ return this.engineConfig.syncConfiguration ?? {};
356
398
  }
357
- else {
358
- // If the user provided a syncConfiguration, use that. Otherwise default to an empty object.
359
- syncConfig = this.engineConfig.syncConfiguration ?? {};
399
+ const syncConfig = {};
400
+ for (const name of Object.keys(this.managers)) {
401
+ syncConfig[name] = false;
360
402
  }
361
- // Build the actual Storage
362
- const storage = new KnexStorage(knex);
363
- // Include the KnexStorage migrations
364
- this.migrationsToRun = [...KnexStorageMigrations.default, ...this.migrationsToRun];
365
- // Prepare broadcaster if arcApiKey is set
366
- let broadcaster;
367
- if (typeof this.arcApiKey === 'string') {
368
- broadcaster = new ARC(
369
- // We hard-code some ARC URLs for now, but we should make this configurable later.
370
- this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com', {
371
- apiKey: this.arcApiKey
372
- });
403
+ return syncConfig;
404
+ }
405
+ /** Build the ARC broadcaster if an API key is configured. */
406
+ buildBroadcaster() {
407
+ if (typeof this.arcApiKey !== 'string')
408
+ return undefined;
409
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
410
+ return new ARC(arcUrl, { apiKey: this.arcApiKey });
411
+ }
412
+ /** Resolve the SLAP trackers from config or network defaults. */
413
+ resolveSlapTrackers() {
414
+ if (Array.isArray(this.engineConfig.slapTrackers))
415
+ return this.engineConfig.slapTrackers;
416
+ return this.network === 'test' ? DEFAULT_TESTNET_SLAP_TRACKERS : DEFAULT_SLAP_TRACKERS;
417
+ }
418
+ /** Build the WalletAdvertiser (or use user-provided one). */
419
+ async buildAdvertiser() {
420
+ if (this.engineConfig.advertiser !== undefined)
421
+ return this.engineConfig.advertiser;
422
+ const storageBase = this.network === 'test'
423
+ ? 'https://staging-storage.babbage.systems'
424
+ : 'https://storage.babbage.systems';
425
+ try {
426
+ return new DiscoveryServices.WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
373
427
  }
374
- // Prepare advertiser if not set by the user
375
- let advertiser = this.engineConfig.advertiser;
376
- if (typeof advertiser === 'undefined') {
377
- try {
378
- advertiser = new DiscoveryServices.WalletAdvertiser(this.network, this.privateKey, this.network === 'test' // For now, we hard-code some storage servers. In the future, this needs to be configurable.
379
- ? 'https://staging-storage.babbage.systems'
380
- : 'https://storage.babbage.systems',
381
- // Until multiple protocols (like https+bsvauth+smf) are fully supported, HTTPS is the one to always use.
382
- `https://${this.advertisableFQDN}`);
383
- }
384
- catch (e) {
385
- this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled.`);
386
- }
428
+ catch (e) {
429
+ this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`);
430
+ return undefined;
387
431
  }
388
- // Construct the Engine with any advanced config overrides. Fallback to defaults.
389
- this.engine = new Engine(this.managers, this.services, storage,
390
- // chainTracker
391
- typeof this.engineConfig.chainTracker !== 'undefined'
392
- ? this.engineConfig.chainTracker
393
- : this.chainTracker,
394
- // hostingURL
395
- `https://${this.advertisableFQDN}`,
396
- // shipTrackers
397
- this.network === 'test'
398
- ? (this.engineConfig.shipTrackers ?? DEFAULT_TESTNET_SLAP_TRACKERS)
399
- : this.engineConfig.shipTrackers,
400
- // slapTrackers
401
- Array.isArray(this.engineConfig.slapTrackers)
402
- ? this.engineConfig.slapTrackers
403
- : this.network === 'test'
404
- ? DEFAULT_TESTNET_SLAP_TRACKERS
405
- : DEFAULT_SLAP_TRACKERS,
406
- // broadcaster
407
- broadcaster ?? this.engineConfig.broadcaster,
408
- // advertiser
409
- advertiser,
410
- // syncConfiguration
411
- syncConfig,
412
- // logTime
413
- this.engineConfig.logTime ?? false,
414
- // logPrefix
415
- this.engineConfig.logPrefix ?? '[OVERLAY_ENGINE] ',
416
- // throwOnBroadcastFailure
417
- this.engineConfig.throwOnBroadcastFailure ?? false,
418
- // overlayBroadcastFacilitator
419
- this.engineConfig.overlayBroadcastFacilitator ?? new HTTPSOverlayBroadcastFacilitator(),
420
- // logger
421
- this.logger,
422
- // suppressDefaultSyncAdvertisements
423
- this.engineConfig.suppressDefaultSyncAdvertisements ?? true);
424
- // Create the server wallet for BSV mutual authentication.
425
- // This uses the same private key as the WalletAdvertiser.
432
+ }
433
+ /** Initialize the server wallet for BSV mutual authentication. */
434
+ initServerWallet() {
426
435
  try {
427
436
  const keyDeriver = new KeyDeriver(new PrivateKey(this.privateKey, 'hex'));
428
437
  const storageManager = new WalletStorageManager(keyDeriver.identityKey);
429
438
  const signer = new WalletSigner(this.network, keyDeriver, storageManager);
430
439
  const services = new Services(this.network);
431
- const wallet = new Wallet(signer, services);
432
- this.serverWallet = wallet;
433
- // Auto-set the admin identity key from the server's own key if not configured
434
- if (typeof this.adminIdentityKey === 'undefined') {
435
- this.adminIdentityKey = keyDeriver.identityKey;
436
- }
440
+ this.serverWallet = new Wallet(signer, services);
441
+ this.adminIdentityKey ??= keyDeriver.identityKey;
437
442
  this.logger.log(chalk.blue('Server wallet initialized for BSV mutual authentication.'));
438
443
  }
439
444
  catch (e) {
440
- this.logger.log(chalk.yellow('Server wallet could not be initialized. BSV auth will not be available.'));
445
+ this.logger.log(chalk.yellow(`Server wallet could not be initialized. BSV auth will not be available. Reason: ${e}`));
441
446
  }
442
- this.logger.log(chalk.green('Engine has been configured.'));
443
447
  }
444
448
  /**
445
449
  * Ensures that Knex is configured and returns it.
446
450
  * @throws Error if Knex is not configured
447
451
  */
448
452
  ensureKnex() {
449
- if (typeof this.knex === 'undefined') {
450
- throw new Error('You must configure your SQL database with the .configureKnex() method first!');
453
+ if (this.knex === undefined) {
454
+ throw new TypeError('You must configure your SQL database with the .configureKnex() method first!');
451
455
  }
452
456
  return this.knex;
453
457
  }
@@ -456,8 +460,8 @@ export default class OverlayExpress {
456
460
  * @throws Error if MongoDB is not configured
457
461
  */
458
462
  ensureMongo() {
459
- if (typeof this.mongoDb === 'undefined') {
460
- throw new Error('You must configure your MongoDB connection with the .configureMongo() method first!');
463
+ if (this.mongoDb === undefined) {
464
+ throw new TypeError('You must configure your MongoDB connection with the .configureMongo() method first!');
461
465
  }
462
466
  return this.mongoDb;
463
467
  }
@@ -466,8 +470,8 @@ export default class OverlayExpress {
466
470
  * @throws Error if the Engine is not configured
467
471
  */
468
472
  ensureEngine() {
469
- if (typeof this.engine === 'undefined') {
470
- throw new Error('You must configure your Overlay Services engine with the .configureEngine() method first!');
473
+ if (this.engine === undefined) {
474
+ throw new TypeError('You must configure your Overlay Services engine with the .configureEngine() method first!');
471
475
  }
472
476
  return this.engine;
473
477
  }
@@ -485,6 +489,215 @@ export default class OverlayExpress {
485
489
  autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
486
490
  });
487
491
  }
492
+ /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
493
+ async handleBanDomain(res, value, reason) {
494
+ await this.banService.banDomain(value, reason);
495
+ const db = this.ensureMongo();
496
+ const [shipDeleted, slapDeleted] = await Promise.all([
497
+ db.collection('shipRecords').deleteMany({ domain: value }),
498
+ db.collection('slapRecords').deleteMany({ domain: value })
499
+ ]);
500
+ return res.status(200).json({
501
+ status: 'success',
502
+ message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
503
+ });
504
+ }
505
+ /** Parse outpoint string, ban it, and evict it from all lookup services. */
506
+ async handleBanOutpoint(res, engine, value, reason) {
507
+ const dotIndex = value.lastIndexOf('.');
508
+ if (dotIndex === -1) {
509
+ return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
510
+ }
511
+ const txid = value.substring(0, dotIndex);
512
+ const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
513
+ if (Number.isNaN(outputIndex)) {
514
+ return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
515
+ }
516
+ await this.banService.banOutpoint(txid, outputIndex, reason);
517
+ await this.evictFromServices(engine, txid, outputIndex);
518
+ return res.status(200).json({
519
+ status: 'success',
520
+ message: `Outpoint "${value}" banned and evicted from lookup services.`
521
+ });
522
+ }
523
+ /** Evict an output from a specific service or all services (silent per-service errors). */
524
+ async evictFromServices(engine, txid, outputIndex, service) {
525
+ if (typeof service === 'string') {
526
+ const svc = engine.lookupServices[service];
527
+ if (svc !== undefined)
528
+ await svc.outputEvicted(txid, outputIndex);
529
+ return;
530
+ }
531
+ for (const svc of Object.values(engine.lookupServices)) {
532
+ try {
533
+ await svc.outputEvicted(txid, outputIndex);
534
+ }
535
+ catch { /* best-effort */ }
536
+ }
537
+ }
538
+ /** Look up the domain of an outpoint from SHIP or SLAP records. */
539
+ async lookupDomainForOutpoint(txid, outputIndex) {
540
+ const db = this.ensureMongo();
541
+ const [shipRecord, slapRecord] = await Promise.all([
542
+ db.collection('shipRecords').findOne({ txid, outputIndex }),
543
+ db.collection('slapRecords').findOne({ txid, outputIndex })
544
+ ]);
545
+ return (shipRecord?.domain ?? slapRecord?.domain);
546
+ }
547
+ /** Ban a domain and delete all SHIP/SLAP records for it. */
548
+ async banDomainAndRemoveRecords(domain, reason) {
549
+ await this.banService.banDomain(domain, reason);
550
+ const db = this.ensureMongo();
551
+ await Promise.all([
552
+ db.collection('shipRecords').deleteMany({ domain }),
553
+ db.collection('slapRecords').deleteMany({ domain })
554
+ ]);
555
+ }
556
+ async runHealthCheck(definition) {
557
+ const startedAt = Date.now();
558
+ try {
559
+ const result = ((await Promise.race([
560
+ Promise.resolve(definition.handler()),
561
+ new Promise((_, reject) => {
562
+ setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
563
+ })
564
+ ])) ?? {});
565
+ return {
566
+ name: definition.name,
567
+ scope: definition.scope,
568
+ critical: definition.critical,
569
+ status: result.status ?? 'ok',
570
+ message: result.message,
571
+ details: result.details,
572
+ durationMs: Date.now() - startedAt
573
+ };
574
+ }
575
+ catch (error) {
576
+ return {
577
+ name: definition.name,
578
+ scope: definition.scope,
579
+ critical: definition.critical,
580
+ status: 'error',
581
+ message: error instanceof Error ? error.message : 'Unknown health-check error',
582
+ durationMs: Date.now() - startedAt
583
+ };
584
+ }
585
+ }
586
+ async collectHealthReport(mode) {
587
+ const definitions = [
588
+ {
589
+ name: 'process',
590
+ scope: 'live',
591
+ critical: true,
592
+ handler: async () => ({
593
+ status: 'ok',
594
+ details: {
595
+ listening: this.isListening
596
+ }
597
+ })
598
+ },
599
+ {
600
+ name: 'engine',
601
+ scope: 'ready',
602
+ critical: true,
603
+ handler: async () => {
604
+ if (this.engine === undefined) {
605
+ throw new TypeError('Overlay engine is not configured');
606
+ }
607
+ return {
608
+ status: 'ok',
609
+ details: {
610
+ topicManagers: Object.keys(this.managers),
611
+ lookupServices: Object.keys(this.services)
612
+ }
613
+ };
614
+ }
615
+ },
616
+ {
617
+ name: 'knex',
618
+ scope: 'ready',
619
+ critical: true,
620
+ handler: async () => {
621
+ if (this.knex === undefined) {
622
+ throw new TypeError('Knex is not configured');
623
+ }
624
+ await this.knex.raw('select 1 as ok');
625
+ return {
626
+ status: 'ok',
627
+ details: {
628
+ client: this.knex.client?.config?.client ?? 'unknown'
629
+ }
630
+ };
631
+ }
632
+ },
633
+ {
634
+ name: 'mongo',
635
+ scope: 'ready',
636
+ critical: true,
637
+ handler: async () => {
638
+ if (this.mongoDb === undefined) {
639
+ throw new TypeError('MongoDB is not configured');
640
+ }
641
+ await this.mongoDb.command({ ping: 1 });
642
+ return {
643
+ status: 'ok',
644
+ details: {
645
+ database: this.mongoDb.databaseName
646
+ }
647
+ };
648
+ }
649
+ }
650
+ ];
651
+ for (const check of this.healthChecks) {
652
+ definitions.push({
653
+ name: check.name,
654
+ scope: check.scope ?? 'ready',
655
+ critical: check.critical ?? false,
656
+ handler: check.handler
657
+ });
658
+ }
659
+ const filteredDefinitions = definitions.filter((definition) => {
660
+ if (mode === 'full') {
661
+ return true;
662
+ }
663
+ return definition.scope === mode;
664
+ });
665
+ const checks = await Promise.all(filteredDefinitions.map(async (definition) => await this.runHealthCheck(definition)));
666
+ const liveChecks = checks.filter(check => check.scope === 'live');
667
+ const readyChecks = checks.filter(check => check.scope === 'ready');
668
+ const live = liveChecks.every(check => !check.critical || check.status === 'ok');
669
+ const ready = readyChecks.every(check => !check.critical || check.status === 'ok');
670
+ let status = 'ok';
671
+ if (!live || !ready || checks.some(check => check.critical && check.status === 'error')) {
672
+ status = 'error';
673
+ }
674
+ else if (checks.some(check => check.status !== 'ok')) {
675
+ status = 'degraded';
676
+ }
677
+ const context = typeof this.healthConfig.contextProvider === 'function'
678
+ ? await this.healthConfig.contextProvider()
679
+ : undefined;
680
+ const report = {
681
+ status,
682
+ live,
683
+ ready,
684
+ service: {
685
+ name: this.name,
686
+ advertisableFQDN: this.advertisableFQDN,
687
+ port: this.port,
688
+ network: this.network,
689
+ startedAt: this.startTime?.toISOString(),
690
+ uptimeMs: this.startTime === undefined ? 0 : Date.now() - this.startTime.getTime(),
691
+ topicManagerCount: Object.keys(this.managers).length,
692
+ lookupServiceCount: Object.keys(this.services).length
693
+ },
694
+ checks: this.healthConfig.includeDetails
695
+ ? checks
696
+ : checks.map(({ details, ...check }) => check),
697
+ context
698
+ };
699
+ return report;
700
+ }
488
701
  /**
489
702
  * Starts the Express server.
490
703
  * Sets up routes and begins listening on the configured port.
@@ -587,9 +800,42 @@ export default class OverlayExpress {
587
800
  adminIdentityKey: this.adminIdentityKey
588
801
  }));
589
802
  });
590
- // Serve a health check endpoint
803
+ // Serve health check endpoints
804
+ this.app.get('/health/live', (_, res) => {
805
+ ;
806
+ (async () => {
807
+ const report = await this.collectHealthReport('live');
808
+ return res.status(report.live ? 200 : 503).json(report);
809
+ })().catch((error) => {
810
+ res.status(500).json({
811
+ status: 'error',
812
+ message: error instanceof Error ? error.message : 'Unexpected error'
813
+ });
814
+ });
815
+ });
816
+ this.app.get('/health/ready', (_, res) => {
817
+ ;
818
+ (async () => {
819
+ const report = await this.collectHealthReport('ready');
820
+ return res.status(report.ready ? 200 : 503).json(report);
821
+ })().catch((error) => {
822
+ res.status(500).json({
823
+ status: 'error',
824
+ message: error instanceof Error ? error.message : 'Unexpected error'
825
+ });
826
+ });
827
+ });
591
828
  this.app.get('/health', (_, res) => {
592
- res.status(200).json({ status: 'ok' });
829
+ ;
830
+ (async () => {
831
+ const report = await this.collectHealthReport('full');
832
+ return res.status(report.ready ? 200 : 503).json(report);
833
+ })().catch((error) => {
834
+ res.status(500).json({
835
+ status: 'error',
836
+ message: error instanceof Error ? error.message : 'Unexpected error'
837
+ });
838
+ });
593
839
  });
594
840
  // List hosted topic managers and lookup services
595
841
  this.app.get('/listTopicManagers', (_, res) => {
@@ -686,7 +932,7 @@ export default class OverlayExpress {
686
932
  const topicsHeader = req.headers['x-topics'];
687
933
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true';
688
934
  if (typeof topicsHeader !== 'string') {
689
- throw new Error('Missing x-topics header');
935
+ throw new TypeError('Missing x-topics header');
690
936
  }
691
937
  const topics = JSON.parse(topicsHeader);
692
938
  let offChainValues;
@@ -946,7 +1192,7 @@ export default class OverlayExpress {
946
1192
  data: {
947
1193
  nodeName: this.name,
948
1194
  network: this.network,
949
- uptime: this.startTime !== undefined ? Date.now() - this.startTime.getTime() : 0,
1195
+ uptime: this.startTime != null ? Date.now() - this.startTime.getTime() : 0,
950
1196
  startedAt: this.startTime?.toISOString(),
951
1197
  shipRecordCount: shipCount,
952
1198
  slapRecordCount: slapCount,
@@ -979,9 +1225,9 @@ export default class OverlayExpress {
979
1225
  const db = this.ensureMongo();
980
1226
  const collection = db.collection('shipRecords');
981
1227
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
982
- const rawPage = parseInt(req.query.page, 10);
1228
+ const rawPage = Number.parseInt(req.query.page, 10);
983
1229
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
984
- const rawLimit = parseInt(req.query.limit, 10);
1230
+ const rawLimit = Number.parseInt(req.query.limit, 10);
985
1231
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
986
1232
  const skip = (page - 1) * limit;
987
1233
  const query = {};
@@ -1022,9 +1268,9 @@ export default class OverlayExpress {
1022
1268
  const db = this.ensureMongo();
1023
1269
  const collection = db.collection('slapRecords');
1024
1270
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1025
- const rawPage = parseInt(req.query.page, 10);
1271
+ const rawPage = Number.parseInt(req.query.page, 10);
1026
1272
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1027
- const rawLimit = parseInt(req.query.limit, 10);
1273
+ const rawLimit = Number.parseInt(req.query.limit, 10);
1028
1274
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1029
1275
  const skip = (page - 1) * limit;
1030
1276
  const query = {};
@@ -1098,45 +1344,9 @@ export default class OverlayExpress {
1098
1344
  return res.status(400).json({ status: 'error', message: 'value is required' });
1099
1345
  }
1100
1346
  if (type === 'domain') {
1101
- await this.banService.banDomain(value, reason);
1102
- // Also remove any existing records for this domain from SHIP and SLAP
1103
- const db = this.ensureMongo();
1104
- const [shipDeleted, slapDeleted] = await Promise.all([
1105
- db.collection('shipRecords').deleteMany({ domain: value }),
1106
- db.collection('slapRecords').deleteMany({ domain: value })
1107
- ]);
1108
- return res.status(200).json({
1109
- status: 'success',
1110
- message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
1111
- });
1112
- }
1113
- else {
1114
- // Parse outpoint: "txid.outputIndex"
1115
- const dotIndex = value.lastIndexOf('.');
1116
- if (dotIndex === -1) {
1117
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
1118
- }
1119
- const txid = value.substring(0, dotIndex);
1120
- const outputIndex = parseInt(value.substring(dotIndex + 1));
1121
- if (isNaN(outputIndex)) {
1122
- return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
1123
- }
1124
- await this.banService.banOutpoint(txid, outputIndex, reason);
1125
- // Also evict from lookup services
1126
- const services = Object.values(engine.lookupServices);
1127
- for (const service of services) {
1128
- try {
1129
- await service.outputEvicted(txid, outputIndex);
1130
- }
1131
- catch {
1132
- continue;
1133
- }
1134
- }
1135
- return res.status(200).json({
1136
- status: 'success',
1137
- message: `Outpoint "${value}" banned and evicted from lookup services.`
1138
- });
1347
+ return await this.handleBanDomain(res, value, reason);
1139
1348
  }
1349
+ return await this.handleBanOutpoint(res, engine, value, reason);
1140
1350
  }
1141
1351
  catch (error) {
1142
1352
  return res.status(400).json({
@@ -1214,49 +1424,25 @@ export default class OverlayExpress {
1214
1424
  if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
1215
1425
  return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' });
1216
1426
  }
1217
- // Get the domain before removing (for ban option)
1427
+ // Look up domain before eviction if needed for banning
1218
1428
  let removedDomain;
1219
1429
  if (shouldBanDomain === true || ban === true) {
1220
- const db = this.ensureMongo();
1221
- const shipRecord = await db.collection('shipRecords').findOne({ txid, outputIndex });
1222
- const slapRecord = await db.collection('slapRecords').findOne({ txid, outputIndex });
1223
- removedDomain = (shipRecord?.domain ?? slapRecord?.domain);
1224
- }
1225
- // Evict from specified service or all services
1226
- if (typeof service === 'string') {
1227
- const svc = engine.lookupServices[service];
1228
- if (svc !== undefined) {
1229
- await svc.outputEvicted(txid, outputIndex);
1230
- }
1430
+ removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex);
1231
1431
  }
1232
- else {
1233
- const services = Object.values(engine.lookupServices);
1234
- for (const svc of services) {
1235
- try {
1236
- await svc.outputEvicted(txid, outputIndex);
1237
- }
1238
- catch {
1239
- continue;
1240
- }
1241
- }
1242
- }
1243
- // Ban the outpoint if requested
1432
+ await this.evictFromServices(engine, txid, outputIndex, service);
1244
1433
  if (ban === true && this.banService !== undefined) {
1245
1434
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
1246
1435
  }
1247
- // Ban the domain if requested
1248
1436
  if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
1249
- await this.banService.banDomain(removedDomain, 'Domain banned by admin via token removal');
1250
- // Remove all records for this domain
1251
- const banDb = this.ensureMongo();
1252
- await Promise.all([
1253
- banDb.collection('shipRecords').deleteMany({ domain: removedDomain }),
1254
- banDb.collection('slapRecords').deleteMany({ domain: removedDomain })
1255
- ]);
1437
+ await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
1256
1438
  }
1439
+ const banMsg = ban === true ? ' Outpoint banned.' : '';
1440
+ const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
1441
+ ? ` Domain "${removedDomain}" banned.`
1442
+ : '';
1257
1443
  return res.status(200).json({
1258
1444
  status: 'success',
1259
- message: `Token ${txid}.${outputIndex} removed.${ban === true ? ' Outpoint banned.' : ''}${shouldBanDomain === true && typeof removedDomain === 'string' ? ` Domain "${removedDomain}" banned.` : ''}`
1445
+ message: `Token ${txid}.${outputIndex} removed.${banMsg}${domainMsg}`
1260
1446
  });
1261
1447
  }
1262
1448
  catch (error) {
@@ -1330,9 +1516,9 @@ export default class OverlayExpress {
1330
1516
  }
1331
1517
  else {
1332
1518
  const services = Object.values(engine.lookupServices);
1333
- for (let i = 0; i < services.length; i++) {
1519
+ for (const service of services) {
1334
1520
  try {
1335
- await services[i].outputEvicted(req.body.txid, req.body.outputIndex);
1521
+ await service.outputEvicted(req.body.txid, req.body.outputIndex);
1336
1522
  }
1337
1523
  catch {
1338
1524
  continue;
@@ -1428,6 +1614,7 @@ export default class OverlayExpress {
1428
1614
  }
1429
1615
  // Start listening on the configured port
1430
1616
  this.app.listen(this.port, () => {
1617
+ this.isListening = true;
1431
1618
  this.logger.log(chalk.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1432
1619
  });
1433
1620
  }