Skip to main content

net_io/server/
mod.rs

1//! The server: listeners, workers, the door, drain, and shutdown.
2
3mod engine;
4#[cfg(feature = "reactor")]
5mod reactor;
6mod source;
7
8use std::any::TypeId;
9use std::fmt;
10use std::net::{SocketAddr, ToSocketAddrs};
11use std::path::PathBuf;
12use std::sync::Arc;
13use std::thread::JoinHandle;
14use std::time::{Duration, Instant};
15
16use crate::control::ControlLine;
17use crate::driver::DriverKind;
18use crate::error::{CloseReason, ConfigReason, KillReason, NetError, RefusalCause};
19use crate::events::{EventSink, NoopSink};
20use crate::gate::Gate;
21use crate::handoff::ListenerHandle;
22use crate::id::{ConnectionId, ListenerId, WorkerId};
23use crate::limits::Limits;
24use crate::opts::{ListenOptions, LocalOptions};
25use crate::proxy::ProxyMode;
26use crate::session::SessionFactory;
27use crate::tcp::{ListenerInfo, TcpConnection};
28use crate::time::Clock;
29use crate::tls::ErasedAcceptor;
30use crate::tls::{NoTls, TlsAcceptor};
31use crate::trusted::TrustedProxies;
32
33pub(crate) use engine::Shared;
34
35/// Whether the server is accepting.
36///
37/// ```
38/// assert_ne!(net_io::DoorState::Open, net_io::DoorState::Closed);
39/// ```
40#[derive(Clone, Copy, Debug, PartialEq, Eq)]
41pub enum DoorState {
42    /// Accepting new connections.
43    Open,
44    /// Not accepting; listening sockets stay open.
45    Closed,
46}
47
48/// What a drain did.
49///
50/// ```
51/// let r = net_io::DrainReport { graceful: 3, killed: 1, took: std::time::Duration::from_millis(40) };
52/// assert_eq!(r.graceful + r.killed, 4);
53/// ```
54#[derive(Clone, Copy, Debug, PartialEq, Eq)]
55pub struct DrainReport {
56    /// Connections that finished before the deadline.
57    pub graceful: u32,
58    /// Connections killed at the deadline.
59    pub killed: u32,
60    /// How long the drain took.
61    pub took: Duration,
62}
63
64/// Counters summed over the workers.
65///
66/// ```no_run
67/// let server = net_io::serve("127.0.0.1:0", |_c| Ok(()))?;
68/// let stats = server.stats();
69/// println!("{} open, {} accepted", stats.open, stats.accepted);
70/// # Ok::<(), net_io::NetError>(())
71/// ```
72#[non_exhaustive]
73#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
74pub struct Stats {
75    /// Connections open now.
76    pub open: u64,
77    /// Connections accepted.
78    pub accepted: u64,
79    /// Connections refused.
80    pub refused: u64,
81    /// Connections closed.
82    pub closed: u64,
83    /// Bytes received.
84    pub bytes_in: u64,
85    /// Bytes sent.
86    pub bytes_out: u64,
87    /// Writes the gate denied.
88    pub egress_denied: u64,
89    /// Connections killed.
90    pub killed: u64,
91    /// Connections closed for the minimum rate.
92    pub slow_peers: u64,
93    /// Connections closed by a timeout.
94    pub timeouts: u64,
95    /// Times the process ran out of descriptors.
96    pub descriptor_pressure: u64,
97    /// Completions for connections that had closed.
98    pub stale_completions: u64,
99    /// Sessions that panicked.
100    pub session_panics: u64,
101    refused_by: [u64; RefusalCause::COUNT],
102    closed_by: [u64; CloseReason::COUNT],
103}
104
105impl Stats {
106    /// Refusals with this cause (gate codes summed).
107    #[must_use]
108    pub fn refused_for(&self, cause: RefusalCause) -> u64 {
109        self.refused_by[cause.index()]
110    }
111
112    /// Closes with this reason's variant (inner values ignored).
113    #[must_use]
114    pub fn closed_for(&self, reason: CloseReason) -> u64 {
115        self.closed_by[reason.index()]
116    }
117
118    /// Every close reason with a non-zero count, one entry per variant (inner
119    /// values are not kept: `Killed` carries reason 0, `Io` class `Other(0)`).
120    ///
121    /// ```no_run
122    /// let server = net_io::serve("127.0.0.1:0", |_c| Ok(()))?;
123    /// for (reason, n) in server.stats().closes() {
124    ///     println!("{}: {n}", reason.as_str());
125    /// }
126    /// # Ok::<(), net_io::NetError>(())
127    /// ```
128    pub fn closes(&self) -> impl Iterator<Item = (CloseReason, u64)> + '_ {
129        CloseReason::BY_INDEX
130            .iter()
131            .zip(self.closed_by.iter())
132            .filter(|(_, n)| **n > 0)
133            .map(|(r, n)| (*r, *n))
134    }
135
136    /// Every refusal cause with a non-zero count (gate codes summed under `Gate(0)`).
137    pub fn refusals(&self) -> impl Iterator<Item = (RefusalCause, u64)> + '_ {
138        RefusalCause::BY_INDEX
139            .iter()
140            .zip(self.refused_by.iter())
141            .filter(|(_, n)| **n > 0)
142            .map(|(r, n)| (*r, *n))
143    }
144}
145
146/// One listener of a server.
147///
148/// ```
149/// use net_io::{ListenerSpec, Limits};
150/// let spec = ListenerSpec::tcp("127.0.0.1:0")
151///     .name("admin")
152///     .limits(Limits::builder().max_per_listener(10).build()?);
153/// # let _ = spec;
154/// # Ok::<(), net_io::NetError>(())
155/// ```
156#[must_use]
157#[derive(Debug)]
158pub struct ListenerSpec {
159    pub(crate) addrs: Result<Vec<SocketAddr>, String>,
160    pub(crate) options: Option<ListenOptions>,
161    pub(crate) name: Option<String>,
162    pub(crate) limits: Limits,
163    pub(crate) proxy: ProxyMode,
164    pub(crate) trusted: Option<Arc<TrustedProxies>>,
165    pub(crate) tls: bool,
166    pub(crate) unix: Option<(PathBuf, LocalOptions)>,
167    #[cfg(all(windows, feature = "local"))]
168    pub(crate) pipe: Option<(String, crate::pipe::PipeOptions)>,
169    #[cfg(feature = "udp")]
170    pub(crate) udp: Option<crate::udp::UdpOptions>,
171    pub(crate) adopt: Option<ListenerHandle>,
172    pub(crate) lockdown_allowed: bool,
173}
174
175impl ListenerSpec {
176    /// The global cap is the server's: a listener caps itself with
177    /// `max_per_listener`. Taking `max_connections` here would let a listener lift
178    /// the server's cap and the descriptor budget checked against it.
179    fn check_listener_limits(&self) -> Result<(), NetError> {
180        if self.limits.max_connections().is_some() {
181            return Err(NetError::InvalidConfig {
182                field: "max_connections",
183                reason: ConfigReason::Inconsistent,
184            });
185        }
186        Ok(())
187    }
188
189    /// A TCP listener on `addr` (resolved now; a failure is reported by `build`).
190    pub fn tcp<A: ToSocketAddrs>(addr: A) -> ListenerSpec {
191        ListenerSpec {
192            addrs: addr
193                .to_socket_addrs()
194                .map(|i| i.collect())
195                .map_err(|e| e.to_string()),
196            options: None,
197            name: None,
198            limits: Limits::default(),
199            proxy: ProxyMode::Off,
200            trusted: None,
201            tls: false,
202            unix: None,
203            #[cfg(all(windows, feature = "local"))]
204            pipe: None,
205            #[cfg(feature = "udp")]
206            udp: None,
207            adopt: None,
208            lockdown_allowed: false,
209        }
210    }
211
212    /// Keeps admitting under `ControlState::Lockdown`, for the listener an operator
213    /// comes in through while everything else is refused.
214    pub fn lockdown_allowed(mut self, on: bool) -> ListenerSpec {
215        self.lockdown_allowed = on;
216        self
217    }
218
219    /// A TCP listener with explicit options (their backlog wins over the limits').
220    pub fn tcp_with<A: ToSocketAddrs>(addr: A, options: ListenOptions) -> ListenerSpec {
221        ListenerSpec {
222            options: Some(options),
223            ..ListenerSpec::tcp(addr)
224        }
225    }
226
227    /// A UDP socket served by the [`UdpSession`](crate::UdpSession) that
228    /// `ServerBuilder::udp_sessions` makes (feature `udp`). A thread of its own reads
229    /// it, with the door and a stop like any listener, and the socket's budgets and
230    /// amplification guard apply.
231    ///
232    /// ```
233    /// use net_io::{ListenerSpec, UdpOptions};
234    /// let spec = ListenerSpec::udp("0.0.0.0:5353", UdpOptions::new());
235    /// # let _ = spec;
236    /// ```
237    #[cfg(feature = "udp")]
238    pub fn udp<A: ToSocketAddrs>(addr: A, options: crate::udp::UdpOptions) -> ListenerSpec {
239        ListenerSpec {
240            udp: Some(options),
241            ..ListenerSpec::tcp(addr)
242        }
243    }
244
245    /// A named pipe listener on `\\\\.\\pipe\\<name>` (feature `local`, Windows).
246    /// Remote clients are always rejected, and connections carry `Transport::Pipe`,
247    /// the client's pid, and no IP address: the per-source cap does not apply. With
248    /// `proxy`, every peer is trusted: the pipe's security decides who may connect.
249    ///
250    /// ```no_run
251    /// use net_io::{ListenerSpec, PipeOptions};
252    /// let spec = ListenerSpec::pipe("myapp-control", PipeOptions::new());
253    /// # let _ = spec;
254    /// ```
255    #[cfg(all(windows, feature = "local"))]
256    pub fn pipe(name: &str, options: crate::pipe::PipeOptions) -> ListenerSpec {
257        ListenerSpec {
258            pipe: Some((name.to_owned(), options)),
259            ..ListenerSpec::tcp(std::net::SocketAddr::from(([127, 0, 0, 1], 0)))
260        }
261    }
262
263    /// A Unix domain socket listener at `path` (feature `local`; on Windows, AF_UNIX,
264    /// where NTFS ACLs replace `options`' mode and owner). The socket file gets
265    /// `options`' mode and owner before it listens, and is removed at shutdown if it
266    /// is still the file this server created. Connections carry `Transport::Unix`, the peer's
267    /// credentials, and no IP address: the per-source cap does not apply, and a
268    /// `BlockingHandler` receives them as a `TcpConnection` whose `peer_addr` is
269    /// unspecified. With `proxy`, every peer is trusted: the socket file's
270    /// permissions decide who may connect.
271    ///
272    /// ```
273    /// use net_io::{ListenerSpec, LocalOptions};
274    /// let spec = ListenerSpec::unix("/run/myapp/api.sock", LocalOptions::new().group_access(33));
275    /// # let _ = spec;
276    /// ```
277    pub fn unix(path: impl Into<PathBuf>, options: LocalOptions) -> ListenerSpec {
278        ListenerSpec {
279            addrs: Ok(Vec::new()),
280            options: None,
281            name: None,
282            limits: Limits::default(),
283            proxy: ProxyMode::Off,
284            trusted: None,
285            tls: false,
286            unix: Some((path.into(), options)),
287            lockdown_allowed: false,
288            #[cfg(all(windows, feature = "local"))]
289            pipe: None,
290            #[cfg(feature = "udp")]
291            udp: None,
292            adopt: None,
293        }
294    }
295
296    /// A listener this process was given: inherited from systemd or a FastCGI
297    /// manager, received in a hand-off, or released by another server. Its name
298    /// is the handle's unless [`ListenerSpec::name`] sets one. The socket is not
299    /// bound again; options set at bind time stay as they are, and the backlog is
300    /// reported as unknown. An adopted Unix socket's file is left in place at
301    /// shutdown (the next bind removes it as stale).
302    ///
303    /// ```no_run
304    /// use net_io::ListenerSpec;
305    /// for inherited in net_io::systemd()? {
306    ///     let spec = ListenerSpec::adopt(inherited.handle);
307    ///     # let _ = spec;
308    /// }
309    /// # Ok::<(), net_io::InheritError>(())
310    /// ```
311    pub fn adopt(handle: ListenerHandle) -> ListenerSpec {
312        ListenerSpec {
313            addrs: Ok(Vec::new()),
314            options: None,
315            name: None,
316            limits: Limits::default(),
317            proxy: ProxyMode::Off,
318            trusted: None,
319            tls: false,
320            unix: None,
321            #[cfg(all(windows, feature = "local"))]
322            pipe: None,
323            #[cfg(feature = "udp")]
324            udp: None,
325            adopt: Some(handle),
326            lockdown_allowed: false,
327        }
328    }
329
330    /// A name (up to 64 bytes) for events and hand-off.
331    pub fn name(mut self, name: &str) -> ListenerSpec {
332        self.name = Some(name.to_owned());
333        self
334    }
335
336    /// Per-listener caps and deadlines; values set here override the server's.
337    pub fn limits(mut self, limits: Limits) -> ListenerSpec {
338        self.limits = limits;
339        self
340    }
341
342    /// Requires a PROXY protocol header on every connection (feature `proxy`).
343    /// Peers outside the trusted proxies are closed before any byte is read.
344    ///
345    /// ```
346    /// use net_io::{ListenerSpec, ProxyMode, ProxyVersions};
347    /// let spec = ListenerSpec::tcp("127.0.0.1:0").proxy(ProxyMode::Required { versions: ProxyVersions::Both });
348    /// # let _ = spec;
349    /// ```
350    pub fn proxy(mut self, mode: ProxyMode) -> ListenerSpec {
351        self.proxy = mode;
352        self
353    }
354
355    /// Serves TLS on this listener through the builder's acceptor
356    /// ([`ServerBuilder::tls`], feature `tls`).
357    pub fn tls(mut self, on: bool) -> ListenerSpec {
358        self.tls = on;
359        self
360    }
361
362    /// The proxies trusted on this listener, instead of the server's list.
363    pub fn trusted_proxies(mut self, proxies: TrustedProxies) -> ListenerSpec {
364        self.trusted = Some(Arc::new(proxies));
365        self
366    }
367}
368
369/// What runs per connection; the unset state (no `build` exists for it).
370#[derive(Clone, Copy, Debug, Default)]
371pub struct NoWork;
372
373/// What `ServerBuilder::udp_sessions` produces when a server has no TCP work; programs
374/// never name it.
375#[cfg(feature = "udp")]
376#[derive(Debug)]
377pub struct UdpOnly;
378
379/// The unset gate (no `build` exists for it): name `AllowAll` to run without a gate.
380#[derive(Clone, Copy, Debug, Default)]
381pub struct NoGate;
382
383/// Where workers run.
384///
385/// ```
386/// let pinned = net_io::Placement::Explicit(vec![0, 2, 4, 6]);
387/// # let _ = pinned;
388/// ```
389#[non_exhaustive]
390#[derive(Clone, Debug, Default, PartialEq, Eq)]
391pub enum Placement {
392    /// The OS decides.
393    #[default]
394    Off,
395    /// Worker `n` on CPU `n`, wrapping around.
396    PinPerCore,
397    /// Worker `n` on `cpus[n % cpus.len()]`.
398    Explicit(Vec<usize>),
399}
400
401/// What `ServerBuilder::sessions` produces; programs never name it.
402#[derive(Debug)]
403pub struct Sessions<F> {
404    pub(crate) factory: F,
405}
406
407#[cfg(feature = "reactor")]
408impl<F> Sessions<F> {
409    pub(crate) fn factory(&self) -> &F {
410        &self.factory
411    }
412}
413
414/// What `ServerBuilder::handler` produces; programs never name it.
415pub struct BlockingHandler<H> {
416    pub(crate) handler: H,
417}
418
419impl<H> fmt::Debug for BlockingHandler<H> {
420    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
421        f.write_str("BlockingHandler")
422    }
423}
424
425pub(crate) mod sealed {
426    pub trait Sealed {}
427}
428
429/// What runs per connection: [`Sessions`] or a [`BlockingHandler`]. Sealed.
430pub trait Workload: sealed::Sealed + engine::Serve + Send + Sync + 'static {}
431
432#[cfg(feature = "udp")]
433impl sealed::Sealed for UdpOnly {}
434#[cfg(feature = "udp")]
435impl Workload for UdpOnly {}
436
437impl<F: SessionFactory> sealed::Sealed for Sessions<F> {}
438impl<F: SessionFactory> Workload for Sessions<F> {}
439
440impl<H> sealed::Sealed for BlockingHandler<H> where
441    H: Fn(&mut TcpConnection) -> Result<(), NetError> + Send + Sync + 'static
442{
443}
444impl<H> Workload for BlockingHandler<H> where
445    H: Fn(&mut TcpConnection) -> Result<(), NetError> + Send + Sync + 'static
446{
447}
448
449/// Builds a [`Server`]. A builder without a gate or without `sessions`/`handler`
450/// has no `build` method: forgetting either is a compile error.
451///
452/// # Examples
453///
454/// ```no_run
455/// use net_io::{AllowAll, DriverKind, Limits, ListenerSpec, ServerBuilder};
456/// use std::time::{Duration, Instant};
457///
458/// let server = ServerBuilder::new()
459///     .listener(ListenerSpec::tcp("0.0.0.0:8080").name("public"))
460///     .listener(ListenerSpec::tcp("127.0.0.1:9090").name("admin"))
461///     .driver(DriverKind::Blocking)
462///     .workers(64)
463///     .limits(Limits::builder().idle_timeout(Duration::from_secs(5)).build()?)
464///     .handler(|conn| { conn.send_all(b"hello\n")?; Ok(()) })
465///     .gate(AllowAll)
466///     .build()?;              // listeners bound, workers started, door closed
467/// // ... drop privileges here ...
468/// server.open_door()?;
469/// let report = server.shutdown(Instant::now() + Duration::from_secs(30));
470/// println!("{report:?}");
471/// # Ok::<(), net_io::NetError>(())
472/// ```
473#[must_use]
474pub struct ServerBuilder<W = NoWork, G = NoGate, S = NoopSink, T = NoTls> {
475    listeners: Vec<ListenerSpec>,
476    driver: DriverKind,
477    workers: Option<u16>,
478    limits: Limits,
479    work: W,
480    gate: G,
481    sink: S,
482    tls: T,
483    control: Option<Arc<dyn ControlLine>>,
484    wipe: bool,
485    clock: Option<Arc<dyn Clock>>,
486    trusted: Option<Arc<TrustedProxies>>,
487    placement: Placement,
488    #[cfg(feature = "udp")]
489    udp: Option<Arc<dyn crate::udp::UdpSessionFactory>>,
490}
491
492impl ServerBuilder {
493    /// An empty builder.
494    pub fn new() -> ServerBuilder {
495        ServerBuilder {
496            listeners: Vec::new(),
497            driver: DriverKind::Auto,
498            workers: None,
499            limits: Limits::default(),
500            work: NoWork,
501            gate: NoGate,
502            sink: NoopSink,
503            tls: NoTls,
504            control: None,
505            wipe: true,
506            clock: None,
507            trusted: None,
508            placement: Placement::Off,
509            #[cfg(feature = "udp")]
510            udp: None,
511        }
512    }
513}
514
515impl Default for ServerBuilder {
516    fn default() -> ServerBuilder {
517        ServerBuilder::new()
518    }
519}
520
521impl<W, G, S, T> ServerBuilder<W, G, S, T> {
522    fn map<W2, G2, S2, T2>(
523        self,
524        f: impl FnOnce(W, G, S, T) -> (W2, G2, S2, T2),
525    ) -> ServerBuilder<W2, G2, S2, T2> {
526        let ServerBuilder {
527            listeners,
528            driver,
529            workers,
530            limits,
531            work,
532            gate,
533            sink,
534            tls,
535            control,
536            wipe,
537            clock,
538            trusted,
539            placement,
540            #[cfg(feature = "udp")]
541            udp,
542        } = self;
543        let (work, gate, sink, tls) = f(work, gate, sink, tls);
544        ServerBuilder {
545            listeners,
546            driver,
547            workers,
548            limits,
549            work,
550            gate,
551            sink,
552            tls,
553            control,
554            wipe,
555            clock,
556            trusted,
557            placement,
558            #[cfg(feature = "udp")]
559            udp,
560        }
561    }
562
563    /// The proxies whose PROXY headers are believed, for every listener that
564    /// requires one and has no list of its own.
565    pub fn trusted_proxies(mut self, proxies: TrustedProxies) -> Self {
566        self.trusted = Some(Arc::new(proxies));
567        self
568    }
569
570    /// Adds a listener (at most 64).
571    pub fn listener(mut self, spec: ListenerSpec) -> Self {
572        self.listeners.push(spec);
573        self
574    }
575
576    /// The driver (default `Auto`).
577    pub fn driver(mut self, kind: DriverKind) -> Self {
578        self.driver = kind;
579        self
580    }
581
582    /// Pins workers to CPUs (`Unsupported` on macOS). A worker that stays on one CPU
583    /// keeps its cache; the cost is that the OS can no longer move it off a busy CPU.
584    pub fn placement(mut self, placement: Placement) -> Self {
585        self.placement = placement;
586        self
587    }
588
589    /// Worker threads (default 128 on the blocking driver; 1 to 4,096).
590    pub fn workers(mut self, n: u16) -> Self {
591        self.workers = Some(n);
592        self
593    }
594
595    /// The server's limits; unset values take the driver's defaults.
596    pub fn limits(mut self, limits: Limits) -> Self {
597        self.limits = limits;
598        self
599    }
600
601    /// Runs a sans-IO session per connection.
602    pub fn sessions<F: SessionFactory>(self, factory: F) -> ServerBuilder<Sessions<F>, G, S, T> {
603        self.map(|_, g, s, t| (Sessions { factory }, g, s, t))
604    }
605
606    /// Runs a blocking handler per connection (on the blocking driver).
607    pub fn handler<H>(self, handler: H) -> ServerBuilder<BlockingHandler<H>, G, S, T>
608    where
609        H: Fn(&mut TcpConnection) -> Result<(), NetError> + Send + Sync + 'static,
610    {
611        self.map(|_, g, s, t| (BlockingHandler { handler }, g, s, t))
612    }
613
614    /// The TLS engine for listeners with `ListenerSpec::tls(true)` (feature `tls`).
615    pub fn tls<T2: TlsAcceptor>(self, acceptor: T2) -> ServerBuilder<W, G, S, T2> {
616        self.map(|w, g, s, _| (w, g, s, acceptor))
617    }
618
619    /// The connection gate (required; `AllowAll` for none).
620    pub fn gate<G2: Gate>(self, gate: G2) -> ServerBuilder<W, G2, S, T> {
621        self.map(|w, _, s, t| (w, gate, s, t))
622    }
623
624    /// The event sink (default `NoopSink`).
625    pub fn events<S2: EventSink>(self, sink: S2) -> ServerBuilder<W, G, S2, T> {
626        self.map(|w, g, _, t| (w, g, sink, t))
627    }
628
629    /// The control line (default: none).
630    pub fn control<C: ControlLine>(mut self, line: Arc<C>) -> Self {
631        self.control = Some(line);
632        self
633    }
634
635    /// Zero the used part of every buffer when it returns to a pool (default on).
636    pub fn wipe_buffers(mut self, on: bool) -> Self {
637        self.wipe = on;
638        self
639    }
640
641    /// The clock deadlines read (tests inject a `ManualClock`).
642    pub fn clock<K: Clock>(mut self, clock: Arc<K>) -> Self {
643        self.clock = Some(clock);
644        self
645    }
646}
647
648#[cfg(feature = "udp")]
649impl<G, S, T> ServerBuilder<NoWork, G, S, T> {
650    /// Serves UDP listeners only; a TCP listener then fails `build`. One thread per
651    /// listener, and no worker pool.
652    ///
653    /// ```no_run
654    /// use std::net::SocketAddr;
655    /// use net_io::{AllowAll, ListenerInfo, ListenerSpec, ServerBuilder, UdpContext, UdpOptions, UdpSession};
656    /// struct Echo;
657    /// impl UdpSession for Echo {
658    ///     fn on_datagram(&mut self, cx: &mut UdpContext<'_>, from: SocketAddr, bytes: &[u8]) {
659    ///         let _ = cx.send_to(bytes, from);
660    ///     }
661    /// }
662    /// let server = ServerBuilder::new()
663    ///     .listener(ListenerSpec::udp("0.0.0.0:7000", UdpOptions::new()))
664    ///     .udp_sessions(|_: &ListenerInfo| Echo)
665    ///     .gate(AllowAll)
666    ///     .build()?;
667    /// server.open_door()?;
668    /// # Ok::<(), net_io::NetError>(())
669    /// ```
670    pub fn udp_sessions<F>(self, factory: F) -> ServerBuilder<UdpOnly, G, S, T>
671    where
672        F: crate::udp::UdpSessionFactory,
673    {
674        let mut b = self.map(|_, g, s, t| (UdpOnly, g, s, t));
675        b.udp = Some(Arc::new(factory));
676        b.workers.get_or_insert(1);
677        b
678    }
679}
680
681#[cfg(feature = "udp")]
682impl<W: Workload, G, S, T> ServerBuilder<W, G, S, T> {
683    /// Serves the UDP listeners beside this server's TCP work.
684    pub fn udp_sessions<F>(mut self, factory: F) -> Self
685    where
686        F: crate::udp::UdpSessionFactory,
687    {
688        self.udp = Some(Arc::new(factory));
689        self
690    }
691}
692
693impl<W, G, S, T> ServerBuilder<W, G, S, T>
694where
695    W: Workload,
696    G: Gate,
697    S: EventSink,
698    T: TlsAcceptor,
699{
700    /// Validates everything, binds the listeners, starts the workers, and returns
701    /// the server with the door **closed**.
702    ///
703    /// # Errors
704    ///
705    /// `InvalidConfig` (`field` names the method), bind errors, `Unsupported` for a
706    /// driver this version does not have.
707    pub fn build(self) -> Result<Server, NetError> {
708        // A handler holds its worker for the whole connection (blocking pool only).
709        let requested = match self.driver {
710            DriverKind::Auto if <W as engine::Serve>::BLOCKING_ONLY => DriverKind::Blocking,
711            other => other,
712        };
713        let driver = match requested.resolve() {
714            DriverKind::Reactor if <W as engine::Serve>::BLOCKING_ONLY => {
715                return Err(invalid("driver", ConfigReason::Inconsistent));
716            }
717            DriverKind::Reactor if !DriverKind::reactor_built() => {
718                return Err(NetError::Unsupported {
719                    feature: "the reactor driver",
720                    platform: std::env::consts::OS,
721                });
722            }
723            DriverKind::Uring => {
724                return Err(NetError::Unsupported {
725                    feature: "the io_uring driver (after 1.0.0)",
726                    platform: std::env::consts::OS,
727                });
728            }
729            kind => kind,
730        };
731        if self.listeners.is_empty() {
732            return Err(invalid("listener", ConfigReason::Missing));
733        }
734        if self.listeners.len() > 64 {
735            return Err(invalid("listener", ConfigReason::TooLarge { max: 64 }));
736        }
737        let workers = self.workers.unwrap_or_else(|| {
738            if driver == DriverKind::Reactor {
739                std::thread::available_parallelism()
740                    .map_or(4, |n| u16::try_from(n.get()).unwrap_or(4096).min(4096))
741            } else {
742                128
743            }
744        });
745        if workers == 0 {
746            return Err(invalid("workers", ConfigReason::Zero));
747        }
748        if workers > 4096 {
749            return Err(invalid("workers", ConfigReason::TooLarge { max: 4096 }));
750        }
751        let mut listeners = self.listeners;
752        let has_tls = TypeId::of::<T>() != TypeId::of::<NoTls>();
753        let mut names = Vec::new();
754        #[cfg(feature = "udp")]
755        for spec in &listeners {
756            if (spec.udp.is_some() && self.udp.is_none())
757                || (spec.udp.is_none() && <W as engine::Serve>::UDP_ONLY)
758            {
759                return Err(invalid("udp_sessions", ConfigReason::Inconsistent));
760            }
761            if spec.udp.is_some() && (spec.tls || spec.proxy != ProxyMode::Off) {
762                return Err(invalid("udp", ConfigReason::Inconsistent));
763            }
764        }
765        for spec in &mut listeners {
766            check_spec(spec, self.trusted.as_ref(), has_tls, &names)?;
767            if let Some(n) = &spec.name {
768                names.push(n.clone());
769            }
770        }
771        // On the blocking driver an unset global cap is one connection per worker;
772        // on the reactor the default, but never more than the descriptors allow.
773        let limits = if self.limits.max_connections().is_none() {
774            let cap = if driver == DriverKind::Reactor {
775                reactor_default_cap(workers)
776            } else {
777                u32::from(workers)
778            };
779            self.limits.to_builder().max_connections(cap).build()?
780        } else {
781            self.limits.clone()
782        };
783        limits.validate(workers, crate::sys::descriptor_limit())?;
784        for spec in &listeners {
785            spec.check_listener_limits()?;
786            limits.overlay(&spec.limits).validate(workers, None)?;
787        }
788        if self.placement != Placement::Off && !crate::sys::CAN_PIN {
789            return Err(NetError::Unsupported {
790                feature: "worker placement",
791                platform: std::env::consts::OS,
792            });
793        }
794        if self.placement == Placement::Explicit(Vec::new()) {
795            return Err(invalid("placement", ConfigReason::Zero));
796        }
797        let tls: Option<Arc<dyn ErasedAcceptor>> = if has_tls {
798            Some(Arc::new(self.tls))
799        } else {
800            None
801        };
802        engine::start(engine::Config {
803            tls,
804            trusted: self.trusted,
805            listeners,
806            driver,
807            workers,
808            limits,
809            work: self.work,
810            gate: self.gate,
811            sink: self.sink,
812            control: self.control,
813            wipe: self.wipe,
814            clock: self.clock,
815            placement: self.placement,
816            #[cfg(feature = "udp")]
817            udp: self.udp,
818        })
819    }
820}
821
822/// The reactor's default global cap: 10,000, less where the process's descriptor
823/// limit would not hold it.
824fn reactor_default_cap(workers: u16) -> u32 {
825    let wanted = 10_000u32;
826    match crate::sys::descriptor_limit() {
827        Some(have) => {
828            let spare = u64::from(workers).saturating_mul(2) + 64;
829            let room = have.saturating_sub(spare).clamp(16, u64::from(wanted));
830            u32::try_from(room).unwrap_or(wanted)
831        }
832        None => wanted,
833    }
834}
835
836fn invalid(field: &'static str, reason: ConfigReason) -> NetError {
837    NetError::InvalidConfig { field, reason }
838}
839
840/// Where `Server::adopt` registers a connection: the listener (by name) whose
841/// limits and caps apply, and an optional starting lane (the gate may change it).
842///
843/// ```
844/// let spec = net_io::AdoptSpec::new("main").lane(net_io::Lane(1));
845/// # let _ = spec;
846/// ```
847#[must_use]
848#[derive(Clone, Debug, PartialEq, Eq)]
849pub struct AdoptSpec {
850    listener: String,
851    lane: Option<crate::info::Lane>,
852}
853
854impl AdoptSpec {
855    /// Registers on the listener named `listener`.
856    pub fn new(listener: &str) -> AdoptSpec {
857        AdoptSpec {
858            listener: listener.to_owned(),
859            lane: None,
860        }
861    }
862
863    /// The lane the connection starts in, before the gate's admission.
864    pub fn lane(mut self, lane: crate::info::Lane) -> AdoptSpec {
865        self.lane = Some(lane);
866        self
867    }
868}
869
870/// The checks `build` and `add_listener` run on one listener: the features it
871/// needs, a TLS engine, trusted proxies (resolved into the spec), and its name.
872fn check_spec(
873    spec: &mut ListenerSpec,
874    server_trusted: Option<&Arc<TrustedProxies>>,
875    has_tls: bool,
876    taken: &[String],
877) -> Result<(), NetError> {
878    if spec.name.is_none() {
879        spec.name = spec
880            .adopt
881            .as_ref()
882            .and_then(|h| h.name())
883            .map(str::to_owned);
884    }
885    let unix = spec.unix.is_some()
886        || spec
887            .adopt
888            .as_ref()
889            .is_some_and(|h| h.kind() == crate::info::Transport::Unix);
890    if unix && !cfg!(feature = "local") {
891        return Err(NetError::Unsupported {
892            feature: "Unix domain sockets (the `local` feature)",
893            platform: std::env::consts::OS,
894        });
895    }
896    if spec.tls {
897        if !cfg!(feature = "tls") {
898            return Err(NetError::Unsupported {
899                feature: "TLS (the `tls` feature)",
900                platform: std::env::consts::OS,
901            });
902        }
903        if !has_tls {
904            return Err(invalid("tls", ConfigReason::Missing));
905        }
906    }
907    if spec.proxy != ProxyMode::Off {
908        if !cfg!(feature = "proxy") {
909            return Err(NetError::Unsupported {
910                feature: "PROXY protocol (the `proxy` feature)",
911                platform: std::env::consts::OS,
912            });
913        }
914        // On a Unix socket the file's permissions decide who may connect.
915        if !unix {
916            let trusted = spec.trusted.clone().or_else(|| server_trusted.cloned());
917            match trusted {
918                Some(t) if !t.is_empty() => spec.trusted = Some(t),
919                // Required without anyone to trust would refuse every connection.
920                _ => return Err(invalid("trusted_proxies", ConfigReason::Missing)),
921            }
922        }
923    }
924    if let Some(n) = &spec.name {
925        if n.len() > 64 {
926            return Err(invalid("name", ConfigReason::TooLarge { max: 64 }));
927        }
928        if taken.contains(n) {
929            return Err(invalid("name", ConfigReason::Inconsistent));
930        }
931    }
932    Ok(())
933}
934
935/// A running server. Dropping it stops it (with a drain), so keep it and call
936/// [`Server::wait_for_stop`] to run until a stop is requested.
937#[must_use = "dropping a Server stops it; call wait_for_stop() to run until a stop is requested"]
938pub struct Server {
939    pub(crate) shared: Arc<Shared>,
940    pub(crate) threads: Vec<JoinHandle<()>>,
941    pub(crate) listeners: Vec<ListenerInfo>,
942    pub(crate) stopped: bool,
943}
944
945impl Server {
946    /// Starts accepting on every listener; a second call is a no-op.
947    ///
948    /// # Errors
949    ///
950    /// `ShuttingDown` while draining or after shutdown; `ForkedChild`.
951    pub fn open_door(&self) -> Result<(), NetError> {
952        self.shared.open_door()
953    }
954
955    /// Stops accepting within one loop iteration; listening sockets stay open. Idempotent.
956    pub fn close_door(&self) {
957        self.shared.close_door();
958    }
959
960    /// Whether the server is accepting.
961    #[must_use]
962    pub fn door(&self) -> DoorState {
963        self.shared.door()
964    }
965
966    /// Closes the door, tells sessions to finish, closes idle connections at once,
967    /// waits for the rest until `deadline`, then kills them with `DrainDeadline`.
968    pub fn drain(&self, deadline: Instant) -> DrainReport {
969        self.shared.drain(deadline)
970    }
971
972    /// Drains, then closes the listening sockets and joins every thread.
973    pub fn shutdown(mut self, deadline: Instant) -> DrainReport {
974        self.stop(deadline)
975    }
976
977    /// Blocks until a stop is requested (`ServerHandle::request_stop`, or the
978    /// control line moves to `Draining` or `Stopping`), then shuts down.
979    pub fn wait_for_stop(mut self) -> DrainReport {
980        let deadline = self.shared.wait_for_stop_request();
981        self.stop(deadline)
982    }
983
984    fn stop(&mut self, deadline: Instant) -> DrainReport {
985        if self.stopped {
986            return DrainReport {
987                graceful: 0,
988                killed: 0,
989                took: Duration::ZERO,
990            };
991        }
992        self.stopped = true;
993        let report = self.shared.drain(deadline);
994        self.shared.stop_threads();
995        for t in self.threads.drain(..) {
996            let _ = t.join();
997        }
998        self.shared.join_listeners();
999        report
1000    }
1001
1002    /// Registers a dialed connection exactly like an accepted one on the
1003    /// listener named in `spec`: a new id, the caps, `Gate::admit` with
1004    /// `AdmitStage::Adopt`, that listener's limits, the server's handler or
1005    /// sessions, its kill handle, and its events. For back-channels and outbound
1006    /// connections a server should run and revoke like its own. A gate the
1007    /// connection had from `set_gate` is closed (`SessionClosed`) first.
1008    ///
1009    /// # Errors
1010    ///
1011    /// `Refused { cause }` (caps, the gate, `Busy`; the connection was reset),
1012    /// `InvalidConfig { field: "listener" }` (no listener with that name),
1013    /// `InvalidConfig { field: "connection" }` (a TLS connection, or bytes read
1014    /// ahead), `ShuttingDown`, `ForkedChild`, `Closed`.
1015    ///
1016    /// ```no_run
1017    /// use net_io::{AdoptSpec, AllowAll, ListenerSpec, ServerBuilder};
1018    /// let server = ServerBuilder::new()
1019    ///     .listener(ListenerSpec::tcp("127.0.0.1:7000").name("main"))
1020    ///     .handler(|conn| { conn.send_all(b"hello, upstream\n")?; Ok(()) })
1021    ///     .gate(AllowAll)
1022    ///     .build()?;
1023    /// let upstream = net_io::connect("10.0.0.9:9000")?;
1024    /// let id = server.adopt(upstream, AdoptSpec::new("main"))?;
1025    /// # let _ = id;
1026    /// # Ok::<(), net_io::NetError>(())
1027    /// ```
1028    pub fn adopt(&self, conn: TcpConnection, spec: AdoptSpec) -> Result<ConnectionId, NetError> {
1029        let mut conn = conn;
1030        let link = conn.take_link().ok_or(NetError::Closed)?;
1031        let (Some(peer), Some(local)) =
1032            (link.info.peer.socket_addr(), link.info.local.socket_addr())
1033        else {
1034            return Err(invalid("connection", ConfigReason::Inconsistent));
1035        };
1036        let stream = link
1037            .into_stream(CloseReason::SessionClosed)
1038            .and_then(crate::sys::Stream::into_tcp)
1039            .ok_or(invalid("connection", ConfigReason::Inconsistent))?;
1040        self.shared
1041            .adopt(stream, peer, local, &spec.listener, spec.lane)
1042    }
1043
1044    /// Owned duplicates of every listening socket, for a hand-off to the next
1045    /// process (`send_listeners`, Unix). This server keeps
1046    /// accepting meanwhile, so the new process can start before this one stops
1047    /// (decision D-042); a later `shutdown` closes only this server's copies, and
1048    /// a Unix socket file stays in place for the new process.
1049    ///
1050    /// # Errors
1051    ///
1052    /// `Os` when a socket cannot be duplicated, `ForkedChild`.
1053    pub fn release_listeners(&self) -> Result<Vec<ListenerHandle>, NetError> {
1054        self.shared.release_listeners()
1055    }
1056
1057    /// Binds one more listener on the running server and starts its accept
1058    /// thread. Its door is closed until the next [`Server::open_door`] (which
1059    /// opens every listener's door); the same checks as `build` apply. The id is
1060    /// new: ids of removed listeners are never reused.
1061    ///
1062    /// # Errors
1063    ///
1064    /// As `build` for the listener; `InvalidConfig { field: "listener" }` past 64
1065    /// listeners, `ShuttingDown`, `ForkedChild`.
1066    ///
1067    /// ```no_run
1068    /// use net_io::{AllowAll, ListenerSpec, ServerBuilder};
1069    /// let mut server = ServerBuilder::new()
1070    ///     .listener(ListenerSpec::tcp("127.0.0.1:8080"))
1071    ///     .handler(|conn| { conn.send_all(b"hi\n")?; Ok(()) })
1072    ///     .gate(AllowAll)
1073    ///     .build()?;
1074    /// server.open_door()?;
1075    /// let added = server.add_listener(ListenerSpec::tcp("127.0.0.1:8081").name("extra"))?;
1076    /// server.open_door()?; // opens the new listener's door
1077    /// # let _ = added;
1078    /// # Ok::<(), net_io::NetError>(())
1079    /// ```
1080    pub fn add_listener(&mut self, spec: ListenerSpec) -> Result<ListenerId, NetError> {
1081        let mut spec = spec;
1082        if self.listeners.len() >= 64 {
1083            return Err(invalid("listener", ConfigReason::TooLarge { max: 64 }));
1084        }
1085        let names: Vec<String> = self
1086            .listeners
1087            .iter()
1088            .filter_map(|l| l.name.clone())
1089            .collect();
1090        check_spec(
1091            &mut spec,
1092            self.shared.trusted.as_ref(),
1093            self.shared.tls.is_some(),
1094            &names,
1095        )?;
1096        let workers = u16::try_from(self.shared.worker_count()).unwrap_or(u16::MAX);
1097        spec.check_listener_limits()?;
1098        self.shared
1099            .base_limits
1100            .overlay(&spec.limits)
1101            .validate(workers, None)?;
1102        let info = self.shared.add_listener(spec)?;
1103        let id = info.id;
1104        self.listeners.push(info);
1105        Ok(id)
1106    }
1107
1108    /// Closes one listener's socket at once (its connections keep running),
1109    /// then drains them: idle ones close now, the rest may finish until
1110    /// `deadline` and are then killed (`DrainDeadline`). Other listeners and
1111    /// their connections are not touched.
1112    ///
1113    /// # Errors
1114    ///
1115    /// `InvalidConfig { field: "listener", reason: Missing }` for an unknown id,
1116    /// `ForkedChild`.
1117    pub fn remove_listener(
1118        &mut self,
1119        id: ListenerId,
1120        deadline: Instant,
1121    ) -> Result<DrainReport, NetError> {
1122        let report = self.shared.remove_listener(id, deadline)?;
1123        self.listeners.retain(|l| l.id != id);
1124        Ok(report)
1125    }
1126
1127    /// A cloneable handle for other threads.
1128    #[must_use]
1129    pub fn handle(&self) -> ServerHandle {
1130        ServerHandle {
1131            shared: self.shared.clone(),
1132        }
1133    }
1134
1135    /// Counters summed over the workers.
1136    #[must_use]
1137    pub fn stats(&self) -> Stats {
1138        self.shared.stats()
1139    }
1140
1141    /// Facts about each listener.
1142    #[must_use]
1143    pub fn listeners(&self) -> &[ListenerInfo] {
1144        &self.listeners
1145    }
1146}
1147
1148impl Drop for Server {
1149    fn drop(&mut self) {
1150        let deadline = Instant::now() + self.shared.drain_timeout;
1151        self.stop(deadline);
1152    }
1153}
1154
1155impl fmt::Debug for Server {
1156    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1157        f.debug_struct("Server")
1158            .field("listeners", &self.listeners)
1159            .field("door", &self.door())
1160            .finish()
1161    }
1162}
1163
1164/// A cloneable handle to a running server, safe to use from any thread.
1165///
1166/// ```no_run
1167/// let server = net_io::serve("127.0.0.1:7000", |conn| { conn.send_all(b"hi\n")?; Ok(()) })?;
1168/// let handle = server.handle();
1169/// std::thread::spawn(move || {
1170///     // ... wait for a signal from the application's signal library ...
1171///     handle.request_stop();
1172/// });
1173/// let report = server.wait_for_stop();
1174/// println!("drained: {} graceful, {} killed in {:?}", report.graceful, report.killed, report.took);
1175/// # Ok::<(), net_io::NetError>(())
1176/// ```
1177#[derive(Clone)]
1178pub struct ServerHandle {
1179    pub(crate) shared: Arc<Shared>,
1180}
1181
1182impl ServerHandle {
1183    /// Aborts the connection `id`; `false` if it already closed or belongs to another server.
1184    pub fn kill(&self, id: ConnectionId, reason: KillReason) -> bool {
1185        self.shared.kill(id, reason)
1186    }
1187
1188    /// Stops accepting.
1189    pub fn close_door(&self) {
1190        self.shared.close_door();
1191    }
1192
1193    /// Makes `Server::wait_for_stop` return after the drain. Does not block.
1194    pub fn request_stop(&self) {
1195        self.shared.request_stop(None);
1196    }
1197
1198    /// Interrupts every worker's and acceptor's wait so a control-line change is seen at once.
1199    pub fn wake_all(&self) {
1200        self.shared.wake_all();
1201    }
1202
1203    /// The completion queue of `worker`.
1204    #[must_use]
1205    pub fn completer(&self, worker: WorkerId) -> Option<crate::completer::Completer> {
1206        self.shared.completer(worker)
1207    }
1208
1209    /// Counters summed over the workers.
1210    #[must_use]
1211    pub fn stats(&self) -> Stats {
1212        self.shared.stats()
1213    }
1214
1215    /// Whether the server is accepting.
1216    #[must_use]
1217    pub fn door(&self) -> DoorState {
1218        self.shared.door()
1219    }
1220}
1221
1222impl fmt::Debug for ServerHandle {
1223    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1224        f.debug_struct("ServerHandle")
1225            .field("door", &self.door())
1226            .finish()
1227    }
1228}
1229
1230impl Stats {
1231    pub(crate) fn from_parts(
1232        mut base: Stats,
1233        refused_by: [u64; RefusalCause::COUNT],
1234        closed_by: [u64; CloseReason::COUNT],
1235    ) -> Stats {
1236        base.refused_by = refused_by;
1237        base.closed_by = closed_by;
1238        base
1239    }
1240}