tcpnamespacenamespace tcpTCP connections, plain and over TLS (commons 0001-net FR-006), on node:net and node:tls: listen, listenTls, connect and connectTls. A Listener gives its address and its connections as an async iterable and closes by close(), an abort signal or using; a Conn gives its local and remote addresses, a web ReadableStream and WritableStream (made here by hand over the socket, the same on Bun and Node), closeWrite and close. Failures are thrown as the runtime's errors (FR-019): AddrInUse, ConnectionRefused, TimedOut (an AbortSignal.timeout that fired), and InvalidData for a server certificate that does not check out.
Some choices are deliberate: listen and listenTls return a promise (Node binds asynchronously and reports a taken port then); a listener binds 127.0.0.1 unless asked, as serve.ts does, never every interface; connectTls's caCerts replace the system's roots instead of adding to them, so a test or a pinned service trusts exactly the roots it names; and a TLS connection is given once its handshake is done.
import { connect, listen } from "./tcp.ts";
await using listener = await listen({ port: 0 });
void (async () => {
for await (const conn of listener) void conn.readable.pipeTo(conn.writable); // an echo server
})();
using conn = await connect({ port: listener.addr.port });tcpnamespacenamespace tcptcp.ListenOptionstypeno test imports ittype ListenOptions = {
/** The port; 0 (the default) asks the system for a free one. */
readonly port?: number;
/** The address to bind; `127.0.0.1` by default, never every interface unless asked (`0.0.0.0`, `::`). */
readonly hostname?: string;
/** Aborting it closes the listener. */
readonly signal?: AbortSignal;
};Where to listen.
tcp.ListenTlsOptionstypeno test imports ittype ListenTlsOptions = ListenOptions & {
/** The server's certificate chain, in PEM. */
readonly cert: string;
/** The certificate's private key, in PEM. */
readonly key: string;
};Where to listen for TLS, and the certificate to answer with.
tcp.ConnectOptionstypeno test imports ittype ConnectOptions = {
/** The host's name or address; `127.0.0.1` by default. */
readonly hostname?: string;
/** The port. */
readonly port: number;
/** Aborting it gives up while connecting (`TimedOut` where it is an `AbortSignal.timeout`); a connection made is not affected. */
readonly signal?: AbortSignal;
};Where to connect.
tcp.ConnectTlsOptionstypeno test imports ittype ConnectTlsOptions = ConnectOptions & {
/** The roots, in PEM, that the server's certificate must chain to, instead of the system's; the system's roots where not given. */
readonly caCerts?: readonly string[];
/** The name the certificate must be for, where it is not `hostname` (SNI is sent only for a name, never for an address). */
readonly serverName?: string;
};Where to connect over TLS, and the roots to check the server's certificate against.
tcp.Conntypeno test imports ittype Conn = {
/** This end's address. */
readonly localAddr: NetAddr;
/** The other end's address. */
readonly r… (815 characters)type Conn = {
/** This end's address. */
readonly localAddr: NetAddr;
/** The other end's address. */
readonly remoteAddr: NetAddr;
/** The bytes the other end sends; ends when it closes its side; cancelling it closes the connection. */
readonly readable: ReadableStream<Uint8Array>;
/** The bytes to send; each write settles once the system has taken it; closing it ends this side (as `closeWrite`). */
readonly writable: WritableStream<Uint8Array>;
/** End this side (TCP half-close): the other end reads the end of the data, and this end can still read. */
closeWrite(): Promise<void>;
/** Close the connection at once, both ways. Closing it again does nothing. */
close(): void;
/** `using conn = await connect(...)` closes it at the end of the block. */
[Symbol.dispose](): void;
};A connection: its two ends, its bytes as web streams, and how to end it.
tcp.Listenertypeno test imports ittype Listener = {
/** Where it listens (the port the system chose where 0 was asked). */
readonly addr: NetAddr;
/… (735 characters)type Listener = {
/** Where it listens (the port the system chose where 0 was asked). */
readonly addr: NetAddr;
/** The next connection; rejects with `ConnectionAborted` once the listener is closed. */
accept(): Promise<Conn>;
/** The connections, one by one, until the listener is closed. */
[Symbol.asyncIterator](): AsyncIterator<Conn>;
/** Stop listening; connections already given stay open, those not yet taken are closed. Closing it again does nothing. */
close(): void;
/** `using listener = await listen(...)` closes it at the end of the block. */
[Symbol.dispose](): void;
/** `await using listener = await listen(...)` closes it at the end of the block. */
[Symbol.asyncDispose](): Promise<void>;
};A listener: its address and its connections.
tcp.listenfunctionno test imports itfunction listen(options?: ListenOptions): Promise<Listener>Listen for TCP connections; AddrInUse where the port is taken.
tcp.listenTlsfunctionno test imports itfunction listenTls(options: ListenTlsOptions): Promise<Listener>Listen for TLS connections with a certificate and key in PEM; AddrInUse where the port is taken.
tcp.connectfunctionno test imports itfunction connect(options: ConnectOptions): Promise<Conn>Connect over TCP; ConnectionRefused where nothing listens.
tcp.connectTlsfunctionno test imports itfunction connectTls(options: ConnectTlsOptions): Promise<Conn>Connect over TLS, checking the server's certificate against the system's roots or the caCerts given, and its name against serverName or hostname; InvalidData where the certificate does not check out.
ListenOptionstypeno test imports ittype ListenOptions = {
/** The port; 0 (the default) asks the system for a free one. */
readonly port?: number;
/** The address to bind; `127.0.0.1` by default, never every interface unless asked (`0.0.0.0`, `::`). */
readonly hostname?: string;
/** Aborting it closes the listener. */
readonly signal?: AbortSignal;
};Where to listen.
ListenTlsOptionstypeno test imports ittype ListenTlsOptions = ListenOptions & {
/** The server's certificate chain, in PEM. */
readonly cert: string;
/** The certificate's private key, in PEM. */
readonly key: string;
};Where to listen for TLS, and the certificate to answer with.
ConnectOptionstypeno test imports ittype ConnectOptions = {
/** The host's name or address; `127.0.0.1` by default. */
readonly hostname?: string;
/** The port. */
readonly port: number;
/** Aborting it gives up while connecting (`TimedOut` where it is an `AbortSignal.timeout`); a connection made is not affected. */
readonly signal?: AbortSignal;
};Where to connect.
ConnectTlsOptionstypeno test imports ittype ConnectTlsOptions = ConnectOptions & {
/** The roots, in PEM, that the server's certificate must chain to, instead of the system's; the system's roots where not given. */
readonly caCerts?: readonly string[];
/** The name the certificate must be for, where it is not `hostname` (SNI is sent only for a name, never for an address). */
readonly serverName?: string;
};Where to connect over TLS, and the roots to check the server's certificate against.
Conntypetype Conn = {
/** This end's address. */
readonly localAddr: NetAddr;
/** The other end's address. */
readonly r… (815 characters)type Conn = {
/** This end's address. */
readonly localAddr: NetAddr;
/** The other end's address. */
readonly remoteAddr: NetAddr;
/** The bytes the other end sends; ends when it closes its side; cancelling it closes the connection. */
readonly readable: ReadableStream<Uint8Array>;
/** The bytes to send; each write settles once the system has taken it; closing it ends this side (as `closeWrite`). */
readonly writable: WritableStream<Uint8Array>;
/** End this side (TCP half-close): the other end reads the end of the data, and this end can still read. */
closeWrite(): Promise<void>;
/** Close the connection at once, both ways. Closing it again does nothing. */
close(): void;
/** `using conn = await connect(...)` closes it at the end of the block. */
[Symbol.dispose](): void;
};A connection: its two ends, its bytes as web streams, and how to end it.
Listenertypetype Listener = {
/** Where it listens (the port the system chose where 0 was asked). */
readonly addr: NetAddr;
/… (735 characters)type Listener = {
/** Where it listens (the port the system chose where 0 was asked). */
readonly addr: NetAddr;
/** The next connection; rejects with `ConnectionAborted` once the listener is closed. */
accept(): Promise<Conn>;
/** The connections, one by one, until the listener is closed. */
[Symbol.asyncIterator](): AsyncIterator<Conn>;
/** Stop listening; connections already given stay open, those not yet taken are closed. Closing it again does nothing. */
close(): void;
/** `using listener = await listen(...)` closes it at the end of the block. */
[Symbol.dispose](): void;
/** `await using listener = await listen(...)` closes it at the end of the block. */
[Symbol.asyncDispose](): Promise<void>;
};A listener: its address and its connections.
listenfunctionfunction listen(options?: ListenOptions): Promise<Listener>Listen for TCP connections; AddrInUse where the port is taken.
listenTlsfunctionfunction listenTls(options: ListenTlsOptions): Promise<Listener>Listen for TLS connections with a certificate and key in PEM; AddrInUse where the port is taken.
connectfunctionfunction connect(options: ConnectOptions): Promise<Conn>Connect over TCP; ConnectionRefused where nothing listens.
connectTlsfunctionfunction connectTls(options: ConnectTlsOptions): Promise<Conn>Connect over TLS, checking the server's certificate against the system's roots or the caCerts given, and its name against serverName or hostname; InvalidData where the certificate does not check out.