// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license. /// /// 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 { /** Waits for and resolves to the next connection to the `Listener`. */ accept(): Promise; /** 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; } /** Specialized listener that accepts TLS connections. */ export interface TlsListener extends Listener, AsyncIterable { /** Waits for a TLS client to connect and accepts the connection. */ accept(): Promise; [Symbol.asyncIterator](): AsyncIterableIterator; } 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; } // 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; } 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 { /** Path to a file containing a PEM formatted CA certificate. Requires * `--allow-read`. */ certFile: string; /** Server public key file. Requires `--allow-read`.*/ 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; 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; 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; /** 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; }