IF Commons GitHub

tcp

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-net FR-006

TCP 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 });

Source: commons/net/src/tcp.ts

6 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

tcpnamespace
namespace tcp
tcp.ListenOptionstypeno test imports it
type 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 it
type 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 it
type 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 it
type 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 it
type 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 it
type 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 it
function listen(options?: ListenOptions): Promise<Listener>

Listen for TCP connections; AddrInUse where the port is taken.

tcp.listenTlsfunctionno test imports it
function 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 it
function connect(options: ConnectOptions): Promise<Conn>

Connect over TCP; ConnectionRefused where nothing listens.

tcp.connectTlsfunctionno test imports it
function 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 it
type 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 it
type 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 it
type 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 it
type 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.

Conntype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Listenertype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

listenfunction
function listen(options?: ListenOptions): Promise<Listener>

Listen for TCP connections; AddrInUse where the port is taken.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

listenTlsfunction
function listenTls(options: ListenTlsOptions): Promise<Listener>

Listen for TLS connections with a certificate and key in PEM; AddrInUse where the port is taken.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

connectfunction
function connect(options: ConnectOptions): Promise<Conn>

Connect over TCP; ConnectionRefused where nothing listens.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

connectTlsfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.