net-io 0.8.0

Network IO substrate for Rust: TCP, UDP and local-socket listeners, connection lifecycle, limits, graceful drain, PROXY protocol, and a TLS seam. Protocol-free and dependency-free.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
//! # 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
//!
//! ```no_run
//! 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](https://github.com/jamesgober/net-io).
//!
//! ## 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.

#![doc(html_root_url = "https://docs.rs/net-io")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(unsafe_code)]
#![deny(unsafe_op_in_unsafe_fn)]
#![deny(missing_docs)]
#![cfg_attr(
    not(test),
    deny(
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::todo,
        clippy::unimplemented,
        clippy::dbg_macro,
        clippy::print_stdout,
        clippy::print_stderr
    )
)]

mod accept;
mod addr;
mod buf;
mod completer;
mod control;
mod crc32c;
mod driver;
mod error;
mod events;
mod gate;
mod handoff;
mod id;
mod info;
mod inherit;
mod limits;
mod link;
#[cfg(feature = "local")]
mod local;
#[cfg(all(windows, feature = "local"))]
mod local_windows;
mod opts;
#[cfg(all(windows, feature = "local"))]
mod pipe;
mod proxy;
#[cfg(feature = "proxy")]
mod proxy_parse;
mod rate;
mod retry;
mod server;
mod session;
mod sys;
mod tcp;
#[cfg(test)]
mod testing;
mod time;
mod tls;
mod trusted;
#[cfg(feature = "udp")]
mod udp;
#[cfg_attr(not(test), allow(dead_code))]
mod wheel;

/// Entry points for net-io's fuzz targets (`fuzz/`), compiled only under
/// cargo-fuzz (`--cfg fuzzing`). Not part of the public API and not covered by semver.
#[cfg(fuzzing)]
#[doc(hidden)]
pub mod __fuzz {
    /// The hand-off manifest decoder.
    pub fn manifest(data: &[u8]) {
        crate::handoff::fuzz_manifest(data);
    }

    /// The systemd environment reader.
    pub fn systemd_env(data: &[u8]) {
        crate::inherit::fuzz_systemd_env(data);
    }

    /// The timing wheel against a model.
    pub fn wheel(data: &[u8]) {
        crate::wheel::fuzz_wheel(data);
    }

    /// The minimum-rate counter's invariants.
    pub fn rate(data: &[u8]) {
        crate::rate::fuzz_rate(data);
    }

    /// The UDP guard's tables, verification, and budgets against a model.
    #[cfg(feature = "udp")]
    pub fn udp(data: &[u8]) {
        crate::udp::fuzz_udp(data);
    }
}

/// Fault injection for net-io's own tests, compiled only with `--cfg net_io_shim`.
/// Not part of the public API and not covered by semver.
#[cfg(net_io_shim)]
#[doc(hidden)]
pub mod __shim {
    pub use crate::sys::shim::{Fault, Op, clear, counted, program, start_counting, stop_counting};
}

use std::net::ToSocketAddrs;

