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; listening sockets stay open, and new connections wait in
956    /// the backlog. Idempotent.
957    ///
958    /// When it returns, no connection is admitted until the next
959    /// [`open_door`](Server::open_door). A connection whose accept was already
960    /// under way is admitted before it returns, so it waits for that admission,
961    /// gate included. Called from a gate's `admit` or an event sink on the thread
962    /// of an admission, it closes the door without waiting. A UDP socket's door
963    /// stops reading; a datagram already read still reaches its session.
964    pub fn close_door(&self) {
965        self.shared.close_door();
966    }
967
968    /// Whether the server is accepting.
969    #[must_use]
970    pub fn door(&self) -> DoorState {
971        self.shared.door()
972    }
973
974    /// Closes the door, tells sessions to finish, closes idle connections at once,
975    /// waits for the rest until `deadline`, then kills them with `DrainDeadline`.
976    pub fn drain(&self, deadline: Instant) -> DrainReport {
977        self.shared.drain(deadline)
978    }
979
980    /// Drains, then closes the listening sockets and joins every thread.
981    pub fn shutdown(mut self, deadline: Instant) -> DrainReport {
982        self.stop(deadline)
983    }
984
985    /// Blocks until a stop is requested (`ServerHandle::request_stop`, or the
986    /// control line moves to `Draining` or `Stopping`), then shuts down.
987    pub fn wait_for_stop(mut self) -> DrainReport {
988        let deadline = self.shared.wait_for_stop_request();
989        self.stop(deadline)
990    }
991
992    fn stop(&mut self, deadline: Instant) -> DrainReport {
993        if self.stopped {
994            return DrainReport {
995                graceful: 0,
996                killed: 0,
997                took: Duration::ZERO,
998            };
999        }
1000        self.stopped = true;
1001        let report = self.shared.drain(deadline);
1002        self.shared.stop_threads();
1003        for t in self.threads.drain(..) {
1004            let _ = t.join();
1005        }
1006        self.shared.join_listeners();
1007        report
1008    }
1009
1010    /// Registers a dialed connection exactly like an accepted one on the
1011    /// listener named in `spec`: a new id, the caps, `Gate::admit` with
1012    /// `AdmitStage::Adopt`, that listener's limits, the server's handler or
1013    /// sessions, its kill handle, and its events. For back-channels and outbound
1014    /// connections a server should run and revoke like its own. A gate the
1015    /// connection had from `set_gate` is closed (`SessionClosed`) first.
1016    ///
1017    /// # Errors
1018    ///
1019    /// `Refused { cause }` (caps, the gate, `Busy`; the connection was reset),
1020    /// `InvalidConfig { field: "listener" }` (no listener with that name),
1021    /// `InvalidConfig { field: "connection" }` (a TLS connection, or bytes read
1022    /// ahead), `ShuttingDown`, `ForkedChild`, `Closed`.
1023    ///
1024    /// ```no_run
1025    /// use net_io::{AdoptSpec, AllowAll, ListenerSpec, ServerBuilder};
1026    /// let server = ServerBuilder::new()
1027    ///     .listener(ListenerSpec::tcp("127.0.0.1:7000").name("main"))
1028    ///     .handler(|conn| { conn.send_all(b"hello, upstream\n")?; Ok(()) })
1029    ///     .gate(AllowAll)
1030    ///     .build()?;
1031    /// let upstream = net_io::connect("10.0.0.9:9000")?;
1032    /// let id = server.adopt(upstream, AdoptSpec::new("main"))?;
1033    /// # let _ = id;
1034    /// # Ok::<(), net_io::NetError>(())
1035    /// ```
1036    pub fn adopt(&self, conn: TcpConnection, spec: AdoptSpec) -> Result<ConnectionId, NetError> {
1037        let mut conn = conn;
1038        let link = conn.take_link().ok_or(NetError::Closed)?;
1039        let (Some(peer), Some(local)) =
1040            (link.info.peer.socket_addr(), link.info.local.socket_addr())
1041        else {
1042            return Err(invalid("connection", ConfigReason::Inconsistent));
1043        };
1044        let stream = link
1045            .into_stream(CloseReason::SessionClosed)
1046            .and_then(crate::sys::Stream::into_tcp)
1047            .ok_or(invalid("connection", ConfigReason::Inconsistent))?;
1048        self.shared
1049            .adopt(stream, peer, local, &spec.listener, spec.lane)
1050    }
1051
1052    /// Owned duplicates of every listening socket, for a hand-off to the next
1053    /// process (`send_listeners`, Unix). This server keeps
1054    /// accepting meanwhile, so the new process can start before this one stops
1055    /// (decision D-042); a later `shutdown` closes only this server's copies, and
1056    /// a Unix socket file stays in place for the new process.
1057    ///
1058    /// # Errors
1059    ///
1060    /// `Os` when a socket cannot be duplicated, `ForkedChild`.
1061    pub fn release_listeners(&self) -> Result<Vec<ListenerHandle>, NetError> {
1062        self.shared.release_listeners()
1063    }
1064
1065    /// Binds one more listener on the running server and starts its accept
1066    /// thread. Its door is closed until the next [`Server::open_door`] (which
1067    /// opens every listener's door); the same checks as `build` apply. The id is
1068    /// new: ids of removed listeners are never reused.
1069    ///
1070    /// # Errors
1071    ///
1072    /// As `build` for the listener; `InvalidConfig { field: "listener" }` past 64
1073    /// listeners, `ShuttingDown`, `ForkedChild`.
1074    ///
1075    /// ```no_run
1076    /// use net_io::{AllowAll, ListenerSpec, ServerBuilder};
1077    /// let mut server = ServerBuilder::new()
1078    ///     .listener(ListenerSpec::tcp("127.0.0.1:8080"))
1079    ///     .handler(|conn| { conn.send_all(b"hi\n")?; Ok(()) })
1080    ///     .gate(AllowAll)
1081    ///     .build()?;
1082    /// server.open_door()?;
1083    /// let added = server.add_listener(ListenerSpec::tcp("127.0.0.1:8081").name("extra"))?;
1084    /// server.open_door()?; // opens the new listener's door
1085    /// # let _ = added;
1086    /// # Ok::<(), net_io::NetError>(())
1087    /// ```
1088    pub fn add_listener(&mut self, spec: ListenerSpec) -> Result<ListenerId, NetError> {
1089        let mut spec = spec;
1090        if self.listeners.len() >= 64 {
1091            return Err(invalid("listener", ConfigReason::TooLarge { max: 64 }));
1092        }
1093        let names: Vec<String> = self
1094            .listeners
1095            .iter()
1096            .filter_map(|l| l.name.clone())
1097            .collect();
1098        check_spec(
1099            &mut spec,
1100            self.shared.trusted.as_ref(),
1101            self.shared.tls.is_some(),
1102            &names,
1103        )?;
1104        let workers = u16::try_from(self.shared.worker_count()).unwrap_or(u16::MAX);
1105        spec.check_listener_limits()?;
1106        self.shared
1107            .base_limits
1108            .overlay(&spec.limits)
1109            .validate(workers, None)?;
1110        let info = self.shared.add_listener(spec)?;
1111        let id = info.id;
1112        self.listeners.push(info);
1113        Ok(id)
1114    }
1115
1116    /// Closes one listener's socket at once (its connections keep running),
1117    /// then drains them: idle ones close now, the rest may finish until
1118    /// `deadline` and are then killed (`DrainDeadline`). Other listeners and
1119    /// their connections are not touched.
1120    ///
1121    /// # Errors
1122    ///
1123    /// `InvalidConfig { field: "listener", reason: Missing }` for an unknown id,
1124    /// `ForkedChild`.
1125    pub fn remove_listener(
1126        &mut self,
1127        id: ListenerId,
1128        deadline: Instant,
1129    ) -> Result<DrainReport, NetError> {
1130        let report = self.shared.remove_listener(id, deadline)?;
1131        self.listeners.retain(|l| l.id != id);
1132        Ok(report)
1133    }
1134
1135    /// A cloneable handle for other threads.
1136    #[must_use]
1137    pub fn handle(&self) -> ServerHandle {
1138        ServerHandle {
1139            shared: self.shared.clone(),
1140        }
1141    }
1142
1143    /// Counters summed over the workers.
1144    #[must_use]
1145    pub fn stats(&self) -> Stats {
1146        self.shared.stats()
1147    }
1148
1149    /// Facts about each listener.
1150    #[must_use]
1151    pub fn listeners(&self) -> &[ListenerInfo] {
1152        &self.listeners
1153    }
1154}
1155
1156impl Drop for Server {
1157    fn drop(&mut self) {
1158        let deadline = Instant::now() + self.shared.drain_timeout;
1159        self.stop(deadline);
1160    }
1161}
1162
1163impl fmt::Debug for Server {
1164    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1165        f.debug_struct("Server")
1166            .field("listeners", &self.listeners)
1167            .field("door", &self.door())
1168            .finish()
1169    }
1170}
1171
1172/// A cloneable handle to a running server, safe to use from any thread.
1173///
1174/// ```no_run
1175/// let server = net_io::serve("127.0.0.1:7000", |conn| { conn.send_all(b"hi\n")?; Ok(()) })?;
1176/// let handle = server.handle();
1177/// std::thread::spawn(move || {
1178///     // ... wait for a signal from the application's signal library ...
1179///     handle.request_stop();
1180/// });
1181/// let report = server.wait_for_stop();
1182/// println!("drained: {} graceful, {} killed in {:?}", report.graceful, report.killed, report.took);
1183/// # Ok::<(), net_io::NetError>(())
1184/// ```
1185#[derive(Clone)]
1186pub struct ServerHandle {
1187    pub(crate) shared: Arc<Shared>,
1188}
1189
1190impl ServerHandle {
1191    /// Aborts the connection `id`; `false` if it already closed or belongs to another server.
1192    pub fn kill(&self, id: ConnectionId, reason: KillReason) -> bool {
1193        self.shared.kill(id, reason)
1194    }
1195
1196    /// Stops accepting, as [`Server::close_door`]: when it returns, no connection
1197    /// is admitted until the door opens again.
1198    pub fn close_door(&self) {
1199        self.shared.close_door();
1200    }
1201
1202    /// Makes `Server::wait_for_stop` return after the drain. Does not block.
1203    pub fn request_stop(&self) {
1204        self.shared.request_stop(None);
1205    }
1206
1207    /// Interrupts every worker's and acceptor's wait so a control-line change is seen at once.
1208    pub fn wake_all(&self) {
1209        self.shared.wake_all();
1210    }
1211
1212    /// The completion queue of `worker`.
1213    #[must_use]
1214    pub fn completer(&self, worker: WorkerId) -> Option<crate::completer::Completer> {
1215        self.shared.completer(worker)
1216    }
1217
1218    /// Counters summed over the workers.
1219    #[must_use]
1220    pub fn stats(&self) -> Stats {
1221        self.shared.stats()
1222    }
1223
1224    /// Whether the server is accepting.
1225    #[must_use]
1226    pub fn door(&self) -> DoorState {
1227        self.shared.door()
1228    }
1229}
1230
1231impl fmt::Debug for ServerHandle {
1232    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1233        f.debug_struct("ServerHandle")
1234            .field("door", &self.door())
1235            .finish()
1236    }
1237}
1238
1239impl Stats {
1240    pub(crate) fn from_parts(
1241        mut base: Stats,
1242        refused_by: [u64; RefusalCause::COUNT],
1243        closed_by: [u64; CloseReason::COUNT],
1244    ) -> Stats {
1245        base.refused_by = refused_by;
1246        base.closed_by = closed_by;
1247        base
1248    }
1249}