syntropylog/dist/types/http/InstrumentedHttpClient.d.ts

An instance manager with observability for Node.js applications

/**
 * @file src/http/InstrumentedHttpClient.ts
 * @description This class is the heart of the HTTP instrumentation architecture.
 * It wraps any adapter that complies with `IHttpClientAdapter` and adds a centralized
 * layer of instrumentation (logging, context, timers).
 */
import { ILogger } from '../logger';
import { IContextManager } from '../context';
import { AdapterHttpRequest, AdapterHttpResponse, IHttpClientAdapter } from './adapters/adapter.types';
import { HttpClientInstanceConfig } from '../config';
/**
 * @interface InstrumentorOptions
 * @description Configuration options for the instrumenter, which would typically be
 * sourced from the global SyntropyLog configuration for a specific client instance.
 */
export interface InstrumentorOptions {
    /** Whether to log request headers. Defaults to false. */
    logRequestHeaders?: boolean;
    /** Whether to log the request body. Defaults to false. */
    logRequestBody?: boolean;
    /** Whether to log response headers on success. Defaults to false. */
    logSuccessHeaders?: boolean;
    /** Whether to log the response body on success. Defaults to false. */
    logSuccessBody?: boolean;
    /** Specifies the log levels for different request lifecycle events. */
    logLevel?: {
        /** Log level for when a request starts. Defaults to 'info'. */
        onRequest?: 'info' | 'debug' | 'trace';
        /** Log level for when a request succeeds. Defaults to 'info'. */
        onSuccess?: 'info' | 'debug' | 'trace';
        /** Log level for when a request fails. Defaults to 'error'. */
        onError?: 'error' | 'warn' | 'fatal';
    };
}
/**
 * @class InstrumentedHttpClient
 * @description Wraps an `IHttpClientAdapter` to provide automatic logging,
 * context propagation, and timing for all HTTP requests.
 */
export declare class InstrumentedHttpClient {
    private readonly adapter;
    private readonly logger;
    private readonly contextManager;
    private readonly config;
    readonly instanceName: string;
    private readonly instrumentorOptions;
    /**
     * @constructor
     * @param {IHttpClientAdapter} adapter - The underlying HTTP client adapter (e.g., AxiosAdapter).
     * @param {ILogger} logger - The logger instance for this client.
     * @param {IContextManager} contextManager - The manager for handling asynchronous contexts.
     * @param {HttpClientInstanceConfig} config - The configuration for this specific instance.
     */
    constructor(adapter: IHttpClientAdapter, logger: ILogger, contextManager: IContextManager, config: HttpClientInstanceConfig);
    /**
     * The single public method. It executes an HTTP request through the wrapped
     * adapter, applying all instrumentation logic.
     * @template T The expected type of the response data.
     * @param {AdapterHttpRequest} request - The generic HTTP request to execute.
     * @returns {Promise<AdapterHttpResponse<T>>} A promise that resolves with the normalized response.
     * @throws {AdapterHttpError | Error} Throws the error from the adapter, which is re-thrown after being logged.
     */
    request<T>(request: AdapterHttpRequest): Promise<AdapterHttpResponse<T>>;
    /**
     * @private
     * Logs the start of an HTTP request, respecting the configured options.
     * @param {AdapterHttpRequest} request - The outgoing request.
     */
    private logRequestStart;
    /**
     * @private
     * Logs the successful completion of an HTTP request.
     * @template T
     * @param {AdapterHttpRequest} request - The original request.
     * @param {AdapterHttpResponse<T>} response - The received response.
     * @param {number} durationMs - The total duration of the request in milliseconds.
     */
    private logRequestSuccess;
    /**
     * @private
     * Logs the failure of an HTTP request.
     * @param {AdapterHttpRequest} request - The original request.
     * @param {unknown} error - The error that was thrown.
     * @param {number} durationMs - The total duration of the request until failure.
     */
    private logRequestFailure;
}