@beignet/core/dist/server/health.d.ts

Core framework primitives for Beignet

/**
 * Health check handler
 * Health check handler for Beignet server adapters.
 */
import type { AnyPorts } from "../ports/index.js";
import type { HttpRequestLike, HttpResponseLike } from "./types.js";
/**
 * Per-dependency health detail returned by readiness checks.
 */
export interface HealthCheckDetail {
    /**
     * Whether this dependency is healthy.
     */
    ok: boolean;
    /**
     * Optional human-readable status. Avoid secrets and raw provider credentials.
     */
    message?: string;
    /**
     * Milliseconds spent running this dependency check.
     */
    durationMs?: number;
    /**
     * Optional safe metadata for operators.
     */
    metadata?: Record<string, unknown>;
}
/**
 * Health check result returned by health handlers.
 */
export interface HealthCheckResult {
    /**
     * Whether the app is healthy.
     */
    ok: boolean;
    /**
     * Optional per-dependency health details.
     */
    details?: Record<string, HealthCheckDetail>;
}
/**
 * A named dependency check run by {@link runHealthChecks}.
 */
export type HealthCheck<Ports> = (ports: Ports) => Promise<HealthCheckDetail | boolean | undefined> | HealthCheckDetail | boolean | undefined;
/**
 * Named dependency checks for an app-owned readiness endpoint.
 */
export type HealthChecks<Ports> = Record<string, HealthCheck<Ports>>;
/**
 * Options for running named dependency checks.
 */
export interface RunHealthChecksOptions {
    /**
     * Maximum time to wait for each dependency check.
     *
     * Defaults to 2000ms.
     */
    timeoutMs?: number;
    /**
     * Include thrown error messages in dependency details.
     *
     * Defaults to true. Set false in production responses when provider errors
     * may include sensitive details.
     */
    includeErrorDetails?: boolean;
}
/**
 * Health check configuration.
 */
export interface HealthConfig<Ports> {
    /** Enable health endpoint (default: false) */
    enabled?: boolean;
    /**
     * Suggested path for the health endpoint (e.g., "/api/health").
     * NOTE: This field is for documentation/metadata only and does not control routing.
     * You must manually wire the healthHandler to your desired route.
     */
    suggestedPath?: string;
    /** Custom health check function */
    check?: (ports: Ports) => Promise<HealthCheckResult>;
    /** Named dependency checks for an app-owned readiness endpoint */
    checks?: HealthChecks<Ports>;
    /** Per-check timeout for named dependency checks */
    timeoutMs?: number;
}
/**
 * Application environment.
 */
export type AppEnvironment = "development" | "production" | "test";
/**
 * Run named dependency health checks in parallel and aggregate the result.
 *
 * This is intended for app-owned readiness endpoints. Checks should be cheap,
 * bounded, non-mutating probes such as `SELECT 1`, Redis `PING`, or provider
 * health endpoints. Do not start workers, drains, migrations, or polling loops
 * from readiness checks.
 */
export declare function runHealthChecks<Ports extends AnyPorts>(ports: Ports, checks: HealthChecks<Ports>, options?: RunHealthChecksOptions): Promise<HealthCheckResult>;
/**
 * Create a framework-neutral health check handler.
 *
 * The returned handler reports 200 when healthy and 503 when unhealthy. Thrown
 * health check errors include details in development/test and use a generic
 * message in production.
 */
export declare function createHealthHandler<Ports extends AnyPorts>(ports: Ports, healthConfig: HealthConfig<Ports> | undefined, env: AppEnvironment): (req: HttpRequestLike) => Promise<HttpResponseLike>;
//# sourceMappingURL=health.d.ts.map