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