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