/// <reference types="node" />
/// <reference types="node" />
import * as http2 from "http2";
export interface Http2SessionOptions {
    /**
     * The interval to send PING frames to keep a connection alive. The interval
     * is reset whenever a stream receives data. If a PING frame is not responded
     * to within pingTimeoutMs, the connection and all open streams close.
     *
     * By default, no PING frames are sent. If a value is provided, PING frames
     * are sent only for connections that have open streams, unless
     * pingIdleConnections is enabled.
     *
     * Sensible values can be between 10 seconds and 2 hours, depending on your
     * infrastructure.
     *
     * This option is equivalent to GRPC_ARG_KEEPALIVE_TIME_MS in gRPC Core.
     */
    pingIntervalMs?: number;
    /**
     * Enable PING frames for connections that are have no open streams.
     * This option is only effective if a value for pingIntervalMs is provided.
     *
     * Note that it may not be necessary to enable this option. If a request is
     * made on a connection that has not been used for longer than pingIntervalMs,
     * a PING frame is sent to verify that the connection is still alive, and a
     * new connection is opened transparently if necessary.
     *
     * Defaults to false.
     *
     * This option is equivalent to GRPC_ARG_KEEPALIVE_PERMIT_WITHOUT_CALLS in
     * gRPC Core.
     */
    pingIdleConnection?: boolean;
    /**
     * Timeout for PING frames. If a PING is not answered within this time, the
     * connection is considered dead.
     *
     * Defaults to 15 seconds. This option is only used if a value for
     * pingIntervalMs is provided.
     *
     * This option is equivalent to GRPC_ARG_KEEPALIVE_TIME_MS in gRPC Core.
     */
    pingTimeoutMs?: number;
    /**
     * Automatically close a connection if the time since the last request stream
     * exceeds this value.
     *
     * Defaults to 15 minutes.
     *
     * This option is equivalent to GRPC_ARG_CLIENT_IDLE_TIMEOUT_MS of gRPC core.
     */
    idleConnectionTimeoutMs?: number;
}
/**
 * Manage an HTTP/2 connection and keep it alive with PING frames.
 *
 * The logic is based on "Basic Keepalive" described in
 * https://github.com/grpc/proposal/blob/0ba0c1905050525f9b0aee46f3f23c8e1e515489/A8-client-side-keepalive.md#basic-keepalive
 * as well as the client channel arguments described in
 * https://github.com/grpc/grpc/blob/8e137e524a1b1da7bbf4603662876d5719563b57/doc/keepalive.md
 *
 * Usually, the managers tracks exactly one connection, but if a connection
 * receives a GOAWAY frame with NO_ERROR, the connection is maintained until
 * all streams have finished, and new requests will open a new connection.
 */
