Skip to main content

Crate net_io

Crate net_io 

Source
Expand description

§net_io

The network IO substrate for the -net and -io crates: the entrance and exit every service shares. It owns listeners and sockets, the life of each connection, the limits and timeouts that keep a peer from holding what it should not, graceful drain, and the seams a connection gate and a TLS engine plug into. It is protocol-free and has no runtime dependencies.

§Quick start

fn main() -> Result<(), net_io::NetError> {
    // An echo server: one handler call per connection on a bounded worker pool,
    // with every default limit (idle, read, write, minimum rate, caps) applied.
    let server = net_io::serve("127.0.0.1:7000", |conn| {
        let mut buf = [0u8; 4096];
        loop {
            let n = conn.recv(&mut buf)?;
            if n == 0 {
                return Ok(()); // the peer closed its side
            }
            conn.send_all(&buf[..n])?;
        }
    })?;

    // A client.
    let mut conn = net_io::connect("127.0.0.1:7000")?;
    conn.send_all(b"ping")?;
    let mut reply = [0u8; 4];
    conn.recv_exact(&mut reply)?;
    assert_eq!(&reply, b"ping");

    // Stop: close the door, drain open connections, join the workers.
    server.handle().request_stop();
    let report = server.wait_for_stop();
    println!("{} closed gracefully, {} killed", report.graceful, report.killed);
    Ok(())
}

Everything else (several listeners, a gate, events, the control line) goes through ServerBuilder. The full reference with every item, its errors, and its cost is docs/API.md in the repository.

§Status

0.8.0, alpha: the reactor on epoll, kqueue, and IOCP, and the blocking pool, on Linux, macOS, FreeBSD, and Windows. TCP with a client that reconnects with backoff, Unix domain sockets (AF_UNIX on Windows), Windows named pipes, and UDP with batches and sessions; zero-copy file sends and file receives; the PROXY protocol, the TLS seam, systemd and FastCGI inheritance, listener hand-off on Unix and Windows, and the public Driver interface. Hardened: an attack test per threat, continuous fuzzing, and a 24-hour soak. 0.8.0 adds what the first consumers needed: flush-then-close, a drain hook, and workers kept for a listener.

Structs§

