@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.
@@ -45,7 +45,7 @@ const mongodb_1 = require("mongodb");
45
45
  const makeUserInterface_js_1 = __importDefault(require("./makeUserInterface.js"));
46
46
  const DiscoveryServices = __importStar(require("@bsv/overlay-discovery-services"));
47
47
  const chalk_1 = __importDefault(require("chalk"));
48
- const util_1 = __importDefault(require("util"));
48
+ const node_util_1 = __importDefault(require("node:util"));
49
49
  const uuid_1 = require("uuid");
50
50
  const JanitorService_js_1 = require("./JanitorService.js");
51
51
  const BanService_js_1 = require("./BanService.js");
@@ -136,6 +136,15 @@ class OverlayExpress {
136
136
  hostDownRevokeScore: 3,
137
137
  autoBanOnRemoval: true
138
138
  };
139
+ // Health endpoint configuration
140
+ this.healthConfig = {
141
+ includeDetails: true,
142
+ timeoutMs: 5000
143
+ };
144
+ // Extra application-specific health checks
145
+ this.healthChecks = [];
146
+ // Lifecycle marker for readiness/liveness reporting
147
+ this.isListening = false;
139
148
  this.app = (0, express_1.default)();
140
149
  this.logger.log(chalk_1.default.green.bold(`${name} constructed`));
141
150
  this.adminToken = adminToken !== null && adminToken !== void 0 ? adminToken : (0, uuid_1.v4)(); // generate random if not provided
@@ -176,6 +185,28 @@ class OverlayExpress {
176
185
  };
177
186
  this.logger.log(chalk_1.default.blue('Janitor service has been configured.'));
178
187
  }
188
+ /**
189
+ * Configures health-report behavior.
190
+ */
191
+ configureHealth(config) {
192
+ this.healthConfig = {
193
+ ...this.healthConfig,
194
+ ...config
195
+ };
196
+ this.logger.log(chalk_1.default.blue('Health reporting has been configured.'));
197
+ }
198
+ /**
199
+ * Registers an application-specific health check.
200
+ */
201
+ registerHealthCheck(definition) {
202
+ this.healthChecks = this.healthChecks.filter(check => check.name !== definition.name);
203
+ this.healthChecks.push({
204
+ scope: 'ready',
205
+ critical: false,
206
+ ...definition
207
+ });
208
+ this.logger.log(chalk_1.default.blue(`Registered health check ${definition.name}`));
209
+ }
179
210
  /**
180
211
  * Configures the admin identity key for wallet-based admin detection.
181
212
  * When set, the frontend can compare the user's wallet identity key against this
@@ -241,7 +272,7 @@ class OverlayExpress {
241
272
  }
242
273
  /**
243
274
  * Configure Knex (SQL) database connection.
244
- * @param config - Knex configuration object, or MySQL connection string (e.g. mysql://overlayAdmin:overlay123@mysql:3306/overlay).
275
+ * @param config - Knex configuration object, or a MySQL connection string loaded from configuration.
245
276
  */
