1use std::{
2 collections::HashMap,
3 error::Error,
4 fmt,
5 sync::{
6 atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering},
7 Arc, Mutex,
8 },
9 time::{Duration, Instant},
10};
11
12use subc_protocol::{error_codes, ErrorBody, Flags, FrameType, Priority};
13use tokio::sync::{mpsc, Notify};
14use tracing::{debug, warn};
15
16use crate::{
17 control::ControlHandler,
18 forwarding::{
19 principal_label, CloseReason, ConnectionCloseReceiver, DataRoute, DataRouteState,
20 ForwardingError, ForwardingTable, RouteBinding, RouteRelease, UndeliveredFrame,
21 },
22 registry::ConnectionId,
23 DaemonCounters, Frame, FrameBuildError,
24};
25
26#[derive(Debug)]
35pub struct OutboundFrame {
36 pub frame: Frame,
37 pub enqueued_at: std::time::Instant,
38 pub(crate) flushed: Option<tokio::sync::oneshot::Sender<()>>,
39 pub(crate) charge: Option<EgressCharge>,
44}
45
46impl OutboundFrame {
47 fn charged(frame: Frame, charge: EgressCharge) -> Self {
48 Self {
49 frame,
50 enqueued_at: charge.enqueued_at,
51 flushed: None,
52 charge: Some(charge),
53 }
54 }
55}
56
57fn queued_frame_bytes(frame: &Frame) -> usize {
60 subc_protocol::HEADER_LEN + frame.body.len()
61}
62
63#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub(crate) struct EgressBacklog {
67 pub queued_bytes: usize,
68 pub queued_frames: usize,
69 pub oldest_age: Option<Duration>,
76}
77
78#[derive(Debug)]
83struct EgressAccounting {
84 ingress_seen: AtomicBool,
87 ingress_terminal: AtomicBool,
88 egress_terminal: AtomicBool,
89 egress_stopped: Notify,
90 byte_budget: usize,
91 queued_bytes: AtomicUsize,
92 queued_frames: AtomicUsize,
93 time_base: Instant,
95 oldest_enqueued_nanos: AtomicU64,
98 waiters: AtomicUsize,
101 freed: Notify,
104 client_delivery_closed: AtomicBool,
105 client_delivery_stopped: Notify,
106 #[cfg(test)]
107 retire_after_reserve: AtomicBool,
108}
109
110impl EgressAccounting {
111 fn new(byte_budget: usize) -> Self {
112 Self {
113 ingress_seen: AtomicBool::new(false),
114 ingress_terminal: AtomicBool::new(false),
115 egress_terminal: AtomicBool::new(false),
116 egress_stopped: Notify::new(),
117 byte_budget,
118 queued_bytes: AtomicUsize::new(0),
119 queued_frames: AtomicUsize::new(0),
120 time_base: tokio::time::Instant::now().into_std(),
121 oldest_enqueued_nanos: AtomicU64::new(0),
122 waiters: AtomicUsize::new(0),
123 freed: Notify::new(),
124 client_delivery_closed: AtomicBool::new(false),
125 client_delivery_stopped: Notify::new(),
126 #[cfg(test)]
127 retire_after_reserve: AtomicBool::new(false),
128 }
129 }
130
131 fn stamp(&self, at: Instant) -> u64 {
132 (at.saturating_duration_since(self.time_base).as_nanos() as u64).saturating_add(1)
133 }
134
135 fn try_charge(self: &Arc<Self>, bytes: usize) -> Option<EgressCharge> {
140 let mut current = self.queued_bytes.load(Ordering::SeqCst);
143 loop {
144 if current != 0 && current.saturating_add(bytes) > self.byte_budget {
145 return None;
146 }
147 match self.queued_bytes.compare_exchange_weak(
148 current,
149 current + bytes,
150 Ordering::SeqCst,
151 Ordering::SeqCst,
152 ) {
153 Ok(_) => return Some(self.record(bytes)),
154 Err(actual) => current = actual,
155 }
156 }
157 }
158
159 fn charge_unconditionally(self: &Arc<Self>, bytes: usize) -> EgressCharge {
162 self.queued_bytes.fetch_add(bytes, Ordering::SeqCst);
163 self.record(bytes)
164 }
165
166 fn record(self: &Arc<Self>, bytes: usize) -> EgressCharge {
167 let enqueued_at = tokio::time::Instant::now().into_std();
168 let stamp = self.stamp(enqueued_at);
169 if self.queued_frames.fetch_add(1, Ordering::AcqRel) == 0 {
170 self.oldest_enqueued_nanos.store(stamp, Ordering::Release);
173 }
174 EgressCharge {
175 accounting: Arc::clone(self),
176 bytes,
177 stamp,
178 enqueued_at,
179 }
180 }
181
182 fn taken_by_writer(&self, stamp: u64) {
184 self.oldest_enqueued_nanos.store(stamp, Ordering::Release);
185 }
186
187 fn release(&self, bytes: usize, stamp: u64) {
188 self.queued_bytes.fetch_sub(bytes, Ordering::SeqCst);
189 if self.queued_frames.fetch_sub(1, Ordering::AcqRel) == 1 {
190 let _ = self.oldest_enqueued_nanos.compare_exchange(
193 stamp,
194 0,
195 Ordering::AcqRel,
196 Ordering::Acquire,
197 );
198 }
199 if self.waiters.load(Ordering::SeqCst) != 0 {
200 self.freed.notify_waiters();
201 }
202 }
203
204 fn backlog(&self) -> EgressBacklog {
205 let queued_frames = self.queued_frames.load(Ordering::Acquire);
206 let stamp = self.oldest_enqueued_nanos.load(Ordering::Acquire);
207 let oldest_age = (queued_frames != 0 && stamp != 0).then(|| {
208 let enqueued = self.time_base + Duration::from_nanos(stamp - 1);
209 tokio::time::Instant::from_std(enqueued).elapsed()
210 });
211 EgressBacklog {
212 queued_bytes: self.queued_bytes.load(Ordering::Acquire),
213 queued_frames,
214 oldest_age,
215 }
216 }
217}
218
219#[derive(Debug)]
222pub(crate) struct EgressCharge {
223 accounting: Arc<EgressAccounting>,
224 bytes: usize,
225 stamp: u64,
226 enqueued_at: Instant,
227}
228
229impl EgressCharge {
230 pub(crate) fn taken_by_writer(&self) {
233 self.accounting.taken_by_writer(self.stamp);
234 }
235}
236
237impl Drop for EgressCharge {
238 fn drop(&mut self) {
239 self.accounting.release(self.bytes, self.stamp);
240 }
241}
242
243#[derive(Debug)]
249pub(crate) struct EgressPermit {
250 permit: mpsc::OwnedPermit<OutboundFrame>,
251 accounting: Arc<EgressAccounting>,
252}
253
254impl EgressPermit {
255 pub(crate) fn send(self, frame: Frame) -> bool {
259 if self.accounting.egress_terminal.load(Ordering::Acquire) {
260 return true;
261 }
262 let charge = self
263 .accounting
264 .charge_unconditionally(queued_frame_bytes(&frame));
265 let sender = self.permit.send(OutboundFrame::charged(frame, charge));
266 sender.is_closed()
267 }
268}
269
270impl std::ops::Deref for OutboundFrame {
273 type Target = Frame;
274
275 fn deref(&self) -> &Frame {
276 &self.frame
277 }
278}
279
280#[cfg(test)]
283pub(crate) mod test_log {
284 use std::{
285 io::Write,
286 sync::{Arc, Mutex, OnceLock},
287 };
288
289 #[derive(Clone)]
290 struct TestLogWriter(Arc<Mutex<Vec<u8>>>);
291
292 impl Write for TestLogWriter {
293 fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
294 self.0
295 .lock()
296 .expect("test log capture is not poisoned")
297 .extend(buffer);
298 Ok(buffer.len())
299 }
300
301 fn flush(&mut self) -> std::io::Result<()> {
302 Ok(())
303 }
304 }
305
306 pub(crate) fn log_capture(
307 level: tracing::Level,
308 ) -> (Arc<Mutex<Vec<u8>>>, tracing::dispatcher::DefaultGuard) {
309 static INTEREST_ANCHOR: OnceLock<tracing::Dispatch> = OnceLock::new();
316 INTEREST_ANCHOR.get_or_init(|| tracing::Dispatch::new(tracing_subscriber::registry()));
317 let output = Arc::new(Mutex::new(Vec::new()));
318 let writer = Arc::clone(&output);
319 let subscriber = tracing_subscriber::fmt()
320 .with_max_level(level)
321 .with_ansi(false)
322 .without_time()
323 .with_target(false)
324 .with_writer(move || TestLogWriter(Arc::clone(&writer)))
325 .finish();
326 let guard = tracing::subscriber::set_default(subscriber);
327 (output, guard)
328 }
329
330 pub(crate) fn captured_logs(output: &Arc<Mutex<Vec<u8>>>) -> String {
331 String::from_utf8(
332 output
333 .lock()
334 .expect("test log capture is not poisoned")
335 .clone(),
336 )
337 .expect("tracing output is UTF-8")
338 }
339
340 #[cfg(test)]
341 mod tests {
342 use super::*;
343
344 fn emit_capture_probe(source: &str) {
345 tracing::error!(source, "parallel capture probe");
346 }
347
348 #[test]
349 fn parallel_callsite_registration_keeps_the_test_capture_enabled() {
350 let (output, _guard) = log_capture(tracing::Level::ERROR);
351 std::thread::spawn(|| emit_capture_probe("other-thread"))
354 .join()
355 .expect("unsubscribed thread exits");
356 emit_capture_probe("captured-thread");
357
358 let logs = captured_logs(&output);
359 assert!(
360 logs.contains("captured-thread"),
361 "capture was disabled: {logs}"
362 );
363 assert!(!logs.contains("other-thread"), "capture leaked: {logs}");
364 }
365 }
366}
367
368#[derive(Debug, Clone)]
376pub struct FrameSink {
377 tx: mpsc::Sender<OutboundFrame>,
378 accounting: Arc<EgressAccounting>,
379}
380
381impl FrameSink {
382 pub(crate) fn terminate_ingress(&self) {
383 self.accounting
384 .ingress_terminal
385 .store(true, Ordering::Release);
386 }
387
388 pub(crate) fn ingress_terminal(&self) -> bool {
389 self.accounting.ingress_terminal.load(Ordering::Acquire)
390 }
391
392 pub(crate) fn terminate_egress(&self) {
395 self.accounting
396 .egress_terminal
397 .store(true, Ordering::Release);
398 self.accounting.egress_stopped.notify_waiters();
399 self.accounting.freed.notify_waiters();
400 }
401
402 pub(crate) fn egress_terminal(&self) -> bool {
403 self.accounting.egress_terminal.load(Ordering::Acquire)
404 }
405
406 pub(crate) fn first_ingress_frame(&self) -> bool {
407 !self.accounting.ingress_seen.swap(true, Ordering::Relaxed)
408 }
409 pub fn new(tx: mpsc::Sender<OutboundFrame>) -> Self {
413 Self::with_byte_budget(tx, crate::server::CONNECTION_EGRESS_BYTE_BUDGET)
414 }
415
416 pub(crate) fn with_byte_budget(tx: mpsc::Sender<OutboundFrame>, byte_budget: usize) -> Self {
417 Self {
418 tx,
419 accounting: Arc::new(EgressAccounting::new(byte_budget)),
420 }
421 }
422
423 async fn charge_waiting(&self, bytes: usize) -> Option<EgressCharge> {
430 if self.egress_terminal() {
431 return None;
432 }
433 if let Some(charge) = self.accounting.try_charge(bytes) {
434 return Some(charge);
435 }
436 struct Waiting<'a>(&'a AtomicUsize);
439 impl Drop for Waiting<'_> {
440 fn drop(&mut self) {
441 self.0.fetch_sub(1, Ordering::SeqCst);
442 }
443 }
444 self.accounting.waiters.fetch_add(1, Ordering::SeqCst);
445 let _waiting = Waiting(&self.accounting.waiters);
446 loop {
447 let freed = self.accounting.freed.notified();
448 tokio::pin!(freed);
449 freed.as_mut().enable();
452 if self.egress_terminal() {
453 return None;
454 }
455 if let Some(charge) = self.accounting.try_charge(bytes) {
456 return Some(charge);
457 }
458 tokio::select! {
459 _ = &mut freed => {}
460 _ = self.tx.closed() => return None,
461 }
462 }
463 }
464
465 async fn send_outbound(&self, outbound: OutboundFrame) -> Result<bool, RouterError> {
470 let stopped = self.accounting.egress_stopped.notified();
471 tokio::pin!(stopped);
472 stopped.as_mut().enable();
473 if self.egress_terminal() {
474 return Ok(false);
475 }
476 let header = &outbound.frame.header;
477 let closed = || {
478 RouterError::backend_with_epoch(
479 header.channel,
480 header.epoch,
481 header.corr,
482 "connection writer closed",
483 )
484 };
485 let permit = tokio::select! {
486 biased;
487 _ = &mut stopped => return Ok(false),
488 permit = self.tx.reserve() => permit.map_err(|_| closed())?,
489 };
490 if self.egress_terminal() {
491 return Ok(false);
492 }
493 permit.send(outbound);
494 Ok(true)
495 }
496
497 pub async fn send(&self, frame: Frame) -> Result<(), RouterError> {
498 if self.egress_terminal() {
499 return Ok(());
500 }
501 let channel = frame.header.channel;
502 let epoch = frame.header.epoch;
503 let corr = frame.header.corr;
504 let closed =
505 || RouterError::backend_with_epoch(channel, epoch, corr, "connection writer closed");
506 let Some(charge) = self.charge_waiting(queued_frame_bytes(&frame)).await else {
507 return if self.egress_terminal() {
508 Ok(())
509 } else {
510 Err(closed())
511 };
512 };
513 self.send_outbound(OutboundFrame::charged(frame, charge))
514 .await
515 .map(|_| ())
516 }
517
518 pub async fn send_flushed(&self, frame: Frame) -> Result<(), RouterError> {
525 self.send_flushed_notifying_enqueue(frame, || {}).await
526 }
527
528 pub(crate) async fn send_flushed_notifying_enqueue(
531 &self,
532 frame: Frame,
533 queued: impl FnOnce(),
534 ) -> Result<(), RouterError> {
535 let (tx, rx) = tokio::sync::oneshot::channel();
536 let charge = self
537 .charge_waiting(queued_frame_bytes(&frame))
538 .await
539 .ok_or_else(|| RouterError::backend(0, 0, "connection writer closed"))?;
540 let mut outbound = OutboundFrame::charged(frame, charge);
541 outbound.flushed = Some(tx);
542 if !self.send_outbound(outbound).await? {
543 return Err(RouterError::backend(0, 0, "connection egress retired"));
544 }
545 queued();
546 rx.await
547 .map_err(|_| RouterError::backend(0, 0, "connection flush failed"))
548 }
549
550 pub(crate) async fn reserve_owned(&self) -> Result<EgressPermit, RouterError> {
551 let stopped = self.accounting.egress_stopped.notified();
552 tokio::pin!(stopped);
553 stopped.as_mut().enable();
554 if self.egress_terminal() {
555 return Err(RouterError::backend(0, 0, "connection egress retired"));
556 }
557 let permit = tokio::select! {
558 biased;
559 _ = &mut stopped => return Err(RouterError::backend(0, 0, "connection egress retired")),
560 permit = self.tx.clone().reserve_owned() => permit
561 .map_err(|_| RouterError::backend(0, 0, "connection writer closed"))?,
562 };
563 #[cfg(test)]
564 if self
565 .accounting
566 .retire_after_reserve
567 .swap(false, Ordering::Relaxed)
568 {
569 self.terminate_egress();
570 }
571 if self.egress_terminal() {
572 return Err(RouterError::backend(0, 0, "connection egress retired"));
573 }
574 Ok(EgressPermit {
575 permit,
576 accounting: Arc::clone(&self.accounting),
577 })
578 }
579
580 #[cfg(test)]
581 pub(crate) fn try_reserve_owned(&self) -> Result<EgressPermit, RouterError> {
582 if self.egress_terminal() {
583 return Err(RouterError::backend(0, 0, "connection egress retired"));
584 }
585 let permit = self
586 .tx
587 .clone()
588 .try_reserve_owned()
589 .map_err(|err| RouterError::backend(0, 0, err.to_string()))?;
590 Ok(EgressPermit {
591 permit,
592 accounting: Arc::clone(&self.accounting),
593 })
594 }
595
596 pub(crate) fn is_closed(&self) -> bool {
597 self.tx.is_closed()
598 }
599
600 pub(crate) fn backlog(&self) -> EgressBacklog {
602 self.accounting.backlog()
603 }
604
605 pub(crate) fn close_client_delivery(&self) {
608 self.accounting
609 .client_delivery_closed
610 .store(true, Ordering::Release);
611 self.accounting.client_delivery_stopped.notify_waiters();
612 }
613
614 async fn send_to_client(&self, frame: Frame) -> Result<(), ClientDeliveryFailure> {
617 if self.egress_terminal() {
618 return Ok(());
619 }
620 let frame_type = frame.header.ty;
621 let flags = frame.header.flags;
622 let stopped = self.accounting.client_delivery_stopped.notified();
623 tokio::pin!(stopped);
624 stopped.as_mut().enable();
625 let failure = |cause, error| ClientDeliveryFailure {
626 diagnosis: ClientDeliveryDiagnosis {
627 frame_type,
628 flags,
629 cause,
630 },
631 error,
632 };
633 let closed = || {
634 RouterError::backend_with_epoch(
635 frame.header.channel,
636 frame.header.epoch,
637 frame.header.corr,
638 "client connection closed",
639 )
640 };
641 if self
642 .accounting
643 .client_delivery_closed
644 .load(Ordering::Acquire)
645 {
646 return Err(failure("client_closed", closed()));
647 }
648 let (frame, error) = match self.try_send_owned(frame) {
649 Ok(()) => return Ok(()),
650 Err(refused) => refused,
651 };
652 if self.is_closed() {
653 return Err(failure("client_closed", error));
654 }
655 let grace = crate::server::CONNECTION_EGRESS_STALL_GRACE;
656 let age = self.backlog().oldest_age.unwrap_or_default();
657 if age > grace {
658 return Err(failure("oldest_frame_older_than_250_ms", error));
659 }
660 let result = tokio::select! {
661 biased;
662 _ = &mut stopped => return Err(failure("client_closed", error)),
663 result = tokio::time::timeout(grace.saturating_sub(age), self.send(frame)) => result,
664 };
665 match result {
666 Ok(Ok(())) => Ok(()),
667 Ok(Err(error)) => Err(failure("client_closed", error)),
668 Err(_) => Err(failure("waited_250_ms_without_room", error)),
669 }
670 }
671
672 pub(crate) fn try_send(&self, frame: Frame) -> Result<(), RouterError> {
676 self.try_send_owned(frame).map_err(|(_, error)| error)
677 }
678
679 fn try_send_owned(&self, frame: Frame) -> Result<(), (Frame, RouterError)> {
680 if self.egress_terminal() {
681 return Ok(());
682 }
683 let channel = frame.header.channel;
684 let epoch = frame.header.epoch;
685 let corr = frame.header.corr;
686 let unavailable = |why: String| {
687 RouterError::backend_with_epoch(
688 channel,
689 epoch,
690 corr,
691 format!("connection writer unavailable: {why}"),
692 )
693 };
694 let bytes = queued_frame_bytes(&frame);
695 let Some(charge) = self.accounting.try_charge(bytes) else {
696 if self.tx.is_closed() {
697 return Err((frame, unavailable("channel closed".to_string())));
698 }
699 return Err((
700 frame,
701 unavailable(format!(
702 "egress byte budget exhausted ({} queued bytes, frame of {bytes} bytes, budget {})",
703 self.accounting.queued_bytes.load(Ordering::Acquire),
704 self.accounting.byte_budget
705 )),
706 ));
707 };
708 if self.egress_terminal() {
711 return Ok(());
712 }
713 self.tx
714 .try_send(OutboundFrame::charged(frame, charge))
715 .map_err(|err| {
716 let error = unavailable(err.to_string());
717 (err.into_inner().frame, error)
718 })
719 }
720}
721
722#[derive(Debug)]
723struct ClientDeliveryFailure {
724 diagnosis: ClientDeliveryDiagnosis,
725 error: RouterError,
726}
727
728#[derive(Debug)]
730pub(crate) struct ClientDeliveryDiagnosis {
731 pub frame_type: FrameType,
732 pub flags: Flags,
733 pub cause: &'static str,
734}
735
736impl fmt::Display for ClientDeliveryFailure {
737 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
738 self.error.fmt(f)
739 }
740}
741
742const ORPHAN_ROUTE_GOODBYE_INTERVAL: Duration = Duration::from_secs(5);
754
755const ORPHAN_ROUTE_GOODBYE_PRUNE_AT: usize = 256;
762
763#[derive(Debug, Default)]
767struct OrphanGoodbyeLimiter {
768 last_sent: Mutex<HashMap<ConnectionId, HashMap<u16, tokio::time::Instant>>>,
769}
770
771impl OrphanGoodbyeLimiter {
772 fn claim(&self, connection_id: ConnectionId, channel: u16) -> bool {
775 let now = tokio::time::Instant::now();
776 let mut last_sent = self
777 .last_sent
778 .lock()
779 .unwrap_or_else(std::sync::PoisonError::into_inner);
780 let channels = last_sent.entry(connection_id).or_default();
781 if channels.get(&channel).is_some_and(|sent| {
782 now.saturating_duration_since(*sent) < ORPHAN_ROUTE_GOODBYE_INTERVAL
783 }) {
784 return false;
785 }
786 if channels.len() >= ORPHAN_ROUTE_GOODBYE_PRUNE_AT {
787 channels.retain(|_, sent| {
788 now.saturating_duration_since(*sent) < ORPHAN_ROUTE_GOODBYE_INTERVAL
789 });
790 }
791 channels.insert(channel, now);
792 true
793 }
794
795 fn forget_connection(&self, connection_id: ConnectionId) {
796 self.last_sent
797 .lock()
798 .unwrap_or_else(std::sync::PoisonError::into_inner)
799 .remove(&connection_id);
800 }
801}
802
803#[derive(Debug, Clone)]
805pub struct RouteCtx {
806 pub connection_id: ConnectionId,
807 pub egress: FrameSink,
808}
809
810#[derive(Debug, Clone)]
816pub enum Backend {
817 Echo(EchoBackend),
818 Forward(ForwardBackend),
819}
820
821impl From<EchoBackend> for Backend {
822 fn from(backend: EchoBackend) -> Self {
823 Self::Echo(backend)
824 }
825}
826
827impl From<ForwardBackend> for Backend {
828 fn from(backend: ForwardBackend) -> Self {
829 Self::Forward(backend)
830 }
831}
832
833impl Backend {
834 pub async fn handle(&self, ctx: RouteCtx, frame: Frame) -> Result<(), RouterError> {
835 match self {
836 Self::Echo(backend) => backend.handle(ctx, frame).await,
837 Self::Forward(backend) => backend.handle(ctx, frame).await,
838 }
839 }
840}
841
842pub struct Router {
863 backends: HashMap<u16, Backend>,
864 control: Arc<ControlHandler>,
865 forwarding: Arc<ForwardingTable>,
866 forward_backend: ForwardBackend,
867 counters: DaemonCounters,
868 next_connection_id: AtomicU64,
869 orphan_goodbyes: Arc<OrphanGoodbyeLimiter>,
870}
871
872impl Router {
873 pub fn with_control_handler(control: Arc<ControlHandler>) -> Self {
874 control.install_swap_promotion_observer();
877 let forwarding = control.forwarding();
878 let counters = control.counters();
879 Self {
880 backends: HashMap::new(),
881 control,
882 forwarding: Arc::clone(&forwarding),
883 forward_backend: ForwardBackend::new(forwarding),
884 counters,
885 next_connection_id: AtomicU64::new(1),
887 orphan_goodbyes: Arc::default(),
888 }
889 }
890
891 pub(crate) fn install_registration_service(self: &Arc<Self>, auth: crate::server::ServerAuth) {
894 self.control
895 .install_registration_service(Arc::downgrade(self), auth);
896 }
897
898 pub fn with_default_self_handler() -> Self {
899 Self::with_control_handler(Arc::new(ControlHandler::default()))
900 }
901
902 pub fn forwarding(&self) -> Arc<ForwardingTable> {
903 Arc::clone(&self.forwarding)
904 }
905
906 pub fn register_backend(
907 &mut self,
908 channel: u16,
909 backend: impl Into<Backend>,
910 ) -> Result<(), RouterError> {
911 self.register_backend_arc(channel, Arc::new(backend.into()))
912 }
913
914 pub(crate) fn register_backend_arc(
915 &mut self,
916 channel: u16,
917 backend: Arc<Backend>,
918 ) -> Result<(), RouterError> {
919 if channel == 0 {
920 return Err(RouterError::ReservedChannelZero);
921 }
922 if self.backends.contains_key(&channel) {
923 return Err(RouterError::DuplicateChannel { channel });
924 }
925 self.backends.insert(channel, backend.as_ref().clone());
926 Ok(())
927 }
928
929 fn record_module_frame_drop(&self, connection_id: ConnectionId) -> Result<(), RouterError> {
932 let module_id = self
933 .forwarding
934 .module_id_for_connection(connection_id)
935 .map_err(RouterError::Forwarding)?;
936 self.counters
937 .increment_module_frames_dropped_no_route(module_id.as_deref());
938 Ok(())
939 }
940
941 fn handle_orphan_module_frame(&self, ctx: &RouteCtx, frame: &Frame) -> Result<(), RouterError> {
953 let channel = frame.header.channel;
954 let epoch = frame.header.epoch;
955 let module_id = self
956 .forwarding
957 .module_id_for_connection(ctx.connection_id)
958 .map_err(RouterError::Forwarding)?;
959 self.counters
960 .increment_module_frames_dropped_no_route(module_id.as_deref());
961 if self
962 .forwarding
963 .module_route_epoch_was_allocated(ctx.connection_id, channel, epoch)
964 .map_err(RouterError::Forwarding)?
965 {
966 self.counters
967 .increment_module_frames_dropped_released_route(module_id.as_deref());
968 }
969 if frame.header.ty == FrameType::Goodbye
970 || !self.orphan_goodbyes.claim(ctx.connection_id, channel)
971 {
972 return Ok(());
973 }
974 let goodbye = Frame::build_with_version(
975 frame.header.ver,
976 FrameType::Goodbye,
977 Flags::new(false, Priority::Passive, false),
978 channel,
979 epoch,
980 0,
981 Vec::new(),
982 )
983 .map_err(RouterError::FrameBuild)?;
984 match ctx.egress.try_send(goodbye) {
985 Ok(()) => {
986 self.counters.increment_module_orphan_route_goodbyes_sent();
987 debug!(
988 connection_id = ctx.connection_id.get(),
989 module_id = module_id.as_deref().unwrap_or("unknown"),
990 channel,
991 epoch,
992 "answered module frame on a route the daemon does not hold with a route GOODBYE"
993 );
994 }
995 Err(err) => {
996 self.forwarding.warn_frame_drop(
997 ctx.connection_id,
998 channel,
999 epoch,
1000 "daemon_to_module",
1001 if ctx.egress.is_closed() {
1002 "endpoint_gone"
1003 } else {
1004 "egress_budget"
1005 },
1006 );
1007 debug!(
1008 connection_id = ctx.connection_id.get(),
1009 module_id = module_id.as_deref().unwrap_or("unknown"),
1010 channel,
1011 epoch,
1012 error = %err,
1013 "could not enqueue route GOODBYE for module frame on a route the daemon does not hold; the next such frame retries"
1014 );
1015 }
1016 }
1017 Ok(())
1018 }
1019
1020 pub fn begin_connection(&self) -> RouterConnection {
1021 let raw = self.next_connection_id.fetch_add(1, Ordering::Relaxed);
1022 let id = ConnectionId::new(raw);
1023 let close_receiver = self.forwarding.register_connection_close(id);
1024 RouterConnection {
1025 id,
1026 control_handler: Arc::clone(&self.control),
1027 forwarding: Arc::clone(&self.forwarding),
1028 close_receiver: Some(close_receiver),
1029 orphan_goodbyes: Arc::clone(&self.orphan_goodbyes),
1030 }
1031 }
1032
1033 pub(crate) fn route_open_target(&self, frame: &Frame) -> Option<String> {
1034 self.control.route_open_target(frame)
1035 }
1036
1037 pub(crate) fn record_local_connection(&self, connection: ConnectionId) {
1038 self.control.record_local_connection(connection);
1039 }
1040
1041 pub(crate) fn record_captured_peer(
1042 &self,
1043 connection: ConnectionId,
1044 peer: subc_os::local_peer::CapturedPeer,
1045 ) {
1046 self.control.record_captured_peer(connection, peer);
1047 }
1048
1049 pub(crate) fn record_caller_endpoints(
1050 &self,
1051 connection: ConnectionId,
1052 endpoints: Option<(std::net::SocketAddr, std::net::SocketAddr)>,
1053 ) {
1054 self.control.record_caller_endpoints(connection, endpoints);
1055 }
1056
1057 pub(crate) fn defers_privileged_control(&self, ctx: &RouteCtx, frame: &Frame) -> bool {
1058 self.control.defers_privileged_control(ctx, frame)
1059 }
1060
1061 pub(crate) fn defers_config_approval(&self, frame: &Frame) -> bool {
1062 self.control.defers_config_approval(frame)
1063 }
1064
1065 pub(crate) fn reserve_config_approval(
1066 &self,
1067 ctx: &RouteCtx,
1068 frame: &Frame,
1069 ) -> Result<
1070 Option<crate::config_gate::runtime::ApprovalRequestGuard>,
1071 crate::config_gate::GateError,
1072 > {
1073 self.control.reserve_config_approval(ctx, frame)
1074 }
1075
1076 pub(crate) fn route_open_capacity_refusal(
1077 &self,
1078 ctx: &RouteCtx,
1079 frame: &Frame,
1080 target_module_id: &str,
1081 in_flight: usize,
1082 limit: usize,
1083 ) -> Result<Frame, RouterError> {
1084 self.control
1085 .route_open_capacity_refusal(ctx, frame, target_module_id, in_flight, limit)
1086 }
1087
1088 pub async fn route_for_connection(
1089 &self,
1090 ctx: &RouteCtx,
1091 frame: Frame,
1092 ) -> Result<(), RouterError> {
1093 self.route_for_connection_started(ctx, frame, None).await
1094 }
1095
1096 pub(crate) async fn observe_connection_wait<F: std::future::Future>(
1097 &self,
1098 ctx: &RouteCtx,
1099 kind: &'static str,
1100 future: F,
1101 ) -> F::Output {
1102 self.counters
1103 .observe_reader_wait(
1104 || {
1105 let module = self
1106 .forwarding
1107 .module_id_for_connection(ctx.connection_id)
1108 .ok()
1109 .flatten();
1110 let principal = if module.is_some() { "module" } else { "direct" };
1111 (
1112 module.unwrap_or_else(|| crate::observability::CONTROL_WAIT_BUCKET.into()),
1113 principal.into(),
1114 )
1115 },
1116 kind,
1117 future,
1118 )
1119 .await
1120 }
1121
1122 pub(crate) async fn route_for_connection_started(
1123 &self,
1124 ctx: &RouteCtx,
1125 frame: Frame,
1126 dispatch_started_at: Option<Instant>,
1127 ) -> Result<(), RouterError> {
1128 let first = ctx.egress.first_ingress_frame();
1130 self.route_for_connection_ingress(ctx, frame, dispatch_started_at, first)
1131 .await
1132 }
1133
1134 pub(crate) async fn route_for_connection_ingress(
1135 &self,
1136 ctx: &RouteCtx,
1137 frame: Frame,
1138 dispatch_started_at: Option<Instant>,
1139 first: bool,
1140 ) -> Result<(), RouterError> {
1141 if ctx.egress.ingress_terminal() {
1142 return Ok(());
1143 }
1144 let channel = frame.header.channel;
1145 let epoch = frame.header.epoch;
1146 let corr = frame.header.corr;
1147 if channel == 0 {
1148 debug!(
1149 connection_id = ctx.connection_id.get(),
1150 corr,
1151 frame_type = ?frame.header.ty,
1152 "routing control frame"
1153 );
1154 let dispatch_started_at = (frame.header.ty == FrameType::Request)
1161 .then(|| dispatch_started_at.unwrap_or_else(Instant::now));
1162 let responses = self
1163 .control
1164 .handle_control_frame_ingress(ctx, frame, dispatch_started_at, first)
1165 .await?;
1166 for response in responses {
1167 if let Some(view) = self
1168 .control
1169 .config_desktop_review_response(ctx.connection_id, &response)
1170 {
1171 self.observe_connection_wait(
1172 ctx,
1173 "reply_egress",
1174 self.control
1175 .deliver_config_desktop_review(ctx, response, view),
1176 )
1177 .await?;
1178 continue;
1179 }
1180 self.observe_connection_wait(ctx, "reply_egress", ctx.egress.send(response))
1181 .await?;
1182 }
1183 return Ok(());
1184 }
1185
1186 let data_route = self
1187 .forwarding
1188 .lookup_data_route(ctx.connection_id, channel, epoch)
1189 .map_err(RouterError::Forwarding)?;
1190
1191 match data_route {
1192 DataRoute::Module(DataRouteState::EpochMismatch) => {
1193 self.forwarding.warn_frame_drop(
1194 ctx.connection_id,
1195 channel,
1196 epoch,
1197 "module_to_client",
1198 "stale_epoch",
1199 );
1200 if frame.header.ty == FrameType::Request {
1201 self.counters
1202 .increment_module_requests_dropped_stale_route();
1203 let err = RouterError::StaleRouteEpoch {
1204 channel,
1205 epoch,
1206 corr,
1207 };
1208 if let Some(error_frame) = err.to_error_frame() {
1209 self.observe_connection_wait(
1210 ctx,
1211 "reply_egress",
1212 ctx.egress.send(error_frame),
1213 )
1214 .await?;
1215 }
1216 } else {
1217 self.handle_orphan_module_frame(ctx, &frame)?;
1218 }
1219 debug!(
1220 connection_id = ctx.connection_id.get(),
1221 channel, epoch, corr, "dropping module frame for stale route epoch"
1222 );
1223 return Ok(());
1224 }
1225 DataRoute::Module(DataRouteState::Reserved) => {
1226 self.forwarding.warn_frame_drop(
1227 ctx.connection_id,
1228 channel,
1229 epoch,
1230 "module_to_client",
1231 "missing_binding",
1232 );
1233 if frame.header.ty == FrameType::Request {
1234 self.counters
1235 .increment_module_requests_dropped_stale_route();
1236 let err = RouterError::UnknownChannel {
1237 channel,
1238 epoch,
1239 corr,
1240 };
1241 if let Some(error_frame) = err.to_error_frame() {
1242 self.observe_connection_wait(
1243 ctx,
1244 "reply_egress",
1245 ctx.egress.send(error_frame),
1246 )
1247 .await?;
1248 }
1249 } else {
1250 self.record_module_frame_drop(ctx.connection_id)?;
1251 }
1252 debug!(
1253 connection_id = ctx.connection_id.get(),
1254 channel, epoch, corr, "dropping module frame for reserved route handle"
1255 );
1256 return Ok(());
1257 }
1258 DataRoute::Module(DataRouteState::Absent) => {
1259 self.forwarding.warn_frame_drop(
1260 ctx.connection_id,
1261 channel,
1262 epoch,
1263 "module_to_client",
1264 "unknown_channel",
1265 );
1266 if frame.header.ty == FrameType::Request {
1267 self.counters
1268 .increment_module_requests_dropped_stale_route();
1269 let err = RouterError::UnknownChannel {
1270 channel,
1271 epoch,
1272 corr,
1273 };
1274 if let Some(error_frame) = err.to_error_frame() {
1275 self.observe_connection_wait(
1276 ctx,
1277 "reply_egress",
1278 ctx.egress.send(error_frame),
1279 )
1280 .await?;
1281 }
1282 } else {
1283 self.handle_orphan_module_frame(ctx, &frame)?;
1284 }
1285 debug!(
1286 connection_id = ctx.connection_id.get(),
1287 channel, epoch, corr, "dropping module frame for absent route handle"
1288 );
1289 return Ok(());
1290 }
1291 DataRoute::Module(DataRouteState::Bound(route)) => {
1292 if frame.header.ty == FrameType::Goodbye {
1293 if let RouteRelease::Removed(target) = self
1294 .forwarding
1295 .release_module_route(ctx.connection_id, channel, epoch)
1296 .map_err(RouterError::Forwarding)?
1297 {
1298 let mut goodbye = frame;
1299 goodbye.header.channel = target.channel;
1300 goodbye.header.epoch = target.epoch;
1301 goodbye.header.flags = goodbye.header.flags.without_daemon_origin();
1305 if let Err(err) = self
1306 .observe_connection_wait(
1307 ctx,
1308 "module_to_client",
1309 target.sink.send_to_client(goodbye),
1310 )
1311 .await
1312 {
1313 if !target.close_on_delivery_failure() {
1314 self.forwarding.warn_frame_drop(
1315 target.connection_id,
1316 target.channel,
1317 target.epoch,
1318 "module_to_client",
1319 err.diagnosis.cause,
1320 );
1321 }
1322 if target.close_on_delivery_failure()
1323 && self
1324 .forwarding
1325 .escalate_client_delivery_failure_diagnosed(
1326 target.connection_id,
1327 target.channel,
1328 target.epoch,
1329 CloseReason::new(
1330 "route_goodbye_delivery_failed",
1331 format!(
1332 "failed to enqueue route GOODBYE for client channel {}: {err}",
1333 target.channel
1334 ),
1335 ),
1336 UndeliveredFrame {
1337 module_id: Some(&route.module_id),
1338 sink: &target.sink,
1339 },
1340 Some(&err.diagnosis),
1341 )
1342 .map_err(RouterError::Forwarding)?
1343 {
1344 self.counters.increment_goodbye_relay_client_failed();
1345 }
1346 }
1347 } else {
1348 self.forwarding.warn_frame_drop(
1349 ctx.connection_id,
1350 channel,
1351 epoch,
1352 "module_to_client",
1353 "missing_binding",
1354 );
1355 }
1356 return Ok(());
1357 }
1358
1359 let bytes = queued_frame_bytes(&frame);
1363 let limit = route.client_sink.accounting.byte_budget;
1364 if bytes > limit {
1365 let ty = frame.header.ty;
1366 let flags = frame.header.flags;
1367 drop(frame);
1368 return self
1369 .refuse_oversized_module_frame(ctx, &route, (ty, flags), corr, bytes)
1370 .await;
1371 }
1372
1373 let releases_credit = is_terminal_frame(frame.header.ty);
1379 if releases_credit {
1380 route.flow.release_corr(corr);
1381 }
1382 let mut frame = frame;
1383 frame.header.channel = route.client_channel;
1384 frame.header.epoch = route.client_epoch;
1385 frame.header.flags = frame.header.flags.without_daemon_origin();
1391 if let Err(err) = self
1392 .counters
1393 .observe_reader_wait(
1394 || (route.module_id.clone(), principal_label(&route.principal)),
1395 "module_to_client",
1396 route.client_sink.send_to_client(frame),
1397 )
1398 .await
1399 {
1400 if self
1401 .forwarding
1402 .escalate_client_delivery_failure_diagnosed(
1403 route.client_connection_id,
1404 route.client_channel,
1405 route.client_epoch,
1406 CloseReason::new(
1407 "module_to_client_delivery_failed",
1408 format!(
1409 "failed to enqueue module frame for client channel {} corr {corr}: {err}",
1410 route.client_channel
1411 ),
1412 ),
1413 UndeliveredFrame {
1414 module_id: Some(&route.module_id),
1415 sink: &route.client_sink,
1416 },
1417 Some(&err.diagnosis),
1418 )
1419 .map_err(RouterError::Forwarding)?
1420 {
1421 self.counters
1422 .increment_client_egress_close_delivery_failed();
1423 }
1424 return Ok(());
1425 }
1426 return Ok(());
1427 }
1428 DataRoute::Client(DataRouteState::EpochMismatch) => {
1429 self.forwarding.warn_frame_drop(
1430 ctx.connection_id,
1431 channel,
1432 epoch,
1433 "client_to_module",
1434 "stale_epoch",
1435 );
1436 if frame.header.ty == FrameType::Request {
1437 self.counters.increment_client_frames_dropped_stale_route();
1438 let err = RouterError::StaleRouteEpoch {
1440 channel,
1441 epoch,
1442 corr,
1443 };
1444 if let Some(error_frame) = err.to_error_frame() {
1445 self.observe_connection_wait(
1446 ctx,
1447 "reply_egress",
1448 ctx.egress.send(error_frame),
1449 )
1450 .await?;
1451 }
1452 }
1453 debug!(
1454 connection_id = ctx.connection_id.get(),
1455 channel, epoch, corr, "dropping client frame for stale route epoch"
1456 );
1457 return Ok(());
1458 }
1459 DataRoute::Client(DataRouteState::Reserved) => {
1460 self.forwarding.warn_frame_drop(
1461 ctx.connection_id,
1462 channel,
1463 epoch,
1464 "client_to_module",
1465 "missing_binding",
1466 );
1467 if frame.header.ty == FrameType::Request {
1468 let err = RouterError::UnknownChannel {
1469 channel,
1470 epoch,
1471 corr,
1472 };
1473 if let Some(error_frame) = err.to_error_frame() {
1474 self.observe_connection_wait(
1475 ctx,
1476 "reply_egress",
1477 ctx.egress.send(error_frame),
1478 )
1479 .await?;
1480 }
1481 }
1482 return Ok(());
1483 }
1484 DataRoute::Client(DataRouteState::Bound(route)) => {
1485 if frame.header.ty == FrameType::Goodbye {
1486 let _ = self
1487 .control
1488 .handle_route_goodbye(ctx.connection_id, channel, epoch)?;
1489 return Ok(());
1490 }
1491 return self.forward_backend.handle_bound(frame, route).await;
1492 }
1493 DataRoute::Client(DataRouteState::Absent) => {}
1494 }
1495
1496 if let Some(backend) = self.backends.get(&channel) {
1497 return backend.handle(ctx.clone(), frame).await.inspect_err(|_| {
1498 self.forwarding.warn_frame_drop(
1499 ctx.connection_id,
1500 channel,
1501 epoch,
1502 "client_to_backend",
1503 "endpoint_gone",
1504 );
1505 });
1506 }
1507 self.forwarding.warn_frame_drop(
1508 ctx.connection_id,
1509 channel,
1510 epoch,
1511 "client_to_module",
1512 "unknown_channel",
1513 );
1514 if frame.header.ty == FrameType::Request {
1515 let err = RouterError::UnknownChannel {
1516 channel,
1517 epoch,
1518 corr,
1519 };
1520 if let Some(error_frame) = err.to_error_frame() {
1521 self.observe_connection_wait(ctx, "reply_egress", ctx.egress.send(error_frame))
1522 .await?;
1523 }
1524 }
1525 Ok(())
1526 }
1527
1528 async fn refuse_oversized_module_frame(
1529 &self,
1530 ctx: &RouteCtx,
1531 route: &RouteBinding,
1532 header: (FrameType, Flags),
1533 corr: u64,
1534 bytes: usize,
1535 ) -> Result<(), RouterError> {
1536 let (ty, flags) = header;
1537 let limit = route.client_sink.accounting.byte_budget;
1538 if ty == FrameType::Push {
1539 let diagnosis = ClientDeliveryDiagnosis {
1543 frame_type: ty,
1544 flags,
1545 cause: "frame_too_large",
1546 };
1547 if self
1548 .forwarding
1549 .escalate_client_delivery_failure_diagnosed(
1550 route.client_connection_id,
1551 route.client_channel,
1552 route.client_epoch,
1553 CloseReason::new(
1554 error_codes::FRAME_TOO_LARGE,
1555 format!(
1556 "oversized push: size={bytes} limit={limit} (header plus body bytes)"
1557 ),
1558 ),
1559 UndeliveredFrame {
1560 module_id: Some(&route.module_id),
1561 sink: &route.client_sink,
1562 },
1563 Some(&diagnosis),
1564 )
1565 .map_err(RouterError::Forwarding)?
1566 {
1567 self.counters
1568 .increment_client_egress_close_delivery_failed();
1569 }
1570 return Ok(());
1571 }
1572
1573 warn!(
1574 connection_id = route.client_connection_id.get(),
1575 module_id = %route.module_id,
1576 client_principal = %principal_label(&route.principal),
1577 client_channel = route.client_channel,
1578 frame_type = ?ty,
1579 frame_bytes = bytes,
1580 byte_limit = limit,
1581 "refusing oversized module-to-client frame with ERROR frame_too_large"
1582 );
1583 if ty == FrameType::Request {
1584 let error = frame_too_large_error(
1587 route.module_channel,
1588 route.module_epoch,
1589 corr,
1590 bytes,
1591 limit,
1592 )?;
1593 self.observe_connection_wait(ctx, "reply_egress", ctx.egress.send(error))
1594 .await?;
1595 } else {
1596 route.flow.release_corr(corr);
1599 let error = frame_too_large_error(
1600 route.client_channel,
1601 route.client_epoch,
1602 corr,
1603 bytes,
1604 limit,
1605 )?;
1606 if let Err(err) = self
1609 .counters
1610 .observe_reader_wait(
1611 || (route.module_id.clone(), principal_label(&route.principal)),
1612 "module_to_client",
1613 route.client_sink.send_to_client(error),
1614 )
1615 .await
1616 {
1617 if self
1618 .forwarding
1619 .escalate_client_delivery_failure_diagnosed(
1620 route.client_connection_id,
1621 route.client_channel,
1622 route.client_epoch,
1623 CloseReason::new(
1624 "module_to_client_delivery_failed",
1625 format!(
1626 "failed to enqueue frame_too_large for client channel {} corr {corr}: {err}",
1627 route.client_channel
1628 ),
1629 ),
1630 UndeliveredFrame {
1631 module_id: Some(&route.module_id),
1632 sink: &route.client_sink,
1633 },
1634 Some(&err.diagnosis),
1635 )
1636 .map_err(RouterError::Forwarding)?
1637 {
1638 self.counters
1639 .increment_client_egress_close_delivery_failed();
1640 }
1641 }
1642 }
1643 Ok(())
1644 }
1645}
1646
1647impl Default for Router {
1648 fn default() -> Self {
1649 Self::with_default_self_handler()
1650 }
1651}
1652
1653#[must_use]
1655pub struct RouterConnection {
1656 id: ConnectionId,
1657 control_handler: Arc<ControlHandler>,
1658 forwarding: Arc<ForwardingTable>,
1659 close_receiver: Option<ConnectionCloseReceiver>,
1660 orphan_goodbyes: Arc<OrphanGoodbyeLimiter>,
1661}
1662
1663impl RouterConnection {
1664 pub fn id(&self) -> ConnectionId {
1665 self.id
1666 }
1667
1668 pub(crate) fn take_close_receiver(&mut self) -> ConnectionCloseReceiver {
1669 self.close_receiver
1670 .take()
1671 .expect("connection close receiver can only be taken once")
1672 }
1673}
1674
1675impl Drop for RouterConnection {
1676 fn drop(&mut self) {
1677 self.orphan_goodbyes.forget_connection(self.id);
1678 let _ = self.control_handler.cleanup_connection(self.id);
1681 self.forwarding.unregister_connection_close(self.id);
1685 }
1686}
1687
1688#[derive(Debug, Default, Clone, Copy)]
1691pub struct EchoBackend;
1692
1693impl EchoBackend {
1694 pub async fn handle(&self, ctx: RouteCtx, frame: Frame) -> Result<(), RouterError> {
1695 let response = Frame::build_with_version(
1696 frame.header.ver,
1697 FrameType::Response,
1698 frame.header.flags,
1699 frame.header.channel,
1700 frame.header.epoch,
1701 frame.header.corr,
1702 frame.body,
1703 )
1704 .map_err(RouterError::FrameBuild)?;
1705 ctx.egress.send(response).await
1706 }
1707}
1708
1709#[derive(Debug, Clone)]
1711pub struct ForwardBackend {
1712 forwarding: Arc<ForwardingTable>,
1713}
1714
1715impl ForwardBackend {
1716 pub fn new(forwarding: Arc<ForwardingTable>) -> Self {
1717 Self { forwarding }
1718 }
1719
1720 pub async fn handle(&self, ctx: RouteCtx, frame: Frame) -> Result<(), RouterError> {
1721 let channel = frame.header.channel;
1722 let corr = frame.header.corr;
1723 let route = match self
1724 .forwarding
1725 .lookup_data_route(ctx.connection_id, channel, frame.header.epoch)
1726 .map_err(RouterError::Forwarding)?
1727 {
1728 DataRoute::Client(DataRouteState::Bound(route)) => route,
1729 DataRoute::Client(_) | DataRoute::Module(_) => {
1730 self.forwarding.warn_frame_drop(
1731 ctx.connection_id,
1732 channel,
1733 frame.header.epoch,
1734 "client_to_module",
1735 "missing_binding",
1736 );
1737 return Err(RouterError::UnknownChannel {
1738 channel,
1739 epoch: frame.header.epoch,
1740 corr,
1741 });
1742 }
1743 };
1744 self.handle_bound(frame, route).await
1745 }
1746
1747 pub(crate) async fn handle_bound(
1748 &self,
1749 frame: Frame,
1750 route: Arc<RouteBinding>,
1751 ) -> Result<(), RouterError> {
1752 let channel = frame.header.channel;
1753 let corr = frame.header.corr;
1754 let frame_type = frame.header.ty;
1755
1756 let acquired_credit = frame_type == FrameType::Request;
1759 if acquired_credit && route.flow.busy_refusals() {
1760 use crate::forwarding::RequestAdmission;
1761 match self
1762 .forwarding
1763 .try_admit_request(
1764 &route,
1765 frame.header.epoch,
1766 corr,
1767 frame.header.flags.is_subscription(),
1768 )
1769 .map_err(RouterError::Forwarding)?
1770 {
1771 RequestAdmission::Admitted => {}
1772 RequestAdmission::Busy(detail) => {
1773 let principal = principal_label(&route.principal);
1774 let counters = self.forwarding.counters_ref();
1775 counters.increment_route_busy(&route.module_id, &principal);
1776 if route.flow.should_warn_busy() {
1777 warn!(module_id = %route.module_id, client_principal = %principal, client_channel = channel,
1778 route_epoch = route.client_epoch, ?detail, "request refused: route_busy");
1779 }
1780 let error = RouterError::RouteBusy {
1781 channel,
1782 epoch: frame.header.epoch,
1783 corr,
1784 detail: Box::new(detail),
1785 };
1786 let refusal = error
1787 .to_error_frame()
1788 .expect("route_busy is a serializable wire error");
1789 counters
1790 .observe_reader_wait(
1791 || (route.module_id.clone(), principal),
1792 "route_busy_egress",
1793 route.client_sink.send(refusal),
1794 )
1795 .await?;
1796 return Ok(());
1797 }
1798 RequestAdmission::ModuleReloading => {
1799 return Err(RouterError::route_error_with_epoch(
1800 channel,
1801 frame.header.epoch,
1802 corr,
1803 error_codes::MODULE_RELOADING,
1804 format!("module endpoint for route channel {channel} is reloading"),
1805 ));
1806 }
1807 RequestAdmission::Stale => {
1808 return Err(RouterError::StaleRouteEpoch {
1809 channel,
1810 epoch: frame.header.epoch,
1811 corr,
1812 })
1813 }
1814 }
1815 } else if acquired_credit {
1816 let counters = self.forwarding.counters_ref();
1817 if let Err(err) = counters
1818 .observe_reader_wait(
1819 || (route.module_id.clone(), principal_label(&route.principal)),
1820 "legacy_credit",
1821 route
1822 .flow
1823 .acquire_tagged(corr, frame.header.flags.is_subscription()),
1824 )
1825 .await
1826 {
1827 self.forwarding.warn_frame_drop(
1828 route.client_connection_id,
1829 channel,
1830 frame.header.epoch,
1831 "client_to_module",
1832 "endpoint_gone",
1833 );
1834 if self
1841 .forwarding
1842 .endpoint_is_draining(route.module_endpoint)
1843 .map_err(RouterError::Forwarding)?
1844 {
1845 return Err(RouterError::route_error_with_epoch(
1846 channel,
1847 frame.header.epoch,
1848 corr,
1849 "module_reloading",
1850 format!("module endpoint for route channel {channel} is reloading"),
1851 ));
1852 }
1853 return Err(RouterError::backend_with_epoch(
1854 channel,
1855 frame.header.epoch,
1856 corr,
1857 format!("{err} for route channel {channel}"),
1858 ));
1859 }
1860 }
1861
1862 let mut frame = frame;
1863 frame.header.channel = route.module_channel;
1864 frame.header.epoch = route.module_epoch;
1865 frame.header.flags = frame.header.flags.without_daemon_origin();
1869 let counters = self.forwarding.counters_ref();
1870 let result = counters
1871 .observe_reader_wait(
1872 || (route.module_id.clone(), principal_label(&route.principal)),
1873 "module_queue",
1874 route.module_sink.send(frame),
1875 )
1876 .await
1877 .map_err(|err| {
1878 self.forwarding.warn_frame_drop(
1879 route.client_connection_id,
1880 channel,
1881 route.client_epoch,
1882 "client_to_module",
1883 "endpoint_gone",
1884 );
1885 RouterError::backend_with_epoch(channel, route.client_epoch, corr, err.to_string())
1886 });
1887 if acquired_credit && result.is_err() {
1888 route.flow.release_corr(corr);
1889 }
1890 result
1891 }
1892}
1893
1894fn is_terminal_frame(frame_type: FrameType) -> bool {
1895 matches!(
1896 frame_type,
1897 FrameType::Response | FrameType::Error | FrameType::StreamEnd
1898 )
1899}
1900
1901#[derive(Debug, Clone, PartialEq, Eq)]
1904pub enum RouterError {
1905 ReservedChannelZero,
1906 DuplicateChannel {
1907 channel: u16,
1908 },
1909 UnknownChannel {
1910 channel: u16,
1911 epoch: u32,
1912 corr: u64,
1913 },
1914 StaleRouteEpoch {
1915 channel: u16,
1916 epoch: u32,
1917 corr: u64,
1918 },
1919 RouteBusy {
1920 channel: u16,
1921 epoch: u32,
1922 corr: u64,
1923 detail: Box<subc_protocol::RouteBusyDetail>,
1924 },
1925 Backend {
1926 channel: u16,
1927 epoch: u32,
1928 corr: u64,
1929 message: String,
1930 },
1931 RouteError {
1932 channel: u16,
1933 epoch: u32,
1934 corr: u64,
1935 code: String,
1936 message: String,
1937 },
1938 FrameBuild(FrameBuildError),
1939 Forwarding(ForwardingError),
1940}
1941
1942impl RouterError {
1943 pub fn backend(channel: u16, corr: u64, message: impl Into<String>) -> Self {
1944 Self::backend_with_epoch(channel, 0, corr, message)
1945 }
1946
1947 pub fn backend_with_epoch(
1948 channel: u16,
1949 epoch: u32,
1950 corr: u64,
1951 message: impl Into<String>,
1952 ) -> Self {
1953 Self::Backend {
1954 channel,
1955 epoch,
1956 corr,
1957 message: message.into(),
1958 }
1959 }
1960
1961 pub fn route_error(
1962 channel: u16,
1963 corr: u64,
1964 code: impl Into<String>,
1965 message: impl Into<String>,
1966 ) -> Self {
1967 Self::route_error_with_epoch(channel, 0, corr, code, message)
1968 }
1969
1970 pub fn route_error_with_epoch(
1971 channel: u16,
1972 epoch: u32,
1973 corr: u64,
1974 code: impl Into<String>,
1975 message: impl Into<String>,
1976 ) -> Self {
1977 Self::RouteError {
1978 channel,
1979 epoch,
1980 corr,
1981 code: code.into(),
1982 message: message.into(),
1983 }
1984 }
1985
1986 pub fn to_error_frame(&self) -> Option<Frame> {
1988 match self {
1989 Self::RouteBusy {
1990 channel,
1991 epoch,
1992 corr,
1993 detail,
1994 } => {
1995 let body = serde_json::to_vec(&ErrorBody {
1996 code: error_codes::ROUTE_BUSY.into(),
1997 message: "route has no free request or watch credit; retry on the same route"
1998 .into(),
1999 detail: Some(serde_json::to_value(detail).ok()?),
2000 })
2001 .ok()?;
2002 Frame::build(
2003 FrameType::Error,
2004 daemon_error_flags(),
2005 *channel,
2006 *epoch,
2007 *corr,
2008 body,
2009 )
2010 .ok()
2011 }
2012 Self::UnknownChannel {
2013 channel,
2014 epoch,
2015 corr,
2016 } => error_frame(
2017 *channel,
2018 *epoch,
2019 *corr,
2020 error_codes::UNKNOWN_CHANNEL,
2021 format!("unknown channel {channel}"),
2022 ),
2023 Self::StaleRouteEpoch {
2024 channel,
2025 epoch,
2026 corr,
2027 } => error_frame(
2028 *channel,
2029 *epoch,
2030 *corr,
2031 error_codes::STALE_ROUTE_EPOCH,
2032 format!("stale route epoch for channel {channel}"),
2033 ),
2034 Self::Backend {
2035 channel,
2036 epoch,
2037 corr,
2038 message,
2039 } => error_frame(*channel, *epoch, *corr, "backend_error", message.clone()),
2040 Self::RouteError {
2041 channel,
2042 epoch,
2043 corr,
2044 code,
2045 message,
2046 } => error_frame(*channel, *epoch, *corr, code, message.clone()),
2047 Self::ReservedChannelZero
2048 | Self::DuplicateChannel { .. }
2049 | Self::FrameBuild(_)
2050 | Self::Forwarding(_) => None,
2051 }
2052 }
2053}
2054
2055pub(crate) fn daemon_error_flags() -> Flags {
2067 Flags::new(false, Priority::Passive, false).with_daemon_origin()
2068}
2069
2070fn error_frame(channel: u16, epoch: u32, corr: u64, code: &str, message: String) -> Option<Frame> {
2071 let body = serde_json::to_vec(&ErrorBody {
2072 code: code.to_string(),
2073 message,
2074 detail: None,
2075 })
2076 .ok()?;
2077
2078 Frame::build(
2079 FrameType::Error,
2080 daemon_error_flags(),
2081 channel,
2082 epoch,
2083 corr,
2084 body,
2085 )
2086 .ok()
2087}
2088
2089fn frame_too_large_error(
2090 channel: u16,
2091 epoch: u32,
2092 corr: u64,
2093 bytes: usize,
2094 limit: usize,
2095) -> Result<Frame, RouterError> {
2096 let body = serde_json::to_vec(&ErrorBody {
2097 code: error_codes::FRAME_TOO_LARGE.to_string(),
2098 message: format!(
2099 "module frame of {bytes} bytes exceeds client egress limit of {limit} bytes"
2100 ),
2101 detail: Some(serde_json::json!({ "frame_bytes": bytes, "byte_limit": limit })),
2102 })
2103 .expect("serializing a frame size error");
2104 Frame::build(
2105 FrameType::Error,
2106 daemon_error_flags(),
2107 channel,
2108 epoch,
2109 corr,
2110 body,
2111 )
2112 .map_err(RouterError::FrameBuild)
2113}
2114
2115impl fmt::Display for RouterError {
2116 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2117 match self {
2118 Self::ReservedChannelZero => write!(f, "channel 0 is reserved for subc"),
2119 Self::DuplicateChannel { channel } => {
2120 write!(f, "backend already registered for channel {channel}")
2121 }
2122 Self::UnknownChannel { channel, corr, .. } => {
2123 write!(f, "unknown channel {channel} for corr {corr}")
2124 }
2125 Self::StaleRouteEpoch { channel, corr, .. } => {
2126 write!(f, "stale route epoch for channel {channel} corr {corr}")
2127 }
2128 Self::RouteBusy { channel, corr, .. } => {
2129 write!(f, "route busy on channel {channel} corr {corr}")
2130 }
2131 Self::Backend {
2132 channel,
2133 corr,
2134 message,
2135 ..
2136 } => write!(
2137 f,
2138 "backend error on channel {channel} corr {corr}: {message}"
2139 ),
2140 Self::RouteError {
2141 channel,
2142 corr,
2143 code,
2144 message,
2145 ..
2146 } => write!(
2147 f,
2148 "route error {code} on channel {channel} corr {corr}: {message}"
2149 ),
2150 Self::FrameBuild(err) => write!(f, "failed to build routed frame: {err}"),
2151 Self::Forwarding(err) => write!(f, "forwarding error: {err}"),
2152 }
2153 }
2154}
2155
2156impl Error for RouterError {
2157 fn source(&self) -> Option<&(dyn Error + 'static)> {
2158 match self {
2159 Self::FrameBuild(err) => Some(err),
2160 Self::Forwarding(err) => Some(err),
2161 Self::ReservedChannelZero
2162 | Self::DuplicateChannel { .. }
2163 | Self::UnknownChannel { .. }
2164 | Self::StaleRouteEpoch { .. }
2165 | Self::RouteBusy { .. }
2166 | Self::Backend { .. }
2167 | Self::RouteError { .. } => None,
2168 }
2169 }
2170}
2171
2172#[cfg(test)]
2173mod tests {
2174 include!("route_busy_router_tests.rs");
2175 use super::*;
2176 use crate::{
2177 forwarding::RouteBindRelayOutcome,
2178 supervise::{ModuleSpec, RestartPolicy, Supervisor, SupervisorHandle},
2179 ControlHandler, Registry,
2180 };
2181 use std::{
2182 sync::{mpsc as std_mpsc, Arc},
2183 time::Duration,
2184 };
2185 use subc_control::ModuleProtocol;
2186 use subc_protocol::{manifest::Concurrency, ErrorBody, Flags, FrameType, Priority};
2187 use tokio::sync::mpsc;
2188
2189 pub(crate) use crate::router::test_log::{captured_logs, log_capture};
2190
2191 fn logged_millis(logs: &str, field: &str) -> u64 {
2192 logs.split_whitespace()
2193 .find_map(|part| part.strip_prefix(field))
2194 .and_then(|value| value.parse().ok())
2195 .unwrap_or_else(|| panic!("missing numeric {field} in logs: {logs}"))
2196 }
2197
2198 fn request(channel: u16, corr: u64, body: &[u8]) -> Frame {
2199 Frame::build(
2200 FrameType::Request,
2201 Flags::new(true, Priority::Interactive, false),
2202 channel,
2203 0,
2204 corr,
2205 body.to_vec(),
2206 )
2207 .unwrap()
2208 }
2209
2210 fn ping(corr: u64) -> Frame {
2211 Frame::build(
2212 FrameType::Ping,
2213 Flags::new(false, Priority::Passive, false),
2214 0,
2215 0,
2216 corr,
2217 Vec::new(),
2218 )
2219 .unwrap()
2220 }
2221
2222 fn route_ctx() -> (RouteCtx, mpsc::Receiver<crate::router::OutboundFrame>) {
2223 let (tx, rx) = mpsc::channel(8);
2224 (
2225 RouteCtx {
2226 connection_id: ConnectionId::LOCAL,
2227 egress: FrameSink::new(tx),
2228 },
2229 rx,
2230 )
2231 }
2232
2233 #[tokio::test]
2234 async fn retirement_egress_all_send_paths_drop_after_fence() {
2235 let (tx, mut rx) = mpsc::channel(8);
2236 let sink = FrameSink::new(tx);
2237 let reserved = sink.reserve_owned().await.unwrap();
2238 let immediate = sink.try_reserve_owned().unwrap();
2239 sink.terminate_egress();
2240 assert!(reserved.send(ping(1)));
2241 assert!(immediate.send(ping(2)));
2242 sink.send(ping(3)).await.unwrap();
2243 sink.try_send(ping(4)).unwrap();
2244 sink.send_to_client(ping(5)).await.unwrap();
2245 let queued = AtomicBool::new(false);
2246 assert!(sink
2247 .send_flushed_notifying_enqueue(ping(6), || queued.store(true, Ordering::Relaxed))
2248 .await
2249 .is_err());
2250 assert!(!queued.load(Ordering::Relaxed));
2251 assert!(sink.send_flushed(ping(7)).await.is_err());
2252 assert!(sink.reserve_owned().await.is_err());
2253 assert!(sink.try_reserve_owned().is_err());
2254 assert!(
2255 rx.try_recv().is_err(),
2256 "retired frames must not enter any writer queue"
2257 );
2258 assert_eq!(sink.backlog().queued_frames, 0);
2259 assert_eq!(sink.backlog().queued_bytes, 0);
2260 }
2261
2262 #[tokio::test]
2263 async fn retirement_egress_reservation_rechecks_after_slot_acquisition() {
2264 let (tx, mut rx) = mpsc::channel(1);
2265 let sink = FrameSink::new(tx);
2266 sink.accounting
2269 .retire_after_reserve
2270 .store(true, Ordering::Relaxed);
2271 assert!(
2272 sink.reserve_owned().await.is_err(),
2273 "a slot acquired before retirement must not escape as a live reservation"
2274 );
2275 assert_eq!(
2276 sink.tx.capacity(),
2277 1,
2278 "refusal must release the reserved slot"
2279 );
2280 assert!(rx.try_recv().is_err());
2281 }
2282
2283 #[tokio::test]
2284 async fn retirement_egress_pending_budget_and_slot_sends_stop() {
2285 for budget in [1, usize::MAX] {
2286 let (tx, mut rx) = mpsc::channel(1);
2287 let sink = FrameSink::with_byte_budget(tx, budget);
2288 sink.try_send(ping(1)).unwrap();
2289 let sending = sink.send(ping(2));
2290 tokio::pin!(sending);
2291 assert!(poll_once(sending.as_mut()).await.is_pending());
2292 sink.terminate_egress();
2293 tokio::time::timeout(Duration::from_secs(2), sending)
2294 .await
2295 .unwrap()
2296 .unwrap();
2297 drop(rx.try_recv().unwrap());
2298 assert!(
2299 rx.try_recv().is_err(),
2300 "a send parked before retirement must not enqueue afterward"
2301 );
2302 assert_eq!(sink.backlog().queued_bytes, 0);
2303 }
2304 }
2305
2306 #[tokio::test]
2307 async fn retirement_egress_pending_flush_and_reservation_stop() {
2308 let (tx, mut rx) = mpsc::channel(1);
2309 let sink = FrameSink::new(tx);
2310 sink.try_send(ping(1)).unwrap();
2311 let queued = AtomicBool::new(false);
2312 let sending =
2313 sink.send_flushed_notifying_enqueue(ping(2), || queued.store(true, Ordering::Relaxed));
2314 let reserving = sink.reserve_owned();
2315 tokio::pin!(sending, reserving);
2316 assert!(poll_once(sending.as_mut()).await.is_pending());
2317 assert!(poll_once(reserving.as_mut()).await.is_pending());
2318 sink.terminate_egress();
2319 assert!(tokio::time::timeout(Duration::from_secs(2), sending)
2320 .await
2321 .unwrap()
2322 .is_err());
2323 assert!(tokio::time::timeout(Duration::from_secs(2), reserving)
2324 .await
2325 .unwrap()
2326 .is_err());
2327 assert!(!queued.load(Ordering::Relaxed));
2328 drop(rx.try_recv().unwrap());
2329 assert!(rx.try_recv().is_err());
2330 assert_eq!(sink.backlog().queued_bytes, 0);
2331 }
2332
2333 #[tokio::test]
2334 async fn echo_backend_returns_response_with_byte_identical_body() {
2335 let mut router = Router::with_default_self_handler();
2336 router.register_backend(7, EchoBackend).unwrap();
2337 let (ctx, mut rx) = route_ctx();
2338 let body = b"{not parsed}\0\xff";
2339
2340 router
2341 .route_for_connection(&ctx, request(7, 123, body))
2342 .await
2343 .unwrap();
2344 let response = rx.recv().await.unwrap();
2345
2346 assert_eq!(response.header.ty, FrameType::Response);
2347 assert_eq!(response.header.channel, 7);
2348 assert_eq!(response.header.corr, 123);
2349 assert_eq!(response.body, body);
2350 assert!(rx.try_recv().is_err());
2351 }
2352
2353 #[tokio::test]
2354 async fn unknown_channel_emits_canonical_error_frame() {
2355 let router = Router::with_default_self_handler();
2356 let (ctx, mut rx) = route_ctx();
2357
2358 router
2359 .route_for_connection(&ctx, request(99, 5, b"payload"))
2360 .await
2361 .unwrap();
2362 let error_frame = rx.recv().await.unwrap();
2363
2364 assert_eq!(error_frame.header.ty, FrameType::Error);
2365 assert_eq!(error_frame.header.channel, 99);
2366 assert_eq!(error_frame.header.corr, 5);
2367 let body: ErrorBody = serde_json::from_slice(&error_frame.body).unwrap();
2368 assert_eq!(body.code, "unknown_channel");
2369 assert_eq!(body.message, "unknown channel 99");
2370 }
2371
2372 #[tokio::test]
2377 async fn daemon_authored_data_plane_errors_carry_daemon_origin() {
2378 let router = Router::with_default_self_handler();
2379 let (ctx, mut rx) = route_ctx();
2380 router
2381 .route_for_connection(&ctx, request(99, 5, b"payload"))
2382 .await
2383 .unwrap();
2384 let unknown = rx.recv().await.unwrap();
2385 assert_eq!(unknown.header.ty, FrameType::Error);
2386 let body: ErrorBody = serde_json::from_slice(&unknown.body).unwrap();
2387 assert_eq!(body.code, "unknown_channel");
2388 assert!(
2389 unknown.header.flags.is_daemon_origin(),
2390 "unknown_channel must carry daemon origin: {:?}",
2391 unknown.header.flags
2392 );
2393
2394 let (
2395 router,
2396 _forwarding,
2397 client_ctx,
2398 mut client_rx,
2399 _module_ctx,
2400 _module_egress_rx,
2401 _module_rx,
2402 pending,
2403 ) = dynamic_route_fixture(true);
2404 let _ = client_rx.recv().await;
2405 router
2406 .route_for_connection(
2407 &client_ctx,
2408 route_frame(
2409 FrameType::Request,
2410 pending.client_channel,
2411 pending.client_epoch + 1,
2412 702,
2413 ),
2414 )
2415 .await
2416 .unwrap();
2417 let stale = client_rx.recv().await.unwrap();
2418 assert_eq!(stale.header.ty, FrameType::Error);
2419 let body: ErrorBody = serde_json::from_slice(&stale.body).unwrap();
2420 assert_eq!(body.code, "stale_route_epoch");
2421 assert!(
2422 stale.header.flags.is_daemon_origin(),
2423 "stale_route_epoch must carry daemon origin: {:?}",
2424 stale.header.flags
2425 );
2426 }
2427
2428 #[tokio::test]
2433 async fn module_error_with_daemon_bit_is_stripped_before_client_delivery() {
2434 let (
2435 router,
2436 _forwarding,
2437 client_ctx,
2438 mut client_rx,
2439 module_ctx,
2440 _module_egress_rx,
2441 mut module_rx,
2442 pending,
2443 ) = dynamic_route_fixture(true);
2444 let _ = client_rx.recv().await;
2445 router
2448 .route_for_connection(
2449 &client_ctx,
2450 route_frame(
2451 FrameType::Request,
2452 pending.client_channel,
2453 pending.client_epoch,
2454 701,
2455 ),
2456 )
2457 .await
2458 .unwrap();
2459 let _ = module_rx.recv().await;
2460
2461 let body = serde_json::to_vec(&ErrorBody::new("module_reloading", "try again")).unwrap();
2462 let spoof = Frame::build(
2463 FrameType::Error,
2464 Flags::new(false, Priority::Interactive, false).with_daemon_origin(),
2465 pending.module_channel,
2466 pending.module_epoch,
2467 701,
2468 body.clone(),
2469 )
2470 .unwrap();
2471 router
2472 .route_for_connection(&module_ctx, spoof)
2473 .await
2474 .unwrap();
2475 let delivered = client_rx.recv().await.unwrap();
2476 assert_eq!(delivered.header.ty, FrameType::Error);
2477 assert_eq!(delivered.header.channel, pending.client_channel);
2478 assert_eq!(delivered.header.epoch, pending.client_epoch);
2479 assert_eq!(delivered.header.corr, 701);
2480 assert!(
2481 !delivered.header.flags.is_daemon_origin(),
2482 "module-set daemon origin must be cleared: {:?}",
2483 delivered.header.flags
2484 );
2485 assert_eq!(delivered.body, body, "the body travels byte-identical");
2486 }
2487
2488 #[tokio::test]
2491 async fn module_response_with_daemon_bit_is_stripped_preserving_other_flags() {
2492 use subc_protocol::FLAG_SUBSCRIPTION;
2493 let (
2494 router,
2495 _forwarding,
2496 client_ctx,
2497 mut client_rx,
2498 module_ctx,
2499 _module_egress_rx,
2500 mut module_rx,
2501 pending,
2502 ) = dynamic_route_fixture(true);
2503 let _ = client_rx.recv().await;
2504 router
2505 .route_for_connection(
2506 &client_ctx,
2507 route_frame(
2508 FrameType::Request,
2509 pending.client_channel,
2510 pending.client_epoch,
2511 701,
2512 ),
2513 )
2514 .await
2515 .unwrap();
2516 let _ = module_rx.recv().await;
2517
2518 let sent_flags = Flags(
2519 Flags::new(true, Priority::Background, true).0
2520 | FLAG_SUBSCRIPTION
2521 | subc_protocol::FLAG_DAEMON_ORIGIN,
2522 );
2523 assert!(sent_flags.is_daemon_origin());
2524 let response = Frame::build(
2525 FrameType::Response,
2526 sent_flags,
2527 pending.module_channel,
2528 pending.module_epoch,
2529 701,
2530 b"route-body".to_vec(),
2531 )
2532 .unwrap();
2533 router
2534 .route_for_connection(&module_ctx, response)
2535 .await
2536 .unwrap();
2537 let delivered = client_rx.recv().await.unwrap();
2538 assert_eq!(delivered.header.ty, FrameType::Response);
2539 assert!(
2540 !delivered.header.flags.is_daemon_origin(),
2541 "module-set daemon origin must be cleared: {:?}",
2542 delivered.header.flags
2543 );
2544 assert!(
2545 delivered.header.flags.is_binary(),
2546 "binary flag must survive: {:?}",
2547 delivered.header.flags
2548 );
2549 assert!(
2550 delivered.header.flags.is_last(),
2551 "LAST flag must survive: {:?}",
2552 delivered.header.flags
2553 );
2554 assert!(
2555 delivered.header.flags.is_subscription(),
2556 "subscription flag must survive: {:?}",
2557 delivered.header.flags
2558 );
2559 assert_eq!(
2560 delivered.header.flags.priority(),
2561 Some(Priority::Background),
2562 "priority must survive"
2563 );
2564 }
2565
2566 #[tokio::test]
2569 async fn client_frame_with_daemon_bit_is_stripped_before_module_delivery() {
2570 let (
2571 router,
2572 _forwarding,
2573 client_ctx,
2574 mut client_rx,
2575 _module_ctx,
2576 _module_egress_rx,
2577 mut module_rx,
2578 pending,
2579 ) = dynamic_route_fixture(true);
2580 let _ = client_rx.recv().await;
2581 let spoof = Frame::build(
2582 FrameType::Request,
2583 Flags::new(false, Priority::Interactive, false).with_daemon_origin(),
2584 pending.client_channel,
2585 pending.client_epoch,
2586 701,
2587 b"route-body".to_vec(),
2588 )
2589 .unwrap();
2590 router
2591 .route_for_connection(&client_ctx, spoof)
2592 .await
2593 .unwrap();
2594 let delivered = module_rx.recv().await.unwrap();
2595 assert_eq!(delivered.header.ty, FrameType::Request);
2596 assert!(
2597 !delivered.header.flags.is_daemon_origin(),
2598 "client-set daemon origin must be cleared: {:?}",
2599 delivered.header.flags
2600 );
2601 }
2602
2603 #[tokio::test]
2604 async fn channel_zero_uses_control_handler_not_backend_registry() {
2605 let mut router = Router::with_default_self_handler();
2606 router.register_backend(1, EchoBackend).unwrap();
2607 let (ctx, mut rx) = route_ctx();
2608
2609 router.route_for_connection(&ctx, ping(77)).await.unwrap();
2610 let response = rx.recv().await.unwrap();
2611
2612 assert_eq!(response.header.ty, FrameType::Pong);
2613 assert_eq!(response.header.channel, 0);
2614 assert_eq!(response.header.corr, 77);
2615 assert!(response.body.is_empty());
2616 }
2617
2618 #[tokio::test]
2619 async fn slow_control_dispatch_logs_decoded_op_and_elapsed_time() {
2620 let control = Arc::new(
2621 ControlHandler::new(Arc::new(Registry::default()))
2622 .with_control_dispatch_delay(Duration::from_millis(1050)),
2623 );
2624 let router = Router::with_control_handler(control);
2625 let (ctx, mut rx) = route_ctx();
2626 let (output, guard) = log_capture(tracing::Level::WARN);
2627
2628 router
2629 .route_for_connection(&ctx, request(0, 41, br#"{"op":"server.describe"}"#))
2630 .await
2631 .expect("slow request routes");
2632 assert!(rx.recv().await.is_some(), "request receives a response");
2633 drop(guard);
2634
2635 let logs = captured_logs(&output);
2636 assert!(logs.contains("slow control dispatch"));
2637 assert!(logs.contains("op=server.describe"));
2638 assert!(logs.contains("connection_id=0"));
2639 assert!(logs.contains("corr=41"));
2640 assert!(
2641 logged_millis(&logs, "elapsed_ms=") >= 1050,
2642 "elapsed must include the injected handler delay: {logs}"
2643 );
2644 }
2645
2646 #[tokio::test]
2647 async fn fast_control_dispatch_emits_arrival_without_slow_warning() {
2648 let router = Router::with_default_self_handler();
2649 let (ctx, mut rx) = route_ctx();
2650 let (output, guard) = log_capture(tracing::Level::DEBUG);
2651
2652 router
2653 .route_for_connection(&ctx, request(0, 42, br#"{"op":"server.describe"}"#))
2654 .await
2655 .expect("fast request routes");
2656 assert!(rx.recv().await.is_some(), "request receives a response");
2657 drop(guard);
2658
2659 let logs = captured_logs(&output);
2660 assert!(logs.contains("control dispatch op=server.describe connection_id=0 corr=42"));
2661 assert!(!logs.contains("slow control dispatch"));
2662 }
2663
2664 #[tokio::test]
2665 async fn control_dispatch_arrival_is_hidden_at_info() {
2666 let router = Router::with_default_self_handler();
2667 let (ctx, mut rx) = route_ctx();
2668 let (output, guard) = log_capture(tracing::Level::INFO);
2669
2670 router
2671 .route_for_connection(&ctx, request(0, 43, br#"{"op":"server.describe"}"#))
2672 .await
2673 .expect("fast request routes");
2674 assert!(rx.recv().await.is_some(), "request receives a response");
2675 drop(guard);
2676
2677 assert!(
2678 !captured_logs(&output).contains("control dispatch"),
2679 "arrival logging must stay hidden at INFO"
2680 );
2681 }
2682
2683 #[tokio::test]
2684 async fn supervisor_list_logs_contended_snapshot_lock_only() {
2685 let registry = Arc::new(Registry::default());
2686 let handle = SupervisorHandle::new();
2687 let supervisor = Supervisor::new_for_test(Arc::clone(®istry), RestartPolicy::default())
2688 .with_handle(handle.clone());
2689 let module = supervisor
2690 .supervise_configured(
2691 ModuleSpec {
2692 carry_containment: false,
2693 module_id: "held-module".to_string(),
2694 program: "test-module".into(),
2695 args: Vec::new(),
2696 env: Vec::new(),
2697 reserved: false,
2698 reserved_prefixes: Vec::new(),
2699 protocol: ModuleProtocol::Subc,
2700 overlap: Default::default(),
2701 },
2702 false,
2703 )
2704 .expect("disabled test module is supervised");
2705 let router = Router::with_control_handler(Arc::new(
2706 ControlHandler::new(Arc::clone(®istry)).with_supervisor(handle),
2707 ));
2708 let (ctx, mut rx) = route_ctx();
2709 let (acquired, ready) = std_mpsc::channel();
2710 tokio::task::yield_now().await;
2713 let holder = module.hold_snapshot_for_test(acquired, Duration::from_millis(400));
2714 ready.recv().expect("holder acquired snapshot lock");
2715 let (output, guard) = log_capture(tracing::Level::WARN);
2716
2717 router
2718 .route_for_connection(&ctx, request(0, 44, br#"{"op":"supervisor.list"}"#))
2719 .await
2720 .expect("list request routes after the lock releases");
2721 assert!(
2722 rx.recv().await.is_some(),
2723 "list request receives a response"
2724 );
2725 holder.join().expect("snapshot holder exits cleanly");
2726 drop(guard);
2727
2728 let logs = captured_logs(&output);
2729 assert!(logs.contains("slow snapshot lock"));
2730 assert!(logs.contains("module_id=held-module"));
2731 assert!(logs.contains("caller=list"));
2732 assert!(
2733 logged_millis(&logs, "waited_ms=") >= 250,
2734 "wait must exceed the slow-lock threshold: {logs}"
2735 );
2736
2737 let (output, guard) = log_capture(tracing::Level::WARN);
2738 router
2739 .route_for_connection(&ctx, request(0, 45, br#"{"op":"supervisor.list"}"#))
2740 .await
2741 .expect("uncontended list request routes");
2742 assert!(
2743 rx.recv().await.is_some(),
2744 "uncontended list receives a response"
2745 );
2746 drop(guard);
2747 assert!(
2748 !captured_logs(&output).contains("slow snapshot lock"),
2749 "uncontended list acquisition must not warn"
2750 );
2751 }
2752
2753 #[tokio::test]
2754 async fn full_module_to_client_sink_requests_client_close_without_erroring_module() {
2755 let forwarding = Arc::new(ForwardingTable::default());
2756 let control = Arc::new(ControlHandler::with_forwarding(
2757 Arc::new(crate::Registry::default()),
2758 Arc::clone(&forwarding),
2759 ));
2760 let router = Router::with_control_handler(control);
2761 let module_connection = ConnectionId::new(10);
2762 let client_connection = ConnectionId::new(20);
2763 let mut close_receiver = forwarding.register_connection_close(client_connection);
2764 let (module_tx, _module_rx) = mpsc::channel(1);
2765 forwarding
2766 .register_module_connection(
2767 module_connection,
2768 "full-sink-provider".to_string(),
2769 1,
2770 Concurrency::ModuleManaged,
2771 FrameSink::new(module_tx),
2772 )
2773 .unwrap();
2774 let (client_tx, mut client_rx) = mpsc::channel(1);
2775 let pending = forwarding
2776 .begin_route_bind_relay_for_test(
2777 client_connection,
2778 FrameSink::new(client_tx),
2779 700,
2780 "full-sink-provider",
2781 )
2782 .unwrap();
2783 forwarding
2784 .complete_pending_relay(
2785 module_connection,
2786 pending.corr,
2787 RouteBindRelayOutcome::Accepted,
2788 )
2789 .unwrap();
2790
2791 let (module_egress_tx, _module_egress_rx) = mpsc::channel(1);
2792 let module_ctx = RouteCtx {
2793 connection_id: module_connection,
2794 egress: FrameSink::new(module_egress_tx),
2795 };
2796 let terminal = Frame::build(
2797 FrameType::Response,
2798 Flags::new(false, Priority::Interactive, true),
2799 pending.module_channel,
2800 pending.module_epoch,
2801 701,
2802 b"terminal".to_vec(),
2803 )
2804 .unwrap();
2805
2806 router
2807 .route_for_connection(&module_ctx, terminal)
2808 .await
2809 .unwrap();
2810 let reason = tokio::time::timeout(Duration::from_secs(1), &mut close_receiver)
2811 .await
2812 .expect("close request should be sent for the full client sink")
2813 .expect("close sender should include a reason");
2814 assert!(
2815 reason
2816 .to_string()
2817 .contains("module_to_client_delivery_failed"),
2818 "unexpected close reason: {reason}"
2819 );
2820 assert_eq!(client_rx.try_recv().unwrap().header.corr, 700);
2821 assert!(client_rx.try_recv().is_err());
2822 assert_eq!(
2823 router.counters.snapshot()["client_egress_close_delivery_failed"],
2824 1
2825 );
2826 }
2827
2828 #[tokio::test]
2832 async fn terminal_frame_releases_its_credit_even_when_client_delivery_fails() {
2833 let forwarding = Arc::new(ForwardingTable::default());
2834 let control = Arc::new(ControlHandler::with_forwarding(
2835 Arc::new(crate::Registry::default()),
2836 Arc::clone(&forwarding),
2837 ));
2838 let router = Router::with_control_handler(control);
2839 let module_connection = ConnectionId::new(11);
2840 let client_connection = ConnectionId::new(21);
2841 let _close_receiver = forwarding.register_connection_close(client_connection);
2842 let (module_tx, _module_rx) = mpsc::channel(1);
2843 forwarding
2844 .register_module_connection(
2845 module_connection,
2846 "credit-provider".to_string(),
2847 1,
2848 Concurrency::ModuleManaged,
2849 FrameSink::new(module_tx),
2850 )
2851 .unwrap();
2852 let (client_tx, _client_rx) = mpsc::channel(1);
2855 let pending = forwarding
2856 .begin_route_bind_relay_for_test(
2857 client_connection,
2858 FrameSink::new(client_tx),
2859 800,
2860 "credit-provider",
2861 )
2862 .unwrap();
2863 forwarding
2864 .complete_pending_relay(
2865 module_connection,
2866 pending.corr,
2867 RouteBindRelayOutcome::Accepted,
2868 )
2869 .unwrap();
2870 let DataRoute::Client(DataRouteState::Bound(route)) = forwarding
2871 .lookup_data_route(
2872 client_connection,
2873 pending.client_channel,
2874 pending.client_epoch,
2875 )
2876 .unwrap()
2877 else {
2878 panic!("expected a bound client route");
2879 };
2880 route.flow.acquire_tagged(801, false).await.unwrap();
2881 assert_eq!(route.flow.drain_in_flight(), 1);
2882
2883 let (module_egress_tx, _module_egress_rx) = mpsc::channel(1);
2884 let module_ctx = RouteCtx {
2885 connection_id: module_connection,
2886 egress: FrameSink::new(module_egress_tx),
2887 };
2888 let terminal = Frame::build(
2889 FrameType::Response,
2890 Flags::new(false, Priority::Interactive, true),
2891 pending.module_channel,
2892 pending.module_epoch,
2893 801,
2894 b"terminal".to_vec(),
2895 )
2896 .unwrap();
2897 router
2898 .route_for_connection(&module_ctx, terminal)
2899 .await
2900 .unwrap();
2901
2902 assert_eq!(
2903 router.counters.snapshot()["client_egress_close_delivery_failed"],
2904 1,
2905 "the client delivery must have failed for this test to mean anything"
2906 );
2907 assert_eq!(
2908 route.flow.drain_in_flight(),
2909 0,
2910 "the module's terminal frame must release its credit even though the client could not take it"
2911 );
2912 }
2913
2914 #[tokio::test]
2915 async fn full_route_goodbye_sink_requests_target_close_without_erroring_module() {
2916 let forwarding = Arc::new(ForwardingTable::default());
2917 let control = Arc::new(ControlHandler::with_forwarding(
2918 Arc::new(crate::Registry::default()),
2919 Arc::clone(&forwarding),
2920 ));
2921 let router = Router::with_control_handler(control);
2922 let module_connection = ConnectionId::new(30);
2923 let client_connection = ConnectionId::new(40);
2924 let mut close_receiver = forwarding.register_connection_close(client_connection);
2925 let (module_tx, _module_rx) = mpsc::channel(1);
2926 forwarding
2927 .register_module_connection(
2928 module_connection,
2929 "goodbye-full-provider".to_string(),
2930 1,
2931 Concurrency::ModuleManaged,
2932 FrameSink::new(module_tx),
2933 )
2934 .unwrap();
2935 let (client_tx, mut client_rx) = mpsc::channel(1);
2936 let pending = forwarding
2937 .begin_route_bind_relay_for_test(
2938 client_connection,
2939 FrameSink::new(client_tx),
2940 800,
2941 "goodbye-full-provider",
2942 )
2943 .unwrap();
2944 forwarding
2945 .complete_pending_relay(
2946 module_connection,
2947 pending.corr,
2948 RouteBindRelayOutcome::Accepted,
2949 )
2950 .unwrap();
2951
2952 let (module_egress_tx, _module_egress_rx) = mpsc::channel(1);
2953 let module_ctx = RouteCtx {
2954 connection_id: module_connection,
2955 egress: FrameSink::new(module_egress_tx),
2956 };
2957 let goodbye = Frame::build(
2958 FrameType::Goodbye,
2959 Flags::new(false, Priority::Passive, true),
2960 pending.module_channel,
2961 pending.module_epoch,
2962 801,
2963 Vec::new(),
2964 )
2965 .unwrap();
2966
2967 router
2968 .route_for_connection(&module_ctx, goodbye)
2969 .await
2970 .unwrap();
2971 let reason = tokio::time::timeout(Duration::from_secs(1), &mut close_receiver)
2972 .await
2973 .expect("close request should be sent for the full GOODBYE sink")
2974 .expect("close sender should include a reason");
2975 assert!(
2976 reason.to_string().contains("route_goodbye_delivery_failed"),
2977 "unexpected close reason: {reason}"
2978 );
2979 assert_eq!(client_rx.try_recv().unwrap().header.corr, 800);
2980 assert!(client_rx.try_recv().is_err());
2981 assert_eq!(router.counters.snapshot()["goodbye_relay_client_failed"], 1);
2982 assert_eq!(router.counters.snapshot()["route_released_epoch_fenced"], 1);
2983 }
2984
2985 async fn multi_route_client(
2990 module_id: &str,
2991 module_connection: ConnectionId,
2992 client_connection: ConnectionId,
2993 routes: usize,
2994 ) -> (
2995 Router,
2996 FrameSink,
2997 mpsc::Receiver<OutboundFrame>,
2998 RouteCtx,
2999 Vec<crate::forwarding::PendingRouteBindRelay>,
3000 ConnectionCloseReceiver,
3001 ) {
3002 let forwarding = Arc::new(ForwardingTable::default());
3003 let control = Arc::new(ControlHandler::with_forwarding(
3004 Arc::new(crate::Registry::default()),
3005 Arc::clone(&forwarding),
3006 ));
3007 let router = Router::with_control_handler(control);
3008 let close_receiver = forwarding.register_connection_close(client_connection);
3009 let (module_tx, _module_rx) = mpsc::channel(8);
3010 forwarding
3011 .register_module_connection(
3012 module_connection,
3013 module_id.to_string(),
3014 1,
3015 Concurrency::ModuleManaged,
3016 FrameSink::new(module_tx),
3017 )
3018 .unwrap();
3019 let (client_sink, mut client_rx) = crate::server::connection_egress();
3020 let mut bound = Vec::with_capacity(routes);
3021 for index in 0..routes {
3022 let pending = forwarding
3023 .begin_route_bind_relay_for_test(
3024 client_connection,
3025 client_sink.clone(),
3026 900 + index as u64,
3027 module_id,
3028 )
3029 .unwrap();
3030 forwarding
3031 .complete_pending_relay(
3032 module_connection,
3033 pending.corr,
3034 RouteBindRelayOutcome::Accepted,
3035 )
3036 .unwrap();
3037 assert_eq!(
3038 client_rx.recv().await.unwrap().header.corr,
3039 900 + index as u64
3040 );
3041 bound.push(pending);
3042 }
3043 let (module_egress_tx, _module_egress_rx) = mpsc::channel(8);
3044 let module_ctx = RouteCtx {
3045 connection_id: module_connection,
3046 egress: FrameSink::new(module_egress_tx),
3047 };
3048 (
3049 router,
3050 client_sink,
3051 client_rx,
3052 module_ctx,
3053 bound,
3054 close_receiver,
3055 )
3056 }
3057
3058 #[test]
3065 #[ignore = "timing measurement, run on demand"]
3066 fn egress_sink_per_frame_cost() {
3067 const FRAMES: usize = 1_000_000;
3068 const BATCH: usize = 1_000;
3069 let (sink, mut rx) = crate::server::connection_egress();
3070 let template = stream_frame(9, 1, 0, vec![b't'; 200]);
3071 let started = Instant::now();
3072 for _ in 0..FRAMES / BATCH {
3073 for _ in 0..BATCH {
3074 sink.try_send(template.clone()).unwrap();
3075 }
3076 for _ in 0..BATCH {
3077 let outbound = rx.try_recv().unwrap();
3078 if let Some(charge) = &outbound.charge {
3079 charge.taken_by_writer();
3080 }
3081 drop(std::hint::black_box(outbound));
3082 }
3083 }
3084 let elapsed = started.elapsed();
3085 assert_eq!(sink.backlog().queued_bytes, 0);
3086 println!(
3087 "egress sink: {FRAMES} frames in {elapsed:?}, {:.1} ns/frame",
3088 elapsed.as_nanos() as f64 / FRAMES as f64
3089 );
3090 }
3091
3092 fn stream_frame(channel: u16, epoch: u32, corr: u64, body: Vec<u8>) -> Frame {
3093 Frame::build(
3094 FrameType::StreamData,
3095 Flags::new(false, Priority::Interactive, false),
3096 channel,
3097 epoch,
3098 corr,
3099 body,
3100 )
3101 .unwrap()
3102 }
3103
3104 fn module_route_for_test(
3105 router: &Router,
3106 ctx: &RouteCtx,
3107 route: &crate::forwarding::PendingRouteBindRelay,
3108 ) -> Arc<RouteBinding> {
3109 match router
3110 .forwarding
3111 .lookup_data_route(ctx.connection_id, route.module_channel, route.module_epoch)
3112 .unwrap()
3113 {
3114 DataRoute::Module(DataRouteState::Bound(binding)) => binding,
3115 other => panic!("expected a bound module route, got {other:?}"),
3116 }
3117 }
3118
3119 fn assert_frame_size_error(frame: &Frame, channel: u16, epoch: u32, corr: u64, bytes: usize) {
3120 assert_eq!(frame.header.ty, FrameType::Error);
3121 assert_eq!(frame.header.channel, channel);
3122 assert_eq!(frame.header.epoch, epoch);
3123 assert_eq!(frame.header.corr, corr);
3124 assert!(frame.header.flags.is_daemon_origin());
3125 let body: ErrorBody = serde_json::from_slice(&frame.body).unwrap();
3126 assert_eq!(body.code, error_codes::FRAME_TOO_LARGE);
3127 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3128 assert!(body.message.contains(&bytes.to_string()));
3129 assert!(body.message.contains(&limit.to_string()));
3130 assert_eq!(
3131 body.detail,
3132 Some(serde_json::json!({ "frame_bytes": bytes, "byte_limit": limit }))
3133 );
3134 }
3135
3136 #[tokio::test]
3137 async fn module_egress_response_oversized_reply_keeps_connection_and_other_route() {
3138 let (logs, _guard) = test_log::log_capture(tracing::Level::WARN);
3139 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3140 "oversize-provider",
3141 ConnectionId::new(80),
3142 ConnectionId::new(81),
3143 2,
3144 )
3145 .await;
3146 let binding = module_route_for_test(&router, &ctx, &routes[0]);
3147 binding.flow.acquire_tagged(101, false).await.unwrap();
3148 module_route_for_test(&router, &ctx, &routes[1])
3149 .flow
3150 .acquire_tagged(102, false)
3151 .await
3152 .unwrap();
3153 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3154 let oversized = Frame::build(
3155 FrameType::Response,
3156 Flags::new(false, Priority::Interactive, true),
3157 routes[0].module_channel,
3158 routes[0].module_epoch,
3159 101,
3160 vec![b'x'; limit - subc_protocol::HEADER_LEN + 1],
3161 )
3162 .unwrap();
3163 assert_eq!(sink.backlog().queued_bytes, 0);
3164 router.route_for_connection(&ctx, oversized).await.unwrap();
3165
3166 router
3170 .route_for_connection(
3171 &ctx,
3172 route_frame(
3173 FrameType::Response,
3174 routes[1].module_channel,
3175 routes[1].module_epoch,
3176 102,
3177 ),
3178 )
3179 .await
3180 .unwrap();
3181 assert!(
3182 close.try_recv().is_err(),
3183 "an oversized reply must not close the multiplexed client"
3184 );
3185 let error = rx.try_recv().expect("the waiting client gets an ERROR");
3186 assert_frame_size_error(
3187 &error,
3188 routes[0].client_channel,
3189 routes[0].client_epoch,
3190 101,
3191 limit + 1,
3192 );
3193 let second = rx.try_recv().expect("the other route's reply arrives");
3194 assert_eq!(second.header.ty, FrameType::Response);
3195 assert_eq!(second.header.channel, routes[1].client_channel);
3196 assert_eq!(second.header.epoch, routes[1].client_epoch);
3197 assert_eq!(second.header.corr, 102);
3198 assert_eq!(second.body, b"route-body");
3199 assert_eq!(binding.flow.drain_in_flight(), 0);
3200 for route in &routes {
3201 module_route_for_test(&router, &ctx, route);
3202 }
3203 assert!(rx.try_recv().is_err());
3204 drop((error, second));
3205 assert_eq!(sink.backlog().queued_bytes, 0);
3206 assert_eq!(
3207 router.counters.snapshot()["client_egress_close_delivery_failed"],
3208 0
3209 );
3210
3211 let captured = test_log::captured_logs(&logs);
3212 let warnings: Vec<_> = captured
3213 .lines()
3214 .filter(|line| line.contains("WARN"))
3215 .collect();
3216 assert_eq!(warnings.len(), 1, "{captured}");
3217 let warning = warnings[0];
3218 for expected in [
3219 "module_id=oversize-provider".to_string(),
3220 "client_principal=direct".to_string(),
3221 format!("client_channel={}", routes[0].client_channel),
3222 format!("frame_bytes={}", limit + 1),
3223 format!("byte_limit={limit}"),
3224 ] {
3225 assert!(warning.contains(&expected), "missing {expected}: {warning}");
3226 }
3227 }
3228
3229 async fn poll_once<F: std::future::Future>(
3230 mut future: std::pin::Pin<&mut F>,
3231 ) -> std::task::Poll<F::Output> {
3232 std::future::poll_fn(|cx| std::task::Poll::Ready(future.as_mut().poll(cx))).await
3233 }
3234
3235 fn fill_client_budget(sink: &FrameSink, route: &crate::forwarding::PendingRouteBindRelay) {
3236 sink.try_send(
3237 Frame::build(
3238 FrameType::Response,
3239 Flags::new(false, Priority::Interactive, true),
3240 route.client_channel,
3241 route.client_epoch,
3242 100,
3243 vec![
3244 b'x';
3245 crate::server::CONNECTION_EGRESS_BYTE_BUDGET - subc_protocol::HEADER_LEN
3246 ],
3247 )
3248 .unwrap(),
3249 )
3250 .unwrap();
3251 assert_eq!(
3252 sink.backlog().queued_bytes,
3253 crate::server::CONNECTION_EGRESS_BYTE_BUDGET
3254 );
3255 }
3256
3257 async fn assert_full_client_burst_survives(ty: FrameType, oversized: bool) {
3258 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3259 "draining-burst",
3260 ConnectionId::new(92),
3261 ConnectionId::new(93),
3262 2,
3263 )
3264 .await;
3265 fill_client_budget(&sink, &routes[0]);
3266 let frame = if oversized {
3267 Frame::build(
3268 ty,
3269 Flags::new(false, Priority::Interactive, false),
3270 routes[1].module_channel,
3271 routes[1].module_epoch,
3272 101,
3273 vec![b's'; crate::server::CONNECTION_EGRESS_BYTE_BUDGET],
3274 )
3275 .unwrap()
3276 } else {
3277 route_frame(ty, routes[1].module_channel, routes[1].module_epoch, 101)
3278 };
3279 let mut delivery = Box::pin(router.route_for_connection(&ctx, frame));
3280 assert!(poll_once(delivery.as_mut()).await.is_pending());
3281 assert!(
3282 close.try_recv().is_err(),
3283 "fresh bursts must not close: {ty:?}"
3284 );
3285 tokio::time::advance(Duration::from_millis(50)).await;
3286 let queued = rx.try_recv().unwrap();
3287 queued.charge.as_ref().unwrap().taken_by_writer();
3288 drop(queued);
3289 assert!(matches!(
3290 poll_once(delivery.as_mut()).await,
3291 std::task::Poll::Ready(Ok(()))
3292 ));
3293 let delivered = rx
3294 .try_recv()
3295 .expect("the burst frame must be delivered after draining");
3296 assert_eq!(delivered.header.channel, routes[1].client_channel);
3297 assert_eq!(delivered.header.epoch, routes[1].client_epoch);
3298 assert_eq!(delivered.header.corr, 101);
3299 if oversized {
3300 assert_frame_size_error(
3301 &delivered,
3302 routes[1].client_channel,
3303 routes[1].client_epoch,
3304 101,
3305 crate::server::CONNECTION_EGRESS_BYTE_BUDGET + subc_protocol::HEADER_LEN,
3306 );
3307 } else {
3308 assert_eq!(delivered.header.ty, ty);
3309 }
3310 assert!(rx.try_recv().is_err());
3311 assert!(close.try_recv().is_err());
3312 assert_eq!(
3313 router.counters.snapshot()["client_egress_close_delivery_failed"],
3314 0
3315 );
3316 assert_eq!(router.counters.snapshot()["goodbye_relay_client_failed"], 0);
3317 }
3318
3319 #[tokio::test(start_paused = true)]
3320 async fn module_egress_fresh_full_queue_burst_survives() {
3321 for ty in [
3322 FrameType::Response,
3323 FrameType::StreamData,
3324 FrameType::Request,
3325 FrameType::Push,
3326 ] {
3327 assert_full_client_burst_survives(ty, false).await;
3328 }
3329 }
3330
3331 #[tokio::test(start_paused = true)]
3332 async fn module_goodbye_fresh_full_queue_burst_survives() {
3333 assert_full_client_burst_survives(FrameType::Goodbye, false).await;
3334 }
3335
3336 #[tokio::test(start_paused = true)]
3337 async fn frame_count_backstop_also_allows_a_draining_burst() {
3338 let (tx, mut rx) = mpsc::channel(1);
3339 let sink = FrameSink::with_byte_budget(tx, 2_000);
3340 sink.try_send(stream_frame(1, 1, 1, vec![b'x'; 100]))
3341 .unwrap();
3342 let mut delivery = Box::pin(sink.send_to_client(stream_frame(1, 1, 2, vec![b'y'; 100])));
3343 assert!(poll_once(delivery.as_mut()).await.is_pending());
3344 assert!(
3345 sink.backlog().queued_bytes < 2_000,
3346 "only frame capacity is exhausted"
3347 );
3348 tokio::time::advance(Duration::from_millis(50)).await;
3349 drop(rx.try_recv().unwrap());
3350 assert!(matches!(
3351 poll_once(delivery.as_mut()).await,
3352 std::task::Poll::Ready(Ok(()))
3353 ));
3354 assert_eq!(rx.try_recv().unwrap().header.corr, 2);
3355 }
3356
3357 #[tokio::test(start_paused = true)]
3358 async fn oversized_reply_replacement_fresh_full_queue_burst_survives() {
3359 for ty in [FrameType::Response, FrameType::StreamData] {
3360 assert_full_client_burst_survives(ty, true).await;
3361 }
3362 }
3363
3364 #[tokio::test(start_paused = true)]
3365 async fn module_egress_stopped_reader_closes_without_waiting() {
3366 let (logs, _guard) = test_log::log_capture(tracing::Level::WARN);
3367 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3368 "oldest-stopped-reader",
3369 ConnectionId::new(94),
3370 ConnectionId::new(95),
3371 2,
3372 )
3373 .await;
3374 fill_client_budget(&sink, &routes[0]);
3375 let writing = rx.try_recv().unwrap();
3378 writing.charge.as_ref().unwrap().taken_by_writer();
3379 tokio::time::advance(Duration::from_millis(251)).await;
3380 assert_eq!(sink.backlog().oldest_age, Some(Duration::from_millis(251)));
3381 assert_eq!(sink.backlog().queued_bytes, queued_frame_bytes(&writing));
3382 let started = tokio::time::Instant::now();
3383 let frame = stream_frame(
3384 routes[0].module_channel,
3385 routes[0].module_epoch,
3386 101,
3387 b"secret-body-never-log".to_vec(),
3388 );
3389 let flags = frame.header.flags.0;
3390 let mut delivery = Box::pin(router.route_for_connection(&ctx, frame));
3391 assert!(
3392 matches!(
3393 poll_once(delivery.as_mut()).await,
3394 std::task::Poll::Ready(Ok(()))
3395 ),
3396 "an oldest frame older than 250 ms must close immediately, without a new wait"
3397 );
3398 assert_eq!(started.elapsed(), Duration::ZERO);
3399 assert!(close
3400 .try_recv()
3401 .unwrap()
3402 .to_string()
3403 .contains("module_to_client_delivery_failed"));
3404 let captured = test_log::captured_logs(&logs);
3405 for expected in [
3406 "frame_type=Some(StreamData)".to_string(),
3407 format!("frame_flags=Some({flags})"),
3408 "oldest_queued_ms=251".to_string(),
3409 "close_cause=\"oldest_frame_older_than_250_ms\"".to_string(),
3410 ] {
3411 assert!(
3412 captured.contains(&expected),
3413 "missing {expected}: {captured}"
3414 );
3415 }
3416 assert!(!captured.contains("secret-body-never-log"));
3417 }
3418
3419 #[tokio::test(start_paused = true)]
3420 async fn client_gone_mid_wait_resumes_module_reader_immediately() {
3421 for writer_gone in [false, true] {
3422 let (router, sink, mut rx, ctx, routes, _close) = multi_route_client(
3423 "gone-during-burst",
3424 ConnectionId::new(96),
3425 ConnectionId::new(97),
3426 1,
3427 )
3428 .await;
3429 fill_client_budget(&sink, &routes[0]);
3430 let frame = route_frame(
3431 FrameType::Response,
3432 routes[0].module_channel,
3433 routes[0].module_epoch,
3434 101,
3435 );
3436 let mut delivery = Box::pin(router.route_for_connection(&ctx, frame));
3437 assert!(poll_once(delivery.as_mut()).await.is_pending());
3438 tokio::time::advance(Duration::from_millis(50)).await;
3439 let started = tokio::time::Instant::now();
3440 if writer_gone {
3441 rx.close();
3442 } else {
3443 sink.close_client_delivery();
3444 }
3445 assert!(
3446 matches!(
3447 poll_once(delivery.as_mut()).await,
3448 std::task::Poll::Ready(Ok(()))
3449 ),
3450 "client teardown must wake the module reader before the writer drains"
3451 );
3452 assert_eq!(started.elapsed(), Duration::ZERO);
3453 assert_eq!(sink.accounting.waiters.load(Ordering::SeqCst), 0);
3454 assert_eq!(rx.try_recv().unwrap().header.corr, 100);
3455 assert!(rx.try_recv().is_err());
3456 }
3457 }
3458
3459 #[tokio::test(start_paused = true)]
3460 async fn cancelled_module_delivery_releases_waiter_without_closing_client() {
3461 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3462 "cancelled-burst",
3463 ConnectionId::new(98),
3464 ConnectionId::new(99),
3465 1,
3466 )
3467 .await;
3468 fill_client_budget(&sink, &routes[0]);
3469 let frame = route_frame(
3470 FrameType::Response,
3471 routes[0].module_channel,
3472 routes[0].module_epoch,
3473 101,
3474 );
3475 let mut delivery = Box::pin(router.route_for_connection(&ctx, frame));
3476 assert!(poll_once(delivery.as_mut()).await.is_pending());
3477 assert_eq!(sink.accounting.waiters.load(Ordering::SeqCst), 1);
3478 drop(delivery);
3479 assert_eq!(sink.accounting.waiters.load(Ordering::SeqCst), 0);
3480 tokio::time::advance(Duration::from_secs(1)).await;
3481 assert!(close.try_recv().is_err());
3482 drop(rx.try_recv().unwrap());
3483 assert_eq!(sink.backlog().queued_bytes, 0);
3484 assert!(sink.backlog().oldest_age.is_none());
3485 }
3486
3487 #[tokio::test(start_paused = true)]
3488 async fn egress_atomic_age_follows_writer_and_clears_when_drained() {
3489 let (sink, mut rx) = crate::server::connection_egress();
3490 sink.try_send(stream_frame(1, 1, 1, vec![b'x'; 100]))
3491 .unwrap();
3492 tokio::time::advance(Duration::from_millis(200)).await;
3493 sink.try_send(stream_frame(2, 1, 2, vec![b'y'; 100]))
3494 .unwrap();
3495 let writing = rx.try_recv().unwrap();
3496 writing.charge.as_ref().unwrap().taken_by_writer();
3497 assert_eq!(sink.backlog().oldest_age, Some(Duration::from_millis(200)));
3498 drop(writing);
3499 assert_eq!(sink.backlog().oldest_age, Some(Duration::from_millis(200)));
3502 tokio::time::advance(Duration::from_millis(50)).await;
3503 let next = rx.try_recv().unwrap();
3504 next.charge.as_ref().unwrap().taken_by_writer();
3505 assert_eq!(sink.backlog().oldest_age, Some(Duration::from_millis(50)));
3506 assert!(
3507 sink.backlog().queued_bytes > 0,
3508 "in-flight bytes remain charged until written"
3509 );
3510 drop(next);
3511 assert_eq!(sink.backlog().queued_bytes, 0);
3512 assert_eq!(sink.backlog().oldest_age, None);
3513 }
3514
3515 #[tokio::test(start_paused = true)]
3516 async fn module_egress_response_full_client_waits_only_remaining_grace() {
3517 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3518 "backpressure-provider",
3519 ConnectionId::new(82),
3520 ConnectionId::new(83),
3521 2,
3522 )
3523 .await;
3524 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3525 router
3528 .route_for_connection(
3529 &ctx,
3530 Frame::build(
3531 FrameType::Response,
3532 Flags::new(false, Priority::Interactive, true),
3533 routes[0].module_channel,
3534 routes[0].module_epoch,
3535 201,
3536 vec![b'x'; limit - subc_protocol::HEADER_LEN],
3537 )
3538 .unwrap(),
3539 )
3540 .await
3541 .unwrap();
3542 assert_eq!(sink.backlog().queued_bytes, limit);
3543 assert_eq!(sink.backlog().queued_frames, 1);
3544 let ordinary = route_frame(
3545 FrameType::Response,
3546 routes[1].module_channel,
3547 routes[1].module_epoch,
3548 202,
3549 );
3550 assert!(queued_frame_bytes(&ordinary) < limit);
3551 tokio::time::advance(Duration::from_millis(100)).await;
3554 let mut delivery = Box::pin(router.route_for_connection(&ctx, ordinary));
3555 assert!(poll_once(delivery.as_mut()).await.is_pending());
3556 assert!(close.try_recv().is_err());
3557 tokio::time::advance(Duration::from_millis(149)).await;
3558 assert!(poll_once(delivery.as_mut()).await.is_pending());
3559 assert!(close.try_recv().is_err());
3560 tokio::time::advance(Duration::from_millis(1)).await;
3561 assert!(matches!(
3562 poll_once(delivery.as_mut()).await,
3563 std::task::Poll::Ready(Ok(()))
3564 ));
3565 drop(delivery);
3566 let reason = close.try_recv().expect("the full client must close");
3567 assert!(reason
3568 .to_string()
3569 .contains("module_to_client_delivery_failed"));
3570 assert!(!reason.to_string().contains("frame_too_large"));
3571 assert_eq!(
3572 router.counters.snapshot()["client_egress_close_delivery_failed"],
3573 1
3574 );
3575 let admitted = rx.try_recv().expect("the budget-sized frame was admitted");
3576 assert_eq!(admitted.header.ty, FrameType::Response);
3577 assert_eq!(admitted.header.corr, 201);
3578 assert!(
3579 rx.try_recv().is_err(),
3580 "no oversized-frame ERROR is substituted for backpressure"
3581 );
3582 }
3583
3584 #[tokio::test(start_paused = true)]
3585 async fn oversized_reply_to_a_full_client_waits_only_remaining_grace() {
3586 let (router, sink, _rx, ctx, routes, mut close) = multi_route_client(
3587 "full-oversize-provider",
3588 ConnectionId::new(90),
3589 ConnectionId::new(91),
3590 2,
3591 )
3592 .await;
3593 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3594 router
3596 .route_for_connection(
3597 &ctx,
3598 Frame::build(
3599 FrameType::Response,
3600 Flags::new(false, Priority::Interactive, true),
3601 routes[0].module_channel,
3602 routes[0].module_epoch,
3603 501,
3604 vec![b'x'; limit - subc_protocol::HEADER_LEN],
3605 )
3606 .unwrap(),
3607 )
3608 .await
3609 .unwrap();
3610 assert_eq!(sink.backlog().queued_bytes, limit);
3611 let oversized = Frame::build(
3612 FrameType::Response,
3613 Flags::new(false, Priority::Interactive, true),
3614 routes[1].module_channel,
3615 routes[1].module_epoch,
3616 502,
3617 vec![b'y'; limit - subc_protocol::HEADER_LEN + 1],
3618 )
3619 .unwrap();
3620 tokio::time::advance(Duration::from_millis(80)).await;
3623 let mut delivery = Box::pin(router.route_for_connection(&ctx, oversized));
3624 assert!(poll_once(delivery.as_mut()).await.is_pending());
3625 assert!(close.try_recv().is_err());
3626 tokio::time::advance(Duration::from_millis(169)).await;
3627 assert!(poll_once(delivery.as_mut()).await.is_pending());
3628 assert!(close.try_recv().is_err());
3629 tokio::time::advance(Duration::from_millis(1)).await;
3630 assert!(matches!(
3631 poll_once(delivery.as_mut()).await,
3632 std::task::Poll::Ready(Ok(()))
3633 ));
3634 drop(delivery);
3635 let reason = close.try_recv().expect("the full client must close");
3636 assert!(reason
3637 .to_string()
3638 .contains("module_to_client_delivery_failed"));
3639 }
3640
3641 #[tokio::test]
3642 async fn oversized_reverse_request_errors_module_without_reaching_client() {
3643 let (router, _sink, mut rx, mut ctx, routes, mut close) = multi_route_client(
3644 "reverse-oversize-provider",
3645 ConnectionId::new(84),
3646 ConnectionId::new(85),
3647 2,
3648 )
3649 .await;
3650 let (module_tx, mut module_rx) = mpsc::channel(8);
3651 ctx.egress = FrameSink::new(module_tx);
3652 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3653 router
3654 .route_for_connection(
3655 &ctx,
3656 Frame::build(
3657 FrameType::Request,
3658 Flags::new(false, Priority::Interactive, false),
3659 routes[0].module_channel,
3660 routes[0].module_epoch,
3661 301,
3662 vec![b'r'; limit - subc_protocol::HEADER_LEN + 1],
3663 )
3664 .unwrap(),
3665 )
3666 .await
3667 .unwrap();
3668 assert!(
3669 rx.try_recv().is_err(),
3670 "the reverse request never reaches the client"
3671 );
3672 let error = module_rx.try_recv().expect("the module gets the refusal");
3673 assert_frame_size_error(
3674 &error,
3675 routes[0].module_channel,
3676 routes[0].module_epoch,
3677 301,
3678 limit + 1,
3679 );
3680 assert!(module_rx.try_recv().is_err());
3681 for (index, route) in routes.iter().enumerate() {
3682 module_route_for_test(&router, &ctx, route);
3683 router
3684 .route_for_connection(
3685 &ctx,
3686 route_frame(
3687 FrameType::Response,
3688 route.module_channel,
3689 route.module_epoch,
3690 302 + index as u64,
3691 ),
3692 )
3693 .await
3694 .unwrap();
3695 let reply = rx.try_recv().expect("both routes still deliver");
3696 assert_eq!(reply.header.ty, FrameType::Response);
3697 assert_eq!(reply.header.channel, route.client_channel);
3698 }
3699 assert!(close.try_recv().is_err());
3700 assert_eq!(
3701 router.counters.snapshot()["client_egress_close_delivery_failed"],
3702 0
3703 );
3704 }
3705
3706 #[tokio::test]
3707 async fn oversized_push_closes_client_with_precise_warn() {
3708 let (logs, _guard) = test_log::log_capture(tracing::Level::WARN);
3709 let (router, _sink, mut rx, ctx, routes, mut close) = multi_route_client(
3710 "push-oversize-provider",
3711 ConnectionId::new(86),
3712 ConnectionId::new(87),
3713 2,
3714 )
3715 .await;
3716 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3717 router
3718 .route_for_connection(
3719 &ctx,
3720 Frame::build(
3721 FrameType::Push,
3722 Flags::new(false, Priority::Interactive, false),
3723 routes[0].module_channel,
3724 routes[0].module_epoch,
3725 0,
3726 vec![b'p'; limit - subc_protocol::HEADER_LEN + 1],
3727 )
3728 .unwrap(),
3729 )
3730 .await
3731 .unwrap();
3732 let reason = close
3733 .try_recv()
3734 .expect("unsolicited oversize still closes the client");
3735 assert!(reason
3736 .to_string()
3737 .contains("frame_too_large: oversized push"));
3738 assert!(
3739 rx.try_recv().is_err(),
3740 "no part of the oversized push is forwarded"
3741 );
3742 let captured = test_log::captured_logs(&logs);
3743 let warnings: Vec<_> = captured
3744 .lines()
3745 .filter(|line| line.contains("WARN"))
3746 .collect();
3747 assert_eq!(warnings.len(), 1, "{captured}");
3748 let warning = warnings[0];
3749 for expected in [
3750 "oversized push".to_string(),
3751 "module_id=\"push-oversize-provider\"".to_string(),
3752 "principals=direct".to_string(),
3753 format!("client_channel={}", routes[0].client_channel),
3754 format!("size={}", limit + 1),
3755 format!("limit={limit}"),
3756 ] {
3757 assert!(warning.contains(&expected), "missing {expected}: {warning}");
3758 }
3759 assert_eq!(
3760 router.counters.snapshot()["client_egress_close_delivery_failed"],
3761 1
3762 );
3763 }
3764
3765 #[tokio::test]
3766 async fn oversized_stream_and_error_frames_end_request_even_with_queued_traffic() {
3767 let (router, sink, mut rx, ctx, routes, mut close) = multi_route_client(
3768 "stream-oversize-provider",
3769 ConnectionId::new(88),
3770 ConnectionId::new(89),
3771 2,
3772 )
3773 .await;
3774 let binding = module_route_for_test(&router, &ctx, &routes[0]);
3775 let limit = crate::server::CONNECTION_EGRESS_BYTE_BUDGET;
3776 for ty in [
3777 FrameType::StreamData,
3778 FrameType::StreamEnd,
3779 FrameType::Error,
3780 ] {
3781 binding.flow.acquire_tagged(401, false).await.unwrap();
3782 sink.try_send(route_frame(
3783 FrameType::Response,
3784 routes[1].client_channel,
3785 routes[1].client_epoch,
3786 402,
3787 ))
3788 .unwrap();
3789 router
3790 .route_for_connection(
3791 &ctx,
3792 Frame::build(
3793 ty,
3794 Flags::new(false, Priority::Interactive, false),
3795 routes[0].module_channel,
3796 routes[0].module_epoch,
3797 401,
3798 vec![b's'; limit - subc_protocol::HEADER_LEN + 1],
3799 )
3800 .unwrap(),
3801 )
3802 .await
3803 .unwrap();
3804 assert!(close.try_recv().is_err());
3805 assert_eq!(rx.try_recv().unwrap().header.corr, 402);
3806 let error = rx
3807 .try_recv()
3808 .expect("every correlated oversize frame becomes ERROR");
3809 assert_frame_size_error(
3810 &error,
3811 routes[0].client_channel,
3812 routes[0].client_epoch,
3813 401,
3814 limit + 1,
3815 );
3816 assert_eq!(binding.flow.drain_in_flight(), 0, "{ty:?} ends the request");
3817 assert!(rx.try_recv().is_err());
3818 }
3819 }
3820
3821 #[tokio::test]
3827 async fn awaited_send_parked_behind_a_full_byte_budget_wakes_when_bytes_free() {
3828 let (tx, mut rx) = mpsc::channel(1024);
3829 let sink = FrameSink::with_byte_budget(tx, 2_000);
3830 let mut queued = 0u64;
3831 while sink
3832 .try_send(stream_frame(7, 1, queued, vec![b'x'; 200]))
3833 .is_ok()
3834 {
3835 queued += 1;
3836 }
3837 assert!(queued > 0, "the budget admitted nothing");
3838
3839 let parked = tokio::spawn({
3840 let sink = sink.clone();
3841 async move { sink.send(stream_frame(0, 0, 999, vec![b'r'; 200])).await }
3842 });
3843 tokio::time::sleep(Duration::from_millis(100)).await;
3844 assert!(
3845 !parked.is_finished(),
3846 "the awaited send must wait while the byte budget is full"
3847 );
3848
3849 drop(rx.recv().await.expect("a queued frame"));
3851 tokio::time::timeout(Duration::from_secs(2), parked)
3852 .await
3853 .expect("the parked send was never woken after bytes were freed")
3854 .unwrap()
3855 .unwrap();
3856 }
3857
3858 #[tokio::test]
3863 async fn paused_client_reader_keeps_connection_through_small_frame_burst() {
3864 const ROUTES: usize = 4;
3865 const FRAMES_PER_ROUTE: usize = 250;
3866 let (router, client_sink, mut client_rx, module_ctx, routes, mut close_receiver) =
3867 multi_route_client(
3868 "burst-provider",
3869 ConnectionId::new(60),
3870 ConnectionId::new(61),
3871 ROUTES,
3872 )
3873 .await;
3874
3875 for seq in 0..FRAMES_PER_ROUTE as u64 {
3877 for (index, route) in routes.iter().enumerate() {
3878 let body = format!("route-{index}-token-{seq:05}-{}", "t".repeat(170));
3879 router
3880 .route_for_connection(
3881 &module_ctx,
3882 stream_frame(
3883 route.module_channel,
3884 route.module_epoch,
3885 seq,
3886 body.into_bytes(),
3887 ),
3888 )
3889 .await
3890 .unwrap();
3891 }
3892 }
3893
3894 let backlog = client_sink.backlog();
3895 assert_eq!(backlog.queued_frames, ROUTES * FRAMES_PER_ROUTE);
3896 assert!(backlog.queued_bytes < crate::server::CONNECTION_EGRESS_BYTE_BUDGET);
3897 assert!(
3898 close_receiver.try_recv().is_err(),
3899 "a paused reader under the byte budget must not be closed"
3900 );
3901 assert_eq!(
3902 router.counters.snapshot()["client_egress_close_delivery_failed"],
3903 0
3904 );
3905
3906 let mut next_seq = vec![0u64; ROUTES];
3908 for _ in 0..ROUTES * FRAMES_PER_ROUTE {
3909 let frame = client_rx.try_recv().expect("every queued frame arrives");
3910 let index = routes
3911 .iter()
3912 .position(|route| route.client_channel == frame.header.channel)
3913 .expect("frame arrives on one of the bound client channels");
3914 assert_eq!(frame.header.corr, next_seq[index], "route {index} order");
3915 let expected_prefix = format!("route-{index}-token-{:05}-", next_seq[index]);
3916 assert!(frame.body.starts_with(expected_prefix.as_bytes()));
3917 next_seq[index] += 1;
3918 }
3919 assert!(client_rx.try_recv().is_err());
3920 assert_eq!(next_seq, vec![FRAMES_PER_ROUTE as u64; ROUTES]);
3921 assert_eq!(client_sink.backlog().queued_bytes, 0);
3922 }
3923
3924 #[tokio::test(start_paused = true)]
3927 async fn never_reading_client_is_closed_at_byte_budget_with_warn_diagnosis() {
3928 let (logs, _guard) = test_log::log_capture(tracing::Level::WARN);
3929 const BODY: usize = 16 * 1024;
3930 let (router, client_sink, _client_rx, module_ctx, routes, mut close_receiver) =
3931 multi_route_client(
3932 "stuck-reader-provider",
3933 ConnectionId::new(70),
3934 ConnectionId::new(71),
3935 2,
3936 )
3937 .await;
3938
3939 let mut admitted = 0usize;
3940 let mut sent = 0u64;
3941 let started = tokio::time::Instant::now();
3942 while router.counters.snapshot()["client_egress_close_delivery_failed"] == 0 {
3943 assert!(sent < 1_000, "the byte budget never refused a frame");
3944 let route = &routes[(sent % 2) as usize];
3945 router
3946 .route_for_connection(
3947 &module_ctx,
3948 stream_frame(
3949 route.module_channel,
3950 route.module_epoch,
3951 sent,
3952 vec![b'z'; BODY],
3953 ),
3954 )
3955 .await
3956 .unwrap();
3957 sent += 1;
3958 admitted = client_sink.backlog().queued_frames;
3959 }
3960 assert_eq!(
3961 started.elapsed(),
3962 crate::server::CONNECTION_EGRESS_STALL_GRACE
3963 );
3964 let frame_bytes = subc_protocol::HEADER_LEN + BODY;
3966 assert_eq!(
3967 admitted,
3968 crate::server::CONNECTION_EGRESS_BYTE_BUDGET / frame_bytes
3969 );
3970 let reason = close_receiver
3971 .try_recv()
3972 .expect("the client connection must be asked to close");
3973 assert!(reason
3974 .to_string()
3975 .contains("module_to_client_delivery_failed"));
3976
3977 router
3979 .route_for_connection(
3980 &module_ctx,
3981 stream_frame(
3982 routes[0].module_channel,
3983 routes[0].module_epoch,
3984 sent,
3985 vec![b'z'; BODY],
3986 ),
3987 )
3988 .await
3989 .unwrap();
3990
3991 let captured = test_log::captured_logs(&logs);
3992 let warn_lines = captured
3993 .lines()
3994 .filter(|line| {
3995 line.contains("closing client connection: its egress queue could not take a frame")
3996 })
3997 .collect::<Vec<_>>();
3998 assert_eq!(warn_lines.len(), 1, "exactly one WARN, got: {captured}");
3999 let line = warn_lines[0];
4000 assert!(line.contains("WARN"), "{line}");
4001 assert!(line.contains("connection_id=71"), "{line}");
4002 assert!(
4003 line.contains("module_id=\"stuck-reader-provider\""),
4004 "{line}"
4005 );
4006 assert!(line.contains("client_channel="), "{line}");
4007 assert!(line.contains("principals=direct"), "{line}");
4008 let queued_bytes: usize = line
4009 .split("queued_bytes=")
4010 .nth(1)
4011 .and_then(|rest| rest.split_whitespace().next())
4012 .and_then(|value| value.parse().ok())
4013 .expect("queued_bytes is logged");
4014 assert_eq!(queued_bytes, admitted * frame_bytes);
4015 assert!(
4016 line.contains(&format!("queued_frames={admitted}")),
4017 "{line}"
4018 );
4019 assert!(line.contains("oldest_queued_ms="), "{line}");
4020 assert!(line.contains("oldest_queued_ms=250"), "{line}");
4021 assert!(line.contains("frame_type=Some(StreamData)"), "{line}");
4022 assert!(
4023 line.contains(&format!(
4024 "frame_flags=Some({})",
4025 Flags::new(false, Priority::Interactive, false).0
4026 )),
4027 "{line}"
4028 );
4029 assert!(
4030 line.contains("close_cause=\"waited_250_ms_without_room\""),
4031 "{line}"
4032 );
4033 assert!(
4034 !line.contains(&"z".repeat(20)),
4035 "body bytes must never be logged: {line}"
4036 );
4037 }
4038
4039 fn route_frame(ty: FrameType, channel: u16, epoch: u32, corr: u64) -> Frame {
4040 Frame::build(
4041 ty,
4042 Flags::new(false, Priority::Interactive, false),
4043 channel,
4044 epoch,
4045 corr,
4046 if ty == FrameType::Request || ty == FrameType::Response {
4047 b"route-body".to_vec()
4048 } else {
4049 Vec::new()
4050 },
4051 )
4052 .unwrap()
4053 }
4054
4055 type DynamicRouteFixture = (
4056 Router,
4057 Arc<ForwardingTable>,
4058 RouteCtx,
4059 mpsc::Receiver<crate::router::OutboundFrame>,
4060 RouteCtx,
4061 mpsc::Receiver<crate::router::OutboundFrame>,
4062 mpsc::Receiver<crate::router::OutboundFrame>,
4063 crate::forwarding::PendingRouteBindRelay,
4064 );
4065
4066 fn dynamic_route_fixture(commit: bool) -> DynamicRouteFixture {
4067 dynamic_route_fixture_with_busy(commit, false)
4068 }
4069
4070 fn dynamic_route_fixture_with_busy(commit: bool, busy_refusals: bool) -> DynamicRouteFixture {
4071 let forwarding = Arc::new(ForwardingTable::default());
4072 let control = Arc::new(crate::ControlHandler::with_forwarding(
4073 Arc::new(crate::Registry::default()),
4074 Arc::clone(&forwarding),
4075 ));
4076 let router = Router::with_control_handler(control);
4077 let module_connection = ConnectionId::new(500);
4078 let client_connection = ConnectionId::new(501);
4079 let (module_tx, module_rx) = mpsc::channel(if busy_refusals { 64 } else { 8 });
4080 forwarding
4081 .register_module_connection(
4082 module_connection,
4083 "epoch-router".into(),
4084 2,
4085 Concurrency::ModuleManaged,
4086 FrameSink::new(module_tx),
4087 )
4088 .unwrap();
4089 let (client_tx, client_rx) = mpsc::channel(if busy_refusals { 64 } else { 8 });
4090 let client_sink = FrameSink::new(client_tx);
4091 let pending = forwarding
4092 .begin_route_bind_relay_with_busy_for_test(
4093 client_connection,
4094 client_sink.clone(),
4095 700,
4096 "epoch-router",
4097 busy_refusals,
4098 )
4099 .unwrap();
4100 if commit {
4101 forwarding
4102 .complete_pending_relay(
4103 module_connection,
4104 pending.corr,
4105 RouteBindRelayOutcome::Accepted,
4106 )
4107 .unwrap();
4108 }
4109 let (module_egress_tx, module_egress_rx) = mpsc::channel(8);
4110 (
4111 router,
4112 forwarding,
4113 RouteCtx {
4114 connection_id: client_connection,
4115 egress: client_sink,
4116 },
4117 client_rx,
4118 RouteCtx {
4119 connection_id: module_connection,
4120 egress: FrameSink::new(module_egress_tx),
4121 },
4122 module_egress_rx,
4123 module_rx,
4124 pending,
4125 )
4126 }
4127
4128 #[tokio::test]
4129 async fn route_epochs_validate_both_directions_and_rewrite_to_peer_handle() {
4130 let (
4131 router,
4132 _forwarding,
4133 client_ctx,
4134 mut client_rx,
4135 module_ctx,
4136 _module_egress_rx,
4137 mut module_rx,
4138 pending,
4139 ) = dynamic_route_fixture(true);
4140 let route_open = client_rx.recv().await.unwrap();
4141 assert_eq!(route_open.header.corr, 700);
4142
4143 router
4144 .route_for_connection(
4145 &client_ctx,
4146 route_frame(
4147 FrameType::Request,
4148 pending.client_channel,
4149 pending.client_epoch,
4150 701,
4151 ),
4152 )
4153 .await
4154 .unwrap();
4155 let forwarded = module_rx.recv().await.unwrap();
4156 assert_eq!(forwarded.header.channel, pending.module_channel);
4157 assert_eq!(forwarded.header.epoch, pending.module_epoch);
4158
4159 router
4160 .route_for_connection(
4161 &module_ctx,
4162 route_frame(
4163 FrameType::Response,
4164 pending.module_channel,
4165 pending.module_epoch,
4166 701,
4167 ),
4168 )
4169 .await
4170 .unwrap();
4171 let delivered = client_rx.recv().await.unwrap();
4172 assert_eq!(delivered.header.channel, pending.client_channel);
4173 assert_eq!(delivered.header.epoch, pending.client_epoch);
4174
4175 router
4176 .route_for_connection(
4177 &client_ctx,
4178 route_frame(
4179 FrameType::Request,
4180 pending.client_channel,
4181 pending.client_epoch + 1,
4182 702,
4183 ),
4184 )
4185 .await
4186 .unwrap();
4187 router
4188 .route_for_connection(
4189 &module_ctx,
4190 route_frame(
4191 FrameType::Response,
4192 pending.module_channel,
4193 pending.module_epoch + 1,
4194 703,
4195 ),
4196 )
4197 .await
4198 .unwrap();
4199 let stale_error = client_rx.recv().await.unwrap();
4200 assert_eq!(stale_error.header.ty, FrameType::Error);
4201 assert_eq!(stale_error.header.channel, pending.client_channel);
4202 assert_eq!(stale_error.header.epoch, pending.client_epoch + 1);
4203 assert_eq!(stale_error.header.corr, 702);
4204 let body: ErrorBody = serde_json::from_slice(&stale_error.body).unwrap();
4205 assert_eq!(body.code, "stale_route_epoch");
4206 assert!(module_rx.try_recv().is_err());
4207 assert!(client_rx.try_recv().is_err());
4208 let counters = router.counters.snapshot();
4209 assert_eq!(counters["client_frames_dropped_stale_route"], 1);
4210 assert_eq!(counters["module_frames_dropped_no_route"], 1);
4211 }
4212
4213 #[tokio::test]
4214 async fn accepted_route_publishes_route_open_before_immediate_reverse_request() {
4215 let (
4216 router,
4217 _,
4218 _client_ctx,
4219 mut client_rx,
4220 module_ctx,
4221 _module_egress_rx,
4222 _module_rx,
4223 pending,
4224 ) = dynamic_route_fixture(true);
4225 router
4226 .route_for_connection(
4227 &module_ctx,
4228 route_frame(
4229 FrameType::Request,
4230 pending.module_channel,
4231 pending.module_epoch,
4232 800,
4233 ),
4234 )
4235 .await
4236 .unwrap();
4237
4238 let first = client_rx.recv().await.unwrap();
4239 let second = client_rx.recv().await.unwrap();
4240 assert_eq!(first.header.channel, 0);
4241 assert_eq!(first.header.corr, 700);
4242 assert_eq!(second.header.channel, pending.client_channel);
4243 assert_eq!(second.header.epoch, pending.client_epoch);
4244 assert_eq!(second.header.corr, 800);
4245 }
4246
4247 #[tokio::test]
4248 async fn reserved_slot_ingress_errors_only_matching_client_requests() {
4249 let (
4250 router,
4251 _forwarding,
4252 client_ctx,
4253 mut client_rx,
4254 _module_ctx,
4255 _module_egress_rx,
4256 mut module_rx,
4257 pending,
4258 ) = dynamic_route_fixture(false);
4259 router
4260 .route_for_connection(
4261 &client_ctx,
4262 route_frame(
4263 FrameType::Request,
4264 pending.client_channel,
4265 pending.client_epoch,
4266 900,
4267 ),
4268 )
4269 .await
4270 .unwrap();
4271 let error = client_rx.recv().await.unwrap();
4272 assert_eq!(error.header.ty, FrameType::Error);
4273 assert_eq!(error.header.channel, pending.client_channel);
4274 assert_eq!(error.header.epoch, pending.client_epoch);
4275 assert_eq!(error.header.corr, 900);
4276
4277 router
4278 .route_for_connection(
4279 &client_ctx,
4280 route_frame(
4281 FrameType::Response,
4282 pending.client_channel,
4283 pending.client_epoch,
4284 901,
4285 ),
4286 )
4287 .await
4288 .unwrap();
4289 router
4290 .route_for_connection(
4291 &client_ctx,
4292 route_frame(
4293 FrameType::Request,
4294 pending.client_channel,
4295 pending.client_epoch + 1,
4296 902,
4297 ),
4298 )
4299 .await
4300 .unwrap();
4301 let stale_error = client_rx.recv().await.unwrap();
4302 assert_eq!(stale_error.header.ty, FrameType::Error);
4303 assert_eq!(stale_error.header.channel, pending.client_channel);
4304 assert_eq!(stale_error.header.epoch, pending.client_epoch + 1);
4305 assert_eq!(stale_error.header.corr, 902);
4306 let body: ErrorBody = serde_json::from_slice(&stale_error.body).unwrap();
4307 assert_eq!(body.code, "stale_route_epoch");
4308 assert!(module_rx.try_recv().is_err());
4309 let counters = router.counters.snapshot();
4310 assert_eq!(counters["client_frames_dropped_stale_route"], 1);
4311 assert_eq!(counters["module_frames_dropped_no_route"], 0);
4312 }
4313
4314 #[tokio::test]
4315 async fn dropped_module_route_goodbye_increments_counter() {
4316 let (
4317 router,
4318 _forwarding,
4319 client_ctx,
4320 mut client_rx,
4321 _module_ctx,
4322 _module_egress_rx,
4323 mut module_rx,
4324 pending,
4325 ) = dynamic_route_fixture(true);
4326 let _ = client_rx.recv().await;
4327 module_rx.close();
4328
4329 router
4330 .route_for_connection(
4331 &client_ctx,
4332 route_frame(
4333 FrameType::Goodbye,
4334 pending.client_channel,
4335 pending.client_epoch,
4336 999,
4337 ),
4338 )
4339 .await
4340 .unwrap();
4341
4342 let counters = router.counters.snapshot();
4343 assert_eq!(counters["goodbye_relay_module_dropped"], 1);
4344 assert_eq!(
4345 counters["goodbye_relay_module_dropped_by_module"],
4346 serde_json::json!({ "epoch-router": 1 })
4347 );
4348 assert_eq!(counters["route_released_epoch_fenced"], 1);
4349 }
4350
4351 #[tokio::test]
4352 async fn module_request_on_stale_epoch_receives_stale_route_epoch() {
4353 let (
4354 router,
4355 _forwarding,
4356 _client_ctx,
4357 _client_rx,
4358 module_ctx,
4359 mut module_egress_rx,
4360 mut module_rx,
4361 pending,
4362 ) = dynamic_route_fixture(true);
4363
4364 router
4365 .route_for_connection(
4366 &module_ctx,
4367 route_frame(
4368 FrameType::Request,
4369 pending.module_channel,
4370 pending.module_epoch + 1,
4371 1_000,
4372 ),
4373 )
4374 .await
4375 .unwrap();
4376
4377 let error = module_egress_rx.try_recv().unwrap();
4378 assert_eq!(error.header.ty, FrameType::Error);
4379 assert_eq!(error.header.channel, pending.module_channel);
4380 assert_eq!(error.header.epoch, pending.module_epoch + 1);
4381 assert_eq!(error.header.corr, 1_000);
4382 let body: ErrorBody = serde_json::from_slice(&error.body).unwrap();
4383 assert_eq!(body.code, "stale_route_epoch");
4384 assert!(module_rx.try_recv().is_err());
4385 let counters = router.counters.snapshot();
4386 assert_eq!(counters["module_requests_dropped_stale_route"], 1);
4387 assert_eq!(counters["module_frames_dropped_no_route"], 0);
4388 }
4389
4390 #[tokio::test(start_paused = true)]
4391 async fn stale_epoch_drop_warns_once_per_minute_with_suppressed_count() {
4392 let (output, _guard) = test_log::log_capture(tracing::Level::WARN);
4393 let (
4394 router,
4395 _forwarding,
4396 client_ctx,
4397 mut client_rx,
4398 _module_ctx,
4399 _module_egress_rx,
4400 mut module_rx,
4401 pending,
4402 ) = dynamic_route_fixture(true);
4403 let _ = client_rx.recv().await;
4404 for corr in 1..=3 {
4405 router
4406 .route_for_connection(
4407 &client_ctx,
4408 route_frame(
4409 FrameType::Request,
4410 pending.client_channel,
4411 pending.client_epoch + 1,
4412 corr,
4413 ),
4414 )
4415 .await
4416 .unwrap();
4417 assert_eq!(client_rx.recv().await.unwrap().header.ty, FrameType::Error);
4418 }
4419 assert!(module_rx.try_recv().is_err());
4420 let logs = test_log::captured_logs(&output);
4421 assert_eq!(
4422 logs.matches("dropping data-plane frame").count(),
4423 1,
4424 "{logs}"
4425 );
4426 assert!(logs.contains("WARN"), "{logs}");
4427 assert!(
4428 logs.contains(&format!("connection_id={}", client_ctx.connection_id.get())),
4429 "{logs}"
4430 );
4431 assert!(
4432 logs.contains(&format!("channel={}", pending.client_channel)),
4433 "{logs}"
4434 );
4435 assert!(
4436 logs.contains(&format!("epoch={}", pending.client_epoch + 1)),
4437 "{logs}"
4438 );
4439 assert!(
4440 logs.contains("client_to_module") && logs.contains("stale_epoch"),
4441 "{logs}"
4442 );
4443 assert!(logs.contains("suppressed=0"), "{logs}");
4444
4445 tokio::time::advance(Duration::from_secs(60)).await;
4446 router
4447 .route_for_connection(
4448 &client_ctx,
4449 route_frame(
4450 FrameType::Request,
4451 pending.client_channel,
4452 pending.client_epoch + 2,
4453 4,
4454 ),
4455 )
4456 .await
4457 .unwrap();
4458 let logs = test_log::captured_logs(&output);
4459 assert_eq!(
4460 logs.matches("dropping data-plane frame").count(),
4461 2,
4462 "{logs}"
4463 );
4464 assert!(logs.contains("suppressed=2"), "{logs}");
4465 }
4466
4467 #[tokio::test]
4468 async fn module_request_on_reserved_or_absent_route_receives_unknown_channel() {
4469 let (
4470 reserved_router,
4471 _forwarding,
4472 _client_ctx,
4473 _client_rx,
4474 reserved_module_ctx,
4475 mut reserved_module_egress_rx,
4476 _module_rx,
4477 reserved,
4478 ) = dynamic_route_fixture(false);
4479 reserved_router
4480 .route_for_connection(
4481 &reserved_module_ctx,
4482 route_frame(
4483 FrameType::Request,
4484 reserved.module_channel,
4485 reserved.module_epoch,
4486 1_001,
4487 ),
4488 )
4489 .await
4490 .unwrap();
4491 let reserved_error = reserved_module_egress_rx.try_recv().unwrap();
4492 let reserved_body: ErrorBody = serde_json::from_slice(&reserved_error.body).unwrap();
4493 assert_eq!(reserved_error.header.ty, FrameType::Error);
4494 assert_eq!(reserved_error.header.channel, reserved.module_channel);
4495 assert_eq!(reserved_error.header.epoch, reserved.module_epoch);
4496 assert_eq!(reserved_error.header.corr, 1_001);
4497 assert_eq!(reserved_body.code, "unknown_channel");
4498 assert_eq!(
4499 reserved_router.counters.snapshot()["module_requests_dropped_stale_route"],
4500 1
4501 );
4502
4503 let (
4504 absent_router,
4505 _forwarding,
4506 _client_ctx,
4507 _client_rx,
4508 absent_module_ctx,
4509 mut absent_module_egress_rx,
4510 _module_rx,
4511 absent,
4512 ) = dynamic_route_fixture(false);
4513 absent_router
4514 .route_for_connection(
4515 &absent_module_ctx,
4516 route_frame(
4517 FrameType::Request,
4518 absent.module_channel + 1,
4519 absent.module_epoch,
4520 1_002,
4521 ),
4522 )
4523 .await
4524 .unwrap();
4525 let absent_error = absent_module_egress_rx.try_recv().unwrap();
4526 let absent_body: ErrorBody = serde_json::from_slice(&absent_error.body).unwrap();
4527 assert_eq!(absent_error.header.ty, FrameType::Error);
4528 assert_eq!(absent_error.header.channel, absent.module_channel + 1);
4529 assert_eq!(absent_error.header.epoch, absent.module_epoch);
4530 assert_eq!(absent_error.header.corr, 1_002);
4531 assert_eq!(absent_body.code, "unknown_channel");
4532 assert_eq!(
4533 absent_router.counters.snapshot()["module_requests_dropped_stale_route"],
4534 1
4535 );
4536 }
4537
4538 #[tokio::test]
4539 async fn non_request_module_frame_on_dead_route_is_counted_without_error() {
4540 let (
4541 router,
4542 forwarding,
4543 client_ctx,
4544 mut client_rx,
4545 module_ctx,
4546 mut module_egress_rx,
4547 mut module_rx,
4548 pending,
4549 ) = dynamic_route_fixture(true);
4550 let (other_module_tx, _other_module_rx) = mpsc::channel(8);
4551 forwarding
4552 .register_module_connection(
4553 ConnectionId::new(502),
4554 "other-module".into(),
4555 2,
4556 Concurrency::ModuleManaged,
4557 FrameSink::new(other_module_tx),
4558 )
4559 .unwrap();
4560 let _ = client_rx.recv().await.unwrap();
4561
4562 router
4563 .route_for_connection(
4564 &client_ctx,
4565 route_frame(
4566 FrameType::Goodbye,
4567 pending.client_channel,
4568 pending.client_epoch,
4569 1_003,
4570 ),
4571 )
4572 .await
4573 .unwrap();
4574 let _ = module_rx.recv().await.unwrap();
4575
4576 router
4577 .route_for_connection(
4578 &module_ctx,
4579 route_frame(
4580 FrameType::StreamData,
4581 pending.module_channel,
4582 pending.module_epoch,
4583 1_004,
4584 ),
4585 )
4586 .await
4587 .unwrap();
4588
4589 let reply = module_egress_rx.try_recv().unwrap();
4592 assert_eq!(reply.header.ty, FrameType::Goodbye);
4593 assert!(module_egress_rx.try_recv().is_err());
4594 let counters = router.counters.snapshot();
4595 assert_eq!(counters["module_frames_dropped_no_route"], 1);
4596 assert_eq!(
4597 counters["module_frames_dropped_no_route_by_module"],
4598 serde_json::json!({ "epoch-router": 1 })
4599 );
4600 assert_eq!(counters["module_requests_dropped_stale_route"], 0);
4601 }
4602
4603 fn drain_now(rx: &mut mpsc::Receiver<OutboundFrame>) {
4606 while rx.try_recv().is_ok() {}
4607 }
4608
4609 #[tokio::test]
4615 async fn route_goodbye_refused_by_stalled_module_is_delivered_when_it_resumes_reading() {
4616 const BUDGET: usize = 4_096;
4617 let forwarding = Arc::new(ForwardingTable::default());
4618 let control = Arc::new(ControlHandler::with_forwarding(
4619 Arc::new(Registry::default()),
4620 Arc::clone(&forwarding),
4621 ));
4622 let router = Router::with_control_handler(control);
4623 let module_connection = ConnectionId::new(80);
4624 let client_connection = ConnectionId::new(81);
4625 let (module_tx, mut module_rx) = mpsc::channel(64);
4626 let module_sink = FrameSink::with_byte_budget(module_tx, BUDGET);
4627 forwarding
4628 .register_module_connection(
4629 module_connection,
4630 "stalled-provider".into(),
4631 2,
4632 Concurrency::ModuleManaged,
4633 module_sink.clone(),
4634 )
4635 .unwrap();
4636 let (client_tx, mut client_rx) = mpsc::channel(8);
4637 let client_sink = FrameSink::new(client_tx);
4638 let pending = forwarding
4639 .begin_route_bind_relay_for_test(
4640 client_connection,
4641 client_sink.clone(),
4642 1_100,
4643 "stalled-provider",
4644 )
4645 .unwrap();
4646 forwarding
4647 .complete_pending_relay(
4648 module_connection,
4649 pending.corr,
4650 RouteBindRelayOutcome::Accepted,
4651 )
4652 .unwrap();
4653 let _ = client_rx.recv().await.unwrap();
4654 drain_now(&mut module_rx);
4655
4656 module_sink
4659 .try_send(stream_frame(9, 1, 0, vec![b'f'; BUDGET]))
4660 .unwrap();
4661 assert!(module_sink
4662 .try_send(stream_frame(9, 1, 1, Vec::new()))
4663 .is_err());
4664
4665 let client_ctx = RouteCtx {
4666 connection_id: client_connection,
4667 egress: client_sink,
4668 };
4669 router
4670 .route_for_connection(
4671 &client_ctx,
4672 route_frame(
4673 FrameType::Goodbye,
4674 pending.client_channel,
4675 pending.client_epoch,
4676 1_101,
4677 ),
4678 )
4679 .await
4680 .unwrap();
4681 tokio::task::yield_now().await;
4682 assert_eq!(
4683 router.counters.snapshot()["goodbye_relay_module_dropped"],
4684 0,
4685 "a GOODBYE refused by a momentarily full module queue must not be dropped"
4686 );
4687
4688 let filler = module_rx.recv().await.unwrap();
4690 assert_eq!(filler.header.ty, FrameType::StreamData);
4691 drop(filler);
4692 let goodbye = tokio::time::timeout(Duration::from_secs(2), module_rx.recv())
4693 .await
4694 .expect("the refused GOODBYE must be delivered once the module frees room")
4695 .unwrap();
4696 assert_eq!(goodbye.header.ty, FrameType::Goodbye);
4697 assert_eq!(goodbye.header.channel, pending.module_channel);
4698 assert_eq!(goodbye.header.epoch, pending.module_epoch);
4699 assert_eq!(
4700 router.counters.snapshot()["goodbye_relay_module_dropped"],
4701 0
4702 );
4703 }
4704
4705 #[tokio::test]
4711 async fn module_frame_on_route_the_daemon_does_not_hold_is_answered_with_goodbye() {
4712 let (
4713 router,
4714 _forwarding,
4715 client_ctx,
4716 mut client_rx,
4717 module_ctx,
4718 mut module_egress_rx,
4719 mut module_rx,
4720 pending,
4721 ) = dynamic_route_fixture(true);
4722 let _ = client_rx.recv().await.unwrap();
4723 router
4724 .route_for_connection(
4725 &client_ctx,
4726 route_frame(
4727 FrameType::Goodbye,
4728 pending.client_channel,
4729 pending.client_epoch,
4730 1_200,
4731 ),
4732 )
4733 .await
4734 .unwrap();
4735 drain_now(&mut module_rx);
4736
4737 let cases = [
4738 (pending.module_channel, pending.module_epoch),
4740 (pending.module_channel + 1, 1),
4742 ];
4743 for (channel, epoch) in cases {
4744 router
4745 .route_for_connection(
4746 &module_ctx,
4747 route_frame(FrameType::StreamData, channel, epoch, 1_201),
4748 )
4749 .await
4750 .unwrap();
4751 let reply = module_egress_rx
4752 .try_recv()
4753 .expect("a frame on a route the daemon does not hold is answered");
4754 assert_eq!(reply.header.ty, FrameType::Goodbye);
4755 assert_eq!(reply.header.channel, channel);
4756 assert_eq!(reply.header.epoch, epoch);
4757 assert_eq!(reply.header.corr, 0);
4758 assert!(module_egress_rx.try_recv().is_err());
4759 }
4760
4761 router
4764 .route_for_connection(
4765 &module_ctx,
4766 route_frame(FrameType::Goodbye, pending.module_channel + 2, 1, 0),
4767 )
4768 .await
4769 .unwrap();
4770 assert!(module_egress_rx.try_recv().is_err());
4771
4772 let counters = router.counters.snapshot();
4773 assert_eq!(counters["module_frames_dropped_no_route"], 3);
4774 assert_eq!(counters["module_frames_dropped_released_route"], 1);
4775 assert_eq!(
4776 counters["module_frames_dropped_released_route_by_module"],
4777 serde_json::json!({ "epoch-router": 1 })
4778 );
4779 assert_eq!(counters["module_orphan_route_goodbyes_sent"], 2);
4780 }
4781
4782 #[tokio::test(start_paused = true)]
4786 async fn burst_of_orphan_module_frames_is_answered_once_per_interval() {
4787 let (
4788 router,
4789 _forwarding,
4790 client_ctx,
4791 mut client_rx,
4792 module_ctx,
4793 mut module_egress_rx,
4794 mut module_rx,
4795 pending,
4796 ) = dynamic_route_fixture(true);
4797 let _ = client_rx.recv().await.unwrap();
4798 router
4799 .route_for_connection(
4800 &client_ctx,
4801 route_frame(
4802 FrameType::Goodbye,
4803 pending.client_channel,
4804 pending.client_epoch,
4805 1_300,
4806 ),
4807 )
4808 .await
4809 .unwrap();
4810 drain_now(&mut module_rx);
4811
4812 let send_burst = |corr: u64| {
4813 route_frame(
4814 FrameType::StreamData,
4815 pending.module_channel,
4816 pending.module_epoch,
4817 corr,
4818 )
4819 };
4820 for corr in 0..20 {
4821 router
4822 .route_for_connection(&module_ctx, send_burst(corr))
4823 .await
4824 .unwrap();
4825 }
4826 let mut replies = 0;
4827 while let Ok(reply) = module_egress_rx.try_recv() {
4828 assert_eq!(reply.header.ty, FrameType::Goodbye);
4829 replies += 1;
4830 }
4831 assert_eq!(replies, 1, "a burst within the interval gets one GOODBYE");
4832
4833 tokio::time::advance(ORPHAN_ROUTE_GOODBYE_INTERVAL).await;
4834 router
4835 .route_for_connection(&module_ctx, send_burst(20))
4836 .await
4837 .unwrap();
4838 let retry = module_egress_rx
4839 .try_recv()
4840 .expect("the first orphan frame after the interval is answered again");
4841 assert_eq!(retry.header.channel, pending.module_channel);
4842 assert_eq!(retry.header.epoch, pending.module_epoch);
4843
4844 let counters = router.counters.snapshot();
4845 assert_eq!(counters["module_frames_dropped_no_route"], 21);
4846 assert_eq!(counters["module_orphan_route_goodbyes_sent"], 2);
4847 }
4848
4849 #[test]
4851 fn orphan_goodbye_rate_limit_state_is_released_with_the_connection() {
4852 let router = Router::with_default_self_handler();
4853 let connection = router.begin_connection();
4854 let id = connection.id();
4855 assert!(router.orphan_goodbyes.claim(id, 7));
4856 assert!(!router.orphan_goodbyes.claim(id, 7));
4857 assert!(router.orphan_goodbyes.claim(id, 8));
4858 drop(connection);
4859 assert!(router
4860 .orphan_goodbyes
4861 .last_sent
4862 .lock()
4863 .unwrap()
4864 .get(&id)
4865 .is_none());
4866 }
4867
4868 #[test]
4869 fn channel_zero_cannot_be_registered_as_backend() {
4870 let mut router = Router::with_default_self_handler();
4871
4872 let err = router.register_backend(0, EchoBackend).unwrap_err();
4873
4874 assert_eq!(err, RouterError::ReservedChannelZero);
4875 }
4876}