pub use addr::{AddrError, Cidr, PrefixKey, PrefixPolicy, normalize, normalize_socket};
pub use buf::{Buffer, BufferPool, PoolStats};
pub use completer::{Completer, PostError};
pub use control::{ControlLine, ControlState, NoControl, SimpleControl};
#[cfg(feature = "reactor")]
pub use driver::new_reactor_driver;
pub use driver::{
    Completion, Completions, Driver, DriverKind, DriverWaker, Operation, OperationKind, Rejected,
    SendChunks, SharedSocket, Token,
};
pub use error::{
    CloseReason, ConfigReason, Direction, ErrorClass, KillReason, LimitKind, NetError,
    OsErrorClass, RefusalCause, TimeoutKind,
};
pub use events::{CoalescedKind, Event, EventSink, NoopSink};
pub use gate::{AdmitStage, Admitted, AllowAll, Denial, Gate, KillHandle, Refusal, WriteCheck};
pub use handoff::{HandoffError, HandoffPeer, ListenerHandle};
#[cfg(all(windows, feature = "local"))]
pub use handoff::{SharedListeners, receive_shared, share_listeners};
#[cfg(all(unix, feature = "local"))]
pub use handoff::{recv_listeners, send_listeners};
pub use id::{ConnectionId, ListenerId, WorkerId};
pub use info::{
    ConnectionInfo, Endpoint, GateTag, Lane, Origin, PeerCredentials, PipeName, Transport, UnixPath,
};
#[cfg(unix)]
pub use inherit::fastcgi_listener;
pub use inherit::{InheritError, InheritedListener, systemd, systemd_named};
pub use limits::{Limits, LimitsBuilder, MinRate, Pressure, SizeClass, descriptor_limit};
#[cfg(all(unix, feature = "local"))]
pub use local::{Descriptors, UnixConnection, UnixListener};
#[cfg(feature = "local")]
pub use local::{LocalConnection, LocalListener};
#[cfg(all(windows, feature = "local"))]
pub use local_windows::{UnixConnection, UnixListener};
pub use opts::{Keepalive, Linger, ListenOptions, LocalOptions, SocketOptions, TcpOptions};
#[cfg(all(windows, feature = "local"))]
pub use pipe::{PipeConnection, PipeListener, PipeOptions, PipeSecurity};
pub use proxy::{ProxyError, ProxyFacts, ProxyMode, ProxyVersions};
#[cfg(feature = "proxy")]
pub use proxy_parse::{
    ProxyAddress, ProxyCommand, ProxyHeader, ProxyParser, ProxyProgress, ProxySsl, ProxyTransport,
    Tlv, Tlvs, encode_v1, encode_v2,
};
pub use retry::Backoff;
#[cfg(feature = "udp")]
pub use server::UdpOnly;
pub use server::{
    AdoptSpec, BlockingHandler, DoorState, DrainReport, ListenerSpec, NoGate, NoWork, Placement,
    Server, ServerBuilder, ServerHandle, Sessions, Stats, Workload,
};
pub use session::{
    Input, Output, OutputFull, Phase, Session, SessionContext, SessionFactory, Step, SwapError,
};
pub use tcp::{ConnectOptions, Drained, Health, ListenerInfo, TcpConnection, TcpListener};
pub use time::{Clock, ManualClock, MonotonicClock, monotonic_micros};
pub use tls::{
    NoTls, NoTlsSession, TlsAcceptor, TlsCloseKind, TlsError, TlsEvent, TlsFailure, TlsInfo,
    TlsProgress, TlsSession,
};
pub use trusted::TrustedProxies;
#[cfg(feature = "udp")]
pub use udp::{
    Datagram, DatagramBuffer, MulticastInterface, OutgoingDatagram, UdpBudget, UdpContext,
    UdpOptions, UdpSession, UdpSessionFactory, UdpSocket, UdpStats,
};

/// Crate version string, populated by Cargo at build time.
///
/// ```
/// assert!(!net_io::VERSION.is_empty());
/// ```
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// 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.
///
/// # Errors
///
/// `AddrInUse`, `PermissionDenied`, `AddrNotAvailable`, `NoAddresses`, `Bind`.
///
/// # Examples
///
/// ```
/// let listener = net_io::listen("127.0.0.1:0")?;
/// let addr = listener.local_addr()?;
/// println!("listening on {addr}, backlog {:?}", listener.info().backlog);
/// # Ok::<(), net_io::NetError>(())
/// ```
pub fn listen<A: ToSocketAddrs>(addr: A) -> Result<TcpListener, NetError> {
    TcpListener::bind(addr)
}

/// Connects with a total timeout of 10 s across every resolved address,
/// `TCP_NODELAY` on, and default limits (read and write timeouts 30 s).
///
/// # Errors
///
/// `ConnectTimeout`, `ConnectionRefused`, `HostUnreachable`, `NetworkUnreachable`, `NoAddresses`.
///
/// # Examples
///
/// ```no_run
/// let mut conn = net_io::connect("example.com:80")?;
/// conn.send_all(b"HEAD / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")?;
/// let mut head = [0u8; 512];
/// let n = conn.recv(&mut head)?;
/// println!("{}", String::from_utf8_lossy(&head[..n]));
/// # Ok::<(), net_io::NetError>(())
/// ```
pub fn connect<A: ToSocketAddrs>(addr: A) -> Result<TcpConnection, NetError> {
    TcpConnection::connect(addr)
}

