279 lines
9.6 KiB
TypeScript
279 lines
9.6 KiB
TypeScript
/**
|
|
*
|
|
* A module containing support for creating http connections and making requests on them.
|
|
*
|
|
* @packageDocumentation
|
|
* @module http
|
|
* @mergeTarget
|
|
*/
|
|
import { CommonHttpProxyOptions, HttpHeader, HttpHeaders as CommonHttpHeaders, HttpClientConnectionConnected, HttpClientConnectionError, HttpClientConnectionClosed, HttpStreamComplete, HttpStreamData, HttpStreamError } from '../common/http';
|
|
export { HttpHeader, HttpProxyAuthenticationType } from '../common/http';
|
|
import { BufferedEventEmitter } from '../common/event';
|
|
import { ClientBootstrap, InputStream, SocketOptions, TlsConnectionOptions } from './io';
|
|
/**
|
|
* A collection of HTTP headers
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpHeaders implements CommonHttpHeaders {
|
|
private headers;
|
|
/** Construct from a collection of [name, value] pairs
|
|
*
|
|
* @param headers list of HttpHeader values to seat in this object
|
|
*/
|
|
constructor(headers?: HttpHeader[]);
|
|
/**
|
|
* Fetches the total length of all headers
|
|
*
|
|
* @returns the total length of all headers
|
|
*/
|
|
get length(): number;
|
|
/**
|
|
* Add a name/value pair
|
|
* @param name The header name
|
|
* @param value The header value
|
|
*/
|
|
add(name: string, value: string): void;
|
|
/**
|
|
* Set a name/value pair, replacing any existing values for the name
|
|
* @param name - The header name
|
|
* @param value - The header value
|
|
*/
|
|
set(name: string, value: string): void;
|
|
/**
|
|
* Get the list of values for the given name
|
|
* @param name - The header name to look for
|
|
* @return List of values, or empty list if none exist
|
|
*/
|
|
get_values(name: string): string[];
|
|
/**
|
|
* Gets the first value for the given name, ignoring any additional values
|
|
* @param name - The header name to look for
|
|
* @param default_value - Value returned if no values are found for the given name
|
|
* @return The first header value, or default if no values exist
|
|
*/
|
|
get(name: string, default_value?: string): string;
|
|
/**
|
|
* Removes all values for the given name
|
|
* @param name - The header to remove all values for
|
|
*/
|
|
remove(name: string): void;
|
|
/**
|
|
* Removes a specific name/value pair
|
|
* @param name - The header name to remove
|
|
* @param value - The header value to remove
|
|
*/
|
|
remove_value(name: string, value: string): void;
|
|
/** Clears the entire header set */
|
|
clear(): void;
|
|
/**
|
|
* Iterator. Allows for:
|
|
* let headers = new HttpHeaders();
|
|
* ...
|
|
* for (const header of headers) { }
|
|
*/
|
|
[Symbol.iterator](): Generator<HttpHeader, void, unknown>;
|
|
/** @internal */
|
|
_flatten(): HttpHeader[];
|
|
}
|
|
/**
|
|
* Options used when connecting to an HTTP endpoint via a proxy
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpProxyOptions extends CommonHttpProxyOptions {
|
|
}
|
|
/**
|
|
* Represents a request to a web server from a client
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpRequest {
|
|
method: string;
|
|
path: string;
|
|
headers: HttpHeaders;
|
|
body?: InputStream | undefined;
|
|
/**
|
|
* Constructor for the HttpRequest class
|
|
*
|
|
* @param method The verb to use for the request (i.e. GET, POST, PUT, DELETE, HEAD)
|
|
* @param path The URI of the request
|
|
* @param headers Additional custom headers to send to the server
|
|
* @param body The request body, in the case of a POST or PUT request
|
|
*/
|
|
constructor(method: string, path: string, headers?: HttpHeaders, body?: InputStream | undefined);
|
|
}
|
|
/**
|
|
* Represents an HTTP connection from a client to a server
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpClientConnection extends BufferedEventEmitter {
|
|
_axios: any;
|
|
private axios_options;
|
|
protected bootstrap: ClientBootstrap | undefined;
|
|
protected socket_options?: SocketOptions;
|
|
protected tls_options?: TlsConnectionOptions;
|
|
protected proxy_options?: HttpProxyOptions;
|
|
/**
|
|
* Http connection constructor, signature synced to native version for compatibility
|
|
*
|
|
* @param bootstrap - (native only) leave undefined
|
|
* @param host_name - endpoint to connection with
|
|
* @param port - port to connect to
|
|
* @param socketOptions - (native only) leave undefined
|
|
* @param tlsOptions - instantiate for TLS, but actual value is unused in browse implementation
|
|
* @param proxyOptions - options to control proxy usage when establishing the connection
|
|
*/
|
|
constructor(bootstrap: ClientBootstrap | undefined, host_name: string, port: number, socketOptions?: SocketOptions, tlsOptions?: TlsConnectionOptions, proxyOptions?: HttpProxyOptions);
|
|
/**
|
|
* Emitted when the connection is connected and ready to start streams
|
|
*
|
|
* @event
|
|
*/
|
|
static CONNECT: string;
|
|
/**
|
|
* Emitted when an error occurs on the connection
|
|
*
|
|
* @event
|
|
*/
|
|
static ERROR: string;
|
|
/**
|
|
* Emitted when the connection has completed
|
|
*
|
|
* @event
|
|
*/
|
|
static CLOSE: string;
|
|
on(event: 'connect', listener: HttpClientConnectionConnected): this;
|
|
on(event: 'error', listener: HttpClientConnectionError): this;
|
|
on(event: 'close', listener: HttpClientConnectionClosed): this;
|
|
/**
|
|
* Make a client initiated request to this connection.
|
|
* @param request - The HttpRequest to attempt on this connection
|
|
* @returns A new stream that will deliver events for the request
|
|
*/
|
|
request(request: HttpRequest): HttpClientStream;
|
|
/**
|
|
* Ends the connection
|
|
*/
|
|
close(): void;
|
|
}
|
|
/**
|
|
* Listener signature for event emitted from an {@link HttpClientStream} when the http response headers have arrived.
|
|
*
|
|
* @param status_code http response status code
|
|
* @param headers the response's set of headers
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export type HttpStreamResponse = (status_code: number, headers: HttpHeaders) => void;
|
|
/**
|
|
* Represents a single http message exchange (request/response) in HTTP.
|
|
*
|
|
* NOTE: Binding either the ready or response event will uncork any buffered events and start
|
|
* event delivery
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpClientStream extends BufferedEventEmitter {
|
|
readonly connection: HttpClientConnection;
|
|
private response_status_code?;
|
|
private constructor();
|
|
/**
|
|
* HTTP status code returned from the server.
|
|
* @return Either the status code, or undefined if the server response has not arrived yet.
|
|
*/
|
|
status_code(): number | undefined;
|
|
/**
|
|
* Begin sending the request.
|
|
*
|
|
* The stream does nothing until this is called. Call activate() when you
|
|
* are ready for its callbacks and events to fire.
|
|
*/
|
|
activate(): void;
|
|
/**
|
|
* Emitted when the http response headers have arrived.
|
|
*
|
|
* @event
|
|
*/
|
|
static RESPONSE: string;
|
|
/**
|
|
* Emitted when http response data is available.
|
|
*
|
|
* @event
|
|
*/
|
|
static DATA: string;
|
|
/**
|
|
* Emitted when an error occurs in stream processing
|
|
*
|
|
* @event
|
|
*/
|
|
static ERROR: string;
|
|
/**
|
|
* Emitted when the stream has completed
|
|
*
|
|
* @event
|
|
*/
|
|
static END: string;
|
|
on(event: 'response', listener: HttpStreamResponse): this;
|
|
on(event: 'data', listener: HttpStreamData): this;
|
|
on(event: 'error', listener: HttpStreamError): this;
|
|
on(event: 'end', listener: HttpStreamComplete): this;
|
|
/** @internal */
|
|
static _create(connection: HttpClientConnection): HttpClientStream;
|
|
/** @internal */
|
|
_on_response(response: any): void;
|
|
/** @internal */
|
|
_on_error(error: any): void;
|
|
}
|
|
/**
|
|
* Creates, manages, and vends connections to a given host/port endpoint
|
|
*
|
|
* @category HTTP
|
|
*/
|
|
export declare class HttpClientConnectionManager {
|
|
readonly bootstrap: ClientBootstrap | undefined;
|
|
readonly host: string;
|
|
readonly port: number;
|
|
readonly max_connections: number;
|
|
readonly initial_window_size: number;
|
|
readonly socket_options?: SocketOptions | undefined;
|
|
readonly tls_opts?: TlsConnectionOptions | undefined;
|
|
readonly proxy_options?: HttpProxyOptions | undefined;
|
|
private pending_connections;
|
|
private live_connections;
|
|
private free_connections;
|
|
private pending_requests;
|
|
/**
|
|
* Constructor for the HttpClientConnectionManager class. Signature stays in sync with native implementation
|
|
* for compatibility purposes (leads to some useless params)
|
|
*
|
|
* @param bootstrap - (native only) leave undefined
|
|
* @param host - endpoint to pool connections for
|
|
* @param port - port to connect to
|
|
* @param max_connections - maximum allowed connection count
|
|
* @param initial_window_size - (native only) leave as zero
|
|
* @param socket_options - (native only) leave null
|
|
* @param tls_opts - if not null TLS will be used, otherwise plain http will be used
|
|
* @param proxy_options - configuration for establishing connections through a proxy
|
|
*/
|
|
constructor(bootstrap: ClientBootstrap | undefined, host: string, port: number, max_connections: number, initial_window_size: number, socket_options?: SocketOptions | undefined, tls_opts?: TlsConnectionOptions | undefined, proxy_options?: HttpProxyOptions | undefined);
|
|
private remove;
|
|
private resolve;
|
|
private reject;
|
|
private pump;
|
|
/**
|
|
* Vends a connection from the pool
|
|
* @returns A promise that results in an HttpClientConnection. When done with the connection, return
|
|
* it via {@link release}
|
|
*/
|
|
acquire(): Promise<HttpClientConnection>;
|
|
/**
|
|
* Returns an unused connection to the pool
|
|
* @param connection - The connection to return
|
|
*/
|
|
release(connection: HttpClientConnection): void;
|
|
/** Closes all connections and rejects all pending requests */
|
|
close(): void;
|
|
}
|