API Reference

Reseau

Root module for Reseau's networking transport stack.

The primary public entrypoints are TCP and TLS.

TCP

Core TCP socket operations and connection/listener types.

This layer sits directly above SocketOps and IOPoll. It is responsible for turning raw non-blocking sockets into higher-level connection/listener objects, including:

• sockets are created non-blocking and registered with the poller
• non-blocking connect completes by waiting for write readiness and then reading SO_ERROR
• accept returns already-initialized child descriptors that are ready for the same poll-driven read/write paths as outbound connections
• deadline expiry is surfaced as TCP.DeadlineExceededError for transport I/O

TLS

TLS client/server layer built on OpenSSL and TCP connections.

This layer provides:

• reusable Config objects for client and server policy
• Conn wrappers that can handshake eagerly or lazily on first I/O
• deadline handling delegated to the wrapped transport so TLS retries follow the same timeout model as plain TCP
• transport timeout handling is available as TLS.DeadlineExceededError

SocketAddr

Abstract network endpoint type for TCP socket addresses.

SocketAddrV4

IPv4 endpoint snapshot.

The address bytes are stored in presentation order and the port is stored in host byte order. Conversion to platform sockaddr structs happens lazily when a socket operation actually needs one.

SocketAddrV6

IPv6 endpoint snapshot.

scope_id is used for scoped link-local addresses and is preserved all the way down to the platform sockaddr representation so bind/connect can target the same interface the caller selected.

loopback_addr(port) -> SocketAddrV4

Convenience constructor for 127.0.0.1:port.

any_addr(port) -> SocketAddrV4

Convenience constructor for 0.0.0.0:port, typically used for wildcard binds.

loopback_addr6(port; scope_id=0) -> SocketAddrV6

Convenience constructor for [::1]:port.

any_addr6(port; scope_id=0) -> SocketAddrV6

Convenience constructor for the IPv6 wildcard bind address [::]:port.

Conn

User-facing connected TCP stream.

Reads and writes are forwarded to IOPoll, which means blocking operations are actually readiness waits against the shared low-level poller rather than thread-per-socket blocking syscalls. Because Conn <: IO, standard Base stream helpers like read, read!, readbytes!, eof, and write apply directly.

Listener

User-facing passive TCP listener.

Accepted children are returned as Conn values whose underlying sockets are already non-blocking, poll-registered, and configured with the default TCP options Reseau wants.

connect

Connect a TCP client using either a concrete SocketAddr or a string-address overload added later in the file load order.

listen

Create a TCP listener from either a concrete SocketAddr or a string-address overload added later in the file load order.

accept

Accept one inbound Conn from a TCP.Listener.

read!(conn, buf) -> buf

Read exactly length(buf) bytes into buf or throw EOFError.

Because Conn <: IO, Base's generic read! implementation already supports mutable byte views like @view bytes[2:5] in addition to plain vectors.

Use readbytes! or readavailable when you want a count-returning read that may stop early.

readbytes!(conn, buf, nb=length(buf); all::Bool=true) -> Int

Read up to nb bytes into buf, returning the byte count.

Unlike read!(conn, buf), this API may return after a short read or EOF. It is the count-returning TCP read entrypoint once TCP.Conn follows Julia's IO contract.

If all is true (the default), the call keeps reading until nb bytes have been transferred, EOF is reached, or an error occurs. If all is false, at most one underlying socket read is performed.

Resizable Vector{UInt8} buffers grow when needed, matching Julia's standard readbytes! behavior. Fixed-size contiguous byte views must satisfy nb <= length(buf).

readavailable(conn) -> Vector{UInt8}

Read and return the bytes that are currently ready without requiring a full-buffer exact read.

eof(conn) -> Bool

Report whether the peer has cleanly closed the read side of the connection.

isopen(conn) -> Bool

Return true while conn still owns an open socket.

isopen(listener) -> Bool

Return true while listener still owns an open listening socket.

write(conn, buf) -> Int

Write all bytes from buf and return the number of bytes written.

On success, the return value is always length(buf). If the socket cannot currently accept data, the call waits for write readiness and resumes until the entire buffer has been written or an error/deadline interrupts the operation.

close(conn)

Close the connection. Repeated closes are treated as no-ops.

close(listener)

Close the listening socket. Repeated closes are treated as no-ops.

closeread(conn)

Shut down the read side of the TCP connection.

closewrite(conn)

Shut down the write side of the TCP connection.

set_deadline!(conn, deadline_ns)

