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

BSV Blockchain Overlay Express

export interface OverlayMonitorLogger {
    log: (...args: any[]) => void;
    warn: (...args: any[]) => void;
    error: (...args: any[]) => void;
}
export interface OverlayLookupProbe {
    name?: string;
    service: string;
    query: unknown;
    maxOutputs?: number;
}
export interface OverlayAnchorProbe {
    name?: string;
    topic: string;
    expectedTac?: string;
    expectedBlockHeight?: number;
    currentHeight?: number;
    maxTipLagBlocks?: number;
}
export interface OverlayMaintenanceConfig {
    adminToken?: string;
    headers?: Record<string, string>;
    maintainUnproven?: boolean | {
        topics?: string[];
        thresholdBlocks?: number;
    };
    startBASMSync?: boolean;
    janitor?: boolean;
}
export interface OverlayMonitorTarget {
    name: string;
    baseUrl: string;
    probes: OverlayLookupProbe[];
    anchorProbes?: OverlayAnchorProbe[];
    maintenance?: OverlayMaintenanceConfig;
    headers?: Record<string, string>;
}
export interface OverlayMonitorThresholds {
    responseBytes?: number;
    beefBytes?: number;
    txsWithoutProof?: number;
    requireSubjectProof?: boolean;
    anchorTipLagBlocks?: number;
    expiredUnprovenCount?: number;
}
export interface OverlayMonitorConfig {
    targets: OverlayMonitorTarget[];
    thresholds?: OverlayMonitorThresholds;
    intervalMs?: number;
    /** Per-probe request timeout in milliseconds. Defaults to 30000. */
    timeoutMs?: number;
    fetchImpl?: typeof fetch;
    logger?: OverlayMonitorLogger;
    onReport?: (report: OverlayMonitorReport) => Promise<void> | void;
    now?: () => Date;
}
export interface OverlayMonitorWarning {
    code: 'response-bytes' | 'beef-bytes' | 'txs-without-proof' | 'subject-proof-missing' | 'anchor-tip-mismatch' | 'anchor-stale-height' | 'expired-unproven-state';
    message: string;
    value: number | boolean;
    threshold?: number | boolean;
    outputIndex?: number;
    txid?: string;
}
export interface OverlayLookupOutputSummary {
    outputIndex: number;
    txid?: string;
    beefBytes: number;
    txCount?: number;
    proofCount?: number;
    txsWithoutProof?: number;
    subjectHasProof?: boolean;
    subjectRawTxBytes?: number;
    currentToSubjectRawRatio?: number;
    contextBytes?: number;
    error?: string;
}
export interface OverlayLookupProbeResult {
    target: string;
    url: string;
    probe: string;
    service: string;
    status: number;
    ok: boolean;
    responseBytes: number;
    outputCount: number;
    analyzedOutputCount: number;
    outputs: OverlayLookupOutputSummary[];
    warnings: OverlayMonitorWarning[];
    durationMs: number;
    error?: string;
}
export interface OverlayAnchorProbeResult {
    target: string;
    url: string;
    probe: string;
    topic: string;
    status: number;
    ok: boolean;
    responseBytes: number;
    blockHeight?: number;
    tac?: string;
    warnings: OverlayMonitorWarning[];
    durationMs: number;
    error?: string;
}
export interface OverlayMaintenanceResult {
    target: string;
    url: string;
    operation: 'maintain-unproven' | 'start-basm-sync' | 'janitor';
    topic?: string;
    status: number;
    ok: boolean;
    responseBytes: number;
    durationMs: number;
    data?: unknown;
    error?: string;
}
export interface OverlayMonitorReport {
    startedAt: Date;
    completedAt: Date;
    durationMs: number;
    results: OverlayLookupProbeResult[];
    anchorResults: OverlayAnchorProbeResult[];
    maintenanceResults: OverlayMaintenanceResult[];
    summary: {
        targetCount: number;
        probeCount: number;
        anchorProbeCount: number;
        maintenanceActionCount: number;
        failedProbeCount: number;
        failedMaintenanceActionCount: number;
        responseBytes: number;
        outputCount: number;
        analyzedOutputCount: number;
        outputsMissingSubjectProof: number;
        warningCount: number;
    };
}
interface AnalyzeOptions {
    target: string;
    url: string;
    probe: string;
    service: string;
    status: number;
    ok: boolean;
    responseBody: unknown;
    responseBytes: number;
    durationMs: number;
    thresholds?: OverlayMonitorThresholds;
    maxOutputs?: number;
    error?: string;
}
/**
 * OverlayMonitor runs generic Overlay Express /lookup probes and reports response
 * size plus BEEF proof shape. It is intended for long-running monitor workers or
 * scheduled jobs, analogous to a storage monitor but scoped to overlay health.
 */
export declare class OverlayMonitor {
    private readonly targets;
    private readonly thresholds;
    private readonly fetchImpl;
    private readonly logger;
    private readonly onReport?;
    private readonly now;
    private readonly intervalMs?;
    private readonly timeoutMs;
    private timer?;
    private running;
    constructor(config: OverlayMonitorConfig);
    runOnce(): Promise<OverlayMonitorReport>;
    start(): void;
    stop(): void;
    private runProbe;
    private runAnchorProbe;
    private runMaintenance;
    private runMaintenanceRequest;
}
export declare function analyzeOverlayAnchorTip(options: {
    target: string;
    url: string;
    probe: string;
    topic: string;
    status: number;
    ok: boolean;
    responseBody: Record<string, unknown>;
    responseBytes: number;
    durationMs: number;
    thresholds?: OverlayMonitorThresholds;
    expectedTac?: string;
    expectedBlockHeight?: number;
    currentHeight?: number;
    maxTipLagBlocks?: number;
}): OverlayAnchorProbeResult;
export declare function analyzeOverlayLookupResponse(options: AnalyzeOptions): OverlayLookupProbeResult;
export {};
//# sourceMappingURL=OverlayMonitor.d.ts.map