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