Set both read and write deadlines on conn.

• deadline_ns is an absolute monotonic timestamp in nanoseconds, using the same clock as time_ns().
• deadline_ns == 0 disables both deadlines.
• deadline_ns <= time_ns() marks both sides as immediately timed out.

After the deadline is reached, blocking read!/write operations fail with DeadlineExceededError until the deadline is cleared or moved forward.

set_deadline!(listener, deadline_ns)

Set the accept deadline on listener.

• deadline_ns uses the same absolute monotonic time_ns() clock as connection deadlines.
• deadline_ns == 0 disables accept timeouts.
• deadline_ns <= time_ns() causes the next blocking accept to time out immediately.

This affects accept(listener) only.

set_read_deadline!(conn, deadline_ns)

Set only the read deadline on conn.

• Uses absolute monotonic nanoseconds (time_ns() clock).
• deadline_ns == 0 disables read timeouts.
• deadline_ns <= time_ns() causes read waits to time out immediately.

This affects read! wait paths only.

set_write_deadline!(conn, deadline_ns)

Set only the write deadline on conn.

• Uses absolute monotonic nanoseconds (time_ns() clock).
• deadline_ns == 0 disables write timeouts.
• deadline_ns <= time_ns() causes write waits to time out immediately.

This affects write wait paths only.

DeadlineExceededError

Raised when blocking TCP I/O or accept(listener) exceeds the active deadline.

Catch TCP.DeadlineExceededError when a deadline set by set_deadline!, set_read_deadline!, or set_write_deadline! expires. This aliases the underlying poller timeout type so downstream code does not need to depend on Reseau.IOPoll directly.

set_nodelay!(conn, enabled=true)

Enable or disable TCP_NODELAY on conn.

set_keepalive!(conn, enabled=true)

Enable or disable SO_KEEPALIVE on conn.

local_addr(conn) -> Union{Nothing, SocketAddr}

Return the cached local endpoint for conn, if known.

local_addr(listener) -> Union{Nothing, SocketAddr}

Return the listener's bound local endpoint.

This is an alias for addr(listener).

remote_addr(conn) -> Union{Nothing, SocketAddr}

Return the cached remote endpoint for conn, if known.

addr(listener) -> Union{Nothing, SocketAddr}

Return the listener's bound local endpoint, if known.

Config(; ...)

Reusable TLS configuration for client and server sessions.

Keyword arguments:

• server_name: hostname or IP literal used for certificate verification. For clients, this also drives SNI when it is a hostname. If omitted, connect will try to derive it from the dial target.
• verify_peer: whether to validate the remote certificate chain and peer name.
• client_auth: server-side client certificate policy.
• cert_file / key_file: PEM-encoded certificate chain and private key. Servers must provide both; clients may provide both for mutual TLS.
• ca_file: CA bundle or hashed CA directory used to verify remote servers. When omitted, client verification uses NetworkOptions.ca_roots_path().
• client_ca_file: CA bundle or hashed CA directory used by servers to verify client certificates. This is required for server configs that verify presented client certs.
• alpn_protocols: ordered ALPN protocol preference list.
• handshake_timeout_ns: optional cap, in monotonic nanoseconds, applied only while the handshake is running. Existing transport deadlines still win if they are earlier.
• min_version / max_version: TLS protocol version bounds. nothing leaves the bound unset.

Returns a reusable immutable Config.

Throws ConfigError if the keyword combination is internally inconsistent.

ConnectionState

Snapshot of negotiated TLS connection state.

Fields:

• handshake_complete: whether the TLS handshake has finished successfully.
• version: negotiated TLS protocol version string as reported by OpenSSL.
• alpn_protocol: negotiated ALPN protocol, or nothing if ALPN was not used.

Conn

TLS stream wrapper over one TCP.Conn.

Conn is safe for one concurrent reader and one concurrent writer. Handshake, read, and write all have separate locks so lazy handshakes and shutdown can coordinate without corrupting the OpenSSL state machine. Because Conn <: IO, standard Base stream helpers like read, read!, readbytes!, eof, and write apply directly to decrypted application data.

Listener

TLS listener wrapper over TCP.Listener.

Accepted connections are wrapped in server-side TLS state but are not handshaken until handshake! or the first read/write call.

ConfigError

Raised when TLS configuration is invalid.

This is thrown before any network I/O starts, typically while normalizing a Config or constructing an SSL_CTX.

TLSError

