// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
/// <reference no-default-lib="true" />
/// <reference lib="esnext" />
declare namespace Deno {
export interface NetAddr {
transport: "tcp" | "udp";
hostname: string;
port: number;
}
export interface UnixAddr {
transport: "unix" | "unixpacket";
path: string;
}
export type Addr = NetAddr | UnixAddr;
/** A generic network listener for stream-oriented protocols. */
export interface Listener extends AsyncIterable<Conn> {
/** Waits for and resolves to the next connection to the `Listener`. */
accept(): Promise<Conn>;
/** Close closes the listener. Any pending accept promises will be rejected
* with errors. */
close(): void;
/** Return the address of the `Listener`. */
readonly addr: Addr;
/** Return the rid of the `Listener`. */
readonly rid: number;
[Symbol.asyncIterator](): AsyncIterableIterator<Conn>;
}
/** Specialized listener that accepts TLS connections. */
export interface TlsListener extends Listener, AsyncIterable<TlsConn> {
/** Waits for a TLS client to connect and accepts the connection. */
accept(): Promise<TlsConn>;
[Symbol.asyncIterator](): AsyncIterableIterator<TlsConn>;
}
export interface Conn extends Reader, Writer, Closer {
/** The local address of the connection. */
readonly localAddr: Addr;
/** The remote address of the connection. */
readonly remoteAddr: Addr;
/** The resource ID of the connection. */
readonly rid: number;
/** Shuts down (`shutdown(2)`) the write side of the connection. Most
* callers should just use `close()`. */
closeWrite(): Promise<void>;
readonly readable: ReadableStream<Uint8Array>;
readonly writable: WritableStream<Uint8Array>;
}
// deno-lint-ignore no-empty-interface
export interface TlsHandshakeInfo {}
export interface TlsConn extends Conn {
/** Runs the client or server handshake protocol to completion if that has
* not happened yet. Calling this method is optional; the TLS handshake
* will be completed automatically as soon as data is sent or received. */
handshake(): Promise<TlsHandshakeInfo>;
}
export interface ListenOptions {
/** The port to listen on. */
port: number;
/** A literal IP address or host name that can be resolved to an IP address.
* If not specified, defaults to `0.0.0.0`.
*
* __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms,
* the browsers on Windows don't work with the address `0.0.0.0`.
* You should show the message like `server running on localhost:8080` instead of
* `server running on 0.0.0.0:8080` if your program supports Windows. */
hostname?: string;
}
/** Listen announces on the local transport address.
*
* ```ts
* const listener1 = Deno.listen({ port: 80 })
* const listener2 = Deno.listen({ hostname: "192.0.2.1", port: 80 })
* const listener3 = Deno.listen({ hostname: "[2001:db8::1]", port: 80 });
* const listener4 = Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" });
* ```
*
* Requires `allow-net` permission. */
export function listen(
options: ListenOptions & { transport?: "tcp" },
): Listener;
export interface ListenTlsOptions extends ListenOptions {
/** Server private key in PEM format */
key?: string;
/** Cert chain in PEM format */
cert?: string;
/** Path to a file containing a PEM formatted CA certificate. Requires
* `--allow-read`.
*
* @deprecated This option is deprecated and will be removed in Deno 2.0.
*/
certFile?: string;
/** Server private key file. Requires `--allow-read`.
*
* @deprecated This option is deprecated and will be removed in Deno 2.0.
*/
keyFile?: string;
transport?: "tcp";
}
/** Listen announces on the local transport address over TLS (transport layer
* security).
*
* ```ts
* const lstnr = Deno.listenTls({ port: 443, certFile: "./server.crt", keyFile: "./server.key" });
* ```
*
* Requires `allow-net` permission. */
export function listenTls(options: ListenTlsOptions): TlsListener;
export interface ConnectOptions {
/** The port to connect to. */
port: number;
/** A literal IP address or host name that can be resolved to an IP address.
* If not specified, defaults to `127.0.0.1`. */
hostname?: string;
transport?: "tcp";
}
/**
* Connects to the hostname (default is "127.0.0.1") and port on the named
* transport (default is "tcp"), and resolves to the connection (`Conn`).
*
* ```ts
* const conn1 = await Deno.connect({ port: 80 });
* const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 });
* const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 });
* const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" });
* ```
*
* Requires `allow-net` permission for "tcp". */
export function connect(options: ConnectOptions): Promise<TcpConn>;
export interface TcpConn extends Conn {
/**
* **UNSTABLE**: new API, see https://github.com/denoland/deno/issues/13617.
*
* Enable/disable the use of Nagle's algorithm. Defaults to true.
*/
setNoDelay(nodelay?: boolean): void;
/**
* **UNSTABLE**: new API, see https://github.com/denoland/deno/issues/13617.
*
* Enable/disable keep-alive functionality.
*/
setKeepAlive(keepalive?: boolean): void;
}
// deno-lint-ignore no-empty-interface
export interface UnixConn extends Conn {}
export interface ConnectTlsOptions {
/** The port to connect to. */
port: number;
/** A literal IP address or host name that can be resolved to an IP address.
* If not specified, defaults to `127.0.0.1`. */
hostname?: string;
/**
* Server certificate file.
*
* @deprecated This option is deprecated and will be removed in a future
* release.
*/
certFile?: string;
/** A list of root certificates that will be used in addition to the
* default root certificates to verify the peer's certificate.
*
* Must be in PEM format. */
caCerts?: string[];
}
/** Establishes a secure connection over TLS (transport layer security) using
* an optional cert file, hostname (default is "127.0.0.1") and port. The
* cert file is optional and if not included Mozilla's root certificates will
* be used (see also https://github.com/ctz/webpki-roots for specifics)
*
* ```ts
* const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem");
* const conn1 = await Deno.connectTls({ port: 80 });
* const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80 });
* const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80 });
* const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80});
* ```
*
* Requires `allow-net` permission.
*/
export function connectTls(options: ConnectTlsOptions): Promise<TlsConn>;
export interface StartTlsOptions {
/** A literal IP address or host name that can be resolved to an IP address.
* If not specified, defaults to `127.0.0.1`. */
hostname?: string;
/** A list of root certificates that will be used in addition to the
* default root certificates to verify the peer's certificate.
*
* Must be in PEM format. */
caCerts?: string[];
}
/** Start TLS handshake from an existing connection using an optional list of
* CA certificates, and hostname (default is "127.0.0.1"). Specifying CA certs
* is optional. By default the configured root certificates are used. Using
* this function requires that the other end of the connection is prepared for
* a TLS handshake.
*
* ```ts
* const conn = await Deno.connect({ port: 80, hostname: "127.0.0.1" });
* const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem");
* const tlsConn = await Deno.startTls(conn, { caCerts: [caCert], hostname: "localhost" });
* ```
*
* Requires `allow-net` permission.
*/
export function startTls(
conn: Conn,
options?: StartTlsOptions,
): Promise<TlsConn>;
/** Shutdown socket send operations.
*
* Matches behavior of POSIX shutdown(3).
*
* ```ts
* const listener = Deno.listen({ port: 80 });
* const conn = await listener.accept();
* Deno.shutdown(conn.rid);
* ```
*/
export function shutdown(rid: number): Promise<void>;
}