@bsv/overlay-express/dist/types/src/JanitorService.d.ts

BSV Blockchain Overlay Express

import { Db } from 'mongodb';
import { BanService } from './BanService.js';
/**
 * Configuration for the Janitor Service
 */
export interface JanitorConfig {
    mongoDb: Db;
    logger?: typeof console;
    requestTimeoutMs?: number;
    hostDownRevokeScore?: number;
    /** Optional BanService for persisting bans when hosts are removed */
    banService?: BanService;
    /** Whether to auto-ban domains when they exceed the down threshold (default: true) */
    autoBanOnRemoval?: boolean;
}
/**
 * Health status of a single record
 */
export interface HostHealthResult {
    txid: string;
    outputIndex: number;
    domain: string;
    topic?: string;
    service?: string;
    identityKey?: string;
    createdAt?: Date;
    healthy: boolean;
    downCount: number;
    responseTimeMs?: number;
    statusCode?: number;
    error?: string;
}
/**
 * Summary report from a janitor run
 */
export interface JanitorReport {
    startedAt: Date;
    completedAt: Date;
    durationMs: number;
    shipResults: HostHealthResult[];
    slapResults: HostHealthResult[];
    summary: {
        totalChecked: number;
        healthy: number;
        unhealthy: number;
        removed: number;
        banned: number;
    };
}
/**
 * JanitorService runs health checks on SHIP and SLAP outputs.
 * It validates domain names and checks /health endpoints to ensure services are operational.
 *
 * When a service is down, it increments a "down" counter. When healthy, it decrements.
 * If the down counter reaches hostDownRevokeScore, the output is deleted and optionally
 * the domain is added to the persistent ban list to prevent GASP re-sync.
 */
export declare class JanitorService {
    private readonly mongoDb;
    private readonly logger;
    private readonly requestTimeoutMs;
    private readonly hostDownRevokeScore;
    private readonly banService?;
    private readonly autoBanOnRemoval;
    constructor(config: JanitorConfig);
    /**
     * Runs a full pass of health checks on all SHIP and SLAP outputs.
     * Returns a detailed report of the results.
     */
    run(): Promise<JanitorReport>;
    /**
     * Checks a single URL's health endpoint. Used by the admin dashboard for on-demand checks.
     */
    checkHost(url: string): Promise<{
        healthy: boolean;
        responseTimeMs: number;
        statusCode?: number;
        error?: string;
    }>;
    /**
     * Gets health status for all records without modifying them.
     * Used by the dashboard to display current state.
     */
    getHealthStatus(): Promise<{
        ship: HostHealthResult[];
        slap: HostHealthResult[];
    }>;
    /**
     * Checks all outputs for a specific collection and returns results.
     */
    private checkTopicOutputs;
    /**
     * Checks a single output for health and returns the result.
     */
    private checkOutput;
    /**
     * Extracts URL from output record
     */
    private extractURLFromOutput;
    /**
     * Validates if a string is a valid domain name
     */
    private isValidDomain;
    /**
     * Handles a healthy output by decrementing its down counter
     */
    private handleHealthyOutput;
    /**
     * Handles an unhealthy output by incrementing its down counter.
     * If the threshold is reached, deletes the record and optionally bans the domain.
     * Returns true if the record was removed.
     */
    private handleUnhealthyOutput;
}
//# sourceMappingURL=JanitorService.d.ts.map