Admitted
What admission grants.
AdoptSpec
Where Server::adopt registers a connection: the listener (by name) whose limits and caps apply, and an optional starting lane (the gate may change it).
AllowAll
The explicit “no gate”: admits every connection in Lane(0) with GateTag(0) and never denies.
Backoff
Delays between attempts: first, doubling each attempt up to max, each one drawn from the upper half of its step when jitter is on, so retries spread out but never come faster than half the step (D-142).
BlockingHandler
What ServerBuilder::handler produces; programs never name it.
Buffer
A byte buffer from a pool: a fixed capacity (its size class) and a filled length.
BufferPool
A worker’s buffer pool: free lists per size class, drawing new buffers from a budget shared by every worker of a server.
Cidr
A network block: a normalized network address and a prefix length.
Completer
A worker’s completion queue, for other threads to hand results back to a connection that returned Step::Park.
Completion
A finished operation.
Completions
What a wait fills; fixed capacity (256), so a wait never allocates.
ConnectOptions
Options for an outbound connection.
ConnectionId
The identity of one connection, unique and never reused within a process.
ConnectionInfo
What net-io knows about one connection, built at accept and completed as the handshake reveals more. It holds no heap memory.
Datagramudp
One received datagram.
DatagramBufferudp
A receive buffer of a batch; UdpSocket::recv_batch fills datagram.
Denial
A gate’s refusal of a write.
DescriptorsUnix and local
Descriptors received with UnixConnection::recv_descriptors: up to 64, owned, close-on-exec. Descriptors not taken are closed when this is dropped or reused.
DrainReport
What a drain did.
Drained
What TcpConnection::drain saw before closing.
DriverWaker
Wakes a driver’s Driver::wait from any thread.
GateTag
An opaque value the gate returns at admission, stored in ConnectionInfo::gate.
HandoffPeer
Whom recv_listeners accepts listeners from. uid: None means this process’s own effective user id; pid: None accepts any process of that user.
InheritedListener
A listener systemd passed to this process, with its LISTEN_FDNAMES name.
Input
The connection’s read buffer: a zero-copy view of what was read and not yet consumed.
Keepalive
Keepalive probes: idle time before the first, interval between them, and count.
KillHandle
Closes one connection abortively from any thread.
KillReason
A caller-defined code for a kill.
Lane
An opaque importance class the gate assigns at admission; lower is more important.
Limits
Every bound net-io enforces. Unset values take the defaults of the driver that runs the connection.
LimitsBuilder
Builds Limits; every setter is optional.
ListenOptions
Options set on a listening socket before bind and listen.
ListenerHandle
An owned listening socket with what is known about it: its kind, an optional name (up to 64 bytes), and its local endpoint. Dropping it closes the socket. Made by crate::systemd, hand-off, and Server::release_listeners; used by ListenerSpec::adopt.
ListenerId
The index of a listener within one server.
ListenerInfo
Facts about one bound listener.
ListenerSpec
One listener of a server.
LocalOptions
Options for a Unix socket listener. The defaults: mode 0600 (only the owner may connect, decision D-024), stale socket files removed, backlog 1,024.
ManualClock
A clock that moves only when told to, for deterministic timeout tests.
MinRate
A minimum transfer rate, checked per direction while that direction is active.
MonotonicClock
Instant::now().
NoControl
A control line that never changes: epoch() is always 0.
NoGate
The builder’s gate until ServerBuilder::gate names one: every connection is admitted, in the most important lane, as with AllowAll, and no gate check runs on the write path.
NoTls
The builder’s default acceptor: no listener may enable TLS with it.
NoWork
What runs per connection; the unset state (no build exists for it).
NoopSink
Discards every event; the builder’s default. Compiles to nothing.
OutgoingDatagramudp
One datagram of a batch to send.
Output
What the session wants written: a bounded queue of chunks.
OutputFull
The output budget was reached; return Step::Write and continue after the flush.
PeerCredentials
Who is on the other end of a local socket. A field the platform cannot report is None.
PipeName
A Windows pipe name in a fixed array (up to 256 UTF-16 units).
PoolStats
Counts of one pool.
PrefixKey
“This address at this prefix length” as a fixed-size Copy hash key.
PrefixPolicy
The prefix lengths used to group addresses.
Pressure
Adaptive deadlines: past high of max_connections, the handshake and idle deadlines of new and waiting connections are multiplied by factor, down to 1 s, until the count falls below low. No cost below the threshold beyond one check per connection opened or closed.
ProxyFacts
Facts copied from a trusted PROXY header into fixed arrays.
ProxyHeaderproxy
A parsed PROXY header, borrowing from the bytes it was parsed from.
ProxyParserproxy
A sans-IO PROXY header parser for one connection.
ProxySslproxy
The SSL facts a proxy that terminated TLS reports (v2 TLV 0x20).
Rejected
Why Driver::submit refused an operation; it comes back with its buffers.
SendChunks
The bytes of one send: up to 64 chunks, taken from an Output or built from a pool buffer.
Server
A running server. Dropping it stops it (with a drain), so keep it and call Server::wait_for_stop to run until a stop is requested.
ServerBuilder
Builds a Server. A builder without sessions/handler has no build method: forgetting it is a compile error. Without gate every connection is admitted (NoGate, as AllowAll).
ServerHandle
A cloneable handle to a running server, safe to use from any thread.
SessionContext
Everything a session may touch, for one call.
Sessions
What ServerBuilder::sessions produces; programs never name it.
SimpleControl
A control line for programs without their own.
SizeClass
A buffer size class: a power of two from 1 KiB to 1 MiB.
SocketOptions
Live get and set on an open socket.
Stats
Counters summed over the workers.
TcpConnection
A connected TCP socket that carries its own limits.
TcpListener
A listening TCP socket created by net-io, so options that must precede bind can be set.
TcpOptions
Options applied to each accepted or dialed TCP connection. None leaves the OS default.
TlsError
A TLS engine error: codes only, never secret material.
TlsInfo
TLS facts after the handshake, in fixed arrays.
TlsProgress
What one TlsSession::step did.
Tlvproxy
One v2 TLV.
Tlvsproxy
The TLVs of a v2 header, already checked to fit the declared length.
Token
Names a registered socket. The low 32 bits index a dense table inside the driver, so keep them small; the high bits are free for a generation.
TrustedProxies
The proxies whose claims about the client address are believed: PROXY headers here, and X-Forwarded-For / Forwarded in the web layer, which should use the same value. Keep it minimal: a trusted proxy can claim any client address.
UdpBudgetudp
Rates for one budget: datagrams and bytes per second, and how many datagrams may arrive at once. The byte bucket holds one second of bytes.
UdpContextudp
What a UdpSession may do during a call.
UdpOnlyudp
What ServerBuilder::udp_sessions produces when a server has no TCP work; programs never name it.
UdpOptionsudp
Options for UdpSocket::bind_with.
UdpSocketudp
A UDP socket with the guard in front of it.
UdpStatsudp
Counters of one socket since it was bound.
UnixConnectionUnix and local
A connection on a Unix domain socket, with the same limits, deadlines, and close behaviour as TcpConnection.
UnixListenerUnix and local
A Unix domain socket listener. Dropping it removes its socket file, but only while the path still names the file this listener created.
UnixPath
A Unix socket path in a fixed array (up to 108 bytes).
WorkerId
The index of a worker within one server.
WriteCheck
The write the gate is asked about.

