kubernetes-health/dist/Health.d.ts

Helper library for implementing Kubernetes heath checks and graceful HTTP shutdown in Node applications

/// <reference types="node" />
export declare type Status = 'Pending' | 'Live' | 'Ready' | 'NotReady' | 'Terminating';
export declare type Task = () => Promise<void>;
export interface PendingTask {
    markComplete: () => void;
}
/**
 * Options for the `Health` instance
 */
export interface Options {
    /**
     * Function called to forcibly terminate the current process
     *
     * @default () => process.exit(1)
     */
    forciblyTerminate: () => void;
    /**
     * The amount of time to wait before starting to shut down. There is often a delay between when Kubernetes informs
     * the pod that it will be terminating and when all network requests to that pod have ceased, so this delay ensures
     * that in-flight requests are not rejected. Set to a number less than or equal to `0` to disable.
     *
     * @default 5
     */
    shutdownDelaySeconds: number;
    /**
     * Signals that trigger application shutdown.
     *
     * @default ['SIGTERM', 'SIGHUP', 'SIGINT']
     */
    shutdownSignals: NodeJS.Signals[];
    /**
     * The amount of time, in seconds, before the process is forcibly terminated after shutdown is initiated. Set to a
     * value less than or equal to `0` to disable.
     *
     * @default 30
     */
    terminationGracePeriodSeconds: number;
}
/** Default values for Health options, if not specified */
export declare const defaultOptions: Options;
/**
 * The `Health` class represents the health status if an application. It manages transitions between application
 * state, and automatically registers shutdown handlers to that run when the process receives a shutdown signal.
 */
export declare class Health {
    #private;
    /**
     * `true` if the application is live, `false` otherwise
     */
    get isLive(): boolean;
    /**
     * `true` if the application is ready, `false` otherwise
     */
    get isReady(): boolean;
    /**
     * The overall application status, transitions between the following status states:
     *
     * - `Pending`
     * - `Live`
     * - `Ready`
     * - `NotReady`
     * - `Terminating`
     */
    get status(): Status;
    constructor(options: Partial<Options>);
    /**
     * Add (register) a task that must complete before the application is considered live
     *
     * @param task the task to execute
     */
    beforeLive(task: Task): void;
    /**
     * Add (register) a task that must complete before the application is considered ready
     *
     * @param task the task to execute
     */
    beforeReady(task: Task): void;
    /**
     * Add (register) a task that must complete before the application terminates
     *
     * @param task the task to execute
     */
    beforeTermination(handler: Task): void;
    /**
     * Create a new pending task that must be completed before the process terminates.
     *
     * @returns a `PendingTask` that can be marked as completed
     */
    createPendingTask(): PendingTask;
    /**
     * Mark the health instance as ready
     */
    markReady(): void;
    /**
     * Mark the health instance as not ready
     */
    markNotReady(): void;
    /**
     * Signals that the process should shut down. Waits for any pending tasks and triggers all shutdown handlers.
     * If a `terminationGracePeriodSeconds` is defined, the process will be forcibly terminated after that amount
     * of time if it does not gracefully exit before then.
     */
    shutdown(): Promise<void>;
}