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
408fn accept_resource_exhausted(error: &io::Error) -> bool {
409    // ENFILE/EMFILE/ENOBUFS by name rather than number: the numbers differ by
410    // platform (ENOBUFS is 55 on macOS and 105 on Linux, and each number means
411    // something unrelated on the other), so a literal list misclassifies.
412    // Winsock: WSAEMFILE and WSAENOBUFS.
413    #[cfg(unix)]
414    {
415        use rustix::io::Errno;
416        let exhausted = [Errno::NFILE, Errno::MFILE, Errno::NOBUFS];
417        error
418            .raw_os_error()
419            .is_some_and(|code| exhausted.iter().any(|e| e.raw_os_error() == code))
420    }
421    #[cfg(windows)]
422    {
423        matches!(error.raw_os_error(), Some(10024 | 10055))
424    }
425    #[cfg(not(any(unix, windows)))]
426    {
427        let _ = error;
428        false
429    }
430}
431
432/// Serve all already-bound loopback TCP listeners until one accept loop fails.
433pub async fn serve_listeners(
434    listeners: Vec<TcpListener>,
435    router: Arc<Router>,
436    auth: ServerAuth,
437) -> Result<(), ServerError> {
438    if listeners.is_empty() {
439        return Err(ServerError::NoListeners);
440    }
441
442    let (tx, mut rx) = mpsc::channel(listeners.len());
443    let mut accept_tasks = AbortTasksOnDrop::default();
444    for listener in listeners {
445        let router = Arc::clone(&router);
446        let auth = auth.clone();
447        let tx = tx.clone();
448        accept_tasks.push(tokio::spawn(async move {
449            let result = serve_listener(listener, router, auth).await;
450            let _ = tx.send(result).await;
451        }));
452    }
453    drop(tx);
454
455    rx.recv().await.unwrap_or(Ok(()))
456}
457
458#[derive(Default)]
459struct AbortTasksOnDrop {
460    handles: Vec<JoinHandle<()>>,
461}
462
463impl AbortTasksOnDrop {
464    fn push(&mut self, handle: JoinHandle<()>) {
465        self.handles.push(handle);
466    }
467}
468
469impl Drop for AbortTasksOnDrop {
470    fn drop(&mut self) {
471        for handle in &self.handles {
472            if !handle.is_finished() {
473                handle.abort();
474            }
475        }
476    }
477}
478
479#[derive(Debug)]
480enum ConnectionLoopExit {
481    PeerClosed,
482    CloseRequested(CloseReason),
483}
484
485/// Run the authenticated frame read -> route loop for one connection.
486///
487/// Every accepted TCP connection must complete the key-auth prelude before any
488/// envelope bytes are read by the router. Outbound frames flow through a bounded
489/// [`FrameSink`] drained by one writer task. Inbound dispatch remains serial for
490/// every frame except `route.open`, activity operations and privileged requests;
491/// their bind, file and operator waits run in connection-owned tasks so
492/// unrelated frames can keep flowing.
493pub async fn handle_connection<S>(
494    mut stream: S,
495    router: Arc<Router>,
496    auth: ServerAuth,
497) -> Result<(), ConnectionError>
498where
499    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
500{
501    // Capture only socket facts here. Process-table lookup happens lazily on a
502    // blocking thread when privileged dispatch needs a caller description.
503    let endpoints = (&stream as &dyn Any)
504        .downcast_ref::<tokio::net::TcpStream>()
505        .and_then(|tcp| tcp.local_addr().ok().zip(tcp.peer_addr().ok()));
506    // Over-cap connections WAIT for a handshake slot (bounded by the auth deadline)
507    // instead of being reset. A restart herd — every client and supervised child
508    // re-dialing the fresh daemon at once — otherwise loses supervised modules to
509    // the permit lottery: each reset burns a module restart-budget slot, and a
510    // module that treats auth failure as fatal can exhaust its budget into
511    // state=failed within the boot window (2026-07-14 aft outage). On loopback
512    // with the pre-auth HMAC deadline, a bounded queue is strictly safer than a
513    // reset.
514    //
515    // Pre-auth time is governed by TWO deliberately separate budgets: the queue
516    // wait below is bounded by `auth.deadline`, and `authenticate_server` then
517    // starts a FRESH `auth.deadline` for the handshake itself. Total pre-auth
518    // occupancy per connection is therefore up to 2x the configured deadline.
519    // This is intentional, not an accounting slip: charging queue time against
520    // the handshake budget would hand a herd-queued supervised module a
521    // near-zero handshake window under CPU saturation, recreating the fatal
522    // auth-failure -> restart-budget-burn path this queue exists to prevent.
523    // On a loopback-only, key-authenticated listener the doubled bound is a
524    // per-connection occupancy cost, not a meaningful DoS surface.
525    let permit =
526        match tokio::time::timeout(auth.deadline, auth.unauthenticated.clone().acquire_owned())
527            .await
528        {
529            Ok(Ok(permit)) => permit,
530            Ok(Err(_)) | Err(_) => {
531                let _ = stream.shutdown().await;
532                return Err(ConnectionError::UnauthenticatedCapacity);
533            }
534        };
535
536    let authenticated = authenticate_server(
537        &mut stream,
538        auth.key.as_ref(),
539        &auth.daemon_id,
540        auth.daemon_ver.as_ref(),
541        auth.deadline,
542    )
543    .await
544    .map_err(ConnectionError::Auth)?;
545    drop(permit);
546
547    let mut connection = router.begin_connection();
548    let connection_id = connection.id();
549    router.record_caller_endpoints(connection_id, endpoints);
550    // `authenticated.role` is CLIENT-SUPPLIED and unverified -- the handshake
551    // proves possession of the connection key, nothing about who is calling. So
552    // this exclusion is safe ONLY while the role decides a reporting question and
553    // never an authorization one: the watchdog's own loopback probe would
554    // otherwise inflate the very count it exists to sanity-check.
555    //
556    // The consequence of it being unverified, stated so nobody has to rediscover
557    // it: ANY client holding the key can claim this role and omit itself from
558    // `connected_clients`. That is a gauge a caller can lie to, and it is
559    // acceptable because the gauge informs an operator rather than gating
560    // anything. IF A ROLE IS EVER USED TO DECIDE ADMISSION, CAPACITY, OR PRIVILEGE,
561    // this stops being safe and the role must be attested rather than declared --
562    // the daemon already has the mechanism for that in the spawn-nonce path used
563    // for module identity.
564    let _connected_client = (authenticated.role != WATCHDOG_CLIENT_ROLE)
565        .then(|| auth.connected_clients.open(connection_id));
566    let close_receiver = connection.take_close_receiver();
567    debug!(
568        connection_id = connection_id.get(),
569        "subc authenticated connection opened"
570    );
571
572    let (read_half, write_half) = tokio::io::split(stream);
573    // Authentication is complete before this buffer can read ahead. The connection loop
574    // retains a partial frame read across completed route.open tasks; dropping the read
575    // happens only when a frame finishes or the connection ends.
576    let mut read_half = BufReader::new(read_half);
577    let (egress, rx) = connection_egress();
578    let delivery_guard = ClientDeliveryGuard(egress.clone());
579    let writer = tokio::spawn(drain_writer(write_half, rx));
580
581    let ctx = RouteCtx {
582        connection_id,
583        egress: egress.clone(),
584    };
585
586    let mut route_open_tasks = JoinSet::new();
587    let mut privileged_tasks = JoinSet::new();
588    let loop_result = connection_loop(
589        &mut read_half,
590        Arc::clone(&router),
591        ctx.clone(),
592        close_receiver,
593        &mut route_open_tasks,
594        &mut privileged_tasks,
595    )
596    .await;
597
598    drop(delivery_guard);
599    // Every in-flight route.open must have FINISHED before `connection` drops,
600    // because that drop runs the forwarding cleanup for this id, and cleanup is
601    // also where the id's closing mark is lifted. Dropping a JoinSet only
602    // requests abort: a task already running on another worker keeps going
603    // until its next await, and could commit a route for this connection after
604    // cleanup has cleared it, with nothing left to refuse it and nothing to
605    // clean it up. shutdown() aborts and then waits.
606    route_open_tasks.shutdown().await;
607    // Abort held approvals and wait for their withdrawal guards before lifting
608    // this connection's cleanup state or removing its caller endpoints.
609    privileged_tasks.shutdown().await;
610
611    drop(ctx);
612    drop(egress);
613    drop(connection);
614
615    let close_reason = match &loop_result {
616        Ok(ConnectionLoopExit::CloseRequested(reason)) => Some(reason.to_string()),
617        Ok(ConnectionLoopExit::PeerClosed) | Err(_) => None,
618    };
619    let writer_result = finish_connection_writer(writer, connection_id.get()).await;
620
621    let result = if let Some(reason) = close_reason.as_deref() {
622        match writer_result {
623            Some(Ok(Ok(()))) | None => Ok(()),
624            Some(Ok(Err(writer_err))) => {
625                debug!(
626                    connection_id = connection_id.get(),
627                    close_reason = reason,
628                    writer_error = %writer_err,
629                    "writer failed after requested connection close"
630                );
631                Ok(())
632            }
633            Some(Err(join_err)) => {
634                warn!(
635                    connection_id = connection_id.get(),
636                    close_reason = reason,
637                    join_error = %join_err,
638                    "writer task join failed after requested connection close"
639                );
640                Ok(())
641            }
642        }
643    } else {
644        match (loop_result, writer_result) {
645            (Err(loop_err), Some(Ok(Ok(()))) | None) => Err(loop_err),
646            (Err(loop_err), Some(Ok(Err(writer_err)))) => {
647                warn!(
648                    connection_id = connection_id.get(),
649                    writer_error = %writer_err,
650                    "writer failed while closing after connection error"
651                );
652                Err(loop_err)
653            }
654            (Err(loop_err), Some(Err(join_err))) => {
655                warn!(
656                    connection_id = connection_id.get(),
657                    join_error = %join_err,
658                    "writer task join failed while closing after connection error"
659                );
660                Err(loop_err)
661            }
662            (Ok(ConnectionLoopExit::PeerClosed), Some(Ok(Ok(()))) | None) => Ok(()),
663            (Ok(ConnectionLoopExit::PeerClosed), Some(Ok(Err(writer_err)))) => {
664                Err(ConnectionError::FrameIo(writer_err))
665            }
666            (Ok(ConnectionLoopExit::PeerClosed), Some(Err(join_err))) => Err(join_err),
667            (Ok(ConnectionLoopExit::CloseRequested(_)), _) => {
668                unreachable!("close requests are handled before normal writer result matching")
669            }
670        }
671    };
672
673    match &result {
674        Ok(()) => {
675            if let Some(reason) = close_reason.as_deref() {
676                debug!(
677                    connection_id = connection_id.get(),
678                    close_reason = reason,
679                    "subc connection closed by request"
680                );
681            } else {
682                debug!(
683                    connection_id = connection_id.get(),
684                    "subc connection closed"
685                );
686            }
687        }
688        Err(err) => debug!(
689            connection_id = connection_id.get(),
690            error = %err,
691            "subc connection exited with error"
692        ),
693    }
694
695    result
696}
697
698async fn finish_connection_writer(
699    mut writer: JoinHandle<Result<(), FrameIoError>>,
700    connection_id: u64,
701) -> Option<Result<Result<(), FrameIoError>, ConnectionError>> {
702    // Even after inbound EOF or an error, the peer may keep its receive side
703    // open without reading. Give queued frames the same grace on every exit.
704    match timeout(CLOSE_DRAIN_GRACE, &mut writer).await {
705        Ok(result) => Some(result.map_err(ConnectionError::WriterTask)),
706        Err(_) => {
707            warn!(
708                connection_id,
709                grace = ?CLOSE_DRAIN_GRACE,
710                "connection writer did not drain during teardown; aborting writer task"
711            );
712            writer.abort();
713            let _ = writer.await;
714            None
715        }
716    }
717}
718
719async fn connection_loop<R>(
720    read_half: &mut R,
721    router: Arc<Router>,
722    ctx: RouteCtx,
723    mut close_receiver: ConnectionCloseReceiver,
724    route_open_tasks: &mut JoinSet<Result<(), RouterError>>,
725    privileged_tasks: &mut JoinSet<Result<(), RouterError>>,
726) -> Result<ConnectionLoopExit, ConnectionError>
727where
728    R: AsyncRead + Unpin,
729{
730    let mut activity_tasks = JoinSet::new();
731    loop {
732        while let Some(result) = activity_tasks.try_join_next() {
733            finish_route_open_task(result)?;
734        }
735        while let Some(result) = privileged_tasks.try_join_next() {
736            finish_route_open_task(result)?;
737        }
738        while let Some(result) = route_open_tasks.try_join_next() {
739            finish_route_open_task(result)?;
740        }
741
742        // Keep the same read future when a route.open completes: read_frame owns
743        // partial header/body buffers that would be lost if that future were dropped.
744        let read = read_frame(&mut *read_half);
745        tokio::pin!(read);
746        let frame = loop {
747            tokio::select! {
748                close = &mut close_receiver => {
749                    return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
750                }
751                result = route_open_tasks.join_next(), if !route_open_tasks.is_empty() => {
752                    finish_route_open_task(
753                        result.expect("a non-empty route.open JoinSet has a next task")
754                    )?;
755                }
756                result = activity_tasks.join_next(), if !activity_tasks.is_empty() => {
757                    finish_route_open_task(result.expect("non-empty activity task set"))?;
758                }
759                result = privileged_tasks.join_next(), if !privileged_tasks.is_empty() => {
760                    finish_route_open_task(result.expect("non-empty privileged task set"))?;
761                }
762                result = &mut read => {
763                    break match result.map_err(ConnectionError::FrameIo)? {
764                        Some(frame) => frame,
765                        None => return Ok(ConnectionLoopExit::PeerClosed),
766                    };
767                }
768            }
769        };
770
771        if frame.header.channel == 0
772            && frame.header.ty == subc_protocol::FrameType::Request
773            && serde_json::from_slice::<serde_json::Value>(&frame.body)
774                .ok()
775                .is_some_and(|body| {
776                    matches!(
777                        body["op"].as_str(),
778                        Some(
779                            subc_control::ops::ACTIVITY_RECORD
780                                | subc_control::ops::ACTIVITY_QUERY
781                                | subc_control::ops::ACTIVITY_SUBSCRIBE
782                        )
783                    )
784                })
785        {
786            // Bound outstanding activity tasks as well as the disk queue,
787            // so the reader never waits for either capacity when the disk stalls.
788            if activity_tasks.len() >= 128 {
789                let response = crate::control::control_error_frame(
790                    &frame,
791                    subc_control::ACTIVITY_UNAVAILABLE,
792                    "activity queue full",
793                )
794                .map_err(ConnectionError::Router)?;
795                let send_result = tokio::select! {
796                    close = &mut close_receiver => {
797                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
798                    }
799                    result = ctx.egress.send(response) => result,
800                };
801                send_result.map_err(ConnectionError::Router)?;
802            } else {
803                let task_router = Arc::clone(&router);
804                let task_ctx = ctx.clone();
805                activity_tasks.spawn(async move {
806                    route_open_tail(task_router, task_ctx, frame, Instant::now()).await
807                });
808            }
809            continue;
810        }
811
812        if let Some(target_module_id) = router.route_open_target(&frame) {
813            // A task can finish while the reader is waiting for the next frame.
814            // Reap it before checking admission so completed work never occupies
815            // one of the deliberately scarce connection slots.
816            while let Some(result) = route_open_tasks.try_join_next() {
817                finish_route_open_task(result)?;
818            }
819
820            if route_open_tasks.len() >= MAX_PENDING_ROUTE_OPENS_PER_CONNECTION {
821                // Never wait for capacity here: doing so would recreate the same
822                // reader head-of-line stall with a smaller constant.
823                let refusal = router
824                    .route_open_capacity_refusal(
825                        &ctx,
826                        &frame,
827                        &target_module_id,
828                        route_open_tasks.len(),
829                        MAX_PENDING_ROUTE_OPENS_PER_CONNECTION,
830                    )
831                    .map_err(ConnectionError::Router)?;
832                let send_result = tokio::select! {
833                    close = &mut close_receiver => {
834                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
835                    }
836                    result = ctx.egress.send(refusal) => result,
837                };
838                send_result.map_err(ConnectionError::Router)?;
839                continue;
840            }
841
842            let task_router = Arc::clone(&router);
843            let task_ctx = ctx.clone();
844            // Start slow-dispatch timing before spawn so it covers the task's
845            // full scheduler and handler lifetime, as inline timing did.
846            let dispatch_started_at = Instant::now();
847            route_open_tasks.spawn(async move {
848                route_open_tail(task_router, task_ctx, frame, dispatch_started_at).await
849            });
850            continue;
851        }
852
853        if router.defers_privileged_control(&ctx, &frame) {
854            let task_router = Arc::clone(&router);
855            let task_ctx = ctx.clone();
856            let started = Instant::now();
857            privileged_tasks
858                .spawn(async move { route_open_tail(task_router, task_ctx, frame, started).await });
859            continue;
860        }
861
862        // Other frames still route serially: routing can backpressure reads,
863        // and a connection close cancels the in-progress route.
864        let route_result = tokio::select! {
865            close = &mut close_receiver => {
866                return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
867            }
868            result = router.route_for_connection(&ctx, frame) => result,
869        };
870
871        if let Err(err) = route_result {
872            if let Some(error_frame) = err.to_error_frame() {
873                warn!(
874                    connection_id = ctx.connection_id.get(),
875                    error = %err,
876                    "routing failure recovered with ERROR frame"
877                );
878                let send_result = tokio::select! {
879                    close = &mut close_receiver => {
880                        return Ok(ConnectionLoopExit::CloseRequested(close_reason(close)));
881                    }
882                    result = ctx.egress.send(error_frame) => result,
883                };
884                send_result.map_err(ConnectionError::Router)?;
885            } else {
886                debug!(
887                    connection_id = ctx.connection_id.get(),
888                    error = %err,
889                    "fatal routing failure"
890                );
891                return Err(ConnectionError::Router(err));
892            }
893        }
894    }
895}
896
897async fn route_open_tail(
898    router: Arc<Router>,
899    ctx: RouteCtx,
900    frame: crate::Frame,
901    dispatch_started_at: Instant,
902) -> Result<(), RouterError> {
903    match router
904        .route_for_connection_started(&ctx, frame, Some(dispatch_started_at))
905        .await
906    {
907        Ok(()) => Ok(()),
908        Err(err) => {
909            let Some(error_frame) = err.to_error_frame() else {
910                return Err(err);
911            };
912            warn!(
913                connection_id = ctx.connection_id.get(),
914                error = %err,
915                "routing failure recovered with ERROR frame"
916            );
917            ctx.egress.send(error_frame).await
918        }
919    }
920}
921
922fn finish_route_open_task(
923    result: Result<Result<(), RouterError>, tokio::task::JoinError>,
924) -> Result<(), ConnectionError> {
925    match result {
926        Ok(Ok(())) => Ok(()),
927        Ok(Err(err)) => Err(ConnectionError::Router(err)),
928        Err(err) => Err(ConnectionError::Router(RouterError::backend(
929            0,
930            0,
931            format!("route.open task failed: {err}"),
932        ))),
933    }
934}
935
936fn close_reason(
937    result: Result<CloseReason, tokio::sync::oneshot::error::RecvError>,
938) -> CloseReason {
939    result.unwrap_or_else(|_| {
940        CloseReason::new(
941            "close_registry_dropped",
942            "connection close registration was dropped without a reason",
943        )
944    })
945}
946
947/// The outbound queue for one daemon connection: a sink bounded by
948/// [`CONNECTION_EGRESS_BYTE_BUDGET`] and [`CONNECTION_EGRESS_FRAME_CAP`], and
949/// the receiver its writer drains.
950pub(crate) fn connection_egress() -> (FrameSink, mpsc::Receiver<crate::router::OutboundFrame>) {
951    let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(CONNECTION_EGRESS_FRAME_CAP);
952    (
953        FrameSink::with_byte_budget(tx, CONNECTION_EGRESS_BYTE_BUDGET),
954        rx,
955    )
956}
957
958async fn drain_writer<W>(
959    write_half: W,
960    mut rx: mpsc::Receiver<crate::router::OutboundFrame>,
961) -> Result<(), FrameIoError>
962where
963    W: AsyncWrite + Unpin,
964{
965    let mut writer = BufWriter::new(write_half);
966    while let Some(outbound) = rx.recv().await {
967        write_outbound(&mut writer, outbound).await?;
968        while let Ok(outbound) = rx.try_recv() {
969            write_outbound(&mut writer, outbound).await?;
970        }
971        writer.flush().await.map_err(FrameIoError::Io)?;
972    }
973    writer.flush().await.map_err(FrameIoError::Io)?;
974    Ok(())
975}
976
977/// Reply-path half of slow-control diagnosis: a channel-0 reply that sat in
978/// the writer queue past the threshold is reported with its queue residency
979/// and its own write duration separated, because "writer task not scheduled"
980/// and "socket write blocked" are different defects and the sum hides which.
981/// Data-plane frames are exempt: their latency is the client's own flow
982/// control, and logging them would drown the control signal in bulk traffic.
983async fn write_outbound<W>(
984    writer: &mut BufWriter<W>,
985    outbound: crate::router::OutboundFrame,
986) -> Result<(), FrameIoError>
987where
988    W: AsyncWrite + Unpin,
989{
990    const SLOW_REPLY_QUEUE: Duration = Duration::from_millis(1000);
991    let queued = outbound.enqueued_at.elapsed();
992    // Held until this frame has been written, then dropped at the end of this
993    // function, which gives its bytes back to the connection's egress budget.
994    let charge = outbound.charge;
995    if let Some(charge) = &charge {
996        charge.taken_by_writer();
997    }
998    let frame = outbound.frame;
999    if frame.header.channel == 0 && queued >= SLOW_REPLY_QUEUE {
1000        let write_started = std::time::Instant::now();
1001        let result = write_frame(writer, &frame).await;
1002        tracing::warn!(
1003            corr = frame.header.corr,
1004            queued_ms = queued.as_millis() as u64,
1005            write_ms = write_started.elapsed().as_millis() as u64,
1006            "slow control reply write"
1007        );
1008        result?;
1009    } else {
1010        write_frame(writer, &frame).await?;
1011    }
1012    if let Some(flushed) = outbound.flushed {
1013        writer.flush().await.map_err(FrameIoError::Io)?;
1014        let _ = flushed.send(());
1015    }
1016    Ok(())
1017}
1018
1019#[cfg(all(test, unix))]
1020#[tokio::test]
1021async fn shutdown_notice_ack_waits_for_socket_flush() {
1022    let (socket, mut peer) = tokio::io::duplex(1);
1023    let (tx, rx) = mpsc::channel(1);
1024    let sink = FrameSink::new(tx);
1025    let writer = tokio::spawn(drain_writer(socket, rx));
1026    let frame = crate::Frame::build(
1027        subc_protocol::FrameType::Push,
1028        subc_protocol::Flags::new(false, subc_protocol::Priority::Interactive, false),
1029        0,
1030        0,
1031        0,
1032        b"notice".to_vec(),
1033    )
1034    .unwrap();
1035    let send = sink.send_flushed(frame);
1036    tokio::pin!(send);
1037    assert!(
1038        timeout(Duration::from_millis(20), &mut send).await.is_err(),
1039        "queueing bytes is not a socket flush acknowledgement"
1040    );
1041    let (sent, received) = timeout(Duration::from_secs(1), async {
1042        tokio::join!(&mut send, read_frame(&mut peer))
1043    })
1044    .await
1045    .unwrap();
1046    sent.unwrap();
1047    assert_eq!(received.unwrap().unwrap().body, b"notice");
1048    writer.abort();
1049}
1050
1051#[derive(Debug)]
1052pub enum ServerError {
1053    NoListeners,
1054    Accept {
1055        local_addr: Option<SocketAddr>,
1056        source: io::Error,
1057    },
1058}
1059
1060impl fmt::Display for ServerError {
1061    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1062        match self {
1063            Self::NoListeners => write!(f, "no TCP listeners were provided"),
1064            Self::Accept { local_addr, source } => match local_addr {
1065                Some(addr) => write!(f, "failed to accept TCP connection on {addr}: {source}"),
1066                None => write!(f, "failed to accept TCP connection: {source}"),
1067            },
1068        }
1069    }
1070}
1071
1072impl Error for ServerError {
1073    fn source(&self) -> Option<&(dyn Error + 'static)> {
1074        match self {
1075            Self::Accept { source, .. } => Some(source),
1076            Self::NoListeners => None,
1077        }
1078    }
1079}
1080
1081#[derive(Debug)]
1082pub enum ConnectionError {
1083    Auth(AuthError),
1084    UnauthenticatedCapacity,
1085    FrameIo(FrameIoError),
1086    Router(RouterError),
1087    WriterTask(tokio::task::JoinError),
1088}
1089
1090impl ConnectionError {
1091    fn is_quiet_reject(&self) -> bool {
1092        matches!(self, Self::Auth(_) | Self::UnauthenticatedCapacity)
1093    }
1094
1095    fn pre_auth_reject_stage(&self) -> Option<PreAuthRejectStage> {
1096        match self {
1097            Self::UnauthenticatedCapacity => Some(PreAuthRejectStage::WaitingForHandshakeSlot),
1098            Self::Auth(AuthError::Timeout { .. }) => Some(PreAuthRejectStage::HandshakeDeadline),
1099            Self::Auth(
1100                AuthError::InvalidClientAuth
1101                | AuthError::InvalidServerProof
1102                | AuthError::DaemonIdMismatch,
1103            ) => Some(PreAuthRejectStage::InvalidProof),
1104            Self::Auth(AuthError::MessageTooLarge { .. } | AuthError::JsonDecode { .. }) => {
1105                Some(PreAuthRejectStage::MalformedMessage)
1106            }
1107            Self::Auth(AuthError::UnexpectedEof { .. }) => Some(PreAuthRejectStage::PeerClosed),
1108            Self::Auth(AuthError::Io { source, .. })
1109                if matches!(
1110                    source.kind(),
1111                    io::ErrorKind::BrokenPipe
1112                        | io::ErrorKind::ConnectionAborted
1113                        | io::ErrorKind::ConnectionReset
1114                        | io::ErrorKind::UnexpectedEof
1115                ) =>
1116            {
1117                Some(PreAuthRejectStage::PeerClosed)
1118            }
1119            Self::Auth(_) => Some(PreAuthRejectStage::OtherAuthenticationFailure),
1120            Self::FrameIo(_) | Self::Router(_) | Self::WriterTask(_) => None,
1121        }
1122    }
1123
1124    fn auth_stage(&self) -> Option<AuthStage> {
1125        match self {
1126            Self::Auth(
1127                AuthError::Io { stage, .. }
1128                | AuthError::Timeout { stage, .. }
1129                | AuthError::UnexpectedEof { stage, .. }
1130                | AuthError::MessageTooLarge { stage, .. }
1131                | AuthError::JsonEncode { stage, .. }
1132                | AuthError::JsonDecode { stage, .. },
1133            ) => Some(*stage),
1134            Self::Auth(
1135                AuthError::Random(_)
1136                | AuthError::KeyTooShort { .. }
1137                | AuthError::InvalidServerProof
1138                | AuthError::DaemonIdMismatch
1139                | AuthError::InvalidClientAuth,
1140            )
1141            | Self::UnauthenticatedCapacity
1142            | Self::FrameIo(_)
1143            | Self::Router(_)
1144            | Self::WriterTask(_) => None,
1145        }
1146    }
1147}
1148
1149impl fmt::Display for ConnectionError {
1150    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1151        match self {
1152            Self::Auth(err) => write!(f, "connection auth failed: {err}"),
1153            Self::UnauthenticatedCapacity => write!(
1154                f,
1155                "too many concurrent unauthenticated subc TCP connections"
1156            ),
1157            Self::FrameIo(err) => write!(f, "frame connection error: {err}"),
1158            Self::Router(err) => write!(f, "router connection error: {err}"),
1159            Self::WriterTask(err) => write!(f, "connection writer task failed: {err}"),
1160        }
1161    }
1162}
1163
1164impl Error for ConnectionError {
1165    fn source(&self) -> Option<&(dyn Error + 'static)> {
1166        match self {
1167            Self::Auth(err) => Some(err),
1168            Self::FrameIo(err) => Some(err),
1169            Self::Router(err) => Some(err),
1170            Self::WriterTask(err) => Some(err),
1171            Self::UnauthenticatedCapacity => None,
1172        }
1173    }
1174}
1175
1176#[cfg(test)]
1177mod tests {
1178    use std::{
1179        future::Future,
1180        pin::Pin,
1181        sync::atomic::{AtomicUsize, Ordering},
1182        task::{Context, Poll},
1183    };
1184
1185    use super::*;
1186    use serde::{de::DeserializeOwned, Serialize};
1187    use subc_protocol::{
1188        DecodeError, ErrorBody, Flags, FrameType, Priority, HEADER_LEN, PROTOCOL_VERSION,
1189    };
1190    use tokio::io::{duplex, AsyncReadExt, AsyncWriteExt, ReadBuf};
1191
1192    use subc_transport::{
1193        authenticate_client, compute_proof, ClientAuth, ClientHello, ConnectionInfo, Endpoint,
1194        ServerProof, CLIENT_AUTH_DOMAIN, NONCE_LEN, SCHEMA_VERSION,
1195    };
1196
1197    use crate::{ControlHandler, EchoBackend, Frame, ReadStage, Registry};
1198
1199    const TEST_DEADLINE: Duration = Duration::from_secs(2);
1200    const TEST_DAEMON_VER: &str = "test-subc-server";
1201
1202    /// Modules size their replies against the published limit, and the router
1203    /// refuses any module frame over the egress budget, so the two must be the
1204    /// same number. This fails if the budget is ever given its own value.
1205    #[test]
1206    fn egress_budget_is_the_published_delivered_frame_limit() {
1207        assert_eq!(
1208            CONNECTION_EGRESS_BYTE_BUDGET,
1209            subc_protocol::MAX_DELIVERED_FRAME_LEN
1210        );
1211    }
1212
1213    struct ObservedStream {
1214        inner: tokio::io::DuplexStream,
1215        write_blocked: Arc<tokio::sync::Notify>,
1216        dropped: Arc<AtomicUsize>,
1217        read_error: Option<tokio::sync::oneshot::Receiver<()>>,
1218    }
1219
1220    impl AsyncRead for ObservedStream {
1221        fn poll_read(
1222            mut self: Pin<&mut Self>,
1223            cx: &mut Context<'_>,
1224            buf: &mut ReadBuf<'_>,
1225        ) -> Poll<io::Result<()>> {
1226            if let Some(receiver) = self.read_error.as_mut() {
1227                match Pin::new(receiver).poll(cx) {
1228                    Poll::Ready(Ok(())) => {
1229                        self.read_error = None;
1230                        return Poll::Ready(Err(io::ErrorKind::ConnectionReset.into()));
1231                    }
1232                    Poll::Ready(Err(_)) => self.read_error = None,
1233                    Poll::Pending => {}
1234                }
1235            }
1236            Pin::new(&mut self.inner).poll_read(cx, buf)
1237        }
1238    }
1239
1240    impl AsyncWrite for ObservedStream {
1241        fn poll_write(
1242            mut self: Pin<&mut Self>,
1243            cx: &mut Context<'_>,
1244            buf: &[u8],
1245        ) -> Poll<io::Result<usize>> {
1246            let result = Pin::new(&mut self.inner).poll_write(cx, buf);
1247            if result.is_pending() {
1248                self.write_blocked.notify_one();
1249            }
1250            result
1251        }
1252
1253        fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
1254            Pin::new(&mut self.inner).poll_flush(cx)
1255        }
1256
1257        fn poll_shutdown(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
1258            Pin::new(&mut self.inner).poll_shutdown(cx)
1259        }
1260    }
1261
1262    impl Drop for ObservedStream {
1263        fn drop(&mut self) {
1264            self.dropped.fetch_add(1, Ordering::SeqCst);
1265        }
1266    }
1267
1268    struct BlockedWriterConnection {
1269        client: tokio::io::DuplexStream,
1270        server: JoinHandle<Result<(), ConnectionError>>,
1271        stream_dropped: Arc<AtomicUsize>,
1272        read_error: Option<tokio::sync::oneshot::Sender<()>>,
1273        router: Arc<Router>,
1274    }
1275
1276    impl BlockedWriterConnection {
1277        async fn new() -> Self {
1278            let (mut client, inner) = duplex(256);
1279            let write_blocked = Arc::new(tokio::sync::Notify::new());
1280            let stream_dropped = Arc::new(AtomicUsize::new(0));
1281            let (read_error, receiver) = tokio::sync::oneshot::channel();
1282            let stream = ObservedStream {
1283                inner,
1284                write_blocked: Arc::clone(&write_blocked),
1285                dropped: Arc::clone(&stream_dropped),
1286                read_error: Some(receiver),
1287            };
1288            let (auth, conn) = test_auth();
1289            let router = echo_router();
1290            let server = tokio::spawn(handle_connection(stream, Arc::clone(&router), auth));
1291            authenticate(&mut client, &conn).await;
1292
1293            // Ignore any backpressure observed during authentication. The echo
1294            // reply is larger than the duplex capacity and the client never reads it.
1295            let _ = timeout(Duration::ZERO, write_blocked.notified()).await;
1296            write_frame(&mut client, &request(7, 1, &[b'x'; 1024]))
1297                .await
1298                .unwrap();
1299            timeout(TEST_DEADLINE, write_blocked.notified())
1300                .await
1301                .expect("writer should block on the unread echo reply");
1302            assert!(!server.is_finished());
1303            assert_eq!(stream_dropped.load(Ordering::SeqCst), 0);
1304            Self {
1305                client,
1306                server,
1307                stream_dropped,
1308                read_error: Some(read_error),
1309                router,
1310            }
1311        }
1312
1313        async fn finish(&mut self) -> Result<(), ConnectionError> {
1314            let started = tokio::time::Instant::now();
1315            let result = timeout(CLOSE_DRAIN_GRACE + Duration::from_secs(1), &mut self.server)
1316                .await
1317                .expect("connection teardown exceeded writer drain grace plus margin")
1318                .expect("connection task should not panic");
1319            assert!(started.elapsed() >= CLOSE_DRAIN_GRACE);
1320            assert_eq!(
1321                self.stream_dropped.load(Ordering::SeqCst),
1322                1,
1323                "writer must release its stream half before teardown completes"
1324            );
1325            result
1326        }
1327
1328        fn request_close(&self) {
1329            // Each fixture owns a fresh router, so its only connection has ID 1.
1330            assert!(self.router.forwarding().request_connection_close(
1331                crate::registry::ConnectionId::new(1),
1332                CloseReason::new("test_close", "test requested close"),
1333            ));
1334        }
1335    }
1336
1337    #[tokio::test(start_paused = true)]
1338    async fn peer_eof_bounds_blocked_writer_teardown() {
1339        let mut connection = BlockedWriterConnection::new().await;
1340        // Half-close only the client-to-server direction: the unread receive
1341        // buffer must stay alive so the server's writer cannot finish naturally.
1342        connection.client.shutdown().await.unwrap();
1343        connection.finish().await.unwrap();
1344    }
1345
1346    #[tokio::test(start_paused = true)]
1347    async fn read_error_bounds_blocked_writer_teardown() {
1348        let mut connection = BlockedWriterConnection::new().await;
1349        connection.read_error.take().unwrap().send(()).unwrap();
1350        let error = connection.finish().await.unwrap_err();
1351        assert!(matches!(
1352            error,
1353            ConnectionError::FrameIo(FrameIoError::Io(error))
1354                if error.kind() == io::ErrorKind::ConnectionReset
1355        ));
1356    }
1357
1358    #[tokio::test(start_paused = true)]
1359    async fn close_requested_bounds_blocked_writer_teardown() {
1360        let mut connection = BlockedWriterConnection::new().await;
1361        connection.request_close();
1362        connection.finish().await.unwrap();
1363    }
1364
1365    #[tokio::test(start_paused = true)]
1366    async fn close_requested_flushes_queued_reply_before_grace() {
1367        let mut connection = BlockedWriterConnection::new().await;
1368        connection.request_close();
1369        let started = tokio::time::Instant::now();
1370        let reply = timeout(CLOSE_DRAIN_GRACE, read_frame(&mut connection.client))
1371            .await
1372            .expect("queued reply should flush before the grace expires")
1373            .unwrap()
1374            .unwrap();
1375        assert_eq!(reply.body, vec![b'x'; 1024]);
1376        timeout(CLOSE_DRAIN_GRACE, &mut connection.server)
1377            .await
1378            .unwrap()
1379            .unwrap()
1380            .unwrap();
1381        assert!(started.elapsed() < CLOSE_DRAIN_GRACE);
1382        assert_eq!(connection.stream_dropped.load(Ordering::SeqCst), 1);
1383    }
1384
1385    /// Reply-path stamp, slow polarity: a channel-0 reply whose queue residency
1386    /// exceeds the threshold must produce the slow-control-reply-write WARN with
1387    /// queued_ms reflecting the residency. Uses a backdated stamp rather than a
1388    /// real stall so the test is fast and deterministic.
1389    #[tokio::test]
1390    async fn stale_queued_control_reply_logs_slow_reply_write() {
1391        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::WARN);
1392        let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(4);
1393        let reply = Frame::build_with_version(
1394            PROTOCOL_VERSION,
1395            FrameType::Error,
1396            Flags::new(false, Priority::Interactive, false),
1397            0,
1398            0,
1399            7,
1400            serde_json::to_vec(&ErrorBody {
1401                code: "test".into(),
1402                message: "reply".into(),
1403                detail: None,
1404            })
1405            .expect("body encodes"),
1406        )
1407        .expect("frame builds");
1408        tx.send(crate::router::OutboundFrame {
1409            frame: reply,
1410            enqueued_at: std::time::Instant::now() - Duration::from_millis(1500),
1411            flushed: None,
1412            charge: None,
1413        })
1414        .await
1415        .expect("queued");
1416        drop(tx);
1417        let (write_half, mut read_half) = duplex(64 * 1024);
1418        drain_writer(write_half, rx).await.expect("writer drains");
1419        let mut sink = Vec::new();
1420        read_half.read_to_end(&mut sink).await.expect("read");
1421        assert!(!sink.is_empty(), "frame reached the socket");
1422        let captured = crate::router::test_log::captured_logs(&logs);
1423        assert!(
1424            captured.contains("slow control reply write") && captured.contains("corr=7"),
1425            "expected slow reply WARN naming corr, got: {captured}"
1426        );
1427        let queued_ms: u64 = captured
1428            .split("queued_ms=")
1429            .nth(1)
1430            .and_then(|s| s.split_whitespace().next())
1431            .and_then(|s| s.parse().ok())
1432            .expect("queued_ms present");
1433        assert!(
1434            queued_ms >= 1500,
1435            "queued_ms reflects residency: {queued_ms}"
1436        );
1437    }
1438
1439    /// Fast polarity: a promptly-drained control reply and a stale DATA-PLANE
1440    /// frame must both stay silent — the WARN is channel-0-only by design, and
1441    /// a healthy queue must add zero log volume.
1442    #[tokio::test]
1443    async fn fresh_control_and_stale_data_frames_log_nothing() {
1444        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::WARN);
1445        let (tx, rx) = mpsc::channel::<crate::router::OutboundFrame>(4);
1446        let control = Frame::build_with_version(
1447            PROTOCOL_VERSION,
1448            FrameType::Error,
1449            Flags::new(false, Priority::Interactive, false),
1450            0,
1451            0,
1452            8,
1453            serde_json::to_vec(&ErrorBody {
1454                code: "test".into(),
1455                message: "fresh".into(),
1456                detail: None,
1457            })
1458            .expect("body encodes"),
1459        )
1460        .expect("frame builds");
1461        tx.send(crate::router::OutboundFrame {
1462            frame: control,
1463            enqueued_at: std::time::Instant::now(),
1464            flushed: None,
1465            charge: None,
1466        })
1467        .await
1468        .expect("queued");
1469        let data = Frame::build_with_version(
1470            PROTOCOL_VERSION,
1471            FrameType::Error,
1472            Flags::new(false, Priority::Interactive, false),
1473            9,
1474            1,
1475            9,
1476            serde_json::to_vec(&ErrorBody {
1477                code: "test".into(),
1478                message: "data".into(),
1479                detail: None,
1480            })
1481            .expect("body encodes"),
1482        )
1483        .expect("frame builds");
1484        tx.send(crate::router::OutboundFrame {
1485            frame: data,
1486            enqueued_at: std::time::Instant::now() - Duration::from_millis(5000),
1487            flushed: None,
1488            charge: None,
1489        })
1490        .await
1491        .expect("queued");
1492        drop(tx);
1493        let (write_half, _read_half) = duplex(64 * 1024);
1494        drain_writer(write_half, rx).await.expect("writer drains");
1495        let captured = crate::router::test_log::captured_logs(&logs);
1496        assert!(
1497            !captured.contains("slow control reply write"),
1498            "no WARN for fresh control or stale data frames, got: {captured}"
1499        );
1500    }
1501
1502    struct CountingReader {
1503        bytes: Vec<u8>,
1504        offset: usize,
1505        first_read_end: Option<usize>,
1506        reads: Arc<AtomicUsize>,
1507    }
1508
1509    impl CountingReader {
1510        fn new(bytes: Vec<u8>, first_read_end: Option<usize>) -> (Self, Arc<AtomicUsize>) {
1511            let reads = Arc::new(AtomicUsize::new(0));
1512            (
1513                Self {
1514                    bytes,
1515                    offset: 0,
1516                    first_read_end,
1517                    reads: Arc::clone(&reads),
1518                },
1519                reads,
1520            )
1521        }
1522    }
1523
1524    impl AsyncRead for CountingReader {
1525        fn poll_read(
1526            mut self: Pin<&mut Self>,
1527            _cx: &mut Context<'_>,
1528            buf: &mut ReadBuf<'_>,
1529        ) -> Poll<io::Result<()>> {
1530            self.reads.fetch_add(1, Ordering::Relaxed);
1531            let available = self.bytes.len().saturating_sub(self.offset);
1532            let first_read_remaining = self
1533                .first_read_end
1534                .filter(|end| self.offset < *end)
1535                .map_or(available, |end| end - self.offset);
1536            let count = available.min(first_read_remaining).min(buf.remaining());
1537            let end = self.offset + count;
1538            buf.put_slice(&self.bytes[self.offset..end]);
1539            self.offset = end;
1540            Poll::Ready(Ok(()))
1541        }
1542    }
1543
1544    fn encode_frames(frames: &[Frame]) -> Vec<u8> {
1545        let mut bytes = Vec::new();
1546        for frame in frames {
1547            bytes.extend_from_slice(&frame.header.encode());
1548            bytes.extend_from_slice(&frame.body);
1549        }
1550        bytes
1551    }
1552
1553    async fn read_frames<R>(reader: &mut R, count: usize) -> Vec<Frame>
1554    where
1555        R: AsyncRead + Unpin,
1556    {
1557        let mut frames = Vec::with_capacity(count);
1558        for _ in 0..count {
1559            frames.push(read_frame(reader).await.unwrap().unwrap());
1560        }
1561        frames
1562    }
1563
1564    fn request(channel: u16, corr: u64, body: &[u8]) -> Frame {
1565        Frame::build(
1566            FrameType::Request,
1567            Flags::new(true, Priority::Interactive, false),
1568            channel,
1569            0,
1570            corr,
1571            body.to_vec(),
1572        )
1573        .unwrap()
1574    }
1575
1576    fn echo_router() -> Arc<Router> {
1577        let mut router = Router::with_default_self_handler();
1578        router.register_backend(7, EchoBackend).unwrap();
1579        router.register_backend(9, EchoBackend).unwrap();
1580        Arc::new(router)
1581    }
1582
1583    fn test_auth() -> (ServerAuth, ConnectionInfo) {
1584        test_auth_with_limit(4)
1585    }
1586
1587    fn test_auth_with_limit(max_unauthenticated: usize) -> (ServerAuth, ConnectionInfo) {
1588        test_auth_with_deadline_and_limit(TEST_DEADLINE, max_unauthenticated)
1589    }
1590
1591    fn test_auth_with_deadline_and_limit(
1592        deadline: Duration,
1593        max_unauthenticated: usize,
1594    ) -> (ServerAuth, ConnectionInfo) {
1595        let key = vec![0x42; 32];
1596        let daemon_id = [0x24; 16];
1597        let conn = ConnectionInfo {
1598            schema: SCHEMA_VERSION,
1599            wire_version: None,
1600            endpoints: vec![Endpoint {
1601                host: "127.0.0.1".to_owned(),
1602                port: 1,
1603            }],
1604            key: key.clone(),
1605            daemon_id,
1606            pid: std::process::id(),
1607            daemon_ver: TEST_DAEMON_VER.to_owned(),
1608        };
1609        (
1610            ServerAuth::with_limits(
1611                key,
1612                daemon_id,
1613                TEST_DAEMON_VER,
1614                deadline,
1615                max_unauthenticated,
1616            ),
1617            conn,
1618        )
1619    }
1620
1621    async fn authenticate<S>(stream: &mut S, conn: &ConnectionInfo)
1622    where
1623        S: AsyncRead + AsyncWrite + Unpin,
1624    {
1625        authenticate_client(stream, conn, TEST_DEADLINE)
1626            .await
1627            .expect("test client should authenticate")
1628    }
1629
1630    async fn write_auth_message<S, T>(stream: &mut S, value: &T)
1631    where
1632        S: AsyncWrite + Unpin,
1633        T: Serialize,
1634    {
1635        let body = serde_json::to_vec(value).expect("auth message encodes");
1636        stream
1637            .write_all(&(body.len() as u32).to_le_bytes())
1638            .await
1639            .expect("auth message length writes");
1640        stream
1641            .write_all(&body)
1642            .await
1643            .expect("auth message body writes");
1644    }
1645
1646    async fn read_auth_message<S, T>(stream: &mut S) -> T
1647    where
1648        S: AsyncRead + Unpin,
1649        T: DeserializeOwned,
1650    {
1651        let mut length = [0; 4];
1652        stream
1653            .read_exact(&mut length)
1654            .await
1655            .expect("auth message length reads");
1656        let mut body = vec![0; u32::from_le_bytes(length) as usize];
1657        stream
1658            .read_exact(&mut body)
1659            .await
1660            .expect("auth message body reads");
1661        serde_json::from_slice(&body).expect("auth message decodes")
1662    }
1663
1664    async fn send_wrong_key_client_auth<S>(stream: &mut S, conn: &ConnectionInfo)
1665    where
1666        S: AsyncRead + AsyncWrite + Unpin,
1667    {
1668        let hello = ClientHello {
1669            client_nonce: [0x57; NONCE_LEN],
1670            role: "client".to_owned(),
1671        };
1672        write_auth_message(stream, &hello).await;
1673        let proof: ServerProof = read_auth_message(stream).await;
1674        let mut wrong_key = conn.key.clone();
1675        wrong_key[0] ^= 0xff;
1676        let client_auth = ClientAuth {
1677            client_auth: compute_proof(
1678                &wrong_key,
1679                CLIENT_AUTH_DOMAIN,
1680                &hello.client_nonce,
1681                &proof.server_nonce,
1682                &conn.daemon_id,
1683            ),
1684        };
1685        write_auth_message(stream, &client_auth).await;
1686    }
1687
1688    fn assert_pre_auth_log(logs: &Arc<std::sync::Mutex<Vec<u8>>>, stage: &str, port: u16) {
1689        let captured = crate::router::test_log::captured_logs(logs);
1690        assert!(
1691            captured.contains(&format!("stage=\"{stage}\"")),
1692            "expected rejection stage {stage}, got: {captured}"
1693        );
1694        assert!(
1695            captured.contains(&format!("peer_addr=127.0.0.1:{port}")),
1696            "expected peer address, got: {captured}"
1697        );
1698        assert!(
1699            captured.contains("elapsed_ms=") && captured.contains("suppressed_since_last="),
1700            "expected elapsed time and suppression count, got: {captured}"
1701        );
1702        assert!(
1703            !captured.contains("WARN"),
1704            "pre-auth rejection must not be logged as a warning: {captured}"
1705        );
1706    }
1707
1708    #[tokio::test]
1709    async fn logs_handshake_deadline_pre_auth_rejection() {
1710        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1711        let deadline = Duration::from_millis(60);
1712        let (auth, _) = test_auth_with_deadline_and_limit(deadline, 4);
1713        let (client, server_stream) = duplex(512);
1714        let port = 41001;
1715        let server = handle_accepted_connection(
1716            server_stream,
1717            echo_router(),
1718            auth,
1719            SocketAddr::from(([127, 0, 0, 1], port)),
1720            Instant::now(),
1721        );
1722
1723        let error = tokio::time::timeout(deadline * 3, server)
1724            .await
1725            .expect("idle handshake should end at its deadline")
1726            .expect_err("idle handshake must be rejected");
1727        drop(client);
1728        assert!(matches!(
1729            error,
1730            ConnectionError::Auth(AuthError::Timeout {
1731                stage: AuthStage::ClientHello,
1732                ..
1733            })
1734        ));
1735        let captured = crate::router::test_log::captured_logs(&logs);
1736        assert!(
1737            captured.contains("reason=\"handshake_deadline_expired\""),
1738            "{captured}"
1739        );
1740        assert_pre_auth_log(&logs, "handshake_deadline", port);
1741    }
1742
1743    #[tokio::test]
1744    async fn logs_invalid_client_proof_pre_auth_rejection() {
1745        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1746        let (auth, conn) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
1747        let (mut client, server_stream) = duplex(512);
1748        let port = 41002;
1749        let server = handle_accepted_connection(
1750            server_stream,
1751            echo_router(),
1752            auth,
1753            SocketAddr::from(([127, 0, 0, 1], port)),
1754            Instant::now(),
1755        );
1756
1757        let (error, ()) = tokio::join!(server, send_wrong_key_client_auth(&mut client, &conn));
1758        assert!(matches!(
1759            error,
1760            Err(ConnectionError::Auth(AuthError::InvalidClientAuth))
1761        ));
1762        let captured = crate::router::test_log::captured_logs(&logs);
1763        assert!(
1764            captured.contains("reason=\"client_proof_mismatch\""),
1765            "{captured}"
1766        );
1767        assert_pre_auth_log(&logs, "client_authentication", port);
1768    }
1769
1770    #[tokio::test]
1771    async fn logs_malformed_pre_auth_message() {
1772        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1773        let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
1774        let (mut client, server_stream) = duplex(512);
1775        let port = 41003;
1776        let server = handle_accepted_connection(
1777            server_stream,
1778            echo_router(),
1779            auth,
1780            SocketAddr::from(([127, 0, 0, 1], port)),
1781            Instant::now(),
1782        );
1783        let send_malformed_message = async {
1784            let body = b"{";
1785            client
1786                .write_all(&(body.len() as u32).to_le_bytes())
1787                .await
1788                .expect("message length writes");
1789            client.write_all(body).await.expect("message body writes");
1790        };
1791
1792        let (error, ()) = tokio::join!(server, send_malformed_message);
1793        assert!(matches!(
1794            error,
1795            Err(ConnectionError::Auth(AuthError::JsonDecode {
1796                stage: AuthStage::ClientHello,
1797                ..
1798            }))
1799        ));
1800        let captured = crate::router::test_log::captured_logs(&logs);
1801        assert!(
1802            captured.contains("reason=\"malformed_or_oversized_message\""),
1803            "{captured}"
1804        );
1805        assert_pre_auth_log(&logs, "malformed_message", port);
1806    }
1807
1808    #[tokio::test]
1809    async fn logs_peer_close_during_handshake() {
1810        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1811        let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
1812        let (client, server_stream) = duplex(512);
1813        let port = 41004;
1814        drop(client);
1815
1816        let error = handle_accepted_connection(
1817            server_stream,
1818            echo_router(),
1819            auth,
1820            SocketAddr::from(([127, 0, 0, 1], port)),
1821            Instant::now(),
1822        )
1823        .await
1824        .expect_err("closed peer must be rejected");
1825        assert!(matches!(
1826            error,
1827            ConnectionError::Auth(AuthError::UnexpectedEof {
1828                stage: AuthStage::ClientHello,
1829                actual: 0,
1830                ..
1831            })
1832        ));
1833        let captured = crate::router::test_log::captured_logs(&logs);
1834        assert!(
1835            captured.contains("reason=\"peer_closed_before_authentication_completed\""),
1836            "{captured}"
1837        );
1838        assert_pre_auth_log(&logs, "peer_closed", port);
1839    }
1840
1841    // Rejection-log rate limits belong to one listener. A process-wide limiter
1842    // let one listener's rejects silence another's for a second, which hid the
1843    // second listener's first rejection entirely.
1844    #[tokio::test]
1845    async fn each_listener_rate_limits_its_own_rejection_logs() {
1846        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1847        for port in [41011, 41012] {
1848            let (auth, _) = test_auth_with_deadline_and_limit(Duration::from_millis(200), 4);
1849            let (client, server_stream) = duplex(512);
1850            drop(client);
1851            handle_accepted_connection(
1852                server_stream,
1853                echo_router(),
1854                auth,
1855                SocketAddr::from(([127, 0, 0, 1], port)),
1856                Instant::now(),
1857            )
1858            .await
1859            .expect_err("closed peer must be rejected");
1860        }
1861        let captured = crate::router::test_log::captured_logs(&logs);
1862        for port in [41011, 41012] {
1863            assert!(
1864                captured.contains(&format!("127.0.0.1:{port}")),
1865                "listener on port {port} logged nothing: {captured}"
1866            );
1867        }
1868    }
1869
1870    #[tokio::test]
1871    async fn logs_unauthenticated_capacity_rejection() {
1872        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1873        let deadline = Duration::from_millis(60);
1874        let (auth, _) = test_auth_with_deadline_and_limit(deadline, 1);
1875        let held_slot = auth
1876            .unauthenticated
1877            .clone()
1878            .try_acquire_owned()
1879            .expect("the only pre-auth slot is available");
1880        let (client, server_stream) = duplex(512);
1881        let port = 41005;
1882        let server = handle_accepted_connection(
1883            server_stream,
1884            echo_router(),
1885            auth,
1886            SocketAddr::from(([127, 0, 0, 1], port)),
1887            Instant::now(),
1888        );
1889
1890        let error = tokio::time::timeout(deadline * 3, server)
1891            .await
1892            .expect("queued connection should end at the capacity deadline")
1893            .expect_err("connection without a free slot must be rejected");
1894        drop(held_slot);
1895        drop(client);
1896        assert!(matches!(error, ConnectionError::UnauthenticatedCapacity));
1897        let captured = crate::router::test_log::captured_logs(&logs);
1898        assert!(
1899            captured.contains("reason=\"capacity_wait_timed_out\""),
1900            "{captured}"
1901        );
1902        assert_pre_auth_log(&logs, "waiting_for_handshake_slot", port);
1903    }
1904
1905    #[test]
1906    fn pre_auth_rejection_limiter_suppresses_bursts_and_reports_count() {
1907        let (logs, _guard) = crate::router::test_log::log_capture(tracing::Level::INFO);
1908        let limiter = PreAuthRejectLimiter::new();
1909        let capacity = ConnectionError::UnauthenticatedCapacity;
1910        let handshake_timeout = ConnectionError::Auth(AuthError::Timeout {
1911            stage: AuthStage::ClientHello,
1912            deadline: Duration::from_millis(200),
1913        });
1914        let peer_addr = SocketAddr::from(([127, 0, 0, 1], 41006));
1915
1916        log_pre_auth_rejection(
1917            &capacity,
1918            peer_addr,
1919            Duration::from_millis(1),
1920            Duration::ZERO,
1921            &limiter,
1922        );
1923        for _ in 0..4 {
1924            log_pre_auth_rejection(
1925                &capacity,
1926                peer_addr,
1927                Duration::from_millis(2),
1928                Duration::from_millis(100),
1929                &limiter,
1930            );
1931        }
1932        log_pre_auth_rejection(
1933            &handshake_timeout,
1934            peer_addr,
1935            Duration::from_millis(3),
1936            Duration::from_millis(100),
1937            &limiter,
1938        );
1939        log_pre_auth_rejection(
1940            &capacity,
1941            peer_addr,
1942            Duration::from_millis(4),
1943            Duration::from_secs(1),
1944            &limiter,
1945        );
1946
1947        let captured = crate::router::test_log::captured_logs(&logs);
1948        assert_eq!(
1949            captured
1950                .matches("subc TCP connection rejected before routing")
1951                .count(),
1952            3,
1953            "one line per stage in a burst, then a later capacity line: {captured}"
1954        );
1955        assert!(
1956            captured.contains("suppressed_since_last=4"),
1957            "later capacity line should report the four hidden rejects: {captured}"
1958        );
1959        assert!(
1960            captured.contains("stage=\"handshake_deadline\""),
1961            "{captured}"
1962        );
1963    }
1964
1965    #[tokio::test]
1966    async fn buffered_frame_reader_coalesces_reads_and_preserves_short_reads() {
1967        let frames = vec![
1968            request(7, 1, b"first"),
1969            request(9, 2, b"second"),
1970            request(7, 3, b"third"),
1971            request(9, 4, b"fourth"),
1972        ];
1973        let bytes = encode_frames(&frames);
1974
1975        let (mut direct, direct_reads) = CountingReader::new(bytes.clone(), None);
1976        assert_eq!(read_frames(&mut direct, frames.len()).await, frames);
1977        assert_eq!(direct_reads.load(Ordering::Relaxed), frames.len() * 3);
1978
1979        let (buffered_source, buffered_reads) = CountingReader::new(bytes, None);
1980        let mut buffered = BufReader::new(buffered_source);
1981        assert_eq!(read_frames(&mut buffered, frames.len()).await, frames);
1982        assert_eq!(buffered_reads.load(Ordering::Relaxed), 1);
1983
1984        let split_frame = request(7, 5, b"split-body");
1985        let split_bytes = encode_frames(std::slice::from_ref(&split_frame));
1986        let (split_source, split_reads) = CountingReader::new(split_bytes, Some(10));
1987        let mut split_reader = BufReader::new(split_source);
1988        assert_eq!(
1989            read_frame(&mut split_reader).await.unwrap(),
1990            Some(split_frame)
1991        );
1992        assert_eq!(split_reads.load(Ordering::Relaxed), 2);
1993    }
1994
1995    #[tokio::test]
1996    async fn interleaved_channels_on_one_stream_demux_byte_identically_after_auth() {
1997        let (mut client, server_stream) = duplex(4096);
1998        let (auth, conn) = test_auth();
1999        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2000        authenticate(&mut client, &conn).await;
2001        let frames = [
2002            request(7, 1, b"chan7-first\0opaque"),
2003            request(9, 2, b"chan9-middle-{json?}"),
2004            request(7, 3, b"chan7-second\xffbytes"),
2005        ];
2006
2007        for frame in &frames {
2008            crate::write_frame(&mut client, frame).await.unwrap();
2009        }
2010
2011        for expected in &frames {
2012            let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2013            assert_eq!(response.header.ty, FrameType::Response);
2014            assert_eq!(response.header.channel, expected.header.channel);
2015            assert_eq!(response.header.corr, expected.header.corr);
2016            assert_eq!(response.body, expected.body);
2017        }
2018
2019        drop(client);
2020        server.await.unwrap().unwrap();
2021    }
2022
2023    #[tokio::test]
2024    async fn channel_zero_goes_to_subc_self_handler_after_auth() {
2025        let (mut client, server_stream) = duplex(512);
2026        let (auth, conn) = test_auth();
2027        let server = tokio::spawn(handle_connection(
2028            server_stream,
2029            Arc::new(Router::with_default_self_handler()),
2030            auth,
2031        ));
2032        authenticate(&mut client, &conn).await;
2033        let ping = Frame::build(
2034            FrameType::Ping,
2035            Flags::new(false, Priority::Passive, false),
2036            0,
2037            0,
2038            55,
2039            Vec::new(),
2040        )
2041        .unwrap();
2042
2043        crate::write_frame(&mut client, &ping).await.unwrap();
2044        let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2045
2046        assert_eq!(response.header.ty, FrameType::Pong);
2047        assert_eq!(response.header.channel, 0);
2048        assert_eq!(response.header.corr, 55);
2049        assert!(response.body.is_empty());
2050
2051        drop(client);
2052        server.await.unwrap().unwrap();
2053    }
2054
2055    #[tokio::test]
2056    async fn unauthenticated_connection_is_rejected_before_routing() {
2057        let (mut client, server_stream) = duplex(512);
2058        let (auth, _conn) = test_auth();
2059        let registry = Arc::new(Registry::default());
2060        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2061            Arc::clone(&registry),
2062        ))));
2063        let server = tokio::spawn(handle_connection(server_stream, router, auth));
2064        let ping = Frame::build(
2065            FrameType::Ping,
2066            Flags::new(false, Priority::Passive, false),
2067            0,
2068            0,
2069            66,
2070            Vec::new(),
2071        )
2072        .unwrap();
2073
2074        crate::write_frame(&mut client, &ping).await.unwrap();
2075        if let Ok(Ok(Some(frame))) =
2076            tokio::time::timeout(Duration::from_millis(200), crate::read_frame(&mut client)).await
2077        {
2078            panic!("unauthenticated frame reached router: {frame:?}");
2079        }
2080
2081        let err = server.await.unwrap().unwrap_err();
2082        assert!(matches!(err, ConnectionError::Auth(_)));
2083        assert_eq!(registry.active_registration_count().unwrap(), 0);
2084    }
2085
2086    #[tokio::test]
2087    async fn over_cap_peer_queues_for_a_slot_and_authenticates_when_one_frees() {
2088        // Restart-herd contract: an over-cap pre-auth connection WAITS (bounded by
2089        // the auth deadline) instead of being reset. When the slot-holder finishes,
2090        // the queued peer must complete a normal handshake — the 2026-07-14 aft
2091        // outage was exactly a supervised child being reset out of this lottery.
2092        let (mut first_client, first_server_stream) = duplex(2048);
2093        let (mut second_client, second_server_stream) = duplex(2048);
2094        let (auth, conn) = test_auth_with_limit(1);
2095        let registry = Arc::new(Registry::default());
2096        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2097            Arc::clone(&registry),
2098        ))));
2099
2100        let first_server = tokio::spawn(handle_connection(
2101            first_server_stream,
2102            Arc::clone(&router),
2103            auth.clone(),
2104        ));
2105
2106        let second_server = tokio::spawn(handle_connection(
2107            second_server_stream,
2108            Arc::clone(&router),
2109            auth.clone(),
2110        ));
2111
2112        // The second peer must still be pending (not reset) while the slot is held.
2113        tokio::time::sleep(Duration::from_millis(50)).await;
2114        assert!(
2115            !second_server.is_finished(),
2116            "queued peer must not be reset"
2117        );
2118
2119        // First peer completes its handshake, freeing the slot; the queued second
2120        // peer then authenticates normally.
2121        authenticate(&mut first_client, &conn).await;
2122        authenticate(&mut second_client, &conn).await;
2123
2124        drop(first_client);
2125        drop(second_client);
2126        let _ = first_server.await;
2127        let _ = second_server.await;
2128        assert_eq!(registry.active_registration_count().unwrap(), 0);
2129    }
2130
2131    #[tokio::test]
2132    async fn over_cap_peer_is_rejected_when_no_slot_frees_within_deadline() {
2133        // The deadline stays the DoS bound: if no slot frees, the queued peer is
2134        // rejected at the deadline with a closed stream. The slot is held DIRECTLY
2135        // (not by another connection) so nothing can free it mid-test — a squatting
2136        // connection's own auth deadline would release the slot at exactly the
2137        // waiter's timeout, making the outcome racy.
2138        let (mut second_client, second_server_stream) = duplex(512);
2139        let (auth, conn) = test_auth_with_limit(1);
2140        let registry = Arc::new(Registry::default());
2141        let router = Arc::new(Router::with_control_handler(Arc::new(ControlHandler::new(
2142            Arc::clone(&registry),
2143        ))));
2144
2145        let held_slot = auth
2146            .unauthenticated
2147            .clone()
2148            .try_acquire_owned()
2149            .expect("sole pre-auth slot");
2150
2151        let second_server = tokio::spawn(handle_connection(
2152            second_server_stream,
2153            Arc::clone(&router),
2154            auth.clone(),
2155        ));
2156        let second_err = tokio::time::timeout(TEST_DEADLINE * 2, second_server)
2157            .await
2158            .expect("capacity reject should settle at the deadline")
2159            .expect("second connection task should not panic")
2160            .expect_err("queued peer must be rejected when no slot frees");
2161        drop(held_slot);
2162        assert!(matches!(
2163            second_err,
2164            ConnectionError::UnauthenticatedCapacity
2165        ));
2166        let mut closed = [0u8; 1];
2167        assert_eq!(
2168            second_client.read(&mut closed).await.unwrap(),
2169            0,
2170            "capacity-rejected peer should observe a closed stream"
2171        );
2172        assert_eq!(registry.active_registration_count().unwrap(), 0);
2173
2174        let (mut authed_client, authed_server_stream) = duplex(2048);
2175        let authed_server = tokio::spawn(handle_connection(
2176            authed_server_stream,
2177            Arc::clone(&router),
2178            auth,
2179        ));
2180        authenticate(&mut authed_client, &conn).await;
2181        let ping = Frame::build(
2182            FrameType::Ping,
2183            Flags::new(false, Priority::Passive, false),
2184            0,
2185            0,
2186            77,
2187            Vec::new(),
2188        )
2189        .unwrap();
2190        crate::write_frame(&mut authed_client, &ping).await.unwrap();
2191        let pong = crate::read_frame(&mut authed_client)
2192            .await
2193            .unwrap()
2194            .unwrap();
2195        assert_eq!(pong.header.ty, FrameType::Pong);
2196        assert_eq!(pong.header.channel, 0);
2197        assert_eq!(pong.header.corr, 77);
2198        assert_eq!(registry.active_registration_count().unwrap(), 0);
2199
2200        drop(authed_client);
2201        authed_server.await.unwrap().unwrap();
2202    }
2203
2204    #[tokio::test]
2205    async fn bind_ack_during_partial_frame_preserves_next_request() {
2206        use subc_control::ClientControlRequest;
2207        use subc_protocol::{
2208            manifest::{
2209                Concurrency, ExecutionMode, IdentityScope, ModuleManifest, ProviderRole, Tool,
2210            },
2211            session::{ModuleControlRequest, ModuleControlResponse},
2212            BindIdentity, ModuleHelloBody, RouteTarget,
2213        };
2214
2215        let mut configured_router = Router::with_default_self_handler();
2216        configured_router.register_backend(7, EchoBackend).unwrap();
2217        let router = Arc::new(configured_router);
2218        let (auth, conn) = test_auth();
2219        let (mut module, module_stream) = duplex(4096);
2220        let module_server = tokio::spawn(handle_connection(
2221            module_stream,
2222            Arc::clone(&router),
2223            auth.clone(),
2224        ));
2225        authenticate(&mut module, &conn).await;
2226        let manifest = ModuleManifest::builder("frame-test", "0.1.0")
2227            .protocol_ver(PROTOCOL_VERSION)
2228            .provides(vec![ProviderRole::ToolProvider {
2229                tools: vec![Tool {
2230                    name: "read".into(),
2231                    description: None,
2232                    execution_mode: ExecutionMode::Pure,
2233                    schema: serde_json::json!({"type": "object"}),
2234                }],
2235                identity_scope: vec![IdentityScope::Project, IdentityScope::Session],
2236                concurrency: Concurrency::ModuleManaged,
2237                emits_push: true,
2238                sub_supervises: true,
2239            }])
2240            .build();
2241        let hello = Frame::build(
2242            FrameType::Hello,
2243            Flags::new(false, Priority::Passive, false),
2244            0,
2245            0,
2246            1,
2247            serde_json::to_vec(&ModuleHelloBody {
2248                manifest,
2249                protocol_ver: PROTOCOL_VERSION,
2250                control_ops: None,
2251                launch_nonce: None,
2252            })
2253            .unwrap(),
2254        )
2255        .unwrap();
2256        crate::write_frame(&mut module, &hello).await.unwrap();
2257        assert_eq!(
2258            read_frame(&mut module).await.unwrap().unwrap().header.ty,
2259            FrameType::HelloAck
2260        );
2261
2262        let (mut client, client_stream) = duplex(4096);
2263        let client_server = tokio::spawn(handle_connection(client_stream, router, auth));
2264        authenticate(&mut client, &conn).await;
2265        let open = Frame::build(
2266            FrameType::Request,
2267            Flags::new(false, Priority::Passive, false),
2268            0,
2269            0,
2270            2,
2271            serde_json::to_vec(&ClientControlRequest::RouteOpen {
2272                target: RouteTarget::ToolProvider {
2273                    module_id: "frame-test".into(),
2274                },
2275                identity: BindIdentity::new(std::env::current_dir().unwrap(), "unit", "session"),
2276                consumer_identity: None,
2277                consumer_capabilities: None,
2278                role_versions: None,
2279                admission_facts: None,
2280                scope: None,
2281            })
2282            .unwrap(),
2283        )
2284        .unwrap();
2285        crate::write_frame(&mut client, &open).await.unwrap();
2286        let bind = timeout(TEST_DEADLINE, read_frame(&mut module))
2287            .await
2288            .unwrap()
2289            .unwrap()
2290            .unwrap();
2291        assert!(matches!(
2292            serde_json::from_slice::<ModuleControlRequest>(&bind.body).unwrap(),
2293            ModuleControlRequest::RouteBind { .. }
2294        ));
2295
2296        let ping = request(7, 3, b"partial-frame-body");
2297        client.write_all(&ping.header.encode()).await.unwrap();
2298        // Give the connection reader time to consume the header while the bind is pending.
2299        tokio::time::sleep(Duration::from_millis(30)).await;
2300        let ack = Frame::build(
2301            FrameType::Response,
2302            Flags::new(false, Priority::Passive, false),
2303            0,
2304            0,
2305            bind.header.corr,
2306            serde_json::to_vec(&ModuleControlResponse::RouteBindAck {}).unwrap(),
2307        )
2308        .unwrap();
2309        crate::write_frame(&mut module, &ack).await.unwrap();
2310        let opened = timeout(TEST_DEADLINE, read_frame(&mut client))
2311            .await
2312            .unwrap()
2313            .unwrap();
2314        if opened.is_none() {
2315            panic!("client closed: {:?}", client_server.await);
2316        }
2317        let opened = opened.unwrap();
2318        assert_eq!(opened.header.corr, 2);
2319        client.write_all(&ping.body).await.unwrap();
2320        let pong = timeout(TEST_DEADLINE, read_frame(&mut client))
2321            .await
2322            .expect("partial frame must reach the router after the bind ack")
2323            .expect("frame must decode")
2324            .expect("connection must remain open");
2325        assert_eq!(pong.header.ty, FrameType::Response);
2326        assert_eq!(pong.header.corr, 3);
2327        assert_eq!(pong.body, ping.body);
2328        drop(client);
2329        drop(module);
2330        client_server.await.unwrap().unwrap();
2331        let _ = module_server.await.unwrap();
2332    }
2333
2334    #[tokio::test]
2335    async fn full_module_egress_health_probe_does_not_block_same_client_other_route() {
2336        use crate::ConnectionId;
2337        use subc_control::{ClientControlRequest, ClientControlResponse};
2338        use subc_protocol::{
2339            manifest::{
2340                Concurrency, ExecutionMode, IdentityScope, ModuleManifest, ProviderRole, Tool,
2341            },
2342            session::ModuleControlResponse,
2343            BindIdentity, ModuleHelloBody, RouteTarget,
2344        };
2345
2346        let probe_timeout = Duration::from_millis(100);
2347        let handler = Arc::new(
2348            ControlHandler::new(Arc::new(Registry::default()))
2349                .with_health_probe_timeout(probe_timeout),
2350        );
2351        let router = Arc::new(Router::with_control_handler(Arc::clone(&handler)));
2352        let hello = |name: &str| {
2353            Frame::build(
2354                FrameType::Hello,
2355                Flags::new(false, Priority::Passive, false),
2356                0,
2357                0,
2358                1,
2359                serde_json::to_vec(&ModuleHelloBody {
2360                    manifest: ModuleManifest::builder(name, "0.1.0")
2361                        .protocol_ver(PROTOCOL_VERSION)
2362                        .provides(vec![ProviderRole::ToolProvider {
2363                            tools: vec![Tool {
2364                                name: "read".into(),
2365                                description: None,
2366                                execution_mode: ExecutionMode::Pure,
2367                                schema: serde_json::json!({"type": "object"}),
2368                            }],
2369                            identity_scope: vec![IdentityScope::Project, IdentityScope::Session],
2370                            concurrency: Concurrency::ModuleManaged,
2371                            emits_push: false,
2372                            sub_supervises: false,
2373                        }])
2374                        .build(),
2375                    protocol_ver: PROTOCOL_VERSION,
2376                    control_ops: Some(vec!["health.check".to_owned()]),
2377                    launch_nonce: None,
2378                })
2379                .unwrap(),
2380            )
2381            .unwrap()
2382        };
2383        let (blocked_tx, mut blocked_rx) = mpsc::channel(1);
2384        let blocked_ctx = RouteCtx {
2385            connection_id: ConnectionId::new(90001),
2386            egress: FrameSink::new(blocked_tx),
2387        };
2388        handler
2389            .handle_control_frame(&blocked_ctx, hello("blocked"))
2390            .await
2391            .unwrap();
2392        assert_eq!(
2393            blocked_rx.try_recv().unwrap().header.ty,
2394            FrameType::HelloAck
2395        );
2396        let filler = request(0, 99, b"queue filler");
2397        blocked_ctx.egress.try_send(filler.clone()).unwrap();
2398        assert!(
2399            blocked_ctx.egress.try_send(filler).is_err(),
2400            "module queue must actually be full"
2401        );
2402
2403        let (healthy_tx, mut healthy_rx) = mpsc::channel(8);
2404        let healthy_ctx = RouteCtx {
2405            connection_id: ConnectionId::new(90002),
2406            egress: FrameSink::new(healthy_tx),
2407        };
2408        handler
2409            .handle_control_frame(&healthy_ctx, hello("healthy"))
2410            .await
2411            .unwrap();
2412        assert_eq!(
2413            healthy_rx.try_recv().unwrap().header.ty,
2414            FrameType::HelloAck
2415        );
2416        let (auth, conn) = test_auth();
2417        let (mut client, client_stream) = duplex(4096);
2418        let client_server =
2419            tokio::spawn(handle_connection(client_stream, Arc::clone(&router), auth));
2420        authenticate(&mut client, &conn).await;
2421        let control_request = |corr, body: ClientControlRequest| {
2422            Frame::build(
2423                FrameType::Request,
2424                Flags::new(false, Priority::Interactive, false),
2425                0,
2426                0,
2427                corr,
2428                serde_json::to_vec(&body).unwrap(),
2429            )
2430            .unwrap()
2431        };
2432        crate::write_frame(
2433            &mut client,
2434            &control_request(
2435                2,
2436                ClientControlRequest::RouteOpen {
2437                    target: RouteTarget::ToolProvider {
2438                        module_id: "healthy".into(),
2439                    },
2440                    identity: BindIdentity::new(
2441                        std::env::current_dir().unwrap(),
2442                        "unit",
2443                        "session",
2444                    ),
2445                    consumer_identity: None,
2446                    consumer_capabilities: None,
2447                    role_versions: None,
2448                    admission_facts: None,
2449                    scope: None,
2450                },
2451            ),
2452        )
2453        .await
2454        .unwrap();
2455        let bind = timeout(TEST_DEADLINE, healthy_rx.recv())
2456            .await
2457            .unwrap()
2458            .unwrap();
2459        handler
2460            .handle_control_frame(
2461                &healthy_ctx,
2462                Frame::build(
2463                    FrameType::Response,
2464                    Flags::new(false, Priority::Passive, false),
2465                    0,
2466                    0,
2467                    bind.header.corr,
2468                    serde_json::to_vec(&ModuleControlResponse::RouteBindAck {}).unwrap(),
2469                )
2470                .unwrap(),
2471            )
2472            .await
2473            .unwrap();
2474        let opened = timeout(TEST_DEADLINE, read_frame(&mut client))
2475            .await
2476            .unwrap()
2477            .unwrap()
2478            .unwrap();
2479        let (channel, epoch) =
2480            match serde_json::from_slice::<ClientControlResponse>(&opened.body).unwrap() {
2481                ClientControlResponse::RouteOpen {
2482                    route_channel,
2483                    route_epoch,
2484                } => (route_channel, route_epoch),
2485                other => panic!("expected a healthy module route, got {other:?}"),
2486            };
2487
2488        let probe = control_request(
2489            3,
2490            ClientControlRequest::SupervisorHealthProbe {
2491                module_id: "blocked".into(),
2492            },
2493        );
2494        let mut ping = request(channel, 4, b"healthy request");
2495        ping.header.epoch = epoch;
2496        crate::write_frame(&mut client, &probe).await.unwrap();
2497        crate::write_frame(&mut client, &ping).await.unwrap();
2498        timeout(probe_timeout + Duration::from_secs(1), async {
2499            let timed_out = read_frame(&mut client).await.unwrap().unwrap();
2500            assert_eq!(timed_out.header.corr, 3);
2501            assert_eq!(timed_out.header.ty, FrameType::Error);
2502            let error: ErrorBody = serde_json::from_slice(&timed_out.body).unwrap();
2503            assert_eq!(error.code, "module_timeout");
2504            let forwarded = healthy_rx.recv().await.unwrap();
2505            assert_eq!(forwarded.header.corr, ping.header.corr);
2506            assert_eq!(forwarded.body, ping.body);
2507            let reply = Frame::build(
2508                FrameType::Response,
2509                ping.header.flags,
2510                forwarded.header.channel,
2511                forwarded.header.epoch,
2512                forwarded.header.corr,
2513                b"healthy response".to_vec(),
2514            )
2515            .unwrap();
2516            router
2517                .route_for_connection(&healthy_ctx, reply)
2518                .await
2519                .unwrap();
2520            let pong = read_frame(&mut client).await.unwrap().unwrap();
2521            assert_eq!(pong.header.ty, FrameType::Response);
2522            assert_eq!(pong.header.channel, channel);
2523            assert_eq!(pong.header.epoch, epoch);
2524            assert_eq!(pong.header.corr, 4);
2525            assert_eq!(pong.body, b"healthy response");
2526        })
2527        .await
2528        .expect(
2529            "the same client's healthy route must answer within the probe deadline plus margin",
2530        );
2531        assert_eq!(
2532            blocked_rx.len(),
2533            1,
2534            "the blocked module must remain undrained"
2535        );
2536        assert_eq!(blocked_rx.try_recv().unwrap().header.corr, 99);
2537        assert!(
2538            blocked_rx.try_recv().is_err(),
2539            "a timed-out probe must not be enqueued later"
2540        );
2541        drop(client);
2542        client_server.await.unwrap().unwrap();
2543    }
2544
2545    #[tokio::test]
2546    async fn aborted_accept_does_not_end_listener() {
2547        let listener = Arc::new(TcpListener::bind("127.0.0.1:0").await.unwrap());
2548        let addr = listener.local_addr().unwrap();
2549        let (auth, conn) = test_auth();
2550        let mut attempts = 0;
2551        let server = tokio::spawn(serve_listener_with_accept(
2552            Some(addr),
2553            echo_router(),
2554            auth,
2555            move || {
2556                attempts += 1;
2557                let result = if attempts == 1 {
2558                    Some(io::Error::from(io::ErrorKind::ConnectionAborted))
2559                } else {
2560                    None
2561                };
2562                let listener = Arc::clone(&listener);
2563                async move {
2564                    match result {
2565                        Some(err) => Err(err),
2566                        None => listener.accept().await,
2567                    }
2568                }
2569            },
2570        ));
2571        let mut client = tokio::net::TcpStream::connect(addr).await.unwrap();
2572        authenticate(&mut client, &conn).await;
2573        let ping = Frame::build(
2574            FrameType::Ping,
2575            Flags::new(false, Priority::Passive, false),
2576            0,
2577            0,
2578            77,
2579            Vec::new(),
2580        )
2581        .unwrap();
2582        crate::write_frame(&mut client, &ping).await.unwrap();
2583        let pong = timeout(TEST_DEADLINE, read_frame(&mut client))
2584            .await
2585            .unwrap()
2586            .unwrap()
2587            .unwrap();
2588        assert_eq!(pong.header.ty, FrameType::Pong);
2589        assert!(
2590            !server.is_finished(),
2591            "a temporary accept failure must not stop the listener"
2592        );
2593        server.abort();
2594    }
2595
2596    #[tokio::test]
2597    async fn exhausted_accept_backs_off_then_serves_connection() {
2598        let listener = Arc::new(TcpListener::bind("127.0.0.1:0").await.unwrap());
2599        let addr = listener.local_addr().unwrap();
2600        let (auth, conn) = test_auth();
2601        let mut attempts = 0;
2602        let server = tokio::spawn(serve_listener_with_accept(
2603            Some(addr),
2604            echo_router(),
2605            auth,
2606            move || {
2607                attempts += 1;
2608                // The platform's "too many open files" code: EMFILE on Unix,
2609                // WSAEMFILE on Windows. A bare 24 is ERROR_BAD_LENGTH on Windows.
2610                #[cfg(unix)]
2611                let emfile = rustix::io::Errno::MFILE.raw_os_error();
2612                #[cfg(windows)]
2613                let emfile = 10024;
2614                let error = (attempts == 1).then(|| io::Error::from_raw_os_error(emfile));
2615                let listener = Arc::clone(&listener);
2616                async move {
2617                    match error {
2618                        Some(err) => Err(err),
2619                        None => listener.accept().await,
2620                    }
2621                }
2622            },
2623        ));
2624        let started = Instant::now();
2625        let mut client = tokio::net::TcpStream::connect(addr).await.unwrap();
2626        authenticate(&mut client, &conn).await;
2627        assert!(
2628            started.elapsed() >= Duration::from_millis(50),
2629            "fd exhaustion must back off before retrying"
2630        );
2631        assert!(!server.is_finished());
2632        server.abort();
2633    }
2634
2635    #[tokio::test]
2636    async fn fatal_accept_error_still_stops_listener() {
2637        let (auth, _) = test_auth();
2638        let err = serve_listener_with_accept(None, echo_router(), auth, || async {
2639            Err(io::Error::from(io::ErrorKind::PermissionDenied))
2640        })
2641        .await
2642        .unwrap_err();
2643        assert!(
2644            matches!(err, ServerError::Accept { source, .. } if source.kind() == io::ErrorKind::PermissionDenied)
2645        );
2646    }
2647
2648    #[tokio::test]
2649    async fn serve_listeners_with_no_listeners_returns_typed_error() {
2650        let (auth, _conn) = test_auth();
2651        let err = serve_listeners(Vec::new(), echo_router(), auth)
2652            .await
2653            .expect_err("empty listener set must fail loudly");
2654        assert!(matches!(err, ServerError::NoListeners));
2655    }
2656
2657    #[tokio::test]
2658    async fn malformed_header_returns_typed_error_no_panic() {
2659        let (mut client, server_stream) = duplex(128);
2660        let (auth, conn) = test_auth();
2661        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2662        authenticate(&mut client, &conn).await;
2663        let mut header = [0u8; HEADER_LEN];
2664        header[4] = PROTOCOL_VERSION;
2665        header[5] = 250;
2666
2667        client.write_all(&header).await.unwrap();
2668        drop(client);
2669
2670        let err = server.await.unwrap().unwrap_err();
2671        assert!(matches!(
2672            err,
2673            ConnectionError::FrameIo(FrameIoError::DecodeHeader(DecodeError::UnknownFrameType {
2674                byte: 250
2675            }))
2676        ));
2677    }
2678
2679    #[tokio::test]
2680    async fn truncated_body_returns_typed_error_no_panic() {
2681        let (mut client, server_stream) = duplex(128);
2682        let (auth, conn) = test_auth();
2683        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2684        authenticate(&mut client, &conn).await;
2685        let frame = request(7, 8, b"abcd");
2686
2687        client.write_all(&frame.header.encode()).await.unwrap();
2688        client.write_all(b"ab").await.unwrap();
2689        drop(client);
2690
2691        let err = server.await.unwrap().unwrap_err();
2692        assert!(matches!(
2693            err,
2694            ConnectionError::FrameIo(FrameIoError::UnexpectedEof {
2695                stage: ReadStage::Body,
2696                expected: 4,
2697                actual: 2
2698            })
2699        ));
2700    }
2701
2702    #[tokio::test]
2703    async fn unknown_channel_is_returned_as_error_frame_and_connection_continues() {
2704        let (mut client, server_stream) = duplex(1024);
2705        let (auth, conn) = test_auth();
2706        let server = tokio::spawn(handle_connection(server_stream, echo_router(), auth));
2707        authenticate(&mut client, &conn).await;
2708        let unknown = request(42, 10, b"lost");
2709        let known = request(7, 11, b"still-routes");
2710
2711        crate::write_frame(&mut client, &unknown).await.unwrap();
2712        crate::write_frame(&mut client, &known).await.unwrap();
2713
2714        let error = crate::read_frame(&mut client).await.unwrap().unwrap();
2715        assert_eq!(error.header.ty, FrameType::Error);
2716        assert_eq!(error.header.channel, 42);
2717        assert_eq!(error.header.corr, 10);
2718        let error_body: ErrorBody = serde_json::from_slice(&error.body).unwrap();
2719        assert_eq!(error_body.code, "unknown_channel");
2720
2721        let response = crate::read_frame(&mut client).await.unwrap().unwrap();
2722        assert_eq!(response.header.ty, FrameType::Response);
2723        assert_eq!(response.header.channel, 7);
2724        assert_eq!(response.header.corr, 11);
2725        assert_eq!(response.body, b"still-routes");
2726
2727        drop(client);
2728        server.await.unwrap().unwrap();
2729    }
2730}