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.
- Adopt
Spec - Where
Server::adoptregisters a connection: the listener (by name) whose limits and caps apply, and an optional starting lane (the gate may change it). - Allow
All - The explicit “no gate”: admits every connection in
Lane(0)withGateTag(0)and never denies. - Backoff
- Delays between attempts:
first, doubling each attempt up tomax, 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). - Blocking
Handler - What
ServerBuilder::handlerproduces; programs never name it. - Buffer
- A byte buffer from a pool: a fixed capacity (its size class) and a filled length.
- Buffer
Pool - 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.
- Connect
Options - Options for an outbound connection.
- Connection
Id - The identity of one connection, unique and never reused within a process.
- Connection
Info - What net-io knows about one connection, built at accept and completed as the handshake reveals more. It holds no heap memory.
- Datagram
udp - One received datagram.
- Datagram
Buffer udp - A receive buffer of a batch;
UdpSocket::recv_batchfillsdatagram. - Denial
- A gate’s refusal of a write.
- Descriptors
Unix 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. - Drain
Report - What a drain did.
- Drained
- What
TcpConnection::drainsaw before closing. - Driver
Waker - Wakes a driver’s
Driver::waitfrom any thread. - GateTag
- An opaque value the gate returns at admission, stored in
ConnectionInfo::gate. - Handoff
Peer - Whom
recv_listenersaccepts listeners from.uid: Nonemeans this process’s own effective user id;pid: Noneaccepts any process of that user. - Inherited
Listener - A listener systemd passed to this process, with its
LISTEN_FDNAMESname. - 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.
- Kill
Handle - Closes one connection abortively from any thread.
- Kill
Reason - 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.
- Limits
Builder - Builds
Limits; every setter is optional. - Listen
Options - Options set on a listening socket before
bindandlisten. - Listener
Handle - 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, andServer::release_listeners; used byListenerSpec::adopt. - Listener
Id - The index of a listener within one server.
- Listener
Info - Facts about one bound listener.
- Listener
Spec - One listener of a server.
- Local
Options - 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. - Manual
Clock - 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.
- Monotonic
Clock Instant::now().- NoControl
- A control line that never changes:
epoch()is always 0. - NoGate
- The builder’s gate until
ServerBuilder::gatenames one: every connection is admitted, in the most important lane, as withAllowAll, 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
buildexists for it). - Noop
Sink - Discards every event; the builder’s default. Compiles to nothing.
- Outgoing
Datagram udp - One datagram of a batch to send.
- Output
- What the session wants written: a bounded queue of chunks.
- Output
Full - The output budget was reached; return
Step::Writeand continue after the flush. - Peer
Credentials - Who is on the other end of a local socket. A field the platform cannot report is
None. - Pipe
Name - A Windows pipe name in a fixed array (up to 256 UTF-16 units).
- Pool
Stats - Counts of one pool.
- Prefix
Key - “This address at this prefix length” as a fixed-size
Copyhash key. - Prefix
Policy - The prefix lengths used to group addresses.
- Pressure
- Adaptive deadlines: past
highofmax_connections, the handshake and idle deadlines of new and waiting connections are multiplied byfactor, down to 1 s, until the count falls belowlow. No cost below the threshold beyond one check per connection opened or closed. - Proxy
Facts - Facts copied from a trusted PROXY header into fixed arrays.
- Proxy
Header proxy - A parsed PROXY header, borrowing from the bytes it was parsed from.
- Proxy
Parser proxy - A sans-IO PROXY header parser for one connection.
- Proxy
Ssl proxy - The SSL facts a proxy that terminated TLS reports (v2 TLV
0x20). - Rejected
- Why
Driver::submitrefused an operation; it comes back with its buffers. - Send
Chunks - The bytes of one send: up to 64 chunks, taken from an
Outputor built from a pool buffer. - Server
- A running server. Dropping it stops it (with a drain), so keep it and call
Server::wait_for_stopto run until a stop is requested. - Server
Builder - Builds a
Server. A builder withoutsessions/handlerhas nobuildmethod: forgetting it is a compile error. Withoutgateevery connection is admitted (NoGate, asAllowAll). - Server
Handle - A cloneable handle to a running server, safe to use from any thread.
- Session
Context - Everything a session may touch, for one call.
- Sessions
- What
ServerBuilder::sessionsproduces; programs never name it. - Simple
Control - A control line for programs without their own.
- Size
Class - A buffer size class: a power of two from 1 KiB to 1 MiB.
- Socket
Options - 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
bindcan be set. - TcpOptions
- Options applied to each accepted or dialed TCP connection.
Noneleaves 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::stepdid. - Tlv
proxy - One v2 TLV.
- Tlvs
proxy - 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.
- Trusted
Proxies - The proxies whose claims about the client address are believed: PROXY
headers here, and
X-Forwarded-For/Forwardedin the web layer, which should use the same value. Keep it minimal: a trusted proxy can claim any client address. - UdpBudget
udp - 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.
- UdpContext
udp - What a
UdpSessionmay do during a call. - UdpOnly
udp - What
ServerBuilder::udp_sessionsproduces when a server has no TCP work; programs never name it. - UdpOptions
udp - Options for
UdpSocket::bind_with. - UdpSocket
udp - A UDP socket with the guard in front of it.
- UdpStats
udp - Counters of one socket since it was bound.
- Unix
Connection Unix and local - A connection on a Unix domain socket, with the same limits, deadlines,
and close behaviour as
TcpConnection. - Unix
Listener Unix 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.
- Unix
Path - A Unix socket path in a fixed array (up to 108 bytes).
- Worker
Id - The index of a worker within one server.
- Write
Check - The write the gate is asked about.
Enums§
- Addr
Error - An error parsing or building an address value.
- Admit
Stage - When
Gate::admitruns. - Close
Reason - Why a connection closed. Every connection ends with exactly one.
- Coalesced
Kind - What was folded into a
Event::Coalesced. - Config
Reason - The rule a configuration value broke.
- Control
State - What the control line asks for.
- Direction
- A direction of transfer.
- Door
State - Whether the server is accepting.
- Driver
Kind - Which driver moves the bytes.
- Endpoint
- One end of a connection.
- Error
Class - The broad kind of a
NetError, for policy decisions. - Event
- One event: fixed size,
Copy, borrowing nothing. - Handoff
Error - Why a listener hand-off failed. Nothing is adopted on any error.
- Health
- What
TcpConnection::probefound, without waiting or consuming anything. - Inherit
Error - Why inherited descriptors were refused.
- Limit
Kind - Which configured bound was hit.
- Linger
- What happens to unsent data at close.
- Local
Connection local - A local IPC connection: a Unix domain socket, or a Windows named pipe.
- Local
Listener local - A local IPC listener: a Unix domain socket, or a Windows named pipe.
- Multicast
Interface udp - Which interface joins a multicast group.
- NetError
- The one error type of the crate.
- NoTls
Session - 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.
- Operation
Kind - Which operation a completion finishes.
- Origin
- How a connection came to exist.
- OsError
Class - The class of an OS error, without its message text.
- Phase
- Which deadlines run.
- Placement
- Where workers run.
- Post
Error - Why a post was refused.
- Proxy
Address proxy - An address in a PROXY header.
- Proxy
Command proxy - The PROXY command.
- Proxy
Error - Why a PROXY header was refused.
- Proxy
Mode - Whether a listener expects a PROXY protocol header.
- Proxy
Progress proxy - What
ProxyParser::feedfound. - Proxy
Transport proxy - The transport of the proxied connection.
- Proxy
Versions - Which PROXY protocol versions a listener accepts.
- Refusal
- How a connection is refused.
- Refusal
Cause - Why a connection was refused.
- Step
- What the session wants next.
- Swap
Error - Why a swap was refused.
- Timeout
Kind - Which deadline passed.
- TlsClose
Kind - 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.
- Control
Line - 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.
- Event
Sink - 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.
- Session
Factory - Creates one session per admitted connection. Any
Fn(&ConnectionInfo) -> Sis one. - TlsAcceptor
- Creates one
TlsSessionper admitted connection. - TlsSession
- One connection’s TLS state machine. Never blocks, never does IO.
- UdpSession
udp - 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.
- UdpSession
Factory udp - Makes the
UdpSessionof each UDP listener; anyFn(&ListenerInfo) -> impl UdpSessionis one. - Workload
- What runs per connection:
Sessionsor aBlockingHandler. Sealed.
Functions§
- connect
- Connects with a total timeout of 10 s across every resolved address,
TCP_NODELAYon, and default limits (read and write timeouts 30 s). - connect_
local local - 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: whatServerBuilder::buildchecks a global cap against.Nonewhere 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_
v1 proxy - 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_
v2 proxy - Writes a v2 header; returns its length.
Nonefor either address sendsUNSPEC, which is whatProxyCommand::Localmeans.with_crcadds a CRC32C TLV. - fastcgi_
listener Unix - FastCGI’s listening socket (
FCGI_LISTENSOCK_FILENO, asmod_fcgidstarts 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 anexecve); otherwiseNone(a terminal, a file, a pipe, a connected socket, a socket this image opened itself). Taken once per process: later calls returnNone. - listen
- Binds a TCP listener with safe defaults: backlog 1,024 (capped by the OS);
SO_REUSEADDRon Unix;SO_EXCLUSIVEADDRUSEon Windows; IPv6-only for IPv6 addresses; close-on-exec. The first resolved address that binds wins. - listen_
local local - Opens a local IPC listener: on Unix, a Unix domain socket at the path
namewith mode0600(only the owner may connect;LocalOptionsandUnixListener::bind_withfor more). On Windows, the named pipe\\\\.\\pipe\\<name>, owner only, remote clients rejected. - monotonic_
micros - The raw monotonic clock in microseconds:
CLOCK_MONOTONICon Linux and macOS, the performance counter on Windows. This is the value systemd’sMONOTONIC_USECexpects (sd_notifyreload and watchdog messages); it is not related toInstantvalues or toClock. - new_
reactor_ driver reactor - The reactor driver for this OS: epoll, kqueue, or an I/O completion port.
capacitysizes 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 normalizefor a socket address; the port is kept.- recv_
listeners Unix and local - Receives listeners from
channel. The sender’s credentials must matchexpect(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_
listeners Unix and local - Sends
listenersoverchannelin 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
handleronce per connection on a pool worker, with default limits andAllowAllas the gate; the door is open on return.Ok(())closes the connection gracefully;Errcloses it abortively. - serve_
sessions - Starts a server that drives sans-IO
Sessions, with default limits andAllowAllas the gate; the door is open on return. AnyFn(&ConnectionInfo) -> Sis 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_PIDFDIDwhere present (Linux: must match this process’s pidfd),LISTEN_FDS(at most 64), andLISTEN_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 (includingsystemd_named) left. - systemd_
named - The one listener systemd passed under
name(LISTEN_FDNAMES), orNone. The others stay for later calls.
Type Aliases§
- Shared
Socket Unix - A socket as a
Driverregisters it: shared, so the driver keeps it open untilDriver::deregisterwhatever the caller drops. AnyArcof 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.