Skip to main content

net_io/
lib.rs

1//! # net_io
2//!
3//! The network IO substrate for the `-net` and `-io` crates: the entrance and
4//! exit every service shares. It owns listeners and sockets, the life of each
5//! connection, the limits and timeouts that keep a peer from holding what it
6//! should not, graceful drain, and the seams a connection gate and a TLS engine
7//! plug into. It is protocol-free and has no runtime dependencies.
8//!
9//! ## Quick start
10//!
11//! ```no_run
12//! fn main() -> Result<(), net_io::NetError> {
13//!     // An echo server: one handler call per connection on a bounded worker pool,
14//!     // with every default limit (idle, read, write, minimum rate, caps) applied.
15//!     let server = net_io::serve("127.0.0.1:7000", |conn| {
16//!         let mut buf = [0u8; 4096];
17//!         loop {
18//!             let n = conn.recv(&mut buf)?;
19//!             if n == 0 {
20//!                 return Ok(()); // the peer closed its side
21//!             }
22//!             conn.send_all(&buf[..n])?;
23//!         }
24//!     })?;
25//!
26//!     // A client.
27//!     let mut conn = net_io::connect("127.0.0.1:7000")?;
28//!     conn.send_all(b"ping")?;
29//!     let mut reply = [0u8; 4];
30//!     conn.recv_exact(&mut reply)?;
31//!     assert_eq!(&reply, b"ping");
32//!
33//!     // Stop: close the door, drain open connections, join the workers.
34//!     server.handle().request_stop();
35//!     let report = server.wait_for_stop();
36//!     println!("{} closed gracefully, {} killed", report.graceful, report.killed);
37//!     Ok(())
38//! }
39//! ```
40//!
41//! Everything else (several listeners, a gate, events, the control line) goes
42//! through [`ServerBuilder`]. The full reference with every item, its errors,
43//! and its cost is `docs/API.md` in the
44//! [repository](https://github.com/jamesgober/net-io).
45//!
46//! ## Status
47//!
48//! `0.8.0`, alpha: the reactor on epoll, kqueue, and IOCP, and the blocking pool, on
49//! Linux, macOS, FreeBSD, and Windows. TCP with a client that reconnects with
50//! backoff, Unix domain sockets (AF_UNIX on Windows), Windows named pipes, and UDP
51//! with batches and sessions; zero-copy file sends and file receives; the PROXY
52//! protocol, the TLS seam, systemd and FastCGI inheritance, listener hand-off on Unix
53//! and Windows, and the public [`Driver`] interface. Hardened: an attack test per
54//! threat, continuous fuzzing, and a 24-hour soak. `0.8.0` adds what the first
55//! consumers needed: flush-then-close, a drain hook, and workers kept for a listener.
56
57#![doc(html_root_url = "https://docs.rs/net-io")]
58#![cfg_attr(docsrs, feature(doc_cfg))]
59#![deny(unsafe_code)]
60#![deny(unsafe_op_in_unsafe_fn)]
61#![deny(missing_docs)]
62#![cfg_attr(
63    not(test),
64    deny(
65        clippy::unwrap_used,
66        clippy::expect_used,
67        clippy::panic,
68        clippy::todo,
69        clippy::unimplemented,
70        clippy::dbg_macro,
71        clippy::print_stdout,
72        clippy::print_stderr
73    )
74)]
75
76mod accept;
77mod addr;
78mod buf;
79mod completer;
80mod control;
81mod crc32c;
82mod driver;
83mod error;
84mod events;
85mod gate;
86mod handoff;
87mod id;
88mod info;
89mod inherit;
90mod limits;
91mod link;
92#[cfg(feature = "local")]
93mod local;
94#[cfg(all(windows, feature = "local"))]
95mod local_windows;
96mod opts;
97#[cfg(all(windows, feature = "local"))]
98mod pipe;
99mod proxy;
100#[cfg(feature = "proxy")]
101mod proxy_parse;
102mod rate;
103mod retry;
104mod server;
105mod session;
106mod sys;
107mod tcp;
108#[cfg(test)]
109mod testing;
110mod time;
111mod tls;
112mod trusted;
113#[cfg(feature = "udp")]
114mod udp;
115#[cfg_attr(not(test), allow(dead_code))]
116mod wheel;
117
118/// Entry points for net-io's fuzz targets (`fuzz/`), compiled only under
119/// cargo-fuzz (`--cfg fuzzing`). Not part of the public API and not covered by semver.
120#[cfg(fuzzing)]
121#[doc(hidden)]
122pub mod __fuzz {
123    /// The hand-off manifest decoder.
124    pub fn manifest(data: &[u8]) {
125        crate::handoff::fuzz_manifest(data);
126    }
127
128    /// The systemd environment reader.
129    pub fn systemd_env(data: &[u8]) {
130        crate::inherit::fuzz_systemd_env(data);
131    }
132
133    /// The timing wheel against a model.
134    pub fn wheel(data: &[u8]) {
135        crate::wheel::fuzz_wheel(data);
136    }
137
138    /// The minimum-rate counter's invariants.
139    pub fn rate(data: &[u8]) {
140        crate::rate::fuzz_rate(data);
141    }
142
143    /// The UDP guard's tables, verification, and budgets against a model.
144    #[cfg(feature = "udp")]
145    pub fn udp(data: &[u8]) {
146        crate::udp::fuzz_udp(data);
147    }
148}
149
150/// Fault injection for net-io's own tests, compiled only with `--cfg net_io_shim`.
151/// Not part of the public API and not covered by semver.
152#[cfg(net_io_shim)]
153#[doc(hidden)]
154pub mod __shim {
155    pub use crate::sys::shim::{Fault, Op, clear, counted, program, start_counting, stop_counting};
156}
157
158use std::net::ToSocketAddrs;
159
160pub use addr::{AddrError, Cidr, PrefixKey, PrefixPolicy, normalize, normalize_socket};
161pub use buf::{Buffer, BufferPool, PoolStats};
162pub use completer::{Completer, PostError};
163pub use control::{ControlLine, ControlState, NoControl, SimpleControl};
164#[cfg(feature = "reactor")]
165pub use driver::new_reactor_driver;
166pub use driver::{
167    Completion, Completions, Driver, DriverKind, DriverWaker, Operation, OperationKind, Rejected,
168    SendChunks, SharedSocket, Token,
169};
170pub use error::{
171    CloseReason, ConfigReason, Direction, ErrorClass, KillReason, LimitKind, NetError,
172    OsErrorClass, RefusalCause, TimeoutKind,
173};
174pub use events::{CoalescedKind, Event, EventSink, NoopSink};
175pub use gate::{AdmitStage, Admitted, AllowAll, Denial, Gate, KillHandle, Refusal, WriteCheck};
176pub use handoff::{HandoffError, HandoffPeer, ListenerHandle};
177#[cfg(all(windows, feature = "local"))]
178pub use handoff::{SharedListeners, receive_shared, share_listeners};
179#[cfg(all(unix, feature = "local"))]
180pub use handoff::{recv_listeners, send_listeners};
181pub use id::{ConnectionId, ListenerId, WorkerId};
182pub use info::{
183    ConnectionInfo, Endpoint, GateTag, Lane, Origin, PeerCredentials, PipeName, Transport, UnixPath,
184};
185#[cfg(unix)]
186pub use inherit::fastcgi_listener;
187pub use inherit::{InheritError, InheritedListener, systemd, systemd_named};
188pub use limits::{Limits, LimitsBuilder, MinRate, Pressure, SizeClass, descriptor_limit};
189#[cfg(all(unix, feature = "local"))]
190pub use local::{Descriptors, UnixConnection, UnixListener};
191#[cfg(feature = "local")]
192pub use local::{LocalConnection, LocalListener};
193#[cfg(all(windows, feature = "local"))]
194pub use local_windows::{UnixConnection, UnixListener};
195pub use opts::{Keepalive, Linger, ListenOptions, LocalOptions, SocketOptions, TcpOptions};
196#[cfg(all(windows, feature = "local"))]
197pub use pipe::{PipeConnection, PipeListener, PipeOptions, PipeSecurity};
198pub use proxy::{ProxyError, ProxyFacts, ProxyMode, ProxyVersions};
199#[cfg(feature = "proxy")]
200pub use proxy_parse::{
201    ProxyAddress, ProxyCommand, ProxyHeader, ProxyParser, ProxyProgress, ProxySsl, ProxyTransport,
202    Tlv, Tlvs, encode_v1, encode_v2,
203};
204pub use retry::Backoff;
205#[cfg(feature = "udp")]
206pub use server::UdpOnly;
207pub use server::{
208    AdoptSpec, BlockingHandler, DoorState, DrainReport, ListenerSpec, NoGate, NoWork, Placement,
209    Server, ServerBuilder, ServerHandle, Sessions, Stats, Workload,
210};
211pub use session::{
212    Input, Output, OutputFull, Phase, Session, SessionContext, SessionFactory, Step, SwapError,
213};
214pub use tcp::{ConnectOptions, Drained, Health, ListenerInfo, TcpConnection, TcpListener};
215pub use time::{Clock, ManualClock, MonotonicClock, monotonic_micros};
216pub use tls::{
217    NoTls, NoTlsSession, TlsAcceptor, TlsCloseKind, TlsError, TlsEvent, TlsFailure, TlsInfo,
218    TlsProgress, TlsSession,
219};
220pub use trusted::TrustedProxies;
221#[cfg(feature = "udp")]
222pub use udp::{
223    Datagram, DatagramBuffer, MulticastInterface, OutgoingDatagram, UdpBudget, UdpContext,
224    UdpOptions, UdpSession, UdpSessionFactory, UdpSocket, UdpStats,
225};
226
227/// Crate version string, populated by Cargo at build time.
228///
229/// ```
230/// assert!(!net_io::VERSION.is_empty());
231/// ```
232pub const VERSION: &str = env!("CARGO_PKG_VERSION");
233
234/// Binds a TCP listener with safe defaults: backlog 1,024 (capped by the OS);
235/// `SO_REUSEADDR` on Unix; `SO_EXCLUSIVEADDRUSE` on Windows; IPv6-only for IPv6
236/// addresses; close-on-exec. The first resolved address that binds wins.
237///
238/// # Errors
239///
240/// `AddrInUse`, `PermissionDenied`, `AddrNotAvailable`, `NoAddresses`, `Bind`.
241///
242/// # Examples
243///
244/// ```
245/// let listener = net_io::listen("127.0.0.1:0")?;
246/// let addr = listener.local_addr()?;
247/// println!("listening on {addr}, backlog {:?}", listener.info().backlog);
248/// # Ok::<(), net_io::NetError>(())
249/// ```
250pub fn listen<A: ToSocketAddrs>(addr: A) -> Result<TcpListener, NetError> {
251    TcpListener::bind(addr)
252}
253
254/// Connects with a total timeout of 10 s across every resolved address,
255/// `TCP_NODELAY` on, and default limits (read and write timeouts 30 s).
256///
257/// # Errors
258///
259/// `ConnectTimeout`, `ConnectionRefused`, `HostUnreachable`, `NetworkUnreachable`, `NoAddresses`.
260///
261/// # Examples
262///
263/// ```no_run
264/// let mut conn = net_io::connect("example.com:80")?;
265/// conn.send_all(b"HEAD / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")?;
266/// let mut head = [0u8; 512];
267/// let n = conn.recv(&mut head)?;
268/// println!("{}", String::from_utf8_lossy(&head[..n]));
269/// # Ok::<(), net_io::NetError>(())
270/// ```
271pub fn connect<A: ToSocketAddrs>(addr: A) -> Result<TcpConnection, NetError> {
272    TcpConnection::connect(addr)
273}
274
275/// Starts a server on the blocking driver that runs `handler` once per
276/// connection on a pool worker, with default limits and [`AllowAll`] as the
277/// gate; the door is open on return. `Ok(())` closes the connection
278/// gracefully; `Err` closes it abortively.
279///
280/// Keep the returned `Server`: dropping it stops the server. A server facing
281/// the internet should set a [`Gate`] through [`ServerBuilder`].
282///
283/// # Errors
284///
285/// As [`listen`]; `InvalidConfig` when the worker count exceeds the descriptor limit.
286///
287/// # Examples
288///
289/// ```no_run
290/// use std::io::{BufRead, BufReader, Write};
291///
292/// // Handlers can use std::io traits: TcpConnection implements Read and Write.
293/// let server = net_io::serve("127.0.0.1:7001", |conn| {
294///     let mut line = String::new();
295///     BufReader::new(&mut *conn).read_line(&mut line)?;
296///     conn.write_all(line.to_uppercase().as_bytes())?;
297///     Ok(())
298/// })?;
299/// server.wait_for_stop();
300/// # Ok::<(), net_io::NetError>(())
301/// ```
302pub fn serve<A, F>(addr: A, handler: F) -> Result<Server, NetError>
303where
304    A: ToSocketAddrs,
305    F: Fn(&mut TcpConnection) -> Result<(), NetError> + Send + Sync + 'static,
306{
307    let server = ServerBuilder::new()
308        .listener(ListenerSpec::tcp(addr))
309        .driver(DriverKind::Blocking)
310        .handler(handler)
311        .gate(AllowAll)
312        .build()?;
313    server.open_door()?;
314    Ok(server)
315}
316
317/// Starts a server that drives sans-IO [`Session`]s, with default limits and
318/// [`AllowAll`] as the gate; the door is open on return. Any
319/// `Fn(&ConnectionInfo) -> S` is a factory.
320///
321/// # Errors
322///
323/// As [`serve`].
324///
325/// # Examples
326///
327/// ```no_run
328/// use net_io::{Input, Session, SessionContext, Step};
329///
330/// struct Echo;
331/// impl Session for Echo {
332///     fn on_data(&mut self, cx: &mut SessionContext<'_>, input: &mut Input) -> Step {
333///         let taken = cx.output().push_partial(input.bytes());
334///         input.consume(taken);
335///         Step::Write
336///     }
337/// }
338///
339/// let server = net_io::serve_sessions("127.0.0.1:7002", |_info: &net_io::ConnectionInfo| Echo)?;
340/// server.wait_for_stop();
341/// # Ok::<(), net_io::NetError>(())
342/// ```
343pub fn serve_sessions<A, F>(addr: A, factory: F) -> Result<Server, NetError>
344where
345    A: ToSocketAddrs,
346    F: SessionFactory,
347{
348    let server = ServerBuilder::new()
349        .listener(ListenerSpec::tcp(addr))
350        .sessions(factory)
351        .gate(AllowAll)
352        .build()?;
353    server.open_door()?;
354    Ok(server)
355}
356
357/// Opens a local IPC listener: on Unix, a Unix domain socket at the path `name`
358/// with mode `0600` (only the owner may connect; [`LocalOptions`] and
359/// `UnixListener::bind_with` for more). On Windows, the named pipe
360/// `\\\\.\\pipe\\<name>`, owner only, remote clients rejected.
361///
362/// # Errors
363///
364/// `PathTooLong`, `StaleSocketInUse` (a live listener owns the path, or it is
365/// not a socket), `PermissionDenied`, `NotFound`, `Unsupported`, `Os`.
366///
367/// ```no_run
368/// let listener = net_io::listen_local("/run/myapp/control.sock")?;
369/// let (mut conn, info) = listener.accept()?;
370/// println!("peer process {:?}", info.peer_credentials.and_then(|c| c.pid));
371/// conn.send_all(b"ok\n")?;
372/// # Ok::<(), net_io::NetError>(())
373/// ```
374#[cfg(feature = "local")]
375pub fn listen_local(name: &str) -> Result<LocalListener, NetError> {
376    local::listen(name)
377}
378
379/// Connects to a local IPC listener (see [`listen_local`]); waits up to 10 s
380/// when its backlog is full.
381///
382/// # Errors
383///
384/// `NotFound` (no socket, or nobody listening), `PermissionDenied`,
385/// `TimedOut { kind: Connect }`, `PathTooLong`, `Unsupported`, `Os`.
386///
387/// ```no_run
388/// let mut conn = net_io::connect_local("/run/myapp/control.sock")?;
389/// conn.send_all(b"status\n")?;
390/// # Ok::<(), net_io::NetError>(())
391/// ```
392#[cfg(feature = "local")]
393pub fn connect_local(name: &str) -> Result<LocalConnection, NetError> {
394    local::connect(name)
395}
396
397#[cfg(test)]
398mod tests {
399    use super::VERSION;
400
401    #[test]
402    fn test_version_matches_manifest() {
403        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
404        assert_eq!(VERSION.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
405    }
406}