Enums§

AddrError
An error parsing or building an address value.
AdmitStage
When Gate::admit runs.
CloseReason
Why a connection closed. Every connection ends with exactly one.
CoalescedKind
What was folded into a Event::Coalesced.
ConfigReason
The rule a configuration value broke.
ControlState
What the control line asks for.
Direction
A direction of transfer.
DoorState
Whether the server is accepting.
DriverKind
Which driver moves the bytes.
Endpoint
One end of a connection.
ErrorClass
The broad kind of a NetError, for policy decisions.
Event
One event: fixed size, Copy, borrowing nothing.
HandoffError
Why a listener hand-off failed. Nothing is adopted on any error.
Health
What TcpConnection::probe found, without waiting or consuming anything.
InheritError
Why inherited descriptors were refused.
LimitKind
Which configured bound was hit.
Linger
What happens to unsent data at close.
LocalConnectionlocal
A local IPC connection: a Unix domain socket, or a Windows named pipe.
LocalListenerlocal
A local IPC listener: a Unix domain socket, or a Windows named pipe.
MulticastInterfaceudp
Which interface joins a multicast group.
NetError
The one error type of the crate.
NoTlsSession
The session type of NoTls; it has no values.
Operation
What to do on a registered socket. The operation owns its buffers until its completion returns them.
OperationKind
Which operation a completion finishes.
Origin
How a connection came to exist.
OsErrorClass
The class of an OS error, without its message text.
Phase
Which deadlines run.
Placement
Where workers run.
PostError
Why a post was refused.
ProxyAddressproxy
An address in a PROXY header.
ProxyCommandproxy
The PROXY command.
ProxyError
Why a PROXY header was refused.
ProxyMode
Whether a listener expects a PROXY protocol header.
ProxyProgressproxy
What ProxyParser::feed found.
ProxyTransportproxy
The transport of the proxied connection.
ProxyVersions
Which PROXY protocol versions a listener accepts.
Refusal
How a connection is refused.
RefusalCause
Why a connection was refused.
Step
What the session wants next.
SwapError
Why a swap was refused.
TimeoutKind
Which deadline passed.
TlsCloseKind
Whether a TLS stream ended with close_notify.
TlsEvent
The next thing the driver does after a step.
TlsFailure
What failed in a TLS engine.
Transport
The kind of socket a connection uses.

Constants§

VERSION
Crate version string, populated by Cargo at build time.

Traits§

Clock
A source of monotonic time.
ControlLine
A process-wide signal (shed, lockdown, drain, stop) that net-io’s workers read at the top of each loop, before each accept batch, and before each admission.
Driver
A driver: one per worker, used from one thread. See the module docs.
EventSink
Receives events. Runs on worker threads: copy what you need and return.
Gate
Decides who may connect and whether bytes may still leave.
Session
A sans-IO protocol engine bound to one connection.
SessionFactory
Creates one session per admitted connection. Any Fn(&ConnectionInfo) -> S is one.
TlsAcceptor
Creates one TlsSession per admitted connection.
TlsSession
One connection’s TLS state machine. Never blocks, never does IO.
UdpSessionudp
A datagram protocol run by a server: one per UDP listener, called on that listener’s thread, so it needs no locks of its own. Budgets and the amplification guard apply before it sees a datagram and on every reply.
UdpSessionFactoryudp
Makes the UdpSession of each UDP listener; any Fn(&ListenerInfo) -> impl UdpSession is one.
Workload
What runs per connection: Sessions or a BlockingHandler. Sealed.