Raised when TLS handshake/read/write/close operations fail.

code is usually an OpenSSL SSL_get_error result, though wrapper paths may set it to 0 when the failure is higher-level than one OpenSSL call. cause preserves the underlying Julia-side exception when the failure originated in the transport/poller layer instead of OpenSSL itself.

TLSHandshakeTimeoutError

Raised when handshake exceeds the configured timeout.

This is kept separate from TLSError because handshake timeouts are often configured and handled distinctly from generic TLS failures.

DeadlineExceededError

Alias for the transport deadline timeout type used by TLS.

Catch TLS.DeadlineExceededError for direct listener accept timeouts and when inspecting TLSError.cause. Higher-level TLS operations may wrap deadline expiry in TLSError or TLSHandshakeTimeoutError so callers can keep operation-specific handling.

client(tcp, config) -> Conn

Wrap an established TCP.Conn in client-side TLS state.

The handshake is deferred until handshake! or the first read/write operation.

Throws ConfigError or TLSError if the TLS state cannot be initialized.

server(tcp, config) -> Conn

Wrap an established TCP.Conn in server-side TLS state.

The handshake is deferred until handshake! or the first read/write operation.

Throws ConfigError or TLSError if the TLS state cannot be initialized.

connect(remote_addr; kwargs...) -> Conn
connect(remote_addr, local_addr; kwargs...) -> Conn

Connect to a concrete TCP.SocketAddr, negotiate TLS, and return a fully handshaken client connection.

This is the direct-address counterpart to the string-address connect(network, address; ...) overloads. The underlying socket setup is delegated to TCP.connect, after which the returned transport is wrapped in TLS and handshaken immediately.

TLS keyword arguments are forwarded to Config. If server_name is omitted, it is inferred from the concrete remote address when possible so peer verification and SNI can follow the same rules as the string-address client path.

connect(network, address; kwargs...) -> Conn

Connect to address, negotiate TLS, and return a fully handshaken client connection.

Network-resolution keyword arguments are:

• timeout_ns
• deadline_ns
• local_addr
• fallback_delay_ns
• resolver
• policy

TLS keyword arguments are forwarded to Config:

• server_name
• verify_peer
• client_auth
• cert_file
• key_file
• ca_file
• client_ca_file
• alpn_protocols
• handshake_timeout_ns
• min_version
• max_version

If server_name is omitted, it is derived from address when possible so SNI and peer verification use the dial target's host name automatically.

connect(address; kwargs...) -> Conn

Convenience shorthand for connect("tcp", address; kwargs...).

listen(network, address, config; backlog=128, reuseaddr=true) -> Listener

Create a TLS listener by first creating a TCP listener and then associating a server Config with accepted connections.

Accepted Conns are returned in lazy-handshake form.

Throws ConfigError if the server config is invalid and propagates any listener creation errors from TCP.listen.

listen(local_addr, config; backlog=128, reuseaddr=true) -> Listener

Create a TLS listener from a concrete local TCP.SocketAddr.

This is the direct-address counterpart to listen(network, address, config; ...). The underlying TCP listener is created with TCP.listen, then accepted connections are wrapped in lazy-handshake TLS state.

accept(listener) -> Conn

Accept one inbound TCP connection and wrap it in server-side TLS state.

The returned Conn has not handshaken yet. If the listener deadline expires, accept(listener) throws DeadlineExceededError.

handshake!(conn)

Run the TLS handshake to completion if it has not already finished.

This method is idempotent. Concurrent callers serialize through handshake_lock, so only one task drives OpenSSL while the others observe the completed state afterward.

Returns nothing.

Throws:

• TLSHandshakeTimeoutError when config.handshake_timeout_ns expires
• TLSError for OpenSSL or transport failures
• EOFError if the peer closes cleanly during the handshake

read!(conn, buf) -> buf

Read exactly length(buf) decrypted bytes into buf or throw EOFError.

Because Conn <: IO, Base's generic read! implementation already supports mutable byte views like @view bytes[2:5] in addition to plain vectors.

Use readbytes! or readavailable when you want a count-returning read that may stop early.

readbytes!(conn, buf, nb=length(buf); all::Bool=true) -> Int

Read up to nb decrypted bytes into buf, returning the byte count.

If all is true (the default), the call keeps reading until nb bytes have been transferred, EOF is reached, or an error occurs. If all is false, at most one underlying TLS read is performed.

Resizable Vector{UInt8} buffers grow when needed, matching Julia's standard readbytes! behavior. Fixed-size contiguous byte views must satisfy nb <= length(buf).