export declare class Http2SessionManager {
    /**
     * The host this session manager connect to.
     */
    authority: string;
    /**
     * The current state of the connection:
     *
     * - "closed"
     *   The connection is closed, or no connection has been opened yet.
     * - connecting
     *   Currently establishing a connection.
     *
     * - "open"
     *   A connection is open and has open streams. PING frames are sent every
     *   pingIntervalMs, unless a stream received data.
     *   If a PING frame is not responded to within pingTimeoutMs, the connection
     *   and all open streams close.
     *
     * - "idle"
     *   A connection is open, but it does not have any open streams.
     *   If pingIdleConnection is enabled, PING frames are used to keep the
     *   connection alive, similar to an "open" connection.
     *   If a connection is idle for longer than idleConnectionTimeoutMs, it closes.
     *   If a request is made on an idle connection that has not been used for
     *   longer than pingIntervalMs, the connection is verified.
     *
     * - "verifying"
     *   Verifying a connection after a long period of inactivity before issuing a
     *   request. A PING frame is sent, and if it times out within pingTimeoutMs, a
     *   new connection is opened.
     *
     * - "error"
     *   The connection is closed because of a transient error. A connection
     *   may have failed to reach the host, or the connection may have died,
     *   or it may have been aborted.
     */
    state(): "closed" | "connecting" | "open" | "idle" | "verifying" | "error";
    /**
     * Returns the error object if the connection is in the "error" state,
     * `undefined` otherwise.
     */
    error(): unknown;
    private s;
    private shuttingDown;
    private readonly http2SessionOptions;
    private readonly options;
    constructor(authority: URL | string, pingOptions?: Http2SessionOptions, http2SessionOptions?: http2.ClientSessionOptions | http2.SecureClientSessionOptions);
    /**
     * Open a connection if none exists, verify an existing connection if
     * necessary.
     */
    connect(): Promise<"open" | "idle" | "error">;
    /**
     * Issue a request.
     *
     * This method automatically opens a connection if none exists, and verifies
     * an existing connection if necessary. It calls http2.ClientHttp2Session.request(),
     * and keeps track of all open http2.ClientHttp2Stream.
     *
     * Clients must call notifyResponseByteRead() whenever they successfully read
     * data from the http2.ClientHttp2Stream.
     */
    request(method: string, path: string, headers: http2.OutgoingHttpHeaders, options: Omit<http2.ClientSessionRequestOptions, "signal">): Promise<http2.ClientHttp2Stream>;
    /**
     * Notify the manager of a successful read from a http2.ClientHttp2Stream.
     *
     * Clients must call this function whenever they successfully read data from
     * a http2.ClientHttp2Stream obtained from request(). This informs the
     * keep-alive logic that the connection is alive, and prevents it from sending
     * unnecessary PING frames.
     */
    notifyResponseByteRead(stream: http2.ClientHttp2Stream): void;
    /**
     * If there is an open connection, close it. This also closes any open streams.
     */
    abort(reason?: Error): void;
    private gotoReady;
    private setState;
}
interface StateCommon {
    /**
     * A unique string that serves as a discriminator for each state type.
     */
    readonly t: string;
    /**
     * Abort this state, cancelling any work, and terminating any connection.
     */
    abort?: (reason?: Error) => void;
    /**
     * Called when the manager is leaving this state.
     */
    onExitState?: () => void;
}
/**
 * The manager is currently establishing a connection.
 */
interface StateConnecting extends StateCommon {
    readonly t: "connecting";
    /**
     * A promise for the new connection that resolves if the connection was
     * established, but rejects if the connection failed or the state was aborted.
     */
    readonly conn: Promise<http2.ClientHttp2Session>;
}
interface StateVerifying extends StateCommon {
    readonly t: "verifying";
    /**
     * The existing connection (StateReady) if it has been successfully verified
     * with a PING frame. A new connection otherwise.
     */
    readonly verified: Promise<StateReady | StateConnecting>;
}
export declare function verify(stateReady: StateReady, options: Required<Http2SessionOptions>, authority: string, http2SessionOptions: http2.ClientSessionOptions | http2.SecureClientSessionOptions | undefined): StateVerifying;
interface StateReady extends StateCommon {
    readonly t: "ready";
    /**
     * The open connection that is ready to use, but might require verification.
     */
    readonly conn: http2.ClientHttp2Session;
    /**
     * Returns the number of open streams.
     */
    streamCount(): number;
    /**
     * Returns true if the connection should be verified before use, because it
     * has not received a PING response or response bytes for longer than
     * pingIntervalMs.
     */
    requiresVerify(): boolean;
    /**
     * This connection has received a GOAWAY frame.
     *
     * If the error code is NO_ERROR (0x0), previously established streams are
     * allowed to finish. Otherwise, they error.
     *
     * No new streams may be opened on this connection, and the connection is
     * closed as soon as possible. Until then, keep-alive continues for the
     * connection.
     */
    isShuttingDown(): boolean;
    /**
     * Register a stream, so that we can keep track of open streams, and keep the
     * connection alive with PING frames while streams are open.
     */
    registerRequest(stream: http2.ClientHttp2Stream): void;
    /**
     * Notify the keep-alive logic about received response bytes. A received byte
     * is proof that the connection is alive, resets the interval for PING frames.
     */
    responseByteRead(stream: http2.ClientHttp2Stream): void;
    /**
     * Send a PING frame, resolve to true if it is responded to in time, resolve
     * to false otherwise (and closes the connection).
     */
    ping(): Promise<boolean>;
    /**
     * Called when the connection closes without error.
     */
    onClose: (() => void) | undefined;
    /**
     * Called when the connection closes with an error.
     */
    onError: ((err: Error) => void) | undefined;
}
export {};