Crate net_io

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.6.0: the reactor on epoll, kqueue, and IOCP, and the blocking pool, on Linux, macOS, FreeBSD, and Windows. TCP, Unix domain sockets (AF_UNIX on Windows), Windows named pipes, and UDP with batches and sessions; zero-copy file sends; the PROXY protocol, the TLS seam, systemd and FastCGI inheritance, listener hand-off on Unix and Windows, and the public Driver interface.

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.
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.
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 unset gate (no build exists for it): name AllowAll to run without a gate.
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 a gate or without sessions/handler has no build method: forgetting either is a compile error.
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.
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.
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, and has no peer; otherwise None (a terminal, a file, a pipe, a connected socket). 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) before any is taken. Not started by systemd: 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§

BorrowedSocketUnix: A borrowed socket, as a Driver registers it.

Crate net_io

Crate net_io Copy item path

§net_io

§Quick start

§Status

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate net_io