readavailable(conn) -> Vector{UInt8}

Read and return decrypted plaintext that is ready without requiring a full-buffer exact read.

eof(conn) -> Bool

Report whether the peer has cleanly finished the TLS stream.

isopen(conn) -> Bool

Return true while both the TLS state and underlying TCP transport remain open.

isopen(listener) -> Bool

Return true while the wrapped TCP listener remains open.

write(conn, buf) -> Int
write(conn, buf, nbytes) -> Int

Write plaintext application bytes through the TLS connection.

write(conn, buf) attempts to write the entire buffer. The fixed-size byte-buffer overload allows callers to cap the write at nbytes.

close(conn)

Close the TLS connection and the underlying TCP transport.

If the handshake completed, this best-effort sends a TLS close_notify alert before closing the socket. The method is idempotent and returns nothing.

close(listener)

Close the underlying TCP listener. Repeated closes are treated as no-ops.

closewrite(conn)

Send TLS shutdown on the write side and mark future writes as permanently failed.

This is the TLS analogue of half-closing a TCP socket. It requires the handshake to have completed because the TLS close-notify alert is itself a TLS record.

Returns nothing.

Throws TLSError if the TLS shutdown path fails.

set_deadline!(conn, deadline_ns)

Set both read and write deadlines on the underlying transport.

deadline_ns is interpreted using the same monotonic-clock convention as TCP and IOPoll: 0 clears the deadline, negative values mean the deadline has already expired, and positive values are absolute time_ns() values.

set_deadline!(listener, deadline_ns)

Set the accept deadline on the underlying TCP listener.

This affects accept(listener) only. The returned Conn still uses its own connection and handshake deadlines afterward. Expired accept waits throw DeadlineExceededError.

set_read_deadline!(conn, deadline_ns)

Set the read deadline on the underlying transport. See set_deadline! for the timestamp convention.

set_write_deadline!(conn, deadline_ns)

Set the write deadline on the underlying transport. See set_deadline! for the timestamp convention.

local_addr(conn)

Return the local TCP.SocketAddr for the wrapped transport.

local_addr(listener)

Return the local listening address for the wrapped TCP listener.

This is an alias for addr(listener).

remote_addr(conn)

Return the remote TCP.SocketAddr for the wrapped transport.

net_conn(conn) -> TCP.Conn

Expose the underlying TCP connection.

Callers that need transport-level inspection can reach through the TLS wrapper without reconstructing the socket state.

connection_state(conn) -> ConnectionState

Return a snapshot of the currently negotiated TLS state.

This does not force a handshake; if the handshake has not yet run, the returned ConnectionState reports handshake_complete=false.

addr(listener)

Return the local listening address for the wrapped TCP listener.

SocketOps

Cross-platform socket syscall facade and sockaddr helpers.

This module is intentionally lower level than TCP: it exposes thin wrappers around the OS socket APIs, normalizes the most important portability differences, and leaves policy decisions to higher layers.

A few conventions are worth keeping in mind when reading the code:

• successful mutating operations usually return nothing
• operations that need to preserve transient errno values often return the raw integer error code instead of throwing immediately
• wrappers aim to look POSIX-like even on Windows so the polling and transport layers can share most control flow
• address helpers always build or decode structs in network byte order so callers can treat the Julia-level tuples as ordinary host-order values

IOPoll

Internal readiness polling and deadline management for network descriptors.

IOPoll owns:

• one dedicated native poller thread plus the platform backend integration
• descriptor registration and readiness waiters
• read/write deadlines and poller-managed timers
• the low-level FD wrapper used by higher transport layers

Higher layers call register!, prepareread, preparewrite, waitread, waitwrite, and timer helpers instead of interacting with backend-specific handles directly.

PollMode

Bitmask enum used for read, write, and combined read/write readiness and deadline directions within IOPoll.

HostResolvers

Address parsing, name resolution, and TCP string-address helpers.

This layer is the bridge between string-oriented user input like "example.com:443" and the lower-level TCP primitives that operate on concrete socket addresses. It is responsible for:

• parse and canonicalize host/port strings
• resolve hostnames according to a resolver policy
• attempt connections serially or in a Happy Eyeballs-style race
• wrap failures in an operation-specific error that preserves context

The public-facing string overloads for TCP.connect and TCP.listen are implemented here so users can stay on the TCP surface while the host/service resolution logic remains factored into its own file.