Skip to main content

subc_daemon/
server.rs

1use std::{
2    any::Any,
3    error::Error,
4    fmt, io,
5    net::SocketAddr,
6    sync::{
7        atomic::{AtomicU64, Ordering as AtomicOrdering},
8        Arc,
9    },
10    time::{Duration, Instant},
11};
12
13use subc_transport::{
14    authenticate_server, AuthError, AuthStage, DAEMON_ID_LEN, WATCHDOG_CLIENT_ROLE,
15};
16use tokio::{
17    io::{AsyncRead, AsyncWrite, AsyncWriteExt, BufReader, BufWriter},
18    net::TcpListener,
19    sync::{mpsc, Semaphore},
20    task::{JoinHandle, JoinSet},
21    time::timeout,
22};
23use tracing::{debug, info, warn};
24
25use crate::{
26    forwarding::{CloseReason, ConnectionCloseReceiver},
27    observability::ConnectedClients,
28    read_frame,
29    router::{FrameSink, RouteCtx, Router},
30    write_frame, FrameIoError, RouterError,
31};
32
33/// Bytes (envelope header plus body) one connection's egress queue may hold
34/// before a module-to-client enqueue must wait for room.
35///
36/// Sized for a client that is slow but still reading: one connection can
37/// multiplex many token streams, and at roughly 200-byte frames (21-byte header
38/// plus body) 4 MiB is about 19,000 queued frames, i.e. thousands of frames on
39/// each of several routes, enough to ride out a pause of seconds. It is also the
40/// most a stuck client can make the daemon hold for it: 4 MiB per connection,
41/// so even 128 stuck connections stay near 512 MiB rather than growing without
42/// bound. A single frame larger than the whole budget is still admitted into an
43/// empty queue on send paths that do not check its size first.
44///
45/// The router, however, refuses a module-to-client frame whose header-plus-body
46/// size exceeds the client connection's budget before queueing it, so the budget
47/// is also the largest module-to-client frame the daemon delivers. Modules read
48/// that limit from `subc_protocol::MAX_DELIVERED_FRAME_LEN`, so the budget is
49/// defined as that constant; giving it a different value would make the
50/// published limit wrong.
51pub const CONNECTION_EGRESS_BYTE_BUDGET: usize = subc_protocol::MAX_DELIVERED_FRAME_LEN;
52/// Let a reading client drain a short fanout burst, but never park a module's
53/// frame reader for more than 250 ms. The atomic backlog age is measured from
54/// the enqueue time of the frame the writer is on, or of the frame that made
55/// the queue non-empty. A blocked writer makes that age the stopped-reader
56/// signal; between frames it may be one frame older than the true head, which
57/// is acceptable for this bounded grace and avoids a lock on every frame.
58pub const CONNECTION_EGRESS_STALL_GRACE: Duration = Duration::from_millis(250);
59/// Frame-count backstop for the same queue (the tokio channel's capacity).
60/// The byte budget is the real bound; this one only matters for floods of tiny
61/// or empty frames, which cost bookkeeping per frame rather than bytes. 32,768
62/// frames times 128 bytes is exactly the 4 MiB budget, so for any mean frame of
63/// 128 bytes or more the byte budget binds first; below that (for example
64/// 21-byte empty frames, of which 4 MiB would be almost 200,000) the count
65/// does. The channel allocates slots lazily, so a large capacity costs nothing
66/// until it is used.
67pub const CONNECTION_EGRESS_FRAME_CAP: usize = 32 * 1024;
68/// A pending `route.open` holds one reserved slot in the connection's egress
69/// queue until its module answers, and its response is sent outside the byte
70/// budget. Eight concurrent opens per connection keep a reconnect burst
71/// parallel while bounding both the reserved slots and the bytes that bypass
72/// the budget.
73pub const MAX_PENDING_ROUTE_OPENS_PER_CONNECTION: usize = 8;
74/// A reconnect herd may spread one target's opens over many client connections.
75/// Two safe per-connection bursts retain useful parallelism without restoring
76/// the hundreds-of-binds fanout that serial dispatch used to suppress.
77pub(crate) const MAX_PENDING_ROUTE_BINDS_PER_TARGET: usize =
78    MAX_PENDING_ROUTE_OPENS_PER_CONNECTION * 2;
79pub const DEFAULT_AUTH_DEADLINE: Duration = Duration::from_secs(2);
80// Sized for the restart-herd shape: after a daemon bounce, every live client
81// connection plus all supervised children re-dial within the same second
82// (~120+ observed on the 2026-07-14 fleet). Handshakes are cheap loopback
83// HMAC exchanges; the deadline, not the permit count, is the DoS bound.
84pub const DEFAULT_MAX_UNAUTHENTICATED_CONNECTIONS: usize = 256;
85const CLOSE_DRAIN_GRACE: Duration = Duration::from_secs(2);
86const PRE_AUTH_REJECT_LOG_INTERVAL: Duration = Duration::from_secs(1);
87
88/// A connection's writer can outlive its reader while draining. Wake module
89/// deliveries when the reader exits, including task cancellation or a panic.
90struct ClientDeliveryGuard(FrameSink);
91
92impl Drop for ClientDeliveryGuard {
93    fn drop(&mut self) {
94        self.0.close_client_delivery();
95    }
96}
97
98#[derive(Clone, Copy, Debug)]
99enum PreAuthRejectStage {
100    WaitingForHandshakeSlot,
101    HandshakeDeadline,
102    InvalidProof,
103    MalformedMessage,
104    PeerClosed,
105    OtherAuthenticationFailure,
106}
107
108impl PreAuthRejectStage {
109    const fn index(self) -> usize {
110        match self {
111            Self::WaitingForHandshakeSlot => 0,
112            Self::HandshakeDeadline => 1,
113            Self::InvalidProof => 2,
114            Self::MalformedMessage => 3,
115            Self::PeerClosed => 4,
116            Self::OtherAuthenticationFailure => 5,
117        }
118    }
119
120    const fn stage(self) -> &'static str {
121        match self {
122            Self::WaitingForHandshakeSlot => "waiting_for_handshake_slot",
123            Self::HandshakeDeadline => "handshake_deadline",
124            Self::InvalidProof => "client_authentication",
125            Self::MalformedMessage => "malformed_message",
126            Self::PeerClosed => "peer_closed",
127            Self::OtherAuthenticationFailure => "authentication",
128        }
129    }
130
131    const fn reason(self) -> &'static str {
132        match self {
133            Self::WaitingForHandshakeSlot => "capacity_wait_timed_out",
134            Self::HandshakeDeadline => "handshake_deadline_expired",
135            Self::InvalidProof => "client_proof_mismatch",
136            Self::MalformedMessage => "malformed_or_oversized_message",
137            Self::PeerClosed => "peer_closed_before_authentication_completed",
138            Self::OtherAuthenticationFailure => "authentication_failed_before_routing",
139        }
140    }
141}
142
143#[derive(Debug)]
144struct PreAuthRejectRateLimit {
145    next_allowed_ns: AtomicU64,
146    suppressed: AtomicU64,
147}
148
149impl PreAuthRejectRateLimit {
150    const fn new() -> Self {
151        Self {
152            next_allowed_ns: AtomicU64::new(0),
153            suppressed: AtomicU64::new(0),
154        }
155    }
156}
157
158/// Rate-limit state for pre-authentication rejection logs, owned by one
159/// `ServerAuth` so each listener (and each test) counts only its own rejects.
160#[derive(Debug)]
161struct PreAuthRejectLog {
162    epoch: Instant,
163    limiter: PreAuthRejectLimiter,
164}
165
166impl PreAuthRejectLog {
167    fn new() -> Self {
168        Self {
169            epoch: Instant::now(),
170            limiter: PreAuthRejectLimiter::new(),
171        }
172    }
173}
174
175// Report accumulated rejects on the next allowed line instead of running a timer task.
176#[derive(Debug)]
177struct PreAuthRejectLimiter {
178    stages: [PreAuthRejectRateLimit; 6],
179}
180
181impl PreAuthRejectLimiter {
182    fn new() -> Self {
183        Self {
184            stages: std::array::from_fn(|_| PreAuthRejectRateLimit::new()),
185        }
186    }
187
188    fn allow_at(&self, stage: PreAuthRejectStage, now: Duration) -> Option<u64> {
189        let slot = &self.stages[stage.index()];
190        let now_ns = now.as_nanos().min(u64::MAX as u128) as u64;
191        let interval_ns = PRE_AUTH_REJECT_LOG_INTERVAL.as_nanos() as u64;
192        let mut next_allowed_ns = slot.next_allowed_ns.load(AtomicOrdering::Relaxed);
193
194        loop {
195            if now_ns < next_allowed_ns {
196                slot.suppressed.fetch_add(1, AtomicOrdering::Relaxed);
197                return None;
198            }
199
200            match slot.next_allowed_ns.compare_exchange_weak(
201                next_allowed_ns,
202                now_ns.saturating_add(interval_ns),
203                AtomicOrdering::Relaxed,
204                AtomicOrdering::Relaxed,
205            ) {
206                Ok(_) => return Some(slot.suppressed.swap(0, AtomicOrdering::Relaxed)),
207                Err(actual) => next_allowed_ns = actual,
208            }
209        }
210    }
211}
212
213fn log_pre_auth_rejection(
214    error: &ConnectionError,
215    peer_addr: SocketAddr,
216    elapsed: Duration,
217    now: Duration,
218    limiter: &PreAuthRejectLimiter,
219) {
220    let Some(stage) = error.pre_auth_reject_stage() else {
221        return;
222    };
223    let Some(suppressed_since_last) = limiter.allow_at(stage, now) else {
224        return;
225    };
226    let elapsed_ms = elapsed.as_millis().min(u64::MAX as u128) as u64;
227
228    info!(
229        peer_addr = %peer_addr,
230        elapsed_ms,
231        stage = stage.stage(),
232        reason = stage.reason(),
233        auth_stage = ?error.auth_stage(),
234        suppressed_since_last,
235        error = %error,
236        "subc TCP connection rejected before routing"
237    );
238}
239
240async fn handle_accepted_connection<S>(
241    stream: S,
242    router: Arc<Router>,
243    auth: ServerAuth,
244    peer_addr: SocketAddr,
245    accepted_at: Instant,
246) -> Result<(), ConnectionError>
247where
248    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
249{
250    let reject_log = Arc::clone(&auth.pre_auth_reject_log);
251    let result = handle_connection(stream, router, auth).await;
252    if let Err(error) = &result {
253        if error.is_quiet_reject() {
254            log_pre_auth_rejection(
255                error,
256                peer_addr,
257                accepted_at.elapsed(),
258                reject_log.epoch.elapsed(),
259                &reject_log.limiter,
260            );
261        } else {
262            warn!(?peer_addr, error = %error, "subc connection ended with error");
263        }
264    }
265    result
266}
267
268/// Authentication material and DoS bounds applied before a TCP connection may
269/// reach the frame router.
270#[derive(Clone)]
271pub struct ServerAuth {
272    key: Arc<[u8]>,
273    daemon_id: [u8; DAEMON_ID_LEN],
274    daemon_ver: Arc<str>,
275    deadline: Duration,
276    unauthenticated: Arc<Semaphore>,
277    connected_clients: ConnectedClients,
278    pre_auth_reject_log: Arc<PreAuthRejectLog>,
279}
280
281impl ServerAuth {
282    pub fn new(
283        key: Vec<u8>,
284        daemon_id: [u8; DAEMON_ID_LEN],
285        daemon_ver: impl Into<String>,
286    ) -> Self {
287        Self::with_limits(
288            key,
289            daemon_id,
290            daemon_ver,
291            DEFAULT_AUTH_DEADLINE,
292            DEFAULT_MAX_UNAUTHENTICATED_CONNECTIONS,
293        )
294    }
295
296    // Production limits are deliberately not config-routed: loosening pre-auth DoS posture changes attack surface.
297    pub fn with_limits(
298        key: Vec<u8>,
299        daemon_id: [u8; DAEMON_ID_LEN],
300        daemon_ver: impl Into<String>,
301        deadline: Duration,
302        max_unauthenticated: usize,
303    ) -> Self {
304        Self {
305            key: Arc::from(key),
306            daemon_id,
307            daemon_ver: Arc::from(daemon_ver.into()),
308            deadline,
309            unauthenticated: Arc::new(Semaphore::new(max_unauthenticated.max(1))),
310            connected_clients: ConnectedClients::new(),
311            pre_auth_reject_log: Arc::new(PreAuthRejectLog::new()),
312        }
313    }
314
315    pub fn with_connected_clients(mut self, connected_clients: ConnectedClients) -> Self {
316        self.connected_clients = connected_clients;
317        self
318    }
319}
320
321impl fmt::Debug for ServerAuth {
322    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
323        f.debug_struct("ServerAuth")
324            .field("key", &"<redacted>")
325            .field("daemon_id", &self.daemon_id)
326            .field("daemon_ver", &self.daemon_ver)
327            .field("deadline", &self.deadline)
328            .finish_non_exhaustive()
329    }
330}
331
332/// Serve an already-bound TCP listener. Each accepted connection gets its own
333/// async task so concurrent clients do not block the accept loop.
334pub async fn serve_listener(
335    listener: TcpListener,
336    router: Arc<Router>,
337    auth: ServerAuth,
338) -> Result<(), ServerError> {
339    serve_listener_with_accept(listener.local_addr().ok(), router, auth, || {
340        listener.accept()
341    })
342    .await
343}
344
345async fn serve_listener_with_accept<A, F>(
346    local_addr: Option<SocketAddr>,
347    router: Arc<Router>,
348    auth: ServerAuth,
349    mut accept: A,
350) -> Result<(), ServerError>
351where
352    A: FnMut() -> F,
353    F: std::future::Future<Output = io::Result<(tokio::net::TcpStream, SocketAddr)>>,
354{
355    loop {
356        let (stream, peer_addr) = match accept().await {
357            Ok(accepted) => accepted,
358            Err(source) => {
359                let kind = source.kind();
360                // Aborted/reset connections and interrupted syscalls affect one accept only.
361                // File-descriptor or socket-buffer exhaustion needs a short backoff to avoid spinning;
362                // other errors may mean the listener itself is unusable.
363                let exhausted = accept_resource_exhausted(&source);
364                if matches!(
365                    kind,
366                    io::ErrorKind::ConnectionAborted
367                        | io::ErrorKind::ConnectionReset
368                        | io::ErrorKind::Interrupted
369                ) || exhausted
370                {
371                    warn!(?local_addr, error = %source, "temporary TCP accept failure");
372                    if exhausted {
373                        tokio::time::sleep(Duration::from_millis(75)).await;
374                    }
375                    continue;
376                }
377                return Err(ServerError::Accept { local_addr, source });
378            }
379        };
380        let accepted_at = Instant::now();
381        // Every route frame is a discrete message whose reply the peer is waiting
382        // for, so there is never a later write for Nagle to coalesce with -- it can
383        // only hold a frame back until an ACK arrives.
384        //
385        // MEASURED: no effect on this transport. A 50-sample-per-arm sweep from
386        // 1 to 32 KiB over the full client->daemon->module->client path showed a
387        // flat 0.28-0.38ms p50 with no step at any buffer boundary, because a
388        // loopback ACK returns in microseconds and never reaches the delayed-ACK
389        // timer that makes Nagle expensive on a real network. Kept anyway: it is
390        // one syscall at accept, it removes the mechanism rather than relying on
391        // loopback staying fast, and Windows loopback was not part of that sweep.
392        // Do not cite it as a latency fix -- the measurement says it is not one.
393        //
394        // Failure is not fatal: the connection works, and refusing to serve a
395        // client over a socket option would be worse than anything it saves.
396        if let Err(source) = stream.set_nodelay(true) {
397            warn!(?peer_addr, error = %source, "could not disable Nagle on accepted connection");
398        }
399        debug!(?peer_addr, ?local_addr, "accepted subc TCP connection");
400        let router = Arc::clone(&router);
401        let auth = auth.clone();
402        tokio::spawn(async move {
403            let _ = handle_accepted_connection(stream, router, auth, peer_addr, accepted_at).await;
404        });
405    }
406}
407
408#[cfg_attr(not(unix), allow(dead_code))]
409fn temporary_accept_failure(source: &io::Error) -> bool {
410    matches!(
411        source.kind(),
412        io::ErrorKind::ConnectionAborted
413            | io::ErrorKind::ConnectionReset
414            | io::ErrorKind::Interrupted
415    ) || accept_resource_exhausted(source)
416}
417
418fn accept_resource_exhausted(error: &io::Error) -> bool {
419    // ENFILE/EMFILE/ENOBUFS by name rather than number: the numbers differ by
420    // platform (ENOBUFS is 55 on macOS and 105 on Linux, and each number means
421    // something unrelated on the other), so a literal list misclassifies.
422    // Winsock: WSAEMFILE and WSAENOBUFS.
423    #[cfg(unix)]
424    {
425        use rustix::io::Errno;
426        let exhausted = [Errno::NFILE, Errno::MFILE, Errno::NOBUFS];
427        error
428            .raw_os_error()
429            .is_some_and(|code| exhausted.iter().any(|e| e.raw_os_error() == code))
430    }
431    #[cfg(windows)]
432    {
433        matches!(error.raw_os_error(), Some(10024 | 10055))
434    }
435    #[cfg(not(any(unix, windows)))]
436    {
437        let _ = error;
438        false
439    }
440}
441
442/// Serve this daemon's local endpoint (a Unix-domain socket, or a Windows named
443/// pipe) until its accept loop fails.
444///
445/// Every connection gets the same key handshake, frame format and router as a
446/// TCP client, so a client's bytes are identical either way. What differs is
447/// that this endpoint serves clients only: a HELLO that would register a module
448/// is refused with [`crate::local_listener::LOCAL_ENDPOINT_CLIENTS_ONLY`]. A
449/// peer read failure costs that one connection; a failure to accept at all ends
450/// the loop, because a local listener that cannot accept is no longer an
451/// endpoint.
452pub async fn serve_local_listener(
453    bound: crate::local_listener::BoundLocalListener,
454    router: Arc<Router>,
455    auth: ServerAuth,
456) -> Result<(), ServerError> {
457    match bound {
458        #[cfg(unix)]
459        crate::local_listener::BoundLocalListener::Unix { listener, path } => {
460            serve_unix_local(listener, path, router, auth).await
461        }
462        #[cfg(windows)]
463        crate::local_listener::BoundLocalListener::Windows {
464            pipe_name,
465            first_instance,
466        } => serve_pipe_local(pipe_name, first_instance, router, auth).await,
467        // The variants above exist only on their own platform.
468        #[allow(unreachable_patterns)]
469        _ => Err(ServerError::NoListeners),
470    }
471}
472
473#[cfg(unix)]
474async fn serve_unix_local(
475    listener: std::os::unix::net::UnixListener,
476    path: std::path::PathBuf,
477    router: Arc<Router>,
478    auth: ServerAuth,
479) -> Result<(), ServerError> {
480    // The socket file is removed when this future ends, whether it returns or is
481    // dropped during shutdown, so a later daemon start finds no leftover.
482    let _release = SocketFileRelease(path.clone());
483    listener
484        .set_nonblocking(true)
485        .map_err(|source| local_accept_error(&path, source))?;
486    let listener = tokio::net::UnixListener::from_std(listener)
487        .map_err(|source| local_accept_error(&path, source))?;
488    loop {
489        let (stream, _addr) = match listener.accept().await {
490            Ok(accepted) => accepted,
491            Err(source) if temporary_accept_failure(&source) => {
492                warn!(error = %source, "temporary local-socket accept failure");
493                if accept_resource_exhausted(&source) {
494                    tokio::time::sleep(Duration::from_millis(75)).await;
495                }
496                continue;
497            }
498            Err(source) => return Err(local_accept_error(&path, source)),
499        };
500        debug!(?path, "accepted a local-socket connection");
501        let router = Arc::clone(&router);
502        let auth = auth.clone();
503        tokio::spawn(async move {
504            let _ = handle_accepted_local_connection(stream, router, auth).await;
505        });
506    }
507}
508
509#[cfg(unix)]
510fn local_accept_error(endpoint: &std::path::Path, source: io::Error) -> ServerError {
511    ServerError::LocalAccept {
512        endpoint: endpoint.display().to_string(),
513        source,
514    }
515}
516
517#[cfg(unix)]
518struct SocketFileRelease(std::path::PathBuf);
519
520#[cfg(unix)]
521impl Drop for SocketFileRelease {
522    fn drop(&mut self) {
523        crate::local_listener::remove_unix_socket(&self.0);
524    }
525}
526
527#[cfg(windows)]
528async fn serve_pipe_local(
529    pipe_name: String,
530    first_instance: Option<tokio::net::windows::named_pipe::NamedPipeServer>,
531    router: Arc<Router>,
532    auth: ServerAuth,
533) -> Result<(), ServerError> {
534    // The end a client may connect to. An end exists whenever the loop is not
535    // accepting one, because Win32 refuses a client that finds none, and no
536    // other task accepts ends here.
537    let mut free = first_instance;
538    loop {
539        let server = match free.take() {
540            Some(server) => server,
541            None => create_pipe_instance(&pipe_name)?,
542        };
543        // Overlapped I/O: the accepted end is AsyncRead and AsyncWrite, so a
544        // connection's reader and writer never wait for each other. A
545        // synchronous handle would, and the daemon's reply would sit behind the
546        // reader's pending read while the client waited for that reply.
547        if let Err(source) = server.connect().await {
548            if temporary_accept_failure(&source) {
549                continue;
550            }
551            return Err(ServerError::LocalAccept {
552                endpoint: pipe_name.clone(),
553                source,
554            });
555        }
556        // The next end is made before this one is served, so a client that
557        // arrives while this one is being served still finds an end.
558        free = Some(create_pipe_instance(&pipe_name)?);
559        let router = Arc::clone(&router);
560        let auth = auth.clone();
561        tokio::spawn(async move {
562            // A network client is refused before a byte is read. The pipe also
563            // carries PIPE_REJECT_REMOTE_CLIENTS, so this is the second gate.
564            match subc_os::named_pipe::reject_remote_client(&server) {
565                Err(error) => {
566                    warn!(%error, "refused a non-local named-pipe client on the local endpoint");
567                }
568                Ok(()) => {
569                    let _ = handle_accepted_local_connection(server, router, auth).await;
570                }
571            }
572        });
573    }
574}
575
576#[cfg(windows)]
577fn create_pipe_instance(
578    pipe_name: &str,
579) -> Result<tokio::net::windows::named_pipe::NamedPipeServer, ServerError> {
580    crate::local_listener::create_named_pipe_end(pipe_name).map_err(|source| {
581        ServerError::LocalAccept {
582            endpoint: pipe_name.to_owned(),
583            source,
584        }
585    })
586}
587
588/// Run one local-endpoint connection: the same handshake as TCP, with the
589/// clients-only rule attached after it.
590async fn handle_accepted_local_connection<S>(
591    stream: S,
592    router: Arc<Router>,
593    auth: ServerAuth,
594) -> Result<(), ConnectionError>
595where
596    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
597{
598    let result = handle_connection_with_origin(stream, router, auth, LocalOrigin::Local).await;
599    if let Err(error) = &result {
600        debug!(error = %error, "local-endpoint connection ended");
601    }
602    result
603}
604
605/// Where a connection came in. The local endpoint serves clients only, because
606/// a module registers over TCP, where the daemon can tell a launched process
607/// apart by the launch nonce in its HELLO.
608#[derive(Debug, Clone, Copy, PartialEq, Eq)]
609pub(crate) enum LocalOrigin {
610    Tcp,
611    Local,
612}
613
614/// Serve all already-bound loopback TCP listeners until one accept loop fails.
615pub async fn serve_listeners(
616    listeners: Vec<TcpListener>,
617    router: Arc<Router>,
618    auth: ServerAuth,
619) -> Result<(), ServerError> {
620    if listeners.is_empty() {
621        return Err(ServerError::NoListeners);
622    }
623
624    let (tx, mut rx) = mpsc::channel(listeners.len());
625    let mut accept_tasks = AbortTasksOnDrop::default();
626    for listener in listeners {
627        let router = Arc::clone(&router);
628        let auth = auth.clone();
629        let tx = tx.clone();
630        accept_tasks.push(tokio::spawn(async move {
631            let result = serve_listener(listener, router, auth).await;
632            let _ = tx.send(result).await;
633        }));
634    }
635    drop(tx);
636
637    rx.recv().await.unwrap_or(Ok(()))
638}
639
640#[derive(Default)]
641struct AbortTasksOnDrop {
642    handles: Vec<JoinHandle<()>>,
643}
644
645impl AbortTasksOnDrop {
646    fn push(&mut self, handle: JoinHandle<()>) {
647        self.handles.push(handle);
648    }
649}
650
651impl Drop for AbortTasksOnDrop {
652    fn drop(&mut self) {
653        for handle in &self.handles {
654            if !handle.is_finished() {
655                handle.abort();
656            }
657        }
658    }
659}
660
661#[derive(Debug)]
662enum ConnectionLoopExit {
663    PeerClosed,
664    CloseRequested(CloseReason),
665}
666
667/// Run the authenticated frame read -> route loop for one connection.
668///
669/// Every accepted TCP connection must complete the key-auth prelude before any
670/// envelope bytes are read by the router. Outbound frames flow through a bounded
671/// [`FrameSink`] drained by one writer task. Inbound dispatch remains serial for
672/// every frame except `route.open`, activity operations and privileged requests;
673/// their bind, file and operator waits run in connection-owned tasks so
674/// unrelated frames can keep flowing.
675pub async fn handle_connection<S>(
676    stream: S,
677    router: Arc<Router>,
678    auth: ServerAuth,
679) -> Result<(), ConnectionError>
680where
681    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
682{
683    handle_connection_with_origin(stream, router, auth, LocalOrigin::Tcp).await
684}
685
686/// [`handle_connection`] for one endpoint kind: `origin` decides whether a
687/// module HELLO is refused before it can register.
688pub(crate) async fn handle_connection_with_origin<S>(
689    mut stream: S,
690    router: Arc<Router>,
691    auth: ServerAuth,
692    origin: LocalOrigin,
693) -> Result<(), ConnectionError>
694where
695    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
696{
697    // Capture only socket facts here. Process-table lookup happens lazily on a
698    // blocking thread when privileged dispatch needs a caller description.
699    let endpoints = (&stream as &dyn Any)
700        .downcast_ref::<tokio::net::TcpStream>()
701        .and_then(|tcp| tcp.local_addr().ok().zip(tcp.peer_addr().ok()));
702    // Over-cap connections WAIT for a handshake slot (bounded by the auth deadline)
703    // instead of being reset. A restart herd — every client and supervised child
704    // re-dialing the fresh daemon at once — otherwise loses supervised modules to
705    // the permit lottery: each reset burns a module restart-budget slot, and a
706    // module that treats auth failure as fatal can exhaust its budget into
707    // state=failed within the boot window (2026-07-14 aft outage). On loopback
708    // with the pre-auth HMAC deadline, a bounded queue is strictly safer than a
709    // reset.
710    //
711    // Pre-auth time is governed by TWO deliberately separate budgets: the queue
712    // wait below is bounded by `auth.deadline`, and `authenticate_server` then
713    // starts a FRESH `auth.deadline` for the handshake itself. Total pre-auth
714    // occupancy per connection is therefore up to 2x the configured deadline.
715    // This is intentional, not an accounting slip: charging queue time against
716    // the handshake budget would hand a herd-queued supervised module a
717    // near-zero handshake window under CPU saturation, recreating the fatal
718    // auth-failure -> restart-budget-burn path this queue exists to prevent.
719    // On a loopback-only, key-authenticated listener the doubled bound is a
720    // per-connection occupancy cost, not a meaningful DoS surface.
721    let permit =
722        match tokio::time::timeout(auth.deadline, auth.unauthenticated.clone().acquire_owned())
723            .await
724        {
725            Ok(Ok(permit)) => permit,
726            Ok(Err(_)) | Err(_) => {
727                let _ = stream.shutdown().await;
728                return Err(ConnectionError::UnauthenticatedCapacity);
729            }
730        };
731
732    let authenticated = authenticate_server(
733        &mut stream,
734        auth.key.as_ref(),
735        &auth.daemon_id,
736        auth.daemon_ver.as_ref(),
737        auth.deadline,
738    )
739    .await
740    .map_err(ConnectionError::Auth)?;
741    drop(permit);
742
743    let mut connection = router.begin_connection();
744    let connection_id = connection.id();
745    router.record_caller_endpoints(connection_id, endpoints);
746    // `authenticated.role` is CLIENT-SUPPLIED and unverified -- the handshake
747    // proves possession of the connection key, nothing about who is calling. So
748    // this exclusion is safe ONLY while the role decides a reporting question and
749    // never an authorization one: the watchdog's own loopback probe would
750    // otherwise inflate the very count it exists to sanity-check.
751    //
752    // The consequence of it being unverified, stated so nobody has to rediscover
753    // it: ANY client holding the key can claim this role and omit itself from
754    // `connected_clients`. That is a gauge a caller can lie to, and it is
755    // acceptable because the gauge informs an operator rather than gating
756    // anything. IF A ROLE IS EVER USED TO DECIDE ADMISSION, CAPACITY, OR PRIVILEGE,
757    // this stops being safe and the role must be attested rather than declared --
758    // the daemon already has the mechanism for that in the spawn-nonce path used
759    // for module identity.
760    let _connected_client = (authenticated.role != WATCHDOG_CLIENT_ROLE)
761        .then(|| auth.connected_clients.open(connection_id));
762    let close_receiver = connection.take_close_receiver();
763    debug!(
764        connection_id = connection_id.get(),
765        "subc authenticated connection opened"
766    );
767
768    let (read_half, write_half) = tokio::io::split(stream);
769    // Authentication is complete before this buffer can read ahead. The connection loop
770    // retains a partial frame read across completed route.open tasks; dropping the read
771    // happens only when a frame finishes or the connection ends.
772    let mut read_half = BufReader::new(read_half);
773    let (egress, rx) = connection_egress();
774    let delivery_guard = ClientDeliveryGuard(egress.clone());
775    let writer = tokio::spawn(drain_writer(write_half, rx));
776
777    let ctx = RouteCtx {
778        connection_id,
779        egress: egress.clone(),
780    };
781
782    let mut route_open_tasks = JoinSet::new();
783    let mut privileged_tasks = JoinSet::new();
784    let loop_result = connection_loop(
785        &mut read_half,
786        Arc::clone(&router),
787        ctx.clone(),
788        close_receiver,
789        &mut route_open_tasks,
790        &mut privileged_tasks,
791        origin,
792    )
793    .await;
794
795    drop(delivery_guard);
796    // Every in-flight route.open must have FINISHED before `connection` drops,
797    // because that drop runs the forwarding cleanup for this id, and cleanup is
798    // also where the id's closing mark is lifted. Dropping a JoinSet only
799    // requests abort: a task already running on another worker keeps going
800    // until its next await, and could commit a route for this connection after
801    // cleanup has cleared it, with nothing left to refuse it and nothing to
802    // clean it up. shutdown() aborts and then waits.
803    route_open_tasks.shutdown().await;
804    // Abort held approvals and wait for their withdrawal guards before lifting
805    // this connection's cleanup state or removing its caller endpoints.
806    privileged_tasks.shutdown().await;
807
808    drop(ctx);
809    drop(egress);
810    drop(connection);
811
812    let close_reason = match &loop_result {
813        Ok(ConnectionLoopExit::CloseRequested(reason)) => Some(reason.to_string()),
814        Ok(ConnectionLoopExit::PeerClosed) | Err(_) => None,
815    };
816    let writer_result = finish_connection_writer(writer, connection_id.get()).await;
817
818    let result = if let Some(reason) = close_reason.as_deref() {
819        match writer_result {
820            Some(Ok(Ok(()))) | None => Ok(()),
821            Some(Ok(Err(writer_err))) => {
822                debug!(
823                    connection_id = connection_id.get(),
824                    close_reason = reason,
825                    writer_error = %writer_err,
826                    "writer failed after requested connection close"
827                );
828                Ok(())
829            }
830            Some(Err(join_err)) => {
831                warn!(
832                    connection_id = connection_id.get(),
833                    close_reason = reason,
834                    join_error = %join_err,
835                    "writer task join failed after requested connection close"
836                );
837                Ok(())
838            }
839        }
840    } else {
841        match (loop_result, writer_result) {
842            (Err(loop_err), Some(Ok(Ok(()))) | None) => Err(loop_err),
843            (Err(loop_err), Some(Ok(Err(writer_err)))) => {
844                warn!(
845                    connection_id = connection_id.get(),
846                    writer_error = %writer_err,
847                    "writer failed while closing after connection error"
848                );
849                Err(loop_err)
850            }
851            (Err(loop_err), Some(Err(join_err))) => {
852                warn!(
853                    connection_id = connection_id.get(),
854                    join_error = %join_err,
855                    "writer task join failed while closing after connection error"
856                );
857                Err(loop_err)
858            }
859            (Ok(ConnectionLoopExit::PeerClosed), Some(Ok(Ok(()))) | None) => Ok(()),
860            (Ok(ConnectionLoopExit::PeerClosed), Some(Ok(Err(writer_err)))) => {
861                Err(ConnectionError::FrameIo(writer_err))
862            }
863            (Ok(ConnectionLoopExit::PeerClosed), Some(Err(join_err))) => Err(join_err),
864            (Ok(ConnectionLoopExit::CloseRequested(_)), _) => {
865                unreachable!("close requests are handled before normal writer result matching")
866            }
867        }
868    };
869
870    match &result {
871        Ok(()) => {
872            if let Some(reason) = close_reason.as_deref() {
873                debug!(
874                    connection_id = connection_id.get(),
875                    close_reason = reason,
876                    "subc connection closed by request"
877                );
878            } else {
879                debug!(
880                    connection_id = connection_id.get(),
881                    "subc connection closed"
882                );
883            }
884        }
885        Err(err) => debug!(
886            connection_id = connection_id.get(),
887            error = %err,
888            "subc connection exited with error"
889        ),
890    }
891
892    result
893}
894
895async fn finish_connection_writer(
896    mut writer: JoinHandle<Result<(), FrameIoError>>,
897    connection_id: u64,
898) -> Option<Result<Result<(), FrameIoError>, ConnectionError>> {
899    // Even after inbound EOF or an error, the peer may keep its receive side
900    // open without reading. Give queued frames the same grace on every exit.
901    match timeout(CLOSE_DRAIN_GRACE, &mut writer).await {
902        Ok(result) => Some(result.map_err(ConnectionError::WriterTask)),
903        Err(_) => {
904            warn!(
905                connection_id,
906                grace = ?CLOSE_DRAIN_GRACE,
907                "connection writer did not drain during teardown; aborting writer task"
908            );
909            writer.abort();
910            let _ = writer.await;
911            None
912        }
913    }
914}
915
916async fn connection_loop<R>(
917    read_half: &mut R,
918    router: Arc<Router>,
919    ctx: RouteCtx,
920    mut close_receiver: ConnectionCloseReceiver,
921    route_open_tasks: &mut JoinSet<Result<(), RouterError>>,
922    privileged_tasks: &mut JoinSet<Result<(), RouterError>>,
923    origin: LocalOrigin,
924) -> Result<ConnectionLoopExit, ConnectionError>
925where
926    R: AsyncRead + Unpin,
927{
928    let mut activity_tasks = JoinSet::new();
929    loop {
930        while let Some(result) = activity_tasks.try_join_next() {
931            finish_route_open_task(result)?;
932        }
933        while let Some(result) = privileged_tasks.try_join_next() {
934            finish_route_open_task(result)?;
935        }
936        while let Some(result) = route_open_tasks.try_join_next() {
937            finish_route_open_task(result)?;
938        }
939
940        // Keep the same read future when a route.open completes: read_frame owns
941        // partial header/body buffers that would be lost if that future were dropped.
942        let read = read_frame(&mut *read_half);
943        tokio::pin!(read);
944        let frame = loop {
945            tokio::select! {
946                close = &mut close_receiver => {
947                    return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
948                }
949                result = route_open_tasks.join_next(), if !route_open_tasks.is_empty() => {
950                    finish_route_open_task(
951                        result.expect("a non-empty route.open JoinSet has a next task")
952                    )?;
953                }
954                result = activity_tasks.join_next(), if !activity_tasks.is_empty() => {
955                    finish_route_open_task(result.expect("non-empty activity task set"))?;
956                }
957                result = privileged_tasks.join_next(), if !privileged_tasks.is_empty() => {
958                    finish_route_open_task(result.expect("non-empty privileged task set"))?;
959                }
960                result = &mut read => {
961                    break match result.map_err(ConnectionError::FrameIo)? {
962                        Some(frame) => frame,
963                        None => return Ok(ConnectionLoopExit::PeerClosed),
964                    };
965                }
966            }
967        };
968
969        if origin == LocalOrigin::Local && frame.header.ty == subc_protocol::FrameType::Hello {
970            // A module registers over TCP only. Refusing here, before the router
971            // sees the frame, is what guarantees the local endpoint leaves no
972            // registration, catalog entry or route behind, whatever the HELLO
973            // carries.
974            let refusal = crate::control::control_error_frame(
975                &frame,
976                crate::local_listener::LOCAL_ENDPOINT_CLIENTS_ONLY,
977                "the local endpoint serves clients only; modules register over TCP",
978            )
979            .map_err(ConnectionError::Router)?;
980            // The connection ends as soon as the refusal is sent, so the bytes
981            // must reach the socket first: a client that has not yet read its
982            // reply would otherwise see only the end of the stream.
983            let send_result = tokio::select! {
984                close = &mut close_receiver => {
985                    return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
986                }
987                result = send_refusal(&ctx.egress, refusal) => result,
988            };
989            send_result.map_err(ConnectionError::Router)?;
990            return Ok(ConnectionLoopExit::PeerClosed);
991        }
992
993        if frame.header.channel == 0
994            && frame.header.ty == subc_protocol::FrameType::Request
995            && serde_json::from_slice::<serde_json::Value>(&frame.body)
996                .ok()
997                .is_some_and(|body| {
998                    matches!(
999                        body["op"].as_str(),
1000                        Some(
1001                            subc_control::ops::ACTIVITY_RECORD
1002                                | subc_control::ops::ACTIVITY_QUERY
1003                                | subc_control::ops::ACTIVITY_SUBSCRIBE
1004                        )
1005                    )
1006                })
1007        {
1008            // Bound outstanding activity tasks as well as the disk queue,
1009            // so the reader never waits for either capacity when the disk stalls.
1010            if activity_tasks.len() >= 128 {
1011                let response = crate::control::control_error_frame(
1012                    &frame,
1013                    subc_control::ACTIVITY_UNAVAILABLE,
1014                    "activity queue full",
1015                )
1016                .map_err(ConnectionError::Router)?;
1017                let send_result = tokio::select! {
1018                    close = &mut close_receiver => {
1019                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
1020                    }
1021                    result = ctx.egress.send(response) => result,
1022                };
1023                send_result.map_err(ConnectionError::Router)?;
1024            } else {
1025                let task_router = Arc::clone(&router);
1026                let task_ctx = ctx.clone();
1027                activity_tasks.spawn(async move {
1028                    route_open_tail(task_router, task_ctx, frame, Instant::now()).await
1029                });
1030            }
1031            continue;
1032        }
1033
1034        if let Some(target_module_id) = router.route_open_target(&frame) {
1035            // A task can finish while the reader is waiting for the next frame.
1036            // Reap it before checking admission so completed work never occupies
1037            // one of the deliberately scarce connection slots.
1038            while let Some(result) = route_open_tasks.try_join_next() {
1039                finish_route_open_task(result)?;
1040            }
1041
1042            if route_open_tasks.len() >= MAX_PENDING_ROUTE_OPENS_PER_CONNECTION {
1043                // Never wait for capacity here: doing so would recreate the same
1044                // reader head-of-line stall with a smaller constant.
1045                let refusal = router
1046                    .route_open_capacity_refusal(
1047                        &ctx,
1048                        &frame,
1049                        &target_module_id,
1050                        route_open_tasks.len(),
1051                        MAX_PENDING_ROUTE_OPENS_PER_CONNECTION,
1052                    )
1053                    .map_err(ConnectionError::Router)?;
1054                let send_result = tokio::select! {
1055                    close = &mut close_receiver => {
1056                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
1057                    }
1058                    result = ctx.egress.send(refusal) => result,
1059                };
1060                send_result.map_err(ConnectionError::Router)?;
1061                continue;
1062            }
1063
1064            let task_router = Arc::clone(&router);
1065            let task_ctx = ctx.clone();
1066            // Start slow-dispatch timing before spawn so it covers the task's
1067            // full scheduler and handler lifetime, as inline timing did.
1068            let dispatch_started_at = Instant::now();
1069            route_open_tasks.spawn(async move {
1070                route_open_tail(task_router, task_ctx, frame, dispatch_started_at).await
1071            });
1072            continue;
1073        }
1074
1075        if router.defers_privileged_control(&ctx, &frame) {
1076            let task_router = Arc::clone(&router);
1077            let task_ctx = ctx.clone();
1078            let started = Instant::now();
1079            privileged_tasks
1080                .spawn(async move { route_open_tail(task_router, task_ctx, frame, started).await });
1081            continue;
1082        }
1083
1084        // Other frames still route serially: routing can backpressure reads,
1085        // and a connection close cancels the in-progress route.
1086        let route_result = tokio::select! {
1087            close = &mut close_receiver => {
1088                return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
1089            }
1090            result = router.route_for_connection(&ctx, frame) => result,
1091        };
1092
1093        if let Err(err) = route_result {
1094            if let Some(error_frame) = err.to_error_frame() {
1095                warn!(
1096                    connection_id = ctx.connection_id.get(),
1097                    error = %err,
1098                    "routing failure recovered with ERROR frame"
1099                );
1100                let send_result = tokio::select! {
1101                    close = &mut close_receiver => {
1102                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
1103                    }
1104                    result = ctx.egress.send(error_frame) => result,
1105                };
1106                send_result.map_err(ConnectionError::Router)?;
1107            } else {
1108                debug!(
1109                    connection_id = ctx.connection_id.get(),
1110                    error = %err,
1111                    "fatal routing failure"
1112                );
1113                return Err(ConnectionError::Router(err));
1114            }
1115        }
1116    }
1117}
1118
1119/// Send one frame so that a connection ending immediately afterwards still
1120/// delivers it: on Unix, wait for the writer's flush acknowledgement; elsewhere
1121/// queue it, because those writers carry no acknowledgement.
1122async fn send_refusal(sink: &FrameSink, frame: crate::Frame) -> Result<(), RouterError> {
1123    // The flush acknowledgement comes from the writer's `write_frame`, which
1124    // only the Unix builds expose; on Windows the refusal is queued for the pipe
1125    // writer instead.
1126    #[cfg(unix)]
1127    {
1128        sink.send_flushed(frame).await
1129    }
1130    #[cfg(not(unix))]
1131    {
1132        sink.send(frame).await
1133    }
1134}
1135
1136async fn route_open_tail(
1137    router: Arc<Router>,
1138    ctx: RouteCtx,
1139    frame: crate::Frame,
1140    dispatch_started_at: Instant,
1141) -> Result<(), RouterError> {
1142    match router
1143        .route_for_connection_started(&ctx, frame, Some(dispatch_started_at))
1144        .await
1145    {
1146        Ok(()) => Ok(()),
1147        Err(err) => {
1148            let Some(error_frame) = err.to_error_frame() else {
1149                return Err(err);
1150            };
1151            warn!(
1152                connection_id = ctx.connection_id.get(),
1153                error = %err,
1154                "routing failure recovered with ERROR frame"
1155            );
1156            ctx.egress.send(error_frame).await
1157        }
1158    }
1159}
1160
1161fn finish_route_open_task(
1162    result: Result<Result<(), RouterError>, tokio::task::JoinError>,
1163) -> Result<(), ConnectionError> {
1164    match result {
1165        Ok(Ok(())) => Ok(()),
1166        Ok(Err(err)) => Err(ConnectionError::Router(err)),
1167        Err(err) => Err(ConnectionError::Router(RouterError::backend(
1168            0,
1169            0,
1170            format!("route.open task failed: {err}"),
1171        ))),
1172    }
1173}
1174
1175fn close_reason(
1176    result: Result<CloseReason, tokio::sync::oneshot::error::RecvError>,
1177) -> CloseReason {
1178    result.unwrap_or_else(|_| {
1179        CloseReason::new(
1180            "close_registry_dropped",
1181            "connection close registration was dropped without a reason",
1182        )
1183    })
1184}
1185
1186/// The outbound queue for one daemon connection: a sink bounded by
1187/// [`CONNECTION_EGRESS_BYTE_BUDGET`] and [`CONNECTION_EGRESS_FRAME_CAP`], and
1188/// the receiver its writer drains.
1189pub(crate) fn connection_egress() -> (FrameSink, mpsc::Receiver<crate::router::OutboundFrame>) {
1190    let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(CONNECTION_EGRESS_FRAME_CAP);
1191    (
1192        FrameSink::with_byte_budget(tx, CONNECTION_EGRESS_BYTE_BUDGET),
1193        rx,
1194    )
1195}
1196
1197async fn drain_writer<W>(
1198    write_half: W,
1199    mut rx: mpsc::Receiver<crate::router::OutboundFrame>,
1200) -> Result<(), FrameIoError>
1201where
1202    W: AsyncWrite + Unpin,
1203{
1204    let mut writer = BufWriter::new(write_half);
1205    while let Some(outbound) = rx.recv().await {
1206        write_outbound(&mut writer, outbound).await?;
1207        while let Ok(outbound) = rx.try_recv() {
1208            write_outbound(&mut writer, outbound).await?;
1209        }
1210        writer.flush().await.map_err(FrameIoError::Io)?;
1211    }
1212    writer.flush().await.map_err(FrameIoError::Io)?;
1213    Ok(())
1214}
1215
1216/// Reply-path half of slow-control diagnosis: a channel-0 reply that sat in
1217/// the writer queue past the threshold is reported with its queue residency
1218/// and its own write duration separated, because "writer task not scheduled"
1219/// and "socket write blocked" are different defects and the sum hides which.
1220/// Data-plane frames are exempt: their latency is the client's own flow
1221/// control, and logging them would drown the control signal in bulk traffic.
1222async fn write_outbound<W>(
1223    writer: &mut BufWriter<W>,
1224    outbound: crate::router::OutboundFrame,
1225) -> Result<(), FrameIoError>
1226where
1227    W: AsyncWrite + Unpin,
1228{
1229    const SLOW_REPLY_QUEUE: Duration = Duration::from_millis(1000);
1230    let queued = outbound.enqueued_at.elapsed();
1231    // Held until this frame has been written, then dropped at the end of this
1232    // function, which gives its bytes back to the connection's egress budget.
1233    let charge = outbound.charge;
1234    if let Some(charge) = &charge {
1235        charge.taken_by_writer();
1236    }
1237    let frame = outbound.frame;
1238    if frame.header.channel == 0 && queued >= SLOW_REPLY_QUEUE {
1239        let write_started = std::time::Instant::now();
1240        let result = write_frame(writer, &frame).await;
1241        tracing::warn!(
1242            corr = frame.header.corr,
1243            queued_ms = queued.as_millis() as u64,
1244            write_ms = write_started.elapsed().as_millis() as u64,
1245            "slow control reply write"
1246        );
1247        result?;
1248    } else {
1249        write_frame(writer, &frame).await?;
1250    }
1251    if let Some(flushed) = outbound.flushed {
1252        writer.flush().await.map_err(FrameIoError::Io)?;
1253        let _ = flushed.send(());
1254    }
1255    Ok(())
1256}
1257
1258#[cfg(all(test, unix))]
1259#[tokio::test]
1260async fn shutdown_notice_ack_waits_for_socket_flush() {
1261    let (socket, mut peer) = tokio::io::duplex(1);
1262    let (tx, rx) = mpsc::channel(1);
1263    let sink = FrameSink::new(tx);
1264    let writer = tokio::spawn(drain_writer(socket, rx));
1265    let frame = crate::Frame::build(
1266        subc_protocol::FrameType::Push,
1267        subc_protocol::Flags::new(false, subc_protocol::Priority::Interactive, false),
1268        0,
1269        0,
1270        0,
1271        b"notice".to_vec(),
1272    )
1273    .unwrap();
1274    let send = sink.send_flushed(frame);
1275    tokio::pin!(send);
1276    assert!(
1277        timeout(Duration::from_millis(20), &mut send).await.is_err(),
1278        "queueing bytes is not a socket flush acknowledgement"
1279    );
1280    let (sent, received) = timeout(Duration::from_secs(1), async {
1281        tokio::join!(&mut send, read_frame(&mut peer))
1282    })
1283    .await
1284    .unwrap();
1285    sent.unwrap();
1286    assert_eq!(received.unwrap().unwrap().body, b"notice");
1287    writer.abort();
1288}
1289
1290#[derive(Debug)]
1291pub enum ServerError {
1292    NoListeners,
1293    Accept {
1294        local_addr: Option<SocketAddr>,
1295        source: io::Error,
1296    },
1297    /// The local endpoint (a Unix-domain socket or a named pipe) could not be
1298    /// created or could not accept.
1299    LocalAccept {
1300        endpoint: String,
1301        source: io::Error,
1302    },
1303}
1304
1305impl fmt::Display for ServerError {
1306    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1307        match self {
1308            Self::NoListeners => write!(f, "no TCP listeners were provided"),
1309            Self::Accept { local_addr, source } => match local_addr {
1310                Some(addr) => write!(f, "failed to accept TCP connection on {addr}: {source}"),
1311                None => write!(f, "failed to accept TCP connection: {source}"),
1312            },
1313            Self::LocalAccept { endpoint, source } => {
1314                write!(f, "local endpoint {endpoint} failed: {source}")
1315            }
1316        }
1317    }
1318}
1319
1320impl Error for ServerError {
1321    fn source(&self) -> Option<&(dyn Error + 'static)> {
1322        match self {
1323            Self::Accept { source, .. } | Self::LocalAccept { source, .. } => Some(source),
1324            Self::NoListeners => None,
1325        }
1326    }
1327}
1328
1329#[derive(Debug)]
1330pub enum ConnectionError {
1331    Auth(AuthError),
1332    UnauthenticatedCapacity,
1333    FrameIo(FrameIoError),
1334    Router(RouterError),
1335    WriterTask(tokio::task::JoinError),
1336}
1337
1338impl ConnectionError {
1339    fn is_quiet_reject(&self) -> bool {
1340        matches!(self, Self::Auth(_) | Self::UnauthenticatedCapacity)
1341    }
1342
1343    fn pre_auth_reject_stage(&self) -> Option<PreAuthRejectStage> {
1344        match self {
1345            Self::UnauthenticatedCapacity => Some(PreAuthRejectStage::WaitingForHandshakeSlot),
1346            Self::Auth(AuthError::Timeout { .. }) => Some(PreAuthRejectStage::HandshakeDeadline),
1347            Self::Auth(
1348                AuthError::InvalidClientAuth
1349                | AuthError::InvalidServerProof
1350                | AuthError::DaemonIdMismatch,
1351            ) => Some(PreAuthRejectStage::InvalidProof),
1352            Self::Auth(AuthError::MessageTooLarge { .. } | AuthError::JsonDecode { .. }) => {
1353                Some(PreAuthRejectStage::MalformedMessage)
1354            }
1355            Self::Auth(AuthError::UnexpectedEof { .. }) => Some(PreAuthRejectStage::PeerClosed),
1356            Self::Auth(AuthError::Io { source, .. })
1357                if matches!(
1358                    source.kind(),
1359                    io::ErrorKind::BrokenPipe
1360                        | io::ErrorKind::ConnectionAborted
1361                        | io::ErrorKind::ConnectionReset
1362                        | io::ErrorKind::UnexpectedEof
1363                ) =>
1364            {
1365                Some(PreAuthRejectStage::PeerClosed)
1366            }
1367            Self::Auth(_) => Some(PreAuthRejectStage::OtherAuthenticationFailure),
1368            Self::FrameIo(_) | Self::Router(_) | Self::WriterTask(_) => None,
1369        }
1370    }
1371
1372    fn auth_stage(&self) -> Option<AuthStage> {
1373        match self {
1374            Self::Auth(
1375                AuthError::Io { stage, .. }
1376                | AuthError::Timeout { stage, .. }
1377                | AuthError::UnexpectedEof { stage, .. }
1378                | AuthError::MessageTooLarge { stage, .. }
1379                | AuthError::JsonEncode { stage, .. }
1380                | AuthError::JsonDecode { stage, .. },
1381            ) => Some(*stage),
1382            Self::Auth(
1383                AuthError::Random(_)
1384                | AuthError::KeyTooShort { .. }
1385                | AuthError::InvalidServerProof
1386                | AuthError::DaemonIdMismatch
1387                | AuthError::InvalidClientAuth,
1388            )
1389            | Self::UnauthenticatedCapacity
1390            | Self::FrameIo(_)
1391            | Self::Router(_)
1392            | Self::WriterTask(_) => None,
1393        }
1394    }
1395}
1396
1397impl fmt::Display for ConnectionError {
1398    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1399        match self {
1400            Self::Auth(err) => write!(f, "connection auth failed: {err}"),
1401            Self::UnauthenticatedCapacity => write!(
1402                f,
1403                "too many concurrent unauthenticated subc TCP connections"
1404            ),
1405            Self::FrameIo(err) => write!(f, "frame connection error: {err}"),
1406            Self::Router(err) => write!(f, "router connection error: {err}"),
1407            Self::WriterTask(err) => write!(f, "connection writer task failed: {err}"),
1408        }
1409    }
1410}
1411
1412impl Error for ConnectionError {
1413    fn source(&self) -> Option<&(dyn Error + 'static)> {
1414        match self {
1415            Self::Auth(err) => Some(err),
1416            Self::FrameIo(err) => Some(err),
1417            Self::Router(err) => Some(err),
1418            Self::WriterTask(err) => Some(err),
1419            Self::UnauthenticatedCapacity => None,
1420        }
1421    }
1422}
1423
1424#[cfg(test)]
1425mod tests {
1426    use std::{
1427        future::Future,
1428        pin::Pin,
1429        sync::atomic::{AtomicUsize, Ordering},
1430        task::{Context, Poll},
1431    };
1432
1433    use super::*;
1434    use serde::{de::DeserializeOwned, Serialize};
1435    use subc_protocol::{
1436        DecodeError, ErrorBody, Flags, FrameType, Priority, HEADER_LEN, PROTOCOL_VERSION,
1437    };
1438    use tokio::io::{duplex, AsyncReadExt, AsyncWriteExt, ReadBuf};
1439
1440    use subc_transport::{
1441        authenticate_client, compute_proof, ClientAuth, ClientHello, ConnectionInfo, Endpoint,
1442        ServerProof, CLIENT_AUTH_DOMAIN, NONCE_LEN, SCHEMA_VERSION,
1443    };
1444
1445    use crate::{ControlHandler, EchoBackend, Frame, ReadStage, Registry};
1446
1447    const TEST_DEADLINE: Duration = Duration::from_secs(2);
1448    const TEST_DAEMON_VER: &str = "test-subc-server";
1449
1450    /// Modules size their replies against the published limit, and the router
1451    /// refuses any module frame over the egress budget, so the two must be the
1452    /// same number. This fails if the budget is ever given its own value.
1453    #[test]
1454    fn egress_budget_is_the_published_delivered_frame_limit() {
1455        assert_eq!(
1456            CONNECTION_EGRESS_BYTE_BUDGET,
1457            subc_protocol::MAX_DELIVERED_FRAME_LEN
1458        );
1459    }
1460
1461    struct ObservedStream {
1462        inner: tokio::io::DuplexStream,
1463        write_blocked: Arc<tokio::sync::Notify>,
1464        dropped: Arc<AtomicUsize>,
1465        read_error: Option<tokio::sync::oneshot::Receiver<()>>,
1466    }
1467
1468    impl AsyncRead for ObservedStream {
1469        fn poll_read(
1470            mut self: Pin<&mut Self>,
1471            cx: &mut Context<'_>,
1472            buf: &mut ReadBuf<'_>,
1473        ) -> Poll<io::Result<()>> {
1474            if let Some(receiver) = self.read_error.as_mut() {
1475                match Pin::new(receiver).poll(cx) {
1476                    Poll::Ready(Ok(())) => {
1477                        self.read_error = None;
1478                        return Poll::Ready(Err(io::ErrorKind::ConnectionReset.into()));
1479                    }
1480                    Poll::Ready(Err(_)) => self.read_error = None,
1481                    Poll::Pending => {}
1482                }
1483            }
1484            Pin::new(&mut self.inner).poll_read(cx, buf)
1485        }
1486    }
1487
1488    impl AsyncWrite for ObservedStream {
1489        fn poll_write(
1490            mut self: Pin<&mut Self>,
1491            cx: &mut Context<'_>,
1492            buf: &[u8],
1493        ) -> Poll<io::Result<usize>> {
1494            let result = Pin::new(&mut self.inner).poll_write(cx, buf);
1495            if result.is_pending() {
1496                self.write_blocked.notify_one();
1497            }
1498            result
1499        }
1500
1501        fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
1502            Pin::new(&mut self.inner).poll_flush(cx)
1503        }
1504
1505        fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
1506            Pin::new(&mut self.inner).poll_shutdown(cx)
1507        }
1508    }
1509
1510    impl Drop for ObservedStream {
1511        fn drop(&mut self) {
1512            self.dropped.fetch_add(1, Ordering::SeqCst);
1513        }
1514    }
1515
1516    struct BlockedWriterConnection {
1517        client: tokio::io::DuplexStream,
1518        server: JoinHandle<Result<(), ConnectionError>>,
1519        stream_dropped: Arc<AtomicUsize>,
1520        read_error: Option<tokio::sync::oneshot::Sender<()>>,
1521        router: Arc<Router>,
1522    }
1523
1524    impl BlockedWriterConnection {
1525        async fn new() -> Self {
1526            let (mut client, inner) = duplex(256);
1527            let write_blocked = Arc::new(tokio::sync::Notify::new());
1528            let stream_dropped = Arc::new(AtomicUsize::new(0));
1529            let (read_error, receiver) = tokio::sync::oneshot::channel();
1530            let stream = ObservedStream {
1531                inner,
1532                write_blocked: Arc::clone(&write_blocked),
1533                dropped: Arc::clone(&stream_dropped),
1534                read_error: Some(receiver),
1535            };
1536            let (auth, conn) = test_auth();
1537            let router = echo_router();
1538            let server = tokio::spawn(handle_connection(stream, Arc::clone(&router), auth));
1539            authenticate(&mut client, &conn).await;
1540
1541            // Ignore any backpressure observed during authentication. The echo
1542            // reply is larger than the duplex capacity and the client never reads it.
1543            let _ = timeout(Duration::ZERO, write_blocked.notified()).await;
1544            write_frame(&mut client, &request(7, 1, &[b'x'; 1024]))
1545                .await
1546                .unwrap();
1547            timeout(TEST_DEADLINE, write_blocked.notified())
1548                .await
1549                .expect("writer should block on the unread echo reply");
1550            assert!(!server.is_finished());
1551            assert_eq!(stream_dropped.load(Ordering::SeqCst), 0);
1552            Self {
1553                client,
1554                server,
1555                stream_dropped,
1556                read_error: Some(read_error),
1557                router,
1558            }
1559        }
1560
1561        async fn finish(&mut self) -> Result<(), ConnectionError> {
1562            let started = tokio::time::Instant::now();
1563            let result = timeout(CLOSE_DRAIN_GRACE + Duration::from_secs(1), &mut self.server)
1564                .await
1565                .expect("connection teardown exceeded writer drain grace plus margin")
1566                .expect("connection task should not panic");
1567            assert!(started.elapsed() >= CLOSE_DRAIN_GRACE);
1568            assert_eq!(
1569                self.stream_dropped.load(Ordering::SeqCst),
1570                1,
1571                "writer must release its stream half before teardown completes"
1572            );
1573            result
1574        }
1575
1576        fn request_close(&self) {
1577            // Each fixture owns a fresh router, so its only connection has ID 1.
1578            assert!(self.router.forwarding().request_connection_close(
1579                crate::registry::ConnectionId::new(1),
1580                CloseReason::new("test_close", "test requested close"),
1581            ));
1582        }
1583    }
1584
1585    #[tokio::test(start_paused = true)]
1586    async fn peer_eof_bounds_blocked_writer_teardown() {
1587        let mut connection = BlockedWriterConnection::new().await;
1588        // Half-close only the client-to-server direction: the unread receive
1589        // buffer must stay alive so the server's writer cannot finish naturally.
1590        connection.client.shutdown().await.unwrap();
1591        connection.finish().await.unwrap();
1592    }
1593
1594    #[tokio::test(start_paused = true)]
1595    async fn read_error_bounds_blocked_writer_teardown() {
1596        let mut connection = BlockedWriterConnection::new().await;
1597        connection.read_error.take().unwrap().send(()).unwrap();
1598        let error = connection.finish().await.unwrap_err();
1599        assert!(matches!(
1600            error,
1601            ConnectionError::FrameIo(FrameIoError::Io(error))
1602                if error.kind() == io::ErrorKind::ConnectionReset
1603        ));
1604    }
1605
1606    #[tokio::test(start_paused = true)]
1607    async fn close_requested_bounds_blocked_writer_teardown() {
1608        let mut connection = BlockedWriterConnection::new().await;
1609        connection.request_close();
1610        connection.finish().await.unwrap();
1611    }
1612
1613    #[tokio::test(start_paused = true)]
1614    async fn close_requested_flushes_queued_reply_before_grace() {
1615        let mut connection = BlockedWriterConnection::new().await;
1616        connection.request_close();
1617        let started = tokio::time::Instant::now();
1618        let reply = timeout(CLOSE_DRAIN_GRACE, read_frame(&mut connection.client))
1619            .await
1620            .expect("queued reply should flush before the grace expires")
1621            .unwrap()
1622            .unwrap();
1623        assert_eq!(reply.body, vec![b'x'; 1024]);
1624        timeout(CLOSE_DRAIN_GRACE, &mut connection.server)
1625            .await
1626            .unwrap()
1627            .unwrap()
1628            .unwrap();
1629        assert!(started.elapsed() < CLOSE_DRAIN_GRACE);
1630        assert_eq!(connection.stream_dropped.load(Ordering::SeqCst), 1);
1631    }
1632
1633    /// Reply-path stamp, slow polarity: a channel-0 reply whose queue residency
1634    /// exceeds the threshold must produce the slow-control-reply-write WARN with
1635    /// queued_ms reflecting the residency. Uses a backdated stamp rather than a
1636    /// real stall so the test is fast and deterministic.
1637    #[tokio::test]
1638    async fn stale_queued_control_reply_logs_slow_reply_write() {
1639        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::WARN);
1640        let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(4);
1641        let reply = Frame::build_with_version(
1642            PROTOCOL_VERSION,
1643            FrameType::Error,
1644            Flags::new(false, Priority::Interactive, false),
1645            0,
1646            0,
1647            7,
1648            serde_json::to_vec(&ErrorBody {
1649                code: "test".into(),
1650                message: "reply".into(),
1651                detail: None,
1652            })
1653            .expect("body encodes"),
1654        )
1655        .expect("frame builds");
1656        tx.send(crate::router::OutboundFrame {
1657            frame: reply,
1658            enqueued_at: std::time::Instant::now() - Duration::from_millis(1500),
1659            flushed: None,
1660            charge: None,
1661        })
1662        .await
1663        .expect("queued");
1664        drop(tx);
1665        let (write_half, mut read_half) = duplex(64 * 1024);
1666        drain_writer(write_half, rx).await.expect("writer drains");
1667        let mut sink = Vec::new();
1668        read_half.read_to_end(&mut sink).await.expect("read");
1669        assert!(!sink.is_empty(), "frame reached the socket");
1670        let captured = crate::router::test_log::captured_logs(&logs);
1671        assert!(
1672            captured.contains("slow control reply write") && captured.contains("corr=7"),
1673            "expected slow reply WARN naming corr, got: {captured}"
1674        );
1675        let queued_ms: u64 = captured
1676            .split("queued_ms=")
1677            .nth(1)
1678            .and_then(|s| s.split_whitespace().next())
1679            .and_then(|s| s.parse().ok())
1680            .expect("queued_ms present");
1681        assert!(
1682            queued_ms >= 1500,
1683            "queued_ms reflects residency: {queued_ms}"
1684        );
1685    }
1686
1687    /// Fast polarity: a promptly-drained control reply and a stale DATA-PLANE
1688    /// frame must both stay silent — the WARN is channel-0-only by design, and
1689    /// a healthy queue must add zero log volume.
1690    #[tokio::test]
1691    async fn fresh_control_and_stale_data_frames_log_nothing() {
1692        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::WARN);
1693        let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(4);
1694        let control = Frame::build_with_version(
1695            PROTOCOL_VERSION,
1696            FrameType::Error,
1697            Flags::new(false, Priority::Interactive, false),
1698            0,
1699            0,
1700            8,
1701            serde_json::to_vec(&ErrorBody {
1702                code: "test".into(),
1703                message: "fresh".into(),
1704                detail: None,
1705            })
1706            .expect("body encodes"),
1707        )
1708        .expect("frame builds");
1709        tx.send(crate::router::OutboundFrame {
1710            frame: control,
1711            enqueued_at: std::time::Instant::now(),
1712            flushed: None,
1713            charge: None,
1714        })
1715        .await
1716        .expect("queued");
1717        let data = Frame::build_with_version(
1718            PROTOCOL_VERSION,
1719            FrameType::Error,
1720            Flags::new(false, Priority::Interactive, false),
1721            9,
1722            1,
1723            9,
1724            serde_json::to_vec(&ErrorBody {
1725                code: "test".into(),
1726                message: "data".into(),
1727                detail: None,
1728            })
1729            .expect("body encodes"),
1730        )
1731        .expect("frame builds");
1732        tx.send(crate::router::OutboundFrame {
1733            frame: data,
1734            enqueued_at: std::time::Instant::now() - Duration::from_millis(5000),
1735            flushed: None,
1736            charge: None,
1737        })
1738        .await
1739        .expect("queued");
1740        drop(tx);
1741        let (write_half, _read_half) = duplex(64 * 1024);
1742        drain_writer(write_half, rx).await.expect("writer drains");
1743        let captured = crate::router::test_log::captured_logs(&logs);
1744        assert!(
1745            !captured.contains("slow control reply write"),
1746            "no WARN for fresh control or stale data frames, got: {captured}"
1747        );
1748    }
1749
1750    struct CountingReader {
1751        bytes: Vec<u8>,
1752        offset: usize,
1753        first_read_end: Option<usize>,
1754        reads: Arc<AtomicUsize>,
1755    }
1756
1757    impl CountingReader {
1758        fn new(bytes: Vec<u8>, first_read_end: Option<usize>) -> (Self, Arc<AtomicUsize>) {
1759            let reads = Arc::new(AtomicUsize::new(0));
1760            (
1761                Self {
1762                    bytes,
1763                    offset: 0,
1764                    first_read_end,
1765                    reads: Arc::clone(&reads),
1766                },
1767                reads,
1768            )
1769        }
1770    }
1771
1772    impl AsyncRead for CountingReader {
1773        fn poll_read(
1774            mut self: Pin<&mut Self>,
1775            _cx: &mut Context<'_>,
1776            buf: &mut ReadBuf<'_>,
1777        ) -> Poll<io::Result<()>> {
1778            self.reads.fetch_add(1, Ordering::Relaxed);
1779            let available = self.bytes.len().saturating_sub(self.offset);
1780            let first_read_remaining = self
1781                .first_read_end
1782                .filter(|end| self.offset < *end)
1783                .map_or(available, |end| end - self.offset);
1784            let count = available.min(first_read_remaining).min(buf.remaining());
1785            let end = self.offset + count;
1786            buf.put_slice(&self.bytes[self.offset..end]);
1787            self.offset = end;
1788            Poll::Ready(Ok(()))
1789        }
1790    }
1791
1792    fn encode_frames(frames: &[Frame]) -> Vec<u8> {
1793        let mut bytes = Vec::new();
1794        for frame in frames {
1795            bytes.extend_from_slice(&frame.header.encode());
1796            bytes.extend_from_slice(&frame.body);
1797        }
1798        bytes
1799    }
1800
1801    async fn read_frames<R>(reader: &mut R, count: usize) -> Vec<Frame>
1802    where
1803        R: AsyncRead + Unpin,
1804    {
1805        let mut frames = Vec::with_capacity(count);
1806        for _ in 0..count {
1807            frames.push(read_frame(reader).await.unwrap().unwrap());
1808        }
1809        frames
1810    }
1811
1812    fn request(channel: u16, corr: u64, body: &[u8]) -> Frame {
1813        Frame::build(
1814            FrameType::Request,
1815            Flags::new(true, Priority::Interactive, false),
1816            channel,
1817            0,
1818            corr,
1819            body.to_vec(),
1820        )
1821        .unwrap()
1822    }
1823
1824    fn echo_router() -> Arc<Router> {
1825        let mut router = Router::with_default_self_handler();
1826        router.register_backend(7, EchoBackend).unwrap();
1827        router.register_backend(9, EchoBackend).unwrap();
1828        Arc::new(router)
1829    }
1830
1831    fn test_auth() -> (ServerAuth, ConnectionInfo) {
1832        test_auth_with_limit(4)
1833    }
1834
1835    fn test_auth_with_limit(max_unauthenticated: usize) -> (ServerAuth, ConnectionInfo) {
1836        test_auth_with_deadline_and_limit(TEST_DEADLINE, max_unauthenticated)
1837    }
1838
1839    fn test_auth_with_deadline_and_limit(
1840        deadline: Duration,
1841        max_unauthenticated: usize,
1842    ) -> (ServerAuth, ConnectionInfo) {
1843        let key = vec![0x42; 32];
1844        let daemon_id = [0x24; 16];
1845        let conn = ConnectionInfo {
1846            schema: SCHEMA_VERSION,
1847            wire_version: None,
1848            endpoints: vec![Endpoint {
1849                host: "127.0.0.1".to_owned(),
1850                port: 1,
1851            }],
1852            key: key.clone(),
1853            daemon_id,
1854            pid: std::process::id(),
1855            daemon_ver: TEST_DAEMON_VER.to_owned(),
1856        };
1857        (
1858            ServerAuth::with_limits(
1859                key,
1860                daemon_id,
1861                TEST_DAEMON_VER,
1862                deadline,
1863                max_unauthenticated,
1864            ),
1865            conn,
1866        )
1867    }
1868
1869    async fn authenticate<S>(stream: &mut S, conn: &ConnectionInfo)
1870    where
1871        S: AsyncRead + AsyncWrite + Unpin,
1872    {
1873        authenticate_client(stream, conn, TEST_DEADLINE)
1874            .await
1875            .expect("test client should authenticate")
1876    }
1877
1878    async fn write_auth_message<S, T>(stream: &mut S, value: &T)
1879    where
1880        S: AsyncWrite + Unpin,
1881        T: Serialize,
1882    {
1883        let body = serde_json::to_vec(value).expect("auth message encodes");
1884        stream
1885            .write_all(&(body.len() as u32).to_le_bytes())
1886            .await
1887            .expect("auth message length writes");
1888        stream
1889            .write_all(&body)
1890            .await
1891            .expect("auth message body writes");
1892    }
1893
1894    async fn read_auth_message<S, T>(stream: &mut S) -> T
1895    where
1896        S: AsyncRead + Unpin,
1897        T: DeserializeOwned,
1898    {
1899        let mut length = [0; 4];
1900        stream
1901            .read_exact(&mut length)
1902            .await
1903            .expect("auth message length reads");
1904        let mut body = vec![0; u32::from_le_bytes(length) as usize];
1905        stream
1906            .read_exact(&mut body)
1907            .await
1908            .expect("auth message body reads");
1909        serde_json::from_slice(&body).expect("auth message decodes")
1910    }
1911
1912    async fn send_wrong_key_client_auth<S>(stream: &mut S, conn: &ConnectionInfo)
1913    where
1914        S: AsyncRead + AsyncWrite + Unpin,
1915    {
1916        let hello = ClientHello {
1917            client_nonce: [0x57; NONCE_LEN],
1918            role: "client".to_owned(),
1919        };
1920        write_auth_message(stream, &hello).await;
1921        let proof: ServerProof = read_auth_message(stream).await;
1922        let mut wrong_key = conn.key.clone();
1923        wrong_key[0] ^= 0xff;
1924        let client_auth = ClientAuth {
1925            client_auth: compute_proof(
1926                &wrong_key,
1927                CLIENT_AUTH_DOMAIN,
1928                &hello.client_nonce,
1929                &proof.server_nonce,
1930                &conn.daemon_id,
1931            ),
1932        };
1933        write_auth_message(stream, &client_auth).await;
1934    }
1935
1936    fn assert_pre_auth_log(logs: &Arc<std::sync::Mutex<Vec<u8>>>, stage: &str, port: u16) {
1937        let captured = crate::router::test_log::captured_logs(logs);
1938        assert!(
1939            captured.contains(&format!("stage=\"{stage}\"")),
1940            "expected rejection stage {stage}, got: {captured}"
1941        );
1942        assert!(
1943            captured.contains(&format!("peer_addr=127.0.0.1:{port}")),
1944            "expected peer address, got: {captured}"
1945        );
1946        assert!(
1947            captured.contains("elapsed_ms=") && captured.contains("suppressed_since_last="),
1948            "expected elapsed time and suppression count, got: {captured}"
1949        );
1950        assert!(
1951            !captured.contains("WARN"),
1952            "pre-auth rejection must not be logged as a warning: {captured}"
1953        );
1954    }
1955
1956    #[tokio::test]
1957    async fn logs_handshake_deadline_pre_auth_rejection() {
1958        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1959        let deadline = Duration::from_millis(60);
1960        let (auth, _) = test_auth_with_deadline_and_limit(deadline, 4);
1961        let (client, server_stream) = duplex(512);
1962        let port = 41001;
1963        let server = handle_accepted_connection(
1964            server_stream,
1965            echo_router(),
1966            auth,
1967            SocketAddr::from(([127, 0, 0, 1], port)),
1968            Instant::now(),
1969        );
1970
1971        let error = tokio::time::timeout(deadline * 3, server)
1972            .await
1973            .expect("idle handshake should end at its deadline")
1974            .expect_err("idle handshake must be rejected");
1975        drop(client);
1976        assert!(matches!(
1977            error,
1978            ConnectionError::Auth(AuthError::Timeout {
1979                stage: AuthStage::ClientHello,
1980                ..
1981            })
1982        ));
1983        let captured = crate::router::test_log::captured_logs(&logs);
1984        assert!(
1985            captured.contains("reason=\"handshake_deadline_expired\""),
1986            "{captured}"
1987        );
1988        assert_pre_auth_log(&logs, "handshake_deadline", port);
1989    }
1990
1991    #[tokio::test]
1992    async fn logs_invalid_client_proof_pre_auth_rejection() {
1993        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1994        let (auth, conn) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
1995        let (mut client, server_stream) = duplex(512);
1996        let port = 41002;
1997        let server = handle_accepted_connection(
1998            server_stream,
1999            echo_router(),
2000            auth,
2001            SocketAddr::from(([127, 0, 0, 1], port)),
2002            Instant::now(),
2003        );
2004
2005        let (error, ()) = tokio::join!(server, send_wrong_key_client_auth(&mut client, &conn));
2006        assert!(matches!(
2007            error,
2008            Err(ConnectionError::Auth(AuthError::InvalidClientAuth))
2009        ));
2010        let captured = crate::router::test_log::captured_logs(&logs);
2011        assert!(
2012            captured.contains("reason=\"client_proof_mismatch\""),
2013            "{captured}"
2014        );
2015        assert_pre_auth_log(&logs, "client_authentication", port);
2016    }
2017
2018    #[tokio::test]
2019    async fn logs_malformed_pre_auth_message() {
2020        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
2021        let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
2022        let (mut client, server_stream) = duplex(512);
2023        let port = 41003;
2024        let server = handle_accepted_connection(
2025            server_stream,
2026            echo_router(),
2027            auth,
2028            SocketAddr::from(([127, 0, 0, 1], port)),
2029            Instant::now(),
2030        );
2031        let send_malformed_message = async {
2032            let body = b"{";
2033            client
2034                .write_all(&(body.len() as u32).to_le_bytes())
2035                .await
2036                .expect("message length writes");
2037            client.write_all(body).await.expect("message body writes");
2038        };
2039
2040        let (error, ()) = tokio::join!(server, send_malformed_message);
2041        assert!(matches!(
2042            error,
2043            Err(ConnectionError::Auth(AuthError::JsonDecode {
2044                stage: AuthStage::ClientHello,
2045                ..
2046            }))
2047        ));
2048        let captured = crate::router::test_log::captured_logs(&logs);
2049        assert!(
2050            captured.contains("reason=\"malformed_or_oversized_message\""),
2051            "{captured}"
2052        );
2053        assert_pre_auth_log(&logs, "malformed_message", port);
2054    }
2055
2056    #[tokio::test]
2057    async fn logs_peer_close_during_handshake() {
2058        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
2059        let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
2060        let (client, server_stream) = duplex(512);
2061        let port = 41004;
2062        drop(client);
2063
2064        let error = handle_accepted_connection(
2065            server_stream,
2066            echo_router(),
2067            auth,
2068            SocketAddr::from(([127, 0, 0, 1], port)),
2069            Instant::now(),
2070        )
2071        .await
2072        .expect_err("closed peer must be rejected");
2073        assert!(matches!(
2074            error,
2075            ConnectionError::Auth(AuthError::UnexpectedEof {
2076                stage: AuthStage::ClientHello,
2077                actual: 0,
2078                ..
2079            })
2080        ));
2081        let captured = crate::router::test_log::captured_logs(&logs);
2082        assert!(
2083            captured.contains("reason=\"peer_closed_before_authentication_completed\""),
2084            "{captured}"
2085        );
2086        assert_pre_auth_log(&logs, "peer_closed", port);
2087    }
2088
2089    // Rejection-log rate limits belong to one listener. A process-wide limiter
2090    // let one listener's rejects silence another's for a second, which hid the
2091    // second listener's first rejection entirely.
2092    #[tokio::test]
2093    async fn each_listener_rate_limits_its_own_rejection_logs() {
2094        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
2095        for port in [41011, 41012] {
2096            let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
2097            let (client, server_stream) = duplex(512);
2098            drop(client);
2099            handle_accepted_connection(
2100                server_stream,
2101                echo_router(),
2102                auth,
2103                SocketAddr::from(([127, 0, 0, 1], port)),
2104                Instant::now(),
2105            )
2106            .await
2107            .expect_err("closed peer must be rejected");
2108        }
2109        let captured = crate::router::test_log::captured_logs(&logs);
2110        for port in [41011, 41012] {
2111            assert!(
2112                captured.contains(&format!("127.0.0.1:{port}")),
2113                "listener on port {port} logged nothing: {captured}"
2114            );
2115        }
2116    }
2117
2118    #[tokio::test]
2119    async fn logs_unauthenticated_capacity_rejection() {
2120        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
2121        let deadline = Duration::from_millis(60);
2122        let (auth, _) = test_auth_with_deadline_and_limit(deadline, 1);
2123        let held_slot = auth
2124            .unauthenticated
2125            .clone()
2126            .try_acquire_owned()
2127            .expect("the only pre-auth slot is available");
2128        let (client, server_stream) = duplex(512);
2129        let port = 41005;
2130        let server = handle_accepted_connection(
2131            server_stream,
2132            echo_router(),
2133            auth,
2134            SocketAddr::from(([127, 0, 0, 1], port)),
2135            Instant::now(),
2136        );
2137
2138        let error = tokio::time::timeout(deadline * 3, server)
2139            .await
2140            .expect("queued connection should end at the capacity deadline")
2141            .expect_err("connection without a free slot must be rejected");
2142        drop(held_slot);
2143        drop(client);
2144        assert!(matches!(error, ConnectionError::UnauthenticatedCapacity));
2145        let captured = crate::router::test_log::captured_logs(&logs);
2146        assert!(
2147            captured.contains("reason=\"capacity_wait_timed_out\""),
2148            "{captured}"
2149        );
2150        assert_pre_auth_log(&logs, "waiting_for_handshake_slot", port);
2151    }
2152
2153    #[test]
2154    fn pre_auth_rejection_limiter_suppresses_bursts_and_reports_count() {
2155        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
2156        let limiter = PreAuthRejectLimiter::new();
2157        let capacity = ConnectionError::UnauthenticatedCapacity;
2158        let handshake_timeout = ConnectionError::Auth(AuthError::Timeout {
2159            stage: AuthStage::ClientHello,
2160            deadline: Duration::from_millis(200),
2161        });
2162        let peer_addr = SocketAddr::from(([127, 0, 0, 1], 41006));
2163
2164        log_pre_auth_rejection(
2165            &capacity,
2166            peer_addr,
2167            Duration::from_millis(1),
2168            Duration::ZERO,
2169            &limiter,
2170        );
2171        for _ in 0..4 {
2172            log_pre_auth_rejection(
2173                &capacity,
2174                peer_addr,
2175                Duration::from_millis(2),
2176                Duration::from_millis(100),
2177                &limiter,
2178            );
2179        }
2180        log_pre_auth_rejection(
2181            &handshake_timeout,
2182            peer_addr,
2183            Duration::from_millis(3),
2184            Duration::from_millis(100),
2185            &limiter,
2186        );
2187        log_pre_auth_rejection(
2188            &capacity,
2189            peer_addr,
2190            Duration::from_millis(4),
2191            Duration::from_secs(1),
2192            &limiter,
2193        );
2194
2195        let captured = crate::router::test_log::captured_logs(&logs);
2196        assert_eq!(
2197            captured
2198                .matches("subc TCP connection rejected before routing")
2199                .count(),
2200            3,
2201            "one line per stage in a burst, then a later capacity line: {captured}"
2202        );
2203        assert!(
2204            captured.contains("suppressed_since_last=4"),
2205            "later capacity line should report the four hidden rejects: {captured}"
2206        );
2207        assert!(
2208            captured.contains("stage=\"handshake_deadline\""),
2209            "{captured}"
2210        );
2211    }
2212
2213    #[tokio::test]
2214    async fn buffered_frame_reader_coalesces_reads_and_preserves_short_reads() {
2215        let frames = vec![
2216            request(7, 1, b"first"),
2217            request(9, 2, b"second"),
2218            request(7, 3, b"third"),
2219            request(9, 4, b"fourth"),
2220        ];
2221        let bytes = encode_frames(&frames);
2222
2223        let (mut direct, direct_reads) = CountingReader::new(bytes.clone(), None);
2224        assert_eq!(read_frames(&mut direct, frames.len()).await, frames);
2225        assert_eq!(direct_reads.load(Ordering::Relaxed), frames.len() * 3);
2226
2227        let (buffered_source, buffered_reads) = CountingReader::new(bytes, None);
2228        let mut buffered = BufReader::new(buffered_source);
2229        assert_eq!(read_frames(&mut buffered, frames.len()).await, frames);
2230        assert_eq!(buffered_reads.load(Ordering::Relaxed), 1);
2231
2232        let split_frame = request(7, 5, b"split-body");
2233        let split_bytes = encode_frames(std::slice::from_ref(&split_frame));
2234        let (split_source, split_reads) = CountingReader::new(split_bytes, Some(10));
2235        let mut split_reader = BufReader::new(split_source);
2236        assert_eq!(
2237            read_frame(&mut split_reader).await.unwrap(),
2238            Some(split_frame)
2239        );
2240        assert_eq!(split_reads.load(Ordering::Relaxed), 2);
2241    }
2242
2243    #[tokio::test]
2244    async fn interleaved_channels_on_one_stream_demux_byte_identically_after_auth() {
2245        let (mut client, server_stream) = duplex(4096);
2246        let (auth, conn) = test_auth();
2247        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2248        authenticate(&mut client, &conn).await;
2249        let frames = [
2250            request(7, 1, b"chan7-first\0opaque"),
2251            request(9, 2, b"chan9-middle-{json?}"),
2252            request(7, 3, b"chan7-second\xffbytes"),
2253        ];
2254
2255        for frame in &frames {
2256            crate::write_frame(&mut client, frame).await.unwrap();
2257        }
2258
2259        for expected in &frames {
2260            let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2261            assert_eq!(response.header.ty, FrameType::Response);
2262            assert_eq!(response.header.channel, expected.header.channel);
2263            assert_eq!(response.header.corr, expected.header.corr);
2264            assert_eq!(response.body, expected.body);
2265        }
2266
2267        drop(client);
2268        server.await.unwrap().unwrap();
2269    }
2270
2271    #[tokio::test]
2272    async fn channel_zero_goes_to_subc_self_handler_after_auth() {
2273        let (mut client, server_stream) = duplex(512);
2274        let (auth, conn) = test_auth();
2275        let server = tokio::spawn(handle_connection(
2276            server_stream,
2277            Arc::new(Router::with_default_self_handler()),
2278            auth,
2279        ));
2280        authenticate(&mut client, &conn).await;
2281        let ping = Frame::build(
2282            FrameType::Ping,
2283            Flags::new(false, Priority::Passive, false),
2284            0,
2285            0,
2286            55,
2287            Vec::new(),
2288        )
2289        .unwrap();
2290
2291        crate::write_frame(&mut client, &ping).await.unwrap();
2292        let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2293
2294        assert_eq!(response.header.ty, FrameType::Pong);
2295        assert_eq!(response.header.channel, 0);
2296        assert_eq!(response.header.corr, 55);
2297        assert!(response.body.is_empty());
2298
2299        drop(client);
2300        server.await.unwrap().unwrap();
2301    }
2302
2303    #[tokio::test]
2304    async fn unauthenticated_connection_is_rejected_before_routing() {
2305        let (mut client, server_stream) = duplex(512);
2306        let (auth, _conn) = test_auth();
2307        let registry = Arc::new(Registry::default());
2308        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2309            Arc::clone(&registry),
2310        ))));
2311        let server = tokio::spawn(handle_connection(server_stream, router, auth));
2312        let ping = Frame::build(
2313            FrameType::Ping,
2314            Flags::new(false, Priority::Passive, false),
2315            0,
2316            0,
2317            66,
2318            Vec::new(),
2319        )
2320        .unwrap();
2321
2322        crate::write_frame(&mut client, &ping).await.unwrap();
2323        if let Ok(Ok(Some(frame))) =
2324            tokio::time::timeout(Duration::from_millis(200), crate::read_frame(&mut client)).await
2325        {
2326            panic!("unauthenticated frame reached router: {frame:?}");
2327        }
2328
2329        let err = server.await.unwrap().unwrap_err();
2330        assert!(matches!(err, ConnectionError::Auth(_)));
2331        assert_eq!(registry.active_registration_count().unwrap(), 0);
2332    }
2333
2334    #[tokio::test]
2335    async fn over_cap_peer_queues_for_a_slot_and_authenticates_when_one_frees() {
2336        // Restart-herd contract: an over-cap pre-auth connection WAITS (bounded by
2337        // the auth deadline) instead of being reset. When the slot-holder finishes,
2338        // the queued peer must complete a normal handshake — the 2026-07-14 aft
2339        // outage was exactly a supervised child being reset out of this lottery.
2340        let (mut first_client, first_server_stream) = duplex(2048);
2341        let (mut second_client, second_server_stream) = duplex(2048);
2342        let (auth, conn) = test_auth_with_limit(1);
2343        let registry = Arc::new(Registry::default());
2344        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2345            Arc::clone(&registry),
2346        ))));
2347
2348        let first_server = tokio::spawn(handle_connection(
2349            first_server_stream,
2350            Arc::clone(&router),
2351            auth.clone(),
2352        ));
2353
2354        let second_server = tokio::spawn(handle_connection(
2355            second_server_stream,
2356            Arc::clone(&router),
2357            auth.clone(),
2358        ));
2359
2360        // The second peer must still be pending (not reset) while the slot is held.
2361        tokio::time::sleep(Duration::from_millis(50)).await;
2362        assert!(
2363            !second_server.is_finished(),
2364            "queued peer must not be reset"
2365        );
2366
2367        // First peer completes its handshake, freeing the slot; the queued second
2368        // peer then authenticates normally.
2369        authenticate(&mut first_client, &conn).await;
2370        authenticate(&mut second_client, &conn).await;
2371
2372        drop(first_client);
2373        drop(second_client);
2374        let _ = first_server.await;
2375        let _ = second_server.await;
2376        assert_eq!(registry.active_registration_count().unwrap(), 0);
2377    }
2378
2379    #[tokio::test]
2380    async fn over_cap_peer_is_rejected_when_no_slot_frees_within_deadline() {
2381        // The deadline stays the DoS bound: if no slot frees, the queued peer is
2382        // rejected at the deadline with a closed stream. The slot is held DIRECTLY
2383        // (not by another connection) so nothing can free it mid-test — a squatting
2384        // connection's own auth deadline would release the slot at exactly the
2385        // waiter's timeout, making the outcome racy.
2386        let (mut second_client, second_server_stream) = duplex(512);
2387        let (auth, conn) = test_auth_with_limit(1);
2388        let registry = Arc::new(Registry::default());
2389        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2390            Arc::clone(&registry),
2391        ))));
2392
2393        let held_slot = auth
2394            .unauthenticated
2395            .clone()
2396            .try_acquire_owned()
2397            .expect("sole pre-auth slot");
2398
2399        let second_server = tokio::spawn(handle_connection(
2400            second_server_stream,
2401            Arc::clone(&router),
2402            auth.clone(),
2403        ));
2404        let second_err = tokio::time::timeout(TEST_DEADLINE * 2, second_server)
2405            .await
2406            .expect("capacity reject should settle at the deadline")
2407            .expect("second connection task should not panic")
2408            .expect_err("queued peer must be rejected when no slot frees");
2409        drop(held_slot);
2410        assert!(matches!(
2411            second_err,
2412            ConnectionError::UnauthenticatedCapacity
2413        ));
2414        let mut closed = [0u8; 1];
2415        assert_eq!(
2416            second_client.read(&mut closed).await.unwrap(),
2417            0,
2418            "capacity-rejected peer should observe a closed stream"
2419        );
2420        assert_eq!(registry.active_registration_count().unwrap(), 0);
2421
2422        let (mut authed_client, authed_server_stream) = duplex(2048);
2423        let authed_server = tokio::spawn(handle_connection(
2424            authed_server_stream,
2425            Arc::clone(&router),
2426            auth,
2427        ));
2428        authenticate(&mut authed_client, &conn).await;
2429        let ping = Frame::build(
2430            FrameType::Ping,
2431            Flags::new(false, Priority::Passive, false),
2432            0,
2433            0,
2434            77,
2435            Vec::new(),
2436        )
2437        .unwrap();
2438        crate::write_frame(&mut authed_client, &ping).await.unwrap();
2439        let pong = crate::read_frame(&mut authed_client)
2440            .await
2441            .unwrap()
2442            .unwrap();
2443        assert_eq!(pong.header.ty, FrameType::Pong);
2444        assert_eq!(pong.header.channel, 0);
2445        assert_eq!(pong.header.corr, 77);
2446        assert_eq!(registry.active_registration_count().unwrap(), 0);
2447
2448        drop(authed_client);
2449        authed_server.await.unwrap().unwrap();
2450    }
2451
2452    #[tokio::test]
2453    async fn bind_ack_during_partial_frame_preserves_next_request() {
2454        use subc_control::ClientControlRequest;
2455        use subc_protocol::{
2456            manifest::{
2457                Concurrency, ExecutionMode, IdentityScope, ModuleManifest, ProviderRole, Tool,
2458            },
2459            session::{ModuleControlRequest, ModuleControlResponse},
2460            BindIdentity, ModuleHelloBody, RouteTarget,
2461        };
2462
2463        let mut configured_router = Router::with_default_self_handler();
2464        configured_router.register_backend(7, EchoBackend).unwrap();
2465        let router = Arc::new(configured_router);
2466        let (auth, conn) = test_auth();
2467        let (mut module, module_stream) = duplex(4096);
2468        let module_server = tokio::spawn(handle_connection(
2469            module_stream,
2470            Arc::clone(&router),
2471            auth.clone(),
2472        ));
2473        authenticate(&mut module, &conn).await;
2474        let manifest = ModuleManifest::builder("frame-test", "0.1.0")
2475            .protocol_ver(PROTOCOL_VERSION)
2476            .provides(vec![ProviderRole::ToolProvider {
2477                tools: vec![Tool {
2478                    name: "read".into(),
2479                    description: None,
2480                    execution_mode: ExecutionMode::Pure,
2481                    schema: serde_json::json!({"type": "object"}),
2482                }],
2483                identity_scope: vec![IdentityScope::Project, IdentityScope::Session],
2484                concurrency: Concurrency::ModuleManaged,
2485                emits_push: true,
2486                sub_supervises: true,
2487            }])
2488            .build();
2489        let hello = Frame::build(
2490            FrameType::Hello,
2491            Flags::new(false, Priority::Passive, false),
2492            0,
2493            0,
2494            1,
2495            serde_json::to_vec(&ModuleHelloBody {
2496                manifest,
2497                protocol_ver: PROTOCOL_VERSION,
2498                control_ops: None,
2499                launch_nonce: None,
2500            })
2501            .unwrap(),
2502        )
2503        .unwrap();
2504        crate::write_frame(&mut module, &hello).await.unwrap();
2505        assert_eq!(
2506            read_frame(&mut module).await.unwrap().unwrap().header.ty,
2507            FrameType::HelloAck
2508        );
2509
2510        let (mut client, client_stream) = duplex(4096);
2511        let client_server = tokio::spawn(handle_connection(client_stream, router, auth));
2512        authenticate(&mut client, &conn).await;
2513        let open = Frame::build(
2514            FrameType::Request,
2515            Flags::new(false, Priority::Passive, false),
2516            0,
2517            0,
2518            2,
2519            serde_json::to_vec(&ClientControlRequest::RouteOpen {
2520                target: RouteTarget::ToolProvider {
2521                    module_id: "frame-test".into(),
2522                },
2523                identity: BindIdentity::new(std::env::current_dir().unwrap(), "unit", "session"),
2524                consumer_identity: None,
2525                consumer_capabilities: None,
2526                role_versions: None,
2527                admission_facts: None,
2528                scope: None,
2529            })
2530            .unwrap(),
2531        )
2532        .unwrap();
2533        crate::write_frame(&mut client, &open).await.unwrap();
2534        let bind = timeout(TEST_DEADLINE, read_frame(&mut module))
2535            .await
2536            .unwrap()
2537            .unwrap()
2538            .unwrap();
2539        assert!(matches!(
2540            serde_json::from_slice::<ModuleControlRequest>(&bind.body).unwrap(),
2541            ModuleControlRequest::RouteBind { .. }
2542        ));
2543
2544        let ping = request(7, 3, b"partial-frame-body");
2545        client.write_all(&ping.header.encode()).await.unwrap();
2546        // Give the connection reader time to consume the header while the bind is pending.
2547        tokio::time::sleep(Duration::from_millis(30)).await;
2548        let ack = Frame::build(
2549            FrameType::Response,
2550            Flags::new(false, Priority::Passive, false),
2551            0,
2552            0,
2553            bind.header.corr,
2554            serde_json::to_vec(&ModuleControlResponse::RouteBindAck {}).unwrap(),
2555        )
2556        .unwrap();
2557        crate::write_frame(&mut module, &ack).await.unwrap();
2558        let opened = timeout(TEST_DEADLINE, read_frame(&mut client))
2559            .await
2560            .unwrap()
2561            .unwrap();
2562        if opened.is_none() {
2563            panic!("client closed: {:?}", client_server.await);
2564        }
2565        let opened = opened.unwrap();
2566        assert_eq!(opened.header.corr, 2);
2567        client.write_all(&ping.body).await.unwrap();
2568        let pong = timeout(TEST_DEADLINE, read_frame(&mut client))
2569            .await
2570            .expect("partial frame must reach the router after the bind ack")
2571            .expect("frame must decode")
2572            .expect("connection must remain open");
2573        assert_eq!(pong.header.ty, FrameType::Response);
2574        assert_eq!(pong.header.corr, 3);
2575        assert_eq!(pong.body, ping.body);
2576        drop(client);
2577        drop(module);
2578        client_server.await.unwrap().unwrap();
2579        let _ = module_server.await.unwrap();
2580    }
2581
2582    #[tokio::test]
2583    async fn full_module_egress_health_probe_does_not_block_same_client_other_route() {
2584        use crate::ConnectionId;
2585        use subc_control::{ClientControlRequest, ClientControlResponse};
2586        use subc_protocol::{
2587            manifest::{
2588                Concurrency, ExecutionMode, IdentityScope, ModuleManifest, ProviderRole, Tool,
2589            },
2590            session::ModuleControlResponse,
2591            BindIdentity, ModuleHelloBody, RouteTarget,
2592        };
2593
2594        let probe_timeout = Duration::from_millis(100);
2595        let handler = Arc::new(
2596            ControlHandler::new(Arc::new(Registry::default()))
2597                .with_health_probe_timeout(probe_timeout),
2598        );
2599        let router = Arc::new(Router::with_control_handler(Arc::clone(&handler)));
2600        let hello = |name: &str| {
2601            Frame::build(
2602                FrameType::Hello,
2603                Flags::new(false, Priority::Passive, false),
2604                0,
2605                0,
2606                1,
2607                serde_json::to_vec(&ModuleHelloBody {
2608                    manifest: ModuleManifest::builder(name, "0.1.0")
2609                        .protocol_ver(PROTOCOL_VERSION)
2610                        .provides(vec![ProviderRole::ToolProvider {
2611                            tools: vec![Tool {
2612                                name: "read".into(),
2613                                description: None,
2614                                execution_mode: ExecutionMode::Pure,
2615                                schema: serde_json::json!({"type": "object"}),
2616                            }],
2617                            identity_scope: vec![IdentityScope::Project, IdentityScope::Session],
2618                            concurrency: Concurrency::ModuleManaged,
2619                            emits_push: false,
2620                            sub_supervises: false,
2621                        }])
2622                        .build(),
2623                    protocol_ver: PROTOCOL_VERSION,
2624                    control_ops: Some(vec!["health.check".to_owned()]),
2625                    launch_nonce: None,
2626                })
2627                .unwrap(),
2628            )
2629            .unwrap()
2630        };
2631        let (blocked_tx, mut blocked_rx) = mpsc::channel(1);
2632        let blocked_ctx = RouteCtx {
2633            connection_id: ConnectionId::new(90001),
2634            egress: FrameSink::new(blocked_tx),
2635        };
2636        handler
2637            .handle_control_frame(&blocked_ctx, hello("blocked"))
2638            .await
2639            .unwrap();
2640        assert_eq!(
2641            blocked_rx.try_recv().unwrap().header.ty,
2642            FrameType::HelloAck
2643        );
2644        let filler = request(0, 99, b"queue filler");
2645        blocked_ctx.egress.try_send(filler.clone()).unwrap();
2646        assert!(
2647            blocked_ctx.egress.try_send(filler).is_err(),
2648            "module queue must actually be full"
2649        );
2650
2651        let (healthy_tx, mut healthy_rx) = mpsc::channel(8);
2652        let healthy_ctx = RouteCtx {
2653            connection_id: ConnectionId::new(90002),
2654            egress: FrameSink::new(healthy_tx),
2655        };
2656        handler
2657            .handle_control_frame(&healthy_ctx, hello("healthy"))
2658            .await
2659            .unwrap();
2660        assert_eq!(
2661            healthy_rx.try_recv().unwrap().header.ty,
2662            FrameType::HelloAck
2663        );
2664        let (auth, conn) = test_auth();
2665        let (mut client, client_stream) = duplex(4096);
2666        let client_server =
2667            tokio::spawn(handle_connection(client_stream, Arc::clone(&router), auth));
2668        authenticate(&mut client, &conn).await;
2669        let control_request = |corr, body: ClientControlRequest| {
2670            Frame::build(
2671                FrameType::Request,
2672                Flags::new(false, Priority::Interactive, false),
2673                0,
2674                0,
2675                corr,
2676                serde_json::to_vec(&body).unwrap(),
2677            )
2678            .unwrap()
2679        };
2680        crate::write_frame(
2681            &mut client,
2682            &control_request(
2683                2,
2684                ClientControlRequest::RouteOpen {
2685                    target: RouteTarget::ToolProvider {
2686                        module_id: "healthy".into(),
2687                    },
2688                    identity: BindIdentity::new(
2689                        std::env::current_dir().unwrap(),
2690                        "unit",
2691                        "session",
2692                    ),
2693                    consumer_identity: None,
2694                    consumer_capabilities: None,
2695                    role_versions: None,
2696                    admission_facts: None,
2697                    scope: None,
2698                },
2699            ),
2700        )
2701        .await
2702        .unwrap();
2703        let bind = timeout(TEST_DEADLINE, healthy_rx.recv())
2704            .await
2705            .unwrap()
2706            .unwrap();
2707        handler
2708            .handle_control_frame(
2709                &healthy_ctx,
2710                Frame::build(
2711                    FrameType::Response,
2712                    Flags::new(false, Priority::Passive, false),
2713                    0,
2714                    0,
2715                    bind.header.corr,
2716                    serde_json::to_vec(&ModuleControlResponse::RouteBindAck {}).unwrap(),
2717                )
2718                .unwrap(),
2719            )
2720            .await
2721            .unwrap();
2722        let opened = timeout(TEST_DEADLINE, read_frame(&mut client))
2723            .await
2724            .unwrap()
2725            .unwrap()
2726            .unwrap();
2727        let (channel, epoch) =
2728            match serde_json::from_slice::<ClientControlResponse>(&opened.body).unwrap() {
2729                ClientControlResponse::RouteOpen {
2730                    route_channel,
2731                    route_epoch,
2732                } => (route_channel, route_epoch),
2733                other => panic!("expected a healthy module route, got {other:?}"),
2734            };
2735
2736        let probe = control_request(
2737            3,
2738            ClientControlRequest::SupervisorHealthProbe {
2739                module_id: "blocked".into(),
2740            },
2741        );
2742        let mut ping = request(channel, 4, b"healthy request");
2743        ping.header.epoch = epoch;
2744        crate::write_frame(&mut client, &probe).await.unwrap();
2745        crate::write_frame(&mut client, &ping).await.unwrap();
2746        timeout(probe_timeout + Duration::from_secs(1), async {
2747            let timed_out = read_frame(&mut client).await.unwrap().unwrap();
2748            assert_eq!(timed_out.header.corr, 3);
2749            assert_eq!(timed_out.header.ty, FrameType::Error);
2750            let error: ErrorBody = serde_json::from_slice(&timed_out.body).unwrap();
2751            assert_eq!(error.code, "module_timeout");
2752            let forwarded = healthy_rx.recv().await.unwrap();
2753            assert_eq!(forwarded.header.corr, ping.header.corr);
2754            assert_eq!(forwarded.body, ping.body);
2755            let reply = Frame::build(
2756                FrameType::Response,
2757                ping.header.flags,
2758                forwarded.header.channel,
2759                forwarded.header.epoch,
2760                forwarded.header.corr,
2761                b"healthy response".to_vec(),
2762            )
2763            .unwrap();
2764            router
2765                .route_for_connection(&healthy_ctx, reply)
2766                .await
2767                .unwrap();
2768            let pong = read_frame(&mut client).await.unwrap().unwrap();
2769            assert_eq!(pong.header.ty, FrameType::Response);
2770            assert_eq!(pong.header.channel, channel);
2771            assert_eq!(pong.header.epoch, epoch);
2772            assert_eq!(pong.header.corr, 4);
2773            assert_eq!(pong.body, b"healthy response");
2774        })
2775        .await
2776        .expect(
2777            "the same client's healthy route must answer within the probe deadline plus margin",
2778        );
2779        assert_eq!(
2780            blocked_rx.len(),
2781            1,
2782            "the blocked module must remain undrained"
2783        );
2784        assert_eq!(blocked_rx.try_recv().unwrap().header.corr, 99);
2785        assert!(
2786            blocked_rx.try_recv().is_err(),
2787            "a timed-out probe must not be enqueued later"
2788        );
2789        drop(client);
2790        client_server.await.unwrap().unwrap();
2791    }
2792
2793    #[tokio::test]
2794    async fn aborted_accept_does_not_end_listener() {
2795        let listener = Arc::new(TcpListener::bind("127.0.0.1:0").await.unwrap());
2796        let addr = listener.local_addr().unwrap();
2797        let (auth, conn) = test_auth();
2798        let mut attempts = 0;
2799        let server = tokio::spawn(serve_listener_with_accept(
2800            Some(addr),
2801            echo_router(),
2802            auth,
2803            move || {
2804                attempts += 1;
2805                let result = if attempts == 1 {
2806                    Some(io::Error::from(io::ErrorKind::ConnectionAborted))
2807                } else {
2808                    None
2809                };
2810                let listener = Arc::clone(&listener);
2811                async move {
2812                    match result {
2813                        Some(err) => Err(err),
2814                        None => listener.accept().await,
2815                    }
2816                }
2817            },
2818        ));
2819        let mut client = tokio::net::TcpStream::connect(addr).await.unwrap();
2820        authenticate(&mut client, &conn).await;
2821        let ping = Frame::build(
2822            FrameType::Ping,
2823            Flags::new(false, Priority::Passive, false),
2824            0,
2825            0,
2826            77,
2827            Vec::new(),
2828        )
2829        .unwrap();
2830        crate::write_frame(&mut client, &ping).await.unwrap();
2831        let pong = timeout(TEST_DEADLINE, read_frame(&mut client))
2832            .await
2833            .unwrap()
2834            .unwrap()
2835            .unwrap();
2836        assert_eq!(pong.header.ty, FrameType::Pong);
2837        assert!(
2838            !server.is_finished(),
2839            "a temporary accept failure must not stop the listener"
2840        );
2841        server.abort();
2842    }
2843
2844    #[tokio::test]
2845    async fn exhausted_accept_backs_off_then_serves_connection() {
2846        let listener = Arc::new(TcpListener::bind("127.0.0.1:0").await.unwrap());
2847        let addr = listener.local_addr().unwrap();
2848        let (auth, conn) = test_auth();
2849        let mut attempts = 0;
2850        let server = tokio::spawn(serve_listener_with_accept(
2851            Some(addr),
2852            echo_router(),
2853            auth,
2854            move || {
2855                attempts += 1;
2856                // The platform's "too many open files" code: EMFILE on Unix,
2857                // WSAEMFILE on Windows. A bare 24 is ERROR_BAD_LENGTH on Windows.
2858                #[cfg(unix)]
2859                let emfile = rustix::io::Errno::MFILE.raw_os_error();
2860                #[cfg(windows)]
2861                let emfile = 10024;
2862                let error = (attempts == 1).then(|| io::Error::from_raw_os_error(emfile));
2863                let listener = Arc::clone(&listener);
2864                async move {
2865                    match error {
2866                        Some(err) => Err(err),
2867                        None => listener.accept().await,
2868                    }
2869                }
2870            },
2871        ));
2872        let started = Instant::now();
2873        let mut client = tokio::net::TcpStream::connect(addr).await.unwrap();
2874        authenticate(&mut client, &conn).await;
2875        assert!(
2876            started.elapsed() >= Duration::from_millis(50),
2877            "fd exhaustion must back off before retrying"
2878        );
2879        assert!(!server.is_finished());
2880        server.abort();
2881    }
2882
2883    #[tokio::test]
2884    async fn fatal_accept_error_still_stops_listener() {
2885        let (auth, _) = test_auth();
2886        let err = serve_listener_with_accept(None, echo_router(), auth, || async {
2887            Err(io::Error::from(io::ErrorKind::PermissionDenied))
2888        })
2889        .await
2890        .unwrap_err();
2891        assert!(
2892            matches!(err, ServerError::Accept { source, .. } if source.kind() == io::ErrorKind::PermissionDenied)
2893        );
2894    }
2895
2896    #[tokio::test]
2897    async fn serve_listeners_with_no_listeners_returns_typed_error() {
2898        let (auth, _conn) = test_auth();
2899        let err = serve_listeners(Vec::new(), echo_router(), auth)
2900            .await
2901            .expect_err("empty listener set must fail loudly");
2902        assert!(matches!(err, ServerError::NoListeners));
2903    }
2904
2905    #[tokio::test]
2906    async fn malformed_header_returns_typed_error_no_panic() {
2907        let (mut client, server_stream) = duplex(128);
2908        let (auth, conn) = test_auth();
2909        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2910        authenticate(&mut client, &conn).await;
2911        let mut header = [0u8; HEADER_LEN];
2912        header[4] = PROTOCOL_VERSION;
2913        header[5] = 250;
2914
2915        client.write_all(&header).await.unwrap();
2916        drop(client);
2917
2918        let err = server.await.unwrap().unwrap_err();
2919        assert!(matches!(
2920            err,
2921            ConnectionError::FrameIo(FrameIoError::DecodeHeader(DecodeError::UnknownFrameType {
2922                byte: 250
2923            }))
2924        ));
2925    }
2926
2927    #[tokio::test]
2928    async fn truncated_body_returns_typed_error_no_panic() {
2929        let (mut client, server_stream) = duplex(128);
2930        let (auth, conn) = test_auth();
2931        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2932        authenticate(&mut client, &conn).await;
2933        let frame = request(7, 8, b"abcd");
2934
2935        client.write_all(&frame.header.encode()).await.unwrap();
2936        client.write_all(b"ab").await.unwrap();
2937        drop(client);
2938
2939        let err = server.await.unwrap().unwrap_err();
2940        assert!(matches!(
2941            err,
2942            ConnectionError::FrameIo(FrameIoError::UnexpectedEof {
2943                stage: ReadStage::Body,
2944                expected: 4,
2945                actual: 2
2946            })
2947        ));
2948    }
2949
2950    #[tokio::test]
2951    async fn unknown_channel_is_returned_as_error_frame_and_connection_continues() {
2952        let (mut client, server_stream) = duplex(1024);
2953        let (auth, conn) = test_auth();
2954        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2955        authenticate(&mut client, &conn).await;
2956        let unknown = request(42, 10, b"lost");
2957        let known = request(7, 11, b"still-routes");
2958
2959        crate::write_frame(&mut client, &unknown).await.unwrap();
2960        crate::write_frame(&mut client, &known).await.unwrap();
2961
2962        let error = crate::read_frame(&mut client).await.unwrap().unwrap();
2963        assert_eq!(error.header.ty, FrameType::Error);
2964        assert_eq!(error.header.channel, 42);
2965        assert_eq!(error.header.corr, 10);
2966        let error_body: ErrorBody = serde_json::from_slice(&error.body).unwrap();
2967        assert_eq!(error_body.code, "unknown_channel");
2968
2969        let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2970        assert_eq!(response.header.ty, FrameType::Response);
2971        assert_eq!(response.header.channel, 7);
2972        assert_eq!(response.header.corr, 11);
2973        assert_eq!(response.body, b"still-routes");
2974
2975        drop(client);
2976        server.await.unwrap().unwrap();
2977    }
2978}