Functions§

connect
Connects with a total timeout of 10 s across every resolved address, TCP_NODELAY on, and default limits (read and write timeouts 30 s).
connect_locallocal
Connects to a local IPC listener (see listen_local); waits up to 10 s when its backlog is full.
descriptor_limit
The process’s open-descriptor limit (RLIMIT_NOFILE, soft) on Unix: what ServerBuilder::build checks a global cap against. None where it is unlimited, and on Windows, where socket handles do not come from a small table. Use it to place a soft cap of your own under the one net-io would pick.
encode_v1proxy
Writes a v1 header for a proxied TCP connection; returns its length (at most 107). For a proxy that speaks PROXY to its backends.
encode_v2proxy
Writes a v2 header; returns its length. None for either address sends UNSPEC, which is what ProxyCommand::Local means. with_crc adds a CRC32C TLV.
fastcgi_listenerUnix
FastCGI’s listening socket (FCGI_LISTENSOCK_FILENO, as mod_fcgid starts a FastCGI server): descriptor 0 is taken only if it is a socket, listening, has no peer, and has close-on-exec clear (it crossed an execve); otherwise None (a terminal, a file, a pipe, a connected socket, a socket this image opened itself). Taken once per process: later calls return None.
listen
Binds a TCP listener with safe defaults: backlog 1,024 (capped by the OS); SO_REUSEADDR on Unix; SO_EXCLUSIVEADDRUSE on Windows; IPv6-only for IPv6 addresses; close-on-exec. The first resolved address that binds wins.
listen_locallocal
Opens a local IPC listener: on Unix, a Unix domain socket at the path name with mode 0600 (only the owner may connect; LocalOptions and UnixListener::bind_with for more). On Windows, the named pipe \\\\.\\pipe\\<name>, owner only, remote clients rejected.
monotonic_micros
The raw monotonic clock in microseconds: CLOCK_MONOTONIC on Linux and macOS, the performance counter on Windows. This is the value systemd’s MONOTONIC_USEC expects (sd_notify reload and watchdog messages); it is not related to Instant values or to Clock.
new_reactor_driverreactor
The reactor driver for this OS: epoll, kqueue, or an I/O completion port. capacity sizes its tables for that many sockets; they grow past it.
normalize
Turns an IPv4-mapped IPv6 address (::ffff:a.b.c.d) into the IPv4 address.
normalize_socket
normalize for a socket address; the port is kept.
recv_listenersUnix and local
Receives listeners from channel. The sender’s credentials must match expect (by default: the same user); the message must be complete, intact (magic, version, CRC32C), carry exactly as many sockets as it lists, and every socket must be a listener bound to the address the manifest names. All or nothing: on any error every received socket is closed.
send_listenersUnix and local
Sends listeners over channel in one message: the manifest and every socket (SCM_RIGHTS). The listeners stay open here; the receiver gets its own copies. At most 64.
serve
Starts a server on the blocking driver that runs handler once per connection on a pool worker, with default limits and AllowAll as the gate; the door is open on return. Ok(()) closes the connection gracefully; Err closes it abortively.
serve_sessions
Starts a server that drives sans-IO Sessions, with default limits and AllowAll as the gate; the door is open on return. Any Fn(&ConnectionInfo) -> S is a factory.
systemd
The listeners systemd passed to this process (socket activation). Reads LISTEN_PID (it must name this process, otherwise the variables were meant for another and the list is empty), LISTEN_PIDFDID where present (Linux: must match this process’s pidfd), LISTEN_FDS (at most 64), and LISTEN_FDNAMES. Every descriptor from 3 is verified (a socket, listening, TCP or Unix stream, close-on-exec clear) before any is taken. Not started by systemd, or a descriptor in the range has close-on-exec set (the variables outlived a re-exec in place): an empty list. A second call returns what earlier calls (including systemd_named) left.
systemd_named
The one listener systemd passed under name (LISTEN_FDNAMES), or None. The others stay for later calls.

Type Aliases§

SharedSocketUnix
A socket as a Driver registers it: shared, so the driver keeps it open until Driver::deregister whatever the caller drops. Any Arc of a socket type converts (Arc<TcpStream>, Arc<TcpListener>, Arc<OwnedFd>); keep a clone to accept from a listener or to read the socket’s options.