/// 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.
///
/// Keep the returned `Server`: dropping it stops the server. A server facing
/// the internet should set a [`Gate`] through [`ServerBuilder`].
///
/// # Errors
///
/// As [`listen`]; `InvalidConfig` when the worker count exceeds the descriptor limit.
///
/// # Examples
///
/// ```no_run
/// use std::io::{BufRead, BufReader, Write};
///
/// // Handlers can use std::io traits: TcpConnection implements Read and Write.
/// let server = net_io::serve("127.0.0.1:7001", |conn| {
///     let mut line = String::new();
///     BufReader::new(&mut *conn).read_line(&mut line)?;
///     conn.write_all(line.to_uppercase().as_bytes())?;
///     Ok(())
/// })?;
/// server.wait_for_stop();
/// # Ok::<(), net_io::NetError>(())
/// ```
pub fn serve<A, F>(addr: A, handler: F) -> Result<Server, NetError>
where
    A: ToSocketAddrs,
    F: Fn(&mut TcpConnection) -> Result<(), NetError> + Send + Sync + 'static,
{
    let server = ServerBuilder::new()
        .listener(ListenerSpec::tcp(addr))
        .driver(DriverKind::Blocking)
        .handler(handler)
        .gate(AllowAll)
        .build()?;
    server.open_door()?;
    Ok(server)
}

/// Starts a server that drives sans-IO [`Session`]s, with default limits and
/// [`AllowAll`] as the gate; the door is open on return. Any
/// `Fn(&ConnectionInfo) -> S` is a factory.
///
/// # Errors
///
/// As [`serve`].
///
/// # Examples
///
/// ```no_run
/// use net_io::{Input, Session, SessionContext, Step};
///
/// struct Echo;
/// impl Session for Echo {
///     fn on_data(&mut self, cx: &mut SessionContext<'_>, input: &mut Input) -> Step {
///         let taken = cx.output().push_partial(input.bytes());
///         input.consume(taken);
///         Step::Write
///     }
/// }
///
/// let server = net_io::serve_sessions("127.0.0.1:7002", |_info: &net_io::ConnectionInfo| Echo)?;
/// server.wait_for_stop();
/// # Ok::<(), net_io::NetError>(())
/// ```
pub fn serve_sessions<A, F>(addr: A, factory: F) -> Result<Server, NetError>
where
    A: ToSocketAddrs,
    F: SessionFactory,
{
    let server = ServerBuilder::new()
        .listener(ListenerSpec::tcp(addr))
        .sessions(factory)
        .gate(AllowAll)
        .build()?;
    server.open_door()?;
    Ok(server)
}

/// 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.
///
/// # Errors
///
/// `PathTooLong`, `StaleSocketInUse` (a live listener owns the path, or it is
/// not a socket), `PermissionDenied`, `NotFound`, `Unsupported`, `Os`.
///
/// ```no_run
/// let listener = net_io::listen_local("/run/myapp/control.sock")?;
/// let (mut conn, info) = listener.accept()?;
/// println!("peer process {:?}", info.peer_credentials.and_then(|c| c.pid));
/// conn.send_all(b"ok\n")?;
/// # Ok::<(), net_io::NetError>(())
/// ```
#[cfg(feature = "local")]
pub fn listen_local(name: &str) -> Result<LocalListener, NetError> {
    local::listen(name)
}

/// Connects to a local IPC listener (see [`listen_local`]); waits up to 10 s
/// when its backlog is full.
///
/// # Errors
///
/// `NotFound` (no socket, or nobody listening), `PermissionDenied`,
/// `TimedOut { kind: Connect }`, `PathTooLong`, `Unsupported`, `Os`.
///
/// ```no_run
/// let mut conn = net_io::connect_local("/run/myapp/control.sock")?;
/// conn.send_all(b"status\n")?;
/// # Ok::<(), net_io::NetError>(())
/// ```
#[cfg(feature = "local")]
pub fn connect_local(name: &str) -> Result<LocalConnection, NetError> {
    local::connect(name)
}

#[cfg(test)]
mod tests {
    use super::VERSION;

    #[test]
    fn test_version_matches_manifest() {
        assert_eq!(VERSION, env!("CARGO_PKG_VERSION"));
        assert_eq!(VERSION.split('.').count(), 3, "expected MAJOR.MINOR.PATCH");
    }
}