velt/net
API referenceTCP, and TLS over TCP. TcpListener and TcpStream are structs around a handle, like file descriptors. For a walkthrough, read the guide.
Exports
opts.ca).listenListens on "host:port" (port 0 picks a free port; read it back from .port).listenTlslisten for TLS connections: accept gives streams that are encrypted with opts.cert.streamPairTwo connected in-memory streams, as Node's duplexPair() (or a socketpair): what one writes, the other reads, and one's shutdown() is the other's end of stream.TlsConnectOptionsNo doc comment yetTlsListenOptionsNo doc comment yetTcpListenerA bound listening socket.TcpStreamA connected TCP stream.Re-exported from velt/net/connect
async function connect(addr: string): Promise<TcpStream>Connects to "host:port".
Re-exported from velt/net/connect
async function connectTls(
addr: string,
opts: TlsConnectOptions = {},
): Promise<TcpStream>Connects to "host:port" over TLS; resolves once the handshake is done (the server's
certificate is checked against the built-in roots and opts.ca).
Re-exported from velt/net/listen
async function listen(addr: string): Promise<TcpListener>Listens on "host:port" (port 0 picks a free port; read it back from .port).
Re-exported from velt/net/listen
async function listenTls(
addr: string,
opts: TlsListenOptions,
): Promise<TcpListener>listen for TLS connections: accept gives streams that are encrypted with opts.cert.
Throws IoError "EINVAL" for a certificate or key that is not valid PEM.
Re-exported from velt/net/pair
function streamPair(): [TcpStream, TcpStream]Two connected in-memory streams, as Node's duplexPair() (or a socketpair): what one
writes, the other reads, and one's shutdown() is the other's end of stream. Each is a
TcpStream like any other (close both). For a protocol carried inside another one: the HTTP/2
server gives a WebSocket over an HTTP/2 stream one end, and moves bytes between the other end
and the stream's frames.
Re-exported from velt/net/connect
Parameter ofconnectTlsNo doc comment yet: add one
| Field | Type | Description |
|---|---|---|
| serverName? | string | The name the server's certificate must be for (default: the host in the address). |
| ca? | string | Extra trusted CA certificates (PEM), e.g. a private or test CA. |
| alpn? | string[] | The protocols to offer with ALPN, most preferred first (default: none). |
Re-exported from velt/net/listen
Parameter oflistenTlsNo doc comment yet: add one
| Field | Type | Description |
|---|---|---|
| cert | string | The certificate chain, PEM text. |
| key | string | Its private key, PEM text. |
| alpn? | string[] | The protocols to offer with ALPN, most preferred first (default: none). |
Re-exported from velt/net/tcp_listener
A bound listening socket.
| Field | Type | Description |
|---|---|---|
| port | number | The real bound port (useful after listening on port 0). |
async accept(): Promise<TcpStream>Waits for the next connection (TCP_NODELAY is on). On a listenTls listener the TLS
handshake runs with the stream's first read or write, which throws if it fails (10 s limit).
close()Releases the handle: later accepts through any copy throw IoError EBADF, and closing
again does nothing. An accept already waiting keeps the socket open until it completes.
Re-exported from velt/net/tcp_stream
A connected TCP stream.
Parameter ofvelt/net/websocketwebSocketOverReturned byconnectconnectTlsstreamPairTcpListener.accept
async read(max: u64 = 0): Promise<u8[]>The next 1..max bytes (max == 0: up to 64 KiB); an empty array means end of stream.
async readString(max: u64 = 0): Promise<string>The next chunk as UTF-8 (a character split across reads is completed by the next call, invalid bytes become U+FFFD); "" means end of stream.
async readInto(buf: Uint8Array): Promise<number | null>Reads what has arrived into buf, at most buf.length bytes, straight from the socket
(nothing is allocated or copied on the way for a plain TCP stream): the number of bytes
read, or null at the end of the stream (as Deno's conn.read). Waits only when nothing
has arrived yet. An empty buf reads nothing and returns 0. Reusing one buffer per
connection, and subarray views of what was read, keeps a server from copying its input.
tryRead(buf: u8[] | Uint8Array, start: number = 0, end?: number): number | nullReads what has arrived into buf[start..end] without waiting: the number of bytes read,
0 when nothing has arrived yet (await readable(), then try again), or null at the end
of the stream. A plain TCP stream reads straight into buf, so a parser can read into its
own buffer with nothing allocated or copied (readInto does the waiting for a
Uint8Array). RangeError for an empty or out-of-range range.
async readable(): Promise<void>Resolves once a tryRead may find data, the end of the stream or an error (it may also
find nothing yet: wait again). Holds no buffer while it waits.
async readableWithin(ms: number, signal: AbortSignal | null = null): Promise<bool>readable() with a limit: true once a tryRead may find something, false when ms
milliseconds passed first or signal was aborted. One wait in the runtime, so nothing of it
is left behind (unlike Promise.race with a timer): a server waiting for the next request on
each idle connection.
async alpnProtocol(): Promise<string | null>The protocol TLS's ALPN chose ("h2"), or null (none, not TLS); waits for the handshake.
async write(data: string): Promise<void>Resolves once every byte is written; data is copied at the call.
async writeBytes(data: u8[] | Uint8Array, start: number = 0, end?: number): Promise<void>Resolves once every byte is written. What the socket takes at the call is written from
data itself; only what it cannot take yet is copied.
tryWrite(data: u8[] | Uint8Array, start: number = 0, end?: number): i64Writes what the socket takes of data right now, without waiting, and returns the number
of bytes written (0 when it takes nothing now, while an earlier write is still going on,
for a TLS stream, and after an error, which the next write reports). For protocols that
send small messages: when everything was written there is nothing to await.
writeLater(data: string): i64Queues data to be sent when the current task next waits (or finishes), together with
everything else it queued until then: one system call where a write each would make
several, and nothing held back past a wait. Returns the number of bytes still to be sent on
this stream; await drained(max) keeps that bounded. A write goes after what was queued
before it. Throws IoError once sending failed (the error a write would have reported),
the stream was aborted or the handle closed.
writeBytesLater(data: u8[] | Uint8Array, start: number = 0, end?: number): i64writeLater of bytes start..end of data (copied at the call).
async drained(max: number = 0): Promise<void>Resolves once at most max bytes queued by writeLater (or a write after them) are still
to be sent: right away when there are no more, otherwise once the peer has read enough.
Throws IoError when sending failed.
shutdown()Half-close: the peer reads end of stream, after every byte written or queued (writeLater)
before; this side can still read.
peerAddr(): stringThe peer's "ip:port" ("" once the handle is closed).
abort()Fails the operations in flight on this stream (a write to a peer that stopped reading
would otherwise never finish) and every later one; nothing more is sent or received. The
handle stays open until close().
close()Releases the handle: later operations through any copy throw IoError EBADF, and closing
again does nothing. The socket closes once the operations in flight have finished.