UNPKG

@connectrpc/connect-node

Version:

Connect is a family of libraries for building and consuming APIs on different languages and platforms, and [@connectrpc/connect](https://www.npmjs.com/package/@connectrpc/connect) brings type-safe APIs with Protobuf to TypeScript.

147 lines (146 loc) 6.12 kB
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_TIMEOUT_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; private verifying; constructor(url: 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; private verify; }