Skip to main content

subc_daemon/
server.rs

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