1use std::{
2 collections::{BTreeMap, BTreeSet, HashMap, HashSet, VecDeque},
3 error::Error,
4 fmt,
5 future::Future,
6 io,
7 path::{Path, PathBuf},
8 pin::Pin,
9 sync::{
10 atomic::{AtomicBool, AtomicU64, Ordering},
11 Arc, Mutex, MutexGuard, OnceLock,
12 },
13 task::{Context, Poll},
14 time::{Duration, SystemTime, UNIX_EPOCH},
15};
16
17use sha2::{Digest, Sha256};
18pub use subc_control::SupervisorEntry;
19use subc_control::{
20 CatalogEntry, ClientControlRequest, ClientControlResponse, ConsumerIdentity, PollKind,
21 RouteOpenReplyExt, RouteOpenRequestExt, ROUTE_CLOSE_REASONS_CAPABILITY,
22};
23pub use subc_control::{LiveSpawn, SpawnCursor, SpawnEvent, SpawnEventKind, SpawnSnapshot};
26pub use subc_control::{RouteOpenTarget, RouteOpenTargetKind};
27pub use subc_protocol::scope::ScopeSelector;
30use subc_protocol::{
31 error_codes, manifest::is_valid_capability_identifier, AdmissionClass, BindIdentity, ErrorBody,
32 Flags, Frame, FrameBuildError, FrameType, Priority, RouteTarget, FLAG_SUBSCRIPTION,
33 SUBC_MODULE_ID_ENV,
34};
35
36use crate::{
37 ActivityCursor, ActivityQueryRequest, ActivityQueryResponse, ActivitySubscribeRequest,
38 ActivitySubscription, RouteHandle,
39};
40use subc_transport::{
41 authenticate_client, connection_file, read_frame, write_frame, AuthError, ConnectionFileError,
42 FrameIoError,
43};
44use tokio::{
45 io::{AsyncRead, AsyncWrite, AsyncWriteExt, BufWriter},
46 net::TcpStream,
47 sync::{mpsc, oneshot, watch, Notify, OwnedSemaphorePermit, Semaphore},
48 task::JoinHandle,
49 time::{sleep, sleep_until, timeout_at, Instant},
50};
51use tokio_util::sync::CancellationToken;
52
53const DEFAULT_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(2);
54const CAPABILITY_PROBE_TIMEOUT: Duration = Duration::from_secs(2);
58pub const DEFAULT_CALL_TIMEOUT: Duration = Duration::from_secs(30);
59pub const DEFAULT_ROUTE_RETRY_DEADLINE: Duration = Duration::from_secs(90);
67pub const MAX_ROUTE_OPENS_IN_FLIGHT: usize = 8;
74const DEFAULT_RESTORED_DEBOUNCE: Duration = Duration::from_millis(250);
75pub const DEFAULT_LIVENESS_PROBE_WINDOW: Duration = Duration::from_secs(2);
76const EGRESS_BUFFER: usize = 128;
77const DEFAULT_ROUTE_WINDOW: usize = 1024;
78const DEFAULT_SUBSCRIPTION_EVENT_BUFFER: usize = 128;
79const DEFAULT_PUSH_EVENT_BUFFER: usize = 128;
80const REVERSE_REQUEST_UNHANDLED: &str = "reverse_request_unhandled";
81const SPAWN_EVENT_BUFFER: usize = 8192;
86const ACTIVITY_EVENT_BUFFER: usize = 2048;
89
90#[cfg(test)]
91#[path = "activity_consumer_tests.rs"]
92mod activity_consumer_tests;
93
94mod cancellation;
95mod slots;
96use slots::*;
97mod reservation;
98pub use reservation::{CorrelationId, PendingReply, RequestBody, RequestReservation};
99mod catalog;
100mod supervisor_ops;
101use catalog::decode_route_open_response;
102pub use catalog::CatalogSubscription;
103
104#[cfg(test)]
105mod reader_skew_tests;
106
107#[cfg(test)]
108mod connection_ops_tests;
109pub use cancellation::{CancelHandle, CancelOutcome};
110use cancellation::{CancelRegistration, UnaryCancel};
111pub use supervisor_ops::{
112 HealthProbeResponse, ServerDescription, StderrTailResponse, SupervisorAck,
113 SupervisorHealthResponse, SupervisorProvenanceResponse,
114};
115
116pub const SPAWN_CURSOR_INCARNATION_MISMATCH: &str = "spawn_cursor_incarnation_mismatch";
118pub const SPAWN_CURSOR_TOO_OLD: &str = "spawn_cursor_too_old";
120pub const SPAWN_SUBSCRIBER_LAGGED: &str = "spawn_subscriber_lagged";
122
123type ReverseRequestFuture =
124 Pin<Box<dyn Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static>>;
125type ReverseRequestHandler =
126 Arc<dyn Fn(Vec<u8>, ReverseRequestContext) -> ReverseRequestFuture + Send + Sync + 'static>;
127
128#[derive(Debug, Clone, PartialEq, Eq)]
129pub struct ReverseRequestContext {
130 pub corr: u64,
131 pub method: String,
132}
133
134#[derive(Debug, Clone, PartialEq, Eq)]
135pub struct ReverseRequestError {
136 message: String,
137}
138
139impl ReverseRequestError {
140 pub fn new(message: impl Into<String>) -> Self {
141 Self {
142 message: message.into(),
143 }
144 }
145}
146
147impl fmt::Display for ReverseRequestError {
148 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
149 f.write_str(&self.message)
150 }
151}
152
153impl Error for ReverseRequestError {}
154
155#[derive(Default)]
156struct ReverseRequestRegistryState {
157 handlers: HashMap<String, ReverseRequestHandler>,
158 declared_families: Option<BTreeSet<String>>,
159 consumer_capabilities: BTreeSet<String>,
160}
161
162#[derive(Clone, Default)]
166pub struct ReverseRequestRegistry {
167 inner: Arc<Mutex<ReverseRequestRegistryState>>,
168}
169
170impl fmt::Debug for ReverseRequestRegistry {
171 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
172 f.debug_struct("ReverseRequestRegistry")
173 .field("capabilities", &self.capabilities())
174 .field("consumer_capabilities", &self.consumer_capabilities())
175 .finish()
176 }
177}
178
179impl PartialEq for ReverseRequestRegistry {
180 fn eq(&self, other: &Self) -> bool {
181 self.capabilities() == other.capabilities()
182 && self.consumer_capabilities() == other.consumer_capabilities()
183 }
184}
185
186impl Eq for ReverseRequestRegistry {}
187
188impl ReverseRequestRegistry {
189 pub fn new() -> Self {
190 Self::default()
191 }
192
193 pub fn on_request<F, Fut>(
194 &self,
195 method_family: impl Into<String>,
196 handler: F,
197 ) -> Result<(), ReverseRequestRegistrationError>
198 where
199 F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
200 Fut: Future<Output = Vec<u8>> + Send + 'static,
201 {
202 self.on_request_fallible(method_family, move |body, ctx| {
203 let future = handler(body, ctx);
204 async move { Ok(future.await) }
205 })
206 }
207
208 pub fn on_request_fallible<F, Fut>(
209 &self,
210 method_family: impl Into<String>,
211 handler: F,
212 ) -> Result<(), ReverseRequestRegistrationError>
213 where
214 F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
215 Fut: Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static,
216 {
217 let method_family = method_family.into();
218 if !is_valid_method_family(&method_family) {
219 return Err(ReverseRequestRegistrationError::InvalidFamily(
220 method_family,
221 ));
222 }
223 let mut state = self
224 .inner
225 .lock()
226 .unwrap_or_else(|poisoned| poisoned.into_inner());
227 if state
228 .declared_families
229 .as_ref()
230 .is_some_and(|families| !families.contains(&method_family))
231 {
232 return Err(ReverseRequestRegistrationError::NotDeclared(method_family));
233 }
234 state.handlers.insert(
235 method_family,
236 Arc::new(move |body, ctx| Box::pin(handler(body, ctx))),
237 );
238 Ok(())
239 }
240
241 fn capabilities(&self) -> Vec<String> {
242 let state = self
243 .inner
244 .lock()
245 .unwrap_or_else(|poisoned| poisoned.into_inner());
246 let mut capabilities = state.handlers.keys().cloned().collect::<Vec<_>>();
247 capabilities.sort();
248 capabilities
249 }
250
251 fn declare_consumer_capability(
252 &self,
253 capability: String,
254 ) -> Result<(), ConsumerCapabilityError> {
255 if capability.is_empty()
256 || capability.len() > 64
257 || !capability.bytes().all(|byte| (0x21..=0x7e).contains(&byte))
258 {
259 return Err(ConsumerCapabilityError { capability });
260 }
261
262 self.inner
263 .lock()
264 .unwrap_or_else(|poisoned| poisoned.into_inner())
265 .consumer_capabilities
266 .insert(capability);
267 Ok(())
268 }
269
270 fn consumer_capabilities(&self) -> Vec<String> {
271 self.inner
272 .lock()
273 .unwrap_or_else(|poisoned| poisoned.into_inner())
274 .consumer_capabilities
275 .iter()
276 .cloned()
277 .collect()
278 }
279
280 fn handler(&self, method_family: &str) -> Option<ReverseRequestHandler> {
281 self.inner
282 .lock()
283 .unwrap_or_else(|poisoned| poisoned.into_inner())
284 .handlers
285 .get(method_family)
286 .cloned()
287 }
288
289 pub(crate) fn seal(&self) {
290 let mut state = self
291 .inner
292 .lock()
293 .unwrap_or_else(|poisoned| poisoned.into_inner());
294 if state.declared_families.is_none() {
295 state.declared_families = Some(state.handlers.keys().cloned().collect());
296 }
297 }
298}
299
300#[derive(Debug, Clone, PartialEq, Eq)]
301pub enum ReverseRequestRegistrationError {
302 InvalidFamily(String),
303 NotDeclared(String),
304 NotConsumerRoute,
305}
306
307impl fmt::Display for ReverseRequestRegistrationError {
308 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
309 match self {
310 Self::InvalidFamily(family) => {
311 write!(f, "invalid reverse-request method family {family:?}")
312 }
313 Self::NotDeclared(family) => write!(
314 f,
315 "reverse-request capability {family:?} was not registered before route.open"
316 ),
317 Self::NotConsumerRoute => {
318 f.write_str("route handle does not belong to a consumer route")
319 }
320 }
321 }
322}
323
324impl Error for ReverseRequestRegistrationError {}
325
326fn is_valid_method_family(value: &str) -> bool {
327 let mut segments = value.split(['.', '_', '-']);
328 segments.next().is_some_and(|segment| {
329 segment
330 .as_bytes()
331 .first()
332 .is_some_and(u8::is_ascii_lowercase)
333 && segment
334 .bytes()
335 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
336 }) && segments.all(|segment| {
337 !segment.is_empty()
338 && segment
339 .bytes()
340 .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
341 })
342}
343
344static NEXT_REVERSE_REQUEST_REGISTRY_ID: AtomicU64 = AtomicU64::new(1);
366static REVERSE_REQUEST_REGISTRIES: OnceLock<Mutex<HashMap<u64, ReverseRequestRegistry>>> =
367 OnceLock::new();
368
369fn reverse_request_registries() -> &'static Mutex<HashMap<u64, ReverseRequestRegistry>> {
370 REVERSE_REQUEST_REGISTRIES.get_or_init(|| Mutex::new(HashMap::new()))
371}
372
373pub(crate) fn install_reverse_request_registry(registry: ReverseRequestRegistry) -> u64 {
374 let id = crate::checked_increment(&NEXT_REVERSE_REQUEST_REGISTRY_ID)
375 .expect("reverse-request route registry id exhausted");
376 reverse_request_registries()
377 .lock()
378 .unwrap_or_else(|poisoned| poisoned.into_inner())
379 .insert(id, registry);
380 id
381}
382
383pub(crate) fn route_reverse_request_registry(
384 id: u64,
385) -> Result<ReverseRequestRegistry, ReverseRequestRegistrationError> {
386 if id == 0 {
387 return Err(ReverseRequestRegistrationError::NotConsumerRoute);
388 }
389 reverse_request_registries()
390 .lock()
391 .unwrap_or_else(|poisoned| poisoned.into_inner())
392 .get(&id)
393 .cloned()
394 .ok_or(ReverseRequestRegistrationError::NotConsumerRoute)
395}
396
397fn release_reverse_request_registry(handle: RouteHandle) {
398 let id = handle.reverse_request_registry_id();
399 if id != 0 {
400 reverse_request_registries()
401 .lock()
402 .unwrap_or_else(|poisoned| poisoned.into_inner())
403 .remove(&id);
404 }
405}
406
407#[derive(Debug, Clone, Copy, PartialEq, Eq)]
411pub struct RetryBackoff {
412 pub base: Duration,
413 pub cap: Duration,
414 pub max_attempts: usize,
416}
417
418impl Default for RetryBackoff {
419 fn default() -> Self {
420 Self {
421 base: Duration::from_millis(100),
422 cap: Duration::from_secs(2),
423 max_attempts: 6,
424 }
425 }
426}
427
428impl RetryBackoff {
429 fn delay_after_attempt(self, attempt: usize) -> Duration {
430 let mut delay = self.base;
431 for _ in 1..attempt {
432 delay = (delay * 2).min(self.cap);
433 }
434 delay
435 }
436}
437
438#[derive(Debug, Clone, Copy, PartialEq, Eq)]
440enum ConsumerTransport {
441 Tcp,
443 Local,
445}
446
447#[derive(Debug, Clone, PartialEq, Eq)]
449pub struct ConsumerOptions {
450 pub handshake_timeout: Duration,
451 pub call_timeout: Duration,
453 pub reconnect_backoff: RetryBackoff,
454 pub restored_debounce: Duration,
455 pub liveness_probe_window: Duration,
458}
459
460impl Default for ConsumerOptions {
461 fn default() -> Self {
462 Self {
463 handshake_timeout: DEFAULT_HANDSHAKE_TIMEOUT,
464 call_timeout: DEFAULT_CALL_TIMEOUT,
465 reconnect_backoff: RetryBackoff::default(),
466 restored_debounce: DEFAULT_RESTORED_DEBOUNCE,
467 liveness_probe_window: DEFAULT_LIVENESS_PROBE_WINDOW,
468 }
469 }
470}
471
472#[derive(Debug, Clone, PartialEq, Eq)]
475pub struct ConsumerCapabilityError {
476 capability: String,
477}
478
479impl ConsumerCapabilityError {
480 pub fn capability(&self) -> &str {
482 &self.capability
483 }
484}
485
486impl fmt::Display for ConsumerCapabilityError {
487 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
488 write!(
489 f,
490 "invalid consumer capability {:?}: expected 1-64 printable ASCII bytes without whitespace",
491 self.capability
492 )
493 }
494}
495
496impl Error for ConsumerCapabilityError {}
497
498#[derive(Debug, Clone)]
500pub struct CloseRouteOptions {
501 pub scope: Option<ScopeSelector>,
506 pub drain: bool,
510 pub drain_timeout: Duration,
512 pub consumer_identity: Option<ConsumerIdentity>,
518 pub reverse_requests: ReverseRequestRegistry,
521 pub role_versions: Option<BTreeMap<String, String>>,
524}
525
526impl Default for CloseRouteOptions {
527 fn default() -> Self {
528 Self {
529 scope: None,
530 drain: false,
531 drain_timeout: DEFAULT_CALL_TIMEOUT,
532 consumer_identity: None,
533 reverse_requests: ReverseRequestRegistry::new(),
534 role_versions: None,
535 }
536 }
537}
538
539impl CloseRouteOptions {
540 pub fn with_consumer_capability(
551 self,
552 capability: impl Into<String>,
553 ) -> Result<Self, ConsumerCapabilityError> {
554 self.reverse_requests
555 .declare_consumer_capability(capability.into())?;
556 Ok(self)
557 }
558
559 pub fn consumer_capabilities(&self) -> Vec<String> {
564 self.reverse_requests.consumer_capabilities()
565 }
566}
567
568#[derive(Debug, Clone, PartialEq, Eq)]
570pub struct CallOptions {
571 pub scope: Option<ScopeSelector>,
580 pub timeout: Duration,
582 pub priority: Priority,
583 pub admission_class: AdmissionClass,
585 pub route_retry: RetryBackoff,
586 pub route_retry_deadline: Duration,
590 pub consumer_identity: Option<ConsumerIdentity>,
596 pub reverse_requests: ReverseRequestRegistry,
601 pub role_versions: Option<BTreeMap<String, String>>,
615}
616
617impl Default for CallOptions {
618 fn default() -> Self {
619 Self {
620 scope: None,
621 timeout: DEFAULT_CALL_TIMEOUT,
622 priority: Priority::Interactive,
623 admission_class: AdmissionClass::Normal,
624 route_retry: RetryBackoff::default(),
625 route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
626 consumer_identity: None,
627 reverse_requests: ReverseRequestRegistry::new(),
628 role_versions: None,
629 }
630 }
631}
632
633impl CallOptions {
634 fn reject_scope(&self) -> Result<(), CallError> {
635 if self.scope.is_some() {
636 return Err(CallError::not_sent(
637 "CallOptions.scope is not supported here; select the scope with open_route_scoped or a managed call",
638 ));
639 }
640 Ok(())
641 }
642
643 pub fn with_consumer_capability(
656 self,
657 capability: impl Into<String>,
658 ) -> Result<Self, ConsumerCapabilityError> {
659 self.reverse_requests
660 .declare_consumer_capability(capability.into())?;
661 Ok(self)
662 }
663
664 pub fn consumer_capabilities(&self) -> Vec<String> {
669 self.reverse_requests.consumer_capabilities()
670 }
671}
672
673#[derive(Debug, Clone, PartialEq, Eq)]
675pub struct SubscribeOptions {
676 pub scope: Option<ScopeSelector>,
682 pub priority: Priority,
683 pub admission_class: AdmissionClass,
685 pub event_buffer: usize,
689 pub route_retry: RetryBackoff,
690 pub route_retry_deadline: Duration,
692 pub route_open_timeout: Duration,
695 pub consumer_identity: Option<ConsumerIdentity>,
700 pub reverse_requests: ReverseRequestRegistry,
705 pub role_versions: Option<BTreeMap<String, String>>,
708}
709
710impl Default for SubscribeOptions {
711 fn default() -> Self {
712 Self {
713 scope: None,
714 priority: Priority::Interactive,
715 admission_class: AdmissionClass::Normal,
716 event_buffer: DEFAULT_SUBSCRIPTION_EVENT_BUFFER,
717 route_retry: RetryBackoff::default(),
718 route_retry_deadline: DEFAULT_ROUTE_RETRY_DEADLINE,
719 route_open_timeout: DEFAULT_CALL_TIMEOUT,
720 consumer_identity: None,
721 reverse_requests: ReverseRequestRegistry::new(),
722 role_versions: None,
723 }
724 }
725}
726
727impl SubscribeOptions {
728 pub fn with_consumer_capability(
735 self,
736 capability: impl Into<String>,
737 ) -> Result<Self, ConsumerCapabilityError> {
738 self.reverse_requests
739 .declare_consumer_capability(capability.into())?;
740 Ok(self)
741 }
742
743 pub fn consumer_capabilities(&self) -> Vec<String> {
748 self.reverse_requests.consumer_capabilities()
749 }
750}
751
752#[derive(Debug, Clone, PartialEq, Eq)]
755pub enum ConnectionState {
756 Dropped,
757 Restored { epoch: u64 },
758}
759
760#[derive(Debug, Clone, PartialEq, Eq)]
762pub struct RoutePollResult {
763 pub handle: RouteHandle,
764 pub status: Option<String>,
765 pub live: Option<bool>,
766}
767
768#[derive(Debug, Clone, serde::Deserialize, PartialEq)]
773pub struct CatalogList {
774 pub generation: u64,
775 #[serde(default)]
776 pub modules: Vec<CatalogEntry>,
777 #[serde(default)]
778 pub subc_ops: Vec<String>,
779}
780
781#[derive(Debug, Clone, PartialEq)]
786pub struct SupervisorListResponse {
787 pub generation: u64,
788 pub modules: Vec<SupervisorEntry>,
789 pub daemon: Option<subc_control::DaemonResources>,
790 pub agent_commands: Option<Vec<subc_control::AgentCommandResources>>,
791}
792
793#[derive(Debug, Clone, PartialEq, Eq)]
795pub struct PushEvent {
796 pub handle: RouteHandle,
798 pub body: Vec<u8>,
800}
801
802enum DroppedPush {
805 Delivered,
806 NoReceiver,
807 ReceiverFull,
808}
809
810#[derive(Debug, Clone)]
812pub struct ControlPush {
813 pub op: String,
815 pub body: serde_json::Value,
817}
818
819#[derive(Debug, Clone, PartialEq, Eq)]
825#[non_exhaustive]
826pub enum RouteCloseReason {
827 Reload,
828 Restart,
829 AuthorityChanged,
830 Disable,
831 Crash,
832 CapabilityDenied,
833 ScopeEnded,
834 ScopeCarrierRemoved,
835 ScopeDelegationChanged,
836 ScopeParentEnded,
837 Unknown(String),
838}
839
840pub const ACCEPTED_CLOSE_REASONS: &[&str] = &[
843 "reload",
844 "restart",
845 "authority_changed",
846 "disable",
847 "crash",
848 "capability_denied",
849 "scope_ended",
850 "scope_carrier_removed",
851 "scope_delegation_changed",
852 "scope_parent_ended",
853];
854
855#[derive(Debug, Clone, PartialEq, Eq)]
857#[non_exhaustive]
858pub enum RouteEndReason {
859 Daemon(RouteCloseReason),
860 ClosedByCaller,
861 ConnectionLost,
862 Unknown,
863}
864
865#[derive(Debug, Clone)]
866struct RouteEnd {
867 reason: RouteEndReason,
868 terminal: Option<bool>,
869}
870
871impl From<RouteEndReason> for RouteEnd {
872 fn from(reason: RouteEndReason) -> Self {
873 Self {
874 reason,
875 terminal: None,
876 }
877 }
878}
879
880#[derive(Debug, Clone, Copy, PartialEq, Eq)]
882pub enum RouteCloseDisposition {
883 MayReopen,
884 MustNotReopen,
885}
886
887impl RouteCloseReason {
888 pub fn from_wire(reason: &str) -> Self {
890 match reason {
891 "reload" => Self::Reload,
892 "restart" => Self::Restart,
893 "authority_changed" => Self::AuthorityChanged,
894 "disable" => Self::Disable,
895 "crash" => Self::Crash,
896 "capability_denied" => Self::CapabilityDenied,
897 "scope_ended" => Self::ScopeEnded,
898 "scope_carrier_removed" => Self::ScopeCarrierRemoved,
899 "scope_delegation_changed" => Self::ScopeDelegationChanged,
900 "scope_parent_ended" => Self::ScopeParentEnded,
901 other => Self::Unknown(other.to_string()),
902 }
903 }
904
905 pub fn disposition(&self) -> RouteCloseDisposition {
907 match self {
908 Self::Reload | Self::Restart | Self::AuthorityChanged => {
909 RouteCloseDisposition::MayReopen
910 }
911 Self::Disable
912 | Self::Crash
913 | Self::CapabilityDenied
914 | Self::ScopeEnded
915 | Self::ScopeCarrierRemoved
916 | Self::ScopeDelegationChanged
917 | Self::ScopeParentEnded
918 | Self::Unknown(_) => RouteCloseDisposition::MustNotReopen,
919 }
920 }
921}
922
923impl ControlPush {
924 pub fn route_close_reason(&self) -> Option<RouteCloseReason> {
926 matches!(self.op.as_str(), "route.closing" | "route.closed")
927 .then(|| {
928 self.body
929 .get("reason")?
930 .as_str()
931 .map(RouteCloseReason::from_wire)
932 })
933 .flatten()
934 }
935}
936
937pub struct SubcConsumer {
939 shared: Arc<Shared>,
940}
941
942#[non_exhaustive]
945#[derive(Debug, Clone, PartialEq, Eq)]
946pub struct ConnectionFacts {
947 local: bool,
948 operator_app: Option<subc_protocol::peer::OperatorApp>,
949}
950
951impl ConnectionFacts {
952 pub fn local(&self) -> bool {
954 self.local
955 }
956
957 pub fn operator_app(&self) -> Option<&subc_protocol::peer::OperatorApp> {
960 self.operator_app.as_ref()
961 }
962}
963
964#[non_exhaustive]
966#[derive(Debug)]
967pub enum AppOpenError {
968 Refused { code: String, message: String },
974 Call(CallError),
976}
977
978impl fmt::Display for AppOpenError {
979 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
980 match self {
981 Self::Refused { code, message } => write!(f, "{code}: {message}"),
982 Self::Call(err) => err.fmt(f),
983 }
984 }
985}
986
987impl Error for AppOpenError {
988 fn source(&self) -> Option<&(dyn Error + 'static)> {
989 match self {
990 Self::Call(err) => Some(err),
991 Self::Refused { .. } => None,
992 }
993 }
994}
995
996impl From<CallError> for AppOpenError {
997 fn from(err: CallError) -> Self {
998 Self::Call(err)
999 }
1000}
1001
1002#[non_exhaustive]
1004#[derive(Debug, Clone, PartialEq, Eq)]
1005pub struct CallReply {
1006 body: Vec<u8>,
1007 binary: bool,
1008}
1009
1010impl CallReply {
1011 pub fn body(&self) -> &[u8] {
1014 &self.body
1015 }
1016
1017 pub fn into_body(self) -> Vec<u8> {
1019 self.body
1020 }
1021
1022 pub fn is_binary(&self) -> bool {
1025 self.binary
1026 }
1027}
1028
1029#[derive(Debug, Clone, PartialEq)]
1031#[non_exhaustive]
1032pub enum SubscriptionEnd {
1033 Response(Vec<u8>),
1034 StreamEnd,
1035 Error(ErrorBody),
1036 RouteClosed {
1037 reason: RouteEndReason,
1038 },
1039 ConnectionLost,
1040 Cancelled,
1041 Backpressure,
1043}
1044
1045pub struct Subscription {
1053 events: mpsc::Receiver<Vec<u8>>,
1054 closed: SubscriptionClosed,
1055 ended: watch::Receiver<Option<SubscriptionEnd>>,
1056 cancel: SubscriptionCancel,
1057}
1058
1059impl Subscription {
1060 pub fn events(&mut self) -> &mut mpsc::Receiver<Vec<u8>> {
1062 &mut self.events
1063 }
1064
1065 pub fn closed(&mut self) -> &mut SubscriptionClosed {
1072 &mut self.closed
1073 }
1074
1075 pub async fn ended(&mut self) -> SubscriptionEnd {
1081 loop {
1082 if let Some(end) = self.ended.borrow().clone() {
1083 return end;
1084 }
1085 if self.ended.changed().await.is_err() {
1086 return SubscriptionEnd::ConnectionLost;
1087 }
1088 }
1089 }
1090
1091 pub fn unsubscribe(&self) -> Result<(), CallError> {
1098 self.cancel.unsubscribe()
1099 }
1100}
1101
1102impl Drop for Subscription {
1103 fn drop(&mut self) {
1104 let _ = self.cancel.unsubscribe();
1105 }
1106}
1107
1108pub struct SpawnSubscription {
1111 inner: Subscription,
1112 finished: bool,
1113}
1114
1115impl SpawnSubscription {
1116 pub async fn next(&mut self) -> Result<Option<SpawnEvent>, SpawnStreamError> {
1125 if self.finished {
1126 return Ok(None);
1127 }
1128 if let Some(body) = self.inner.events().recv().await {
1129 return serde_json::from_slice::<SpawnEvent>(&body)
1130 .map(Some)
1131 .map_err(|err| {
1132 self.finished = true;
1133 let _ = self.inner.unsubscribe();
1134 SpawnStreamError::Decode(err.to_string())
1135 });
1136 }
1137 let terminal = self.inner.closed().await;
1140 self.finished = true;
1141 match terminal {
1142 Ok(()) => Ok(None),
1143 Err(err) => Err(SpawnStreamError::from_call_error(err)),
1144 }
1145 }
1146
1147 pub fn unsubscribe(&self) -> Result<(), CallError> {
1149 self.inner.unsubscribe()
1150 }
1151}
1152
1153#[derive(Debug)]
1155pub enum SpawnStreamError {
1156 CursorIncarnationMismatch {
1159 current_daemon_incarnation: String,
1160 body: Box<ErrorBody>,
1161 },
1162 CursorTooOld {
1164 oldest_retained_cursor: SpawnCursor,
1165 body: Box<ErrorBody>,
1166 },
1167 SubscriberLagged {
1170 first_undelivered_cursor: SpawnCursor,
1171 body: Box<ErrorBody>,
1172 },
1173 Call(CallError),
1177 Decode(String),
1179}
1180
1181impl SpawnStreamError {
1182 fn from_call_error(err: CallError) -> Self {
1183 let CallError::Module(body) = err else {
1184 return Self::Call(err);
1185 };
1186 let detail = |key: &str| body.detail.as_ref().and_then(|detail| detail.get(key));
1187 let cursor = |key: &str| {
1188 detail(key).and_then(|value| serde_json::from_value::<SpawnCursor>(value.clone()).ok())
1189 };
1190 match body.code.as_str() {
1191 SPAWN_CURSOR_INCARNATION_MISMATCH => {
1192 match detail("current_daemon_incarnation").and_then(|value| value.as_str()) {
1193 Some(current) => Self::CursorIncarnationMismatch {
1194 current_daemon_incarnation: current.to_string(),
1195 body: Box::new(body),
1196 },
1197 None => Self::Call(CallError::Module(body)),
1198 }
1199 }
1200 SPAWN_CURSOR_TOO_OLD => match cursor("oldest_retained_cursor") {
1201 Some(oldest_retained_cursor) => Self::CursorTooOld {
1202 oldest_retained_cursor,
1203 body: Box::new(body),
1204 },
1205 None => Self::Call(CallError::Module(body)),
1206 },
1207 SPAWN_SUBSCRIBER_LAGGED => match cursor("first_undelivered_cursor") {
1208 Some(first_undelivered_cursor) => Self::SubscriberLagged {
1209 first_undelivered_cursor,
1210 body: Box::new(body),
1211 },
1212 None => Self::Call(CallError::Module(body)),
1213 },
1214 _ => Self::Call(CallError::Module(body)),
1215 }
1216 }
1217
1218 pub fn code(&self) -> Option<&str> {
1220 match self {
1221 Self::CursorIncarnationMismatch { .. } => Some(SPAWN_CURSOR_INCARNATION_MISMATCH),
1222 Self::CursorTooOld { .. } => Some(SPAWN_CURSOR_TOO_OLD),
1223 Self::SubscriberLagged { .. } => Some(SPAWN_SUBSCRIBER_LAGGED),
1224 Self::Call(err) => err.code(),
1225 Self::Decode(_) => None,
1226 }
1227 }
1228}
1229
1230impl fmt::Display for SpawnStreamError {
1231 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1232 match self {
1233 Self::CursorIncarnationMismatch {
1234 current_daemon_incarnation,
1235 ..
1236 } => write!(
1237 f,
1238 "{SPAWN_CURSOR_INCARNATION_MISMATCH}: the daemon is incarnation \
1239 {current_daemon_incarnation}"
1240 ),
1241 Self::CursorTooOld {
1242 oldest_retained_cursor,
1243 ..
1244 } => write!(
1245 f,
1246 "{SPAWN_CURSOR_TOO_OLD}: the oldest retained event is seq {}",
1247 oldest_retained_cursor.seq
1248 ),
1249 Self::SubscriberLagged {
1250 first_undelivered_cursor,
1251 ..
1252 } => write!(
1253 f,
1254 "{SPAWN_SUBSCRIBER_LAGGED}: the first undelivered event is seq {}",
1255 first_undelivered_cursor.seq
1256 ),
1257 Self::Call(err) => write!(f, "spawn stream ended: {err}"),
1258 Self::Decode(message) => write!(f, "spawn event did not decode: {message}"),
1259 }
1260 }
1261}
1262
1263impl Error for SpawnStreamError {}
1264
1265pub struct SubscriptionClosed {
1267 rx: oneshot::Receiver<Result<(), CallError>>,
1268}
1269
1270impl Unpin for SubscriptionClosed {}
1271
1272impl Future for SubscriptionClosed {
1273 type Output = Result<(), CallError>;
1274
1275 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
1276 let this = self.get_mut();
1277 match Pin::new(&mut this.rx).poll(cx) {
1278 Poll::Ready(Ok(result)) => Poll::Ready(result),
1279 Poll::Ready(Err(_)) => Poll::Ready(Err(CallError::outcome_unknown(
1280 "subscription closed result channel dropped",
1281 OutcomeUnknownCause::CompletionFailed,
1282 ))),
1283 Poll::Pending => Poll::Pending,
1284 }
1285 }
1286}
1287
1288struct SubscriptionCancel {
1289 shared: Arc<Shared>,
1290 position: Arc<SubscriptionPosition>,
1291 priority: Priority,
1292 cancelled: AtomicBool,
1293}
1294
1295impl SubscriptionCancel {
1296 fn new(shared: Arc<Shared>, position: Arc<SubscriptionPosition>, priority: Priority) -> Self {
1297 Self {
1298 shared,
1299 position,
1300 priority,
1301 cancelled: AtomicBool::new(false),
1302 }
1303 }
1304
1305 fn unsubscribe(&self) -> Result<(), CallError> {
1306 let key = *self
1307 .position
1308 .key
1309 .lock()
1310 .unwrap_or_else(|err| err.into_inner());
1311 let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
1312 self.shared.validate_current_handle(handle)?;
1313 if self.cancelled.swap(true, Ordering::AcqRel) {
1314 return Ok(());
1315 }
1316 self.shared
1317 .unsubscribe_subscription(&self.position, self.priority)
1318 }
1319}
1320
1321impl SubcConsumer {
1322 pub async fn connect(
1330 connection_file: &Path,
1331 opts: ConsumerOptions,
1332 ) -> Result<Self, ConsumerError> {
1333 Self::connect_with_transport(connection_file, opts, ConsumerTransport::Tcp, true).await
1334 }
1335
1336 pub async fn connect_local(
1343 connection_file: &Path,
1344 opts: ConsumerOptions,
1345 ) -> Result<Self, ConsumerError> {
1346 Self::connect_with_transport(connection_file, opts, ConsumerTransport::Local, true).await
1347 }
1348
1349 async fn connect_with_transport(
1350 connection_file: &Path,
1351 opts: ConsumerOptions,
1352 transport: ConsumerTransport,
1353 identity_from_environment: bool,
1354 ) -> Result<Self, ConsumerError> {
1355 let opened =
1356 open_connection(connection_file, opts.handshake_timeout, transport, None).await?;
1357 let mut shared = Shared::with_transport(connection_file.to_path_buf(), opts, transport);
1358 shared.identity_from_environment = identity_from_environment;
1359 let shared = Arc::new(shared);
1360 shared.install_initial(opened)?;
1361 Ok(Self { shared })
1362 }
1363
1364 pub async fn connect_default(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1366 let discovered = connection_file::discover(None)
1367 .map_err(|source| ConsumerError::Discovery { source })?;
1368 let opened =
1369 open_connection_with_info(&discovered.path, &discovered.info, opts.handshake_timeout)
1370 .await?;
1371 let shared = Arc::new(Shared::new(discovered.path, opts));
1372 shared.install_initial(opened)?;
1373 Ok(Self { shared })
1374 }
1375
1376 pub async fn connect_default_local(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1381 let discovered = connection_file::discover(None)
1382 .map_err(|source| ConsumerError::Discovery { source })?;
1383 Self::connect_local(&discovered.path, opts).await
1384 }
1385
1386 pub async fn connect_operator_app(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1396 Self::connect_operator_app_resolving(
1397 opts,
1398 ConsumerTransport::Local,
1399 crate::operator_app_candidates,
1400 )
1401 .await
1402 }
1403
1404 pub async fn connect_operator_app_plain(opts: ConsumerOptions) -> Result<Self, ConsumerError> {
1428 Self::connect_operator_app_resolving(
1429 opts,
1430 ConsumerTransport::Tcp,
1431 crate::operator_app_candidates,
1432 )
1433 .await
1434 }
1435
1436 async fn connect_operator_app_resolving(
1437 opts: ConsumerOptions,
1438 transport: ConsumerTransport,
1439 resolve: impl FnOnce() -> Result<Vec<PathBuf>, crate::OperatorAppPathError>,
1440 ) -> Result<Self, ConsumerError> {
1441 let candidates = resolve().map_err(|source| ConsumerError::ConnectionFile {
1442 path: PathBuf::new(),
1443 source: ConnectionFileError::Io {
1444 op: "resolve installed daemon connection-file path",
1445 path: PathBuf::new(),
1446 source: io::Error::other(source),
1447 },
1448 })?;
1449 let path = candidates[0].clone();
1450 let opened =
1451 open_connection(&path, opts.handshake_timeout, transport, Some(&candidates)).await?;
1452 let mut shared = Shared::with_transport(path, opts, transport);
1453 shared.operator_app_candidates = Some(candidates);
1454 shared.identity_from_environment = false;
1455 let shared = Arc::new(shared);
1456 shared.install_initial(opened)?;
1457 Ok(Self { shared })
1458 }
1459
1460 pub async fn open_route(
1464 &self,
1465 target: RouteTarget,
1466 identity: BindIdentity,
1467 opts: CallOptions,
1468 ) -> Result<RouteHandle, CallError> {
1469 opts.reject_scope()?;
1470 let deadline = Instant::now() + opts.timeout;
1471 let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1472 let consumer_capabilities = route_open_consumer_capabilities(&opts);
1473 let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1474 let key = RouteKey::new(
1475 &target,
1476 &identity,
1477 consumer_identity.as_ref(),
1478 consumer_capabilities.as_deref(),
1479 )
1480 .with_role_versions(role_versions.as_ref());
1481 let params = RouteOpenParams {
1482 target: &target,
1483 identity: &identity,
1484 consumer_identity: &consumer_identity,
1485 consumer_capabilities: &consumer_capabilities,
1486 role_versions: &role_versions,
1487 reverse_requests: &opts.reverse_requests,
1488 scope: None,
1489 };
1490 self.shared
1491 .ensure_route(&key, ¶ms, &opts, deadline)
1492 .await
1493 .map(|route| route.handle)
1494 }
1495
1496 pub async fn open_route_scoped(
1533 &self,
1534 target: RouteTarget,
1535 identity: BindIdentity,
1536 scope: ScopeSelector,
1537 opts: CallOptions,
1538 ) -> Result<RouteHandle, CallError> {
1539 if opts
1540 .scope
1541 .as_ref()
1542 .is_some_and(|selected| selected != &scope)
1543 {
1544 return Err(CallError::not_sent(
1545 "CallOptions.scope differs from open_route_scoped's explicit scope",
1546 ));
1547 }
1548 let deadline = Instant::now() + opts.timeout;
1549 let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
1550 let consumer_capabilities = route_open_consumer_capabilities(&opts);
1551 let role_versions = route_open_role_versions(opts.role_versions.as_ref());
1552 let key = RouteKey::new(
1553 &target,
1554 &identity,
1555 consumer_identity.as_ref(),
1556 consumer_capabilities.as_deref(),
1557 )
1558 .with_role_versions(role_versions.as_ref())
1559 .with_scope(Some(&scope));
1560 let params = RouteOpenParams {
1561 target: &target,
1562 identity: &identity,
1563 consumer_identity: &consumer_identity,
1564 consumer_capabilities: &consumer_capabilities,
1565 role_versions: &role_versions,
1566 reverse_requests: &opts.reverse_requests,
1567 scope: Some(&scope),
1568 };
1569 self.shared
1570 .ensure_route(&key, ¶ms, &opts, deadline)
1571 .await
1572 .map(|route| route.handle)
1573 }
1574
1575 pub async fn open_route_with_admission_facts(
1585 &self,
1586 target: RouteTarget,
1587 identity: BindIdentity,
1588 facts: serde_json::Value,
1589 ) -> Result<RouteHandle, CallError> {
1590 let deadline = Instant::now() + self.shared.opts.call_timeout;
1591 self.open_admitted_route(
1592 target,
1593 identity,
1594 facts,
1595 &CallOptions::default(),
1596 None,
1597 deadline,
1598 )
1599 .await
1600 }
1601
1602 pub async fn open_route_with_admission_facts_and_options(
1619 &self,
1620 target: RouteTarget,
1621 identity: BindIdentity,
1622 facts: serde_json::Value,
1623 opts: CallOptions,
1624 ) -> Result<RouteHandle, CallError> {
1625 opts.reject_scope()?;
1626 let deadline = Instant::now() + opts.timeout;
1627 let reverse_requests = opts.reverse_requests.clone();
1628 self.open_admitted_route(
1629 target,
1630 identity,
1631 facts,
1632 &opts,
1633 Some(reverse_requests),
1634 deadline,
1635 )
1636 .await
1637 }
1638
1639 async fn open_admitted_route(
1645 &self,
1646 target: RouteTarget,
1647 identity: BindIdentity,
1648 facts: serde_json::Value,
1649 opts: &CallOptions,
1650 reverse_requests: Option<ReverseRequestRegistry>,
1651 deadline: Instant,
1652 ) -> Result<RouteHandle, CallError> {
1653 let consumer_capabilities = route_open_consumer_capabilities(opts);
1654 let target_label = route_target_label(&target);
1655 let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
1656 busy_refusals: Some(true),
1657 target,
1658 identity,
1659 consumer_identity: self.shared.route_open_consumer_identity(opts)?,
1660 consumer_capabilities,
1661 role_versions: route_open_role_versions(opts.role_versions.as_ref()),
1662 admission_facts: Some(facts),
1663 scope: None,
1664 })
1665 .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
1666
1667 let terminal = self
1668 .shared
1669 .paced_route_open(body, deadline, reverse_requests.clone())
1670 .await?;
1671 let (generation, body) = match terminal {
1672 TerminalFrame::Response {
1673 generation, body, ..
1674 } => (generation, body),
1675 TerminalFrame::Error { body, .. } => {
1680 return Err(CallError::route_open_refused(target_label, body));
1681 }
1682 _ => {
1683 return Err(CallError::not_sent_with_cause(
1684 "route.open returned a non-response frame",
1685 NotSentCause::RouteOpenAbandoned,
1686 ));
1687 }
1688 };
1689 let ClientControlResponse::RouteOpen {
1690 route_channel,
1691 route_epoch,
1692 request_window,
1693 watch_window,
1694 ..
1695 } = decode_route_open_response(&body)
1696 .map_err(|err| {
1697 CallError::not_sent_with_cause(
1698 format!("failed to decode route.open response: {err}"),
1699 NotSentCause::RouteOpenAbandoned,
1700 )
1701 })?
1702 .0
1703 else {
1704 return Err(CallError::not_sent_with_cause(
1705 "route.open returned an unexpected control response",
1706 NotSentCause::RouteOpenAbandoned,
1707 ));
1708 };
1709 let handle = self
1713 .shared
1714 .ingress_handle(generation, route_channel, route_epoch)
1715 .unwrap_or_else(|| match reverse_requests {
1716 Some(reverse_requests) => RouteHandle::new_consumer(
1717 route_channel,
1718 route_epoch,
1719 generation,
1720 reverse_requests,
1721 ),
1722 None => RouteHandle::new(route_channel, route_epoch, generation),
1723 });
1724 let route = RouteState::windows(handle, request_window, watch_window);
1725 self.shared.install_one_shot_route(route.clone())?;
1726 Ok(route.handle)
1727 }
1728
1729 pub async fn describe_connection(&self) -> Result<Option<ConnectionFacts>, CallError> {
1733 let body =
1734 serde_json::to_vec(&subc_control::ConnectionDescribeRequest::new()).map_err(|err| {
1735 CallError::not_sent(format!("failed to encode connection.describe: {err}"))
1736 })?;
1737 let deadline = Instant::now() + self.shared.opts.call_timeout;
1738 match self
1739 .shared
1740 .control_call(body, deadline, false, None)
1741 .await?
1742 {
1743 TerminalFrame::Response { body, .. } => {
1744 let reply: subc_control::ConnectionDescribeReply = serde_json::from_slice(&body)
1745 .map_err(|err| {
1746 CallError::invalid_response(format!(
1747 "failed to decode connection.describe: {err}"
1748 ))
1749 })?;
1750 Ok(Some(ConnectionFacts {
1751 local: reply.local,
1752 operator_app: reply.operator_app,
1753 }))
1754 }
1755 TerminalFrame::Error { body, .. } if body.code == "unknown_control_op" => Ok(None),
1757 TerminalFrame::Error { body, .. } => Err(CallError::Module(body)),
1758 TerminalFrame::StreamEnd => Err(CallError::invalid_response(
1759 "connection.describe returned StreamEnd",
1760 )),
1761 }
1762 }
1763
1764 pub async fn app_open(&self, app: &str) -> Result<subc_control::AppOpenReply, AppOpenError> {
1767 let body = serde_json::to_vec(&subc_control::AppOpenRequest::new(app))
1768 .map_err(|err| CallError::not_sent(format!("failed to encode app.open: {err}")))?;
1769 let deadline = Instant::now() + self.shared.opts.call_timeout;
1770 match self
1771 .shared
1772 .control_call(body, deadline, false, None)
1773 .await?
1774 {
1775 TerminalFrame::Response { body, .. } => serde_json::from_slice(&body).map_err(|err| {
1776 CallError::invalid_response(format!("failed to decode app.open: {err}")).into()
1777 }),
1778 TerminalFrame::Error { body, .. } => Err(AppOpenError::Refused {
1779 code: body.code,
1780 message: body.message,
1781 }),
1782 TerminalFrame::StreamEnd => {
1783 Err(CallError::invalid_response("app.open returned StreamEnd").into())
1784 }
1785 }
1786 }
1787
1788 pub async fn catalog_list(&self) -> Result<CatalogList, CallError> {
1791 let deadline = Instant::now() + self.shared.opts.call_timeout;
1792 let body = serde_json::to_vec(&serde_json::json!({
1793 "op": subc_control::ops::CATALOG_LIST,
1794 }))
1795 .map_err(|err| CallError::not_sent(format!("failed to encode catalog.list: {err}")))?;
1796
1797 let mut attempt = 0usize;
1798 loop {
1799 attempt = attempt.saturating_add(1);
1800 match self
1801 .shared
1802 .control_call(body.clone(), deadline, false, None)
1803 .await
1804 {
1805 Ok(TerminalFrame::Response { body, .. }) => {
1806 let response =
1807 serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1808 CallError::invalid_response(format!(
1809 "failed to decode catalog.list response: {err}"
1810 ))
1811 })?;
1812 let ClientControlResponse::CatalogList {
1813 generation,
1814 modules,
1815 subc_ops,
1816 } = response
1817 else {
1818 return Err(CallError::invalid_response(
1819 "catalog.list returned an unexpected control response",
1820 ));
1821 };
1822 return Ok(CatalogList {
1823 generation,
1824 modules,
1825 subc_ops,
1826 });
1827 }
1828 Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1829 Ok(TerminalFrame::StreamEnd) => {
1830 return Err(CallError::invalid_response(
1831 "catalog.list returned StreamEnd",
1832 ));
1833 }
1834 Err(err)
1835 if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1836 {
1837 let delay = self.shared.jittered(
1841 self.shared
1842 .opts
1843 .reconnect_backoff
1844 .delay_after_attempt(attempt),
1845 );
1846 self.shared.sleep_until_retry(deadline, delay).await?;
1847 continue;
1848 }
1849 Err(err) => return Err(err),
1850 }
1851 }
1852 }
1853
1854 pub async fn supervisor_list(&self) -> Result<SupervisorListResponse, CallError> {
1857 let deadline = Instant::now() + self.shared.opts.call_timeout;
1858 let body = serde_json::to_vec(&ClientControlRequest::SupervisorList {}).map_err(|err| {
1859 CallError::not_sent(format!("failed to encode supervisor.list: {err}"))
1860 })?;
1861
1862 let mut attempt = 0usize;
1863 loop {
1864 attempt = attempt.saturating_add(1);
1865 match self
1866 .shared
1867 .control_call(body.clone(), deadline, false, None)
1868 .await
1869 {
1870 Ok(TerminalFrame::Response { body, .. }) => {
1871 let response =
1872 serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1873 CallError::invalid_response(format!(
1874 "failed to decode supervisor.list response: {err}"
1875 ))
1876 })?;
1877 let ClientControlResponse::SupervisorList {
1878 generation,
1879 modules,
1880 daemon,
1881 agent_commands,
1882 } = response
1883 else {
1884 return Err(CallError::invalid_response(
1885 "supervisor.list returned an unexpected control response",
1886 ));
1887 };
1888 return Ok(SupervisorListResponse {
1889 generation,
1890 modules,
1891 daemon,
1892 agent_commands,
1893 });
1894 }
1895 Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1896 Ok(TerminalFrame::StreamEnd) => {
1897 return Err(CallError::invalid_response(
1898 "supervisor.list returned StreamEnd",
1899 ));
1900 }
1901 Err(err)
1902 if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1903 {
1904 let delay = self.shared.jittered(
1906 self.shared
1907 .opts
1908 .reconnect_backoff
1909 .delay_after_attempt(attempt),
1910 );
1911 self.shared.sleep_until_retry(deadline, delay).await?;
1912 continue;
1913 }
1914 Err(err) => return Err(err),
1915 }
1916 }
1917 }
1918
1919 pub async fn spawn_snapshot(&self) -> Result<SpawnSnapshot, CallError> {
1928 let deadline = Instant::now() + self.shared.opts.call_timeout;
1929 let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSnapshot {}).map_err(
1930 |err| CallError::not_sent(format!("failed to encode supervisor.spawn_snapshot: {err}")),
1931 )?;
1932
1933 let mut attempt = 0usize;
1934 loop {
1935 attempt = attempt.saturating_add(1);
1936 match self
1937 .shared
1938 .control_call(body.clone(), deadline, false, None)
1939 .await
1940 {
1941 Ok(TerminalFrame::Response { body, .. }) => {
1942 let response =
1943 serde_json::from_slice::<ClientControlResponse>(&body).map_err(|err| {
1944 CallError::invalid_response(format!(
1945 "failed to decode supervisor.spawn_snapshot response: {err}"
1946 ))
1947 })?;
1948 let ClientControlResponse::SupervisorSpawnSnapshot { snapshot } = response
1949 else {
1950 return Err(CallError::invalid_response(
1951 "supervisor.spawn_snapshot returned an unexpected control response",
1952 ));
1953 };
1954 return Ok(snapshot);
1955 }
1956 Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
1957 Ok(TerminalFrame::StreamEnd) => {
1958 return Err(CallError::invalid_response(
1959 "supervisor.spawn_snapshot returned StreamEnd",
1960 ));
1961 }
1962 Err(err)
1963 if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
1964 {
1965 let delay = self.shared.jittered(
1966 self.shared
1967 .opts
1968 .reconnect_backoff
1969 .delay_after_attempt(attempt),
1970 );
1971 self.shared.sleep_until_retry(deadline, delay).await?;
1972 continue;
1973 }
1974 Err(err) => return Err(err),
1975 }
1976 }
1977 }
1978
1979 pub async fn query_activity(
1986 &self,
1987 request: ActivityQueryRequest,
1988 ) -> Result<ActivityQueryResponse, CallError> {
1989 let deadline = Instant::now() + self.shared.opts.call_timeout;
1990 let body = self.shared.activity_read_body(request)?;
1991 let mut attempt = 0usize;
1992 loop {
1993 attempt = attempt.saturating_add(1);
1994 match self
1995 .shared
1996 .control_call(body.clone(), deadline, false, None)
1997 .await
1998 {
1999 Ok(TerminalFrame::Response { body, .. }) => {
2000 return serde_json::from_slice(&body).map_err(|err| {
2001 CallError::invalid_response(format!(
2002 "invalid activity.query response: {err}"
2003 ))
2004 });
2005 }
2006 Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2007 Ok(TerminalFrame::StreamEnd) => {
2008 return Err(CallError::invalid_response(
2009 "activity.query returned StreamEnd",
2010 ));
2011 }
2012 Err(err)
2013 if is_retryable_catalog_transport_error(&err) && Instant::now() < deadline =>
2014 {
2015 let delay = self.shared.jittered(
2016 self.shared
2017 .opts
2018 .reconnect_backoff
2019 .delay_after_attempt(attempt),
2020 );
2021 self.shared.sleep_until_retry(deadline, delay).await?;
2022 }
2023 Err(err) => return Err(err),
2024 }
2025 }
2026 }
2027
2028 pub async fn subscribe_activity(
2034 &self,
2035 since: Option<ActivityCursor>,
2036 ) -> Result<ActivitySubscription, CallError> {
2037 let deadline = Instant::now() + self.shared.opts.call_timeout;
2038 let body = self
2039 .shared
2040 .activity_read_body(ActivitySubscribeRequest { since })?;
2041 loop {
2042 self.shared.ensure_connected_for_call(deadline).await?;
2043 let permit = Arc::new(Semaphore::new(1))
2044 .acquire_owned()
2045 .await
2046 .map_err(|_| CallError::not_sent("activity subscription permit closed"))?;
2047 match self
2048 .shared
2049 .send_subscription(SubscriptionSend {
2050 expected_handle: None,
2051 channel: 0,
2052 epoch: 0,
2053 body: body.clone(),
2054 priority: Priority::Interactive,
2055 admission_class: AdmissionClass::Normal,
2056 event_buffer: ACTIVITY_EVENT_BUFFER,
2057 deadline,
2058 permit: RoutePermit::legacy(permit),
2059 })
2060 .await
2061 {
2062 Ok(inner) => {
2063 return Ok(ActivitySubscription {
2064 inner,
2065 finished: false,
2066 })
2067 }
2068 Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2069 Err(err) => return Err(err),
2070 }
2071 }
2072 }
2073
2074 pub async fn spawn_subscribe(
2085 &self,
2086 since: Option<SpawnCursor>,
2087 ) -> Result<SpawnSubscription, CallError> {
2088 let deadline = Instant::now() + self.shared.opts.call_timeout;
2089 let body = serde_json::to_vec(&ClientControlRequest::SupervisorSpawnSubscribe { since })
2090 .map_err(|err| {
2091 CallError::not_sent(format!(
2092 "failed to encode supervisor.spawn_subscribe: {err}"
2093 ))
2094 })?;
2095 loop {
2096 self.shared.ensure_connected_for_call(deadline).await?;
2097 let permit = Arc::new(Semaphore::new(1))
2100 .acquire_owned()
2101 .await
2102 .map_err(|_| CallError::not_sent("spawn subscription permit closed"))?;
2103 match self
2104 .shared
2105 .send_subscription(SubscriptionSend {
2106 expected_handle: None,
2107 channel: 0,
2108 epoch: 0,
2109 body: body.clone(),
2110 priority: Priority::Interactive,
2111 admission_class: AdmissionClass::Normal,
2112 event_buffer: SPAWN_EVENT_BUFFER,
2113 deadline,
2114 permit: RoutePermit::legacy(permit),
2115 })
2116 .await
2117 {
2118 Ok(inner) => {
2119 return Ok(SpawnSubscription {
2120 inner,
2121 finished: false,
2122 })
2123 }
2124 Err(err) if err.is_not_sent() && Instant::now() < deadline => continue,
2125 Err(err) => return Err(err),
2126 }
2127 }
2128 }
2129
2130 pub async fn resolve_provider(&self, capability: &str) -> Result<String, CallError> {
2137 let claimants = self.resolve_providers(capability).await?;
2138 match claimants.as_slice() {
2139 [] => Err(CallError::CapabilityUnprovided {
2140 capability: capability.to_string(),
2141 }),
2142 [claimant] => Ok(claimant.clone()),
2143 _ => Err(CallError::CapabilityAmbiguous {
2144 capability: capability.to_string(),
2145 claimants,
2146 }),
2147 }
2148 }
2149
2150 pub async fn resolve_providers(&self, capability: &str) -> Result<Vec<String>, CallError> {
2155 validate_capability_for_resolution(capability)?;
2156 let catalog = self.catalog_list().await?;
2157 Ok(capability_claimants(&catalog, capability))
2158 }
2159
2160 pub async fn request(
2163 &self,
2164 handle: &RouteHandle,
2165 body: Vec<u8>,
2166 opts: CallOptions,
2167 ) -> Result<Vec<u8>, CallError> {
2168 self.request_inner(handle, body, opts, None).await
2169 }
2170
2171 pub fn request_cancellable(
2197 &self,
2198 handle: &RouteHandle,
2199 body: Vec<u8>,
2200 opts: CallOptions,
2201 ) -> (
2202 CancelHandle,
2203 impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2204 ) {
2205 let consumer = self;
2206 let handle = *handle;
2207 let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2208 let future = async move {
2209 let guard = registration;
2210 consumer
2211 .request_inner(&handle, body, opts, Some(Arc::clone(&guard.state)))
2212 .await
2213 };
2214 (cancel, future)
2215 }
2216
2217 async fn request_inner(
2218 &self,
2219 handle: &RouteHandle,
2220 body: Vec<u8>,
2221 opts: CallOptions,
2222 cancel: Option<Arc<UnaryCancel>>,
2223 ) -> Result<Vec<u8>, CallError> {
2224 opts.reject_scope()?;
2225 let deadline = Instant::now() + opts.timeout;
2226 let route = self.shared.route_state(*handle)?;
2227 let permit = route.acquire(false, deadline, cancel.as_ref()).await?;
2228 let mut busy_delay = Duration::from_millis(25);
2229 loop {
2230 let result = self
2231 .shared
2232 .send_request_with_slot(
2233 RequestSend {
2234 binary: false,
2235 expected_handle: Some(*handle),
2236 channel: handle.channel,
2237 epoch: handle.epoch,
2238 body: body.clone(),
2239 priority: opts.priority,
2240 admission_class: opts.admission_class,
2241 deadline,
2242 retain_late_route_open: false,
2243 route_open_reverse_requests: None,
2244 },
2245 cancel.clone(),
2246 Some(Arc::clone(&permit)),
2247 )
2248 .await;
2249 match result? {
2250 TerminalFrame::Response { body, .. } => return Ok(body),
2251 TerminalFrame::StreamEnd => return Ok(Vec::new()),
2252 TerminalFrame::Error { body, flags }
2253 if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2254 {
2255 if !self
2256 .shared
2257 .busy_backoff(deadline, busy_delay, cancel.as_ref())
2258 .await
2259 {
2260 return Err(busy_error(&body));
2261 }
2262 busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2263 self.shared.validate_current_handle(*handle)?;
2264 }
2265 TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2266 }
2267 }
2268 }
2269
2270 pub async fn subscribe_route(
2273 &self,
2274 handle: &RouteHandle,
2275 body: Vec<u8>,
2276 opts: SubscribeOptions,
2277 ) -> Result<Subscription, CallError> {
2278 if opts.scope.is_some() {
2279 return Err(CallError::not_sent(
2280 "SubscribeOptions.scope is not supported on subscribe_route; select the scope when opening the route",
2281 ));
2282 }
2283 let deadline = Instant::now() + opts.route_open_timeout;
2284 let route = self.shared.route_state(*handle)?;
2285 let permit = route.acquire(true, deadline, None).await?;
2286 self.shared
2287 .send_subscription(SubscriptionSend {
2288 expected_handle: Some(*handle),
2289 channel: handle.channel,
2290 epoch: handle.epoch,
2291 body,
2292 priority: opts.priority,
2293 admission_class: opts.admission_class,
2294 event_buffer: opts.event_buffer,
2295 deadline,
2296 permit,
2297 })
2298 .await
2299 }
2300
2301 pub async fn poll_route(
2304 &self,
2305 handle: &RouteHandle,
2306 kind: PollKind,
2307 timeout: Duration,
2308 ) -> Result<RoutePollResult, CallError> {
2309 let deadline = Instant::now() + timeout;
2310 let body = serde_json::to_vec(&ClientControlRequest::RoutePoll {
2311 route_channel: handle.channel,
2312 route_epoch: handle.epoch,
2313 kind,
2314 })
2315 .map_err(|err| CallError::not_sent(format!("failed to encode route.poll: {err}")))?;
2316 let terminal = self
2317 .shared
2318 .send_request(RequestSend {
2319 binary: false,
2320 expected_handle: Some(*handle),
2321 channel: 0,
2322 epoch: 0,
2323 body,
2324 priority: Priority::Interactive,
2325 admission_class: AdmissionClass::Normal,
2326 deadline,
2327 retain_late_route_open: false,
2328 route_open_reverse_requests: None,
2329 })
2330 .await?;
2331 let body = match terminal {
2332 TerminalFrame::Response { body, .. } => body,
2333 TerminalFrame::Error { body, .. } => return Err(CallError::Module(body)),
2334 TerminalFrame::StreamEnd => {
2335 return Err(CallError::invalid_response(
2336 "route.poll returned a non-response frame",
2337 ));
2338 }
2339 };
2340 let ClientControlResponse::RoutePoll {
2341 route_channel,
2342 route_epoch,
2343 status,
2344 live,
2345 } = serde_json::from_slice(&body).map_err(|err| {
2346 CallError::invalid_response(format!("failed to decode route.poll: {err}"))
2347 })?
2348 else {
2349 return Err(CallError::invalid_response(
2350 "route.poll returned an unexpected control response",
2351 ));
2352 };
2353 if route_channel != handle.channel || route_epoch != handle.epoch {
2354 return Err(CallError::invalid_response(
2355 "route.poll response echoed a different route handle",
2356 ));
2357 }
2358 self.shared.validate_current_handle(*handle)?;
2359 Ok(RoutePollResult {
2360 handle: *handle,
2361 status,
2362 live,
2363 })
2364 }
2365
2366 pub fn dropped_route_frames(&self) -> u64 {
2368 self.shared.lock_inner().dropped_route_frames
2369 }
2370
2371 pub fn push_events(
2380 &self,
2381 handle: &RouteHandle,
2382 ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
2383 self.shared.register_push_events(*handle)
2384 }
2385
2386 pub fn pushes_dropped_no_receiver(&self) -> u64 {
2392 self.shared
2393 .pushes_dropped_no_receiver
2394 .load(Ordering::Relaxed)
2395 }
2396
2397 pub fn pushes_dropped_receiver_full(&self) -> u64 {
2404 self.shared
2405 .pushes_dropped_receiver_full
2406 .load(Ordering::Relaxed)
2407 }
2408
2409 pub fn control_pushes(&self, capacity: usize) -> mpsc::Receiver<ControlPush> {
2419 let (sender, receiver) = mpsc::channel(capacity.max(1));
2420 self.shared.lock_inner().control_push_receiver = Some(sender);
2421 receiver
2422 }
2423
2424 pub fn control_pushes_dropped(&self) -> u64 {
2429 self.shared.control_pushes_dropped.load(Ordering::Relaxed)
2430 }
2431
2432 pub async fn call(
2444 &self,
2445 target: RouteTarget,
2446 identity: BindIdentity,
2447 body: Vec<u8>,
2448 opts: CallOptions,
2449 ) -> Result<Vec<u8>, CallError> {
2450 self.call_with_reply(target, identity, body, opts)
2451 .await
2452 .map(CallReply::into_body)
2453 }
2454
2455 pub async fn call_with_reply(
2458 &self,
2459 target: RouteTarget,
2460 identity: BindIdentity,
2461 body: Vec<u8>,
2462 opts: CallOptions,
2463 ) -> Result<CallReply, CallError> {
2464 self.call_inner(target, identity, (body, false), opts, None)
2465 .await
2466 }
2467
2468 pub fn call_cancellable(
2476 &self,
2477 target: RouteTarget,
2478 identity: BindIdentity,
2479 body: Vec<u8>,
2480 opts: CallOptions,
2481 ) -> (
2482 CancelHandle,
2483 impl Future<Output = Result<Vec<u8>, CallError>> + Send + '_,
2484 ) {
2485 let (cancel, reply) = self.call_cancellable_with_reply(target, identity, body, opts);
2486 (cancel, async move { reply.await.map(CallReply::into_body) })
2487 }
2488
2489 pub fn call_cancellable_with_reply(
2493 &self,
2494 target: RouteTarget,
2495 identity: BindIdentity,
2496 body: Vec<u8>,
2497 opts: CallOptions,
2498 ) -> (
2499 CancelHandle,
2500 impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2501 ) {
2502 let consumer = self;
2503 let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2504 let future = async move {
2505 let guard = registration;
2506 consumer
2507 .call_inner(
2508 target,
2509 identity,
2510 (body, false),
2511 opts,
2512 Some(Arc::clone(&guard.state)),
2513 )
2514 .await
2515 };
2516 (cancel, future)
2517 }
2518
2519 pub async fn call_framed_with_reply(
2523 &self,
2524 target: RouteTarget,
2525 identity: BindIdentity,
2526 head: serde_json::Value,
2527 payload: Vec<u8>,
2528 opts: CallOptions,
2529 ) -> Result<CallReply, CallError> {
2530 let body = subc_protocol::framed_body::encode(&head, &payload)
2531 .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2532 self.call_inner(target, identity, (body, true), opts, None)
2533 .await
2534 }
2535
2536 pub fn call_framed_cancellable_with_reply(
2539 &self,
2540 target: RouteTarget,
2541 identity: BindIdentity,
2542 head: serde_json::Value,
2543 payload: Vec<u8>,
2544 opts: CallOptions,
2545 ) -> (
2546 CancelHandle,
2547 impl Future<Output = Result<CallReply, CallError>> + Send + '_,
2548 ) {
2549 let (cancel, registration) = CancelRegistration::new(Arc::clone(&self.shared));
2550 (cancel, async move {
2551 let guard = registration;
2552 let body = subc_protocol::framed_body::encode(&head, &payload)
2553 .map_err(|error| CallError::not_sent(format!("invalid framed request: {error}")))?;
2554 self.call_inner(
2555 target,
2556 identity,
2557 (body, true),
2558 opts,
2559 Some(Arc::clone(&guard.state)),
2560 )
2561 .await
2562 })
2563 }
2564
2565 async fn call_inner(
2566 &self,
2567 target: RouteTarget,
2568 identity: BindIdentity,
2569 body: (Vec<u8>, bool),
2570 opts: CallOptions,
2571 cancel: Option<Arc<UnaryCancel>>,
2572 ) -> Result<CallReply, CallError> {
2573 let mut history = CallAttemptHistory {
2574 never_forwarded: true,
2575 sent: false,
2576 };
2577 self.call_attempts(target, identity, body, opts, cancel, &mut history)
2578 .await
2579 .map_err(|err| {
2580 let err = if history.sent && matches!(err, CallError::StaleRouteHandle(_)) {
2581 CallError::not_sent(err.to_string())
2582 } else {
2583 err
2584 };
2585 err.with_never_forwarded(history.never_forwarded)
2586 })
2587 }
2588
2589 async fn call_attempts(
2590 &self,
2591 target: RouteTarget,
2592 identity: BindIdentity,
2593 body: (Vec<u8>, bool),
2594 opts: CallOptions,
2595 cancel: Option<Arc<UnaryCancel>>,
2596 history: &mut CallAttemptHistory,
2597 ) -> Result<CallReply, CallError> {
2598 let (body, binary) = body;
2599 let call_deadline = Instant::now() + opts.timeout;
2600 let mut resent_after_unsent_refusal = false;
2603 let consumer_identity = self.shared.route_open_consumer_identity(&opts)?;
2604 let consumer_capabilities = route_open_consumer_capabilities(&opts);
2605 let role_versions = route_open_role_versions(opts.role_versions.as_ref());
2606 let route_key = RouteKey::new(
2607 &target,
2608 &identity,
2609 consumer_identity.as_ref(),
2610 consumer_capabilities.as_deref(),
2611 )
2612 .with_role_versions(role_versions.as_ref())
2613 .with_scope(opts.scope.as_ref());
2614
2615 let route_open = RouteOpenParams {
2616 target: &target,
2617 identity: &identity,
2618 consumer_identity: &consumer_identity,
2619 consumer_capabilities: &consumer_capabilities,
2620 role_versions: &role_versions,
2621 reverse_requests: &opts.reverse_requests,
2622 scope: opts.scope.as_ref(),
2623 };
2624
2625 let mut busy_permit: Option<Arc<RoutePermit>> = None;
2626 let mut busy_delay = Duration::from_millis(25);
2627 loop {
2628 let route = self
2629 .shared
2630 .ensure_route(&route_key, &route_open, &opts, call_deadline)
2631 .await
2632 .map_err(request_not_sent_after_route_open_failure)?;
2633 if busy_permit
2634 .as_ref()
2635 .is_some_and(|permit| !permit.belongs_to(&route))
2636 {
2637 busy_permit.take();
2638 }
2639 let permit = match busy_permit.take() {
2640 Some(permit) => permit,
2641 None => route
2642 .acquire(false, call_deadline, cancel.as_ref())
2643 .await
2644 .map_err(|err| {
2645 if matches!(err, CallError::StaleRouteHandle(_)) {
2646 self.shared.route_not_sent_error(route.handle)
2647 } else {
2648 err
2649 }
2650 })?,
2651 };
2652
2653 if !self.shared.route_is_current(&route_key, &route) {
2654 drop(permit);
2655 self.shared
2656 .sleep_until_retry(call_deadline, opts.route_retry.base)
2657 .await?;
2658 continue;
2659 }
2660
2661 let daemon_origin_trusted = {
2664 let inner = self.shared.lock_inner();
2665 inner.generation == route.handle.connection_token() && inner.daemon_origin_trusted
2666 };
2667 let response = self
2668 .shared
2669 .send_request_with_slot(
2670 RequestSend {
2671 expected_handle: Some(route.handle),
2672 channel: route.handle.channel,
2673 epoch: route.handle.epoch,
2674 body: body.clone(),
2675 binary,
2676 priority: opts.priority,
2677 admission_class: opts.admission_class,
2678 deadline: call_deadline,
2679 retain_late_route_open: false,
2680 route_open_reverse_requests: None,
2681 },
2682 cancel.clone(),
2683 Some(Arc::clone(&permit)),
2684 )
2685 .await;
2686
2687 history.sent |= response.is_ok();
2688 let proven_undelivered = match &response {
2689 Ok(TerminalFrame::Error { body, flags }) => {
2690 is_refusal_on_route(daemon_origin_trusted, *flags, &body.code, route.opted_in)
2691 }
2692 Err(err) => {
2693 err.never_forwarded() == Some(true)
2694 || matches!(err, CallError::StaleRouteHandle(_))
2695 }
2696 _ => false,
2697 };
2698 history.never_forwarded &= proven_undelivered;
2699
2700 match response {
2701 Ok(TerminalFrame::Response { body, flags, .. }) => {
2702 return Ok(CallReply {
2703 body,
2704 binary: flags.is_binary(),
2705 });
2706 }
2707 Ok(TerminalFrame::StreamEnd) => {
2708 return Ok(CallReply {
2709 body: Vec::new(),
2710 binary: false,
2711 });
2712 }
2713 Ok(TerminalFrame::Error { body, flags })
2714 if error_codes::is_route_busy_retryable(flags, &body.code, route.opted_in) =>
2715 {
2716 if !self
2717 .shared
2718 .busy_backoff(call_deadline, busy_delay, cancel.as_ref())
2719 .await
2720 {
2721 return Err(busy_error(&body));
2722 }
2723 busy_delay = (busy_delay * 2).min(Duration::from_secs(1));
2724 busy_permit = Some(permit);
2725 continue;
2726 }
2727 Ok(TerminalFrame::Error { body, flags })
2731 if (error_codes::is_established_route_dead(flags, &body.code)
2732 || is_data_plane_drain_refusal(&body.code))
2733 && !resent_after_unsent_refusal
2734 && !cancel.as_ref().is_some_and(|cancel| cancel.requested())
2735 && Instant::now() < call_deadline =>
2736 {
2737 resent_after_unsent_refusal = true;
2738 self.shared.invalidate_route(&route_key, Some(route.handle));
2739 continue;
2740 }
2741 Ok(TerminalFrame::Error { body, flags })
2742 if is_daemon_refusal_before_forward(
2743 daemon_origin_trusted,
2744 flags,
2745 &body.code,
2746 ) =>
2747 {
2748 return Err(CallError::not_sent_with_cause(
2749 format!(
2750 "daemon refused before forwarding: {} ({})",
2751 body.code, body.message
2752 ),
2753 NotSentCause::DaemonRefusedBeforeForward { code: body.code },
2754 ));
2755 }
2756 Ok(TerminalFrame::Error { body, .. }) => return Err(CallError::Module(body)),
2757 Err(err)
2758 if err.is_not_sent()
2759 && Instant::now() < call_deadline
2760 && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2761 {
2762 self.shared.invalidate_route(&route_key, Some(route.handle));
2763 self.shared.ensure_connected_for_call(call_deadline).await?;
2764 continue;
2765 }
2766 Err(err)
2767 if err.outcome_cause() == Some(OutcomeUnknownCause::Deadline)
2768 && !cancel.as_ref().is_some_and(|cancel| cancel.requested()) =>
2769 {
2770 self.shared.invalidate_route_with_deadline(
2771 &route_key,
2772 Some(route.handle),
2773 true,
2774 );
2775 return Err(err);
2776 }
2777 Err(err) => return Err(err),
2778 }
2779 }
2780 }
2781
2782 pub async fn subscribe(
2794 &self,
2795 target: RouteTarget,
2796 identity: BindIdentity,
2797 body: Vec<u8>,
2798 opts: SubscribeOptions,
2799 ) -> Result<Subscription, CallError> {
2800 let open_deadline = Instant::now() + opts.route_open_timeout;
2801 let route_opts = CallOptions {
2802 scope: opts.scope.clone(),
2803 timeout: opts.route_open_timeout,
2804 priority: opts.priority,
2805 admission_class: opts.admission_class,
2806 route_retry: opts.route_retry,
2807 route_retry_deadline: opts.route_retry_deadline,
2808 consumer_identity: opts.consumer_identity.clone(),
2809 reverse_requests: opts.reverse_requests.clone(),
2810 role_versions: opts.role_versions.clone(),
2811 };
2812 let consumer_identity = self.shared.route_open_consumer_identity(&route_opts)?;
2813 let consumer_capabilities = route_open_consumer_capabilities(&route_opts);
2814 let role_versions = route_open_role_versions(route_opts.role_versions.as_ref());
2815 let route_key = RouteKey::new(
2816 &target,
2817 &identity,
2818 consumer_identity.as_ref(),
2819 consumer_capabilities.as_deref(),
2820 )
2821 .with_role_versions(role_versions.as_ref())
2822 .with_scope(opts.scope.as_ref());
2823
2824 let route_open = RouteOpenParams {
2825 target: &target,
2826 identity: &identity,
2827 consumer_identity: &consumer_identity,
2828 consumer_capabilities: &consumer_capabilities,
2829 role_versions: &role_versions,
2830 reverse_requests: &opts.reverse_requests,
2831 scope: opts.scope.as_ref(),
2832 };
2833
2834 loop {
2835 let route = self
2836 .shared
2837 .ensure_route(&route_key, &route_open, &route_opts, open_deadline)
2838 .await
2839 .map_err(request_not_sent_after_route_open_failure)?;
2840 let permit = route
2841 .acquire(true, open_deadline, None)
2842 .await
2843 .map_err(|err| {
2844 if matches!(err, CallError::StaleRouteHandle(_)) {
2845 self.shared.route_not_sent_error(route.handle)
2846 } else {
2847 err
2848 }
2849 })?;
2850
2851 if !self.shared.route_is_current(&route_key, &route) {
2852 drop(permit);
2853 self.shared
2854 .sleep_until_retry(open_deadline, opts.route_retry.base)
2855 .await?;
2856 continue;
2857 }
2858
2859 match self
2860 .shared
2861 .send_subscription(SubscriptionSend {
2862 expected_handle: Some(route.handle),
2863 channel: route.handle.channel,
2864 epoch: route.handle.epoch,
2865 body: body.clone(),
2866 priority: opts.priority,
2867 admission_class: opts.admission_class,
2868 event_buffer: opts.event_buffer,
2869 deadline: open_deadline,
2870 permit,
2871 })
2872 .await
2873 {
2874 Ok(subscription) => return Ok(subscription),
2875 Err(err) if err.is_not_sent() && Instant::now() < open_deadline => {
2876 self.shared.invalidate_route(&route_key, Some(route.handle));
2877 self.shared.ensure_connected_for_call(open_deadline).await?;
2878 continue;
2879 }
2880 Err(err) => return Err(err),
2881 }
2882 }
2883 }
2884
2885 pub async fn close_route(
2909 &self,
2910 target: RouteTarget,
2911 identity: BindIdentity,
2912 opts: CloseRouteOptions,
2913 ) {
2914 let Ok(consumer_identity) = self.shared.close_route_consumer_identity(&opts) else {
2915 return;
2916 };
2917 let consumer_capabilities = close_route_consumer_capabilities(&opts);
2918 let key = RouteKey::new(
2919 &target,
2920 &identity,
2921 consumer_identity.as_ref(),
2922 consumer_capabilities.as_deref(),
2923 )
2924 .with_role_versions(route_open_role_versions(opts.role_versions.as_ref()).as_ref())
2925 .with_scope(opts.scope.as_ref());
2926 self.shared.close_route(&key, &opts).await;
2927 }
2928
2929 pub async fn close_handle(
2938 &self,
2939 handle: &RouteHandle,
2940 opts: CloseRouteOptions,
2941 ) -> Result<(), CallError> {
2942 if opts.scope.is_some() {
2943 return Err(CallError::not_sent(
2944 "CloseRouteOptions.scope is not supported on close_handle; the handle already selects the route",
2945 ));
2946 }
2947 self.shared.close_handle(*handle, &opts).await
2948 }
2949
2950 pub fn current_epoch(&self) -> u64 {
2952 self.shared.lock_inner().epoch
2953 }
2954
2955 pub(crate) fn pool_reusable(&self) -> bool {
2956 !self.shared.close_token.is_cancelled()
2957 }
2958
2959 pub fn on_connection_state(&self, cb: impl Fn(ConnectionState) + Send + 'static) {
2961 self.shared
2962 .lock_inner()
2963 .callbacks
2964 .push(Arc::new(Mutex::new(Box::new(cb))));
2965 }
2966
2967 pub async fn close(&self) {
2969 self.shared.close_sync("consumer closed");
2970 tokio::task::yield_now().await;
2971 }
2972}
2973
2974impl Drop for SubcConsumer {
2975 fn drop(&mut self) {
2976 self.shared.close_sync("consumer dropped");
2977 }
2978}
2979
2980#[derive(Debug)]
2982pub enum ConsumerError {
2983 Discovery {
2984 source: connection_file::DiscoveryError,
2985 },
2986 ConnectionFile {
2987 path: PathBuf,
2988 source: ConnectionFileError,
2989 },
2990 NoEndpoint {
2993 path: PathBuf,
2994 },
2995 Connect {
2996 path: PathBuf,
2997 endpoint: String,
2998 source: io::Error,
2999 },
3000 Auth {
3001 path: PathBuf,
3002 endpoint: String,
3003 source: AuthError,
3004 },
3005 Closed,
3006}
3007
3008impl ConsumerError {
3009 pub(crate) fn claim(error: crate::ClaimError) -> Self {
3010 Self::Connect {
3011 path: PathBuf::new(),
3012 endpoint: "claim binding".into(),
3013 source: io::Error::other(error),
3014 }
3015 }
3016}
3017
3018impl fmt::Display for ConsumerError {
3019 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3020 match self {
3021 Self::Discovery { source } => source.fmt(f),
3022 Self::ConnectionFile { path, source } => write!(
3023 f,
3024 "failed to read subc connection file '{}': {source}",
3025 path.display()
3026 ),
3027 Self::NoEndpoint { path } => {
3028 write!(
3029 f,
3030 "subc connection file '{}' has no endpoint for the requested transport",
3031 path.display()
3032 )
3033 }
3034 Self::Connect {
3035 path,
3036 endpoint,
3037 source,
3038 } => write!(
3039 f,
3040 "failed to connect to subc endpoint {endpoint} from '{}': {source}",
3041 path.display()
3042 ),
3043 Self::Auth {
3044 path,
3045 endpoint,
3046 source,
3047 } => write!(
3048 f,
3049 "failed to authenticate to subc endpoint {endpoint} from '{}': {source}",
3050 path.display()
3051 ),
3052 Self::Closed => write!(f, "consumer closed"),
3053 }
3054 }
3055}
3056
3057impl Error for ConsumerError {
3058 fn source(&self) -> Option<&(dyn Error + 'static)> {
3059 match self {
3060 Self::Discovery { source } => Some(source),
3061 Self::ConnectionFile { source, .. } => Some(source),
3062 Self::Connect { source, .. } => Some(source),
3063 Self::Auth { source, .. } => Some(source),
3064 Self::NoEndpoint { .. } | Self::Closed => None,
3065 }
3066 }
3067}
3068
3069#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3071#[non_exhaustive]
3072pub enum OutcomeUnknownCause {
3073 Deadline,
3075 WriterClosed,
3077 ConsumerClosed,
3079 ConnectionFailed,
3081 RouteEnded,
3083 CompletionFailed,
3085}
3086
3087#[derive(Debug, Clone)]
3088struct OutcomeUnknownSource {
3089 message: String,
3090 cause: OutcomeUnknownCause,
3091 route_reason: Option<RouteEnd>,
3092}
3093
3094impl fmt::Display for OutcomeUnknownSource {
3095 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3096 f.write_str(&self.message)
3097 }
3098}
3099impl Error for OutcomeUnknownSource {}
3100
3101#[derive(Debug, Clone, PartialEq, Eq)]
3104#[non_exhaustive]
3105pub enum NotSentCause {
3106 RouteOpenRefused { code: String },
3108 RouteOpenAbandoned,
3110 BeforeQueue,
3112 WriterCapacity,
3114 WriterRejected,
3116 InvalidResponse,
3118 CompletionFailed,
3123 DaemonRefusedBeforeForward { code: String },
3125}
3126
3127#[derive(Debug, Clone)]
3128struct NotSentSource {
3129 message: String,
3130 cause: NotSentCause,
3131 never_forwarded: bool,
3132 route_reason: Option<RouteEnd>,
3133 refusal: Option<Box<RouteOpenRefused>>,
3134}
3135
3136impl fmt::Display for NotSentSource {
3137 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3138 f.write_str(&self.message)
3139 }
3140}
3141impl Error for NotSentSource {}
3142
3143#[derive(Debug)]
3145pub enum CallError {
3146 DaemonTooOld { daemon_ver: String },
3153 NotSent(Box<dyn Error + Send + Sync>),
3156 OutcomeUnknown(Box<dyn Error + Send + Sync>),
3158 Module(ErrorBody),
3161 SubscriptionBackpressure(Box<dyn Error + Send + Sync>),
3166 StaleRouteHandle(RouteHandle),
3168 CapabilityUnprovided { capability: String },
3170 CapabilityAmbiguous {
3172 capability: String,
3173 claimants: Vec<String>,
3174 },
3175 InvalidCapabilityIdentifier { capability: String },
3177}
3178
3179impl CallError {
3180 pub fn scope_bind_proof_refusal(&self) -> Option<ScopeBindProofRefusal> {
3182 match self.route_open_refusal()?.code.as_str() {
3183 error_codes::SCOPE_BIND_PROOF_REQUIRED => Some(ScopeBindProofRefusal::Required),
3184 error_codes::SCOPE_BIND_PROOF_MISMATCH => Some(ScopeBindProofRefusal::Mismatch),
3185 _ => None,
3186 }
3187 }
3188
3189 pub fn close_reason(&self) -> Option<&RouteEndReason> {
3192 self.route_end().map(|end| &end.reason)
3193 }
3194
3195 fn route_end(&self) -> Option<&RouteEnd> {
3196 match self {
3197 Self::NotSent(source) => source
3198 .downcast_ref::<NotSentSource>()?
3199 .route_reason
3200 .as_ref(),
3201 Self::OutcomeUnknown(source) => source
3202 .downcast_ref::<OutcomeUnknownSource>()?
3203 .route_reason
3204 .as_ref(),
3205 _ => None,
3206 }
3207 }
3208
3209 pub fn terminal(&self) -> Option<bool> {
3215 self.route_end()?.terminal
3216 }
3217
3218 pub fn outcome_cause(&self) -> Option<OutcomeUnknownCause> {
3221 match self {
3222 Self::OutcomeUnknown(source) => source
3223 .downcast_ref::<OutcomeUnknownSource>()
3224 .map(|source| source.cause),
3225 _ => None,
3226 }
3227 }
3228
3229 pub fn not_sent_cause(&self) -> Option<NotSentCause> {
3232 match self {
3233 Self::NotSent(source) => source
3234 .downcast_ref::<NotSentSource>()
3235 .map(|source| source.cause.clone()),
3236 _ => None,
3237 }
3238 }
3239
3240 pub fn never_forwarded(&self) -> Option<bool> {
3247 match self {
3248 Self::NotSent(source) => source
3249 .downcast_ref::<NotSentSource>()
3250 .map(|source| source.never_forwarded),
3251 _ => None,
3252 }
3253 }
3254
3255 pub fn code(&self) -> Option<&str> {
3257 match self {
3258 Self::Module(body) => Some(&body.code),
3259 Self::DaemonTooOld { .. } => Some("daemon_too_old"),
3260 Self::CapabilityUnprovided { .. } => Some("capability_unprovided"),
3261 Self::CapabilityAmbiguous { .. } => Some("capability_ambiguous"),
3262 Self::InvalidCapabilityIdentifier { .. } => Some("invalid_capability_identifier"),
3263 Self::NotSent(source) => match &source.downcast_ref::<NotSentSource>()?.cause {
3264 NotSentCause::DaemonRefusedBeforeForward { code }
3265 if code == error_codes::ROUTE_BUSY =>
3266 {
3267 Some(code)
3268 }
3269 _ => None,
3270 },
3271 Self::OutcomeUnknown(_)
3272 | Self::SubscriptionBackpressure(_)
3273 | Self::StaleRouteHandle(_) => None,
3274 }
3275 }
3276
3277 fn not_sent(reason: impl Into<String>) -> Self {
3278 Self::not_sent_with_cause(reason, NotSentCause::BeforeQueue)
3279 }
3280
3281 fn not_sent_with_cause(reason: impl Into<String>, cause: NotSentCause) -> Self {
3282 Self::NotSent(Box::new(NotSentSource {
3283 message: reason.into(),
3284 cause,
3285 never_forwarded: true,
3286 route_reason: None,
3287 refusal: None,
3288 }))
3289 }
3290
3291 fn with_never_forwarded(mut self, never_forwarded: bool) -> Self {
3292 if let Self::NotSent(source) = &mut self {
3293 if let Some(source) = source.downcast_mut::<NotSentSource>() {
3294 source.never_forwarded &= never_forwarded;
3295 }
3296 }
3297 self
3298 }
3299
3300 fn invalid_response(reason: impl Into<String>) -> Self {
3301 Self::not_sent_with_cause(reason, NotSentCause::InvalidResponse).with_never_forwarded(false)
3302 }
3303
3304 fn outcome_unknown(reason: impl Into<String>, cause: OutcomeUnknownCause) -> Self {
3305 Self::outcome_unknown_source(OutcomeUnknownSource {
3306 message: reason.into(),
3307 cause,
3308 route_reason: None,
3309 })
3310 }
3311
3312 fn outcome_unknown_source(source: OutcomeUnknownSource) -> Self {
3313 Self::OutcomeUnknown(Box::new(source))
3314 }
3315
3316 fn is_not_sent(&self) -> bool {
3317 matches!(self, Self::NotSent(_))
3318 }
3319
3320 pub fn route_open_refusal(&self) -> Option<&ErrorBody> {
3333 match self {
3334 Self::NotSent(err) => err
3335 .downcast_ref::<NotSentSource>()
3336 .and_then(|source| source.refusal.as_ref())
3337 .map(|refused| &refused.body),
3338 _ => None,
3339 }
3340 }
3341
3342 fn subscription_backpressure(reason: impl Into<String>) -> Self {
3343 Self::SubscriptionBackpressure(Box::new(SimpleError(reason.into())))
3344 }
3345}
3346
3347impl fmt::Display for CallError {
3348 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3349 match self {
3350 Self::DaemonTooOld { daemon_ver } => write!(
3351 f,
3352 "daemon_too_old: route.open requires daemon 0.39.0 or newer (connected version: {daemon_ver})"
3353 ),
3354 Self::NotSent(err) => write!(f, "request not sent: {err}"),
3355 Self::OutcomeUnknown(err) => write!(f, "request outcome unknown: {err}"),
3356 Self::Module(body) => write!(f, "module error {}: {}", body.code, body.message),
3357 Self::SubscriptionBackpressure(err) => {
3358 write!(f, "subscription event channel backpressure: {err}")
3359 }
3360 Self::StaleRouteHandle(handle) => write!(f, "stale route handle: {handle:?}"),
3361 Self::CapabilityUnprovided { capability } => {
3362 write!(
3363 f,
3364 "capability_unprovided: no catalog claimant for {capability}"
3365 )
3366 }
3367 Self::CapabilityAmbiguous {
3368 capability,
3369 claimants,
3370 } => write!(
3371 f,
3372 "capability_ambiguous: multiple catalog claimants for {capability}: {claimants:?}"
3373 ),
3374 Self::InvalidCapabilityIdentifier { capability } => write!(
3375 f,
3376 "invalid_capability_identifier: malformed capability identifier {capability:?}"
3377 ),
3378 }
3379 }
3380}
3381
3382impl Error for CallError {
3383 fn source(&self) -> Option<&(dyn Error + 'static)> {
3384 match self {
3385 Self::NotSent(err)
3386 | Self::OutcomeUnknown(err)
3387 | Self::SubscriptionBackpressure(err) => Some(err.as_ref()),
3388 Self::Module(_)
3389 | Self::DaemonTooOld { .. }
3390 | Self::StaleRouteHandle(_)
3391 | Self::CapabilityUnprovided { .. }
3392 | Self::CapabilityAmbiguous { .. }
3393 | Self::InvalidCapabilityIdentifier { .. } => None,
3394 }
3395 }
3396}
3397
3398#[derive(Debug, Clone)]
3402struct RouteOpenRefused {
3403 target: String,
3404 body: ErrorBody,
3405 most_recent: Option<ErrorBody>,
3408}
3409
3410#[derive(Debug, Clone, Copy, PartialEq, Eq)]
3412#[non_exhaustive]
3413pub enum ScopeBindProofRefusal {
3414 Required,
3415 Mismatch,
3416}
3417
3418impl fmt::Display for RouteOpenRefused {
3419 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3420 write!(
3421 f,
3422 "route.open failed for target {}: {}",
3423 self.target,
3424 DescribeRefusal(&self.body)
3425 )?;
3426 if let Some(most_recent) = &self.most_recent {
3427 write!(
3428 f,
3429 "; the most recent refusal was {}",
3430 DescribeRefusal(most_recent)
3431 )?;
3432 }
3433 Ok(())
3434 }
3435}
3436
3437impl Error for RouteOpenRefused {}
3438
3439struct DescribeRefusal<'a>(&'a ErrorBody);
3442
3443impl fmt::Display for DescribeRefusal<'_> {
3444 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3445 write!(f, "{}", self.0.code)?;
3446 if let Some(reason) = refusal_reason(self.0) {
3447 write!(f, " (reason {reason})")?;
3448 }
3449 write!(f, " ({})", self.0.message)
3450 }
3451}
3452
3453fn refusal_reason(body: &ErrorBody) -> Option<&str> {
3454 body.detail.as_ref()?.get("reason")?.as_str()
3455}
3456
3457const ADMISSION_PRESSURE_REASONS: [&str; 2] = ["open_admission_full", "target_binds_full"];
3462const ADMISSION_PRESSURE_MESSAGES: [&str; 2] =
3466 ["route.open binds in flight", "route.bind relays in flight"];
3467
3468fn route_open_refusal_rank(body: &ErrorBody) -> u8 {
3472 if body.code == error_codes::MODULE_RELOADING || body.code == error_codes::MODULE_WARMING {
3473 return 3;
3474 }
3475 let reason = refusal_reason(body);
3476 if body.code == "delegation_not_registered" || reason == Some("delegation_not_registered") {
3477 return 2;
3478 }
3479 if body.code == error_codes::TARGET_UNAVAILABLE {
3480 let admission_pressure = match reason {
3481 Some(reason) => ADMISSION_PRESSURE_REASONS.contains(&reason),
3482 None => ADMISSION_PRESSURE_MESSAGES
3483 .iter()
3484 .any(|marker| body.message.contains(marker)),
3485 };
3486 if admission_pressure {
3487 return 1;
3488 }
3489 }
3490 0
3491}
3492
3493#[derive(Default)]
3498struct RouteOpenRefusals {
3499 best: Option<ErrorBody>,
3500 most_recent: Option<ErrorBody>,
3502}
3503
3504impl RouteOpenRefusals {
3505 fn record(&mut self, body: ErrorBody) {
3506 let outranks = self
3508 .best
3509 .as_ref()
3510 .is_none_or(|best| route_open_refusal_rank(&body) >= route_open_refusal_rank(best));
3511 if outranks {
3512 self.best = Some(body);
3513 self.most_recent = None;
3514 } else {
3515 self.most_recent = Some(body);
3516 }
3517 }
3518
3519 fn into_error(self, target: String) -> Option<CallError> {
3520 let body = self.best?;
3521 Some(CallError::from_route_open_refusal(RouteOpenRefused {
3522 target,
3523 body,
3524 most_recent: self.most_recent,
3525 }))
3526 }
3527}
3528
3529fn route_target_label(target: &RouteTarget) -> String {
3532 match target {
3533 RouteTarget::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
3534 RouteTarget::ManagementSurface { module_id } => format!("management_surface:{module_id}"),
3535 RouteTarget::InternalService {
3536 module_id,
3537 service_id,
3538 } => format!("internal_service:{module_id}:{service_id}"),
3539 }
3540}
3541
3542impl CallError {
3543 fn route_open_refused(target: String, body: ErrorBody) -> Self {
3544 Self::from_route_open_refusal(RouteOpenRefused {
3545 target,
3546 body,
3547 most_recent: None,
3548 })
3549 }
3550
3551 fn from_route_open_refusal(refusal: RouteOpenRefused) -> Self {
3552 Self::NotSent(Box::new(NotSentSource {
3553 message: refusal.to_string(),
3554 cause: NotSentCause::RouteOpenRefused {
3555 code: refusal.body.code.clone(),
3556 },
3557 never_forwarded: true,
3558 route_reason: None,
3559 refusal: Some(Box::new(refusal)),
3560 }))
3561 }
3562}
3563
3564#[derive(Debug)]
3565struct SimpleError(String);
3566
3567impl fmt::Display for SimpleError {
3568 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3569 f.write_str(&self.0)
3570 }
3571}
3572
3573impl Error for SimpleError {}
3574
3575type Callback = Arc<Mutex<Box<dyn Fn(ConnectionState) + Send + 'static>>>;
3576
3577type OpeningWaiter = oneshot::Sender<Result<RouteState, SharedCallFailure>>;
3578
3579struct Opening {
3585 waiters: Vec<OpeningWaiter>,
3586 closed: bool,
3587}
3588
3589struct Shared {
3590 claim_bound: bool,
3591 connection_file: PathBuf,
3592 operator_app_candidates: Option<Vec<PathBuf>>,
3593 opts: ConsumerOptions,
3594 transport: ConsumerTransport,
3595 identity_from_environment: bool,
3596 inner: Mutex<Inner>,
3597 notify: Notify,
3598 #[cfg(test)]
3599 before_wait: Mutex<Option<Box<dyn FnOnce() + Send>>>,
3600 close_token: CancellationToken,
3601 last_inbound_ms: AtomicU64,
3605 liveness_probe_running: AtomicBool,
3607 pushes_dropped_no_receiver: AtomicU64,
3608 control_pushes_dropped: AtomicU64,
3613 pushes_dropped_receiver_full: AtomicU64,
3618 random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
3621 route_open_slots: Semaphore,
3627 route_description: tokio::sync::Mutex<()>,
3630}
3631
3632struct Inner {
3633 generation: u64,
3634 daemon_origin_trusted: bool,
3635 daemon_ver: String,
3636 accepts_close_reasons: Option<bool>,
3637 epoch: u64,
3638 next_corr: Option<u64>,
3639 writer: Option<mpsc::Sender<WriteCommand>>,
3640 pending: HashMap<PendingKey, PendingEntry>,
3641 wire_slots: HashMap<PendingKey, Arc<RoutePermit>>,
3642 routes: HashMap<RouteKey, RouteState>,
3643 route_by_channel: HashMap<u16, RouteKey>,
3644 one_shot_routes: HashMap<u16, RouteState>,
3645 route_epochs: HashMap<u16, RouteHandle>,
3646 route_targets: HashMap<RouteHandle, RouteOpenTarget>,
3647 retired_routes: HashSet<RouteHandle>,
3648 retirement_goodbyes: HashSet<RouteHandle>,
3649 retirement_queue: VecDeque<RouteHandle>,
3650 retirement_notify: Arc<Notify>,
3651 retirement_task: Option<JoinHandle<()>>,
3652 route_modules: HashMap<u16, String>,
3653 route_end_reasons: HashMap<u16, (RouteEnd, bool)>,
3654 legacy_channel_reasons: HashMap<u16, RouteEnd>,
3655 push_event_receivers: HashMap<RouteHandle, mpsc::Sender<PushEvent>>,
3656 control_push_receiver: Option<mpsc::Sender<ControlPush>>,
3661 dropped_route_frames: u64,
3662 openings: HashMap<RouteKey, Opening>,
3663 callbacks: Vec<Callback>,
3664 closed: bool,
3665 reconnect: ReconnectState,
3666 restored_token: u64,
3667 reader_task: Option<JoinHandle<()>>,
3668 writer_task: Option<JoinHandle<()>>,
3669}
3670
3671impl Inner {
3672 fn record_route_end(&mut self, push: &ControlPush) {
3673 let Some(reason) = push.route_close_reason() else {
3674 return;
3675 };
3676 let end = RouteEnd {
3677 reason: RouteEndReason::Daemon(reason),
3678 terminal: (push.op == "route.closed")
3679 .then(|| {
3680 push.body
3681 .get("terminal")
3682 .and_then(serde_json::Value::as_bool)
3683 })
3684 .flatten(),
3685 };
3686 if let Some(channels) = push.body.get("channels") {
3687 if let Some(channels) = channels.as_array() {
3688 for channel in channels
3689 .iter()
3690 .filter_map(|v| v.as_u64().and_then(|v| u16::try_from(v).ok()))
3691 {
3692 let final_reason = push.op == "route.closed";
3693 if final_reason
3694 || !self
3695 .route_end_reasons
3696 .get(&channel)
3697 .is_some_and(|(_, final_reason)| *final_reason)
3698 {
3699 self.route_end_reasons
3700 .insert(channel, (end.clone(), final_reason));
3701 }
3702 }
3703 }
3704 } else if let Some(module) = push.body.get("module_id").and_then(|v| v.as_str()) {
3705 for (&channel, target) in &self.route_modules {
3706 if target == module {
3707 self.legacy_channel_reasons.insert(channel, end.clone());
3708 }
3709 }
3710 }
3711 }
3712
3713 fn route_end(&self, channel: u16) -> RouteEnd {
3714 self.route_end_reasons
3715 .get(&channel)
3716 .map(|(reason, _)| reason.clone())
3717 .or_else(|| self.legacy_channel_reasons.get(&channel).cloned())
3718 .unwrap_or_else(|| RouteEndReason::Unknown.into())
3719 }
3720
3721 #[cfg(test)]
3722 fn route_end_reason(&self, channel: u16) -> RouteEndReason {
3723 self.route_end(channel).reason
3724 }
3725
3726 fn cache_route(&mut self, key: RouteKey, route: RouteState) -> RouteState {
3727 let cached = self.routes.entry(key.clone()).or_insert(route).clone();
3728 let previous = self
3729 .route_by_channel
3730 .insert(cached.handle.channel, key.clone());
3731 debug_assert!(previous.as_ref().is_none_or(|previous| previous == &key));
3732 self.route_epochs
3733 .insert(cached.handle.channel, cached.handle);
3734 cached
3735 }
3736
3737 fn remove_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3738 let route = self.evict_route(key)?;
3739 release_reverse_request_registry(route.handle);
3740 Some(route)
3741 }
3742
3743 fn evict_route(&mut self, key: &RouteKey) -> Option<RouteState> {
3744 let route = self.routes.remove(key)?;
3745 let indexed = self.route_by_channel.remove(&route.handle.channel);
3746 debug_assert_eq!(indexed.as_ref(), Some(key));
3747 Some(route)
3748 }
3749
3750 fn reap_retired_route(&mut self, handle: RouteHandle) {
3751 if !self.retired_routes.contains(&handle)
3754 || self
3755 .pending
3756 .keys()
3757 .chain(self.wire_slots.keys())
3758 .any(|key| {
3759 key.generation == handle.connection_token()
3760 && key.channel == handle.channel
3761 && key.epoch == handle.epoch
3762 })
3763 {
3764 return;
3765 }
3766 let handle = *self
3769 .retired_routes
3770 .get(&handle)
3771 .expect("retired route exists");
3772 if self.retirement_goodbyes.contains(&handle) {
3773 if !self.queue_retirement_goodbye(handle) {
3774 return;
3777 }
3778 self.retirement_goodbyes.remove(&handle);
3779 }
3780 self.retired_routes.remove(&handle);
3781 if self.route_epochs.get(&handle.channel) == Some(&handle) {
3782 self.route_epochs.remove(&handle.channel);
3783 self.route_targets.remove(&handle);
3784 self.push_event_receivers.remove(&handle);
3785 }
3786 release_reverse_request_registry(handle);
3787 }
3788
3789 fn queue_retirement_goodbye(&mut self, handle: RouteHandle) -> bool {
3790 if self.generation != handle.connection_token()
3791 || self.route_epochs.get(&handle.channel) != Some(&handle)
3792 || self.writer.is_none()
3793 {
3794 return true;
3795 }
3796 if self.retirement_queue.is_empty() {
3797 let frame = Frame::build(
3798 FrameType::Goodbye,
3799 Flags::new(false, Priority::Interactive, false),
3800 handle.channel,
3801 handle.epoch,
3802 0,
3803 Vec::new(),
3804 )
3805 .expect("header-only route GOODBYE is valid");
3806 if self
3807 .writer
3808 .as_ref()
3809 .unwrap()
3810 .try_send(WriteCommand {
3811 frame,
3812 pending: None,
3813 })
3814 .is_ok()
3815 {
3816 return true;
3817 }
3818 }
3819 if !self.retirement_queue.contains(&handle) {
3822 self.retirement_queue.push_back(handle);
3823 }
3824 self.retirement_notify.notify_one();
3825 false
3826 }
3827
3828 fn remove_pending(&mut self, key: &PendingKey) -> Option<PendingEntry> {
3829 let entry = self.pending.remove(key);
3830 if entry.as_ref().is_some_and(|entry| !entry.accepted) {
3831 if let Some(slot) = self.wire_slots.remove(key) {
3832 slot.release();
3833 }
3834 }
3835 self.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
3836 entry
3837 }
3838
3839 fn release_wire_slots(&mut self, handle: RouteHandle) {
3840 self.wire_slots.retain(|key, slot| {
3841 let keep = key.generation != handle.connection_token()
3842 || key.channel != handle.channel
3843 || key.epoch != handle.epoch;
3844 if !keep {
3845 slot.release();
3846 }
3847 keep
3848 });
3849 }
3850
3851 fn remove_route_by_handle(&mut self, handle: RouteHandle) -> Option<RouteState> {
3852 if let Some(key) = self.route_by_channel.get(&handle.channel).cloned() {
3853 let matches = self
3854 .routes
3855 .get(&key)
3856 .is_some_and(|route| route.handle == handle);
3857 debug_assert!(matches);
3858 if matches {
3859 return self.remove_route(&key);
3860 }
3861 }
3862 let route = self
3863 .one_shot_routes
3864 .get(&handle.channel)
3865 .is_some_and(|route| route.handle == handle)
3866 .then(|| self.one_shot_routes.remove(&handle.channel))
3867 .flatten();
3868 if let Some(route) = &route {
3869 release_reverse_request_registry(route.handle);
3870 }
3871 route
3872 }
3873
3874 fn drain_routes(&mut self) -> Vec<RouteState> {
3875 self.route_targets.clear();
3876 for (_, slot) in self.wire_slots.drain() {
3877 slot.release();
3878 }
3879 self.retirement_goodbyes.clear();
3880 self.retirement_queue.clear();
3881 if let Some(task) = self.retirement_task.take() {
3882 task.abort();
3883 }
3884 for handle in self.retired_routes.drain() {
3885 release_reverse_request_registry(handle);
3886 }
3887 self.route_by_channel.clear();
3888 let routes = self
3889 .routes
3890 .drain()
3891 .map(|(_, route)| route)
3892 .chain(self.one_shot_routes.drain().map(|(_, route)| route))
3893 .collect::<Vec<_>>();
3894 for route in &routes {
3895 release_reverse_request_registry(route.handle);
3896 }
3897 routes
3898 }
3899
3900 fn close_routes(&mut self) {
3901 self.push_event_receivers.clear();
3902 for route in self.drain_routes() {
3903 route.close();
3904 }
3905 }
3906}
3907
3908impl Shared {
3909 fn new(connection_file: PathBuf, opts: ConsumerOptions) -> Self {
3910 Self::with_transport(connection_file, opts, ConsumerTransport::Tcp)
3911 }
3912
3913 fn with_transport(
3914 connection_file: PathBuf,
3915 opts: ConsumerOptions,
3916 transport: ConsumerTransport,
3917 ) -> Self {
3918 Self {
3919 claim_bound: crate::registration::bound(),
3920 connection_file,
3921 operator_app_candidates: None,
3922 opts,
3923 transport,
3924 identity_from_environment: true,
3925 inner: Mutex::new(Inner {
3926 generation: 1,
3927 daemon_origin_trusted: false,
3928 daemon_ver: String::new(),
3929 accepts_close_reasons: None,
3930 epoch: 1,
3931 next_corr: Some(1),
3932 writer: None,
3933 pending: HashMap::new(),
3934 wire_slots: HashMap::new(),
3935 routes: HashMap::new(),
3936 route_by_channel: HashMap::new(),
3937 one_shot_routes: HashMap::new(),
3938 route_epochs: HashMap::new(),
3939 route_targets: HashMap::new(),
3940 retired_routes: HashSet::new(),
3941 retirement_goodbyes: HashSet::new(),
3942 retirement_queue: VecDeque::new(),
3943 retirement_notify: Arc::new(Notify::new()),
3944 retirement_task: None,
3945 route_modules: HashMap::new(),
3946 route_end_reasons: HashMap::new(),
3947 legacy_channel_reasons: HashMap::new(),
3948 push_event_receivers: HashMap::new(),
3949 control_push_receiver: None,
3950 dropped_route_frames: 0,
3951 openings: HashMap::new(),
3952 callbacks: Vec::new(),
3953 closed: false,
3954 reconnect: ReconnectState::Idle,
3955 restored_token: 0,
3956 reader_task: None,
3957 writer_task: None,
3958 }),
3959 notify: Notify::new(),
3960 #[cfg(test)]
3961 before_wait: Mutex::new(None),
3962 close_token: CancellationToken::new(),
3963 last_inbound_ms: AtomicU64::new(0),
3964 liveness_probe_running: AtomicBool::new(false),
3965 pushes_dropped_no_receiver: AtomicU64::new(0),
3966 control_pushes_dropped: AtomicU64::new(0),
3967 pushes_dropped_receiver_full: AtomicU64::new(0),
3968 random_unit: Box::new(default_random_unit),
3969 route_open_slots: Semaphore::new(MAX_ROUTE_OPENS_IN_FLIGHT),
3970 route_description: tokio::sync::Mutex::new(()),
3971 }
3972 }
3973
3974 fn jittered(&self, delay: Duration) -> Duration {
3979 let unit = (self.random_unit)();
3980 let unit = if unit.is_finite() {
3981 unit.clamp(0.0, 1.0)
3982 } else {
3983 0.0
3984 };
3985 let half = delay / 2;
3986 half + half.mul_f64(unit)
3987 }
3988
3989 async fn paced_route_open(
3992 self: &Arc<Self>,
3993 body: Vec<u8>,
3994 deadline: Instant,
3995 reverse_requests: Option<ReverseRequestRegistry>,
3996 ) -> Result<TerminalFrame, CallError> {
3997 let _slot = match timeout_at(deadline, self.route_open_slots.acquire()).await {
3998 Ok(Ok(permit)) => permit,
3999 Ok(Err(_)) => return Err(CallError::not_sent("consumer closed")),
4000 Err(_) => {
4001 return Err(CallError::not_sent(format!(
4002 "deadline elapsed waiting for one of {MAX_ROUTE_OPENS_IN_FLIGHT} route.open slots"
4003 )));
4004 }
4005 };
4006 self.control_call(body, deadline, true, reverse_requests)
4007 .await
4008 }
4009
4010 fn lock_inner(&self) -> MutexGuard<'_, Inner> {
4011 self.inner
4012 .lock()
4013 .unwrap_or_else(|poisoned| poisoned.into_inner())
4014 }
4015
4016 fn install_initial(self: &Arc<Self>, opened: OpenedConnection) -> Result<(), ConsumerError> {
4017 self.install_connection(opened, InstallKind::Initial)
4018 .map(|_| ())
4019 }
4020
4021 fn install_reconnected(
4022 self: &Arc<Self>,
4023 opened: OpenedConnection,
4024 ) -> Result<(u64, u64), ConsumerError> {
4025 let generation_epoch = self.install_connection(opened, InstallKind::Reconnect)?;
4026 self.notify.notify_waiters();
4027 Ok(generation_epoch)
4028 }
4029
4030 fn install_connection(
4031 self: &Arc<Self>,
4032 opened: OpenedConnection,
4033 kind: InstallKind,
4034 ) -> Result<(u64, u64), ConsumerError> {
4035 if self.close_token.is_cancelled() {
4036 return Err(ConsumerError::Closed);
4037 }
4038
4039 let (reader, writer) = tokio::io::split(opened.stream);
4040 let (tx, rx) = mpsc::channel(EGRESS_BUFFER);
4041 let (generation, epoch, old_reader, old_writer) = {
4042 let mut inner = self.lock_inner();
4043 if inner.closed {
4044 return Err(ConsumerError::Closed);
4045 }
4046 let (generation, epoch) = match kind {
4047 InstallKind::Initial => (inner.generation, inner.epoch),
4048 InstallKind::Reconnect => {
4049 inner.generation = inner
4050 .generation
4051 .checked_add(1)
4052 .ok_or(ConsumerError::Closed)?;
4053 inner.epoch = inner.epoch.checked_add(1).ok_or(ConsumerError::Closed)?;
4054 (inner.generation, inner.epoch)
4055 }
4056 };
4057 inner.close_routes();
4058 inner.route_epochs.clear();
4059 inner.route_targets.clear();
4060 inner.route_modules.clear();
4061 inner.route_end_reasons.clear();
4062 inner.legacy_channel_reasons.clear();
4063 inner.next_corr = Some(1);
4064 inner.writer = Some(tx);
4065 inner.daemon_origin_trusted = opened.daemon_origin_trusted;
4066 inner.daemon_ver = opened.daemon_ver;
4067 inner.accepts_close_reasons = None;
4068 self.last_inbound_ms.store(0, Ordering::Release);
4069 (
4070 generation,
4071 epoch,
4072 inner.reader_task.take(),
4073 inner.writer_task.take(),
4074 )
4075 };
4076
4077 if let Some(handle) = old_reader {
4078 handle.abort();
4079 }
4080 if let Some(handle) = old_writer {
4081 handle.abort();
4082 }
4083
4084 let reader_shared = Arc::clone(self);
4085 let reader_task = tokio::spawn(async move {
4086 reader_loop(reader_shared, reader, generation).await;
4087 });
4088 let writer_shared = Arc::clone(self);
4089 let writer_task = tokio::spawn(async move {
4090 writer_loop(writer_shared, writer, rx, generation).await;
4091 });
4092
4093 {
4094 let mut inner = self.lock_inner();
4095 if inner.closed || inner.generation != generation {
4096 reader_task.abort();
4097 writer_task.abort();
4098 return Err(ConsumerError::Closed);
4099 }
4100 inner.reader_task = Some(reader_task);
4101 inner.writer_task = Some(writer_task);
4102 let retirement_shared = Arc::clone(self);
4103 let retirement_notify = Arc::clone(&inner.retirement_notify);
4104 inner.retirement_task = Some(tokio::spawn(async move {
4105 retirement_goodbye_loop(retirement_shared, generation, retirement_notify).await;
4106 }));
4107 }
4108
4109 Ok((generation, epoch))
4110 }
4111
4112 async fn ensure_connected_for_call(
4113 self: &Arc<Self>,
4114 deadline: Instant,
4115 ) -> Result<(), CallError> {
4116 loop {
4117 if Instant::now() >= deadline {
4118 return Err(CallError::not_sent(
4119 "call deadline elapsed waiting for reconnection",
4120 ));
4121 }
4122 let notified = self.notify.notified();
4131 tokio::pin!(notified);
4132 let action = {
4133 let mut inner = self.lock_inner();
4134 notified.as_mut().enable();
4135 if inner.closed {
4136 return Err(CallError::not_sent("consumer closed"));
4137 }
4138 if inner.writer.is_some() {
4139 return Ok(());
4140 }
4141 let generation = inner.generation;
4142 let reconnect_is_live = match &inner.reconnect {
4143 ReconnectState::Idle => false,
4144 ReconnectState::Inline { generation: active } => *active == generation,
4145 ReconnectState::Background {
4146 generation: active,
4147 task,
4148 } => *active == generation && !task.is_finished(),
4149 };
4150 if reconnect_is_live {
4151 EnsureAction::Wait
4152 } else {
4153 let stale_task =
4154 match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4155 ReconnectState::Background { task, .. } => Some(task),
4156 ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4157 };
4158 inner.reconnect = ReconnectState::Inline { generation };
4159 EnsureAction::Lead {
4160 generation,
4161 stale_task,
4162 }
4163 }
4164 };
4165
4166 match action {
4167 EnsureAction::Wait => {
4168 #[cfg(test)]
4169 {
4170 let hook = self.before_wait.lock().unwrap().take();
4171 if let Some(hook) = hook {
4172 hook();
4173 }
4174 }
4175 timeout_at(deadline, notified).await.map_err(|_| {
4176 CallError::not_sent("call deadline elapsed waiting for reconnection")
4177 })?;
4178 }
4179 EnsureAction::Lead {
4180 generation,
4181 stale_task,
4182 } => {
4183 if let Some(handle) = stale_task {
4184 handle.abort();
4185 }
4186 let mut guard = InlineReconnectGuard::new(Arc::clone(self), generation);
4187 let result = timeout_at(deadline, self.reconnect_with_retry(generation)).await;
4188 guard.finish();
4189 return match result {
4190 Ok(Ok(())) => Ok(()),
4191 Ok(Err(err)) => Err(CallError::not_sent(err.to_string())),
4192 Err(_) => Err(CallError::not_sent(
4193 "call deadline elapsed waiting for reconnection",
4194 )),
4195 };
4196 }
4197 }
4198 }
4199 }
4200
4201 fn spawn_reconnect(self: &Arc<Self>, generation: u64) -> bool {
4202 let stale_task = {
4206 let mut inner = self.lock_inner();
4207 if inner.closed || inner.writer.is_some() || inner.generation != generation {
4208 return false;
4209 }
4210 let should_spawn = match &inner.reconnect {
4211 ReconnectState::Idle => true,
4212 ReconnectState::Inline { generation: active } => *active < generation,
4213 ReconnectState::Background {
4214 generation: active,
4215 task,
4216 } => *active < generation || (*active == generation && task.is_finished()),
4217 };
4218 if !should_spawn {
4219 return false;
4220 }
4221
4222 let stale_task = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4223 ReconnectState::Background { task, .. } => Some(task),
4224 ReconnectState::Idle | ReconnectState::Inline { .. } => None,
4225 };
4226 let shared = Arc::clone(self);
4227 let handle = tokio::spawn(async move {
4228 let _result = shared.reconnect_with_retry(generation).await;
4229 shared.finish_background_reconnect(generation);
4230 });
4231 inner.reconnect = ReconnectState::Background {
4232 generation,
4233 task: handle,
4234 };
4235 stale_task
4236 };
4237 if let Some(handle) = stale_task {
4238 handle.abort();
4239 }
4240 true
4241 }
4242
4243 async fn reconnect_with_retry(
4244 self: &Arc<Self>,
4245 reconnect_generation: u64,
4246 ) -> Result<(), ConsumerError> {
4247 let mut last_error: Option<ConsumerError> = None;
4248 for attempt in 1..=self.opts.reconnect_backoff.max_attempts {
4249 if self.close_token.is_cancelled() {
4250 return Err(ConsumerError::Closed);
4251 }
4252 if !self.reconnect_attempt_is_current(reconnect_generation) {
4253 return Ok(());
4254 }
4255
4256 match open_connection(
4257 &self.connection_file,
4258 self.opts.handshake_timeout,
4259 self.transport,
4260 self.operator_app_candidates.as_deref(),
4261 )
4262 .await
4263 {
4264 Ok(opened) => {
4265 if !self.reconnect_attempt_is_current(reconnect_generation) {
4268 return Ok(());
4269 }
4270 let (generation, epoch) = self.install_reconnected(opened)?;
4271 self.schedule_restored(generation, epoch);
4272 return Ok(());
4273 }
4274 Err(err) => {
4275 let transient = is_reconnect_transient(&err);
4276 last_error = Some(err);
4277 if !transient || attempt >= self.opts.reconnect_backoff.max_attempts {
4278 break;
4279 }
4280 let delay =
4282 self.jittered(self.opts.reconnect_backoff.delay_after_attempt(attempt));
4283 tokio::select! {
4284 () = self.close_token.cancelled() => return Err(ConsumerError::Closed),
4285 () = sleep(delay) => {}
4286 }
4287 }
4288 }
4289 }
4290 Err(last_error.unwrap_or(ConsumerError::Closed))
4291 }
4292
4293 fn reconnect_attempt_is_current(&self, generation: u64) -> bool {
4294 let inner = self.lock_inner();
4295 !inner.closed
4296 && inner.writer.is_none()
4297 && inner.generation == generation
4298 && matches!(
4299 &inner.reconnect,
4300 ReconnectState::Inline { generation: active }
4301 | ReconnectState::Background {
4302 generation: active,
4303 ..
4304 } if *active == generation
4305 )
4306 }
4307
4308 fn finish_inline_reconnect(&self, generation: u64) {
4309 let finished = {
4310 let mut inner = self.lock_inner();
4311 if matches!(
4312 &inner.reconnect,
4313 ReconnectState::Inline { generation: active } if *active == generation
4314 ) {
4315 inner.reconnect = ReconnectState::Idle;
4316 true
4317 } else {
4318 false
4319 }
4320 };
4321 if finished {
4322 self.notify.notify_waiters();
4323 }
4324 }
4325
4326 fn finish_background_reconnect(&self, generation: u64) {
4327 let completed_task = {
4328 let mut inner = self.lock_inner();
4329 if !matches!(
4330 &inner.reconnect,
4331 ReconnectState::Background { generation: active, .. } if *active == generation
4332 ) {
4333 None
4334 } else {
4335 match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
4336 ReconnectState::Background { task, .. } => Some(task),
4337 ReconnectState::Idle | ReconnectState::Inline { .. } => unreachable!(),
4338 }
4339 }
4340 };
4341 if completed_task.is_some() {
4342 drop(completed_task);
4343 self.notify.notify_waiters();
4344 }
4345 }
4346
4347 fn schedule_restored(self: &Arc<Self>, generation: u64, epoch: u64) {
4348 let token = {
4349 let mut inner = self.lock_inner();
4350 inner.restored_token = inner.restored_token.saturating_add(1);
4351 inner.restored_token
4352 };
4353 let shared = Arc::clone(self);
4354 tokio::spawn(async move {
4355 tokio::select! {
4356 () = shared.close_token.cancelled() => {}
4357 () = sleep(shared.opts.restored_debounce) => {
4358 let should_emit = {
4359 let inner = shared.lock_inner();
4360 !inner.closed
4361 && inner.generation == generation
4362 && inner.epoch == epoch
4363 && inner.restored_token == token
4364 && inner.writer.is_some()
4365 };
4366 if should_emit {
4367 shared.emit_connection_state(ConnectionState::Restored { epoch });
4368 }
4369 }
4370 }
4371 });
4372 }
4373
4374 fn install_one_shot_route(&self, route: RouteState) -> Result<(), CallError> {
4375 let handle = route.handle;
4376 let mut inner = self.lock_inner();
4377 if inner.closed || inner.generation != handle.connection_token() || inner.writer.is_none() {
4378 return Err(CallError::StaleRouteHandle(handle));
4379 }
4380 if inner
4386 .route_epochs
4387 .get(&handle.channel)
4388 .is_some_and(|existing| *existing != handle)
4389 {
4390 return Err(CallError::not_sent(
4391 "daemon returned a route channel already in use",
4392 ));
4393 }
4394 inner.one_shot_routes.insert(handle.channel, route);
4395 inner.route_epochs.insert(handle.channel, handle);
4396 Ok(())
4397 }
4398
4399 async fn ensure_route(
4400 self: &Arc<Self>,
4401 key: &RouteKey,
4402 route_open: &RouteOpenParams<'_>,
4403 opts: &CallOptions,
4404 call_deadline: Instant,
4405 ) -> Result<RouteState, CallError> {
4406 loop {
4407 let action = {
4408 let mut inner = self.lock_inner();
4409 if inner.closed {
4410 return Err(CallError::not_sent("consumer closed"));
4411 }
4412 if let Some(route) = inner.routes.get(key) {
4413 if route.handle.connection_token() == inner.generation && inner.writer.is_some()
4414 {
4415 return Ok(route.clone());
4416 }
4417 }
4418 if let Some(opening) = inner.openings.get_mut(key) {
4419 let (tx, rx) = oneshot::channel();
4420 opening.waiters.push(tx);
4421 RouteOpenAction::Wait(rx)
4422 } else {
4423 inner.openings.insert(
4424 key.clone(),
4425 Opening {
4426 waiters: Vec::new(),
4427 closed: false,
4428 },
4429 );
4430 RouteOpenAction::Lead
4431 }
4432 };
4433
4434 match action {
4435 RouteOpenAction::Wait(rx) => match timeout_at(call_deadline, rx).await {
4436 Ok(Ok(Ok(route))) => return Ok(route),
4437 Ok(Ok(Err(err))) => return Err(err.into_call_error()),
4438 Ok(Err(_)) => continue,
4439 Err(_) => {
4440 return Err(CallError::not_sent_with_cause(
4441 "call deadline elapsed waiting for route.open",
4442 NotSentCause::RouteOpenAbandoned,
4443 ));
4444 }
4445 },
4446 RouteOpenAction::Lead => {
4447 let mut guard = OpeningGuard::new(Arc::clone(self), key.clone());
4448 let result = self
4449 .open_route_with_retry(key, route_open, opts, call_deadline)
4450 .await
4451 .map_err(SharedCallFailure::from);
4452 guard.finish(result.clone());
4453 return result.map_err(SharedCallFailure::into_call_error);
4454 }
4455 }
4456 }
4457 }
4458
4459 async fn open_route_with_retry(
4460 self: &Arc<Self>,
4461 key: &RouteKey,
4462 route_open: &RouteOpenParams<'_>,
4463 opts: &CallOptions,
4464 call_deadline: Instant,
4465 ) -> Result<RouteState, CallError> {
4466 let route_deadline = (Instant::now() + opts.route_retry_deadline).min(call_deadline);
4467 let mut attempt = 0usize;
4468 let mut refusals = RouteOpenRefusals::default();
4473 let expired = |err: CallError, refusals: &mut RouteOpenRefusals| {
4483 let ended_by_deadline =
4484 err.is_not_sent() || err.outcome_cause() == Some(OutcomeUnknownCause::Deadline);
4485 if ended_by_deadline && Instant::now() >= route_deadline {
4486 if let Some(refused) = std::mem::take(refusals).into_error(key.target_label()) {
4487 return refused;
4488 }
4489 }
4490 err
4491 };
4492 loop {
4493 attempt = attempt.saturating_add(1);
4494 let body = serde_json::to_vec(&ClientControlRequest::RouteOpen {
4495 busy_refusals: Some(true),
4496 target: route_open.target.clone(),
4497 identity: route_open.identity.clone(),
4498 consumer_identity: route_open.consumer_identity.clone(),
4499 consumer_capabilities: route_open.consumer_capabilities.clone(),
4500 role_versions: route_open.role_versions.clone(),
4501 admission_facts: None,
4502 scope: route_open.scope.cloned(),
4503 })
4504 .map_err(|err| CallError::not_sent(format!("failed to encode route.open: {err}")))?;
4505 match self
4506 .paced_route_open(
4507 body,
4508 route_deadline,
4509 Some(route_open.reverse_requests.clone()),
4510 )
4511 .await
4512 {
4513 Ok(TerminalFrame::Response {
4514 generation, body, ..
4515 }) => {
4516 let (response, _) = decode_route_open_response(&body).map_err(|err| {
4517 CallError::not_sent_with_cause(
4518 format!("failed to decode route.open response: {err}"),
4519 NotSentCause::RouteOpenAbandoned,
4520 )
4521 })?;
4522 let ClientControlResponse::RouteOpen {
4523 route_channel,
4524 route_epoch,
4525 request_window,
4526 watch_window,
4527 ..
4528 } = response
4529 else {
4530 return Err(CallError::not_sent_with_cause(
4531 "route.open returned an unexpected control response",
4532 NotSentCause::RouteOpenAbandoned,
4533 ));
4534 };
4535 let handle = self
4536 .ingress_handle(generation, route_channel, route_epoch)
4537 .unwrap_or_else(|| {
4538 RouteHandle::new_consumer(
4539 route_channel,
4540 route_epoch,
4541 generation,
4542 route_open.reverse_requests.clone(),
4543 )
4544 });
4545 let route = RouteState::windows(handle, request_window, watch_window);
4546 let install = {
4547 let mut inner = self.lock_inner();
4548 if inner.closed {
4549 return Err(CallError::not_sent("consumer closed"));
4550 }
4551 let closed_during_open = inner.openings.get(key).is_some_and(|o| o.closed);
4556 if closed_during_open
4557 || inner.generation != generation
4558 || inner.writer.is_none()
4559 {
4560 RouteInstall::Discard {
4561 closed: closed_during_open,
4562 }
4563 } else {
4564 let cached = inner.cache_route(key.clone(), route.clone());
4565 RouteInstall::Cached(cached)
4566 }
4567 };
4568 match install {
4569 RouteInstall::Cached(cached) => return Ok(cached),
4570 RouteInstall::Discard { closed } => {
4571 if closed {
4572 self.send_route_goodbye(route.handle, true);
4575 self.uninstall_route_handle(route.handle);
4576 return Err(CallError::not_sent_with_cause(
4577 "route was closed before route.open completed",
4578 NotSentCause::RouteOpenAbandoned,
4579 ));
4580 }
4581 }
4583 }
4584 self.sleep_until_retry(route_deadline, self.jittered(opts.route_retry.base))
4585 .await?;
4586 }
4587 Ok(TerminalFrame::Error { body, .. }) => {
4588 if !is_retryable_route_open_code(&body.code) {
4597 return Err(CallError::route_open_refused(key.target_label(), body));
4598 }
4599 refusals.record(body);
4600 if Instant::now() >= route_deadline {
4601 return Err(std::mem::take(&mut refusals)
4603 .into_error(key.target_label())
4604 .unwrap_or_else(|| {
4605 CallError::not_sent("route.open retry deadline elapsed")
4606 }));
4607 }
4608 let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4609 if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4610 return Err(expired(err, &mut refusals));
4611 }
4612 continue;
4613 }
4614 Ok(TerminalFrame::StreamEnd) => {
4615 return Err(CallError::not_sent_with_cause(
4616 "route.open returned StreamEnd",
4617 NotSentCause::RouteOpenAbandoned,
4618 ));
4619 }
4620 Err(err) if err.is_not_sent() && Instant::now() < route_deadline => {
4621 let delay = self.jittered(opts.route_retry.delay_after_attempt(attempt));
4622 if let Err(err) = self.sleep_until_retry(route_deadline, delay).await {
4623 return Err(expired(err, &mut refusals));
4624 }
4625 }
4626 Err(err) => return Err(expired(err, &mut refusals)),
4627 }
4628 }
4629
4630 #[allow(unreachable_code)]
4631 Err(CallError::not_sent(format!(
4632 "route.open retry deadline elapsed for target {}",
4633 key.target_label()
4634 )))
4635 }
4636
4637 async fn sleep_until_retry(&self, deadline: Instant, delay: Duration) -> Result<(), CallError> {
4638 if Instant::now() >= deadline {
4639 return Err(CallError::not_sent("retry deadline elapsed"));
4640 }
4641 let bounded = delay.min(deadline.saturating_duration_since(Instant::now()));
4642 tokio::select! {
4643 () = self.close_token.cancelled() => Err(CallError::not_sent("consumer closed")),
4644 () = sleep(bounded) => Ok(()),
4645 }
4646 }
4647
4648 async fn control_call(
4649 self: &Arc<Self>,
4650 body: Vec<u8>,
4651 deadline: Instant,
4652 retain_late_route_open: bool,
4653 route_open_reverse_requests: Option<ReverseRequestRegistry>,
4654 ) -> Result<TerminalFrame, CallError> {
4655 self.ensure_connected_for_call(deadline).await?;
4656 if retain_late_route_open {
4657 {
4658 let inner = self.lock_inner();
4659 if !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4660 return Err(CallError::DaemonTooOld {
4661 daemon_ver: inner.daemon_ver.clone(),
4662 });
4663 }
4664 }
4665 self.describe_route_close_reasons(deadline).await?;
4666 }
4667 self.send_request(RequestSend {
4668 binary: false,
4669 expected_handle: None,
4670 channel: 0,
4671 epoch: 0,
4672 body,
4673 priority: Priority::Interactive,
4674 admission_class: AdmissionClass::Normal,
4675 deadline,
4676 retain_late_route_open,
4677 route_open_reverse_requests,
4678 })
4679 .await
4680 }
4681
4682 async fn describe_route_close_reasons(
4683 self: &Arc<Self>,
4684 deadline: Instant,
4685 ) -> Result<(), CallError> {
4686 let _lookup = timeout_at(deadline, self.route_description.lock())
4687 .await
4688 .map_err(|_| CallError::not_sent("deadline waiting for server.describe"))?;
4689 loop {
4690 self.ensure_connected_for_call(deadline).await?;
4691 let generation = {
4692 let inner = self.lock_inner();
4693 if inner.accepts_close_reasons.is_some() {
4694 return Ok(());
4695 }
4696 inner.generation
4697 };
4698 let reply = self
4701 .send_request(RequestSend {
4702 binary: false,
4703 expected_handle: None,
4704 channel: 0,
4705 epoch: 0,
4706 body: br#"{"op":"server.describe"}"#.to_vec(),
4707 priority: Priority::Interactive,
4708 admission_class: AdmissionClass::Normal,
4709 deadline: deadline.min(Instant::now() + CAPABILITY_PROBE_TIMEOUT),
4710 retain_late_route_open: false,
4711 route_open_reverse_requests: None,
4712 })
4713 .await;
4714 let supported = match reply {
4715 Ok(TerminalFrame::Response { body, .. }) => {
4716 matches!(serde_json::from_slice::<ClientControlResponse>(&body),
4717 Ok(ClientControlResponse::ServerDescribe { capabilities, .. })
4718 if capabilities.iter().any(|cap| cap == ROUTE_CLOSE_REASONS_CAPABILITY))
4719 }
4720 _ => false,
4721 };
4722 let mut inner = self.lock_inner();
4723 if inner.generation == generation {
4724 inner.accepts_close_reasons = Some(supported);
4725 return Ok(());
4726 }
4727 }
4728 }
4729
4730 async fn send_request(
4731 self: &Arc<Self>,
4732 request: RequestSend,
4733 ) -> Result<TerminalFrame, CallError> {
4734 self.send_request_cancellable(request, None).await
4735 }
4736
4737 fn allocate_request(
4738 self: &Arc<Self>,
4739 expected_handle: Option<RouteHandle>,
4740 channel: u16,
4741 epoch: u32,
4742 ) -> Result<(PendingKey, mpsc::Sender<WriteCommand>), CallError> {
4743 let mut inner = self.lock_inner();
4744 if inner.closed {
4745 return Err(CallError::not_sent("consumer closed"));
4746 }
4747 let generation = inner.generation;
4748 if let Some(expected) = expected_handle {
4749 let route_pair_matches =
4750 channel == 0 || (expected.channel == channel && expected.epoch == epoch);
4751 if expected.connection_token() != generation
4752 || !route_pair_matches
4753 || inner.route_epochs.get(&expected.channel) != Some(&expected)
4754 || inner.retired_routes.contains(&expected)
4755 {
4756 return Err(CallError::StaleRouteHandle(expected));
4757 }
4758 }
4759 let Some(writer) = inner.writer.clone() else {
4760 return Err(CallError::not_sent("subc connection is down before send"));
4761 };
4762 let Some(corr) = inner.next_corr else {
4763 drop(inner);
4764 self.handle_generation_drop(
4765 generation,
4766 "channel-0 correlation allocator exhausted".to_string(),
4767 );
4768 return Err(CallError::not_sent(
4769 "correlation allocator exhausted; connection closed",
4770 ));
4771 };
4772 inner.next_corr = corr.checked_add(1);
4773 Ok((
4774 PendingKey {
4775 generation,
4776 channel,
4777 epoch,
4778 corr,
4779 },
4780 writer,
4781 ))
4782 }
4783
4784 async fn send_request_cancellable(
4785 self: &Arc<Self>,
4786 request: RequestSend,
4787 cancel: Option<Arc<UnaryCancel>>,
4788 ) -> Result<TerminalFrame, CallError> {
4789 self.send_request_with_slot(request, cancel, None).await
4790 }
4791
4792 async fn send_request_with_slot(
4793 self: &Arc<Self>,
4794 request: RequestSend,
4795 cancel: Option<Arc<UnaryCancel>>,
4796 slot: Option<Arc<RoutePermit>>,
4797 ) -> Result<TerminalFrame, CallError> {
4798 let RequestSend {
4799 expected_handle,
4800 channel,
4801 epoch,
4802 body,
4803 binary,
4804 priority,
4805 admission_class,
4806 deadline,
4807 retain_late_route_open,
4808 route_open_reverse_requests,
4809 } = request;
4810 if Instant::now() >= deadline {
4811 return Err(CallError::not_sent(
4812 "call deadline elapsed before request was sent",
4813 ));
4814 }
4815 let slot = match (slot, expected_handle) {
4816 (Some(slot), _) => Some(slot),
4817 (None, Some(handle)) if channel != 0 => match self.route_state(handle) {
4818 Ok(route) if route.opted_in => {
4819 Some(route.acquire(false, deadline, cancel.as_ref()).await?)
4820 }
4821 _ => None,
4822 },
4823 (None, _) => None,
4824 };
4825 let (key, writer) = self.allocate_request(expected_handle, channel, epoch)?;
4826 let generation = key.generation;
4827
4828 let mut frame = Frame::build(
4829 FrameType::Request,
4830 Flags::new(binary, priority, false).with_admission_class(admission_class),
4831 channel,
4832 epoch,
4833 key.corr,
4834 body,
4835 )
4836 .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
4837 let (tx, rx) = oneshot::channel();
4838 {
4839 let mut inner = self.lock_inner();
4840 if inner.closed || inner.generation != generation || inner.writer.is_none() {
4841 return Err(CallError::not_sent(
4842 "connection changed before request registration",
4843 ));
4844 }
4845 if retain_late_route_open && !daemon_version_at_least(&inner.daemon_ver, (0, 39, 0)) {
4849 return Err(CallError::DaemonTooOld {
4850 daemon_ver: inner.daemon_ver.clone(),
4851 });
4852 }
4853 if retain_late_route_open {
4854 let supported = inner.accepts_close_reasons.ok_or_else(|| {
4855 CallError::not_sent("connection changed before route.open capability discovery")
4856 })?;
4857 let mut body: serde_json::Value = serde_json::from_slice(&frame.body)
4858 .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4859 RouteOpenRequestExt::new()
4860 .with_accepts_close_reasons(supported.then(|| {
4861 ACCEPTED_CLOSE_REASONS
4862 .iter()
4863 .map(|reason| (*reason).to_string())
4864 .collect()
4865 }))
4866 .write_to(&mut body)
4867 .map_err(|err| CallError::not_sent(format!("invalid route.open: {err}")))?;
4868 frame = Frame::build(
4869 FrameType::Request,
4870 frame.header.flags,
4871 channel,
4872 epoch,
4873 key.corr,
4874 serde_json::to_vec(&body)
4875 .map_err(|err| CallError::not_sent(err.to_string()))?,
4876 )
4877 .map_err(|err| CallError::not_sent(err.to_string()))?;
4878 }
4879 if let Some(expected) = expected_handle {
4880 if inner.route_epochs.get(&expected.channel) != Some(&expected)
4881 || inner.retired_routes.contains(&expected)
4882 {
4883 return Err(CallError::StaleRouteHandle(expected));
4884 }
4885 }
4886 let expected_control_handle = (channel == 0 && !retain_late_route_open)
4887 .then_some(expected_handle)
4888 .flatten();
4889 inner.pending.insert(
4890 key,
4891 PendingEntry::unary(
4892 tx,
4893 retain_late_route_open,
4894 expected_control_handle,
4895 route_open_reverse_requests,
4896 ),
4897 );
4898 if let Some(slot) = slot.filter(|slot| slot.opted_in()) {
4899 inner.wire_slots.insert(key, slot);
4900 }
4901 if retain_late_route_open {
4902 inner.pending.get_mut(&key).unwrap().route_open_module =
4903 serde_json::from_slice::<serde_json::Value>(&frame.body)
4904 .ok()
4905 .and_then(|body| {
4906 body.get("target")?
4907 .get("module_id")?
4908 .as_str()
4909 .map(str::to_string)
4910 });
4911 }
4912 }
4913 let mut registration =
4914 PendingRegistration::new(Arc::clone(self), key, retain_late_route_open);
4915 registration.unary_cancel = cancel.clone();
4916
4917 match timeout_at(
4918 deadline,
4919 writer.send(WriteCommand {
4920 frame,
4921 pending: Some(key),
4922 }),
4923 )
4924 .await
4925 {
4926 Ok(Ok(())) => {}
4927 Ok(Err(_)) => {
4928 let accepted = registration.remove_pending().unwrap_or(false);
4929 return Err(classify_failure(
4930 accepted,
4931 "writer task closed before accepting request",
4932 OutcomeUnknownCause::WriterClosed,
4933 ));
4934 }
4935 Err(_) => {
4936 let accepted = registration.remove_pending().unwrap_or(false);
4937 return Err(classify_failure_with_not_sent_cause(
4938 accepted,
4939 "call deadline elapsed waiting for writer capacity",
4940 OutcomeUnknownCause::Deadline,
4941 NotSentCause::WriterCapacity,
4942 ));
4943 }
4944 }
4945
4946 if let Some(cancel) = cancel {
4947 cancel.activate(key, priority, deadline);
4948 if cancel.requested() {
4949 cancel.cancel().await;
4950 }
4951 }
4952
4953 self.wait_for_reply(registration, rx, deadline).await
4954 }
4955
4956 async fn wait_for_reply(
4957 self: &Arc<Self>,
4958 mut registration: PendingRegistration,
4959 rx: oneshot::Receiver<PendingResult>,
4960 deadline: Instant,
4961 ) -> Result<TerminalFrame, CallError> {
4962 let key = registration.key;
4963 let channel = key.channel;
4964 tokio::select! {
4968 result = timeout_at(deadline, rx) => match result {
4969 Ok(Ok(result)) => {
4970 registration.disarm();
4971 result.into_call_result()
4972 }
4973 Ok(Err(_)) => {
4974 registration.disarm();
4977 Err(CallError::outcome_unknown(
4978 "pending response channel closed",
4979 OutcomeUnknownCause::CompletionFailed,
4980 ))
4981 }
4982 Err(_) => {
4983 let accepted = if registration.retain_on_drop {
4984 registration.disarm();
4985 self.pending_accepted(key).unwrap_or(true)
4986 } else {
4987 registration.remove_pending().unwrap_or(true)
4988 };
4989 if accepted {
4990 let cancel_sent = registration.unary_cancel.as_ref().is_some_and(|cancel| cancel.sent());
4994 if !cancel_sent && self.lock_inner().wire_slots.contains_key(&key) {
4995 self.send_cancel(RouteHandle::new(key.channel, key.epoch, key.generation), key.corr, Priority::Interactive);
4996 }
4997 self.spawn_liveness_probe();
4998 }
4999 Err(classify_failure(
5000 accepted,
5001 format!("request on channel {channel} timed out at its deadline"),
5002 OutcomeUnknownCause::Deadline,
5003 ))
5004 }
5005 },
5006 () = self.close_token.cancelled() => {
5007 let accepted = registration.remove_pending().unwrap_or(true);
5008 Err(classify_failure(accepted, "consumer closed while request was pending", OutcomeUnknownCause::ConsumerClosed))
5009 }
5010 }
5011 }
5012
5013 fn spawn_liveness_probe(self: &Arc<Self>) {
5019 if self.liveness_probe_running.swap(true, Ordering::AcqRel) {
5020 return;
5021 }
5022
5023 let allocation = {
5024 let mut inner = self.lock_inner();
5025 let control_pending = inner
5035 .pending
5036 .keys()
5037 .any(|key| key.generation == inner.generation && key.channel == 0);
5038 if inner.closed || control_pending || !matches!(&inner.reconnect, ReconnectState::Idle)
5039 {
5040 None
5041 } else {
5042 match (inner.next_corr, inner.writer.clone()) {
5043 (Some(corr), Some(writer)) => {
5044 inner.next_corr = corr.checked_add(1);
5045 Some((inner.generation, corr, writer))
5046 }
5047 (None, _) | (_, None) => None,
5048 }
5049 }
5050 };
5051 let Some((generation, corr, writer)) = allocation else {
5052 self.liveness_probe_running.store(false, Ordering::Release);
5053 return;
5054 };
5055
5056 let t0 = epoch_millis();
5057 let ping = match Frame::build(
5058 FrameType::Ping,
5059 Flags::new(false, Priority::Interactive, false),
5060 0,
5061 0,
5062 corr,
5063 Vec::new(),
5064 ) {
5065 Ok(ping) => ping,
5066 Err(_) => {
5067 self.liveness_probe_running.store(false, Ordering::Release);
5068 return;
5069 }
5070 };
5071 let window = self.opts.liveness_probe_window;
5072 let shared = Arc::clone(self);
5073 tokio::spawn(async move {
5074 let window_end = Instant::now() + window;
5075 let _ = timeout_at(
5078 window_end,
5079 writer.send(WriteCommand {
5080 frame: ping,
5081 pending: None,
5082 }),
5083 )
5084 .await;
5085 sleep_until(window_end).await;
5086
5087 let control_pending_now = {
5088 let inner = shared.lock_inner();
5089 inner
5090 .pending
5091 .keys()
5092 .any(|key| key.generation == generation && key.channel == 0)
5093 };
5094 if !shared.close_token.is_cancelled()
5095 && !control_pending_now && shared.generation_is_current(generation)
5097 && shared.last_inbound_ms.load(Ordering::Acquire) < t0
5098 {
5099 shared.handle_generation_drop(
5100 generation,
5101 format!(
5102 "liveness probe convicted a half-open socket: no inbound frame for {}ms after a channel-0 Ping",
5103 window.as_millis()
5104 ),
5105 );
5106 }
5107 shared
5108 .liveness_probe_running
5109 .store(false, Ordering::Release);
5110 });
5111 }
5112
5113 async fn send_subscription(
5114 self: &Arc<Self>,
5115 subscription: SubscriptionSend,
5116 ) -> Result<Subscription, CallError> {
5117 let SubscriptionSend {
5118 expected_handle,
5119 channel,
5120 epoch,
5121 body,
5122 priority,
5123 admission_class,
5124 event_buffer,
5125 deadline,
5126 permit,
5127 } = subscription;
5128 if Instant::now() >= deadline {
5129 return Err(CallError::not_sent(
5130 "subscription deadline elapsed before request was sent",
5131 ));
5132 }
5133 let (generation, corr, writer) = {
5134 let mut inner = self.lock_inner();
5135 if inner.closed {
5136 return Err(CallError::not_sent("consumer closed"));
5137 }
5138 let generation = inner.generation;
5139 if let Some(expected) = expected_handle {
5140 if expected.connection_token() != generation
5141 || expected.channel != channel
5142 || expected.epoch != epoch
5143 || inner.route_epochs.get(&channel) != Some(&expected)
5144 || inner.retired_routes.contains(&expected)
5145 {
5146 return Err(CallError::StaleRouteHandle(expected));
5147 }
5148 }
5149 let Some(writer) = inner.writer.clone() else {
5150 return Err(CallError::not_sent("subc connection is down before send"));
5151 };
5152 let Some(corr) = inner.next_corr else {
5153 drop(inner);
5154 self.handle_generation_drop(
5155 generation,
5156 "correlation allocator exhausted".to_string(),
5157 );
5158 return Err(CallError::not_sent(
5159 "correlation allocator exhausted; connection closed",
5160 ));
5161 };
5162 inner.next_corr = corr.checked_add(1);
5163 (generation, corr, writer)
5164 };
5165
5166 let frame = Frame::build(
5168 FrameType::Request,
5169 Flags(
5170 Flags::new(false, priority, false)
5171 .with_admission_class(admission_class)
5172 .0
5173 | FLAG_SUBSCRIPTION,
5174 ),
5175 channel,
5176 epoch,
5177 corr,
5178 body,
5179 )
5180 .map_err(|err| CallError::not_sent(format!("failed to build request frame: {err}")))?;
5181 let key = PendingKey {
5182 generation,
5183 channel,
5184 epoch,
5185 corr,
5186 };
5187 let position = Arc::new(SubscriptionPosition {
5188 key: Mutex::new(key),
5189 stop: CancellationToken::new(),
5190 });
5191 let retry = permit.opted_in().then(|| SubscriptionRetry {
5192 frame: frame.clone(),
5193 deadline,
5194 delay: Duration::from_millis(25),
5195 position: Arc::clone(&position),
5196 });
5197 let (events_tx, events_rx) = mpsc::channel(event_buffer.max(1));
5198 let (closed_tx, closed_rx) = oneshot::channel();
5199 let (ended_tx, ended_rx) = watch::channel(None);
5200 {
5201 let mut inner = self.lock_inner();
5202 if inner.closed || inner.generation != generation || inner.writer.is_none() {
5203 return Err(CallError::not_sent(
5204 "connection changed before subscription registration",
5205 ));
5206 }
5207 if let Some(expected) = expected_handle {
5208 if inner.route_epochs.get(&expected.channel) != Some(&expected)
5209 || inner.retired_routes.contains(&expected)
5210 {
5211 return Err(CallError::StaleRouteHandle(expected));
5212 }
5213 }
5214 if permit.opted_in() {
5215 inner.wire_slots.insert(key, Arc::clone(&permit));
5216 }
5217 let mut entry =
5218 PendingEntry::subscription(events_tx, closed_tx, ended_tx, permit, priority);
5219 entry.retry = retry;
5220 inner.pending.insert(key, entry);
5221 }
5222 let mut registration = PendingRegistration::new(Arc::clone(self), key, false);
5223
5224 match timeout_at(
5225 deadline,
5226 writer.send(WriteCommand {
5227 frame,
5228 pending: Some(key),
5229 }),
5230 )
5231 .await
5232 {
5233 Ok(Ok(())) => {}
5234 Ok(Err(_)) => {
5235 let accepted = registration.remove_pending().unwrap_or(false);
5236 return Err(classify_failure(
5237 accepted,
5238 "writer task closed before accepting subscription request",
5239 OutcomeUnknownCause::WriterClosed,
5240 ));
5241 }
5242 Err(_) => {
5243 let accepted = registration.remove_pending().unwrap_or(false);
5244 return Err(classify_failure_with_not_sent_cause(
5245 accepted,
5246 "subscription deadline elapsed waiting for writer capacity",
5247 OutcomeUnknownCause::Deadline,
5248 NotSentCause::WriterCapacity,
5249 ));
5250 }
5251 }
5252
5253 registration.disarm();
5254 Ok(Subscription {
5255 events: events_rx,
5256 closed: SubscriptionClosed { rx: closed_rx },
5257 ended: ended_rx,
5258 cancel: SubscriptionCancel::new(Arc::clone(self), position, priority),
5259 })
5260 }
5261
5262 fn unsubscribe_subscription(
5263 &self,
5264 position: &SubscriptionPosition,
5265 priority: Priority,
5266 ) -> Result<(), CallError> {
5267 let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5268 let handle = RouteHandle::new(key.channel, key.epoch, key.generation);
5269 self.validate_current_handle(handle)?;
5270 let (key, entry) = {
5271 let mut inner = self.lock_inner();
5272 let key = *position.key.lock().unwrap_or_else(|err| err.into_inner());
5273 position.stop.cancel();
5274 let entry = inner.pending.remove(&key);
5275 if entry.as_ref().is_some_and(|entry| !entry.accepted) {
5276 if let Some(slot) = inner.wire_slots.remove(&key) {
5277 slot.release();
5278 }
5279 }
5280 (key, entry)
5282 };
5283 if let Some(entry) = entry {
5284 let should_cancel = entry.accepted || entry.retry.is_none();
5285 entry.settle_subscription_result(Ok(()));
5286 if should_cancel {
5287 self.send_cancel(handle, key.corr, priority);
5288 }
5289 self.lock_inner().reap_retired_route(handle);
5290 }
5291 Ok(())
5292 }
5293
5294 fn route_stream_data(&self, key: PendingKey, body: Vec<u8>) {
5295 let overflow = {
5296 let mut inner = self.lock_inner();
5297 let Some(entry) = inner.pending.get(&key) else {
5298 return;
5299 };
5300 match entry.try_send_stream_data(body) {
5301 Ok(()) | Err(StreamDataDelivery::NotSubscription) => return,
5302 Err(StreamDataDelivery::Full) => {
5303 let priority = entry
5304 .subscription_priority()
5305 .unwrap_or(Priority::Interactive);
5306 let entry = inner.pending.remove(&key);
5307 entry.map(|entry| {
5308 (
5309 entry,
5310 priority,
5311 "subscription event channel filled; reader dropped the stream instead of blocking",
5312 )
5313 })
5314 }
5315 Err(StreamDataDelivery::Closed) => {
5316 let priority = entry
5317 .subscription_priority()
5318 .unwrap_or(Priority::Interactive);
5319 let entry = inner.pending.remove(&key);
5320 entry.map(|entry| {
5321 (
5322 entry,
5323 priority,
5324 "subscription event receiver closed before the stream ended",
5325 )
5326 })
5327 }
5328 }
5329 };
5330
5331 if let Some((entry, priority, reason)) = overflow {
5332 entry.settle_call_error(CallError::subscription_backpressure(reason));
5333 self.send_cancel(
5334 RouteHandle::new(key.channel, key.epoch, key.generation),
5335 key.corr,
5336 priority,
5337 );
5338 self.lock_inner().reap_retired_route(RouteHandle::new(
5339 key.channel,
5340 key.epoch,
5341 key.generation,
5342 ));
5343 }
5344 }
5345
5346 fn register_push_events(
5347 &self,
5348 handle: RouteHandle,
5349 ) -> Result<mpsc::Receiver<PushEvent>, CallError> {
5350 let (events_tx, events_rx) = mpsc::channel(DEFAULT_PUSH_EVENT_BUFFER);
5351 let mut inner = self.lock_inner();
5352 if inner.closed
5353 || inner.generation != handle.connection_token()
5354 || inner.writer.is_none()
5355 || inner.route_epochs.get(&handle.channel) != Some(&handle)
5356 {
5357 return Err(CallError::StaleRouteHandle(handle));
5358 }
5359 inner.push_event_receivers.insert(handle, events_tx);
5360 Ok(events_rx)
5361 }
5362
5363 fn route_push(&self, handle: RouteHandle, body: Vec<u8>) {
5364 let should_count_drop = {
5365 let mut inner = self.lock_inner();
5366 if inner.closed
5367 || inner.generation != handle.connection_token()
5368 || inner.route_epochs.get(&handle.channel) != Some(&handle)
5369 {
5370 return;
5374 }
5375 match inner.push_event_receivers.get(&handle) {
5376 None => DroppedPush::NoReceiver,
5377 Some(events) => match events.try_send(PushEvent { handle, body }) {
5378 Ok(()) => DroppedPush::Delivered,
5379 Err(mpsc::error::TrySendError::Closed(_)) => {
5380 inner.push_event_receivers.remove(&handle);
5381 DroppedPush::NoReceiver
5382 }
5383 Err(mpsc::error::TrySendError::Full(_)) => DroppedPush::ReceiverFull,
5393 },
5394 }
5395 };
5396 match should_count_drop {
5397 DroppedPush::Delivered => {}
5398 DroppedPush::NoReceiver => {
5399 self.pushes_dropped_no_receiver
5400 .fetch_add(1, Ordering::Relaxed);
5401 }
5402 DroppedPush::ReceiverFull => {
5403 self.pushes_dropped_receiver_full
5404 .fetch_add(1, Ordering::Relaxed);
5405 }
5406 }
5407 }
5408
5409 fn control_push(&self, body: &[u8]) {
5412 let parsed = serde_json::from_slice::<serde_json::Value>(body)
5413 .ok()
5414 .and_then(|value| {
5415 let op = value.get("op")?.as_str()?.to_string();
5416 Some(ControlPush { op, body: value })
5417 });
5418 let delivered = match parsed {
5419 None => false,
5420 Some(push) => {
5421 let mut inner = self.lock_inner();
5422 inner.record_route_end(&push);
5423 match inner.control_push_receiver.as_ref() {
5424 None => false,
5425 Some(sender) => match sender.try_send(push) {
5426 Ok(()) => true,
5427 Err(mpsc::error::TrySendError::Closed(_)) => {
5428 inner.control_push_receiver = None;
5429 false
5430 }
5431 Err(mpsc::error::TrySendError::Full(_)) => false,
5432 },
5433 }
5434 }
5435 };
5436 if !delivered {
5437 self.control_pushes_dropped.fetch_add(1, Ordering::Relaxed);
5438 }
5439 }
5440
5441 fn send_cancel(&self, handle: RouteHandle, corr: u64, priority: Priority) {
5442 let writer = {
5443 let inner = self.lock_inner();
5444 if inner.closed
5445 || inner.generation != handle.connection_token()
5446 || !route_is_installed(&inner, handle)
5447 {
5448 return;
5449 }
5450 inner.writer.clone()
5451 };
5452 let Some(writer) = writer else {
5453 return;
5454 };
5455 let Ok(frame) = Frame::build(
5456 FrameType::Cancel,
5457 Flags::new(false, priority, false),
5458 handle.channel,
5459 handle.epoch,
5460 corr,
5461 Vec::new(),
5462 ) else {
5463 return;
5464 };
5465 let _ = writer.try_send(WriteCommand {
5466 frame,
5467 pending: None,
5468 });
5469 }
5470
5471 fn mark_pending_accepted(&self, key: PendingKey) -> bool {
5472 let mut inner = self.lock_inner();
5473 if inner.closed || inner.generation != key.generation {
5474 return false;
5475 }
5476 let Some(entry) = inner.pending.get_mut(&key) else {
5477 return false;
5478 };
5479 if entry
5480 .send_deadline
5481 .is_some_and(|deadline| Instant::now() >= deadline)
5482 {
5483 let entry = inner.remove_pending(&key).unwrap();
5484 drop(inner);
5485 entry.settle_call_error(CallError::not_sent_with_cause(
5486 "call deadline elapsed before request was sent",
5487 NotSentCause::WriterRejected,
5488 ));
5489 return false;
5490 }
5491 entry.accepted = true;
5492 true
5493 }
5494
5495 fn settle_pending(self: &Arc<Self>, key: PendingKey, terminal: PendingTerminal) {
5496 let (entry, retry) = {
5497 let mut inner = self.lock_inner();
5498 let entry = inner.remove_pending(&key);
5499 let slot = inner.wire_slots.remove(&key);
5500 let busy = matches!(&terminal, PendingTerminal::Error { body, flags }
5501 if error_codes::is_route_busy_retryable(*flags, &body.code, slot.as_ref().is_some_and(|slot| slot.opted_in())))
5502 && entry
5503 .as_ref()
5504 .is_some_and(|entry| !entry.completion_is_closed());
5505 if let Some(slot) = slot {
5506 if !busy {
5507 slot.release();
5508 }
5509 }
5510 if busy && entry.as_ref().is_some_and(|entry| entry.retry.is_some()) {
5511 let mut entry = entry.unwrap();
5512 entry.accepted = false;
5513 let retry = entry.retry.clone();
5514 inner.pending.insert(key, entry);
5515 (None, retry)
5516 } else {
5517 inner.reap_retired_route(RouteHandle::new(key.channel, key.epoch, key.generation));
5518 (entry, None)
5519 }
5520 };
5521 if let Some(retry) = retry {
5522 let shared = Arc::clone(self);
5523 tokio::spawn(async move {
5524 shared.retry_subscription(key, retry, terminal).await;
5525 });
5526 return;
5527 }
5528 let Some(entry) = entry else {
5529 return;
5530 };
5531 if entry.retain_late_route_open && entry.completion_is_closed() {
5532 if let PendingTerminal::Response {
5533 generation, body, ..
5534 } = &terminal
5535 {
5536 if let Ok(ClientControlResponse::RouteOpen {
5537 route_channel,
5538 route_epoch,
5539 ..
5540 }) = serde_json::from_slice::<ClientControlResponse>(body)
5541 {
5542 let handle = RouteHandle::new(route_channel, route_epoch, *generation);
5543 self.send_route_goodbye(handle, true);
5544 self.uninstall_route_handle(handle);
5545 }
5546 }
5547 return;
5548 }
5549 entry.settle_terminal(terminal);
5550 }
5551
5552 fn pending_accepted(&self, key: PendingKey) -> Option<bool> {
5553 self.lock_inner()
5554 .pending
5555 .get(&key)
5556 .map(|entry| entry.accepted)
5557 }
5558
5559 fn handle_generation_drop(self: &Arc<Self>, generation: u64, reason: String) {
5560 self.handle_generation_drop_with_cause(
5561 generation,
5562 reason,
5563 OutcomeUnknownCause::ConnectionFailed,
5564 );
5565 }
5566
5567 fn handle_generation_drop_with_cause(
5568 self: &Arc<Self>,
5569 generation: u64,
5570 reason: String,
5571 cause: OutcomeUnknownCause,
5572 ) {
5573 let (should_emit, pending, callbacks) = {
5574 let mut inner = self.lock_inner();
5575 if inner.closed || inner.generation != generation || inner.writer.is_none() {
5576 return;
5577 }
5578 inner.writer = None;
5579 inner.restored_token = inner.restored_token.saturating_add(1);
5580 inner.close_routes();
5581 inner.route_epochs.clear();
5582 inner.route_modules.clear();
5583 inner.route_end_reasons.clear();
5584 inner.legacy_channel_reasons.clear();
5585 let pending = drain_pending_generation(&mut inner.pending, generation);
5586 let callbacks = inner.callbacks.clone();
5591 (true, pending, callbacks)
5592 };
5593
5594 if should_emit {
5595 settle_route_pending_entries_with_cause(
5596 pending,
5597 reason.clone(),
5598 RouteEndReason::ConnectionLost,
5599 cause,
5600 );
5601 emit_callbacks(callbacks, ConnectionState::Dropped);
5602 self.notify.notify_waiters();
5603 let _ = self.spawn_reconnect(generation);
5604 }
5605 }
5606
5607 fn close_sync(&self, reason: &str) {
5608 let (pending, openings, routes, reader, writer, reconnect) = {
5609 let mut inner = self.lock_inner();
5610 if inner.closed {
5611 return;
5612 }
5613 inner.closed = true;
5614 let retirements = inner
5618 .retirement_goodbyes
5619 .iter()
5620 .copied()
5621 .collect::<Vec<_>>();
5622 for handle in retirements {
5623 inner.queue_retirement_goodbye(handle);
5624 }
5625 inner.writer = None;
5626 inner.route_epochs.clear();
5627 inner.route_modules.clear();
5628 inner.route_end_reasons.clear();
5629 inner.legacy_channel_reasons.clear();
5630 inner.push_event_receivers.clear();
5631 self.close_token.cancel();
5632 let reconnect = match std::mem::replace(&mut inner.reconnect, ReconnectState::Idle) {
5633 ReconnectState::Background { task, .. } => Some(task),
5634 ReconnectState::Idle | ReconnectState::Inline { .. } => None,
5635 };
5636 (
5637 inner
5638 .pending
5639 .drain()
5640 .map(|(_, entry)| entry)
5641 .collect::<Vec<_>>(),
5642 inner
5643 .openings
5644 .drain()
5645 .map(|(_, opening)| opening.waiters)
5646 .collect::<Vec<_>>(),
5647 inner.drain_routes(),
5648 inner.reader_task.take(),
5649 inner.writer_task.take(),
5650 reconnect,
5651 )
5652 };
5653 for route in routes {
5654 route.close();
5655 }
5656 if let Some(handle) = reader {
5657 handle.abort();
5658 }
5659 if let Some(mut handle) = writer {
5660 if let Ok(runtime) = tokio::runtime::Handle::try_current() {
5663 runtime.spawn(async move {
5664 if tokio::time::timeout(Duration::from_millis(250), &mut handle)
5665 .await
5666 .is_err()
5667 {
5668 handle.abort();
5669 }
5670 });
5671 } else {
5672 handle.abort();
5673 }
5674 }
5675 if let Some(handle) = reconnect {
5676 handle.abort();
5677 }
5678 settle_pending_entries(pending, reason.to_string());
5679 fail_openings(openings, SharedCallFailure::not_sent(reason.to_string()));
5680 self.notify.notify_waiters();
5681 }
5682
5683 fn validate_current_handle(&self, handle: RouteHandle) -> Result<(), CallError> {
5684 let inner = self.lock_inner();
5685 if inner.closed
5686 || inner.generation != handle.connection_token()
5687 || inner.writer.is_none()
5688 || !route_is_installed(&inner, handle)
5689 {
5690 Err(CallError::StaleRouteHandle(handle))
5691 } else {
5692 Ok(())
5693 }
5694 }
5695
5696 fn route_state(&self, handle: RouteHandle) -> Result<RouteState, CallError> {
5697 let inner = self.lock_inner();
5698 if inner.closed
5699 || inner.generation != handle.connection_token()
5700 || inner.writer.is_none()
5701 || inner.route_epochs.get(&handle.channel) != Some(&handle)
5702 {
5703 return Err(CallError::StaleRouteHandle(handle));
5704 }
5705
5706 let route = inner
5707 .route_by_channel
5708 .get(&handle.channel)
5709 .and_then(|key| inner.routes.get(key))
5710 .or_else(|| inner.one_shot_routes.get(&handle.channel));
5711 debug_assert!(route.is_none_or(|route| route.handle == handle));
5712 route
5713 .filter(|route| route.handle == handle)
5714 .cloned()
5715 .ok_or(CallError::StaleRouteHandle(handle))
5716 }
5717
5718 fn route_is_current(&self, key: &RouteKey, route: &RouteState) -> bool {
5719 let inner = self.lock_inner();
5720 if inner.closed
5721 || inner.generation != route.handle.connection_token()
5722 || inner.writer.is_none()
5723 {
5724 return false;
5725 }
5726 inner.routes.get(key).is_some_and(|cached| {
5727 cached.handle == route.handle && Arc::ptr_eq(&cached.sem, &route.sem)
5728 })
5729 }
5730
5731 fn invalidate_route(&self, key: &RouteKey, expected_handle: Option<RouteHandle>) {
5732 self.invalidate_route_with_deadline(key, expected_handle, false);
5733 }
5734
5735 fn invalidate_route_with_deadline(
5742 &self,
5743 key: &RouteKey,
5744 expected_handle: Option<RouteHandle>,
5745 response_deadline_expired: bool,
5746 ) {
5747 let removed = {
5748 let mut inner = self.lock_inner();
5749 match inner.routes.get(key) {
5750 Some(route) if expected_handle.is_none_or(|expected| expected == route.handle) => {
5751 let removed = inner.evict_route(key);
5752 if let Some(route) = &removed {
5753 inner.retired_routes.insert(route.handle);
5758 if response_deadline_expired {
5759 inner.retirement_goodbyes.insert(route.handle);
5760 inner.release_wire_slots(route.handle);
5763 let pending_calls = inner
5764 .pending
5765 .keys()
5766 .filter(|pending| {
5767 pending.generation == route.handle.connection_token()
5768 && pending.channel == route.handle.channel
5769 && pending.epoch == route.handle.epoch
5770 })
5771 .count();
5772 tracing::warn!(
5773 target_module = %key.target_label(),
5774 channel = route.handle.channel,
5775 epoch = route.handle.epoch,
5776 pending_calls,
5777 "retiring route after call response deadline"
5778 );
5779 }
5780 inner.reap_retired_route(route.handle);
5781 }
5782 removed
5783 }
5784 _ => None,
5785 }
5786 };
5787 if let Some(route) = removed {
5788 route.close();
5789 }
5790 }
5791
5792 fn finish_opening(&self, key: &RouteKey, result: Result<RouteState, SharedCallFailure>) {
5793 let opening = self.lock_inner().openings.remove(key);
5794 for waiter in opening.map(|o| o.waiters).unwrap_or_default() {
5795 let _ = waiter.send(result.clone());
5796 }
5797 }
5798
5799 async fn close_handle(
5800 self: &Arc<Self>,
5801 handle: RouteHandle,
5802 opts: &CloseRouteOptions,
5803 ) -> Result<(), CallError> {
5804 self.validate_current_handle(handle)?;
5805 let route = {
5806 let mut inner = self.lock_inner();
5807 inner.route_end_reasons.insert(
5808 handle.channel,
5809 (RouteEndReason::ClosedByCaller.into(), true),
5810 );
5811 inner.remove_route_by_handle(handle)
5812 };
5813 let mut closing = RouteCloseGuard::new(
5814 Arc::clone(self),
5815 handle,
5816 route,
5817 "route closed by close_handle",
5818 );
5819 if opts.drain {
5820 self.drain_channel(handle, opts.drain_timeout).await;
5821 }
5822 closing.close_pending();
5823 self.queue_route_goodbye(handle).await;
5824 closing.finish();
5825 Ok(())
5826 }
5827
5828 async fn close_route(self: &Arc<Self>, key: &RouteKey, opts: &CloseRouteOptions) {
5830 let route = {
5834 let mut inner = self.lock_inner();
5835 if let Some(opening) = inner.openings.get_mut(key) {
5836 opening.closed = true;
5837 }
5838 let route = inner.remove_route(key);
5839 if let Some(route) = &route {
5840 inner.route_end_reasons.insert(
5841 route.handle.channel,
5842 (RouteEndReason::ClosedByCaller.into(), true),
5843 );
5844 }
5845 route
5846 };
5847
5848 let Some(route) = route else {
5851 return;
5852 };
5853 let handle = route.handle;
5854 let mut closing = RouteCloseGuard::new(
5855 Arc::clone(self),
5856 handle,
5857 Some(route),
5858 "route closed by close_route",
5859 );
5860
5861 if opts.drain {
5862 self.drain_channel(handle, opts.drain_timeout).await;
5865 }
5866
5867 closing.close_pending();
5871
5872 self.queue_route_goodbye(handle).await;
5876 closing.finish();
5877 }
5878
5879 fn uninstall_route_handle(&self, handle: RouteHandle) {
5880 let mut inner = self.lock_inner();
5881 inner.release_wire_slots(handle);
5882 inner.retired_routes.remove(&handle);
5883 inner.retirement_goodbyes.remove(&handle);
5884 if inner.route_epochs.get(&handle.channel) == Some(&handle) {
5885 let installed = inner.route_epochs.remove(&handle.channel).unwrap();
5886 inner.route_targets.remove(&handle);
5887 inner.push_event_receivers.remove(&handle);
5888 release_reverse_request_registry(installed);
5889 }
5890 }
5891
5892 fn route_not_sent_error(&self, handle: RouteHandle) -> CallError {
5893 let inner = self.lock_inner();
5894 let reason = if inner.generation != handle.connection_token() || inner.writer.is_none() {
5895 RouteEndReason::ConnectionLost.into()
5896 } else {
5897 inner.route_end(handle.channel)
5898 };
5899 CallError::NotSent(Box::new(NotSentSource {
5900 message: "route flow-control semaphore closed".into(),
5901 cause: NotSentCause::BeforeQueue,
5902 never_forwarded: true,
5903 route_reason: Some(reason),
5904 refusal: None,
5905 }))
5906 }
5907
5908 fn fail_channel_pending(
5911 &self,
5912 handle: RouteHandle,
5913 reason: &str,
5914 close_reason: RouteEndReason,
5915 ) {
5916 let entries = {
5917 let mut inner = self.lock_inner();
5918 inner.release_wire_slots(handle);
5919 inner
5920 .route_end_reasons
5921 .insert(handle.channel, (close_reason.clone().into(), true));
5922 drain_pending_handle(&mut inner.pending, handle, true)
5923 };
5924 settle_route_pending_entries(entries, reason.to_string(), close_reason);
5925 }
5926
5927 async fn drain_channel(&self, handle: RouteHandle, timeout: Duration) {
5931 let deadline = Instant::now() + timeout;
5932 loop {
5933 let has_inflight = {
5934 let inner = self.lock_inner();
5935 inner.pending.iter().any(|(key, entry)| {
5936 key.generation == handle.connection_token()
5937 && key.channel == handle.channel
5938 && key.epoch == handle.epoch
5939 && !entry.is_subscription()
5940 })
5941 };
5942 if !has_inflight || Instant::now() >= deadline {
5943 return;
5944 }
5945 sleep(Duration::from_millis(5)).await;
5946 }
5947 }
5948
5949 async fn queue_route_goodbye(self: &Arc<Self>, handle: RouteHandle) {
5950 let frame = Frame::build(
5951 FrameType::Goodbye,
5952 Flags::new(false, Priority::Interactive, false),
5953 handle.channel,
5954 handle.epoch,
5955 0,
5956 Vec::new(),
5957 )
5958 .expect("header-only route GOODBYE is valid");
5959 loop {
5960 let changed = self.notify.notified();
5961 tokio::pin!(changed);
5962 changed.as_mut().enable();
5963 let writer = {
5964 let inner = self.lock_inner();
5965 if inner.closed
5969 || inner.generation != handle.connection_token()
5970 || inner.route_epochs.get(&handle.channel) != Some(&handle)
5971 {
5972 return;
5973 }
5974 let Some(writer) = inner.writer.clone() else {
5975 return;
5976 };
5977 writer
5978 };
5979 tokio::select! {
5983 result = writer.reserve() => {
5984 let Ok(permit) = result else {
5985 self.handle_generation_drop(
5986 handle.connection_token(),
5987 "writer closed before route GOODBYE".into(),
5988 );
5989 return;
5990 };
5991 let inner = self.lock_inner();
5992 if !inner.closed
5993 && inner.generation == handle.connection_token()
5994 && inner.writer.as_ref().is_some_and(|current| current.same_channel(&writer))
5995 && inner.route_epochs.get(&handle.channel) == Some(&handle)
5996 {
5997 permit.send(WriteCommand { frame, pending: None });
5998 }
5999 return;
6000 }
6001 _ = &mut changed => {}
6002 _ = self.close_token.cancelled() => return,
6003 }
6004 }
6005 }
6006
6007 fn send_route_goodbye(self: &Arc<Self>, handle: RouteHandle, close_on_failure: bool) -> bool {
6011 let writer = {
6012 let inner = self.lock_inner();
6013 if inner.closed
6014 || inner.generation != handle.connection_token()
6015 || inner.route_epochs.get(&handle.channel) != Some(&handle)
6016 {
6017 return false;
6018 }
6019 inner.writer.clone()
6020 };
6021 let Some(writer) = writer else {
6022 return false;
6023 };
6024 let Ok(frame) = Frame::build(
6025 FrameType::Goodbye,
6026 Flags::new(false, Priority::Interactive, false),
6027 handle.channel,
6028 handle.epoch,
6029 0,
6030 Vec::new(),
6031 ) else {
6032 return false;
6033 };
6034 if writer
6035 .try_send(WriteCommand {
6036 frame,
6037 pending: None,
6038 })
6039 .is_ok()
6040 {
6041 return true;
6042 }
6043 if close_on_failure {
6044 self.handle_generation_drop(
6045 handle.connection_token(),
6046 "failed to queue late route.open cleanup GOODBYE".to_string(),
6047 );
6048 }
6049 false
6050 }
6051
6052 fn emit_connection_state(&self, state: ConnectionState) {
6053 let callbacks = self.lock_inner().callbacks.clone();
6054 emit_callbacks(callbacks, state);
6055 }
6056}
6057
6058#[derive(Clone, Copy)]
6059enum InstallKind {
6060 Initial,
6061 Reconnect,
6062}
6063
6064enum EnsureAction {
6065 Wait,
6066 Lead {
6067 generation: u64,
6068 stale_task: Option<JoinHandle<()>>,
6069 },
6070}
6071
6072enum ReconnectState {
6076 Idle,
6077 Inline {
6078 generation: u64,
6079 },
6080 Background {
6081 generation: u64,
6082 task: JoinHandle<()>,
6083 },
6084}
6085
6086enum RouteInstall {
6089 Cached(RouteState),
6091 Discard { closed: bool },
6094}
6095
6096enum RouteOpenAction {
6097 Wait(oneshot::Receiver<Result<RouteState, SharedCallFailure>>),
6098 Lead,
6099}
6100
6101struct RouteOpenParams<'a> {
6102 target: &'a RouteTarget,
6103 identity: &'a BindIdentity,
6104 consumer_identity: &'a Option<ConsumerIdentity>,
6105 consumer_capabilities: &'a Option<Vec<String>>,
6106 role_versions: &'a Option<BTreeMap<String, String>>,
6108 reverse_requests: &'a ReverseRequestRegistry,
6109 scope: Option<&'a ScopeSelector>,
6112}
6113
6114struct CallAttemptHistory {
6115 never_forwarded: bool,
6116 sent: bool,
6117}
6118
6119struct RequestSend {
6120 expected_handle: Option<RouteHandle>,
6121 channel: u16,
6122 epoch: u32,
6123 body: Vec<u8>,
6124 binary: bool,
6125 priority: Priority,
6126 admission_class: AdmissionClass,
6127 deadline: Instant,
6128 retain_late_route_open: bool,
6129 route_open_reverse_requests: Option<ReverseRequestRegistry>,
6130}
6131
6132struct SubscriptionSend {
6133 expected_handle: Option<RouteHandle>,
6134 channel: u16,
6135 epoch: u32,
6136 body: Vec<u8>,
6137 priority: Priority,
6138 admission_class: AdmissionClass,
6139 event_buffer: usize,
6140 deadline: Instant,
6141 permit: Arc<RoutePermit>,
6142}
6143
6144struct SubscriptionPosition {
6145 key: Mutex<PendingKey>,
6146 stop: CancellationToken,
6147}
6148
6149#[derive(Clone)]
6150struct SubscriptionRetry {
6151 frame: Frame,
6152 deadline: Instant,
6153 delay: Duration,
6154 position: Arc<SubscriptionPosition>,
6155}
6156
6157struct RouteCloseGuard {
6158 shared: Arc<Shared>,
6159 handle: RouteHandle,
6160 route: Option<RouteState>,
6161 reason: &'static str,
6162 finished: bool,
6163}
6164
6165impl RouteCloseGuard {
6166 fn new(
6167 shared: Arc<Shared>,
6168 handle: RouteHandle,
6169 route: Option<RouteState>,
6170 reason: &'static str,
6171 ) -> Self {
6172 Self {
6173 shared,
6174 handle,
6175 route,
6176 reason,
6177 finished: false,
6178 }
6179 }
6180
6181 fn close_pending(&self) {
6182 if let Some(route) = &self.route {
6183 route.close();
6184 }
6185 self.shared
6186 .fail_channel_pending(self.handle, self.reason, RouteEndReason::ClosedByCaller);
6187 }
6188
6189 fn finish(&mut self) {
6190 self.shared.uninstall_route_handle(self.handle);
6191 self.finished = true;
6192 }
6193}
6194
6195impl Drop for RouteCloseGuard {
6196 fn drop(&mut self) {
6197 if self.finished {
6198 return;
6199 }
6200 self.close_pending();
6203 let mut inner = self.shared.lock_inner();
6204 if inner.closed
6205 || inner.generation != self.handle.connection_token()
6206 || inner.writer.is_none()
6207 || inner.route_epochs.get(&self.handle.channel) != Some(&self.handle)
6208 {
6209 return;
6210 }
6211 inner.retired_routes.insert(self.handle);
6212 inner.retirement_goodbyes.insert(self.handle);
6213 inner.reap_retired_route(self.handle);
6216 }
6217}
6218
6219struct OpeningGuard {
6220 shared: Arc<Shared>,
6221 key: RouteKey,
6222 finished: bool,
6223}
6224
6225impl OpeningGuard {
6226 fn new(shared: Arc<Shared>, key: RouteKey) -> Self {
6227 Self {
6228 shared,
6229 key,
6230 finished: false,
6231 }
6232 }
6233
6234 fn finish(&mut self, result: Result<RouteState, SharedCallFailure>) {
6235 self.shared.finish_opening(&self.key, result);
6236 self.finished = true;
6237 }
6238}
6239
6240impl Drop for OpeningGuard {
6241 fn drop(&mut self) {
6242 if !self.finished {
6243 self.shared.finish_opening(
6244 &self.key,
6245 Err(SharedCallFailure::not_sent(
6246 "route.open future was cancelled",
6247 )),
6248 );
6249 }
6250 }
6251}
6252
6253struct InlineReconnectGuard {
6254 shared: Arc<Shared>,
6255 generation: u64,
6256 finished: bool,
6257}
6258
6259impl InlineReconnectGuard {
6260 fn new(shared: Arc<Shared>, generation: u64) -> Self {
6261 Self {
6262 shared,
6263 generation,
6264 finished: false,
6265 }
6266 }
6267
6268 fn finish(&mut self) {
6269 self.shared.finish_inline_reconnect(self.generation);
6270 self.finished = true;
6271 }
6272}
6273
6274impl Drop for InlineReconnectGuard {
6275 fn drop(&mut self) {
6276 if !self.finished {
6277 self.shared.finish_inline_reconnect(self.generation);
6278 }
6279 }
6280}
6281
6282#[derive(Clone)]
6283struct RouteState {
6284 handle: RouteHandle,
6285 sem: Arc<Semaphore>,
6286 watch_sem: Option<Arc<Semaphore>>,
6287 opted_in: bool,
6288}
6289
6290#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6291struct RouteKey {
6292 target: RouteTargetKey,
6293 harness: String,
6294 session: String,
6295 consumer_identity: Option<ConsumerIdentityKey>,
6296 consumer_capabilities: Option<ConsumerCapabilitiesKey>,
6297 role_versions: Option<BTreeMap<String, String>>,
6302 scope: Option<ScopeKey>,
6306}
6307
6308impl RouteKey {
6309 fn new(
6310 target: &RouteTarget,
6311 identity: &BindIdentity,
6312 consumer_identity: Option<&ConsumerIdentity>,
6313 consumer_capabilities: Option<&[String]>,
6314 ) -> Self {
6315 Self {
6316 target: RouteTargetKey::from(target),
6317 harness: identity.harness.clone(),
6318 session: identity.session.clone(),
6319 consumer_identity: consumer_identity.map(ConsumerIdentityKey::from),
6320 consumer_capabilities: consumer_capabilities.map(ConsumerCapabilitiesKey::from_slice),
6321 role_versions: None,
6322 scope: None,
6323 }
6324 }
6325
6326 fn with_role_versions(mut self, role_versions: Option<&BTreeMap<String, String>>) -> Self {
6327 self.role_versions = role_versions.cloned();
6328 self
6329 }
6330
6331 fn with_scope(mut self, scope: Option<&ScopeSelector>) -> Self {
6332 self.scope = scope.map(ScopeKey::from);
6333 self
6334 }
6335
6336 fn target_label(&self) -> String {
6337 match &self.target {
6338 RouteTargetKey::ToolProvider { module_id } => format!("tool_provider:{module_id}"),
6339 RouteTargetKey::ManagementSurface { module_id } => {
6340 format!("management_surface:{module_id}")
6341 }
6342 RouteTargetKey::InternalService {
6343 module_id,
6344 service_id,
6345 } => format!("internal_service:{module_id}:{service_id}"),
6346 }
6347 }
6348}
6349
6350#[derive(Clone, Hash, PartialEq, Eq)]
6351struct ConsumerIdentityKey {
6352 module_id: String,
6353 launch_nonce: String,
6354}
6355
6356impl fmt::Debug for ConsumerIdentityKey {
6361 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
6362 f.debug_struct("ConsumerIdentityKey")
6363 .field("module_id", &self.module_id)
6364 .field(
6365 "launch_nonce",
6366 &format_args!("<{} bytes redacted>", self.launch_nonce.len()),
6367 )
6368 .finish()
6369 }
6370}
6371
6372impl From<&ConsumerIdentity> for ConsumerIdentityKey {
6373 fn from(value: &ConsumerIdentity) -> Self {
6374 Self {
6375 module_id: value.module_id.clone(),
6376 launch_nonce: value.launch_nonce.clone(),
6377 }
6378 }
6379}
6380
6381#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6383struct ScopeKey {
6384 owner: String,
6388 scope_ref: String,
6389 scope_epoch: Option<u64>,
6390 bind_proof_digest: Option<[u8; 32]>,
6391}
6392
6393impl From<&ScopeSelector> for ScopeKey {
6394 fn from(value: &ScopeSelector) -> Self {
6395 Self {
6396 owner: serde_json::to_string(&value.owner)
6397 .unwrap_or_else(|_| format!("{:?}", value.owner)),
6398 scope_ref: value.scope_ref.clone(),
6399 scope_epoch: value.scope_epoch,
6400 bind_proof_digest: value
6401 .bind_proof
6402 .as_ref()
6403 .map(|proof| Sha256::digest(proof.as_bytes()).into()),
6404 }
6405 }
6406}
6407
6408#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6409struct ConsumerCapabilitiesKey {
6410 values: Vec<String>,
6411}
6412
6413impl ConsumerCapabilitiesKey {
6414 fn from_slice(values: &[String]) -> Self {
6415 let mut values = values.to_vec();
6416 values.sort();
6417 values.dedup();
6418 Self { values }
6419 }
6420}
6421
6422#[derive(Debug, Clone, Hash, PartialEq, Eq)]
6423enum RouteTargetKey {
6424 ToolProvider {
6425 module_id: String,
6426 },
6427 ManagementSurface {
6428 module_id: String,
6429 },
6430 InternalService {
6431 module_id: String,
6432 service_id: String,
6433 },
6434}
6435
6436impl From<&RouteTarget> for RouteTargetKey {
6437 fn from(value: &RouteTarget) -> Self {
6438 match value {
6439 RouteTarget::ToolProvider { module_id } => Self::ToolProvider {
6440 module_id: module_id.clone(),
6441 },
6442 RouteTarget::ManagementSurface { module_id } => Self::ManagementSurface {
6443 module_id: module_id.clone(),
6444 },
6445 RouteTarget::InternalService {
6446 module_id,
6447 service_id,
6448 } => Self::InternalService {
6449 module_id: module_id.clone(),
6450 service_id: service_id.clone(),
6451 },
6452 }
6453 }
6454}
6455
6456#[derive(Debug, Clone)]
6457struct SharedCallFailure {
6458 kind: FailureKind,
6459}
6460
6461impl SharedCallFailure {
6462 fn not_sent(message: impl Into<String>) -> Self {
6463 CallError::not_sent_with_cause(message, NotSentCause::RouteOpenAbandoned).into()
6464 }
6465
6466 fn into_call_error(self) -> CallError {
6467 match self.kind {
6468 FailureKind::NotSent(source) => CallError::NotSent(Box::new(source)),
6469 FailureKind::OutcomeUnknown(source) => CallError::outcome_unknown_source(source),
6470 FailureKind::DaemonTooOld(daemon_ver) => CallError::DaemonTooOld { daemon_ver },
6471 }
6472 }
6473}
6474
6475impl From<CallError> for SharedCallFailure {
6476 fn from(value: CallError) -> Self {
6477 match value {
6478 CallError::DaemonTooOld { daemon_ver } => Self {
6479 kind: FailureKind::DaemonTooOld(daemon_ver),
6480 },
6481 CallError::NotSent(err) => Self {
6482 kind: FailureKind::NotSent(
6483 err.downcast_ref::<NotSentSource>()
6484 .expect("crate-built route.open failure has a typed source")
6485 .clone(),
6486 ),
6487 },
6488 CallError::OutcomeUnknown(err) => Self {
6489 kind: FailureKind::OutcomeUnknown(
6490 err.downcast_ref::<OutcomeUnknownSource>()
6491 .cloned()
6492 .unwrap_or_else(|| OutcomeUnknownSource {
6493 message: err.to_string(),
6494 cause: OutcomeUnknownCause::CompletionFailed,
6495 route_reason: None,
6496 }),
6497 ),
6498 },
6499 CallError::Module(body) => Self {
6500 kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6501 message: format!(
6502 "unexpected module error during route.open: {} ({})",
6503 body.code, body.message
6504 ),
6505 cause: OutcomeUnknownCause::CompletionFailed,
6506 route_reason: None,
6507 }),
6508 },
6509 CallError::SubscriptionBackpressure(err) => Self {
6510 kind: FailureKind::OutcomeUnknown(OutcomeUnknownSource {
6511 message: err.to_string(),
6512 cause: OutcomeUnknownCause::CompletionFailed,
6513 route_reason: None,
6514 }),
6515 },
6516 CallError::StaleRouteHandle(handle) => {
6517 CallError::not_sent(format!("stale route handle: {handle:?}")).into()
6518 }
6519 error @ (CallError::CapabilityUnprovided { .. }
6520 | CallError::CapabilityAmbiguous { .. }
6521 | CallError::InvalidCapabilityIdentifier { .. }) => {
6522 CallError::not_sent(error.to_string()).into()
6523 }
6524 }
6525 }
6526}
6527
6528#[derive(Debug, Clone)]
6529enum FailureKind {
6530 NotSent(NotSentSource),
6531 OutcomeUnknown(OutcomeUnknownSource),
6532 DaemonTooOld(String),
6533}
6534
6535#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)]
6536struct PendingKey {
6537 generation: u64,
6538 channel: u16,
6539 epoch: u32,
6540 corr: u64,
6541}
6542
6543struct PendingEntry {
6544 accepted: bool,
6545 send_deadline: Option<Instant>,
6546 retain_late_route_open: bool,
6547 expected_control_handle: Option<RouteHandle>,
6548 route_open_reverse_requests: Option<ReverseRequestRegistry>,
6549 route_open_module: Option<String>,
6550 retry: Option<SubscriptionRetry>,
6551 completion: PendingCompletion,
6552}
6553
6554enum PendingCompletion {
6555 Unary(oneshot::Sender<PendingResult>),
6556 Subscription {
6557 events: mpsc::Sender<Vec<u8>>,
6558 closed: oneshot::Sender<Result<(), CallError>>,
6559 ended: watch::Sender<Option<SubscriptionEnd>>,
6560 _permit: Arc<RoutePermit>,
6561 priority: Priority,
6562 },
6563}
6564
6565enum StreamDataDelivery {
6566 NotSubscription,
6567 Full,
6568 Closed,
6569}
6570
6571impl PendingEntry {
6572 fn unary(
6573 tx: oneshot::Sender<PendingResult>,
6574 retain_late_route_open: bool,
6575 expected_control_handle: Option<RouteHandle>,
6576 route_open_reverse_requests: Option<ReverseRequestRegistry>,
6577 ) -> Self {
6578 Self {
6579 accepted: false,
6580 send_deadline: None,
6581 retain_late_route_open,
6582 expected_control_handle,
6583 route_open_reverse_requests,
6584 route_open_module: None,
6585 retry: None,
6586 completion: PendingCompletion::Unary(tx),
6587 }
6588 }
6589
6590 fn subscription(
6591 events: mpsc::Sender<Vec<u8>>,
6592 closed: oneshot::Sender<Result<(), CallError>>,
6593 ended: watch::Sender<Option<SubscriptionEnd>>,
6594 permit: Arc<RoutePermit>,
6595 priority: Priority,
6596 ) -> Self {
6597 Self {
6598 accepted: false,
6599 send_deadline: None,
6600 retain_late_route_open: false,
6601 expected_control_handle: None,
6602 route_open_reverse_requests: None,
6603 route_open_module: None,
6604 retry: None,
6605 completion: PendingCompletion::Subscription {
6606 events,
6607 closed,
6608 ended,
6609 _permit: permit,
6610 priority,
6611 },
6612 }
6613 }
6614
6615 fn completion_is_closed(&self) -> bool {
6616 match &self.completion {
6617 PendingCompletion::Unary(tx) => tx.is_closed(),
6618 PendingCompletion::Subscription { closed, .. } => closed.is_closed(),
6619 }
6620 }
6621
6622 fn is_subscription(&self) -> bool {
6623 matches!(&self.completion, PendingCompletion::Subscription { .. })
6624 }
6625
6626 fn subscription_priority(&self) -> Option<Priority> {
6627 match &self.completion {
6628 PendingCompletion::Subscription { priority, .. } => Some(*priority),
6629 PendingCompletion::Unary(_) => None,
6630 }
6631 }
6632
6633 fn try_send_stream_data(&self, body: Vec<u8>) -> Result<(), StreamDataDelivery> {
6634 let PendingCompletion::Subscription { events, .. } = &self.completion else {
6635 return Err(StreamDataDelivery::NotSubscription);
6636 };
6637 events.try_send(body).map_err(|err| match err {
6638 mpsc::error::TrySendError::Full(_) => StreamDataDelivery::Full,
6639 mpsc::error::TrySendError::Closed(_) => StreamDataDelivery::Closed,
6640 })
6641 }
6642
6643 fn settle_terminal(self, terminal: PendingTerminal) {
6644 if let Some(retry) = &self.retry {
6645 retry.position.stop.cancel();
6646 }
6647 match self.completion {
6648 PendingCompletion::Unary(tx) => {
6649 let _ = tx.send(PendingResult::Terminal(terminal));
6650 }
6651 PendingCompletion::Subscription { closed, ended, .. } => {
6652 let (end, result) = match terminal {
6653 PendingTerminal::Response { body, .. } => {
6654 (SubscriptionEnd::Response(body), Ok(()))
6655 }
6656 PendingTerminal::StreamEnd => (SubscriptionEnd::StreamEnd, Ok(())),
6657 PendingTerminal::Error { body, flags } => {
6658 let err = if error_codes::is_route_busy_retryable(
6659 flags,
6660 &body.code,
6661 self.retry.is_some(),
6662 ) {
6663 busy_error(&body)
6664 } else {
6665 CallError::Module(body.clone())
6666 };
6667 (SubscriptionEnd::Error(body.clone()), Err(err))
6668 }
6669 };
6670 let _ = ended.send(Some(end));
6671 let _ = closed.send(result);
6672 }
6673 }
6674 }
6675
6676 fn settle_failure(self, reason: String) {
6677 if let Some(retry) = &self.retry {
6678 retry.position.stop.cancel();
6679 }
6680 let err = classify_failure(self.accepted, reason, OutcomeUnknownCause::ConsumerClosed);
6681 match self.completion {
6682 PendingCompletion::Unary(tx) => {
6683 let _ = tx.send(PendingResult::CallError(err));
6684 }
6685 PendingCompletion::Subscription { closed, ended, .. } => {
6686 let _ = ended.send(Some(SubscriptionEnd::RouteClosed {
6687 reason: RouteEndReason::ClosedByCaller,
6688 }));
6689 let _ = closed.send(Err(err));
6690 }
6691 }
6692 }
6693
6694 fn settle_call_error(self, err: CallError) {
6695 if let Some(retry) = &self.retry {
6696 retry.position.stop.cancel();
6697 }
6698 match self.completion {
6699 PendingCompletion::Unary(tx) => {
6700 let _ = tx.send(PendingResult::CallError(err));
6701 }
6702 PendingCompletion::Subscription { closed, ended, .. } => {
6703 let end = if let Some(reason) = err.close_reason() {
6704 match reason {
6705 RouteEndReason::ConnectionLost => SubscriptionEnd::ConnectionLost,
6706 reason => SubscriptionEnd::RouteClosed {
6707 reason: reason.clone(),
6708 },
6709 }
6710 } else if matches!(err, CallError::SubscriptionBackpressure(_)) {
6711 SubscriptionEnd::Backpressure
6712 } else {
6713 SubscriptionEnd::ConnectionLost
6714 };
6715 let _ = ended.send(Some(end));
6716 let _ = closed.send(Err(err));
6717 }
6718 }
6719 }
6720
6721 fn settle_subscription_result(self, result: Result<(), CallError>) {
6722 if let Some(retry) = &self.retry {
6723 retry.position.stop.cancel();
6724 }
6725 match self.completion {
6726 PendingCompletion::Subscription { closed, ended, .. } => {
6727 let _ = ended.send(Some(SubscriptionEnd::Cancelled));
6728 let _ = closed.send(result);
6729 }
6730 PendingCompletion::Unary(tx) => {
6731 let _ = tx.send(PendingResult::Failure {
6732 accepted: self.accepted,
6733 reason: "subscription cancel matched a unary request".to_string(),
6734 });
6735 }
6736 }
6737 }
6738}
6739
6740struct PendingRegistration {
6741 shared: Arc<Shared>,
6742 key: PendingKey,
6743 active: bool,
6744 retain_on_drop: bool,
6745 unary_cancel: Option<Arc<UnaryCancel>>,
6746}
6747
6748impl PendingRegistration {
6749 fn new(shared: Arc<Shared>, key: PendingKey, retain_on_drop: bool) -> Self {
6750 Self {
6751 shared,
6752 key,
6753 active: true,
6754 retain_on_drop,
6755 unary_cancel: None,
6756 }
6757 }
6758
6759 fn remove_pending(&mut self) -> Option<bool> {
6760 if !self.active {
6761 return None;
6762 }
6763 self.active = false;
6764 self.shared
6765 .lock_inner()
6766 .remove_pending(&self.key)
6767 .map(|entry| entry.accepted)
6768 }
6769
6770 fn disarm(&mut self) {
6771 self.active = false;
6772 }
6773}
6774
6775impl Drop for PendingRegistration {
6776 fn drop(&mut self) {
6777 if self.retain_on_drop {
6778 self.disarm();
6779 } else {
6780 let _ = self.remove_pending();
6781 }
6782 }
6783}
6784
6785enum PendingResult {
6786 Terminal(PendingTerminal),
6787 CallError(CallError),
6788 Failure { accepted: bool, reason: String },
6789}
6790
6791impl PendingResult {
6792 fn into_call_result(self) -> Result<TerminalFrame, CallError> {
6793 match self {
6794 Self::Terminal(terminal) => Ok(terminal.into_terminal_frame()),
6795 Self::CallError(err) => Err(err),
6796 Self::Failure { accepted, reason } => Err(classify_failure(
6797 accepted,
6798 reason,
6799 OutcomeUnknownCause::CompletionFailed,
6800 )),
6801 }
6802 }
6803}
6804
6805enum PendingTerminal {
6806 Response {
6807 generation: u64,
6808 body: Vec<u8>,
6809 flags: Flags,
6810 },
6811 Error {
6812 body: ErrorBody,
6813 flags: Flags,
6814 },
6815 StreamEnd,
6816}
6817
6818impl PendingTerminal {
6819 fn into_terminal_frame(self) -> TerminalFrame {
6820 match self {
6821 Self::Response {
6822 generation,
6823 body,
6824 flags,
6825 } => TerminalFrame::Response {
6826 generation,
6827 body,
6828 flags,
6829 },
6830 Self::Error { body, flags } => TerminalFrame::Error { body, flags },
6831 Self::StreamEnd => TerminalFrame::StreamEnd,
6832 }
6833 }
6834}
6835
6836#[derive(Debug)]
6837enum TerminalFrame {
6838 Response {
6839 generation: u64,
6840 body: Vec<u8>,
6841 flags: Flags,
6842 },
6843 Error {
6844 body: ErrorBody,
6845 flags: Flags,
6846 },
6847 StreamEnd,
6848}
6849
6850struct WriteCommand {
6851 frame: Frame,
6852 pending: Option<PendingKey>,
6853}
6854
6855trait ConsumerStream: AsyncRead + AsyncWrite + Unpin + Send {}
6856impl<T: AsyncRead + AsyncWrite + Unpin + Send> ConsumerStream for T {}
6857
6858struct OpenedConnection {
6859 stream: Box<dyn ConsumerStream>,
6860 daemon_origin_trusted: bool,
6861 daemon_ver: String,
6862}
6863
6864async fn open_connection(
6865 path: &Path,
6866 deadline: Duration,
6867 transport: ConsumerTransport,
6868 operator_candidates: Option<&[PathBuf]>,
6869) -> Result<OpenedConnection, ConsumerError> {
6870 let path = operator_candidates
6871 .map(crate::operator_app::owned_candidate)
6872 .unwrap_or(path);
6873 if transport == ConsumerTransport::Local {
6874 let read =
6875 connection_file::read_for_client_with_local_endpoint(path).map_err(|source| {
6876 ConsumerError::ConnectionFile {
6877 path: path.to_path_buf(),
6878 source,
6879 }
6880 })?;
6881 let endpoint = read
6882 .local_endpoint
6883 .ok_or_else(|| ConsumerError::NoEndpoint {
6884 path: path.to_path_buf(),
6885 })?;
6886 let label = match &endpoint {
6887 connection_file::LocalEndpoint::Unix { path } => path.display().to_string(),
6888 connection_file::LocalEndpoint::Pipe { name } => name.clone(),
6889 _ => "unsupported local endpoint".to_owned(),
6890 };
6891 let mut stream =
6892 connect_local(&endpoint)
6893 .await
6894 .map_err(|source| ConsumerError::Connect {
6895 path: path.to_path_buf(),
6896 endpoint: label.clone(),
6897 source,
6898 })?;
6899 authenticate_client(&mut stream, &read.info, deadline)
6900 .await
6901 .map_err(|source| ConsumerError::Auth {
6902 path: path.to_path_buf(),
6903 endpoint: label,
6904 source,
6905 })?;
6906 crate::registration::bind_consumer(&mut stream, deadline)
6907 .await
6908 .map_err(ConsumerError::claim)?;
6909 return Ok(OpenedConnection {
6910 stream,
6911 daemon_origin_trusted: trusts_daemon_origin(&read.info.daemon_ver),
6912 daemon_ver: read.info.daemon_ver,
6913 });
6914 }
6915 let conn =
6916 connection_file::read_for_client(path).map_err(|source| ConsumerError::ConnectionFile {
6917 path: path.to_path_buf(),
6918 source,
6919 })?;
6920 open_connection_with_info(path, &conn, deadline).await
6921}
6922
6923async fn connect_local(
6924 endpoint: &connection_file::LocalEndpoint,
6925) -> io::Result<Box<dyn ConsumerStream>> {
6926 match endpoint {
6927 #[cfg(unix)]
6928 connection_file::LocalEndpoint::Unix { path } => {
6929 Ok(Box::new(tokio::net::UnixStream::connect(path).await?))
6930 }
6931 #[cfg(windows)]
6932 connection_file::LocalEndpoint::Pipe { name } => Ok(Box::new(
6933 tokio::net::windows::named_pipe::ClientOptions::new().open(name)?,
6934 )),
6935 _ => Err(io::Error::new(
6936 io::ErrorKind::Unsupported,
6937 "unsupported local endpoint kind",
6938 )),
6939 }
6940}
6941
6942async fn open_connection_with_info(
6943 path: &Path,
6944 conn: &connection_file::ConnectionInfo,
6945 deadline: Duration,
6946) -> Result<OpenedConnection, ConsumerError> {
6947 let endpoint = conn
6948 .endpoints
6949 .first()
6950 .ok_or_else(|| ConsumerError::NoEndpoint {
6951 path: path.to_path_buf(),
6952 })?;
6953 let endpoint_label = format!("{}:{}", endpoint.host, endpoint.port);
6954 let mut stream = TcpStream::connect(&endpoint_label)
6955 .await
6956 .map_err(|source| ConsumerError::Connect {
6957 path: path.to_path_buf(),
6958 endpoint: endpoint_label.clone(),
6959 source,
6960 })?;
6961 let _ = stream.set_nodelay(true);
6969 authenticate_client(&mut stream, conn, deadline)
6970 .await
6971 .map_err(|source| ConsumerError::Auth {
6972 path: path.to_path_buf(),
6973 endpoint: endpoint_label,
6974 source,
6975 })?;
6976 crate::registration::bind_consumer(&mut stream, deadline)
6977 .await
6978 .map_err(ConsumerError::claim)?;
6979 Ok(OpenedConnection {
6980 stream: Box::new(stream),
6981 daemon_origin_trusted: trusts_daemon_origin(&conn.daemon_ver),
6982 daemon_ver: conn.daemon_ver.clone(),
6983 })
6984}
6985
6986fn dispatch_reverse_request(shared: &Arc<Shared>, frame: Frame, handle: RouteHandle) {
6987 let method = serde_json::from_slice::<serde_json::Value>(&frame.body)
6988 .ok()
6989 .and_then(|body| body.get("method")?.as_str().map(str::to_string));
6990 let method_family = method
6991 .as_deref()
6992 .and_then(|method| method.split('/').next())
6993 .filter(|family| !family.is_empty())
6994 .map(str::to_string);
6995 let handler = method_family.as_deref().and_then(|family| {
6996 route_reverse_request_registry(handle.reverse_request_registry_id())
6997 .ok()?
6998 .handler(family)
6999 });
7000 let generation = handle.connection_token();
7001 let shared = Arc::clone(shared);
7002
7003 tokio::spawn(async move {
7004 let (frame_type, body) = if let (Some(handler), Some(method)) = (handler, method) {
7005 let request_body = frame.body.clone();
7006 let corr = frame.header.corr;
7007 match tokio::spawn(async move {
7008 handler(request_body, ReverseRequestContext { corr, method }).await
7009 })
7010 .await
7011 {
7012 Ok(Ok(body)) => (FrameType::Response, body),
7013 Ok(Err(err)) => (
7014 FrameType::Error,
7015 serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, err.to_string()))
7016 .unwrap_or_default(),
7017 ),
7018 Err(err) => (
7019 FrameType::Error,
7020 serde_json::to_vec(&ErrorBody::new(
7021 REVERSE_REQUEST_UNHANDLED,
7022 join_error_message(err),
7023 ))
7024 .unwrap_or_default(),
7025 ),
7026 }
7027 } else {
7028 let message = method_family.map_or_else(
7029 || "reverse request has no valid method".to_string(),
7030 |family| format!("no reverse-request handler is registered for {family}"),
7031 );
7032 (
7033 FrameType::Error,
7034 serde_json::to_vec(&ErrorBody::new(REVERSE_REQUEST_UNHANDLED, message))
7035 .unwrap_or_default(),
7036 )
7037 };
7038
7039 if shared.ingress_handle(generation, handle.channel, handle.epoch) != Some(handle) {
7040 return;
7041 }
7042 let reply = match Frame::build_with_version(
7043 frame.header.ver,
7044 frame_type,
7045 Flags::new(false, Priority::Interactive, false),
7046 handle.channel,
7047 handle.epoch,
7048 frame.header.corr,
7049 body,
7050 ) {
7051 Ok(reply) => reply,
7052 Err(_) => return,
7053 };
7054 let writer = shared.lock_inner().writer.clone();
7055 if let Some(writer) = writer {
7056 let _ = writer
7057 .send(WriteCommand {
7058 frame: reply,
7059 pending: None,
7060 })
7061 .await;
7062 }
7063 });
7064}
7065
7066fn join_error_message(error: tokio::task::JoinError) -> String {
7067 if !error.is_panic() {
7068 return error.to_string();
7069 }
7070 let payload = error.into_panic();
7071 if let Some(message) = payload.downcast_ref::<String>() {
7072 return message.clone();
7073 }
7074 if let Some(message) = payload.downcast_ref::<&str>() {
7075 return (*message).to_string();
7076 }
7077 "reverse-request handler panicked".to_string()
7078}
7079
7080async fn reader_loop<R: AsyncRead + Unpin>(shared: Arc<Shared>, mut reader: R, generation: u64) {
7081 loop {
7082 match read_frame(&mut reader).await {
7083 Ok(Some(frame)) => {
7084 if !dispatch_frame(&shared, generation, frame).await {
7085 return;
7086 }
7087 }
7088 Ok(None) => {
7089 shared.handle_generation_drop(generation, "subc connection closed".to_string());
7090 return;
7091 }
7092 Err(err) => {
7093 shared.handle_generation_drop(generation, err.to_string());
7094 return;
7095 }
7096 }
7097 }
7098}
7099
7100async fn dispatch_frame(shared: &Arc<Shared>, generation: u64, frame: Frame) -> bool {
7101 if !shared.record_inbound_if_current(generation) {
7102 return false;
7103 }
7104 if frame.header.channel != 0
7105 && !shared.validate_ingress_handle(generation, frame.header.channel, frame.header.epoch)
7106 {
7107 return true;
7108 }
7109
7110 if frame.header.ty == FrameType::Request && frame.header.channel != 0 {
7111 if let Some(handle) =
7112 shared.ingress_handle(generation, frame.header.channel, frame.header.epoch)
7113 {
7114 dispatch_reverse_request(shared, frame, handle);
7115 }
7116 return true;
7117 }
7118
7119 let key = PendingKey {
7120 generation,
7121 channel: frame.header.channel,
7122 epoch: frame.header.epoch,
7123 corr: frame.header.corr,
7124 };
7125
7126 if frame.header.channel == 0 && frame.header.ty == FrameType::Response {
7127 if let Some(expected) = shared.pending_expected_control_handle(key) {
7128 let echoes_expected = matches!(
7129 serde_json::from_slice::<ClientControlResponse>(&frame.body),
7130 Ok(ClientControlResponse::RoutePoll {
7131 route_channel,
7132 route_epoch,
7133 ..
7134 }) if route_channel == expected.channel && route_epoch == expected.epoch
7135 );
7136 if !echoes_expected {
7137 shared.count_dropped_route_frame();
7138 return true;
7139 }
7140 }
7141 }
7142
7143 if frame.header.channel == 0
7146 && frame.header.ty == FrameType::Response
7147 && shared.pending_expects_route_open(key)
7148 {
7149 if let Ok((
7150 ClientControlResponse::RouteOpen {
7151 route_channel,
7152 route_epoch,
7153 ..
7154 },
7155 authority,
7156 )) = decode_route_open_response(&frame.body)
7157 {
7158 let reverse_requests = shared
7159 .pending_route_open_reverse_requests(key)
7160 .unwrap_or_default();
7161 let module = shared
7162 .lock_inner()
7163 .pending
7164 .get(&key)
7165 .and_then(|entry| entry.route_open_module.clone());
7166 let handle =
7167 RouteHandle::new_consumer(route_channel, route_epoch, generation, reverse_requests);
7168 shared.install_ingress_handle(handle);
7169 if let Some(target) = authority.target {
7170 let mut inner = shared.lock_inner();
7171 if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7172 inner.route_targets.insert(handle, target);
7173 }
7174 }
7175 if let Some(module) = module {
7176 shared
7177 .lock_inner()
7178 .route_modules
7179 .insert(route_channel, module);
7180 }
7181 }
7182 }
7183
7184 match frame.header.ty {
7185 FrameType::Response => shared.settle_pending(
7186 key,
7187 PendingTerminal::Response {
7188 generation,
7189 body: frame.body,
7190 flags: frame.header.flags,
7191 },
7192 ),
7193 FrameType::Error => {
7194 let body =
7195 serde_json::from_slice::<ErrorBody>(&frame.body).unwrap_or_else(|err| ErrorBody {
7196 code: "invalid_error_body".to_string(),
7197 message: err.to_string(),
7198 detail: None,
7199 });
7200 shared.settle_pending(
7201 key,
7202 PendingTerminal::Error {
7203 body,
7204 flags: frame.header.flags,
7205 },
7206 );
7207 }
7208 FrameType::StreamEnd => shared.settle_pending(key, PendingTerminal::StreamEnd),
7209 FrameType::StreamData => shared.route_stream_data(key, frame.body),
7210 FrameType::Push if frame.header.channel == 0 => {
7211 shared.control_push(&frame.body);
7212 }
7213 FrameType::Push => shared.route_push(
7214 RouteHandle::new(frame.header.channel, frame.header.epoch, generation),
7215 frame.body,
7216 ),
7217 FrameType::Goodbye if frame.header.channel == 0 => {
7218 shared.handle_generation_drop(generation, "subc sent GOODBYE".to_string());
7219 return false;
7220 }
7221 FrameType::Goodbye => {
7222 let handle = RouteHandle::new(frame.header.channel, frame.header.epoch, generation);
7223 let close_reason = shared.lock_inner().route_end(handle.channel);
7224 shared.invalidate_routes_for_handle(handle);
7225 let pending = {
7226 let mut inner = shared.lock_inner();
7227 drain_pending_handle(&mut inner.pending, handle, true)
7228 };
7229 settle_route_pending_entries(pending, "route closed by subc".to_string(), close_reason);
7230 }
7231 FrameType::Ping if frame.header.channel == 0 => {
7232 if let Ok(pong) = Frame::build_with_version(
7233 frame.header.ver,
7234 FrameType::Pong,
7235 frame.header.flags,
7236 0,
7237 0,
7238 frame.header.corr,
7239 Vec::new(),
7240 ) {
7241 let writer = shared.lock_inner().writer.clone();
7242 if let Some(writer) = writer {
7243 let _ = writer
7244 .send(WriteCommand {
7245 frame: pong,
7246 pending: None,
7247 })
7248 .await;
7249 }
7250 }
7251 }
7252 _ => {}
7253 }
7254 true
7255}
7256
7257impl Shared {
7258 fn record_inbound_if_current(&self, generation: u64) -> bool {
7269 let inner = self.lock_inner();
7270 if inner.closed || inner.generation != generation || inner.writer.is_none() {
7271 return false;
7272 }
7273 self.last_inbound_ms
7274 .store(epoch_millis(), Ordering::Release);
7275 true
7276 }
7277
7278 fn generation_is_current(&self, generation: u64) -> bool {
7279 let inner = self.lock_inner();
7280 !inner.closed && inner.generation == generation && inner.writer.is_some()
7281 }
7282
7283 fn pending_expected_control_handle(&self, key: PendingKey) -> Option<RouteHandle> {
7284 self.lock_inner()
7285 .pending
7286 .get(&key)
7287 .and_then(|entry| entry.expected_control_handle)
7288 }
7289
7290 fn count_dropped_route_frame(&self) {
7291 let mut inner = self.lock_inner();
7292 inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7293 }
7294
7295 fn pending_expects_route_open(&self, key: PendingKey) -> bool {
7296 self.lock_inner()
7297 .pending
7298 .get(&key)
7299 .is_some_and(|entry| entry.retain_late_route_open)
7300 }
7301
7302 fn pending_route_open_reverse_requests(
7303 &self,
7304 key: PendingKey,
7305 ) -> Option<ReverseRequestRegistry> {
7306 self.lock_inner()
7307 .pending
7308 .get(&key)
7309 .and_then(|entry| entry.route_open_reverse_requests.clone())
7310 }
7311
7312 fn ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> Option<RouteHandle> {
7313 let inner = self.lock_inner();
7314 let handle = inner.route_epochs.get(&channel).copied()?;
7315 (handle.connection_token() == generation && handle.epoch == epoch).then_some(handle)
7316 }
7317
7318 fn validate_ingress_handle(&self, generation: u64, channel: u16, epoch: u32) -> bool {
7319 let mut inner = self.lock_inner();
7320 let expected = RouteHandle::new(channel, epoch, generation);
7321 if inner.route_epochs.get(&channel) == Some(&expected) {
7322 true
7323 } else {
7324 inner.dropped_route_frames = inner.dropped_route_frames.saturating_add(1);
7325 false
7326 }
7327 }
7328
7329 fn install_ingress_handle(&self, handle: RouteHandle) {
7330 let mut inner = self.lock_inner();
7331 if !inner.closed && inner.generation == handle.connection_token() && inner.writer.is_some()
7332 {
7333 inner.route_end_reasons.remove(&handle.channel);
7334 inner.legacy_channel_reasons.remove(&handle.channel);
7335 inner.route_modules.remove(&handle.channel);
7336 if let Some(previous) = inner.route_epochs.insert(handle.channel, handle) {
7337 inner.route_targets.remove(&previous);
7338 if previous.reverse_request_registry_id() != handle.reverse_request_registry_id() {
7339 release_reverse_request_registry(previous);
7340 }
7341 }
7342 }
7343 }
7344
7345 fn invalidate_routes_for_handle(&self, handle: RouteHandle) {
7346 let removed = {
7347 let mut inner = self.lock_inner();
7348 if inner.route_epochs.get(&handle.channel) != Some(&handle) {
7349 return;
7350 }
7351 inner.release_wire_slots(handle);
7352 let installed = inner.route_epochs.remove(&handle.channel).unwrap();
7353 inner.route_targets.remove(&handle);
7354 inner.retired_routes.remove(&handle);
7355 inner.retirement_goodbyes.remove(&handle);
7356 inner.push_event_receivers.remove(&handle);
7357 release_reverse_request_registry(installed);
7358 inner
7359 .remove_route_by_handle(handle)
7360 .into_iter()
7361 .collect::<Vec<_>>()
7362 };
7363 for route in removed {
7364 route.close();
7365 }
7366 }
7367}
7368
7369async fn retirement_goodbye_loop(shared: Arc<Shared>, generation: u64, notify: Arc<Notify>) {
7370 loop {
7371 let notified = notify.notified();
7372 let next = {
7373 let inner = shared.lock_inner();
7374 if inner.closed || inner.generation != generation || inner.writer.is_none() {
7375 return;
7376 }
7377 inner
7378 .retirement_queue
7379 .front()
7380 .map(|handle| (*handle, inner.writer.as_ref().unwrap().clone()))
7381 };
7382 let Some((handle, writer)) = next else {
7383 notified.await;
7384 continue;
7385 };
7386 let Ok(permit) = writer.reserve().await else {
7387 shared.handle_generation_drop(
7388 generation,
7389 "writer closed before retirement GOODBYE".into(),
7390 );
7391 return;
7392 };
7393 let mut inner = shared.lock_inner();
7394 if inner.closed || inner.generation != generation || inner.writer.is_none() {
7395 return;
7396 }
7397 if inner.retirement_queue.front() != Some(&handle) {
7398 continue;
7399 }
7400 inner.retirement_queue.pop_front();
7401 inner.retirement_goodbyes.remove(&handle);
7402 if inner.route_epochs.get(&handle.channel) == Some(&handle) {
7403 let frame = Frame::build(
7404 FrameType::Goodbye,
7405 Flags::new(false, Priority::Interactive, false),
7406 handle.channel,
7407 handle.epoch,
7408 0,
7409 Vec::new(),
7410 )
7411 .expect("header-only route GOODBYE is valid");
7412 permit.send(WriteCommand {
7415 frame,
7416 pending: None,
7417 });
7418 }
7419 inner.reap_retired_route(handle);
7420 }
7421}
7422
7423async fn writer_loop<W>(
7424 shared: Arc<Shared>,
7425 writer: W,
7426 mut rx: mpsc::Receiver<WriteCommand>,
7427 generation: u64,
7428) where
7429 W: AsyncWrite + Unpin,
7430{
7431 let mut writer = BufWriter::new(writer);
7432 while let Some(command) = rx.recv().await {
7433 if let Some(key) = command.pending {
7434 if !shared.mark_pending_accepted(key) {
7435 continue;
7436 }
7437 }
7438 if let Err(err) = write_frame(&mut writer, &command.frame).await {
7439 shared.handle_generation_drop_with_cause(
7440 generation,
7441 err.to_string(),
7442 OutcomeUnknownCause::WriterClosed,
7443 );
7444 return;
7445 }
7446 while let Ok(command) = rx.try_recv() {
7447 if let Some(key) = command.pending {
7448 if !shared.mark_pending_accepted(key) {
7449 continue;
7450 }
7451 }
7452 if let Err(err) = write_frame(&mut writer, &command.frame).await {
7453 shared.handle_generation_drop_with_cause(
7454 generation,
7455 err.to_string(),
7456 OutcomeUnknownCause::WriterClosed,
7457 );
7458 return;
7459 }
7460 }
7461 if let Err(err) = writer.flush().await.map_err(FrameIoError::Io) {
7462 shared.handle_generation_drop_with_cause(
7463 generation,
7464 err.to_string(),
7465 OutcomeUnknownCause::WriterClosed,
7466 );
7467 return;
7468 }
7469 }
7470}
7471
7472impl Shared {
7473 fn implicit_consumer_identity(&self) -> Option<ConsumerIdentity> {
7474 if self.identity_from_environment && !self.claim_bound {
7477 consumer_identity_from_env()
7478 } else {
7479 None
7480 }
7481 }
7482
7483 fn activity_read_body(&self, request: impl serde::Serialize) -> Result<Vec<u8>, CallError> {
7484 #[derive(serde::Serialize)]
7485 struct ReadRequest<T> {
7486 #[serde(flatten)]
7487 request: T,
7488 #[serde(skip_serializing_if = "Option::is_none")]
7489 consumer_identity: Option<ConsumerIdentity>,
7490 }
7491 serde_json::to_vec(&ReadRequest {
7492 request,
7493 consumer_identity: self.implicit_consumer_identity(),
7494 })
7495 .map_err(|err| CallError::not_sent(format!("failed to encode activity read: {err}")))
7496 }
7497
7498 fn route_open_consumer_identity(
7499 &self,
7500 opts: &CallOptions,
7501 ) -> Result<Option<ConsumerIdentity>, CallError> {
7502 if self.claim_bound && opts.consumer_identity.is_some() {
7503 return Err(CallError::not_sent(
7505 "consumer identity conflicts with connection binding",
7506 ));
7507 }
7508 Ok(opts
7509 .consumer_identity
7510 .clone()
7511 .or_else(|| self.implicit_consumer_identity()))
7512 }
7513
7514 fn close_route_consumer_identity(
7515 &self,
7516 opts: &CloseRouteOptions,
7517 ) -> Result<Option<ConsumerIdentity>, CallError> {
7518 if self.claim_bound && opts.consumer_identity.is_some() {
7519 return Err(CallError::not_sent(
7520 "consumer identity conflicts with connection binding",
7521 ));
7522 }
7523 Ok(opts
7524 .consumer_identity
7525 .clone()
7526 .or_else(|| self.implicit_consumer_identity()))
7527 }
7528}
7529
7530fn route_open_consumer_capabilities(opts: &CallOptions) -> Option<Vec<String>> {
7531 opts.reverse_requests.seal();
7532 let mut capabilities = opts.reverse_requests.capabilities();
7533 capabilities.extend(opts.consumer_capabilities());
7534 capabilities.sort();
7535 capabilities.dedup();
7536 (!capabilities.is_empty()).then_some(capabilities)
7537}
7538
7539fn route_open_role_versions(
7544 role_versions: Option<&BTreeMap<String, String>>,
7545) -> Option<BTreeMap<String, String>> {
7546 role_versions
7547 .filter(|role_versions| !role_versions.is_empty())
7548 .cloned()
7549}
7550
7551fn close_route_consumer_capabilities(opts: &CloseRouteOptions) -> Option<Vec<String>> {
7552 opts.reverse_requests.seal();
7553 let mut capabilities = opts.reverse_requests.capabilities();
7554 capabilities.extend(opts.consumer_capabilities());
7555 capabilities.sort();
7556 capabilities.dedup();
7557 (!capabilities.is_empty()).then_some(capabilities)
7558}
7559
7560fn consumer_identity_from_env() -> Option<ConsumerIdentity> {
7561 let module_id = std::env::var(SUBC_MODULE_ID_ENV)
7562 .ok()
7563 .filter(|value| !value.is_empty())?;
7564 let launch_nonce = crate::launch_nonce()
7571 .ok()
7572 .flatten()
7573 .map(|nonce| nonce.value().to_string())?;
7574 Some(ConsumerIdentity {
7575 module_id,
7576 launch_nonce,
7577 })
7578}
7579
7580fn validate_capability_for_resolution(capability: &str) -> Result<(), CallError> {
7581 if is_valid_capability_identifier(capability) {
7582 Ok(())
7583 } else {
7584 Err(CallError::InvalidCapabilityIdentifier {
7585 capability: capability.to_string(),
7586 })
7587 }
7588}
7589
7590fn capability_claimants(catalog: &CatalogList, capability: &str) -> Vec<String> {
7591 let mut claimants = catalog
7592 .modules
7593 .iter()
7594 .filter(|module| {
7595 module.capabilities.as_ref().is_some_and(|capabilities| {
7596 capabilities
7597 .provides
7598 .iter()
7599 .any(|claim| claim == capability)
7600 })
7601 })
7602 .map(|module| module.module_id.clone())
7603 .collect::<Vec<_>>();
7604 claimants.sort();
7605 claimants
7606}
7607
7608fn epoch_millis() -> u64 {
7609 u64::try_from(
7610 SystemTime::now()
7611 .duration_since(UNIX_EPOCH)
7612 .unwrap_or_default()
7613 .as_millis(),
7614 )
7615 .unwrap_or(u64::MAX)
7616}
7617
7618fn default_random_unit() -> f64 {
7634 use std::hash::{BuildHasher, RandomState};
7635 static COUNTER: AtomicU64 = AtomicU64::new(0);
7636 let bits = RandomState::new().hash_one(COUNTER.fetch_add(1, Ordering::Relaxed));
7637 (bits >> 11) as f64 / (1u64 << 53) as f64
7639}
7640
7641fn request_not_sent_after_route_open_failure(err: CallError) -> CallError {
7642 match err {
7643 CallError::OutcomeUnknown(source) => CallError::not_sent_with_cause(
7644 format!("request not sent: route.open did not complete ({source})"),
7645 NotSentCause::RouteOpenAbandoned,
7646 ),
7647 other => other,
7648 }
7649}
7650
7651fn classify_failure(
7652 accepted: bool,
7653 reason: impl Into<String>,
7654 cause: OutcomeUnknownCause,
7655) -> CallError {
7656 classify_failure_with_not_sent_cause(accepted, reason, cause, NotSentCause::WriterRejected)
7657}
7658
7659fn classify_failure_with_not_sent_cause(
7660 accepted: bool,
7661 reason: impl Into<String>,
7662 cause: OutcomeUnknownCause,
7663 not_sent_cause: NotSentCause,
7664) -> CallError {
7665 if accepted {
7666 CallError::outcome_unknown(reason, cause)
7667 } else {
7668 CallError::not_sent_with_cause(reason, not_sent_cause)
7669 }
7670}
7671
7672fn settle_route_pending_entries(
7673 entries: Vec<PendingEntry>,
7674 message: String,
7675 reason: impl Into<RouteEnd>,
7676) {
7677 let reason = reason.into();
7678 let cause = if reason.reason == RouteEndReason::ConnectionLost {
7679 OutcomeUnknownCause::ConnectionFailed
7680 } else {
7681 OutcomeUnknownCause::RouteEnded
7682 };
7683 settle_route_pending_entries_with_cause(entries, message, reason, cause);
7684}
7685
7686fn settle_route_pending_entries_with_cause(
7687 entries: Vec<PendingEntry>,
7688 message: String,
7689 reason: impl Into<RouteEnd>,
7690 cause: OutcomeUnknownCause,
7691) {
7692 let reason = reason.into();
7693 for entry in entries {
7694 let err = if entry.accepted {
7695 CallError::outcome_unknown_source(OutcomeUnknownSource {
7696 message: message.clone(),
7697 cause,
7698 route_reason: Some(reason.clone()),
7699 })
7700 } else {
7701 CallError::NotSent(Box::new(NotSentSource {
7702 message: message.clone(),
7703 cause: NotSentCause::WriterRejected,
7704 never_forwarded: true,
7705 route_reason: Some(reason.clone()),
7706 refusal: None,
7707 }))
7708 };
7709 entry.settle_call_error(err);
7710 }
7711}
7712
7713fn settle_pending_entries(entries: Vec<PendingEntry>, reason: String) {
7714 for entry in entries {
7715 entry.settle_failure(reason.clone());
7716 }
7717}
7718
7719fn drain_pending_generation(
7720 pending: &mut HashMap<PendingKey, PendingEntry>,
7721 generation: u64,
7722) -> Vec<PendingEntry> {
7723 let keys = pending
7724 .keys()
7725 .copied()
7726 .filter(|key| key.generation == generation)
7727 .collect::<Vec<_>>();
7728 keys.into_iter()
7729 .filter_map(|key| pending.remove(&key))
7730 .collect()
7731}
7732
7733fn drain_pending_handle(
7734 pending: &mut HashMap<PendingKey, PendingEntry>,
7735 handle: RouteHandle,
7736 include_subscriptions: bool,
7737) -> Vec<PendingEntry> {
7738 let keys = pending
7739 .iter()
7740 .filter_map(|(key, entry)| {
7741 (key.generation == handle.connection_token()
7742 && key.channel == handle.channel
7743 && key.epoch == handle.epoch
7744 && (include_subscriptions || !entry.is_subscription()))
7745 .then_some(*key)
7746 })
7747 .collect::<Vec<_>>();
7748 keys.into_iter()
7749 .filter_map(|key| pending.remove(&key))
7750 .collect()
7751}
7752
7753fn fail_openings(openings: Vec<Vec<OpeningWaiter>>, failure: SharedCallFailure) {
7754 for waiters in openings {
7755 for waiter in waiters {
7756 let _ = waiter.send(Err(failure.clone()));
7757 }
7758 }
7759}
7760
7761fn emit_callbacks(callbacks: Vec<Callback>, state: ConnectionState) {
7762 for callback in callbacks {
7763 if let Ok(callback) = callback.lock() {
7764 callback(state.clone());
7765 }
7766 }
7767}
7768
7769pub fn is_retryable_route_open_code(code: &str) -> bool {
7772 error_codes::is_retryable_route_open(code)
7773}
7774
7775fn is_data_plane_drain_refusal(code: &str) -> bool {
7792 code == error_codes::MODULE_RELOADING
7793}
7794
7795const DAEMON_ORIGIN_MIN_VERSION: (u64, u64, u64) = (0, 37, 15);
7797
7798pub fn trusts_daemon_origin(daemon_ver: &str) -> bool {
7807 daemon_version_at_least(daemon_ver, DAEMON_ORIGIN_MIN_VERSION)
7808}
7809
7810fn daemon_version_at_least(daemon_ver: &str, minimum: (u64, u64, u64)) -> bool {
7811 let mut components = daemon_ver.split('.');
7812 let mut next = || {
7813 let component = components.next()?;
7814 if component.is_empty() || !component.bytes().all(|byte| byte.is_ascii_digit()) {
7815 return None;
7816 }
7817 component.parse::<u64>().ok()
7818 };
7819 let version = (next(), next(), next());
7820 match version {
7821 (Some(major), Some(minor), Some(patch)) if components.next().is_none() => {
7822 (major, minor, patch) >= minimum
7823 }
7824 _ => false,
7825 }
7826}
7827
7828pub fn is_daemon_refusal_before_forward(
7839 daemon_origin_trusted: bool,
7840 flags: Flags,
7841 code: &str,
7842) -> bool {
7843 daemon_origin_trusted
7844 && flags.is_daemon_origin()
7845 && matches!(
7846 code,
7847 error_codes::MODULE_RELOADING
7848 | error_codes::UNKNOWN_CHANNEL
7849 | error_codes::STALE_ROUTE_EPOCH
7850 )
7851}
7852
7853fn route_is_installed(inner: &Inner, handle: RouteHandle) -> bool {
7858 handle.channel == 0 || inner.route_epochs.get(&handle.channel) == Some(&handle)
7859}
7860
7861fn is_retryable_catalog_transport_error(err: &CallError) -> bool {
7862 matches!(err, CallError::NotSent(_) | CallError::OutcomeUnknown(_))
7863}
7864
7865fn is_reconnect_transient(err: &ConsumerError) -> bool {
7866 if let ConsumerError::Connect { source, .. } = err {
7867 if let Some(claim) = source
7868 .get_ref()
7869 .and_then(|source| source.downcast_ref::<crate::ClaimError>())
7870 {
7871 return matches!(claim, crate::ClaimError::Refused { code } if error_codes::is_retryable_claim(code));
7872 }
7873 }
7874 match err {
7875 ConsumerError::Connect { source, .. } => matches!(
7876 source.kind(),
7877 io::ErrorKind::ConnectionRefused
7878 | io::ErrorKind::ConnectionReset
7879 | io::ErrorKind::ConnectionAborted
7880 | io::ErrorKind::TimedOut
7881 | io::ErrorKind::NotConnected
7882 | io::ErrorKind::AddrNotAvailable
7883 ),
7884 ConsumerError::ConnectionFile { source, .. } => match source {
7885 ConnectionFileError::Io { source, .. } => source.kind() == io::ErrorKind::NotFound,
7886 _ => false,
7887 },
7888 ConsumerError::Auth { .. } => true,
7897 ConsumerError::Discovery { .. }
7898 | ConsumerError::NoEndpoint { .. }
7899 | ConsumerError::Closed => false,
7900 }
7901}
7902
7903impl From<FrameBuildError> for CallError {
7904 fn from(err: FrameBuildError) -> Self {
7905 Self::not_sent(err.to_string())
7906 }
7907}
7908
7909#[cfg(test)]
7910mod local_transport_tests;
7911
7912#[cfg(test)]
7913mod tests {
7914 use super::*;
7915
7916 mod busy_refusals_tests;
7917 mod not_sent_tests;
7918 mod route_close_tests;
7919 mod route_deadline_tests;
7920
7921 #[derive(Clone)]
7922 struct InstrumentedWriter {
7923 state: Arc<InstrumentedWriterState>,
7924 fail_flush: bool,
7925 }
7926
7927 #[derive(Default)]
7928 struct InstrumentedWriterState {
7929 bytes: Mutex<Vec<u8>>,
7930 flushes: std::sync::atomic::AtomicUsize,
7931 }
7932
7933 impl InstrumentedWriter {
7934 fn new(fail_flush: bool) -> Self {
7935 Self {
7936 state: Arc::new(InstrumentedWriterState::default()),
7937 fail_flush,
7938 }
7939 }
7940
7941 fn bytes(&self) -> Vec<u8> {
7942 self.state
7943 .bytes
7944 .lock()
7945 .unwrap_or_else(|poisoned| poisoned.into_inner())
7946 .clone()
7947 }
7948
7949 fn flush_count(&self) -> usize {
7950 self.state.flushes.load(Ordering::SeqCst)
7951 }
7952 }
7953
7954 impl AsyncWrite for InstrumentedWriter {
7955 fn poll_write(
7956 self: Pin<&mut Self>,
7957 _cx: &mut Context<'_>,
7958 buf: &[u8],
7959 ) -> Poll<io::Result<usize>> {
7960 self.state
7961 .bytes
7962 .lock()
7963 .unwrap_or_else(|poisoned| poisoned.into_inner())
7964 .extend_from_slice(buf);
7965 Poll::Ready(Ok(buf.len()))
7966 }
7967
7968 fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7969 self.state.flushes.fetch_add(1, Ordering::SeqCst);
7970 if self.fail_flush {
7971 Poll::Ready(Err(io::Error::new(
7972 io::ErrorKind::BrokenPipe,
7973 "instrumented flush failure",
7974 )))
7975 } else {
7976 Poll::Ready(Ok(()))
7977 }
7978 }
7979
7980 fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<io::Result<()>> {
7981 Poll::Ready(Ok(()))
7982 }
7983 }
7984
7985 fn writer_test_shared() -> Arc<Shared> {
7986 Arc::new(reader_skew_tests::legacy_shared(
7987 PathBuf::from("/tmp/does-not-exist"),
7988 ConsumerOptions {
7989 reconnect_backoff: RetryBackoff {
7990 max_attempts: 1,
7991 ..RetryBackoff::default()
7992 },
7993 ..ConsumerOptions::default()
7994 },
7995 ))
7996 }
7997
7998 fn reverse_test_shared(
7999 reverse_requests: ReverseRequestRegistry,
8000 ) -> (Arc<Shared>, mpsc::Receiver<WriteCommand>, RouteHandle) {
8001 let shared = writer_test_shared();
8002 let (writer, receiver) = mpsc::channel(16);
8003 let handle = RouteHandle::new_consumer(17, 3, 1, reverse_requests);
8004 {
8005 let mut inner = shared.lock_inner();
8006 inner.writer = Some(writer);
8007 inner.daemon_ver = "0.39.0".into();
8008 inner.route_epochs.insert(handle.channel, handle);
8009 }
8010 (shared, receiver, handle)
8011 }
8012
8013 fn reverse_request_frame(handle: RouteHandle, corr: u64, body: Vec<u8>) -> Frame {
8014 Frame::build(
8015 FrameType::Request,
8016 Flags::new(false, Priority::Interactive, false),
8017 handle.channel,
8018 handle.epoch,
8019 corr,
8020 body,
8021 )
8022 .unwrap()
8023 }
8024
8025 #[tokio::test]
8026 async fn binary_reply_request_preserves_flagged_non_utf8_bytes() {
8027 let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8028 let consumer = SubcConsumer {
8029 shared: Arc::clone(&shared),
8030 };
8031 shared
8032 .install_one_shot_route(RouteState {
8033 handle,
8034 sem: Arc::new(Semaphore::new(1)),
8035 watch_sem: None,
8036 opted_in: false,
8037 })
8038 .unwrap();
8039 let request = tokio::spawn(async move {
8040 consumer
8041 .request(&handle, b"bytes".to_vec(), CallOptions::default())
8042 .await
8043 });
8044 let command = receiver.recv().await.unwrap();
8045 let bytes = vec![0, 0xff, 0x80, b'{'];
8046 let frame = Frame::build(
8047 FrameType::Response,
8048 Flags::new(true, Priority::Interactive, false),
8049 handle.channel,
8050 handle.epoch,
8051 command.frame.header.corr,
8052 bytes.clone(),
8053 )
8054 .unwrap();
8055 assert!(dispatch_frame(&shared, 1, frame).await);
8056 assert_eq!(request.await.unwrap().unwrap(), bytes);
8057 }
8058
8059 async fn capture_route_open(
8060 reverse_requests: ReverseRequestRegistry,
8061 ) -> (serde_json::Value, RouteHandle) {
8062 capture_route_open_with_options(CallOptions {
8063 reverse_requests,
8064 ..CallOptions::default()
8065 })
8066 .await
8067 }
8068
8069 async fn capture_route_open_with_options(
8070 opts: CallOptions,
8071 ) -> (serde_json::Value, RouteHandle) {
8072 let shared = writer_test_shared();
8073 let (writer, mut receiver) = mpsc::channel(4);
8074 shared.lock_inner().writer = Some(writer);
8075 shared.lock_inner().daemon_ver = "0.39.0".into();
8076 let consumer = SubcConsumer {
8077 shared: Arc::clone(&shared),
8078 };
8079 let task = tokio::spawn(async move {
8080 consumer
8081 .open_route(
8082 RouteTarget::ToolProvider {
8083 module_id: "reverse-provider".to_string(),
8084 },
8085 BindIdentity::new("test".to_string(), "reverse".to_string()),
8086 opts,
8087 )
8088 .await
8089 });
8090 let command = receiver.recv().await.expect("route.open frame");
8091 let request = serde_json::from_slice(&command.frame.body).unwrap();
8092 let response_body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
8093 request_window: None,
8094 watch_window: None,
8095 route_channel: 17,
8096 route_epoch: 3,
8097 })
8098 .unwrap();
8099 assert!(
8100 dispatch_frame(
8101 &shared,
8102 1,
8103 response_frame(0, 0, command.frame.header.corr, response_body),
8104 )
8105 .await
8106 );
8107 let handle = task.await.unwrap().unwrap();
8108 (request, handle)
8109 }
8110
8111 #[tokio::test]
8113 async fn held_subscriptions_set_the_flag_but_ordinary_requests_do_not() {
8114 let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8115 let call_shared = Arc::clone(&shared);
8116 let call = tokio::spawn(async move {
8117 call_shared
8118 .send_request(RequestSend {
8119 binary: false,
8120 expected_handle: Some(handle),
8121 channel: handle.channel,
8122 epoch: handle.epoch,
8123 body: b"ordinary".to_vec(),
8124 priority: Priority::Interactive,
8125 admission_class: AdmissionClass::Normal,
8126 deadline: Instant::now() + Duration::from_secs(1),
8127 retain_late_route_open: false,
8128 route_open_reverse_requests: None,
8129 })
8130 .await
8131 });
8132 let ordinary = receiver.recv().await.unwrap();
8133 assert_eq!(ordinary.frame.header.encode()[6] & FLAG_SUBSCRIPTION, 0);
8134 assert!(
8135 dispatch_frame(
8136 &shared,
8137 1,
8138 response_frame(
8139 handle.channel,
8140 handle.epoch,
8141 ordinary.frame.header.corr,
8142 Vec::new()
8143 ),
8144 )
8145 .await
8146 );
8147 assert!(call.await.unwrap().is_ok());
8148
8149 let permit = Arc::new(Semaphore::new(1)).acquire_owned().await.unwrap();
8150 let subscription = Arc::clone(&shared)
8151 .send_subscription(SubscriptionSend {
8152 expected_handle: Some(handle),
8153 channel: handle.channel,
8154 epoch: handle.epoch,
8155 body: b"held".to_vec(),
8156 priority: Priority::Interactive,
8157 admission_class: AdmissionClass::Normal,
8158 event_buffer: 1,
8159 deadline: Instant::now() + Duration::from_secs(1),
8160 permit: RoutePermit::legacy(permit),
8161 })
8162 .await
8163 .unwrap();
8164 let held = receiver.recv().await.unwrap();
8165 assert_ne!(
8166 held.frame.header.encode()[6] & FLAG_SUBSCRIPTION,
8167 0,
8168 "a held-open subscription must be marked for drain accounting"
8169 );
8170 drop(subscription);
8171 release_reverse_request_registry(handle);
8172 }
8173
8174 #[tokio::test]
8175 async fn registered_handlers_derive_route_open_consumer_capabilities() {
8176 let registry = ReverseRequestRegistry::new();
8177 registry
8178 .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8179 .unwrap();
8180 let (request, handle) = capture_route_open(registry).await;
8181 assert_eq!(
8182 request.get("consumer_capabilities"),
8183 Some(&serde_json::json!(["elicitation"]))
8184 );
8185 release_reverse_request_registry(handle);
8186 }
8187
8188 #[tokio::test]
8189 async fn declared_consumer_capabilities_merge_with_handler_families_on_route_open() {
8190 let registry = ReverseRequestRegistry::new();
8191 registry
8192 .on_request("elicitation", |_body, _ctx| async { Vec::new() })
8193 .unwrap();
8194 let opts = CallOptions {
8195 reverse_requests: registry,
8196 ..CallOptions::default()
8197 }
8198 .with_consumer_capability("tool-result/v1")
8199 .unwrap()
8200 .with_consumer_capability("elicitation")
8201 .unwrap()
8202 .with_consumer_capability("tool-result/v1")
8203 .unwrap();
8204
8205 let (request, handle) = capture_route_open_with_options(opts).await;
8206 assert_eq!(
8207 request.get("consumer_capabilities"),
8208 Some(&serde_json::json!(["elicitation", "tool-result/v1"]))
8209 );
8210 release_reverse_request_registry(handle);
8211 }
8212
8213 #[test]
8214 fn invalid_consumer_capability_declarations_are_rejected_before_route_open() {
8215 let (shared, mut receiver) = {
8216 let shared = writer_test_shared();
8217 let (writer, receiver) = mpsc::channel(4);
8218 shared.lock_inner().writer = Some(writer);
8219 shared.lock_inner().daemon_ver = "0.39.0".into();
8220 (shared, receiver)
8221 };
8222 let too_long = "x".repeat(65);
8223 for invalid in [
8224 String::new(),
8225 "content v1".to_string(),
8226 "content\tv1".to_string(),
8227 "content\nv1".to_string(),
8228 "cöntent/v1".to_string(),
8229 "content/\u{7f}v1".to_string(),
8230 too_long,
8231 ] {
8232 let error = CallOptions::default()
8233 .with_consumer_capability(invalid.clone())
8234 .expect_err("invalid declarations must not produce route options");
8235 assert_eq!(error.capability(), invalid);
8236 assert!(
8237 receiver.try_recv().is_err(),
8238 "invalid declaration {invalid:?} must be rejected before any frame is queued"
8239 );
8240 }
8241 let close_error = CloseRouteOptions::default()
8242 .with_consumer_capability("bad value")
8243 .expect_err("close-route declarations use the same validation");
8244 assert_eq!(close_error.capability(), "bad value");
8245 let call_options = CallOptions::default()
8246 .with_consumer_capability("tool-result/v1")
8247 .unwrap();
8248 assert_eq!(
8249 call_options.consumer_capabilities(),
8250 vec!["tool-result/v1".to_string()]
8251 );
8252 let close_options = CloseRouteOptions::default()
8253 .with_consumer_capability("tool-result/v1")
8254 .unwrap();
8255 assert_eq!(
8256 close_options.consumer_capabilities(),
8257 vec!["tool-result/v1".to_string()]
8258 );
8259 shared.close_sync("test complete");
8260 }
8261
8262 #[tokio::test]
8263 async fn no_handlers_omit_consumer_capabilities_from_route_open() {
8264 let (request, handle) = capture_route_open(ReverseRequestRegistry::new()).await;
8265 assert!(!request
8266 .as_object()
8267 .unwrap()
8268 .contains_key("consumer_capabilities"));
8269 release_reverse_request_registry(handle);
8270 }
8271
8272 #[tokio::test]
8273 async fn reverse_request_without_handler_returns_typed_error_instead_of_silence() {
8274 let (shared, mut receiver, handle) = reverse_test_shared(ReverseRequestRegistry::new());
8275 let body = serde_json::to_vec(&serde_json::json!({
8276 "jsonrpc": "2.0",
8277 "id": 1,
8278 "method": "elicitation/create",
8279 "params": {}
8280 }))
8281 .unwrap();
8282 assert!(dispatch_frame(&shared, 1, reverse_request_frame(handle, 800, body)).await);
8283 let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8284 .await
8285 .unwrap()
8286 .unwrap()
8287 .frame;
8288 assert_eq!(reply.header.ty, FrameType::Error);
8289 assert_eq!(reply.header.corr, 800);
8290 let error: ErrorBody = serde_json::from_slice(&reply.body).unwrap();
8291 assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8292 release_reverse_request_registry(handle);
8293 }
8294
8295 #[tokio::test]
8296 async fn reverse_request_round_trip_preserves_raw_body_corr_and_response() {
8297 let registry = ReverseRequestRegistry::new();
8298 let seen = Arc::new(Mutex::new(None));
8299 let seen_by_handler = Arc::clone(&seen);
8300 let response = br#"{"jsonrpc":"2.0","id":9,"result":{"accepted":true}}"#.to_vec();
8301 let expected_response = response.clone();
8302 registry
8303 .on_request("elicitation", move |body, ctx| {
8304 *seen_by_handler
8305 .lock()
8306 .unwrap_or_else(|poisoned| poisoned.into_inner()) =
8307 Some((body, ctx.corr, ctx.method));
8308 let response = response.clone();
8309 async move { response }
8310 })
8311 .unwrap();
8312 let (shared, mut receiver, handle) = reverse_test_shared(registry);
8313 let request_body =
8314 br#"{"jsonrpc":"2.0","id":9,"method":"elicitation/create","params":{"z":1,"a":2}}"#
8315 .to_vec();
8316 assert!(
8317 dispatch_frame(
8318 &shared,
8319 1,
8320 reverse_request_frame(handle, 801, request_body.clone()),
8321 )
8322 .await
8323 );
8324 let reply = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8325 .await
8326 .unwrap()
8327 .unwrap()
8328 .frame;
8329 assert_eq!(reply.header.ty, FrameType::Response);
8330 assert_eq!(reply.header.corr, 801);
8331 assert_eq!(reply.body, expected_response);
8332 assert_eq!(
8333 seen.lock()
8334 .unwrap_or_else(|poisoned| poisoned.into_inner())
8335 .clone(),
8336 Some((request_body, 801, "elicitation/create".to_string()))
8337 );
8338 release_reverse_request_registry(handle);
8339 }
8340
8341 #[tokio::test]
8342 async fn panicking_reverse_handler_returns_typed_refusal_and_sibling_request_resolves() {
8343 let registry = ReverseRequestRegistry::new();
8344 registry
8345 .on_request("sampling", |_body, _ctx| async move {
8346 panic!("person prompt exploded");
8347 })
8348 .unwrap();
8349 let (shared, mut receiver, handle) = reverse_test_shared(registry);
8350 let sibling_shared = Arc::clone(&shared);
8351 let sibling = tokio::spawn(async move {
8352 sibling_shared
8353 .send_request(RequestSend {
8354 binary: false,
8355 expected_handle: Some(handle),
8356 channel: handle.channel,
8357 epoch: handle.epoch,
8358 body: b"sibling".to_vec(),
8359 priority: Priority::Interactive,
8360 admission_class: AdmissionClass::Normal,
8361 deadline: Instant::now() + Duration::from_secs(1),
8362 retain_late_route_open: false,
8363 route_open_reverse_requests: None,
8364 })
8365 .await
8366 });
8367 let sibling_request = receiver.recv().await.unwrap();
8368 let reverse_body = serde_json::to_vec(&serde_json::json!({
8369 "method": "sampling/createMessage",
8370 "params": {}
8371 }))
8372 .unwrap();
8373 assert!(
8374 dispatch_frame(&shared, 1, reverse_request_frame(handle, 802, reverse_body),).await
8375 );
8376 assert!(
8377 dispatch_frame(
8378 &shared,
8379 1,
8380 response_frame(
8381 handle.channel,
8382 handle.epoch,
8383 sibling_request.frame.header.corr,
8384 b"ok".to_vec(),
8385 ),
8386 )
8387 .await
8388 );
8389 assert!(matches!(
8390 sibling.await.unwrap().unwrap(),
8391 TerminalFrame::Response { body, .. } if body == b"ok"
8392 ));
8393 let refusal = tokio::time::timeout(Duration::from_secs(1), receiver.recv())
8394 .await
8395 .unwrap()
8396 .unwrap()
8397 .frame;
8398 assert_eq!(refusal.header.ty, FrameType::Error);
8399 let error: ErrorBody = serde_json::from_slice(&refusal.body).unwrap();
8400 assert_eq!(error.code, REVERSE_REQUEST_UNHANDLED);
8401 assert!(error.message.contains("person prompt exploded"));
8402 assert!(shared.generation_is_current(1));
8403 release_reverse_request_registry(handle);
8404 }
8405
8406 fn reservation_stand_in(
8407 credit: usize,
8408 capacity: usize,
8409 ) -> (
8410 Arc<Shared>,
8411 SubcConsumer,
8412 mpsc::Receiver<WriteCommand>,
8413 RouteHandle,
8414 Arc<Semaphore>,
8415 ) {
8416 let shared = writer_test_shared();
8417 let (writer, rx) = mpsc::channel(capacity);
8418 shared.lock_inner().writer = Some(writer);
8419 shared.lock_inner().daemon_ver = "0.39.0".into();
8420 let handle = RouteHandle::new(5, 3, 1);
8421 let sem = Arc::new(Semaphore::new(credit));
8422 shared
8423 .install_one_shot_route(RouteState {
8424 handle,
8425 sem: Arc::clone(&sem),
8426 watch_sem: None,
8427 opted_in: false,
8428 })
8429 .unwrap();
8430 let consumer = SubcConsumer {
8431 shared: Arc::clone(&shared),
8432 };
8433 (shared, consumer, rx, handle, sem)
8434 }
8435
8436 #[tokio::test]
8437 async fn reservation_send_is_synchronous_and_uses_prevalidated_body() {
8438 let oversized = vec![0; subc_protocol::MAX_FRAME_BODY_LEN as usize + 1];
8439 assert!(matches!(
8440 RequestBody::new(oversized),
8441 Err(CallError::NotSent(_))
8442 ));
8443 let body = RequestBody::new(b"valid".to_vec()).unwrap();
8444 let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8445 let reserved = consumer
8446 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8447 .await
8448 .unwrap();
8449 let corr = reserved.correlation_id();
8450 assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 0);
8451 assert!(rx.try_recv().is_err());
8452
8453 let (sent_corr, reply): (CorrelationId, PendingReply) =
8456 reserved.send(body, CallOptions::default());
8457 assert_eq!(sent_corr, corr);
8458 let command = rx.try_recv().expect("send must enqueue without yielding");
8459 assert_eq!(command.frame.body, b"valid");
8460 assert_eq!(command.frame.header.corr, corr);
8461 assert_eq!(sem.available_permits(), 0);
8462 assert!(shared.mark_pending_accepted(command.pending.unwrap()));
8463 dispatch_frame(
8464 &shared,
8465 1,
8466 response_frame(handle.channel, handle.epoch, corr, b"reply".to_vec()),
8467 )
8468 .await;
8469 assert_eq!(reply.await.unwrap(), b"reply");
8470 assert_eq!(sem.available_permits(), 1);
8471 consumer.close().await;
8472 }
8473
8474 #[tokio::test]
8475 async fn reservation_drop_releases_route_credit_and_writer_capacity_without_sending() {
8476 let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8477 let deadline = Instant::now() + Duration::from_secs(1);
8478 let first = consumer.reserve(&handle, deadline).await.unwrap();
8479 let second = consumer.reserve(&handle, deadline);
8480 tokio::pin!(second);
8481 assert_pending(second.as_mut()).await;
8482 assert_eq!(sem.available_permits(), 0);
8483 drop(first);
8484 let second = timeout_at(deadline, second).await.unwrap().unwrap();
8485 drop(second);
8486 assert_eq!(sem.available_permits(), 1);
8487 assert_eq!(shared.lock_inner().writer.as_ref().unwrap().capacity(), 1);
8488 assert!(shared.lock_inner().pending.is_empty());
8489 assert!(rx.try_recv().is_err());
8490 consumer.close().await;
8491 }
8492
8493 #[tokio::test]
8494 async fn reservation_route_closed_before_send_matches_an_ordinary_unwritten_request() {
8495 let (shared, consumer, mut rx, handle, _) = reservation_stand_in(2, 4);
8496 let reserved = consumer
8497 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8498 .await
8499 .unwrap();
8500 let ordinary = consumer.request(&handle, b"ordinary".to_vec(), CallOptions::default());
8501 tokio::pin!(ordinary);
8502 assert_pending(ordinary.as_mut()).await;
8503 let ordinary_command = rx.try_recv().unwrap();
8504 assert_eq!(ordinary_command.frame.body, b"ordinary");
8505 consumer
8506 .close_handle(&handle, CloseRouteOptions::default())
8507 .await
8508 .unwrap();
8509 let (_, reply) = reserved.send(
8510 RequestBody::new(b"reserved".to_vec()).unwrap(),
8511 CallOptions::default(),
8512 );
8513 let ordinary_error = ordinary.await.unwrap_err();
8514 let reserved_error = reply.await.unwrap_err();
8515 assert!(matches!(reserved_error, CallError::NotSent(_)));
8516 assert_eq!(
8517 reserved_error.close_reason(),
8518 Some(&RouteEndReason::ClosedByCaller)
8519 );
8520 assert_eq!(reserved_error.to_string(), ordinary_error.to_string());
8521 assert_eq!(reserved_error.close_reason(), ordinary_error.close_reason());
8522
8523 rx.close();
8524 let writer = InstrumentedWriter::new(false);
8525 writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8526 let bytes = writer.bytes();
8527 let mut bytes = bytes.as_slice();
8528 let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8529 assert_eq!(frame.header.ty, FrameType::Goodbye);
8530 assert!(
8531 bytes.is_empty(),
8532 "the closed route's reserved request must not be written"
8533 );
8534 consumer.close().await;
8535 }
8536
8537 #[tokio::test]
8538 async fn reservation_connection_loss_after_send_preserves_existing_errors() {
8539 for written in [false, true] {
8540 let (shared, consumer, rx, handle, sem) = reservation_stand_in(1, 1);
8541 let reserved = consumer
8542 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8543 .await
8544 .unwrap();
8545 let (_, reply) = reserved.send(
8546 RequestBody::new(b"request".to_vec()).unwrap(),
8547 CallOptions::default(),
8548 );
8549 let writer = InstrumentedWriter::new(written);
8550 if !written {
8551 shared.handle_generation_drop(1, "connection lost before dequeue".to_string());
8552 }
8553 writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8554 let err = reply.await.unwrap_err();
8555 assert_eq!(err.close_reason(), Some(&RouteEndReason::ConnectionLost));
8556 if written {
8557 assert_eq!(err.outcome_cause(), Some(OutcomeUnknownCause::WriterClosed));
8561 assert!(!writer.bytes().is_empty());
8562 } else {
8563 assert!(matches!(err, CallError::NotSent(_)));
8564 assert!(writer.bytes().is_empty());
8565 }
8566 assert_eq!(sem.available_permits(), 1);
8567 consumer.close().await;
8568 }
8569 }
8570
8571 #[tokio::test]
8572 async fn reservation_correlations_are_unique_and_match_frames_written_out_of_order() {
8573 let (shared, consumer, mut rx, handle, _) = reservation_stand_in(3, 3);
8574 let deadline = Instant::now() + Duration::from_secs(1);
8575 let first = consumer.reserve(&handle, deadline).await.unwrap();
8576 let second = consumer.reserve(&handle, deadline).await.unwrap();
8577 let third = consumer.reserve(&handle, deadline).await.unwrap();
8578 let ids = [
8579 first.correlation_id(),
8580 second.correlation_id(),
8581 third.correlation_id(),
8582 ];
8583 assert_eq!(ids.into_iter().collect::<HashSet<_>>().len(), 3);
8584 let opts = CallOptions {
8585 priority: Priority::Background,
8586 admission_class: AdmissionClass::Expedite,
8587 ..CallOptions::default()
8588 };
8589 let mut replies = Vec::new();
8590 for (reserved, expected_id, body) in [
8591 (third, ids[2], "third"),
8592 (first, ids[0], "first"),
8593 (second, ids[1], "second"),
8594 ] {
8595 let (corr, reply) = reserved.send(
8596 RequestBody::new(body.as_bytes().to_vec()).unwrap(),
8597 opts.clone(),
8598 );
8599 assert_eq!(corr, expected_id);
8600 replies.push((corr, body, reply));
8601 }
8602 rx.close();
8603 let writer = InstrumentedWriter::new(false);
8604 writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8605 let bytes = writer.bytes();
8606 let mut bytes = bytes.as_slice();
8607 for (corr, body, reply) in replies {
8608 let frame = read_frame(&mut bytes).await.unwrap().unwrap();
8609 assert_eq!(frame.header.ty, FrameType::Request);
8610 assert_eq!(frame.header.corr, corr);
8611 assert_eq!(frame.header.channel, handle.channel);
8612 assert_eq!(frame.header.epoch, handle.epoch);
8613 assert_eq!(
8614 frame.header.flags,
8615 Flags::new(false, Priority::Background, false)
8616 .with_admission_class(AdmissionClass::Expedite)
8617 );
8618 assert_eq!(frame.body, body.as_bytes());
8619 dispatch_frame(
8620 &shared,
8621 1,
8622 response_frame(handle.channel, handle.epoch, corr, body.as_bytes().to_vec()),
8623 )
8624 .await;
8625 assert_eq!(reply.await.unwrap(), body.as_bytes());
8626 }
8627 assert!(bytes.is_empty());
8628 consumer.close().await;
8629 }
8630
8631 #[tokio::test(start_paused = true)]
8632 async fn reservation_deadline_before_send_prevents_writing_without_polling_reply() {
8633 let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8634 let reserved = consumer
8635 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8636 .await
8637 .unwrap();
8638 tokio::time::advance(Duration::from_secs(2)).await;
8639 let (_, reply) = reserved.send(
8640 RequestBody::new(b"expired".to_vec()).unwrap(),
8641 CallOptions::default(),
8642 );
8643 rx.close();
8644 let writer = InstrumentedWriter::new(false);
8645 writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8646 assert!(writer.bytes().is_empty());
8647 assert!(matches!(reply.await, Err(CallError::NotSent(_))));
8648 assert_eq!(sem.available_permits(), 1);
8649 consumer.close().await;
8650 }
8651
8652 #[tokio::test(start_paused = true)]
8653 async fn reservation_deadline_bounds_writer_capacity_and_releases_credit() {
8654 let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(2, 1);
8655 let first = consumer
8656 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8657 .await
8658 .unwrap();
8659 let second = consumer
8660 .reserve(&handle, Instant::now() + Duration::from_millis(25))
8661 .await;
8662 assert!(matches!(second, Err(CallError::NotSent(_))));
8663 assert_eq!(sem.available_permits(), 1);
8664 drop(first);
8665 assert_eq!(sem.available_permits(), 2);
8666 assert!(shared.lock_inner().pending.is_empty());
8667 assert!(rx.try_recv().is_err());
8668 consumer.close().await;
8669 }
8670
8671 #[tokio::test]
8672 async fn reservation_reconnect_during_writer_capacity_wait_fails_promptly_without_writing() {
8673 let (shared, consumer, mut old_rx, handle, sem) = reservation_stand_in(1, 1);
8674 let old_writer = shared.lock_inner().writer.clone().unwrap();
8675 let held_capacity = old_writer.reserve_owned().await.unwrap();
8676 let reserve = consumer.reserve(&handle, Instant::now() + Duration::from_secs(60));
8677 tokio::pin!(reserve);
8678 assert_pending(reserve.as_mut()).await;
8679 assert_eq!(sem.available_permits(), 0);
8680
8681 let mut replacement_rx = drop_and_replace_test_transport(&shared);
8682 assert_ne!(shared.lock_inner().generation, handle.connection_token());
8683 drop(held_capacity);
8684 let result = std::future::poll_fn(|cx| Poll::Ready(reserve.as_mut().poll(cx))).await;
8685 assert!(matches!(
8686 result,
8687 Poll::Ready(Err(CallError::StaleRouteHandle(stale))) if stale == handle
8688 ));
8689 assert!(shared.lock_inner().pending.is_empty());
8690 assert_eq!(sem.available_permits(), 1);
8691 assert!(old_rx.try_recv().is_err());
8692 assert!(replacement_rx.try_recv().is_err());
8693
8694 old_rx.close();
8695 replacement_rx.close();
8696 let writer = InstrumentedWriter::new(false);
8697 writer_loop(
8698 Arc::clone(&shared),
8699 writer.clone(),
8700 old_rx,
8701 handle.connection_token(),
8702 )
8703 .await;
8704 let generation = shared.lock_inner().generation;
8705 writer_loop(
8706 Arc::clone(&shared),
8707 writer.clone(),
8708 replacement_rx,
8709 generation,
8710 )
8711 .await;
8712 assert!(writer.bytes().is_empty());
8713 consumer.close().await;
8714 }
8715
8716 #[tokio::test]
8717 async fn reservation_reply_drop_cleans_up_without_polling() {
8718 let (shared, consumer, mut rx, handle, sem) = reservation_stand_in(1, 1);
8719 let reserved = consumer
8720 .reserve(&handle, Instant::now() + Duration::from_secs(1))
8721 .await
8722 .unwrap();
8723 let (_, reply) = reserved.send(
8724 RequestBody::new(b"request".to_vec()).unwrap(),
8725 CallOptions::default(),
8726 );
8727 drop(reply);
8728 assert!(shared.lock_inner().pending.is_empty());
8729 assert_eq!(sem.available_permits(), 1);
8730 rx.close();
8731 let writer = InstrumentedWriter::new(false);
8732 writer_loop(Arc::clone(&shared), writer.clone(), rx, 1).await;
8733 assert!(writer.bytes().is_empty());
8734 consumer.close().await;
8735 }
8736
8737 #[tokio::test]
8738 async fn writer_batches_ready_frames_into_one_flush() {
8739 const FRAME_COUNT: usize = 8;
8740
8741 let shared = writer_test_shared();
8742 let (live_writer, _live_rx) = mpsc::channel(1);
8743 let (tx, rx) = mpsc::channel(FRAME_COUNT + 1);
8744 let instrumented = InstrumentedWriter::new(false);
8745 let observer = instrumented.clone();
8746 let mut expected = Vec::with_capacity(FRAME_COUNT);
8747 let mut keys = Vec::with_capacity(FRAME_COUNT);
8748
8749 {
8750 let mut inner = shared.lock_inner();
8751 inner.writer = Some(live_writer);
8752 inner.daemon_ver = "0.39.0".into();
8753 for index in 0..FRAME_COUNT {
8754 let corr = index as u64 + 1;
8755 let frame = response_frame(7, 1, corr, vec![index as u8; index + 1]);
8756 let key = PendingKey {
8757 generation: 1,
8758 channel: 7,
8759 epoch: 1,
8760 corr,
8761 };
8762 let (pending_tx, _pending_rx) = oneshot::channel();
8763 inner
8764 .pending
8765 .insert(key, PendingEntry::unary(pending_tx, false, None, None));
8766 expected.push(frame.clone());
8767 keys.push(key);
8768 tx.try_send(WriteCommand {
8769 frame,
8770 pending: Some(key),
8771 })
8772 .expect("the burst should fit in the writer queue");
8773 if index == 0 {
8774 tx.try_send(WriteCommand {
8775 frame: response_frame(7, 1, 999, b"skip".to_vec()),
8776 pending: Some(PendingKey {
8777 generation: 1,
8778 channel: 7,
8779 epoch: 1,
8780 corr: 999,
8781 }),
8782 })
8783 .expect("the skipped command should fit in the writer queue");
8784 }
8785 }
8786 }
8787 drop(tx);
8788
8789 writer_loop(Arc::clone(&shared), instrumented, rx, 1).await;
8790
8791 {
8792 let inner = shared.lock_inner();
8793 for key in keys {
8794 assert!(
8795 inner.pending.get(&key).is_some_and(|entry| entry.accepted),
8796 "every written command must be marked accepted"
8797 );
8798 }
8799 }
8800
8801 let mut wire = std::io::Cursor::new(observer.bytes());
8802 for expected_frame in expected {
8803 let actual = read_frame(&mut wire)
8804 .await
8805 .expect("the emitted frame should decode")
8806 .expect("the emitted frame should be present");
8807 assert_eq!(actual, expected_frame);
8808 }
8809 assert!(
8810 read_frame(&mut wire)
8811 .await
8812 .expect("the end of the emitted burst should be clean")
8813 .is_none(),
8814 "the writer must not emit extra frames"
8815 );
8816
8817 let flush_count = observer.flush_count();
8818 assert_eq!(
8819 flush_count, 1,
8820 "a ready burst must be coalesced into one flush"
8821 );
8822 shared.close_sync("test complete");
8823 }
8824
8825 #[tokio::test]
8826 async fn writer_flush_failure_drops_generation_and_preserves_acceptance_classification() {
8827 let shared = writer_test_shared();
8828 let (live_writer, _live_rx) = mpsc::channel(1);
8829 let accepted_key = PendingKey {
8830 generation: 1,
8831 channel: 3,
8832 epoch: 1,
8833 corr: 1,
8834 };
8835 let not_sent_key = PendingKey {
8836 corr: 2,
8837 ..accepted_key
8838 };
8839 let (accepted_tx, accepted_rx) = oneshot::channel();
8840 let (not_sent_tx, not_sent_rx) = oneshot::channel();
8841 {
8842 let mut inner = shared.lock_inner();
8843 inner.writer = Some(live_writer);
8844 inner.daemon_ver = "0.39.0".into();
8845 inner.pending.insert(
8846 accepted_key,
8847 PendingEntry::unary(accepted_tx, false, None, None),
8848 );
8849 inner.pending.insert(
8850 not_sent_key,
8851 PendingEntry::unary(not_sent_tx, false, None, None),
8852 );
8853 }
8854
8855 let (tx, rx) = mpsc::channel(1);
8856 tx.send(WriteCommand {
8857 frame: response_frame(3, 1, accepted_key.corr, b"accepted".to_vec()),
8858 pending: Some(accepted_key),
8859 })
8860 .await
8861 .unwrap();
8862 drop(tx);
8863
8864 writer_loop(Arc::clone(&shared), InstrumentedWriter::new(true), rx, 1).await;
8865
8866 assert!(
8867 shared.lock_inner().writer.is_none(),
8868 "a flush failure must drop the active generation"
8869 );
8870 let accepted_error = accepted_rx
8871 .await
8872 .expect("the accepted request should be settled")
8873 .into_call_result()
8874 .unwrap_err();
8875 assert!(matches!(accepted_error, CallError::OutcomeUnknown(_)));
8876 assert_eq!(
8877 accepted_error.outcome_cause(),
8878 Some(OutcomeUnknownCause::WriterClosed)
8879 );
8880 let not_sent_error = not_sent_rx
8881 .await
8882 .expect("the unwritten request should be settled")
8883 .into_call_result()
8884 .unwrap_err();
8885 assert!(matches!(not_sent_error, CallError::NotSent(_)));
8886 assert_eq!(not_sent_error.outcome_cause(), None);
8887 shared.close_sync("test complete");
8888 }
8889
8890 #[tokio::test]
8891 async fn consumer_close_attaches_outcome_cause_to_pending_call() {
8892 let shared = writer_test_shared();
8893 let (writer, _writer_rx) = mpsc::channel(1);
8894 shared.lock_inner().writer = Some(writer);
8895 shared.lock_inner().daemon_ver = "0.39.0".into();
8896 let (tx, rx) = oneshot::channel();
8897 let mut entry = PendingEntry::unary(tx, false, None, None);
8898 entry.accepted = true;
8899 shared.lock_inner().pending.insert(
8900 PendingKey {
8901 generation: 1,
8902 channel: 3,
8903 epoch: 1,
8904 corr: 1,
8905 },
8906 entry,
8907 );
8908 let consumer = SubcConsumer { shared };
8909 consumer.close().await;
8910 let err = rx.await.unwrap().into_call_result().unwrap_err();
8911 assert_eq!(
8912 err.outcome_cause(),
8913 Some(OutcomeUnknownCause::ConsumerClosed)
8914 );
8915 assert_eq!(err.to_string(), "request outcome unknown: consumer closed");
8916 assert_eq!(err.close_reason(), None);
8917 }
8918
8919 #[tokio::test]
8920 async fn subscription_completion_drop_attaches_outcome_cause() {
8921 let (tx, rx) = oneshot::channel();
8922 let closed = SubscriptionClosed { rx };
8923 drop(tx);
8924 let err = closed.await.unwrap_err();
8925 assert_eq!(
8926 err.outcome_cause(),
8927 Some(OutcomeUnknownCause::CompletionFailed)
8928 );
8929 assert_eq!(
8930 err.to_string(),
8931 "request outcome unknown: subscription closed result channel dropped"
8932 );
8933 }
8934
8935 #[test]
8936 fn reconnect_classifier_treats_auth_failure_as_transient() {
8937 let auth = ConsumerError::Auth {
8943 path: PathBuf::from("/tmp/subc-connection.json"),
8944 endpoint: "127.0.0.1:8757".to_string(),
8945 source: subc_transport::AuthError::InvalidServerProof,
8946 };
8947 assert!(is_reconnect_transient(&auth), "rotation race must retry");
8948
8949 let absent = ConsumerError::ConnectionFile {
8951 path: PathBuf::from("/tmp/subc-connection.json"),
8952 source: ConnectionFileError::Io {
8953 op: "read",
8954 path: PathBuf::from("/tmp/subc-connection.json"),
8955 source: io::Error::new(io::ErrorKind::NotFound, "gone"),
8956 },
8957 };
8958 assert!(is_reconnect_transient(&absent));
8959 }
8960
8961 #[tokio::test]
8962 async fn newer_drop_supersedes_reconnect_and_ignores_stale_completion() {
8963 let shared = Arc::new(reader_skew_tests::legacy_shared(
8964 PathBuf::from("/tmp/does-not-exist"),
8965 ConsumerOptions::default(),
8966 ));
8967 let stale_task = tokio::spawn(std::future::pending::<()>());
8968 {
8969 let mut inner = shared.lock_inner();
8970 inner.generation = 2;
8971 inner.reconnect = ReconnectState::Background {
8972 generation: 1,
8973 task: stale_task,
8974 };
8975 }
8976
8977 assert!(shared.spawn_reconnect(2));
8978 assert!(matches!(
8979 &shared.lock_inner().reconnect,
8980 ReconnectState::Background { generation, .. } if *generation == 2
8981 ));
8982
8983 shared.finish_background_reconnect(1);
8984 assert!(matches!(
8985 &shared.lock_inner().reconnect,
8986 ReconnectState::Background { generation, .. } if *generation == 2
8987 ));
8988 shared.close_sync("test complete");
8989 }
8990
8991 #[test]
8992 fn retryable_route_open_codes_are_code_specific() {
8993 for code in [
8994 "module_reloading",
8995 "module_warming",
8996 "target_unavailable",
8997 "module_timeout",
8998 ] {
8999 assert!(is_retryable_route_open_code(code), "{code} should retry");
9000 }
9001 assert!(
9006 !is_retryable_route_open_code(error_codes::UNKNOWN_MODULE),
9007 "unknown_module is terminal"
9008 );
9009 assert!(!is_retryable_route_open_code(error_codes::MODULE_REMOVED));
9010 assert!(!is_retryable_route_open_code("invalid_project_root"));
9011 assert!(!is_retryable_route_open_code("route_rejected"));
9012 assert!(
9013 !is_retryable_route_open_code("capability_forbidden"),
9014 "a capability policy refusal must not enter the route.open retry set"
9015 );
9016 }
9017
9018 #[test]
9019 fn two_routes_record_distinct_reasons_and_reuse_clears_channel() {
9020 let shared = Arc::new(reader_skew_tests::legacy_shared(
9021 PathBuf::new(),
9022 ConsumerOptions::default(),
9023 ));
9024 let (writer, _rx) = mpsc::channel(8);
9025 shared.lock_inner().writer = Some(writer);
9026 shared.lock_inner().daemon_ver = "0.39.0".into();
9027 shared.install_ingress_handle(RouteHandle::new(7, 1, 1));
9028 shared.install_ingress_handle(RouteHandle::new(9, 1, 1));
9029 {
9030 let mut inner = shared.lock_inner();
9031 inner.route_modules.insert(7, "provider".into());
9032 inner.route_modules.insert(9, "provider".into());
9033 }
9034 shared.control_push(br#"{"op":"route.closed","module_id":"provider","channels":[7],"reason":"scope_ended"}"#);
9035 shared.control_push(
9036 br#"{"op":"route.closing","module_id":"provider","channels":[9],"reason":"restart"}"#,
9037 );
9038 shared.control_push(
9039 br#"{"op":"route.closing","module_id":"provider","channels":[7],"reason":"crash"}"#,
9040 );
9041 assert_eq!(
9042 shared.lock_inner().route_end_reason(7),
9043 RouteEndReason::Daemon(RouteCloseReason::ScopeEnded)
9044 );
9045 assert_eq!(
9046 shared.lock_inner().route_end_reason(9),
9047 RouteEndReason::Daemon(RouteCloseReason::Restart)
9048 );
9049 shared.control_push(
9050 br#"{"op":"route.closed","module_id":"provider","channels":[9],"reason":"crash"}"#,
9051 );
9052 assert_eq!(
9053 shared.lock_inner().route_end_reason(9),
9054 RouteEndReason::Daemon(RouteCloseReason::Crash)
9055 );
9056 shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"disable"}"#);
9057 shared.install_ingress_handle(RouteHandle::new(7, 2, 1));
9058 assert_eq!(
9059 shared.lock_inner().route_end_reason(7),
9060 RouteEndReason::Unknown
9061 );
9062 assert_eq!(shared.lock_inner().route_end(7).terminal, None);
9063 }
9064
9065 #[test]
9066 fn legacy_route_push_falls_back_only_when_channels_are_absent() {
9067 let shared = reader_skew_tests::legacy_shared(PathBuf::new(), ConsumerOptions::default());
9068 shared
9069 .lock_inner()
9070 .route_modules
9071 .insert(7, "provider".into());
9072 shared.control_push(
9073 br#"{"op":"route.closed","module_id":"provider","channels":[],"reason":"crash"}"#,
9074 );
9075 assert_eq!(
9076 shared.lock_inner().route_end_reason(7),
9077 RouteEndReason::Unknown
9078 );
9079 shared.control_push(br#"{"op":"route.closing","module_id":"provider","reason":"restart"}"#);
9080 assert_eq!(
9081 shared.lock_inner().route_end_reason(7),
9082 RouteEndReason::Daemon(RouteCloseReason::Restart)
9083 );
9084 shared.control_push(br#"{"op":"route.closed","module_id":"provider","reason":"crash"}"#);
9085 assert_eq!(
9086 shared.lock_inner().route_end_reason(7),
9087 RouteEndReason::Daemon(RouteCloseReason::Crash)
9088 );
9089 }
9090
9091 #[tokio::test]
9092 async fn sdk_teardown_paths_attach_caller_and_connection_loss_reasons() {
9093 for local in [true, false] {
9094 let shared = Arc::new(reader_skew_tests::legacy_shared(
9095 PathBuf::new(),
9096 ConsumerOptions::default(),
9097 ));
9098 let (writer, _writer_rx) = mpsc::channel(8);
9099 shared.lock_inner().writer = Some(writer);
9100 shared.lock_inner().daemon_ver = "0.39.0".into();
9101 let handle = RouteHandle::new(7, 1, 1);
9102 shared.install_ingress_handle(handle);
9103 let (tx, rx) = oneshot::channel();
9104 let mut entry = PendingEntry::unary(tx, false, None, None);
9105 entry.accepted = true;
9106 shared.lock_inner().pending.insert(
9107 PendingKey {
9108 generation: 1,
9109 channel: 7,
9110 epoch: 1,
9111 corr: 1,
9112 },
9113 entry,
9114 );
9115 if local {
9116 shared
9117 .close_handle(handle, &CloseRouteOptions::default())
9118 .await
9119 .unwrap();
9120 } else {
9121 shared.handle_generation_drop(1, "connection gone".into());
9122 }
9123 let err = rx.await.unwrap().into_call_result().err().unwrap();
9124 assert!(matches!(err, CallError::OutcomeUnknown(_)));
9125 assert_eq!(
9126 err.outcome_cause(),
9127 Some(if local {
9128 OutcomeUnknownCause::RouteEnded
9129 } else {
9130 OutcomeUnknownCause::ConnectionFailed
9131 })
9132 );
9133 let shared_failure = SharedCallFailure::from(err);
9134 let err = shared_failure.into_call_error();
9135 assert_eq!(
9136 err.close_reason(),
9137 Some(&if local {
9138 RouteEndReason::ClosedByCaller
9139 } else {
9140 RouteEndReason::ConnectionLost
9141 })
9142 );
9143 shared.close_sync("test complete");
9144 }
9145 }
9146
9147 #[tokio::test]
9148 async fn route_end_reasons_preserve_pending_retry_classes() {
9149 for reason in [
9150 RouteEndReason::ClosedByCaller,
9151 RouteEndReason::ConnectionLost,
9152 RouteEndReason::Daemon(RouteCloseReason::ScopeEnded),
9153 RouteEndReason::Unknown,
9154 ] {
9155 for accepted in [false, true] {
9156 let (tx, rx) = oneshot::channel();
9157 let mut entry = PendingEntry::unary(tx, false, None, None);
9158 entry.accepted = accepted;
9159 settle_route_pending_entries(vec![entry], "route ended".into(), reason.clone());
9160 let err = rx.await.unwrap().into_call_result().err().unwrap();
9161 assert_eq!(err.close_reason(), Some(&reason));
9162 assert_eq!(err.terminal(), None);
9163 assert_eq!(matches!(err, CallError::OutcomeUnknown(_)), accepted);
9164 assert_eq!(matches!(err, CallError::NotSent(_)), !accepted);
9165 }
9166 }
9167 }
9168
9169 #[test]
9170 fn route_closing_does_not_supply_or_overwrite_a_terminal_verdict() {
9171 let shared = Shared::new(PathBuf::new(), ConsumerOptions::default());
9172 shared.control_push(
9173 br#"{"op":"route.closing","channels":[7],"reason":"restart","terminal":true}"#,
9174 );
9175 assert_eq!(shared.lock_inner().route_end(7).terminal, None);
9176 shared.control_push(
9177 br#"{"op":"route.closed","channels":[7],"reason":"restart","terminal":false}"#,
9178 );
9179 shared.control_push(
9180 br#"{"op":"route.closing","channels":[7],"reason":"restart","terminal":true}"#,
9181 );
9182 assert_eq!(shared.lock_inner().route_end(7).terminal, Some(false));
9183 assert_eq!(CallError::not_sent("not a route end").terminal(), None);
9184 }
9185
9186 #[test]
9187 fn route_close_reason_classifier_accepts_capability_denied_and_fails_closed_for_unknown() {
9188 assert_eq!(
9189 RouteCloseReason::from_wire("capability_denied"),
9190 RouteCloseReason::CapabilityDenied
9191 );
9192 assert_eq!(
9193 RouteCloseReason::from_wire("capability_denied").disposition(),
9194 RouteCloseDisposition::MustNotReopen
9195 );
9196 assert_eq!(
9197 RouteCloseReason::from_wire("future_policy_reason").disposition(),
9198 RouteCloseDisposition::MustNotReopen,
9199 "an unknown close reason must receive the strictest handling"
9200 );
9201 assert_eq!(
9202 RouteCloseReason::from_wire("reload").disposition(),
9203 RouteCloseDisposition::MayReopen,
9204 "control proves the classifier can distinguish a conservative default"
9205 );
9206 }
9207
9208 #[tokio::test]
9209 async fn module_removed_fails_fast_while_module_reloading_retries_at_the_same_route_open_call_site(
9210 ) {
9211 async fn reject_route_open_attempts(code: &str, deadline: Duration) -> (usize, CallError) {
9218 let shared = Arc::new(reader_skew_tests::legacy_shared(
9219 PathBuf::from("/tmp/does-not-exist"),
9220 ConsumerOptions::default(),
9221 ));
9222 let (writer, mut receiver) = mpsc::channel(4);
9223 {
9224 let mut inner = shared.lock_inner();
9225 inner.writer = Some(writer);
9226 inner.daemon_ver = "0.39.0".into();
9227 }
9228 let consumer = SubcConsumer {
9229 shared: Arc::clone(&shared),
9230 };
9231 let target = RouteTarget::ToolProvider {
9232 module_id: "retry-polarity".to_string(),
9233 };
9234 let identity = BindIdentity::new("test".to_string(), code.to_string());
9235 let options = CallOptions {
9236 timeout: Duration::from_secs(2),
9237 route_retry: RetryBackoff {
9238 base: Duration::ZERO,
9239 cap: Duration::ZERO,
9240 max_attempts: 2,
9241 },
9242 route_retry_deadline: deadline,
9243 ..CallOptions::default()
9244 };
9245 let mut task =
9246 tokio::spawn(async move { consumer.open_route(target, identity, options).await });
9247
9248 let mut attempts = 0usize;
9249 let result = loop {
9250 tokio::select! {
9251 command = receiver.recv() => {
9252 let Some(command) = command else {
9257 break task.await.unwrap().expect_err("route.open must reject");
9258 };
9259 attempts += 1;
9260 let body =
9261 serde_json::to_vec(&ErrorBody::new(code, "test rejection")).unwrap();
9262 assert!(
9263 dispatch_frame(
9264 &shared,
9265 1,
9266 Frame::build(
9267 FrameType::Error,
9268 Flags::new(false, Priority::Interactive, false),
9269 0,
9270 0,
9271 command.frame.header.corr,
9272 body,
9273 )
9274 .unwrap(),
9275 )
9276 .await
9277 );
9278 }
9279 joined = &mut task => {
9280 break joined.unwrap().expect_err("route.open must reject");
9281 }
9282 }
9283 };
9284 assert!(
9285 receiver.try_recv().is_err(),
9286 "a settled route.open must not queue another attempt"
9287 );
9288 (attempts, result)
9289 }
9290
9291 let (reloading_attempts, reloading) =
9292 reject_route_open_attempts(error_codes::MODULE_RELOADING, Duration::from_millis(150))
9293 .await;
9294 assert!(matches!(reloading, CallError::NotSent(_)));
9295 assert!(
9296 reloading_attempts > 2,
9297 "reloading retries must run until the deadline, not an attempt cap \
9298 (served {reloading_attempts} attempts against max_attempts=2)"
9299 );
9300
9301 let (removed_attempts, removed) =
9302 reject_route_open_attempts(error_codes::MODULE_REMOVED, Duration::from_millis(150))
9303 .await;
9304 assert!(matches!(removed, CallError::NotSent(_)));
9305 assert_eq!(
9306 removed_attempts, 1,
9307 "terminal codes settle on the first answer"
9308 );
9309 }
9310
9311 fn seeded_random(seed: u64) -> Box<dyn Fn() -> f64 + Send + Sync> {
9314 let state = AtomicU64::new(seed);
9315 Box::new(move || {
9316 let mut z = state
9317 .fetch_add(0x9E37_79B9_7F4A_7C15, Ordering::Relaxed)
9318 .wrapping_add(0x9E37_79B9_7F4A_7C15);
9319 z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
9320 z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
9321 z ^= z >> 31;
9322 (z >> 11) as f64 / (1u64 << 53) as f64
9323 })
9324 }
9325
9326 fn route_open_stand_in(
9329 random_unit: Box<dyn Fn() -> f64 + Send + Sync>,
9330 ) -> (Arc<Shared>, Arc<SubcConsumer>, mpsc::Receiver<WriteCommand>) {
9331 let mut shared = reader_skew_tests::legacy_shared(
9332 PathBuf::from("/tmp/does-not-exist"),
9333 ConsumerOptions::default(),
9334 );
9335 shared.random_unit = random_unit;
9336 let shared = Arc::new(shared);
9337 let (writer, receiver) = mpsc::channel(64);
9338 shared.lock_inner().writer = Some(writer);
9339 shared.lock_inner().daemon_ver = "0.39.0".into();
9340 let consumer = Arc::new(SubcConsumer {
9341 shared: Arc::clone(&shared),
9342 });
9343 (shared, consumer, receiver)
9344 }
9345
9346 fn restart_target(module_id: &str) -> RouteTarget {
9347 RouteTarget::ToolProvider {
9348 module_id: module_id.to_string(),
9349 }
9350 }
9351
9352 fn restart_identity() -> BindIdentity {
9353 BindIdentity::new("test".to_string(), "restart".to_string())
9354 }
9355
9356 fn route_open_answer(corr: u64, channel: u16, refusal: Option<ErrorBody>) -> Frame {
9359 match refusal {
9360 None => response_frame(
9361 0,
9362 0,
9363 corr,
9364 serde_json::to_vec(&ClientControlResponse::RouteOpen {
9365 request_window: None,
9366 watch_window: None,
9367 route_channel: channel,
9368 route_epoch: 1,
9369 })
9370 .unwrap(),
9371 ),
9372 Some(body) => Frame::build(
9373 FrameType::Error,
9374 Flags::new(false, Priority::Interactive, false),
9375 0,
9376 0,
9377 corr,
9378 serde_json::to_vec(&body).unwrap(),
9379 )
9380 .unwrap(),
9381 }
9382 }
9383
9384 async fn answer_route_opens<T>(
9387 shared: &Arc<Shared>,
9388 receiver: &mut mpsc::Receiver<WriteCommand>,
9389 task: &mut JoinHandle<T>,
9390 mut answer: impl FnMut(&str) -> Option<ErrorBody>,
9391 ) -> T {
9392 let mut next_channel = 40u16;
9393 loop {
9394 tokio::select! {
9395 command = receiver.recv() => {
9396 let Some(command) = command else {
9397 return (&mut *task).await.unwrap();
9398 };
9399 let request: serde_json::Value =
9400 serde_json::from_slice(&command.frame.body).unwrap();
9401 let module_id = request["target"]["module_id"].as_str().unwrap().to_string();
9402 next_channel += 1;
9403 let frame = route_open_answer(
9404 command.frame.header.corr,
9405 next_channel,
9406 answer(&module_id),
9407 );
9408 assert!(dispatch_frame(shared, 1, frame).await);
9409 }
9410 joined = &mut *task => return joined.unwrap(),
9411 }
9412 }
9413 }
9414
9415 fn reloading() -> ErrorBody {
9416 ErrorBody::new(error_codes::MODULE_RELOADING, "module is reloading")
9417 }
9418
9419 fn drain_call<'a>(
9420 consumer: &'a SubcConsumer,
9421 body: &'static [u8],
9422 ) -> impl Future<Output = Result<Vec<u8>, CallError>> + 'a {
9423 consumer.call(
9424 restart_target("plexus"),
9425 restart_identity(),
9426 body.to_vec(),
9427 CallOptions {
9428 timeout: Duration::from_secs(5),
9429 ..CallOptions::default()
9430 },
9431 )
9432 }
9433
9434 async fn refuse_during_drain(shared: &Arc<Shared>, request: &Frame) {
9435 let frame = Frame::build(
9436 FrameType::Error,
9437 request.header.flags,
9438 request.header.channel,
9439 request.header.epoch,
9440 request.header.corr,
9441 serde_json::to_vec(&reloading()).unwrap(),
9442 )
9443 .unwrap();
9444 assert!(dispatch_frame(shared, 1, frame).await);
9445 }
9446
9447 async fn reply_to_drain_call(shared: &Arc<Shared>, request: Frame) {
9448 assert_eq!(request.header.ty, FrameType::Request);
9449 assert!(
9450 dispatch_frame(
9451 shared,
9452 1,
9453 response_frame(
9454 request.header.channel,
9455 request.header.epoch,
9456 request.header.corr,
9457 request.body,
9458 ),
9459 )
9460 .await
9461 );
9462 }
9463
9464 #[tokio::test(start_paused = true)]
9465 async fn shared_route_drain_delivers_both_refusals_and_resends_both_calls() {
9466 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9467 let (_, old) = open_answered(
9468 &shared,
9469 &consumer,
9470 &mut receiver,
9471 None,
9472 41,
9473 "initial shared route",
9474 )
9475 .await;
9476 let mut seed = Box::pin(drain_call(&consumer, b"seed"));
9477 assert_pending(seed.as_mut()).await;
9478 reply_to_drain_call(&shared, receiver.recv().await.unwrap().frame).await;
9479 assert_eq!(seed.await.unwrap(), b"seed");
9480 shared.control_push(
9481 &serde_json::to_vec(&serde_json::json!({
9482 "op": "route.closing", "module_id": "plexus",
9483 "channels": [old.channel], "terminal": false
9484 }))
9485 .unwrap(),
9486 );
9487 let mut first = Box::pin(drain_call(&consumer, b"first"));
9488 let mut second = Box::pin(drain_call(&consumer, b"second"));
9489 assert_pending(first.as_mut()).await;
9490 assert_pending(second.as_mut()).await;
9491 let first_command = receiver.recv().await.unwrap();
9492 let second_command = receiver.recv().await.unwrap();
9493 assert!(shared.mark_pending_accepted(first_command.pending.unwrap()));
9495 assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9496 let first_request = first_command.frame;
9497 let second_request = second_command.frame;
9498 assert_eq!(first_request.header.channel, old.channel);
9499 assert_eq!(second_request.header.channel, old.channel);
9500
9501 refuse_during_drain(&shared, &first_request).await;
9502 assert_pending(first.as_mut()).await;
9503 let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9506 refuse_during_drain(&shared, &second_request).await;
9507 for (ty, channel, epoch, corr) in [
9508 (FrameType::Goodbye, old.channel, old.epoch, 0),
9509 (FrameType::Ping, 0, 0, 991),
9510 ] {
9511 let frame = Frame::build(
9512 ty,
9513 Flags::new(false, Priority::Interactive, false),
9514 channel,
9515 epoch,
9516 corr,
9517 Vec::new(),
9518 )
9519 .unwrap();
9520 assert!(dispatch_frame(&shared, 1, frame).await);
9521 }
9522 let pong = receiver.recv().await.unwrap().frame;
9525 assert_eq!(pong.header.ty, FrameType::Pong);
9526 assert_eq!(pong.header.corr, 991);
9527 assert_pending(second.as_mut()).await;
9528 assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9529 assert_pending(first.as_mut()).await;
9530 assert_pending(second.as_mut()).await;
9531 while let Ok(command) = receiver.try_recv() {
9532 assert_eq!(command.frame.header.channel, 42);
9533 reply_to_drain_call(&shared, command.frame).await;
9534 }
9535 assert_eq!(first.await.expect("first call resends"), b"first");
9536 assert_eq!(
9537 second.await.expect("second refusal must not time out"),
9538 b"second"
9539 );
9540 assert!(shared.lock_inner().pending.is_empty());
9541 }
9542
9543 #[tokio::test(start_paused = true)]
9544 async fn shared_route_drain_preserves_unrefused_reply_without_resending() {
9545 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9546 let (_, old) = open_answered(
9547 &shared,
9548 &consumer,
9549 &mut receiver,
9550 None,
9551 41,
9552 "initial shared route",
9553 )
9554 .await;
9555 let mut first = Box::pin(drain_call(&consumer, b"refused"));
9556 let mut second = Box::pin(drain_call(&consumer, b"executing"));
9557 assert_pending(first.as_mut()).await;
9558 assert_pending(second.as_mut()).await;
9559 let first_request = receiver.recv().await.unwrap().frame;
9560 let second_request = receiver.recv().await.unwrap().frame;
9561 let executing_corr = second_request.header.corr;
9562 assert_eq!(second_request.header.channel, old.channel);
9563 let mut executing_requests = 1;
9564
9565 refuse_during_drain(&shared, &first_request).await;
9566 assert_pending(first.as_mut()).await;
9567 let (open_corr, _) = next_route_open(&mut receiver, "replacement route barrier").await;
9568 assert_pending(second.as_mut()).await;
9569 assert!(dispatch_frame(&shared, 1, route_open_answer(open_corr, 42, None)).await);
9570 assert_pending(first.as_mut()).await;
9571 assert_pending(second.as_mut()).await;
9572 while let Ok(command) = receiver.try_recv() {
9573 assert_eq!(command.frame.header.ty, FrameType::Request);
9574 if command.frame.header.corr == executing_corr || command.frame.body == b"executing" {
9577 executing_requests += 1;
9578 }
9579 reply_to_drain_call(&shared, command.frame).await;
9580 }
9581 reply_to_drain_call(&shared, second_request).await;
9582 assert_eq!(first.await.expect("refused call resends"), b"refused");
9583 assert_eq!(
9584 second.await.expect("real old-route reply arrives"),
9585 b"executing"
9586 );
9587 assert_eq!(executing_requests, 1, "unrefused call must never resend");
9588 }
9589
9590 #[tokio::test(start_paused = true)]
9591 async fn invalidated_route_ingress_is_uninstalled_after_last_pending_settles() {
9592 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9593 let (_, old) = open_answered(
9594 &shared,
9595 &consumer,
9596 &mut receiver,
9597 None,
9598 41,
9599 "initial shared route",
9600 )
9601 .await;
9602 let mut first = Box::pin(drain_call(&consumer, b"first"));
9603 let mut second = Box::pin(drain_call(&consumer, b"second"));
9604 assert_pending(first.as_mut()).await;
9605 assert_pending(second.as_mut()).await;
9606 let first_request = receiver.recv().await.unwrap().frame;
9607 let second_request = receiver.recv().await.unwrap().frame;
9608 refuse_during_drain(&shared, &first_request).await;
9609 assert_pending(first.as_mut()).await;
9610 let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9611 assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9612 assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_ok());
9613 reply_to_drain_call(&shared, second_request).await;
9614 assert_eq!(second.await.unwrap(), b"second");
9615 assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9616 assert!(shared.lock_inner().retired_routes.is_empty());
9617 assert!(route_reverse_request_registry(old.reverse_request_registry_id()).is_err());
9618 drop(first);
9619 }
9620
9621 #[tokio::test(start_paused = true)]
9622 async fn invalidated_route_ingress_cleans_up_on_drop_deadline_goodbye_and_disconnect() {
9623 for ending in ["drop", "deadline", "goodbye", "disconnect"] {
9624 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9625 let (_, old) = open_answered(
9626 &shared,
9627 &consumer,
9628 &mut receiver,
9629 None,
9630 41,
9631 "initial shared route",
9632 )
9633 .await;
9634 let mut first = Box::pin(drain_call(&consumer, b"refused"));
9635 let mut second = Box::pin(drain_call(&consumer, b"executing"));
9636 assert_pending(first.as_mut()).await;
9637 assert_pending(second.as_mut()).await;
9638 let first_request = receiver.recv().await.unwrap().frame;
9639 let second_command = receiver.recv().await.unwrap();
9640 assert!(shared.mark_pending_accepted(second_command.pending.unwrap()));
9641 refuse_during_drain(&shared, &first_request).await;
9642 assert_pending(first.as_mut()).await;
9643 let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9644 match ending {
9645 "drop" => drop(second),
9646 "deadline" => {
9647 assert_eq!(
9648 second.await.unwrap_err().outcome_cause(),
9649 Some(OutcomeUnknownCause::Deadline)
9650 );
9651 }
9652 "goodbye" => {
9653 let frame = Frame::build(
9654 FrameType::Goodbye,
9655 Flags::new(false, Priority::Interactive, false),
9656 old.channel,
9657 old.epoch,
9658 0,
9659 Vec::new(),
9660 )
9661 .unwrap();
9662 assert!(dispatch_frame(&shared, 1, frame).await);
9663 assert_eq!(
9664 second.await.unwrap_err().outcome_cause(),
9665 Some(OutcomeUnknownCause::RouteEnded)
9666 );
9667 }
9668 "disconnect" => {
9669 shared.handle_generation_drop(1, "test disconnect".into());
9670 assert_eq!(
9671 second.await.unwrap_err().outcome_cause(),
9672 Some(OutcomeUnknownCause::ConnectionFailed)
9673 );
9674 }
9675 _ => unreachable!(),
9676 }
9677 assert_eq!(
9678 shared.ingress_handle(1, old.channel, old.epoch),
9679 None,
9680 "{ending}"
9681 );
9682 assert!(shared.lock_inner().retired_routes.is_empty(), "{ending}");
9683 assert!(
9684 route_reverse_request_registry(old.reverse_request_registry_id()).is_err(),
9685 "{ending}"
9686 );
9687 drop(first);
9688 }
9689 }
9690
9691 #[tokio::test(start_paused = true)]
9692 async fn invalidated_route_subscription_cancel_and_overflow_uninstall_ingress() {
9693 for overflow in [false, true] {
9694 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9695 let (_, old) = open_answered(
9696 &shared,
9697 &consumer,
9698 &mut receiver,
9699 None,
9700 41,
9701 "initial shared route",
9702 )
9703 .await;
9704 let mut subscription = consumer
9705 .subscribe_route(&old, b"watch".to_vec(), SubscribeOptions::default())
9706 .await
9707 .unwrap();
9708 let request = receiver.recv().await.unwrap().frame;
9709 let mut call = Box::pin(drain_call(&consumer, b"refused"));
9710 assert_pending(call.as_mut()).await;
9711 let refused = receiver.recv().await.unwrap().frame;
9712 refuse_during_drain(&shared, &refused).await;
9713 assert_pending(call.as_mut()).await;
9714 let _ = next_route_open(&mut receiver, "replacement route barrier").await;
9715 assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), Some(old));
9716 assert!(matches!(
9717 consumer
9718 .request(&old, b"new".to_vec(), CallOptions::default())
9719 .await,
9720 Err(CallError::StaleRouteHandle(_))
9721 ));
9722 if overflow {
9723 for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
9724 assert!(
9725 dispatch_frame(
9726 &shared,
9727 1,
9728 watch_terminal(&request, FrameType::StreamData, vec![1])
9729 )
9730 .await
9731 );
9732 }
9733 assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
9734 } else {
9735 subscription.unsubscribe().unwrap();
9736 assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
9737 }
9738 assert_eq!(
9739 receiver.recv().await.unwrap().frame.header.ty,
9740 FrameType::Cancel
9741 );
9742 assert_eq!(shared.ingress_handle(1, old.channel, old.epoch), None);
9743 assert!(shared.lock_inner().retired_routes.is_empty());
9744 drop(call);
9745 }
9746 }
9747
9748 #[tokio::test(start_paused = true)]
9749 async fn the_default_retry_deadline_outlasts_a_60s_restart_and_the_open_succeeds() {
9750 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(1));
9751 let started = Instant::now();
9752 let options = CallOptions {
9755 timeout: Duration::from_secs(120),
9756 ..CallOptions::default()
9757 };
9758 let mut task = tokio::spawn(async move {
9759 consumer
9760 .open_route(restart_target("restarting"), restart_identity(), options)
9761 .await
9762 });
9763 let opened = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9764 (started.elapsed() < Duration::from_secs(60)).then(reloading)
9765 })
9766 .await;
9767 let handle =
9768 opened.unwrap_or_else(|err| panic!("the open must survive the restart: {err}"));
9769 assert!(handle.channel > 40);
9770 assert!(started.elapsed() >= Duration::from_secs(60));
9771 }
9772
9773 #[tokio::test(start_paused = true)]
9774 async fn a_call_timeout_shorter_than_the_retry_deadline_ends_the_retries_at_the_call_timeout() {
9775 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(2));
9776 let started = Instant::now();
9777 let options = CallOptions {
9778 timeout: Duration::from_secs(10),
9779 ..CallOptions::default()
9780 };
9781 let mut task = tokio::spawn(async move {
9782 consumer
9783 .open_route(restart_target("restarting"), restart_identity(), options)
9784 .await
9785 });
9786 let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9787 (started.elapsed() < Duration::from_secs(60)).then(reloading)
9788 })
9789 .await
9790 .expect_err("the call timeout must end the retries before the module is back");
9791 let elapsed = started.elapsed();
9792 assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9793 assert!(
9794 elapsed >= Duration::from_secs(9) && elapsed <= Duration::from_secs(10),
9795 "the retries must stop at the 10s call timeout, stopped after {elapsed:?}"
9796 );
9797 }
9798
9799 #[tokio::test(start_paused = true)]
9800 async fn two_routes_refused_together_retry_at_different_jittered_times() {
9801 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(42));
9802 let started = Instant::now();
9803 let mut task = tokio::spawn(async move {
9804 let alpha = consumer.open_route(
9805 restart_target("alpha"),
9806 restart_identity(),
9807 CallOptions::default(),
9808 );
9809 let beta = consumer.open_route(
9810 restart_target("beta"),
9811 restart_identity(),
9812 CallOptions::default(),
9813 );
9814 let (alpha, beta) = tokio::join!(alpha, beta);
9815 (alpha.is_ok(), beta.is_ok())
9816 });
9817 let mut first_open = HashMap::<String, Duration>::new();
9818 let mut retried_at = HashMap::<String, Duration>::new();
9819 let opened = answer_route_opens(&shared, &mut receiver, &mut task, |module_id| {
9820 let at = started.elapsed();
9821 if first_open.contains_key(module_id) {
9822 retried_at.insert(module_id.to_string(), at);
9823 None
9824 } else {
9825 first_open.insert(module_id.to_string(), at);
9826 Some(reloading())
9827 }
9828 })
9829 .await;
9830 assert_eq!(opened, (true, true));
9831 assert_eq!(first_open["alpha"], first_open["beta"], "refused together");
9832 for at in retried_at.values() {
9834 assert!(
9835 *at >= Duration::from_millis(50) && *at <= Duration::from_millis(100),
9836 "retry at {at:?} is outside the jitter window"
9837 );
9838 }
9839 assert_ne!(
9840 retried_at["alpha"], retried_at["beta"],
9841 "routes refused together must not retry in lock step"
9842 );
9843 }
9844
9845 #[tokio::test(start_paused = true)]
9846 async fn twenty_concurrent_opens_never_have_more_than_eight_outstanding_at_the_daemon() {
9847 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(3));
9848 let mut task = tokio::spawn(async move {
9849 let mut opens = tokio::task::JoinSet::new();
9850 for i in 0..20 {
9851 let consumer = Arc::clone(&consumer);
9852 opens.spawn(async move {
9853 consumer
9854 .open_route(
9855 restart_target(&format!("module-{i}")),
9856 restart_identity(),
9857 CallOptions::default(),
9858 )
9859 .await
9860 });
9861 }
9862 let mut opened = 0usize;
9863 while let Some(result) = opens.join_next().await {
9864 result.unwrap().unwrap();
9865 opened += 1;
9866 }
9867 opened
9868 });
9869 let mut held = Vec::new();
9872 let mut max_outstanding = 0usize;
9873 let mut next_channel = 40u16;
9874 let opened = loop {
9875 tokio::select! {
9876 command = receiver.recv() => {
9877 let Some(command) = command else {
9880 break (&mut task).await.unwrap();
9881 };
9882 held.push(command.frame.header.corr);
9883 max_outstanding = max_outstanding.max(held.len());
9884 }
9885 () = sleep(Duration::from_millis(25)), if !held.is_empty() => {
9886 for corr in held.drain(..) {
9887 next_channel += 1;
9888 assert!(dispatch_frame(&shared, 1, route_open_answer(corr, next_channel, None)).await);
9889 }
9890 }
9891 joined = &mut task => break joined.unwrap(),
9892 }
9893 };
9894 assert_eq!(opened, 20);
9895 assert_eq!(max_outstanding, MAX_ROUTE_OPENS_IN_FLIGHT);
9896 }
9897
9898 #[tokio::test(start_paused = true)]
9899 async fn an_exhausted_deadline_names_module_reloading_not_the_later_admission_pressure() {
9900 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(4));
9901 let options = CallOptions {
9902 route_retry_deadline: Duration::from_secs(5),
9903 ..CallOptions::default()
9904 };
9905 let mut task = tokio::spawn(async move {
9906 consumer
9907 .open_route(restart_target("restarting"), restart_identity(), options)
9908 .await
9909 });
9910 let mut opens = 0usize;
9911 let err = answer_route_opens(&shared, &mut receiver, &mut task, |_| {
9912 opens += 1;
9913 Some(if opens <= 2 {
9914 reloading().with_detail(serde_json::json!({ "reason": "restart" }))
9915 } else {
9916 ErrorBody::new(
9917 error_codes::TARGET_UNAVAILABLE,
9918 "connection already has 8 route.open binds in flight (limit 8); retry after one settles",
9919 )
9920 })
9921 })
9922 .await
9923 .expect_err("the module never comes back");
9924 assert!(opens > 2);
9925 assert!(matches!(err, CallError::NotSent(_)), "got {err:?}");
9926 assert_eq!(
9927 err.route_open_refusal().map(|body| body.code.as_str()),
9928 Some(error_codes::MODULE_RELOADING)
9929 );
9930 let message = err.to_string();
9931 assert!(
9932 message.starts_with(
9933 "request not sent: route.open failed for target tool_provider:restarting: \
9934 module_reloading (reason restart) (module is reloading); \
9935 the most recent refusal was target_unavailable"
9936 ),
9937 "got {message}"
9938 );
9939 }
9940
9941 #[tokio::test]
9942 async fn close_route_flips_inflight_opening_so_a_racing_open_discards() {
9943 let shared = Arc::new(reader_skew_tests::legacy_shared(
9948 PathBuf::from("/tmp/does-not-exist"),
9949 ConsumerOptions::default(),
9950 ));
9951 let key = RouteKey::new(
9952 &RouteTarget::ToolProvider {
9953 module_id: "m".into(),
9954 },
9955 &BindIdentity::new("h", "s"),
9956 None,
9957 None,
9958 );
9959 shared.lock_inner().openings.insert(
9962 key.clone(),
9963 Opening {
9964 waiters: Vec::new(),
9965 closed: false,
9966 },
9967 );
9968
9969 shared
9972 .close_route(&key, &CloseRouteOptions::default())
9973 .await;
9974 assert!(
9975 shared
9976 .lock_inner()
9977 .openings
9978 .get(&key)
9979 .is_some_and(|o| o.closed),
9980 "close_route must flip the in-flight opening's closed flag (close-beats-reopen)"
9981 );
9982
9983 let absent = RouteKey::new(
9985 &RouteTarget::ToolProvider {
9986 module_id: "absent".into(),
9987 },
9988 &BindIdentity::new("h", "s"),
9989 None,
9990 None,
9991 );
9992 shared
9993 .close_route(&absent, &CloseRouteOptions::default())
9994 .await;
9995 }
9996
9997 #[test]
9998 fn route_key_is_structured() {
9999 let target = RouteTarget::InternalService {
10000 module_id: "a\0b".into(),
10001 service_id: "svc".into(),
10002 };
10003 let identity = BindIdentity::new("h", "s");
10004 let key = RouteKey::new(&target, &identity, None, None);
10005 assert!(matches!(key.target, RouteTargetKey::InternalService { .. }));
10006 }
10007
10008 async fn assert_pending(mut future: Pin<&mut (impl Future + ?Sized)>) {
10009 assert!(
10010 std::future::poll_fn(|cx| Poll::Ready(future.as_mut().poll(cx).is_pending())).await
10011 );
10012 }
10013
10014 fn drop_and_replace_test_transport(shared: &Arc<Shared>) -> mpsc::Receiver<WriteCommand> {
10016 let generation = shared.lock_inner().generation;
10017 shared.lock_inner().reconnect = ReconnectState::Inline { generation };
10019 shared.handle_generation_drop(generation, "test connection drop".into());
10020 let (writer, receiver) = mpsc::channel(64);
10021 let mut inner = shared.lock_inner();
10022 inner.generation += 1;
10023 inner.epoch += 1;
10024 inner.next_corr = Some(1);
10025 inner.writer = Some(writer);
10026 inner.daemon_ver = "0.39.0".into();
10027 inner.reconnect = ReconnectState::Idle;
10028 receiver
10029 }
10030
10031 #[tokio::test(start_paused = true)]
10032 async fn route_open_single_flight_survives_generation_drop_during_backoff() {
10033 let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10034 let opts = CallOptions::default();
10035 let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10036 tokio::pin!(opener);
10037 assert_pending(opener.as_mut()).await;
10038 let first = receiver.try_recv().unwrap();
10039 assert!(
10040 dispatch_frame(
10041 &shared,
10042 1,
10043 route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10044 )
10045 .await
10046 );
10047 assert_pending(opener.as_mut()).await;
10048
10049 let waiting = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10052 tokio::pin!(waiting);
10053 assert_pending(waiting.as_mut()).await;
10054 let mut receiver = drop_and_replace_test_transport(&shared);
10055 assert_pending(waiting.as_mut()).await;
10056 let arriving = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10057 tokio::pin!(arriving);
10058 assert_pending(arriving.as_mut()).await;
10059 assert!(
10060 receiver.try_recv().is_err(),
10061 "a second opener bypassed the backoff"
10062 );
10063
10064 tokio::time::advance(opts.route_retry.base).await;
10065 assert_pending(opener.as_mut()).await;
10066 let retry = receiver.try_recv().unwrap();
10067 assert!(
10068 dispatch_frame(
10069 &shared,
10070 2,
10071 route_open_answer(retry.frame.header.corr, 42, None),
10072 )
10073 .await
10074 );
10075 let handle = opener.await.unwrap();
10076 assert_eq!(waiting.await.unwrap(), handle);
10077 assert_eq!(arriving.await.unwrap(), handle);
10078 assert!(
10079 receiver.try_recv().is_err(),
10080 "more than one retry was emitted"
10081 );
10082 let inner = shared.lock_inner();
10083 assert!(inner.openings.is_empty());
10084 assert_eq!(inner.routes.len(), 1);
10085 assert_eq!(inner.route_epochs.len(), 1);
10086 }
10087
10088 #[tokio::test(start_paused = true)]
10089 async fn close_route_during_backoff_survives_generation_drop() {
10090 let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
10091 let opts = CallOptions::default();
10092 let opener = consumer.open_route(restart_target("m"), restart_identity(), opts.clone());
10093 tokio::pin!(opener);
10094 assert_pending(opener.as_mut()).await;
10095 let first = receiver.try_recv().unwrap();
10096 assert!(
10097 dispatch_frame(
10098 &shared,
10099 1,
10100 route_open_answer(first.frame.header.corr, 0, Some(reloading())),
10101 )
10102 .await
10103 );
10104 assert_pending(opener.as_mut()).await;
10105 consumer
10106 .close_route(
10107 restart_target("m"),
10108 restart_identity(),
10109 CloseRouteOptions::default(),
10110 )
10111 .await;
10112 let mut receiver = drop_and_replace_test_transport(&shared);
10113 tokio::time::advance(opts.route_retry.base).await;
10114 assert_pending(opener.as_mut()).await;
10115 let retry = receiver.try_recv().unwrap();
10116 assert!(
10117 dispatch_frame(
10118 &shared,
10119 2,
10120 route_open_answer(retry.frame.header.corr, 42, None),
10121 )
10122 .await
10123 );
10124 let err = opener.await.expect_err("close must win over the retry");
10125 assert!(matches!(err, CallError::NotSent(_)));
10126 let goodbye = receiver
10127 .try_recv()
10128 .expect("discarded route must get GOODBYE");
10129 assert_eq!(goodbye.frame.header.ty, FrameType::Goodbye);
10130 assert_eq!(goodbye.frame.header.channel, 42);
10131 assert!(receiver.try_recv().is_err());
10132 let inner = shared.lock_inner();
10133 assert!(inner.routes.is_empty());
10134 assert!(inner.route_epochs.is_empty());
10135 assert!(inner.openings.is_empty());
10136 }
10137
10138 fn route_teardown_stand_in() -> (
10139 Arc<Shared>,
10140 SubcConsumer,
10141 mpsc::Receiver<WriteCommand>,
10142 tokio::io::DuplexStream,
10143 RouteKey,
10144 RouteState,
10145 ) {
10146 let shared = writer_test_shared();
10147 let (stream, peer) = tokio::io::duplex(1024);
10148 shared
10149 .install_initial(OpenedConnection {
10150 stream: Box::new(stream),
10151 daemon_origin_trusted: true,
10152 daemon_ver: "0.39.0".into(),
10153 })
10154 .unwrap();
10155 let (writer, rx) = mpsc::channel(1);
10156 writer
10157 .try_send(WriteCommand {
10158 frame: response_frame(0, 0, 99, b"filler".to_vec()),
10159 pending: None,
10160 })
10161 .unwrap();
10162 let key = RouteKey::new(&restart_target("teardown"), &restart_identity(), None, None);
10163 let route = RouteState {
10164 handle: RouteHandle::new(17, 23, 1),
10165 sem: Arc::new(Semaphore::new(1)),
10166 watch_sem: None,
10167 opted_in: false,
10168 };
10169 {
10170 let mut inner = shared.lock_inner();
10171 inner.writer = Some(writer);
10172 inner.cache_route(key.clone(), route.clone());
10173 }
10174 let consumer = SubcConsumer {
10175 shared: Arc::clone(&shared),
10176 };
10177 (shared, consumer, rx, peer, key, route)
10178 }
10179
10180 async fn assert_reopened_request_after_goodbye(
10181 shared: &Arc<Shared>,
10182 consumer: &SubcConsumer,
10183 rx: &mut mpsc::Receiver<WriteCommand>,
10184 old: RouteHandle,
10185 ) {
10186 let reopened = RouteHandle::new(old.channel, old.epoch + 1, old.connection_token());
10187 shared
10188 .install_one_shot_route(RouteState {
10189 handle: reopened,
10190 sem: Arc::new(Semaphore::new(1)),
10191 watch_sem: None,
10192 opted_in: false,
10193 })
10194 .unwrap();
10195 let request = consumer.request(&reopened, b"reopened".to_vec(), CallOptions::default());
10196 tokio::pin!(request);
10197 assert_pending(request.as_mut()).await;
10198 let command = rx.recv().await.unwrap();
10199 assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10200 assert_eq!(
10201 (command.frame.header.channel, command.frame.header.epoch),
10202 (old.channel, old.epoch)
10203 );
10204 assert_pending(request.as_mut()).await;
10205 let command = rx.recv().await.unwrap();
10206 assert_eq!(command.frame.header.ty, FrameType::Request);
10207 assert_eq!(command.frame.header.channel, reopened.channel);
10208 assert_eq!(command.frame.header.epoch, reopened.epoch);
10209 dispatch_frame(
10210 shared,
10211 reopened.connection_token(),
10212 response_frame(
10213 reopened.channel,
10214 reopened.epoch,
10215 command.frame.header.corr,
10216 Vec::new(),
10217 ),
10218 )
10219 .await;
10220 request.await.unwrap();
10221 }
10222
10223 #[tokio::test]
10224 async fn route_teardown_close_waits_for_goodbye_before_channel_reuse() {
10225 for by_handle in [false, true] {
10226 let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10227 let close = async {
10228 if by_handle {
10229 consumer
10230 .close_handle(&route.handle, CloseRouteOptions::default())
10231 .await
10232 .unwrap();
10233 } else {
10234 consumer
10235 .close_route(
10236 restart_target("teardown"),
10237 restart_identity(),
10238 CloseRouteOptions::default(),
10239 )
10240 .await;
10241 }
10242 };
10243 tokio::pin!(close);
10244 assert_pending(close.as_mut()).await;
10245 assert!(route.sem.is_closed());
10246 assert!(!shared.lock_inner().routes.contains_key(&key));
10247 assert_eq!(
10248 shared.lock_inner().route_epochs.get(&route.handle.channel),
10249 Some(&route.handle)
10250 );
10251 let mut reopened = route.clone();
10252 reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10253 assert!(shared.install_one_shot_route(reopened).is_err());
10254 assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10255 close.await;
10256 assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10257 consumer.close().await;
10258 }
10259 }
10260
10261 #[tokio::test]
10262 async fn route_teardown_retirement_waits_for_goodbye_before_channel_reuse() {
10263 let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10264 shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10265 assert!(route.sem.is_closed());
10266 assert_eq!(
10267 shared.lock_inner().route_epochs.get(&route.handle.channel),
10268 Some(&route.handle)
10269 );
10270 let mut reopened = route.clone();
10271 reopened.handle = RouteHandle::new(route.handle.channel, route.handle.epoch + 1, 1);
10272 assert!(shared.install_one_shot_route(reopened).is_err());
10273 assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10274 tokio::time::timeout(Duration::from_secs(1), async {
10275 while shared
10276 .lock_inner()
10277 .route_epochs
10278 .contains_key(&route.handle.channel)
10279 {
10280 tokio::task::yield_now().await;
10281 }
10282 })
10283 .await
10284 .expect("retirement must queue its GOODBYE after writer capacity frees");
10285 assert_reopened_request_after_goodbye(&shared, &consumer, &mut rx, route.handle).await;
10286 consumer.close().await;
10287 }
10288
10289 #[tokio::test]
10290 async fn route_teardown_retirements_flush_in_order() {
10291 let (shared, consumer, mut rx, _peer, first_key, first) = route_teardown_stand_in();
10292 let second_key = RouteKey::new(&restart_target("second"), &restart_identity(), None, None);
10293 let mut second = first.clone();
10294 second.handle = RouteHandle::new(first.handle.channel + 1, 31, 1);
10295 shared
10296 .lock_inner()
10297 .cache_route(second_key.clone(), second.clone());
10298 shared.invalidate_route_with_deadline(&first_key, Some(first.handle), true);
10299 shared.invalidate_route_with_deadline(&second_key, Some(second.handle), true);
10300 assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10301 for handle in [first.handle, second.handle] {
10302 let command = tokio::time::timeout(Duration::from_secs(1), rx.recv())
10303 .await
10304 .unwrap()
10305 .unwrap();
10306 assert_eq!(command.frame.header.ty, FrameType::Goodbye);
10307 assert_eq!(
10308 (command.frame.header.channel, command.frame.header.epoch),
10309 (handle.channel, handle.epoch)
10310 );
10311 assert!(!shared
10312 .lock_inner()
10313 .route_epochs
10314 .contains_key(&handle.channel));
10315 }
10316 assert!(shared.lock_inner().retirement_queue.is_empty());
10317 assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10318 assert!(rx.try_recv().is_err());
10319 consumer.close().await;
10320 }
10321
10322 #[tokio::test]
10323 async fn route_teardown_dead_connection_ends_writer_wait_and_discards_retirements() {
10324 for death in 0..3 {
10325 let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10326 let opts = CloseRouteOptions::default();
10327 let close = shared.close_route(&key, &opts);
10328 tokio::pin!(close);
10329 assert_pending(close.as_mut()).await;
10330 match death {
10331 0 => rx.close(),
10332 1 => shared.handle_generation_drop(1, "test connection lost".into()),
10333 _ => shared.close_sync("test connection closed"),
10334 }
10335 tokio::time::timeout(Duration::from_secs(1), close)
10336 .await
10337 .unwrap();
10338 assert!(!shared
10339 .lock_inner()
10340 .route_epochs
10341 .contains_key(&route.handle.channel));
10342 assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10343 assert!(rx.try_recv().is_err());
10344 consumer.close().await;
10345
10346 let (shared, consumer, mut rx, _peer, key, route) = route_teardown_stand_in();
10347 shared.invalidate_route_with_deadline(&key, Some(route.handle), true);
10348 if death == 1 {
10349 shared.handle_generation_drop(1, "test connection lost".into());
10350 } else {
10351 consumer.close().await;
10352 }
10353 assert!(shared.lock_inner().retirement_queue.is_empty());
10354 assert!(shared.lock_inner().retirement_goodbyes.is_empty());
10355 assert_eq!(rx.recv().await.unwrap().frame.body, b"filler");
10356 assert!(rx.try_recv().is_err());
10357 consumer.close().await;
10358 }
10359 }
10360
10361 #[tokio::test]
10362 async fn route_channel_index_tracks_lookup_close_and_generation_drop() {
10363 let shared = writer_test_shared();
10364 let (writer, _rx) = mpsc::channel(32);
10365 let mut expected = Vec::new();
10366 {
10367 let mut inner = shared.lock_inner();
10368 inner.writer = Some(writer);
10369 inner.daemon_ver = "0.39.0".into();
10370 for channel in 1..=8 {
10371 let key = RouteKey::new(
10372 &RouteTarget::ToolProvider {
10373 module_id: format!("module-{channel}"),
10374 },
10375 &BindIdentity::new("test", format!("session-{channel}")),
10376 None,
10377 None,
10378 );
10379 let route = RouteState {
10380 handle: RouteHandle::new(channel, channel.into(), 1),
10381 sem: Arc::new(Semaphore::new(DEFAULT_ROUTE_WINDOW)),
10382 watch_sem: None,
10383 opted_in: false,
10384 };
10385 inner.cache_route(key.clone(), route.clone());
10386 expected.push((key, route));
10387 }
10388 }
10389
10390 for (key, expected_route) in &expected {
10391 let resolved = shared
10392 .route_state(expected_route.handle)
10393 .expect("an indexed route handle should resolve");
10394 assert_eq!(resolved.handle, expected_route.handle);
10395 assert!(Arc::ptr_eq(&resolved.sem, &expected_route.sem));
10396
10397 let inner = shared.lock_inner();
10398 assert_eq!(
10399 inner.route_by_channel.get(&expected_route.handle.channel),
10400 Some(key)
10401 );
10402 assert_eq!(
10403 inner.route_epochs.get(&expected_route.handle.channel),
10404 Some(&expected_route.handle)
10405 );
10406 assert!(inner
10407 .routes
10408 .get(key)
10409 .is_some_and(|route| route.handle == expected_route.handle));
10410 }
10411
10412 let (closed_key, closed_route) = &expected[3];
10413 shared
10414 .close_route(closed_key, &CloseRouteOptions::default())
10415 .await;
10416 {
10417 let inner = shared.lock_inner();
10418 assert!(!inner.routes.contains_key(closed_key));
10419 assert!(!inner
10420 .route_by_channel
10421 .contains_key(&closed_route.handle.channel));
10422 assert!(!inner
10423 .route_epochs
10424 .contains_key(&closed_route.handle.channel));
10425 }
10426 assert!(matches!(
10427 shared.route_state(closed_route.handle),
10428 Err(CallError::StaleRouteHandle(handle)) if handle == closed_route.handle
10429 ));
10430
10431 shared.handle_generation_drop(1, "test generation dropped".into());
10432 {
10433 let inner = shared.lock_inner();
10434 assert!(inner.routes.is_empty());
10435 assert!(inner.route_by_channel.is_empty());
10436 assert!(inner.route_epochs.is_empty());
10437 }
10438 shared.close_sync("test complete");
10439 }
10440
10441 #[tokio::test]
10442 async fn stale_push_is_not_delivered_after_connection_generation_changes() {
10443 let shared = writer_test_shared();
10444 let old_handle = RouteHandle::new(7, 1, 1);
10445 let (writer, _writer_rx) = mpsc::channel(1);
10446 {
10447 let mut inner = shared.lock_inner();
10448 inner.writer = Some(writer);
10449 inner.daemon_ver = "0.39.0".into();
10450 inner.route_epochs.insert(old_handle.channel, old_handle);
10451 }
10452 let mut pushes = shared
10453 .register_push_events(old_handle)
10454 .expect("the old live route should accept a receiver");
10455
10456 {
10457 let mut inner = shared.lock_inner();
10458 inner.generation = 2;
10459 inner.close_routes();
10460 inner.route_epochs.clear();
10461 inner.route_modules.clear();
10462 inner.route_end_reasons.clear();
10463 inner.legacy_channel_reasons.clear();
10464 }
10465 shared.route_push(old_handle, b"stale".to_vec());
10466
10467 assert!(
10468 pushes.recv().await.is_none(),
10469 "connection teardown must end the old receiver before a stale Push can arrive"
10470 );
10471 shared.close_sync("test complete");
10472 }
10473
10474 #[test]
10475 fn route_key_canonicalizes_consumer_capabilities() {
10476 let target = RouteTarget::ToolProvider {
10477 module_id: "aft".into(),
10478 };
10479 let identity = BindIdentity::new("h", "s");
10480 let left = RouteKey::new(
10481 &target,
10482 &identity,
10483 None,
10484 Some(&["sampling".to_string(), "elicitation".to_string()]),
10485 );
10486 let right = RouteKey::new(
10487 &target,
10488 &identity,
10489 None,
10490 Some(&[
10491 "elicitation".to_string(),
10492 "sampling".to_string(),
10493 "sampling".to_string(),
10494 ]),
10495 );
10496 assert_eq!(left, right);
10497 }
10498
10499 #[tokio::test]
10500 async fn routes_with_and_without_declared_consumer_capabilities_are_kept_apart() {
10501 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(10));
10502 let (undeclared_request, undeclared) = open_answered_with(
10503 &shared,
10504 &consumer,
10505 &mut receiver,
10506 CallOptions::default(),
10507 74,
10508 "the undeclared route opens first",
10509 )
10510 .await;
10511 assert!(undeclared_request.get("consumer_capabilities").is_none());
10512
10513 let declared_opts = CallOptions::default()
10514 .with_consumer_capability("tool-result/v1")
10515 .unwrap();
10516 let (declared_request, declared) = open_answered_with(
10517 &shared,
10518 &consumer,
10519 &mut receiver,
10520 declared_opts.clone(),
10521 75,
10522 "a declared open must not reuse the undeclared route",
10523 )
10524 .await;
10525 assert_eq!(
10526 declared_request["consumer_capabilities"],
10527 serde_json::json!(["tool-result/v1"])
10528 );
10529 assert_ne!(undeclared, declared);
10530
10531 assert_eq!(
10532 consumer
10533 .open_route(restart_target("plexus"), restart_identity(), declared_opts)
10534 .await
10535 .unwrap(),
10536 declared,
10537 "the same declaration must reuse its cached route"
10538 );
10539 assert_eq!(
10540 consumer
10541 .open_route(
10542 restart_target("plexus"),
10543 restart_identity(),
10544 CallOptions::default(),
10545 )
10546 .await
10547 .unwrap(),
10548 undeclared,
10549 "an undeclared open must continue to reuse only its own route"
10550 );
10551 assert!(
10552 receiver.try_recv().is_err(),
10553 "both subsequent opens are cache hits"
10554 );
10555 shared.close_sync("test complete");
10556 }
10557
10558 fn scope_selector(owner: &str, scope_ref: &str, scope_epoch: u64) -> ScopeSelector {
10559 ScopeSelector::new(
10560 subc_protocol::Principal::Reserved {
10561 module_id: owner.to_string(),
10562 },
10563 scope_ref.to_string(),
10564 Some(scope_epoch),
10565 )
10566 }
10567
10568 #[test]
10569 fn route_key_separates_scopes_by_owner_ref_and_epoch_and_from_unscoped() {
10570 let target = RouteTarget::ToolProvider {
10571 module_id: "plexus".into(),
10572 };
10573 let identity = BindIdentity::new("h", "s");
10574 let key = |scope: Option<ScopeSelector>| {
10575 RouteKey::new(&target, &identity, None, None).with_scope(scope.as_ref())
10576 };
10577 let base = key(Some(scope_selector("owner", "session-a", 1)));
10578 assert_eq!(base, key(Some(scope_selector("owner", "session-a", 1))));
10579 for (label, other) in [
10580 ("epoch", key(Some(scope_selector("owner", "session-a", 2)))),
10581 ("ref", key(Some(scope_selector("owner", "session-b", 1)))),
10582 ("owner", key(Some(scope_selector("other", "session-a", 1)))),
10583 ("unscoped", key(None)),
10584 ] {
10585 assert_ne!(base, other, "a different {label} must be a different route");
10586 }
10587 let mut no_epoch = scope_selector("owner", "session-a", 1);
10588 no_epoch.scope_epoch = None;
10589 assert_ne!(base, key(Some(no_epoch)));
10590 }
10591
10592 async fn next_route_open(
10596 receiver: &mut mpsc::Receiver<WriteCommand>,
10597 why: &str,
10598 ) -> (u64, serde_json::Value) {
10599 loop {
10600 let command = tokio::time::timeout(Duration::from_secs(2), receiver.recv())
10601 .await
10602 .unwrap_or_else(|_| panic!("no route.open was sent: {why}"))
10603 .expect("writer channel open");
10604 if command.frame.header.channel != 0 || command.frame.header.ty != FrameType::Request {
10605 continue;
10606 }
10607 let request: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10608 if request["op"] == "route.open" {
10609 return (command.frame.header.corr, request);
10610 }
10611 }
10612 }
10613
10614 async fn open_answered(
10617 shared: &Arc<Shared>,
10618 consumer: &Arc<SubcConsumer>,
10619 receiver: &mut mpsc::Receiver<WriteCommand>,
10620 scope: Option<ScopeSelector>,
10621 channel: u16,
10622 why: &str,
10623 ) -> (serde_json::Value, RouteHandle) {
10624 let consumer = Arc::clone(consumer);
10625 let task = tokio::spawn(async move {
10626 match scope {
10627 Some(scope) => {
10628 consumer
10629 .open_route_scoped(
10630 restart_target("plexus"),
10631 restart_identity(),
10632 scope,
10633 CallOptions::default(),
10634 )
10635 .await
10636 }
10637 None => {
10638 consumer
10639 .open_route(
10640 restart_target("plexus"),
10641 restart_identity(),
10642 CallOptions::default(),
10643 )
10644 .await
10645 }
10646 }
10647 });
10648 let (corr, request) = next_route_open(receiver, why).await;
10649 assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10650 let handle = task.await.unwrap().expect("the stand-in accepted the open");
10651 (request, handle)
10652 }
10653
10654 async fn open_answered_with(
10658 shared: &Arc<Shared>,
10659 consumer: &Arc<SubcConsumer>,
10660 receiver: &mut mpsc::Receiver<WriteCommand>,
10661 opts: CallOptions,
10662 channel: u16,
10663 why: &str,
10664 ) -> (serde_json::Value, RouteHandle) {
10665 let consumer = Arc::clone(consumer);
10666 let task = tokio::spawn(async move {
10667 consumer
10668 .open_route(restart_target("plexus"), restart_identity(), opts)
10669 .await
10670 });
10671 let (corr, request) = next_route_open(receiver, why).await;
10672 assert!(dispatch_frame(shared, 1, route_open_answer(corr, channel, None)).await);
10673 let handle = task.await.unwrap().expect("the stand-in accepted the open");
10674 (request, handle)
10675 }
10676
10677 fn with_role_versions(entries: &[(&str, &str)]) -> CallOptions {
10678 CallOptions {
10679 role_versions: Some(
10680 entries
10681 .iter()
10682 .map(|(role, version)| (role.to_string(), version.to_string()))
10683 .collect(),
10684 ),
10685 ..CallOptions::default()
10686 }
10687 }
10688
10689 #[tokio::test]
10694 async fn routes_differing_only_in_role_versions_are_kept_apart() {
10695 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10696 let (legacy_request, legacy) = open_answered_with(
10697 &shared,
10698 &consumer,
10699 &mut receiver,
10700 CallOptions::default(),
10701 71,
10702 "first, legacy open",
10703 )
10704 .await;
10705 assert!(
10706 legacy_request.get("role_versions").is_none(),
10707 "{legacy_request}"
10708 );
10709
10710 let (v1_request, v1) = open_answered_with(
10711 &shared,
10712 &consumer,
10713 &mut receiver,
10714 with_role_versions(&[("tool-provider", "v1")]),
10715 72,
10716 "a v1 open must not reuse the legacy route",
10717 )
10718 .await;
10719 assert_eq!(
10720 v1_request["role_versions"],
10721 serde_json::json!({ "tool-provider": "v1" })
10722 );
10723 assert_ne!(legacy, v1);
10724
10725 let (v2_request, v2) = open_answered_with(
10726 &shared,
10727 &consumer,
10728 &mut receiver,
10729 with_role_versions(&[("tool-provider", "v2")]),
10730 73,
10731 "a v2 open must not reuse the v1 route",
10732 )
10733 .await;
10734 assert_eq!(
10735 v2_request["role_versions"],
10736 serde_json::json!({ "tool-provider": "v2" })
10737 );
10738 assert!(![legacy, v1].contains(&v2));
10739
10740 let open = |opts: CallOptions| {
10741 let consumer = Arc::clone(&consumer);
10742 async move {
10743 consumer
10744 .open_route(restart_target("plexus"), restart_identity(), opts)
10745 .await
10746 .unwrap()
10747 }
10748 };
10749 assert_eq!(
10750 open(with_role_versions(&[("tool-provider", "v1")])).await,
10751 v1
10752 );
10753 assert_eq!(open(CallOptions::default()).await, legacy);
10754 assert_eq!(
10755 open(CallOptions {
10756 role_versions: Some(BTreeMap::new()),
10757 ..CallOptions::default()
10758 })
10759 .await,
10760 legacy,
10761 "an empty map declares nothing and reuses the legacy route"
10762 );
10763 assert!(
10764 receiver.try_recv().is_err(),
10765 "a cache hit must not send a route.open"
10766 );
10767 shared.close_sync("test complete");
10768 }
10769
10770 #[tokio::test]
10771 async fn scoped_routes_are_cached_per_owner_ref_and_epoch_and_apart_from_unscoped() {
10772 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(8));
10773 let selector = scope_selector("owner", "session-a", 1);
10774 let (request, first) = open_answered(
10775 &shared,
10776 &consumer,
10777 &mut receiver,
10778 Some(selector.clone()),
10779 61,
10780 "first scoped open",
10781 )
10782 .await;
10783 assert_eq!(request["scope"], serde_json::to_value(&selector).unwrap());
10784
10785 let again = consumer
10787 .open_route_scoped(
10788 restart_target("plexus"),
10789 restart_identity(),
10790 selector,
10791 CallOptions::default(),
10792 )
10793 .await
10794 .unwrap();
10795 assert_eq!(again, first);
10796 assert!(
10797 receiver.try_recv().is_err(),
10798 "a cache hit must not send a route.open"
10799 );
10800
10801 let mut handles = vec![first];
10802 for (channel, scope, why) in [
10803 (
10804 62,
10805 Some(scope_selector("owner", "session-a", 2)),
10806 "another epoch of the same scope must open its own route",
10807 ),
10808 (
10809 63,
10810 Some(scope_selector("owner", "session-b", 1)),
10811 "another scope ref must open its own route",
10812 ),
10813 (
10814 64,
10815 Some(scope_selector("other-owner", "session-a", 1)),
10816 "another owner's scope must open its own route",
10817 ),
10818 (65, None, "an unscoped open must not reuse a scoped route"),
10819 ] {
10820 let expected_scope = scope
10821 .as_ref()
10822 .map(|scope| serde_json::to_value(scope).unwrap());
10823 let (request, handle) =
10824 open_answered(&shared, &consumer, &mut receiver, scope, channel, why).await;
10825 assert_eq!(
10826 request.get("scope").cloned(),
10827 expected_scope,
10828 "the route.open must carry exactly the requested scope: {why}"
10829 );
10830 assert!(!handles.contains(&handle), "{why}");
10831 handles.push(handle);
10832 }
10833 shared.close_sync("test complete");
10834 }
10835
10836 #[tokio::test]
10837 async fn a_dropped_scoped_route_reopens_with_the_same_selector() {
10838 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(7));
10839 let selector = scope_selector("owner", "session-a", 3);
10840 let (first_request, first) = open_answered(
10841 &shared,
10842 &consumer,
10843 &mut receiver,
10844 Some(selector.clone()),
10845 51,
10846 "first scoped open",
10847 )
10848 .await;
10849
10850 let goodbye = Frame::build(
10852 FrameType::Goodbye,
10853 Flags::new(false, Priority::Interactive, false),
10854 first.channel,
10855 first.epoch,
10856 0,
10857 Vec::new(),
10858 )
10859 .unwrap();
10860 assert!(dispatch_frame(&shared, 1, goodbye).await);
10861 assert!(matches!(
10862 shared.route_state(first),
10863 Err(CallError::StaleRouteHandle(_))
10864 ));
10865
10866 let (second_request, second) = open_answered(
10867 &shared,
10868 &consumer,
10869 &mut receiver,
10870 Some(selector.clone()),
10871 52,
10872 "the reopen after the route dropped",
10873 )
10874 .await;
10875 assert_eq!(
10876 first_request["scope"],
10877 serde_json::to_value(&selector).unwrap()
10878 );
10879 assert_eq!(second_request["scope"], first_request["scope"]);
10880 assert_ne!(second, first);
10881 shared.close_sync("test complete");
10882 }
10883
10884 async fn refuse_scoped_opens(code: &str) -> (usize, CallError) {
10887 refuse_scoped_operation(code, "open").await
10888 }
10889
10890 async fn refuse_scoped_operation(code: &str, operation: &str) -> (usize, CallError) {
10891 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(9));
10892 let selector = scope_selector("owner", "session-a", 1);
10893 let options = CallOptions {
10894 scope: Some(selector.clone()),
10895 timeout: Duration::from_secs(2),
10896 route_retry: RetryBackoff {
10897 base: Duration::ZERO,
10898 cap: Duration::ZERO,
10899 max_attempts: 2,
10900 },
10901 route_retry_deadline: Duration::from_millis(150),
10902 ..CallOptions::default()
10903 };
10904 let operation = operation.to_string();
10905 let mut task = tokio::spawn(async move {
10906 match operation.as_str() {
10907 "call" => consumer
10908 .call(
10909 restart_target("plexus"),
10910 restart_identity(),
10911 b"{}".to_vec(),
10912 options,
10913 )
10914 .await
10915 .map(|_| ()),
10916 "subscribe" => consumer
10917 .subscribe(
10918 restart_target("plexus"),
10919 restart_identity(),
10920 b"{}".to_vec(),
10921 SubscribeOptions {
10922 scope: options.scope,
10923 route_open_timeout: options.timeout,
10924 route_retry: options.route_retry,
10925 route_retry_deadline: options.route_retry_deadline,
10926 ..SubscribeOptions::default()
10927 },
10928 )
10929 .await
10930 .map(|_| ()),
10931 "open" => consumer
10932 .open_route_scoped(
10933 restart_target("plexus"),
10934 restart_identity(),
10935 scope_selector("owner", "session-a", 1),
10936 options,
10937 )
10938 .await
10939 .map(|_| ()),
10940 _ => unreachable!(),
10941 }
10942 });
10943 let mut attempts = 0usize;
10944 let err = loop {
10945 tokio::select! {
10946 command = receiver.recv() => {
10947 let Some(command) = command else {
10948 break task.await.unwrap().expect_err("route.open must be refused");
10949 };
10950 let open: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
10951 assert_eq!(open["scope"], serde_json::to_value(&selector).unwrap());
10952 attempts += 1;
10953 let frame = route_open_answer(
10954 command.frame.header.corr,
10955 0,
10956 Some(ErrorBody::new(code, "test refusal")),
10957 );
10958 assert!(dispatch_frame(&shared, 1, frame).await);
10959 }
10960 joined = &mut task => {
10961 break joined.unwrap().expect_err("route.open must be refused");
10962 }
10963 }
10964 };
10965 shared.close_sync("test complete");
10966 (attempts, err)
10967 }
10968
10969 #[tokio::test]
10970 async fn scoped_managed_operations_retry_only_transient_scope_refusals() {
10971 for operation in ["call", "subscribe"] {
10972 for (code, retryable) in [
10973 (error_codes::SCOPE_NOT_SYNCED, true),
10974 (error_codes::SCOPE_CHANGED, true),
10975 (error_codes::SCOPE_ENDED, false),
10976 (error_codes::SCOPE_NOT_LIVE, false),
10977 (error_codes::SCOPE_EPOCH_REQUIRED, false),
10978 (error_codes::SCOPE_NOT_CARRIER, false),
10979 ] {
10980 let (attempts, err) = refuse_scoped_operation(code, operation).await;
10981 if retryable {
10982 assert!(attempts > 1, "{operation}: {code} must be retried");
10983 } else {
10984 assert_eq!(attempts, 1, "{operation}: {code} must be terminal");
10985 }
10986 assert!(matches!(err, CallError::NotSent(_)), "{operation}: {err}");
10987 assert_eq!(err.never_forwarded(), Some(true));
10988 assert_eq!(err.route_open_refusal().unwrap().code, code);
10989 }
10990 }
10991 }
10992
10993 #[tokio::test]
10994 async fn scoped_open_retries_not_synced_and_changed_and_ends_on_the_terminal_scope_codes() {
10995 for code in [error_codes::SCOPE_NOT_SYNCED, error_codes::SCOPE_CHANGED] {
10996 let (attempts, err) = refuse_scoped_opens(code).await;
10997 assert!(attempts > 1, "{code} must be retried, served {attempts}");
10998 assert_eq!(
10999 err.route_open_refusal().map(|body| body.code.as_str()),
11000 Some(code)
11001 );
11002 }
11003 for code in [
11004 error_codes::SCOPE_ENDED,
11005 error_codes::SCOPE_NOT_LIVE,
11006 error_codes::SCOPE_EPOCH_REQUIRED,
11007 error_codes::SCOPE_NOT_CARRIER,
11008 ] {
11009 let (attempts, err) = refuse_scoped_opens(code).await;
11010 assert_eq!(attempts, 1, "{code} is terminal and must not be retried");
11011 assert!(matches!(err, CallError::NotSent(_)));
11012 assert_eq!(
11013 err.route_open_refusal().map(|body| body.code.as_str()),
11014 Some(code)
11015 );
11016 }
11017 }
11018
11019 #[tokio::test]
11026 async fn refusal_survives_a_retry_still_in_flight_at_the_deadline() {
11027 let (shared, consumer, mut receiver) = route_open_stand_in(seeded_random(11));
11028 let options = CallOptions {
11029 timeout: Duration::from_secs(5),
11030 route_retry: RetryBackoff {
11031 base: Duration::ZERO,
11032 cap: Duration::ZERO,
11033 max_attempts: 2,
11034 },
11035 route_retry_deadline: Duration::from_millis(300),
11036 ..CallOptions::default()
11037 };
11038 let mut task = tokio::spawn(async move {
11039 consumer
11040 .open_route(restart_target("warming"), restart_identity(), options)
11041 .await
11042 });
11043 let generation = shared.lock_inner().generation;
11044 let refusal = ErrorBody {
11045 code: error_codes::MODULE_WARMING.to_string(),
11046 message: "warming is not ready".to_string(),
11047 detail: Some(serde_json::json!({"reason": "required_capability_unprovided"})),
11048 };
11049 let mut attempts = 0usize;
11050 let mut held = false;
11051 let err = loop {
11052 tokio::select! {
11053 command = receiver.recv() => {
11054 let Some(command) = command else {
11055 break task.await.unwrap().expect_err("route.open must fail");
11056 };
11057 if command.frame.header.ty != FrameType::Request {
11058 continue;
11059 }
11060 attempts += 1;
11061 if attempts == 1 {
11062 let frame = route_open_answer(
11063 command.frame.header.corr,
11064 0,
11065 Some(refusal.clone()),
11066 );
11067 assert!(dispatch_frame(&shared, generation, frame).await);
11068 } else {
11069 held = shared.mark_pending_accepted(
11072 command.pending.expect("a route.open is a pending request"),
11073 );
11074 }
11075 }
11076 joined = &mut task => {
11077 break joined.unwrap().expect_err("route.open must fail");
11078 }
11079 }
11080 };
11081 shared.close_sync("test complete");
11082 assert_eq!(
11083 attempts, 2,
11084 "one refused attempt, then one held past the deadline"
11085 );
11086 assert!(
11087 held,
11088 "the second attempt must be accepted and left unanswered"
11089 );
11090 assert!(
11091 err.is_not_sent(),
11092 "a refused route never delivered the request: {err}"
11093 );
11094 let body = err
11095 .route_open_refusal()
11096 .unwrap_or_else(|| panic!("the refusal must survive the deadline: {err}"));
11097 assert_eq!(body.code, error_codes::MODULE_WARMING);
11098 assert_eq!(body.detail, refusal.detail);
11099 }
11100
11101 #[test]
11102 fn every_scope_close_reason_must_not_reopen() {
11103 for reason in [
11104 subc_protocol::RouteCloseReason::ScopeEnded,
11105 subc_protocol::RouteCloseReason::ScopeCarrierRemoved,
11106 subc_protocol::RouteCloseReason::ScopeDelegationChanged,
11107 subc_protocol::RouteCloseReason::ScopeParentEnded,
11108 ] {
11109 let wire = serde_json::to_value(reason).unwrap();
11110 let wire = wire.as_str().expect("a close reason is a string");
11111 assert!(wire.starts_with("scope_"), "{wire}");
11112 assert_eq!(
11113 RouteCloseReason::from_wire(wire).disposition(),
11114 RouteCloseDisposition::MustNotReopen,
11115 "a route closed for {wire} must not be reopened"
11116 );
11117 }
11118 }
11119
11120 async fn watch_subscribed() -> (
11123 SubcConsumer,
11124 mpsc::Receiver<WriteCommand>,
11125 Subscription,
11126 Frame,
11127 ) {
11128 let (shared, mut rx, handle) = reverse_test_shared(ReverseRequestRegistry::new());
11129 shared.lock_inner().one_shot_routes.insert(
11130 handle.channel,
11131 RouteState {
11132 handle,
11133 sem: Arc::new(Semaphore::new(1)),
11134 watch_sem: None,
11135 opted_in: false,
11136 },
11137 );
11138 let consumer = SubcConsumer { shared };
11139 let subscription = consumer
11140 .subscribe_route(&handle, b"watch".to_vec(), SubscribeOptions::default())
11141 .await
11142 .unwrap();
11143 let request = rx.recv().await.unwrap().frame;
11144 (consumer, rx, subscription, request)
11145 }
11146
11147 fn watch_terminal(request: &Frame, ty: FrameType, body: Vec<u8>) -> Frame {
11148 Frame::build(
11149 ty,
11150 Flags::new(false, Priority::Interactive, false),
11151 request.header.channel,
11152 request.header.epoch,
11153 request.header.corr,
11154 body,
11155 )
11156 .unwrap()
11157 }
11158
11159 #[tokio::test]
11160 async fn subscription_ended_preserves_response_body_and_closed_stays_ok() {
11161 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11162 let body = vec![0, 255, 128, 1, 10];
11163 assert!(
11164 dispatch_frame(
11165 &consumer.shared,
11166 1,
11167 watch_terminal(&request, FrameType::Response, body.clone())
11168 )
11169 .await
11170 );
11171 subscription.closed().await.unwrap();
11172 assert_eq!(
11173 subscription.ended().await,
11174 SubscriptionEnd::Response(body.clone())
11175 );
11176 subscription.unsubscribe().unwrap();
11177 assert_eq!(subscription.ended().await, SubscriptionEnd::Response(body));
11178 assert_eq!(subscription.events().recv().await, None);
11179 }
11180
11181 #[tokio::test]
11182 async fn subscription_ended_distinguishes_empty_response_from_stream_end() {
11183 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11184 assert!(
11185 dispatch_frame(
11186 &consumer.shared,
11187 1,
11188 watch_terminal(&request, FrameType::Response, Vec::new())
11189 )
11190 .await
11191 );
11192 assert_eq!(
11193 subscription.ended().await,
11194 SubscriptionEnd::Response(Vec::new())
11195 );
11196 subscription.closed().await.unwrap();
11197 }
11198
11199 #[tokio::test]
11200 async fn subscription_ended_reports_stream_end_and_closed_stays_ok() {
11201 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11202 assert!(
11203 dispatch_frame(
11204 &consumer.shared,
11205 1,
11206 watch_terminal(&request, FrameType::StreamEnd, Vec::new())
11207 )
11208 .await
11209 );
11210 assert_eq!(subscription.ended().await, SubscriptionEnd::StreamEnd);
11211 subscription.closed().await.unwrap();
11212 }
11213
11214 #[tokio::test]
11215 async fn subscription_ended_reports_module_error_code_and_detail() {
11216 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11217 let error = ErrorBody {
11218 code: "no_grant".to_string(),
11219 message: "not accepted: no grant".to_string(),
11220 detail: Some(serde_json::json!({"capability": "watch"})),
11221 };
11222 assert!(
11223 dispatch_frame(
11224 &consumer.shared,
11225 1,
11226 watch_terminal(
11227 &request,
11228 FrameType::Error,
11229 serde_json::to_vec(&error).unwrap()
11230 )
11231 )
11232 .await
11233 );
11234 assert_eq!(
11235 subscription.ended().await,
11236 SubscriptionEnd::Error(error.clone())
11237 );
11238 let CallError::Module(closed_error) = subscription.closed().await.unwrap_err() else {
11239 panic!("closed must still return the module error");
11240 };
11241 assert_eq!(closed_error, error);
11242 subscription.unsubscribe().unwrap();
11243 assert_eq!(subscription.ended().await, SubscriptionEnd::Error(error));
11244 }
11245
11246 #[tokio::test]
11247 async fn subscription_ended_reports_unsubscribe_as_cancelled_and_ignores_late_terminal() {
11248 let (consumer, mut rx, mut subscription, request) = watch_subscribed().await;
11249 subscription.unsubscribe().unwrap();
11250 subscription.unsubscribe().unwrap();
11251 subscription.closed().await.unwrap();
11252 assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11253 let cancel = rx.recv().await.unwrap().frame;
11254 assert_eq!(cancel.header.ty, FrameType::Cancel);
11255 assert_eq!(cancel.header.corr, request.header.corr);
11256 assert!(rx.try_recv().is_err());
11257 assert!(
11258 dispatch_frame(
11259 &consumer.shared,
11260 1,
11261 watch_terminal(&request, FrameType::Response, b"late".to_vec())
11262 )
11263 .await
11264 );
11265 assert_eq!(subscription.ended().await, SubscriptionEnd::Cancelled);
11266 }
11267
11268 #[tokio::test]
11269 async fn subscription_ended_retains_route_close_reason() {
11270 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11271 let push = Frame::build(FrameType::Push, Flags::new(false, Priority::Interactive, false), 0, 0, 0,
11272 serde_json::to_vec(&serde_json::json!({"op": "route.closed", "module_id": "watch", "reason": "capability_denied", "channels": [request.header.channel]})).unwrap()).unwrap();
11273 assert!(dispatch_frame(&consumer.shared, 1, push).await);
11274 assert!(
11275 dispatch_frame(
11276 &consumer.shared,
11277 1,
11278 watch_terminal(&request, FrameType::Goodbye, Vec::new())
11279 )
11280 .await
11281 );
11282 let reason = RouteEndReason::Daemon(RouteCloseReason::CapabilityDenied);
11283 assert_eq!(
11284 subscription.ended().await,
11285 SubscriptionEnd::RouteClosed {
11286 reason: reason.clone()
11287 }
11288 );
11289 assert_eq!(
11290 subscription.closed().await.unwrap_err().close_reason(),
11291 Some(&reason)
11292 );
11293 }
11294
11295 #[tokio::test]
11296 async fn subscription_ended_reports_connection_loss() {
11297 let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11298 consumer
11299 .shared
11300 .handle_generation_drop(1, "fake connection lost".to_string());
11301 assert_eq!(subscription.ended().await, SubscriptionEnd::ConnectionLost);
11302 assert!(subscription.closed().await.is_err());
11303 }
11304
11305 #[tokio::test]
11306 async fn subscription_ended_waiter_wakes_on_stream_end() {
11307 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11308 let (end, dispatched) = tokio::join!(subscription.ended(), async {
11309 tokio::task::yield_now().await;
11310 dispatch_frame(
11311 &consumer.shared,
11312 1,
11313 watch_terminal(&request, FrameType::StreamEnd, Vec::new()),
11314 )
11315 .await
11316 });
11317 assert!(dispatched);
11318 assert_eq!(end, SubscriptionEnd::StreamEnd);
11319 subscription.closed().await.unwrap();
11320 }
11321
11322 #[tokio::test]
11323 async fn subscription_ended_reports_backpressure_without_hiding_closed_error() {
11324 let (consumer, _rx, mut subscription, request) = watch_subscribed().await;
11325 for _ in 0..=DEFAULT_SUBSCRIPTION_EVENT_BUFFER {
11326 assert!(
11327 dispatch_frame(
11328 &consumer.shared,
11329 1,
11330 watch_terminal(&request, FrameType::StreamData, vec![1])
11331 )
11332 .await
11333 );
11334 }
11335 assert_eq!(subscription.ended().await, SubscriptionEnd::Backpressure);
11336 assert!(matches!(
11337 subscription.closed().await,
11338 Err(CallError::SubscriptionBackpressure(_))
11339 ));
11340 }
11341
11342 #[tokio::test]
11343 async fn subscription_ended_reports_client_close_as_route_closed_by_caller() {
11344 let (consumer, _rx, mut subscription, _request) = watch_subscribed().await;
11345 consumer.close().await;
11346 assert_eq!(
11347 subscription.ended().await,
11348 SubscriptionEnd::RouteClosed {
11349 reason: RouteEndReason::ClosedByCaller
11350 }
11351 );
11352 assert!(subscription.closed().await.is_err());
11353 }
11354
11355 #[test]
11356 fn drain_pending_channel_can_skip_subscriptions() {
11357 let mut pending = HashMap::new();
11358 let generation = 7;
11359 let channel = 11;
11360 let handle = RouteHandle::new(channel, 3, generation);
11361 let unary_key = PendingKey {
11362 generation,
11363 channel,
11364 epoch: handle.epoch,
11365 corr: 1,
11366 };
11367 let subscription_key = PendingKey {
11368 generation,
11369 channel,
11370 epoch: handle.epoch,
11371 corr: 2,
11372 };
11373 let (unary_tx, _unary_rx) = oneshot::channel();
11374 pending.insert(unary_key, PendingEntry::unary(unary_tx, false, None, None));
11375
11376 let (events_tx, _events_rx) = mpsc::channel(1);
11377 let (closed_tx, _closed_rx) = oneshot::channel();
11378 let (ended_tx, _ended_rx) = watch::channel(None);
11379 let permit = Arc::new(Semaphore::new(1))
11380 .try_acquire_owned()
11381 .expect("test semaphore permit should be available");
11382 pending.insert(
11383 subscription_key,
11384 PendingEntry::subscription(
11385 events_tx,
11386 closed_tx,
11387 ended_tx,
11388 RoutePermit::legacy(permit),
11389 Priority::Interactive,
11390 ),
11391 );
11392
11393 let drained = drain_pending_handle(&mut pending, handle, false);
11394 assert_eq!(drained.len(), 1);
11395 assert!(pending.contains_key(&subscription_key));
11396
11397 let drained = drain_pending_handle(&mut pending, handle, true);
11398 assert_eq!(drained.len(), 1);
11399 assert!(pending.is_empty());
11400 }
11401
11402 fn response_frame(channel: u16, epoch: u32, corr: u64, body: Vec<u8>) -> Frame {
11403 Frame::build(
11404 FrameType::Response,
11405 Flags::new(false, Priority::Interactive, false),
11406 channel,
11407 epoch,
11408 corr,
11409 body,
11410 )
11411 .unwrap()
11412 }
11413
11414 #[tokio::test]
11415 async fn stale_epoch_ingress_drops_without_settling_matching_corr() {
11416 let shared = Arc::new(reader_skew_tests::legacy_shared(
11417 PathBuf::from("/tmp/does-not-exist"),
11418 ConsumerOptions::default(),
11419 ));
11420 let (writer, _rx) = mpsc::channel(4);
11421 let current = RouteHandle::new(9, 2, 1);
11422 let stale_key = PendingKey {
11423 generation: 1,
11424 channel: 9,
11425 epoch: 1,
11426 corr: 77,
11427 };
11428 let key = PendingKey {
11429 generation: 1,
11430 channel: 9,
11431 epoch: 2,
11432 corr: 77,
11433 };
11434 let (stale_tx, mut stale_response) = oneshot::channel();
11435 let (tx, mut response) = oneshot::channel();
11436 {
11437 let mut inner = shared.lock_inner();
11438 inner.writer = Some(writer);
11439 inner.daemon_ver = "0.39.0".into();
11440 inner.route_epochs.insert(9, current);
11441 inner
11442 .pending
11443 .insert(stale_key, PendingEntry::unary(stale_tx, false, None, None));
11444 inner
11445 .pending
11446 .insert(key, PendingEntry::unary(tx, false, None, None));
11447 }
11448
11449 assert!(dispatch_frame(&shared, 1, response_frame(9, 1, 77, b"stale".to_vec())).await);
11450 assert!(matches!(
11451 response.try_recv(),
11452 Err(oneshot::error::TryRecvError::Empty)
11453 ));
11454 assert!(matches!(
11455 stale_response.try_recv(),
11456 Err(oneshot::error::TryRecvError::Empty)
11457 ));
11458 assert!(shared.lock_inner().pending.contains_key(&stale_key));
11459 assert!(shared.lock_inner().pending.contains_key(&key));
11460 assert_eq!(shared.lock_inner().dropped_route_frames, 1);
11461
11462 assert!(dispatch_frame(&shared, 1, response_frame(9, 2, 77, b"current".to_vec())).await);
11463 let PendingResult::Terminal(PendingTerminal::Response { body, .. }) =
11464 response.await.unwrap()
11465 else {
11466 panic!("current epoch must settle its own pending request");
11467 };
11468 assert_eq!(body, b"current");
11469 assert!(shared.lock_inner().pending.contains_key(&stale_key));
11470 }
11471
11472 #[tokio::test]
11473 async fn route_poll_response_must_echo_expected_handle_before_settling() {
11474 let shared = Arc::new(reader_skew_tests::legacy_shared(
11475 PathBuf::from("/tmp/does-not-exist"),
11476 ConsumerOptions::default(),
11477 ));
11478 let (writer, _rx) = mpsc::channel(4);
11479 let handle = RouteHandle::new(3, 9, 1);
11480 let key = PendingKey {
11481 generation: 1,
11482 channel: 0,
11483 epoch: 0,
11484 corr: 88,
11485 };
11486 let (tx, mut response) = oneshot::channel();
11487 {
11488 let mut inner = shared.lock_inner();
11489 inner.writer = Some(writer);
11490 inner.daemon_ver = "0.39.0".into();
11491 inner.route_epochs.insert(handle.channel, handle);
11492 inner
11493 .pending
11494 .insert(key, PendingEntry::unary(tx, false, Some(handle), None));
11495 }
11496 let wrong = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11497 route_channel: handle.channel,
11498 route_epoch: handle.epoch + 1,
11499 status: Some("wrong".to_string()),
11500 live: Some(true),
11501 })
11502 .unwrap();
11503 assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, wrong)).await);
11504 assert!(matches!(
11505 response.try_recv(),
11506 Err(oneshot::error::TryRecvError::Empty)
11507 ));
11508 assert!(shared.lock_inner().pending.contains_key(&key));
11509
11510 let correct = serde_json::to_vec(&ClientControlResponse::RoutePoll {
11511 route_channel: handle.channel,
11512 route_epoch: handle.epoch,
11513 status: Some("ready".to_string()),
11514 live: Some(true),
11515 })
11516 .unwrap();
11517 assert!(dispatch_frame(&shared, 1, response_frame(0, 0, key.corr, correct)).await);
11518 assert!(matches!(
11519 response.await.unwrap(),
11520 PendingResult::Terminal(PendingTerminal::Response { .. })
11521 ));
11522 }
11523
11524 #[tokio::test]
11525 async fn stale_connection_handle_emits_no_request_cancel_or_goodbye() {
11526 let shared = Arc::new(reader_skew_tests::legacy_shared(
11527 PathBuf::from("/tmp/does-not-exist"),
11528 ConsumerOptions::default(),
11529 ));
11530 let (writer, mut rx) = mpsc::channel(4);
11531 let stale = RouteHandle::new(4, 1, 1);
11532 let current = RouteHandle::new(4, 1, 2);
11533 {
11534 let mut inner = shared.lock_inner();
11535 inner.generation = 2;
11536 inner.writer = Some(writer);
11537 inner.daemon_ver = "0.39.0".into();
11538 inner.route_epochs.insert(4, current);
11539 }
11540
11541 let err = shared
11542 .send_request(RequestSend {
11543 binary: false,
11544 expected_handle: Some(stale),
11545 channel: stale.channel,
11546 epoch: stale.epoch,
11547 body: b"request".to_vec(),
11548 priority: Priority::Interactive,
11549 admission_class: AdmissionClass::Normal,
11550 deadline: Instant::now() + Duration::from_millis(10),
11551 retain_late_route_open: false,
11552 route_open_reverse_requests: None,
11553 })
11554 .await
11555 .unwrap_err();
11556 assert!(matches!(err, CallError::StaleRouteHandle(handle) if handle == stale));
11557 shared.send_cancel(stale, 8, Priority::Interactive);
11558 assert!(!shared.send_route_goodbye(stale, false));
11559 assert!(
11560 rx.try_recv().is_err(),
11561 "stale operations must not queue frames"
11562 );
11563 }
11564
11565 #[tokio::test]
11566 async fn route_poll_refusal_preserves_daemon_code_message_and_detail() {
11567 let (shared, consumer, mut receiver) = route_open_stand_in(Box::new(|| 0.5));
11568 let handle = RouteHandle::new(3, 9, 1);
11569 shared
11570 .lock_inner()
11571 .route_epochs
11572 .insert(handle.channel, handle);
11573 let poll = consumer.poll_route(&handle, PollKind::Liveness, Duration::from_secs(1));
11574 tokio::pin!(poll);
11575 assert_pending(poll.as_mut()).await;
11576 let request = receiver.try_recv().unwrap();
11577 let refusal = ErrorBody {
11578 code: "unknown_route".into(),
11579 message: "the route is no longer present".into(),
11580 detail: Some(serde_json::json!({ "route_channel": 3, "route_epoch": 9 })),
11581 };
11582 assert!(
11583 dispatch_frame(
11584 &shared,
11585 1,
11586 channel_zero_frame(
11587 FrameType::Error,
11588 request.frame.header.corr,
11589 serde_json::to_vec(&refusal).unwrap(),
11590 ),
11591 )
11592 .await
11593 );
11594 let err = poll.await.unwrap_err();
11595 assert_eq!(err.code(), Some("unknown_route"));
11596 let CallError::Module(body) = err else {
11597 panic!("a delivered refusal must not be classified as a send failure");
11598 };
11599 assert_eq!(body.code, refusal.code);
11600 assert_eq!(body.message, refusal.message);
11601 assert_eq!(body.detail, refusal.detail);
11602 }
11603
11604 #[tokio::test]
11605 async fn late_route_open_queues_goodbye_and_full_queue_closes_connection() {
11606 let shared = Arc::new(reader_skew_tests::legacy_shared(
11607 PathBuf::from("/tmp/does-not-exist"),
11608 ConsumerOptions::default(),
11609 ));
11610 let (writer, mut rx) = mpsc::channel(2);
11611 let key = PendingKey {
11612 generation: 1,
11613 channel: 0,
11614 epoch: 0,
11615 corr: 41,
11616 };
11617 let (tx, response) = oneshot::channel();
11618 drop(response);
11619 {
11620 let mut inner = shared.lock_inner();
11621 inner.writer = Some(writer);
11622 inner.daemon_ver = "0.39.0".into();
11623 inner
11624 .pending
11625 .insert(key, PendingEntry::unary(tx, true, None, None));
11626 }
11627 let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11628 request_window: None,
11629 watch_window: None,
11630 route_channel: 12,
11631 route_epoch: 7,
11632 })
11633 .unwrap();
11634 assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 41, body)).await);
11635 let cleanup = rx.recv().await.unwrap().frame;
11636 assert_eq!(cleanup.header.ty, FrameType::Goodbye);
11637 assert_eq!((cleanup.header.channel, cleanup.header.epoch), (12, 7));
11638
11639 let shared = Arc::new(reader_skew_tests::legacy_shared(
11640 PathBuf::from("/tmp/does-not-exist"),
11641 ConsumerOptions {
11642 reconnect_backoff: RetryBackoff {
11643 max_attempts: 1,
11644 ..RetryBackoff::default()
11645 },
11646 ..ConsumerOptions::default()
11647 },
11648 ));
11649 let (writer, _rx) = mpsc::channel(1);
11650 let filler = response_frame(0, 0, 1, Vec::new());
11651 writer
11652 .try_send(WriteCommand {
11653 frame: filler,
11654 pending: None,
11655 })
11656 .unwrap();
11657 let key = PendingKey {
11658 generation: 1,
11659 channel: 0,
11660 epoch: 0,
11661 corr: 42,
11662 };
11663 let (tx, response) = oneshot::channel();
11664 drop(response);
11665 {
11666 let mut inner = shared.lock_inner();
11667 inner.writer = Some(writer);
11668 inner.daemon_ver = "0.39.0".into();
11669 inner
11670 .pending
11671 .insert(key, PendingEntry::unary(tx, true, None, None));
11672 }
11673 let body = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11674 request_window: None,
11675 watch_window: None,
11676 route_channel: 13,
11677 route_epoch: 8,
11678 })
11679 .unwrap();
11680 assert!(dispatch_frame(&shared, 1, response_frame(0, 0, 42, body)).await);
11681 assert!(shared.lock_inner().writer.is_none());
11682 }
11683
11684 #[tokio::test]
11685 async fn correlation_allocator_emits_max_once_then_closes_without_reuse() {
11686 let shared = Arc::new(reader_skew_tests::legacy_shared(
11687 PathBuf::from("/tmp/does-not-exist"),
11688 ConsumerOptions {
11689 reconnect_backoff: RetryBackoff {
11690 max_attempts: 1,
11691 ..RetryBackoff::default()
11692 },
11693 ..ConsumerOptions::default()
11694 },
11695 ));
11696 let (writer, mut rx) = mpsc::channel(4);
11697 {
11698 let mut inner = shared.lock_inner();
11699 inner.writer = Some(writer);
11700 inner.daemon_ver = "0.39.0".into();
11701 inner.next_corr = Some(u64::MAX);
11702 }
11703 let request_shared = Arc::clone(&shared);
11704 let request = tokio::spawn(async move {
11705 request_shared
11706 .send_request(RequestSend {
11707 binary: false,
11708 expected_handle: None,
11709 channel: 0,
11710 epoch: 0,
11711 body: Vec::new(),
11712 priority: Priority::Interactive,
11713 admission_class: AdmissionClass::Normal,
11714 deadline: Instant::now() + Duration::from_secs(1),
11715 retain_late_route_open: false,
11716 route_open_reverse_requests: None,
11717 })
11718 .await
11719 });
11720 let command = rx.recv().await.unwrap();
11721 assert_eq!(command.frame.header.corr, u64::MAX);
11722 assert!(dispatch_frame(&shared, 1, response_frame(0, 0, u64::MAX, Vec::new()),).await);
11723 assert!(request.await.unwrap().is_ok());
11724
11725 let exhausted = shared
11726 .send_request(RequestSend {
11727 binary: false,
11728 expected_handle: None,
11729 channel: 0,
11730 epoch: 0,
11731 body: Vec::new(),
11732 priority: Priority::Interactive,
11733 admission_class: AdmissionClass::Normal,
11734 deadline: Instant::now() + Duration::from_millis(10),
11735 retain_late_route_open: false,
11736 route_open_reverse_requests: None,
11737 })
11738 .await
11739 .unwrap_err();
11740 assert!(matches!(exhausted, CallError::NotSent(_)));
11741 assert!(rx.try_recv().is_err());
11742 assert!(shared.lock_inner().writer.is_none());
11743 }
11744
11745 #[tokio::test]
11746 async fn managed_call_deadline_bounds_flow_control_wait() {
11747 let shared = Arc::new(reader_skew_tests::legacy_shared(
11748 PathBuf::from("/tmp/does-not-exist"),
11749 ConsumerOptions::default(),
11750 ));
11751 let (writer, mut rx) = mpsc::channel(4);
11752 let target = RouteTarget::ToolProvider {
11753 module_id: "flow-controlled".to_string(),
11754 };
11755 let identity = BindIdentity::new("test".to_string(), "deadline".to_string());
11756 let consumer_identity = Some(ConsumerIdentity {
11757 module_id: "caller".to_string(),
11758 launch_nonce: "nonce".to_string(),
11759 });
11760 let first_opts = CallOptions {
11761 timeout: Duration::from_secs(1),
11762 consumer_identity: consumer_identity.clone(),
11763 ..CallOptions::default()
11764 };
11765 let second_opts = CallOptions {
11766 timeout: Duration::from_millis(25),
11767 consumer_identity,
11768 ..CallOptions::default()
11769 };
11770 let key = RouteKey::new(
11771 &target,
11772 &identity,
11773 first_opts.consumer_identity.as_ref(),
11774 None,
11775 );
11776 let handle = RouteHandle::new(5, 3, 1);
11777 {
11778 let mut inner = shared.lock_inner();
11779 inner.writer = Some(writer);
11780 inner.daemon_ver = "0.39.0".into();
11781 inner.cache_route(
11782 key,
11783 RouteState {
11784 handle,
11785 sem: Arc::new(Semaphore::new(1)),
11786 watch_sem: None,
11787 opted_in: false,
11788 },
11789 );
11790 }
11791
11792 let first = tokio::spawn({
11793 let consumer = SubcConsumer {
11794 shared: Arc::clone(&shared),
11795 };
11796 let target = target.clone();
11797 let identity = identity.clone();
11798 async move {
11799 consumer
11800 .call(target, identity, b"first".to_vec(), first_opts)
11801 .await
11802 }
11803 });
11804 let first_frame = rx
11805 .recv()
11806 .await
11807 .expect("the first request should enter the fake daemon queue");
11808 assert_eq!(first_frame.frame.header.ty, FrameType::Request);
11809 assert_eq!(first_frame.frame.body, b"first");
11810 assert!(shared.mark_pending_accepted(
11811 first_frame
11812 .pending
11813 .expect("request commands retain their pending key"),
11814 ));
11815
11816 let consumer = SubcConsumer {
11817 shared: Arc::clone(&shared),
11818 };
11819 let result = tokio::time::timeout(
11820 Duration::from_millis(250),
11821 consumer.call(target, identity, b"second".to_vec(), second_opts),
11822 )
11823 .await
11824 .expect("a flow-controlled call must finish at its own deadline")
11825 .unwrap_err();
11826 assert!(matches!(result, CallError::NotSent(_)));
11827 assert!(
11828 rx.try_recv().is_err(),
11829 "the timed-out second request must not reach the fake daemon"
11830 );
11831
11832 first.abort();
11833 let _ = first.await;
11834 }
11835
11836 #[tokio::test]
11837 async fn admitted_route_open_emits_one_frame_without_retrying_daemon_errors() {
11838 let shared = Arc::new(reader_skew_tests::legacy_shared(
11839 PathBuf::from("/tmp/does-not-exist"),
11840 ConsumerOptions {
11841 call_timeout: Duration::from_secs(1),
11842 ..ConsumerOptions::default()
11843 },
11844 ));
11845 let (writer, mut rx) = mpsc::channel(4);
11846 {
11847 let mut inner = shared.lock_inner();
11848 inner.writer = Some(writer);
11849 inner.daemon_ver = "0.39.0".into();
11850 }
11851
11852 let consumer = SubcConsumer {
11853 shared: Arc::clone(&shared),
11854 };
11855 let target = RouteTarget::ToolProvider {
11856 module_id: "admitted-target".to_string(),
11857 };
11858 let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11859 let task = tokio::spawn(async move {
11860 consumer
11861 .open_route_with_admission_facts(
11862 target,
11863 identity,
11864 serde_json::json!({"schema": 1, "verified_class": "member"}),
11865 )
11866 .await
11867 });
11868
11869 let command = rx.recv().await.expect("one route.open must be queued");
11870 let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11871 let ClientControlRequest::RouteOpen {
11872 admission_facts, ..
11873 } = request
11874 else {
11875 panic!("expected route.open")
11876 };
11877 assert_eq!(
11878 admission_facts,
11879 Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
11880 );
11881
11882 let error_body = serde_json::to_vec(&ErrorBody {
11883 code: "admission_facts_not_permitted".to_string(),
11884 message: "not permitted".to_string(),
11885 detail: None,
11886 })
11887 .unwrap();
11888 assert!(
11889 dispatch_frame(
11890 &shared,
11891 1,
11892 Frame::build(
11893 FrameType::Error,
11894 Flags::new(false, Priority::Interactive, false),
11895 0,
11896 0,
11897 command.frame.header.corr,
11898 error_body,
11899 )
11900 .unwrap(),
11901 )
11902 .await
11903 );
11904 let result = task.await.unwrap();
11905 assert!(matches!(result, Err(CallError::NotSent(_))));
11906 assert!(rx.try_recv().is_err(), "one-shot route.open must not retry");
11907 }
11908
11909 async fn open_admitted_route_for_test(
11912 opts: Option<CallOptions>,
11913 ) -> (
11914 Arc<Shared>,
11915 SubcConsumer,
11916 ClientControlRequest,
11917 Result<RouteHandle, CallError>,
11918 mpsc::Receiver<WriteCommand>,
11919 ) {
11920 let shared = writer_test_shared();
11921 let (writer, mut rx) = mpsc::channel(8);
11922 let generation = {
11923 let mut inner = shared.lock_inner();
11924 inner.writer = Some(writer);
11925 inner.daemon_ver = "0.39.0".into();
11926 inner.generation
11927 };
11928 let consumer = SubcConsumer {
11929 shared: Arc::clone(&shared),
11930 };
11931 let target = RouteTarget::ToolProvider {
11932 module_id: "cerebellum".to_string(),
11933 };
11934 let identity = BindIdentity::new("test".to_string(), "admitted".to_string());
11935 let facts = serde_json::json!({"schema": 1, "verified_class": "member"});
11936 let task = tokio::spawn(async move {
11939 let result = match opts {
11940 Some(opts) => {
11941 consumer
11942 .open_route_with_admission_facts_and_options(target, identity, facts, opts)
11943 .await
11944 }
11945 None => {
11946 consumer
11947 .open_route_with_admission_facts(target, identity, facts)
11948 .await
11949 }
11950 };
11951 (consumer, result)
11952 });
11953 let command = rx.recv().await.expect("one route.open must be queued");
11954 let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
11955 let response = serde_json::to_vec(&ClientControlResponse::RouteOpen {
11956 request_window: None,
11957 watch_window: None,
11958 route_channel: 21,
11959 route_epoch: 4,
11960 })
11961 .unwrap();
11962 assert!(
11963 dispatch_frame(
11964 &shared,
11965 generation,
11966 Frame::build(
11967 FrameType::Response,
11968 Flags::new(false, Priority::Interactive, false),
11969 0,
11970 0,
11971 command.frame.header.corr,
11972 response,
11973 )
11974 .unwrap(),
11975 )
11976 .await
11977 );
11978 let (consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
11979 .await
11980 .expect("admitted route.open resolves")
11981 .unwrap();
11982 (shared, consumer, request, result, rx)
11983 }
11984
11985 #[tokio::test]
11986 async fn admitted_route_open_refusal_keeps_the_daemon_code_and_detail() {
11987 let shared = writer_test_shared();
11988 let (writer, mut rx) = mpsc::channel(8);
11989 let generation = {
11990 let mut inner = shared.lock_inner();
11991 inner.writer = Some(writer);
11992 inner.daemon_ver = "0.39.0".into();
11993 inner.generation
11994 };
11995 let consumer = SubcConsumer {
11996 shared: Arc::clone(&shared),
11997 };
11998 let task = tokio::spawn(async move {
11999 let result = consumer
12000 .open_route_with_admission_facts(
12001 RouteTarget::ToolProvider {
12002 module_id: "cerebellum".to_string(),
12003 },
12004 BindIdentity::new("test".to_string(), "admitted".to_string()),
12005 serde_json::json!({"schema": 1, "verified_class": "member"}),
12006 )
12007 .await;
12008 (consumer, result)
12009 });
12010 let command = rx.recv().await.expect("one route.open must be queued");
12011 let refusal = ErrorBody {
12012 code: "module_warming".to_string(),
12013 message: "cerebellum is not ready".to_string(),
12014 detail: Some(serde_json::json!({"reason": "declared_not_ready"})),
12015 };
12016 assert!(
12017 dispatch_frame(
12018 &shared,
12019 generation,
12020 Frame::build(
12021 FrameType::Error,
12022 Flags::new(false, Priority::Interactive, false),
12023 0,
12024 0,
12025 command.frame.header.corr,
12026 serde_json::to_vec(&refusal).unwrap(),
12027 )
12028 .unwrap(),
12029 )
12030 .await
12031 );
12032 let (_consumer, result) = tokio::time::timeout(Duration::from_secs(1), task)
12033 .await
12034 .expect("admitted route.open resolves")
12035 .unwrap();
12036 let error = result.expect_err("a refused open is an error");
12037 assert!(
12038 error.is_not_sent(),
12039 "a refused open never reached the module: {error}"
12040 );
12041 let body = error
12042 .route_open_refusal()
12043 .unwrap_or_else(|| panic!("the refusal's code must survive: {error}"));
12044 assert_eq!(body.code, "module_warming");
12045 assert_eq!(
12046 body.detail,
12047 Some(serde_json::json!({"reason": "declared_not_ready"}))
12048 );
12049 assert!(
12050 error.to_string().contains("tool_provider:cerebellum"),
12051 "the error names its target: {error}"
12052 );
12053 }
12054
12055 #[tokio::test]
12056 async fn admitted_route_without_options_opens_and_declares_no_reverse_capabilities() {
12057 let (_shared, _consumer, request, result, _rx) = open_admitted_route_for_test(None).await;
12058 let ClientControlRequest::RouteOpen {
12059 consumer_capabilities,
12060 admission_facts,
12061 ..
12062 } = request
12063 else {
12064 panic!("expected route.open")
12065 };
12066 assert_eq!(consumer_capabilities, None);
12067 assert!(admission_facts.is_some());
12068 let handle = result.expect("admitted route opens");
12069 assert_eq!((handle.channel, handle.epoch), (21, 4));
12070 }
12071
12072 #[tokio::test]
12077 async fn admitted_route_with_options_delivers_elicitation_to_its_handler() {
12078 let opts = CallOptions::default();
12079 let seen = Arc::new(Mutex::new(None));
12080 let seen_by_handler = Arc::clone(&seen);
12081 let reply_body = br#"{"jsonrpc":"2.0","id":3,"result":{"action":"accept"}}"#.to_vec();
12082 let expected_reply = reply_body.clone();
12083 opts.reverse_requests
12084 .on_request("elicitation", move |body, ctx| {
12085 *seen_by_handler
12086 .lock()
12087 .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some((body, ctx.corr));
12088 let reply_body = reply_body.clone();
12089 async move { reply_body }
12090 })
12091 .unwrap();
12092
12093 let (shared, _consumer, request, result, mut rx) =
12094 open_admitted_route_for_test(Some(opts)).await;
12095 let ClientControlRequest::RouteOpen {
12096 consumer_capabilities,
12097 admission_facts,
12098 ..
12099 } = request
12100 else {
12101 panic!("expected route.open")
12102 };
12103 assert_eq!(consumer_capabilities, Some(vec!["elicitation".to_string()]));
12104 assert_eq!(
12105 admission_facts,
12106 Some(serde_json::json!({"schema": 1, "verified_class": "member"}))
12107 );
12108 let handle = result.expect("admitted route opens");
12109
12110 let request_body =
12111 br#"{"jsonrpc":"2.0","id":3,"method":"elicitation/create","params":{}}"#.to_vec();
12112 assert!(
12113 dispatch_frame(
12114 &shared,
12115 handle.connection_token(),
12116 reverse_request_frame(handle, 900, request_body.clone()),
12117 )
12118 .await
12119 );
12120 let reply = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12121 .await
12122 .expect("the handler replies")
12123 .unwrap()
12124 .frame;
12125 assert_eq!(reply.header.ty, FrameType::Response);
12126 assert_eq!(reply.header.corr, 900);
12127 assert_eq!(reply.header.channel, 21);
12128 assert_eq!(reply.body, expected_reply);
12129 assert_eq!(
12130 seen.lock()
12131 .unwrap_or_else(|poisoned| poisoned.into_inner())
12132 .clone(),
12133 Some((request_body, 900))
12134 );
12135 }
12136
12137 #[tokio::test]
12138 async fn route_open_waiter_deadline_is_not_sent_without_writing() {
12139 let shared = Arc::new(reader_skew_tests::legacy_shared(
12140 PathBuf::from("/tmp/does-not-exist"),
12141 ConsumerOptions::default(),
12142 ));
12143 let (writer, mut rx) = mpsc::channel(4);
12144 let target = RouteTarget::ToolProvider {
12145 module_id: "single-flight".to_string(),
12146 };
12147 let identity = BindIdentity::new("test".to_string(), "route-open".to_string());
12148 let opts = CallOptions {
12149 timeout: Duration::from_millis(25),
12150 consumer_identity: Some(ConsumerIdentity {
12151 module_id: "caller".to_string(),
12152 launch_nonce: "nonce".to_string(),
12153 }),
12154 ..CallOptions::default()
12155 };
12156 let key = RouteKey::new(&target, &identity, opts.consumer_identity.as_ref(), None);
12157 {
12158 let mut inner = shared.lock_inner();
12159 inner.writer = Some(writer);
12160 inner.daemon_ver = "0.39.0".into();
12161 inner.openings.insert(
12162 key,
12163 Opening {
12164 waiters: Vec::new(),
12165 closed: false,
12166 },
12167 );
12168 }
12169
12170 let consumer = SubcConsumer { shared };
12171 let result = tokio::time::timeout(
12172 Duration::from_millis(250),
12173 consumer.open_route(target, identity, opts),
12174 )
12175 .await
12176 .expect("a route.open waiter must finish at its own deadline")
12177 .unwrap_err();
12178 assert!(matches!(result, CallError::NotSent(_)));
12179 assert!(
12180 rx.try_recv().is_err(),
12181 "a timed-out route.open waiter must not write a control frame"
12182 );
12183 }
12184
12185 async fn managed_op_with_unanswered_route_open(subscribe: bool) -> CallError {
12191 let shared = Arc::new(reader_skew_tests::legacy_shared(
12192 PathBuf::from("/tmp/does-not-exist"),
12193 ConsumerOptions::default(),
12194 ));
12195 let (writer, mut rx) = mpsc::channel(4);
12196 {
12197 let mut inner = shared.lock_inner();
12198 inner.writer = Some(writer);
12199 inner.daemon_ver = "0.39.0".into();
12200 }
12201 let consumer = SubcConsumer {
12202 shared: Arc::clone(&shared),
12203 };
12204 let target = RouteTarget::ToolProvider {
12205 module_id: "slow-route-open".to_string(),
12206 };
12207 let identity = BindIdentity::new("test".to_string(), "slow-route-open".to_string());
12208 let task = tokio::spawn(async move {
12209 if subscribe {
12210 consumer
12211 .subscribe(
12212 target,
12213 identity,
12214 b"{}".to_vec(),
12215 SubscribeOptions {
12216 route_open_timeout: Duration::from_millis(200),
12217 route_retry_deadline: Duration::from_millis(100),
12218 ..SubscribeOptions::default()
12219 },
12220 )
12221 .await
12222 .map(|_| ())
12223 } else {
12224 consumer
12225 .call(
12226 target,
12227 identity,
12228 b"{}".to_vec(),
12229 CallOptions {
12230 timeout: Duration::from_millis(200),
12231 route_retry_deadline: Duration::from_millis(100),
12232 ..CallOptions::default()
12233 },
12234 )
12235 .await
12236 .map(|_| ())
12237 }
12238 });
12239
12240 let command = rx.recv().await.expect("route.open must be queued");
12244 assert_eq!(command.frame.header.channel, 0);
12245 let request: ClientControlRequest = serde_json::from_slice(&command.frame.body).unwrap();
12246 assert!(matches!(request, ClientControlRequest::RouteOpen { .. }));
12247 assert!(shared.mark_pending_accepted(command.pending.expect("route.open is tracked")));
12248
12249 let err = tokio::time::timeout(Duration::from_secs(2), task)
12250 .await
12251 .expect("the managed op must settle at its own deadline")
12252 .unwrap()
12253 .expect_err("an unanswered route.open cannot yield a route");
12254 while let Ok(command) = rx.try_recv() {
12255 assert_eq!(
12256 command.frame.header.channel, 0,
12257 "no data-plane frame may be written without an open route"
12258 );
12259 }
12260 err
12261 }
12262
12263 #[tokio::test]
12264 async fn call_whose_route_open_times_out_after_send_is_not_sent() {
12265 let err = managed_op_with_unanswered_route_open(false).await;
12266 assert!(
12267 matches!(err, CallError::NotSent(_)),
12268 "call body never left the client, got {err:?}"
12269 );
12270 }
12271
12272 #[tokio::test]
12273 async fn subscribe_whose_route_open_times_out_after_send_is_not_sent() {
12274 let err = managed_op_with_unanswered_route_open(true).await;
12275 assert!(
12276 matches!(err, CallError::NotSent(_)),
12277 "subscription request never left the client, got {err:?}"
12278 );
12279 }
12280
12281 #[tokio::test]
12282 async fn route_poll_deadline_bounds_writer_capacity() {
12283 let shared = Arc::new(reader_skew_tests::legacy_shared(
12284 PathBuf::from("/tmp/does-not-exist"),
12285 ConsumerOptions::default(),
12286 ));
12287 let (writer, mut rx) = mpsc::channel(1);
12288 let handle = RouteHandle::new(8, 4, 1);
12289 writer
12290 .try_send(WriteCommand {
12291 frame: response_frame(0, 0, 99, Vec::new()),
12292 pending: None,
12293 })
12294 .expect("the fake daemon queue should accept its filler frame");
12295 {
12296 let mut inner = shared.lock_inner();
12297 inner.writer = Some(writer);
12298 inner.daemon_ver = "0.39.0".into();
12299 inner.route_epochs.insert(handle.channel, handle);
12300 }
12301
12302 let consumer = SubcConsumer { shared };
12303 let result = tokio::time::timeout(
12304 Duration::from_millis(250),
12305 consumer.poll_route(&handle, PollKind::Liveness, Duration::from_millis(25)),
12306 )
12307 .await
12308 .expect("a control request must finish at its own deadline")
12309 .unwrap_err();
12310 assert!(matches!(result, CallError::NotSent(_)));
12311 assert_eq!(
12312 rx.recv()
12313 .await
12314 .expect("the filler must still be the only queued frame")
12315 .frame
12316 .header
12317 .corr,
12318 99
12319 );
12320 assert!(
12321 rx.try_recv().is_err(),
12322 "the timed-out control request must not reach the fake daemon"
12323 );
12324 }
12325
12326 #[tokio::test]
12327 async fn subscription_deadline_bounds_writer_capacity() {
12328 let shared = Arc::new(reader_skew_tests::legacy_shared(
12329 PathBuf::from("/tmp/does-not-exist"),
12330 ConsumerOptions::default(),
12331 ));
12332 let (writer, mut rx) = mpsc::channel(1);
12333 let handle = RouteHandle::new(9, 2, 1);
12334 let route_sem = Arc::new(Semaphore::new(1));
12335 writer
12336 .try_send(WriteCommand {
12337 frame: response_frame(0, 0, 100, Vec::new()),
12338 pending: None,
12339 })
12340 .expect("the fake daemon queue should accept its filler frame");
12341 {
12342 let mut inner = shared.lock_inner();
12343 inner.writer = Some(writer);
12344 inner.daemon_ver = "0.39.0".into();
12345 inner.cache_route(
12346 RouteKey::new(
12347 &RouteTarget::ToolProvider {
12348 module_id: "subscriptions".to_string(),
12349 },
12350 &BindIdentity::new("test".to_string(), "subscription".to_string()),
12351 None,
12352 None,
12353 ),
12354 RouteState {
12355 handle,
12356 sem: Arc::clone(&route_sem),
12357 watch_sem: None,
12358 opted_in: false,
12359 },
12360 );
12361 }
12362
12363 let consumer = SubcConsumer { shared };
12364 let result = tokio::time::timeout(
12365 Duration::from_millis(250),
12366 consumer.subscribe_route(
12367 &handle,
12368 b"subscribe".to_vec(),
12369 SubscribeOptions {
12370 route_open_timeout: Duration::from_millis(25),
12371 ..SubscribeOptions::default()
12372 },
12373 ),
12374 )
12375 .await
12376 .expect("a subscription must finish at its route-open deadline");
12377 let result = match result {
12378 Ok(_) => panic!("a subscription blocked before writing must time out"),
12379 Err(err) => err,
12380 };
12381 assert!(matches!(result, CallError::NotSent(_)));
12382 assert_eq!(
12383 rx.recv()
12384 .await
12385 .expect("the filler must still be the only queued frame")
12386 .frame
12387 .header
12388 .corr,
12389 100
12390 );
12391 assert!(
12392 rx.try_recv().is_err(),
12393 "the timed-out subscription must not reach the fake daemon"
12394 );
12395 assert!(
12396 route_sem.try_acquire().is_ok(),
12397 "a pre-write subscription timeout must release its route credit"
12398 );
12399 }
12400
12401 #[test]
12402 fn catalog_list_deserializes_golden_reply_and_ignores_unknown_fields() {
12403 let mut reply: serde_json::Value = serde_json::from_str(include_str!(
12404 "../../subc-control/tests/golden/client_control_response_catalog_list.json"
12405 ))
12406 .expect("the catalog.list golden reply must be valid JSON");
12407 reply["future_top_level"] = serde_json::json!(true);
12408 reply["modules"][0]["future_module_field"] = serde_json::json!("ignored");
12409
12410 let catalog: CatalogList =
12411 serde_json::from_value(reply).expect("catalog.list should tolerate additive fields");
12412 assert_eq!(catalog.generation, 7);
12413 assert_eq!(catalog.modules.len(), 1);
12414 assert!(catalog.subc_ops.iter().any(|op| op == "catalog.list"));
12415
12416 let tools = catalog.modules[0]
12417 .roles
12418 .iter()
12419 .find_map(|role| match role {
12420 subc_protocol::manifest::ProviderRole::ToolProvider { tools, .. } => Some(tools),
12421 _ => None,
12422 })
12423 .expect("the golden module must advertise a tool_provider role");
12424 let tool = tools
12425 .first()
12426 .expect("the golden tool_provider role must advertise a tool");
12427 assert!(!tool.name.is_empty());
12428 assert_eq!(
12429 tool.schema.get("type").and_then(serde_json::Value::as_str),
12430 Some("object")
12431 );
12432 assert!(matches!(
12433 tool.execution_mode,
12434 subc_protocol::manifest::ExecutionMode::Pure
12435 ));
12436 }
12437
12438 #[tokio::test]
12439 async fn catalog_list_sends_an_unfiltered_channel_zero_request() {
12440 let shared = Arc::new(reader_skew_tests::legacy_shared(
12441 PathBuf::from("/tmp/does-not-exist"),
12442 ConsumerOptions::default(),
12443 ));
12444 let (writer, mut rx) = mpsc::channel(1);
12445 shared.lock_inner().writer = Some(writer);
12446 shared.lock_inner().daemon_ver = "0.39.0".into();
12447
12448 let consumer = SubcConsumer {
12449 shared: Arc::clone(&shared),
12450 };
12451 let request = tokio::spawn(async move { consumer.catalog_list().await });
12452 let command = rx
12453 .recv()
12454 .await
12455 .expect("catalog.list must queue a channel-0 request");
12456 assert_eq!(command.frame.header.channel, 0);
12457 let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12458 assert_eq!(body["op"], "catalog.list");
12459 assert!(
12460 body.get("module_id").is_none(),
12461 "catalog.list must request the complete catalog without a module filter"
12462 );
12463
12464 let response = serde_json::to_vec(&ClientControlResponse::CatalogList {
12465 generation: 9,
12466 modules: Vec::new(),
12467 subc_ops: vec!["catalog.list".to_string()],
12468 })
12469 .unwrap();
12470 assert!(
12471 dispatch_frame(
12472 &shared,
12473 1,
12474 response_frame(0, 0, command.frame.header.corr, response),
12475 )
12476 .await
12477 );
12478 let catalog = request.await.unwrap().unwrap();
12479 assert_eq!(catalog.generation, 9);
12480 assert!(catalog.modules.is_empty());
12481 }
12482
12483 #[tokio::test]
12484 async fn spawn_snapshot_sends_a_channel_zero_request_and_returns_the_snapshot() {
12485 let shared = Arc::new(reader_skew_tests::legacy_shared(
12486 PathBuf::from("/tmp/does-not-exist"),
12487 ConsumerOptions::default(),
12488 ));
12489 let (writer, mut rx) = mpsc::channel(1);
12490 shared.lock_inner().writer = Some(writer);
12491 shared.lock_inner().daemon_ver = "0.39.0".into();
12492
12493 let consumer = SubcConsumer {
12494 shared: Arc::clone(&shared),
12495 };
12496 let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12497 let command = rx
12498 .recv()
12499 .await
12500 .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12501 assert_eq!(command.frame.header.channel, 0);
12502 let body: serde_json::Value = serde_json::from_slice(&command.frame.body).unwrap();
12503 assert_eq!(body["op"], "supervisor.spawn_snapshot");
12504
12505 let snapshot = SpawnSnapshot {
12506 cursor: SpawnCursor {
12507 daemon_incarnation: "incarnation-a".to_string(),
12508 seq: 41,
12509 },
12510 ring_bound: 256,
12511 live: vec![LiveSpawn {
12512 module_id: "participant".to_string(),
12513 spawn_generation: 3,
12514 pid: 4242,
12515 spawned_at_ms: 1_700_000_000_000,
12516 }],
12517 };
12518 let response = serde_json::to_vec(&ClientControlResponse::SupervisorSpawnSnapshot {
12519 snapshot: snapshot.clone(),
12520 })
12521 .unwrap();
12522 assert!(
12523 dispatch_frame(
12524 &shared,
12525 1,
12526 response_frame(0, 0, command.frame.header.corr, response),
12527 )
12528 .await
12529 );
12530 assert_eq!(request.await.unwrap().unwrap(), snapshot);
12531 }
12532
12533 #[tokio::test]
12534 async fn spawn_snapshot_refusal_keeps_the_daemon_code() {
12535 let shared = Arc::new(reader_skew_tests::legacy_shared(
12536 PathBuf::from("/tmp/does-not-exist"),
12537 ConsumerOptions::default(),
12538 ));
12539 let (writer, mut rx) = mpsc::channel(1);
12540 shared.lock_inner().writer = Some(writer);
12541 shared.lock_inner().daemon_ver = "0.39.0".into();
12542
12543 let consumer = SubcConsumer {
12544 shared: Arc::clone(&shared),
12545 };
12546 let request = tokio::spawn(async move { consumer.spawn_snapshot().await });
12547 let command = rx
12548 .recv()
12549 .await
12550 .expect("supervisor.spawn_snapshot must queue a channel-0 request");
12551 let refusal = serde_json::to_vec(&ErrorBody {
12552 code: "op_not_permitted".to_string(),
12553 message: "refused by the test".to_string(),
12554 detail: None,
12555 })
12556 .unwrap();
12557 let frame = Frame::build(
12558 FrameType::Error,
12559 Flags::new(false, Priority::Interactive, false),
12560 0,
12561 0,
12562 command.frame.header.corr,
12563 refusal,
12564 )
12565 .unwrap();
12566 assert!(dispatch_frame(&shared, 1, frame).await);
12567 let error = request.await.unwrap().unwrap_err();
12568 assert_eq!(error.code(), Some("op_not_permitted"));
12569 }
12570
12571 fn spawn_cursor(seq: u64) -> SpawnCursor {
12572 SpawnCursor {
12573 daemon_incarnation: "incarnation-a".to_string(),
12574 seq,
12575 }
12576 }
12577
12578 fn spawn_event(seq: u64, kind: SpawnEventKind, generation: u64) -> SpawnEvent {
12579 SpawnEvent {
12580 cursor: spawn_cursor(seq),
12581 kind,
12582 module_id: "participant".to_string(),
12583 spawn_generation: generation,
12584 pid: 4242,
12585 exit_code: (kind == SpawnEventKind::Exited).then_some(0),
12586 exit_signal: None,
12587 }
12588 }
12589
12590 fn channel_zero_frame(ty: FrameType, corr: u64, body: Vec<u8>) -> Frame {
12591 Frame::build(
12592 ty,
12593 Flags::new(false, Priority::Interactive, false),
12594 0,
12595 0,
12596 corr,
12597 body,
12598 )
12599 .unwrap()
12600 }
12601
12602 fn spawn_error_frame(corr: u64, code: &str, detail: serde_json::Value) -> Frame {
12603 channel_zero_frame(
12604 FrameType::Error,
12605 corr,
12606 serde_json::to_vec(&ErrorBody {
12607 code: code.to_string(),
12608 message: "sent by the test".to_string(),
12609 detail: Some(detail),
12610 })
12611 .unwrap(),
12612 )
12613 }
12614
12615 async fn spawn_subscribed(
12618 since: Option<SpawnCursor>,
12619 ) -> (
12620 Arc<Shared>,
12621 mpsc::Receiver<WriteCommand>,
12622 SpawnSubscription,
12623 Frame,
12624 ) {
12625 let shared = writer_test_shared();
12626 let (writer, mut rx) = mpsc::channel(8);
12627 shared.lock_inner().writer = Some(writer);
12628 shared.lock_inner().daemon_ver = "0.39.0".into();
12629 let consumer = SubcConsumer {
12630 shared: Arc::clone(&shared),
12631 };
12632 let subscription = consumer
12633 .spawn_subscribe(since)
12634 .await
12635 .expect("supervisor.spawn_subscribe must be sent");
12636 std::mem::forget(consumer);
12637 let command = rx
12638 .recv()
12639 .await
12640 .expect("supervisor.spawn_subscribe must queue a channel-0 request");
12641 (shared, rx, subscription, command.frame)
12642 }
12643
12644 #[tokio::test]
12645 async fn spawn_subscribe_sends_its_cursor_on_channel_zero_and_yields_events_until_stream_end() {
12646 let (shared, _rx, mut subscription, request) =
12647 spawn_subscribed(Some(spawn_cursor(7))).await;
12648 assert_eq!(request.header.channel, 0);
12649 assert_eq!(request.header.ty, FrameType::Request);
12650 let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12651 assert_eq!(
12652 body,
12653 serde_json::json!({
12654 "op": "supervisor.spawn_subscribe",
12655 "since": {"daemon_incarnation": "incarnation-a", "seq": 7},
12656 })
12657 );
12658
12659 let corr = request.header.corr;
12660 let events = [
12661 spawn_event(8, SpawnEventKind::Exited, 3),
12662 spawn_event(9, SpawnEventKind::Spawned, 4),
12663 ];
12664 for event in &events {
12665 let body = serde_json::to_vec(event).unwrap();
12666 assert!(
12667 dispatch_frame(
12668 &shared,
12669 1,
12670 channel_zero_frame(FrameType::StreamData, corr, body)
12671 )
12672 .await
12673 );
12674 }
12675 assert!(
12676 dispatch_frame(
12677 &shared,
12678 1,
12679 channel_zero_frame(FrameType::StreamEnd, corr, Vec::new())
12680 )
12681 .await
12682 );
12683 assert_eq!(subscription.next().await.unwrap(), Some(events[0].clone()));
12684 assert_eq!(subscription.next().await.unwrap(), Some(events[1].clone()));
12685 assert_eq!(subscription.next().await.unwrap(), None);
12686 assert_eq!(
12687 subscription.next().await.unwrap(),
12688 None,
12689 "a finished stream stays finished"
12690 );
12691 }
12692
12693 #[tokio::test]
12694 async fn spawn_subscribe_without_a_cursor_omits_since() {
12695 let (_shared, _rx, _subscription, request) = spawn_subscribed(None).await;
12696 let body: serde_json::Value = serde_json::from_slice(&request.body).unwrap();
12697 assert_eq!(
12698 body,
12699 serde_json::json!({"op": "supervisor.spawn_subscribe"})
12700 );
12701 }
12702
12703 #[tokio::test]
12704 async fn spawn_cursor_refusals_surface_as_coded_errors_with_their_detail() {
12705 let (shared, _rx, mut subscription, request) =
12706 spawn_subscribed(Some(spawn_cursor(7))).await;
12707 let frame = spawn_error_frame(
12708 request.header.corr,
12709 "spawn_cursor_incarnation_mismatch",
12710 serde_json::json!({"current_daemon_incarnation": "incarnation-b"}),
12711 );
12712 assert!(dispatch_frame(&shared, 1, frame).await);
12713 let error = subscription.next().await.unwrap_err();
12714 assert_eq!(error.code(), Some("spawn_cursor_incarnation_mismatch"));
12715 let SpawnStreamError::CursorIncarnationMismatch {
12716 current_daemon_incarnation,
12717 body,
12718 } = &error
12719 else {
12720 panic!("expected the incarnation refusal, got {error:?}");
12721 };
12722 assert_eq!(current_daemon_incarnation, "incarnation-b");
12723 assert_eq!(body.code, "spawn_cursor_incarnation_mismatch");
12724 assert_eq!(subscription.next().await.unwrap(), None);
12725
12726 let (shared, _rx, mut subscription, request) =
12727 spawn_subscribed(Some(spawn_cursor(1))).await;
12728 let frame = spawn_error_frame(
12729 request.header.corr,
12730 "spawn_cursor_too_old",
12731 serde_json::json!({"oldest_retained_cursor": spawn_cursor(90)}),
12732 );
12733 assert!(dispatch_frame(&shared, 1, frame).await);
12734 let error = subscription.next().await.unwrap_err();
12735 assert_eq!(error.code(), Some("spawn_cursor_too_old"));
12736 let SpawnStreamError::CursorTooOld {
12737 oldest_retained_cursor,
12738 ..
12739 } = &error
12740 else {
12741 panic!("expected the too-old refusal, got {error:?}");
12742 };
12743 assert_eq!(oldest_retained_cursor, &spawn_cursor(90));
12744 }
12745
12746 #[tokio::test]
12747 async fn a_lagged_spawn_stream_yields_its_queued_events_then_the_lag_error() {
12748 let (shared, _rx, mut subscription, request) =
12749 spawn_subscribed(Some(spawn_cursor(7))).await;
12750 let corr = request.header.corr;
12751 let queued = spawn_event(8, SpawnEventKind::Exited, 3);
12752 assert!(
12753 dispatch_frame(
12754 &shared,
12755 1,
12756 channel_zero_frame(
12757 FrameType::StreamData,
12758 corr,
12759 serde_json::to_vec(&queued).unwrap()
12760 ),
12761 )
12762 .await
12763 );
12764 let frame = spawn_error_frame(
12765 corr,
12766 "spawn_subscriber_lagged",
12767 serde_json::json!({"first_undelivered_cursor": spawn_cursor(9)}),
12768 );
12769 assert!(dispatch_frame(&shared, 1, frame).await);
12770 assert_eq!(subscription.next().await.unwrap(), Some(queued));
12771 let error = subscription.next().await.unwrap_err();
12772 assert_eq!(error.code(), Some("spawn_subscriber_lagged"));
12773 let SpawnStreamError::SubscriberLagged {
12774 first_undelivered_cursor,
12775 ..
12776 } = &error
12777 else {
12778 panic!("expected the lag error, got {error:?}");
12779 };
12780 assert_eq!(first_undelivered_cursor, &spawn_cursor(9));
12781 }
12782
12783 #[tokio::test]
12784 async fn dropping_a_spawn_subscription_sends_a_channel_zero_cancel_for_its_corr() {
12785 let (_shared, mut rx, subscription, request) =
12786 spawn_subscribed(Some(spawn_cursor(7))).await;
12787 drop(subscription);
12788 let cancel = tokio::time::timeout(Duration::from_secs(1), rx.recv())
12789 .await
12790 .expect("dropping the subscription must queue a Cancel")
12791 .expect("the writer stays open");
12792 assert_eq!(cancel.frame.header.ty, FrameType::Cancel);
12793 assert_eq!(cancel.frame.header.channel, 0);
12794 assert_eq!(cancel.frame.header.corr, request.header.corr);
12795 }
12796
12797 #[tokio::test]
12798 async fn reconnect_completion_between_wait_decision_and_registration_wakes_caller() {
12799 let shared = Arc::new(reader_skew_tests::legacy_shared(
12800 PathBuf::from("/tmp/subc-client-rs-reconnect-wakeup"),
12801 ConsumerOptions::default(),
12802 ));
12803 let (sender, _receiver) = mpsc::channel(EGRESS_BUFFER);
12804 {
12805 let mut inner = shared.lock_inner();
12806 inner.reconnect = ReconnectState::Inline {
12807 generation: inner.generation,
12808 };
12809 }
12810 let completing = Arc::clone(&shared);
12811 *shared.before_wait.lock().unwrap() = Some(Box::new(move || {
12812 completing.lock_inner().writer = Some(sender);
12813 completing.lock_inner().daemon_ver = "0.39.0".into();
12814 completing.notify.notify_waiters();
12815 }));
12816
12817 let result = shared
12818 .ensure_connected_for_call(Instant::now() + Duration::from_millis(30))
12819 .await;
12820 assert!(
12821 result.is_ok(),
12822 "connected caller should not time out: {result:?}"
12823 );
12824 assert!(shared.before_wait.lock().unwrap().is_none());
12825 }
12826
12827 #[tokio::test]
12828 async fn catalog_list_deadline_is_not_sent_when_reconnection_stays_down() {
12829 let shared = Arc::new(reader_skew_tests::legacy_shared(
12830 PathBuf::from("/tmp/subc-client-rs-catalog-list-unavailable"),
12831 ConsumerOptions {
12832 call_timeout: Duration::from_millis(25),
12833 reconnect_backoff: RetryBackoff {
12834 base: Duration::from_millis(1),
12835 cap: Duration::from_millis(1),
12836 max_attempts: 100,
12837 },
12838 ..ConsumerOptions::default()
12839 },
12840 ));
12841 let consumer = SubcConsumer { shared };
12842 let result = tokio::time::timeout(Duration::from_millis(250), consumer.catalog_list())
12843 .await
12844 .expect("catalog.list must finish at its configured deadline")
12845 .unwrap_err();
12846 assert!(matches!(result, CallError::NotSent(_)));
12847 }
12848
12849 fn consumer_with_malformed_connection_file(
12850 ) -> (cortexkit_test_support::ScratchDir, SubcConsumer) {
12851 let temp = cortexkit_test_support::ScratchDir::new("consumer-malformed-connection");
12852 let path = temp.path().join("connection.json");
12853 std::fs::write(&path, b"not JSON").unwrap();
12854 #[cfg(unix)]
12855 {
12856 use std::os::unix::fs::PermissionsExt;
12857 std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
12858 }
12859 let shared = Arc::new(reader_skew_tests::legacy_shared(
12860 path,
12861 ConsumerOptions {
12862 call_timeout: Duration::from_millis(100),
12863 reconnect_backoff: RetryBackoff {
12864 base: Duration::from_millis(20),
12865 cap: Duration::from_millis(40),
12866 max_attempts: 6,
12867 },
12868 ..ConsumerOptions::default()
12869 },
12870 ));
12871 (temp, SubcConsumer { shared })
12872 }
12873
12874 #[tokio::test]
12877 async fn catalog_list_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12878 let (_temp, consumer) = consumer_with_malformed_connection_file();
12879 let call = consumer.catalog_list();
12880 tokio::pin!(call);
12881 assert_pending(call.as_mut()).await;
12882 consumer.close().await;
12883 let err = call.await.unwrap_err();
12884 assert!(matches!(err, CallError::NotSent(_)));
12885 assert!(err.to_string().contains("consumer closed"));
12886 }
12887
12888 #[tokio::test]
12889 async fn spawn_snapshot_backs_off_after_malformed_connection_file_and_close_cancels_it() {
12890 let (_temp, consumer) = consumer_with_malformed_connection_file();
12891 let call = consumer.spawn_snapshot();
12892 tokio::pin!(call);
12893 assert_pending(call.as_mut()).await;
12894 consumer.close().await;
12895 let err = call.await.unwrap_err();
12896 assert!(matches!(err, CallError::NotSent(_)));
12897 assert!(err.to_string().contains("consumer closed"));
12898 }
12899}
12900
12901#[cfg(test)]
12902mod launch_nonce_redaction_tests {
12903 use super::*;
12904
12905 const NONCE: &str = "nonce-f00dfeed1234abcd";
12906
12907 #[test]
12908 fn option_types_and_route_keys_never_print_the_nonce() {
12909 let identity = ConsumerIdentity {
12910 module_id: "wernicke".to_string(),
12911 launch_nonce: NONCE.to_string(),
12912 };
12913 let call = CallOptions {
12914 consumer_identity: Some(identity.clone()),
12915 ..CallOptions::default()
12916 };
12917 let key = ConsumerIdentityKey::from(&identity);
12918 for printed in [format!("{call:?}"), format!("{key:?}")] {
12919 assert!(!printed.contains(NONCE), "launch nonce printed: {printed}");
12920 }
12921 }
12922}