@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
TypeScript
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;
}