246
277
  async configureKnex(config) {
247
278
  if (typeof config === 'string') {
@@ -261,6 +292,7 @@ class OverlayExpress {
261
292
  async configureMongo(connectionString) {
262
293
  const mongoClient = new mongodb_1.MongoClient(connectionString);
263
294
  await mongoClient.connect();
295
+ this.mongoClient = mongoClient;
264
296
  const db = mongoClient.db(`${this.name}_lookup_services`);
265
297
  this.mongoDb = db;
266
298
  // Initialize the BanService
@@ -344,126 +376,98 @@ class OverlayExpress {
344
376
  var _a, _b, _c, _d, _e, _f, _g;
345
377
  const knex = this.ensureKnex();
346
378
  if (autoConfigureShipSlap) {
347
- // Auto-configure SHIP and SLAP services
348
379
  this.configureTopicManager('tm_ship', new DiscoveryServices.SHIPTopicManager());
349
380
  this.configureTopicManager('tm_slap', new DiscoveryServices.SLAPTopicManager());
350
381
  this.configureLookupServiceWithMongo('ls_ship', (db) => new DiscoveryServices.SHIPLookupService(new DiscoveryServices.SHIPStorage(db)));
351
382
  this.configureLookupServiceWithMongo('ls_slap', (db) => new DiscoveryServices.SLAPLookupService(new DiscoveryServices.SLAPStorage(db)));
352
383
  }
353
- // Wrap SHIP/SLAP lookup services with ban-aware wrappers if BanService is available.
354
- // This prevents GASP from re-syncing tokens whose domains or outpoints have been banned.
355
- if (this.banService !== undefined) {
356
- if (this.services.ls_ship !== undefined) {
357
- this.services.ls_ship = new BanAwareLookupWrapper_js_1.BanAwareLookupWrapper(this.services.ls_ship, this.banService, 'SHIP', this.logger);
358
- this.logger.log(chalk_1.default.blue('SHIP lookup service wrapped with ban-aware filter.'));
359
- }
360
- if (this.services.ls_slap !== undefined) {
361
- this.services.ls_slap = new BanAwareLookupWrapper_js_1.BanAwareLookupWrapper(this.services.ls_slap, this.banService, 'SLAP', this.logger);
362
- this.logger.log(chalk_1.default.blue('SLAP lookup service wrapped with ban-aware filter.'));
384
+ this.wrapBanAwareServices();
385
+ const syncConfig = this.buildSyncConfig();
386
+ const storage = new overlay_1.KnexStorage(knex);
387
+ this.migrationsToRun = [...overlay_1.KnexStorageMigrations.default, ...this.migrationsToRun];
388
+ const broadcaster = this.buildBroadcaster();
389
+ const advertiser = await this.buildAdvertiser();
390
+ this.engine = new overlay_1.Engine(this.managers, this.services, storage, (_a = this.engineConfig.chainTracker) !== null && _a !== void 0 ? _a : this.chainTracker, `https://${this.advertisableFQDN}`, this.network === 'test'
391
+ ? ((_b = this.engineConfig.shipTrackers) !== null && _b !== void 0 ? _b : sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS)
392
+ : this.engineConfig.shipTrackers, this.resolveSlapTrackers(), broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster, advertiser, syncConfig, (_c = this.engineConfig.logTime) !== null && _c !== void 0 ? _c : false, (_d = this.engineConfig.logPrefix) !== null && _d !== void 0 ? _d : '[OVERLAY_ENGINE] ', (_e = this.engineConfig.throwOnBroadcastFailure) !== null && _e !== void 0 ? _e : false, (_f = this.engineConfig.overlayBroadcastFacilitator) !== null && _f !== void 0 ? _f : new sdk_1.HTTPSOverlayBroadcastFacilitator(), this.logger, (_g = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _g !== void 0 ? _g : true);
393
+ this.initServerWallet();
394
+ this.logger.log(chalk_1.default.green('Engine has been configured.'));
395
+ }
396
+ /** Wrap SHIP/SLAP with ban-aware filter if BanService is configured. */
397
+ wrapBanAwareServices() {
398
+ if (this.banService === undefined)
399
+ return;
400
+ for (const key of ['ls_ship', 'ls_slap']) {
401
+ if (this.services[key] !== undefined) {
402
+ const label = key === 'ls_ship' ? 'SHIP' : 'SLAP';
403
+ this.services[key] = new BanAwareLookupWrapper_js_1.BanAwareLookupWrapper(this.services[key], this.banService, label, this.logger);
404
+ this.logger.log(chalk_1.default.blue(`${label} lookup service wrapped with ban-aware filter.`));
363
405
  }
364
406
  }
365
- // Construct a default sync configuration, in case the user doesn't want GASP at all:
366
- let syncConfig = {};
367
- if (!this.enableGASPSync) {
368
- // For each manager, disable sync
369
- for (const managerName of Object.keys(this.managers)) {
370
- syncConfig[managerName] = false;
371
- }
407
+ }
408
+ /** Build the sync config based on enableGASPSync and engineConfig. */
409
+ buildSyncConfig() {
410
+ var _a;
411
+ if (this.enableGASPSync) {
412
+ return (_a = this.engineConfig.syncConfiguration) !== null && _a !== void 0 ? _a : {};
372
413
  }
373
- else {
374
- // If the user provided a syncConfiguration, use that. Otherwise default to an empty object.
375
- syncConfig = (_a = this.engineConfig.syncConfiguration) !== null && _a !== void 0 ? _a : {};
414
+ const syncConfig = {};
415
+ for (const name of Object.keys(this.managers)) {
416
+ syncConfig[name] = false;
376
417
  }
377
- // Build the actual Storage
378
- const storage = new overlay_1.KnexStorage(knex);
379
- // Include the KnexStorage migrations
380
- this.migrationsToRun = [...overlay_1.KnexStorageMigrations.default, ...this.migrationsToRun];
381
- // Prepare broadcaster if arcApiKey is set
382
- let broadcaster;
383
- if (typeof this.arcApiKey === 'string') {
384
- broadcaster = new sdk_1.ARC(
385
- // We hard-code some ARC URLs for now, but we should make this configurable later.
386
- this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com', {
387
- apiKey: this.arcApiKey
388
- });
418
+ return syncConfig;
419
+ }
420
+ /** Build the ARC broadcaster if an API key is configured. */
421
+ buildBroadcaster() {
422
+ if (typeof this.arcApiKey !== 'string')
423
+ return undefined;
424
+ const arcUrl = this.network === 'test' ? 'https://arc-test.taal.com' : 'https://arc.taal.com';
425
+ return new sdk_1.ARC(arcUrl, { apiKey: this.arcApiKey });
426
+ }
427
+ /** Resolve the SLAP trackers from config or network defaults. */
428
+ resolveSlapTrackers() {
429
+ if (Array.isArray(this.engineConfig.slapTrackers))
430
+ return this.engineConfig.slapTrackers;
431
+ return this.network === 'test' ? sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS : sdk_1.DEFAULT_SLAP_TRACKERS;
432
+ }
433
+ /** Build the WalletAdvertiser (or use user-provided one). */
434
+ async buildAdvertiser() {
435
+ if (this.engineConfig.advertiser !== undefined)
436
+ return this.engineConfig.advertiser;
437
+ const storageBase = this.network === 'test'
438
+ ? 'https://staging-storage.babbage.systems'
439
+ : 'https://storage.babbage.systems';
440
+ try {
441
+ return new DiscoveryServices.WalletAdvertiser(this.network, this.privateKey, storageBase, `https://${this.advertisableFQDN}`);
389
442
  }
390
- // Prepare advertiser if not set by the user
391
- let advertiser = this.engineConfig.advertiser;
392
- if (typeof advertiser === 'undefined') {
393
- try {
394
- 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.
395
- ? 'https://staging-storage.babbage.systems'
396
- : 'https://storage.babbage.systems',
397
- // Until multiple protocols (like https+bsvauth+smf) are fully supported, HTTPS is the one to always use.
398
- `https://${this.advertisableFQDN}`);
399
- }
400
- catch (e) {
401
- this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled.`);
402
- }
443
+ catch (e) {
444
+ this.logger.log(`Advertiser not initialized for FQDN ${this.advertisableFQDN} - SHIP and SLAP will be disabled. Reason: ${e}`);
445
+ return undefined;
403
446
  }
404
- // Construct the Engine with any advanced config overrides. Fallback to defaults.
405
- this.engine = new overlay_1.Engine(this.managers, this.services, storage,
406
- // chainTracker
407
- typeof this.engineConfig.chainTracker !== 'undefined'
408
- ? this.engineConfig.chainTracker
409
- : this.chainTracker,
410
- // hostingURL
411
- `https://${this.advertisableFQDN}`,
412
- // shipTrackers
413
- this.network === 'test'
414
- ? ((_b = this.engineConfig.shipTrackers) !== null && _b !== void 0 ? _b : sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS)
415
- : this.engineConfig.shipTrackers,
416
- // slapTrackers
417
- Array.isArray(this.engineConfig.slapTrackers)
418
- ? this.engineConfig.slapTrackers
419
- : this.network === 'test'
420
- ? sdk_1.DEFAULT_TESTNET_SLAP_TRACKERS
421
- : sdk_1.DEFAULT_SLAP_TRACKERS,
422
- // broadcaster
423
- broadcaster !== null && broadcaster !== void 0 ? broadcaster : this.engineConfig.broadcaster,
424
- // advertiser
425
- advertiser,
426
- // syncConfiguration
427
- syncConfig,
428
- // logTime
429
- (_c = this.engineConfig.logTime) !== null && _c !== void 0 ? _c : false,
430
- // logPrefix
431
- (_d = this.engineConfig.logPrefix) !== null && _d !== void 0 ? _d : '[OVERLAY_ENGINE] ',
432
- // throwOnBroadcastFailure
433
- (_e = this.engineConfig.throwOnBroadcastFailure) !== null && _e !== void 0 ? _e : false,
434
- // overlayBroadcastFacilitator
435
- (_f = this.engineConfig.overlayBroadcastFacilitator) !== null && _f !== void 0 ? _f : new sdk_1.HTTPSOverlayBroadcastFacilitator(),
436
- // logger
437
- this.logger,
438
- // suppressDefaultSyncAdvertisements
439
- (_g = this.engineConfig.suppressDefaultSyncAdvertisements) !== null && _g !== void 0 ? _g : true);
440
- // Create the server wallet for BSV mutual authentication.
441
- // This uses the same private key as the WalletAdvertiser.
447
+ }
448
+ /** Initialize the server wallet for BSV mutual authentication. */
449
+ initServerWallet() {
450
+ var _a;
442
451
  try {
443
452
  const keyDeriver = new sdk_1.KeyDeriver(new sdk_1.PrivateKey(this.privateKey, 'hex'));
444
453
  const storageManager = new wallet_toolbox_client_1.WalletStorageManager(keyDeriver.identityKey);
445
454
  const signer = new wallet_toolbox_client_1.WalletSigner(this.network, keyDeriver, storageManager);
446
455
  const services = new wallet_toolbox_client_1.Services(this.network);
447
- const wallet = new wallet_toolbox_client_1.Wallet(signer, services);
448
- this.serverWallet = wallet;
449
- // Auto-set the admin identity key from the server's own key if not configured
450
- if (typeof this.adminIdentityKey === 'undefined') {
451
- this.adminIdentityKey = keyDeriver.identityKey;
452
- }
456
+ this.serverWallet = new wallet_toolbox_client_1.Wallet(signer, services);
457
+ (_a = this.adminIdentityKey) !== null && _a !== void 0 ? _a : (this.adminIdentityKey = keyDeriver.identityKey);
453
458
  this.logger.log(chalk_1.default.blue('Server wallet initialized for BSV mutual authentication.'));
454
459
  }
455
460
  catch (e) {
456
- this.logger.log(chalk_1.default.yellow('Server wallet could not be initialized. BSV auth will not be available.'));
461
+ this.logger.log(chalk_1.default.yellow(`Server wallet could not be initialized. BSV auth will not be available. Reason: ${e}`));
457
462
  }
458
- this.logger.log(chalk_1.default.green('Engine has been configured.'));
459
463
  }
460
464
  /**
461
465
  * Ensures that Knex is configured and returns it.
462
466
  * @throws Error if Knex is not configured
463
467
  */
464
468
  ensureKnex() {
465
- if (typeof this.knex === 'undefined') {
466
- throw new Error('You must configure your SQL database with the .configureKnex() method first!');
469
+ if (this.knex === undefined) {
470
+ throw new TypeError('You must configure your SQL database with the .configureKnex() method first!');
467
471
  }
468
472
  return this.knex;
469
473
  }
@@ -472,8 +476,8 @@ class OverlayExpress {
472
476
  * @throws Error if MongoDB is not configured
473
477
  */
474
478
  ensureMongo() {
475
- if (typeof this.mongoDb === 'undefined') {
476
- throw new Error('You must configure your MongoDB connection with the .configureMongo() method first!');
479
+ if (this.mongoDb === undefined) {
480
+ throw new TypeError('You must configure your MongoDB connection with the .configureMongo() method first!');
477
481
  }
478
482
  return this.mongoDb;
479
483
  }
@@ -482,8 +486,8 @@ class OverlayExpress {
482
486
  * @throws Error if the Engine is not configured
483
487
  */
484
488
  ensureEngine() {
485
- if (typeof this.engine === 'undefined') {
486
- throw new Error('You must configure your Overlay Services engine with the .configureEngine() method first!');
489
+ if (this.engine === undefined) {
490
+ throw new TypeError('You must configure your Overlay Services engine with the .configureEngine() method first!');
487
491
  }
488
492
  return this.engine;
489
493
  }
@@ -501,6 +505,219 @@ class OverlayExpress {
501
505
  autoBanOnRemoval: this.janitorConfig.autoBanOnRemoval
502
506
  });
503
507
  }
508
+ /** Ban a domain and remove all its SHIP/SLAP records from MongoDB. */
509
+ async handleBanDomain(res, value, reason) {
510
+ await this.banService.banDomain(value, reason);
511
+ const db = this.ensureMongo();
512
+ const [shipDeleted, slapDeleted] = await Promise.all([
513
+ db.collection('shipRecords').deleteMany({ domain: value }),
514
+ db.collection('slapRecords').deleteMany({ domain: value })
515
+ ]);
516
+ return res.status(200).json({
517
+ status: 'success',
518
+ message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
519
+ });
520
+ }
521
+ /** Parse outpoint string, ban it, and evict it from all lookup services. */
522
+ async handleBanOutpoint(res, engine, value, reason) {
523
+ const dotIndex = value.lastIndexOf('.');
524
+ if (dotIndex === -1) {
525
+ return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
526
+ }
527
+ const txid = value.substring(0, dotIndex);
528
+ const outputIndex = Number.parseInt(value.substring(dotIndex + 1));
529
+ if (Number.isNaN(outputIndex)) {
530
+ return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
531
+ }
532
+ await this.banService.banOutpoint(txid, outputIndex, reason);
533
+ await this.evictFromServices(engine, txid, outputIndex);
534
+ return res.status(200).json({
535
+ status: 'success',
536
+ message: `Outpoint "${value}" banned and evicted from lookup services.`
537
+ });
538
+ }
539
+ /** Evict an output from a specific service or all services (silent per-service errors). */
540
+ async evictFromServices(engine, txid, outputIndex, service) {
541
+ if (typeof service === 'string') {
542
+ const svc = engine.lookupServices[service];
543
+ if (svc !== undefined)
544
+ await svc.outputEvicted(txid, outputIndex);
545
+ return;
546
+ }
547
+ for (const svc of Object.values(engine.lookupServices)) {
548
+ try {
549
+ await svc.outputEvicted(txid, outputIndex);
550
+ }
551
+ catch { /* best-effort */ }
552
+ }
553
+ }
554
+ /** Look up the domain of an outpoint from SHIP or SLAP records. */
555
+ async lookupDomainForOutpoint(txid, outputIndex) {
556
+ var _a;
557
+ const db = this.ensureMongo();
558
+ const [shipRecord, slapRecord] = await Promise.all([
559
+ db.collection('shipRecords').findOne({ txid, outputIndex }),
560
+ db.collection('slapRecords').findOne({ txid, outputIndex })
561
+ ]);
562
+ return ((_a = shipRecord === null || shipRecord === void 0 ? void 0 : shipRecord.domain) !== null && _a !== void 0 ? _a : slapRecord === null || slapRecord === void 0 ? void 0 : slapRecord.domain);
563
+ }
564
+ /** Ban a domain and delete all SHIP/SLAP records for it. */
565
+ async banDomainAndRemoveRecords(domain, reason) {
566
+ await this.banService.banDomain(domain, reason);
567
+ const db = this.ensureMongo();
568
+ await Promise.all([
569
+ db.collection('shipRecords').deleteMany({ domain }),
570
+ db.collection('slapRecords').deleteMany({ domain })
571
+ ]);
572
+ }
573
+ async runHealthCheck(definition) {
574
+ var _a, _b;
575
+ const startedAt = Date.now();
576
+ try {
577
+ const result = ((_a = (await Promise.race([
578
+ Promise.resolve(definition.handler()),
579
+ new Promise((_, reject) => {
580
+ setTimeout(() => reject(new Error(`Timed out after ${this.healthConfig.timeoutMs}ms`)), this.healthConfig.timeoutMs);
581
+ })
582
+ ]))) !== null && _a !== void 0 ? _a : {});
583
+ return {
584
+ name: definition.name,
585
+ scope: definition.scope,
586
+ critical: definition.critical,
587
+ status: (_b = result.status) !== null && _b !== void 0 ? _b : 'ok',
588
+ message: result.message,
589
+ details: result.details,
590
+ durationMs: Date.now() - startedAt
591
+ };
592
+ }
593
+ catch (error) {
594
+ return {
595
+ name: definition.name,
596
+ scope: definition.scope,
597
+ critical: definition.critical,
598
+ status: 'error',
599
+ message: error instanceof Error ? error.message : 'Unknown health-check error',
600
+ durationMs: Date.now() - startedAt
601
+ };
602
+ }
603
+ }
604
+ async collectHealthReport(mode) {
605
+ var _a, _b, _c;
606
+ const definitions = [
607
+ {
608
+ name: 'process',
609
+ scope: 'live',
610
+ critical: true,
611
+ handler: async () => ({
612
+ status: 'ok',
613
+ details: {
614
+ listening: this.isListening
615
+ }
616
+ })
617
+ },
618
+ {
619
+ name: 'engine',
620
+ scope: 'ready',
621
+ critical: true,
622
+ handler: async () => {
623
+ if (this.engine === undefined) {
624
+ throw new TypeError('Overlay engine is not configured');
625
+ }
626
+ return {
627
+ status: 'ok',
628
+ details: {
629
+ topicManagers: Object.keys(this.managers),
630
+ lookupServices: Object.keys(this.services)
631
+ }
632
+ };
633
+ }
634
+ },
635
+ {
636
+ name: 'knex',
637
+ scope: 'ready',
638
+ critical: true,
639
+ handler: async () => {
640
+ var _a, _b, _c;
641
+ if (this.knex === undefined) {
642
+ throw new TypeError('Knex is not configured');
643
+ }
644
+ await this.knex.raw('select 1 as ok');
645
+ return {
646
+ status: 'ok',
647
+ details: {
648
+ client: (_c = (_b = (_a = this.knex.client) === null || _a === void 0 ? void 0 : _a.config) === null || _b === void 0 ? void 0 : _b.client) !== null && _c !== void 0 ? _c : 'unknown'
649
+ }
650
+ };
651
+ }
652
+ },
653
+ {
654
+ name: 'mongo',
655
+ scope: 'ready',
656
+ critical: true,
657
+ handler: async () => {
658
+ if (this.mongoDb === undefined) {
659
+ throw new TypeError('MongoDB is not configured');
660
+ }
661
+ await this.mongoDb.command({ ping: 1 });
662
+ return {
663
+ status: 'ok',
664
+ details: {
665
+ database: this.mongoDb.databaseName
666
+ }
667
+ };
668
+ }
669
+ }
670
+ ];
671
+ for (const check of this.healthChecks) {
672
+ definitions.push({
673
+ name: check.name,
674
+ scope: (_a = check.scope) !== null && _a !== void 0 ? _a : 'ready',
675
+ critical: (_b = check.critical) !== null && _b !== void 0 ? _b : false,
676
+ handler: check.handler
677
+ });
678
+ }
679
+ const filteredDefinitions = definitions.filter((definition) => {
680
+ if (mode === 'full') {
681
+ return true;
682
+ }
683
+ return definition.scope === mode;
684
+ });
685
+ const checks = await Promise.all(filteredDefinitions.map(async (definition) => await this.runHealthCheck(definition)));
686
+ const liveChecks = checks.filter(check => check.scope === 'live');
687
+ const readyChecks = checks.filter(check => check.scope === 'ready');
688
+ const live = liveChecks.every(check => !check.critical || check.status === 'ok');
689
+ const ready = readyChecks.every(check => !check.critical || check.status === 'ok');
690
+ let status = 'ok';
691
+ if (!live || !ready || checks.some(check => check.critical && check.status === 'error')) {
692
+ status = 'error';
693
+ }
694
+ else if (checks.some(check => check.status !== 'ok')) {
695
+ status = 'degraded';
696
+ }
697
+ const context = typeof this.healthConfig.contextProvider === 'function'
698
+ ? await this.healthConfig.contextProvider()
699
+ : undefined;
700
+ const report = {
701
+ status,
702
+ live,
703
+ ready,
704
+ service: {
705
+ name: this.name,
706
+ advertisableFQDN: this.advertisableFQDN,
707
+ port: this.port,
708
+ network: this.network,
709
+ startedAt: (_c = this.startTime) === null || _c === void 0 ? void 0 : _c.toISOString(),
710
+ uptimeMs: this.startTime === undefined ? 0 : Date.now() - this.startTime.getTime(),
711
+ topicManagerCount: Object.keys(this.managers).length,
712
+ lookupServiceCount: Object.keys(this.services).length
713
+ },
714
+ checks: this.healthConfig.includeDetails
715
+ ? checks
716
+ : checks.map(({ details, ...check }) => check),
717
+ context
718
+ };
719
+ return report;
720
+ }
504
721
  /**
505
722
  * Starts the Express server.
506
723
  * Sets up routes and begins listening on the configured port.
@@ -519,7 +736,7 @@ class OverlayExpress {
519
736
  this.logger.log(chalk_1.default.magenta.bold(`Incoming Request: ${String(req.method)} ${String(req.originalUrl)}`));
520
737
  // Pretty-print headers
521
738
  this.logger.log(chalk_1.default.cyan('Headers:'));
522
- this.logger.log(util_1.default.inspect(req.headers, { colors: true, depth: null }));
739
+ this.logger.log(node_util_1.default.inspect(req.headers, { colors: true, depth: null }));
523
740
  // Handle request body
524
741
  if (req.body != null && Object.keys(req.body).length > 0) {
525
742
  let bodyContent;
@@ -553,7 +770,7 @@ class OverlayExpress {
553
770
  const duration = Date.now() - startTime;
554
771
  this.logger.log(chalk_1.default.magenta.bold(`Outgoing Response: ${String(req.method)} ${String(req.originalUrl)} - Status: ${String(res.statusCode)} - Duration: ${String(duration)}ms`));
555
772
  this.logger.log(chalk_1.default.cyan('Response Headers:'));
556
- this.logger.log(util_1.default.inspect(res.getHeaders(), { colors: true, depth: null }));
773
+ this.logger.log(node_util_1.default.inspect(res.getHeaders(), { colors: true, depth: null }));
557
774
  // Handle response body
558
775
  if (responseBody != null) {
559
776
  let bodyContent;
@@ -604,9 +821,42 @@ class OverlayExpress {
604
821
  adminIdentityKey: this.adminIdentityKey
605
822
  }));
606
823
  });
607
- // Serve a health check endpoint
824
+ // Serve health check endpoints
825
+ this.app.get('/health/live', (_, res) => {
826
+ ;
827
+ (async () => {
828
+ const report = await this.collectHealthReport('live');
829
+ return res.status(report.live ? 200 : 503).json(report);
830
+ })().catch((error) => {
831
+ res.status(500).json({
832
+ status: 'error',
833
+ message: error instanceof Error ? error.message : 'Unexpected error'
834
+ });
835
+ });
836
+ });
837
+ this.app.get('/health/ready', (_, res) => {
838
+ ;
839
+ (async () => {
840
+ const report = await this.collectHealthReport('ready');
841
+ return res.status(report.ready ? 200 : 503).json(report);
842
+ })().catch((error) => {
843
+ res.status(500).json({
844
+ status: 'error',
845
+ message: error instanceof Error ? error.message : 'Unexpected error'
846
+ });
847
+ });
848
+ });
608
849
  this.app.get('/health', (_, res) => {
609
- res.status(200).json({ status: 'ok' });
850
+ ;
851
+ (async () => {
852
+ const report = await this.collectHealthReport('full');
853
+ return res.status(report.ready ? 200 : 503).json(report);
854
+ })().catch((error) => {
855
+ res.status(500).json({
856
+ status: 'error',
857
+ message: error instanceof Error ? error.message : 'Unexpected error'
858
+ });
859
+ });
610
860
  });
611
861
  // List hosted topic managers and lookup services
612
862
  this.app.get('/listTopicManagers', (_, res) => {
@@ -703,7 +953,7 @@ class OverlayExpress {
703
953
  const topicsHeader = req.headers['x-topics'];
704
954
  const includesOffChain = req.headers['x-includes-off-chain-values'] === 'true';
705
955
  if (typeof topicsHeader !== 'string') {
706
- throw new Error('Missing x-topics header');
956
+ throw new TypeError('Missing x-topics header');
707
957
  }
708
958
  const topics = JSON.parse(topicsHeader);
709
959
  let offChainValues;
@@ -965,7 +1215,7 @@ class OverlayExpress {
965
1215
  data: {
966
1216
  nodeName: this.name,
967
1217
  network: this.network,
968
- uptime: this.startTime !== undefined ? Date.now() - this.startTime.getTime() : 0,
1218
+ uptime: this.startTime != null ? Date.now() - this.startTime.getTime() : 0,
969
1219
  startedAt: (_c = this.startTime) === null || _c === void 0 ? void 0 : _c.toISOString(),
970
1220
  shipRecordCount: shipCount,
971
1221
  slapRecordCount: slapCount,
@@ -998,9 +1248,9 @@ class OverlayExpress {
998
1248
  const db = this.ensureMongo();
999
1249
  const collection = db.collection('shipRecords');
1000
1250
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1001
- const rawPage = parseInt(req.query.page, 10);
1251
+ const rawPage = Number.parseInt(req.query.page, 10);
1002
1252
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1003
- const rawLimit = parseInt(req.query.limit, 10);
1253
+ const rawLimit = Number.parseInt(req.query.limit, 10);
1004
1254
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1005
1255
  const skip = (page - 1) * limit;
1006
1256
  const query = {};
@@ -1041,9 +1291,9 @@ class OverlayExpress {
1041
1291
  const db = this.ensureMongo();
1042
1292
  const collection = db.collection('slapRecords');
1043
1293
  const search = typeof req.query.search === 'string' ? req.query.search : undefined;
1044
- const rawPage = parseInt(req.query.page, 10);
1294
+ const rawPage = Number.parseInt(req.query.page, 10);
1045
1295
  const page = Math.max(1, Number.isNaN(rawPage) ? 1 : rawPage);
1046
- const rawLimit = parseInt(req.query.limit, 10);
1296
+ const rawLimit = Number.parseInt(req.query.limit, 10);
1047
1297
  const limit = Math.min(200, Math.max(1, Number.isNaN(rawLimit) ? 50 : rawLimit));
1048
1298
  const skip = (page - 1) * limit;
1049
1299
  const query = {};
@@ -1117,45 +1367,9 @@ class OverlayExpress {
1117
1367
  return res.status(400).json({ status: 'error', message: 'value is required' });
1118
1368
  }
1119
1369
  if (type === 'domain') {
1120
- await this.banService.banDomain(value, reason);
1121
- // Also remove any existing records for this domain from SHIP and SLAP
1122
- const db = this.ensureMongo();
1123
- const [shipDeleted, slapDeleted] = await Promise.all([
1124
- db.collection('shipRecords').deleteMany({ domain: value }),
1125
- db.collection('slapRecords').deleteMany({ domain: value })
1126
- ]);
1127
- return res.status(200).json({
1128
- status: 'success',
1129
- message: `Domain "${value}" banned. Removed ${shipDeleted.deletedCount} SHIP and ${slapDeleted.deletedCount} SLAP records.`
1130
- });
1131
- }
1132
- else {
1133
- // Parse outpoint: "txid.outputIndex"
1134
- const dotIndex = value.lastIndexOf('.');
1135
- if (dotIndex === -1) {
1136
- return res.status(400).json({ status: 'error', message: 'Outpoint format must be "txid.outputIndex"' });
1137
- }
1138
- const txid = value.substring(0, dotIndex);
1139
- const outputIndex = parseInt(value.substring(dotIndex + 1));
1140
- if (isNaN(outputIndex)) {
1141
- return res.status(400).json({ status: 'error', message: 'Invalid outputIndex in outpoint' });
1142
- }
1143
- await this.banService.banOutpoint(txid, outputIndex, reason);
1144
- // Also evict from lookup services
1145
- const services = Object.values(engine.lookupServices);
1146
- for (const service of services) {
1147
- try {
1148
- await service.outputEvicted(txid, outputIndex);
1149
- }
1150
- catch {
1151
- continue;
1152
- }
1153
- }
1154
- return res.status(200).json({
1155
- status: 'success',
1156
- message: `Outpoint "${value}" banned and evicted from lookup services.`
1157
- });
1370
+ return await this.handleBanDomain(res, value, reason);
1158
1371
  }
1372
+ return await this.handleBanOutpoint(res, engine, value, reason);
1159
1373
  }
1160
1374
  catch (error) {
1161
1375
  return res.status(400).json({
@@ -1228,55 +1442,30 @@ class OverlayExpress {
1228
1442
  this.app.post('/admin/remove-token', checkAdminAuth, (req, res) => {
1229
1443
  ;
1230
1444
  (async () => {
1231
- var _a;
1232
1445
  try {
1233
1446
  const { txid, outputIndex, service, ban, banDomain: shouldBanDomain } = req.body;
1234
1447
  if (typeof txid !== 'string' || typeof outputIndex !== 'number') {
1235
1448
  return res.status(400).json({ status: 'error', message: 'txid (string) and outputIndex (number) are required' });
1236
1449
  }
1237
- // Get the domain before removing (for ban option)
1450
+ // Look up domain before eviction if needed for banning
1238
1451
  let removedDomain;
1239
1452
  if (shouldBanDomain === true || ban === true) {
1240
- const db = this.ensureMongo();
1241
- const shipRecord = await db.collection('shipRecords').findOne({ txid, outputIndex });
1242
- const slapRecord = await db.collection('slapRecords').findOne({ txid, outputIndex });
1243
- removedDomain = ((_a = shipRecord === null || shipRecord === void 0 ? void 0 : shipRecord.domain) !== null && _a !== void 0 ? _a : slapRecord === null || slapRecord === void 0 ? void 0 : slapRecord.domain);
1244
- }
1245
- // Evict from specified service or all services
1246
- if (typeof service === 'string') {
1247
- const svc = engine.lookupServices[service];
1248
- if (svc !== undefined) {
1249
- await svc.outputEvicted(txid, outputIndex);
1250
- }
1453
+ removedDomain = await this.lookupDomainForOutpoint(txid, outputIndex);
1251
1454
  }
1252
- else {
1253
- const services = Object.values(engine.lookupServices);
1254
- for (const svc of services) {
1255
- try {
1256
- await svc.outputEvicted(txid, outputIndex);
1257
- }
1258
- catch {
1259
- continue;
1260
- }
1261
- }
1262
- }
1263
- // Ban the outpoint if requested
1455
+ await this.evictFromServices(engine, txid, outputIndex, service);
1264
1456
  if (ban === true && this.banService !== undefined) {
1265
1457
  await this.banService.banOutpoint(txid, outputIndex, 'Manually removed by admin', removedDomain);
1266
1458
  }
1267
- // Ban the domain if requested
1268
1459
  if (shouldBanDomain === true && typeof removedDomain === 'string' && this.banService !== undefined) {
1269
- await this.banService.banDomain(removedDomain, 'Domain banned by admin via token removal');
1270
- // Remove all records for this domain
1271
- const banDb = this.ensureMongo();
1272
- await Promise.all([
1273
- banDb.collection('shipRecords').deleteMany({ domain: removedDomain }),
1274
- banDb.collection('slapRecords').deleteMany({ domain: removedDomain })
1275
- ]);
1460
+ await this.banDomainAndRemoveRecords(removedDomain, 'Domain banned by admin via token removal');
1276
1461
  }
1462
+ const banMsg = ban === true ? ' Outpoint banned.' : '';
1463
+ const domainMsg = shouldBanDomain === true && typeof removedDomain === 'string'
1464
+ ? ` Domain "${removedDomain}" banned.`
1465
+ : '';
1277
1466
  return res.status(200).json({
1278
1467
  status: 'success',
1279
- message: `Token ${txid}.${outputIndex} removed.${ban === true ? ' Outpoint banned.' : ''}${shouldBanDomain === true && typeof removedDomain === 'string' ? ` Domain "${removedDomain}" banned.` : ''}`
1468
+ message: `Token ${txid}.${outputIndex} removed.${banMsg}${domainMsg}`
1280
1469
  });
1281
1470
  }
1282
1471
  catch (error) {
@@ -1350,9 +1539,9 @@ class OverlayExpress {
1350
1539
  }
1351
1540
  else {
1352
1541
  const services = Object.values(engine.lookupServices);
1353
- for (let i = 0; i < services.length; i++) {
1542
+ for (const service of services) {
1354
1543
  try {
1355
- await services[i].outputEvicted(req.body.txid, req.body.outputIndex);
1544
+ await service.outputEvicted(req.body.txid, req.body.outputIndex);
1356
1545
  }
1357
1546
  catch {
1358
1547
  continue;
@@ -1448,6 +1637,7 @@ class OverlayExpress {
1448
1637
  }
1449
1638
  // Start listening on the configured port
1450
1639
  this.app.listen(this.port, () => {
1640
+ this.isListening = true;
1451
1641
  this.logger.log(chalk_1.default.green.bold(`${this.name} is ready and listening on local port ${this.port}`));
1452
1642
  });
1453
1643
  }