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}