1#![forbid(unsafe_code)]
2
3pub mod activity;
4mod agent_commands;
5pub mod config;
6mod control_ops;
7pub use agent_commands::AgentCommandsError;
8pub use subc_protocol::session::{AgentCommandFinished, AgentCommandRoot};
9pub mod consumer;
10mod operator_app;
11pub mod policy_cache;
12#[cfg(any(test, feature = "test-support"))]
13mod stand_in;
14#[cfg(feature = "test-support")]
15pub mod test_support;
16pub use activity::*;
17pub use consumer::{
18 is_retryable_route_open_code, AppOpenError, CallError, CallOptions, CallReply, CancelHandle,
19 CancelOutcome, CatalogList, CatalogSubscription, CloseRouteOptions, ConnectionFacts,
20 ConnectionState, ConsumerCapabilityError, ConsumerError, ConsumerOptions, ControlPush,
21 CorrelationId, HealthProbeResponse, NotSentCause, OutcomeUnknownCause, PendingReply, PushEvent,
22 RequestBody, RequestReservation, RetryBackoff, ReverseRequestContext, ReverseRequestError,
23 ReverseRequestRegistrationError, ReverseRequestRegistry, RouteCloseDisposition,
24 RouteCloseReason, RouteEndReason, RouteOpenTarget, RouteOpenTargetKind, RoutePollResult,
25 ScopeBindProofRefusal, ScopeSelector, ServerDescription, SpawnStreamError, SpawnSubscription,
26 StderrTailResponse, SubcConsumer, SubscribeOptions, Subscription, SubscriptionClosed,
27 SubscriptionEnd, SupervisorAck, SupervisorEntry, SupervisorHealthResponse,
28 SupervisorListResponse, SupervisorProvenanceResponse, ACCEPTED_CLOSE_REASONS,
29 DEFAULT_CALL_TIMEOUT, DEFAULT_LIVENESS_PROBE_WINDOW, DEFAULT_ROUTE_RETRY_DEADLINE,
30 SPAWN_CURSOR_INCARNATION_MISMATCH, SPAWN_CURSOR_TOO_OLD, SPAWN_SUBSCRIBER_LAGGED,
31};
32pub use operator_app::{operator_app_candidates, operator_app_path, OperatorAppPathError};
33pub use policy_cache::{
34 PolicyResolveError, PolicyResolver, PolicyResolverConfig, PolicyResolverFootprint,
35 PolicyVerdict, ProjectRef, Subject, DEFAULT_POLICY_RESOLVER_MODULE_ID,
36};
37pub use subc_control::{AppOpenReply, AppOpenStatus, CatalogOrigin, CatalogWatchResponse};
38pub use subc_control::{
39 ScopeRef, ScopeWatchEvent, ScopeWatchPush, ScopeWatchResponse, ScopeWatchSelector,
40 ScopeWatchState, ScopeWatchStatus,
41};
42
43mod module_subscription;
44pub use module_subscription::ScopeSubscription;
45
46use std::{
47 collections::{BTreeMap, HashMap, VecDeque},
48 env,
49 error::Error,
50 ffi::OsString,
51 fmt,
52 future::Future,
53 io,
54 panic::{catch_unwind, AssertUnwindSafe},
55 path::{Path, PathBuf},
56 pin::Pin,
57 sync::{
58 atomic::{AtomicBool, AtomicU64, Ordering},
59 Arc, Mutex,
60 },
61 time::{Duration, SystemTime, UNIX_EPOCH},
62};
63
64pub use async_trait::async_trait;
65pub use subc_control::{CatalogEntry, ConsumerIdentity};
66mod scope_served_by;
67pub use scope_served_by::{ScopeServedByAnswer, ScopeServedByReply};
68pub mod registration;
69mod route_authorize;
70pub use route_authorize::{
71 RouteAuthorizeExpected, RouteAuthorizeOutcome, RouteAuthorizeResponse, RouteAuthorizeScope,
72};
73mod request_pools;
74pub use registration::ClaimError;
75use request_pools::{wait_for_permit, DispatchPools, PermitWaitOutcome, WaitingRequest};
76pub use request_pools::{RequestClass, RequestPool, RequestPoolSnapshot, RequestPools};
77pub use subc_os::launch_nonce;
84use subc_protocol::{
85 call_mode::derive_call_mode,
86 error_codes,
87 manifest::ModuleManifest,
88 scope::{
89 ScopeEnd, ScopeEndResult, ScopeEnded, ScopeRecord, ScopeRecordResult, ScopeStamp,
90 ScopeStatus, SCOPE_APPLY_OP, SCOPE_DESCRIBE_OP, SCOPE_SYNC_OP,
91 },
92 session::{
93 ModuleControlCommand, ModuleControlRequest, ModuleControlRequestFromModule,
94 ModuleControlResponse, ModuleControlResponseToModule, OperatorConfirmKind,
95 OperatorConfirmReply, OperatorConfirmRequest, MODULE_CONTROL_OP_HEALTH_CHECK,
96 MODULE_TO_SUBC_OP_CATALOG_UPDATE, MODULE_TO_SUBC_OP_CATALOG_UPDATE_ROLE_DECLARATIONS,
97 },
98 BindIdentity, ErrorBody, Flags, Frame, FrameBuildError, FrameType, ModuleHelloAckBody,
99 ModuleHelloBody, Principal, Priority, RouteTarget, PROTOCOL_VERSION, SUBC_MODULE_ID_ENV,
100};
101pub use subc_protocol::{
102 call_mode::{CallMode, CALL_MODES_CAPABILITY},
103 manifest::{
104 build_provenance, CapabilityDeclarations, CapabilityNeed, CapabilityRequirement,
105 ExecutionMode, LaunchNonceSource, ManifestProvenance, ProvenanceFormError, ProviderRole,
106 Tool, PROVENANCE_SENTINELS,
107 },
108 session::{HealthReport, HealthStatus},
109 AdmissionClass, MachineId, SUBC_PROTOCOL_CRATE_VERSION,
110};
111pub use subc_transport::connection_file::{
112 discover, discovery_candidates, Discovered, DiscoveryError,
113};
114
115use subc_transport::{
116 authenticate_client, connection_file, read_frame, write_frame, AuthError, ConnectionFileError,
117 FrameIoError,
118};
119use tokio::{
120 io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, BufWriter},
121 net::TcpStream,
122 sync::{mpsc, oneshot},
123 time::{timeout, timeout_at, Instant},
124};
125use tokio_util::{
126 sync::{CancellationToken, WaitForCancellationFuture},
127 task::TaskTracker,
128};
129
130const AUTH_DEADLINE: Duration = Duration::from_secs(2);
131const CATALOG_UPDATE_TIMEOUT: Duration = Duration::from_secs(10);
132const OPERATOR_CONFIRM_TIMEOUT: Duration = Duration::from_secs(290);
133const OPERATOR_CONFIRM_OP: &str = "operator.confirm";
134const EGRESS_BUFFER: usize = 64;
135const HANDLER_TASK_CAPACITY: usize = 64;
136const DISPATCH_SATURATION_WAIT: Duration = Duration::from_secs(2);
139const HELLO_CORR: u64 = 1;
140const DEFAULT_WRITER_DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
141const DRAINING_HOOK_START_LIMIT: Duration = Duration::from_secs(2);
149static NEXT_MODULE_CONNECTION_TOKEN: AtomicU64 = AtomicU64::new(1);
150const DETACHED_CONNECTION_TOKEN: u64 = 0;
154
155type RequestKey = (u16, u32, u64);
156type InFlight = Arc<Mutex<HashMap<RequestKey, CancellationToken>>>;
157
158#[derive(Clone, Copy)]
164pub struct RouteHandle {
165 pub channel: u16,
166 pub epoch: u32,
167 connection_token: u64,
168 reverse_request_registry_id: u64,
169}
170
171impl RouteHandle {
172 pub fn detached(channel: u16, epoch: u32) -> Self {
186 Self::new(channel, epoch, DETACHED_CONNECTION_TOKEN)
187 }
188
189 pub(crate) fn new(channel: u16, epoch: u32, connection_token: u64) -> Self {
190 Self {
191 channel,
192 epoch,
193 connection_token,
194 reverse_request_registry_id: 0,
195 }
196 }
197
198 pub(crate) fn new_consumer(
199 channel: u16,
200 epoch: u32,
201 connection_token: u64,
202 reverse_requests: ReverseRequestRegistry,
203 ) -> Self {
204 reverse_requests.seal();
205 Self {
206 channel,
207 epoch,
208 connection_token,
209 reverse_request_registry_id: consumer::install_reverse_request_registry(
210 reverse_requests,
211 ),
212 }
213 }
214
215 pub(crate) fn connection_token(self) -> u64 {
216 self.connection_token
217 }
218
219 pub fn on_request<F, Fut>(
220 &self,
221 method_family: impl Into<String>,
222 handler: F,
223 ) -> Result<(), ReverseRequestRegistrationError>
224 where
225 F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
226 Fut: Future<Output = Vec<u8>> + Send + 'static,
227 {
228 consumer::route_reverse_request_registry(self.reverse_request_registry_id)?
229 .on_request(method_family, handler)
230 }
231
232 pub fn on_request_fallible<F, Fut>(
233 &self,
234 method_family: impl Into<String>,
235 handler: F,
236 ) -> Result<(), ReverseRequestRegistrationError>
237 where
238 F: Fn(Vec<u8>, ReverseRequestContext) -> Fut + Send + Sync + 'static,
239 Fut: Future<Output = Result<Vec<u8>, ReverseRequestError>> + Send + 'static,
240 {
241 consumer::route_reverse_request_registry(self.reverse_request_registry_id)?
242 .on_request_fallible(method_family, handler)
243 }
244
245 pub(crate) fn reverse_request_registry_id(self) -> u64 {
246 self.reverse_request_registry_id
247 }
248}
249
250impl PartialEq for RouteHandle {
251 fn eq(&self, other: &Self) -> bool {
252 self.channel == other.channel
253 && self.epoch == other.epoch
254 && self.connection_token == other.connection_token
255 }
256}
257
258impl Eq for RouteHandle {}
259
260impl std::hash::Hash for RouteHandle {
261 fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
262 std::hash::Hash::hash(&self.channel, state);
263 std::hash::Hash::hash(&self.epoch, state);
264 std::hash::Hash::hash(&self.connection_token, state);
265 }
266}
267
268impl fmt::Debug for RouteHandle {
269 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
270 f.debug_struct("RouteHandle")
271 .field("channel", &self.channel)
272 .field("epoch", &self.epoch)
273 .finish_non_exhaustive()
274 }
275}
276#[derive(Debug, Clone, PartialEq, Eq)]
278pub struct LiveRootsSnapshot {
279 pub roots: Vec<subc_protocol::session::LiveRoot>,
280 pub unknown_root_bindings: u64,
281 pub total_bindings: u64,
282}
283
284#[derive(Debug, Clone, PartialEq, Eq)]
289#[non_exhaustive]
290pub struct ScopeSyncReply {
291 pub generation: u64,
293 pub results: Vec<ScopeRecordResult>,
297 pub ended: Vec<ScopeEnded>,
300}
301
302#[derive(Debug, Clone, PartialEq, Eq)]
306#[non_exhaustive]
307pub struct ScopeApplyReply {
308 pub generation: u64,
310 pub results: Vec<ScopeRecordResult>,
312 pub end_results: Vec<ScopeEndResult>,
315 pub ended: Vec<ScopeEnded>,
318}
319
320#[derive(Debug, Clone, PartialEq, Eq)]
323#[non_exhaustive]
324pub struct ScopeDescribeReply {
325 pub status: ScopeStatus,
326 pub scope_epoch: Option<u64>,
328 pub daemon_incarnation: String,
331 pub owner_synced: bool,
333 pub owner_configured: bool,
335 pub scope: Option<ScopeStamp>,
339}
340
341#[derive(Debug, serde::Deserialize)]
344#[serde(untagged)]
345enum ModuleControlReply {
346 Control(Box<ModuleControlResponseToModule>),
347 RouteAuthorize(RouteAuthorizeResponse),
348}
349
350impl ModuleControlReply {
351 fn control(self) -> Result<ModuleControlResponseToModule, CatalogUpdateError> {
352 match self {
353 Self::Control(reply) => Ok(*reply),
354 other => Err(CatalogUpdateError::Protocol(format!(
355 "unexpected module control response: {other:?}"
356 ))),
357 }
358 }
359}
360
361type CatalogUpdateReply = oneshot::Sender<Result<ModuleControlReply, CatalogUpdateError>>;
362type CatalogUpdateWaiter = oneshot::Receiver<Result<ModuleControlReply, CatalogUpdateError>>;
363type CatalogUpdateRequest = (u64, mpsc::Sender<Frame>, CatalogUpdateWaiter);
364type OperatorConfirmRequestWaiter = (u64, mpsc::Sender<Frame>, oneshot::Receiver<Frame>);
365
366pub type ModuleServeFuture = Pin<Box<dyn Future<Output = Result<(), SubcModuleError>> + Send>>;
368
369#[derive(Clone)]
370struct RequestDispatcher {
371 in_flight: InFlight,
372 control_slots: Arc<tokio::sync::Semaphore>,
373 pools: Arc<DispatchPools>,
376 draining_hooks: Arc<Mutex<Vec<oneshot::Receiver<()>>>>,
381 undecodable_push_logged: Arc<AtomicBool>,
384 failure: Arc<Mutex<Option<SubcModuleError>>>,
385 failed: CancellationToken,
386 tasks: TaskTracker,
387 aborts: Arc<Mutex<Vec<tokio::task::AbortHandle>>>,
388 undelivered_replies: Arc<AtomicU64>,
389}
390
391impl RequestDispatcher {
392 #[cfg(test)]
395 fn new() -> Self {
396 Self::with_pools(Arc::new(DispatchPools::new(RequestPools::new())))
397 }
398
399 fn with_pools(pools: Arc<DispatchPools>) -> Self {
400 Self {
401 in_flight: Arc::new(Mutex::new(HashMap::new())),
402 control_slots: Arc::new(tokio::sync::Semaphore::new(16)),
403 pools,
404 draining_hooks: Arc::new(Mutex::new(Vec::new())),
405 undecodable_push_logged: Arc::new(AtomicBool::new(false)),
406 failure: Arc::new(Mutex::new(None)),
407 failed: CancellationToken::new(),
408 tasks: TaskTracker::new(),
409 aborts: Arc::new(Mutex::new(Vec::new())),
410 undelivered_replies: Arc::new(AtomicU64::new(0)),
411 }
412 }
413
414 fn fail(&self, error: SubcModuleError) {
415 let mut failure = self.failure.lock().unwrap_or_else(|e| e.into_inner());
416 if failure.is_none() {
417 *failure = Some(error);
418 }
419 self.failed.cancel();
420 }
421
422 fn take_failure(&self) -> Option<SubcModuleError> {
423 self.failure
424 .lock()
425 .unwrap_or_else(|e| e.into_inner())
426 .take()
427 }
428
429 fn spawn(&self, future: impl Future<Output = ()> + Send + 'static) {
430 let task = self.tasks.spawn(future);
431 let mut aborts = self.aborts.lock().unwrap_or_else(|e| e.into_inner());
432 aborts.retain(|task| !task.is_finished());
433 aborts.push(task.abort_handle());
434 }
435
436 fn abort_all(&self) {
437 for task in self
438 .aborts
439 .lock()
440 .unwrap_or_else(|e| e.into_inner())
441 .drain(..)
442 {
443 task.abort();
444 }
445 }
446
447 fn fold_health(&self, mut report: HealthReport) -> HealthReport {
448 if let Some(saturation) = self.pools.saturation() {
449 if report.status == HealthStatus::Ok {
450 report.status = HealthStatus::Degraded;
451 }
452 report.detail = Some(match report.detail {
453 Some(detail) => format!("{saturation}; {detail}"),
454 None => saturation,
455 });
456 }
457 report
458 }
459
460 async fn wait_for_draining_hooks_to_start(&self) {
464 let started = std::mem::take(
465 &mut *self
466 .draining_hooks
467 .lock()
468 .unwrap_or_else(|poisoned| poisoned.into_inner()),
469 );
470 let deadline = tokio::time::Instant::now() + DRAINING_HOOK_START_LIMIT;
471 for hook in started {
472 if tokio::time::timeout_at(deadline, hook).await.is_err() {
475 return;
476 }
477 }
478 }
479
480 fn cancel_all(&self) {
485 self.pools.close();
486 let cancelled = match self.in_flight.lock() {
487 Ok(guard) => guard.values().cloned().collect::<Vec<_>>(),
488 Err(poisoned) => poisoned.into_inner().values().cloned().collect(),
489 };
490 for cancellation in cancelled {
491 cancellation.cancel();
492 }
493 }
494}
495
496#[derive(Clone)]
498pub struct ModuleHandle {
499 shared: Arc<ModuleHandleShared>,
500}
501
502struct ModuleHandleShared {
503 registration: registration::Session,
504 negotiated_ver: u8,
505 daemon_capabilities: Vec<String>,
506 supports_catalog_update: bool,
507 supports_role_declarations_update: bool,
508 supports_live_roots: bool,
509 supports_agent_commands: bool,
510 supports_scope_sync: bool,
511 supports_scope_apply: bool,
512 supports_scope_describe: bool,
513 supports_scope_watch: bool,
514 supports_route_authorize: bool,
515 supports_operator_confirm: bool,
516 supports_activity: bool,
517 connection_runtime: tokio::runtime::Handle,
518 connection_token: u64,
519 machine_id: Option<MachineId>,
520 live_routes: Mutex<HashMap<u16, RouteHandle>>,
521 dropped_route_frames: AtomicU64,
522 close_token: CancellationToken,
523 dispatch_pools: Mutex<Arc<DispatchPools>>,
526 catalog_send: tokio::sync::Mutex<()>,
527 config: config::Session,
528 served_control_ops: std::sync::OnceLock<Vec<String>>,
529 inner: Mutex<ModuleHandleState>,
530}
531
532struct ModuleHandleState {
533 pending_control_streams: HashMap<u64, module_subscription::ControlStreamSender>,
534 pending_claim_calls: HashMap<u64, oneshot::Sender<Frame>>,
535 writer: Option<mpsc::Sender<Frame>>,
536 next_corr: Option<u64>,
537 pending_catalog_updates: HashMap<u64, CatalogUpdateReply>,
538 pending_operator_confirms: HashMap<u64, oneshot::Sender<Frame>>,
539 pending_activity_records: HashMap<u64, oneshot::Sender<Frame>>,
540 pending_scope_served_by: HashMap<u64, oneshot::Sender<Frame>>,
541 pending_config_calls: HashMap<u64, oneshot::Sender<Frame>>,
542 pending_agent_commands: HashMap<u64, oneshot::Sender<Frame>>,
543 current_provides: Option<Vec<ProviderRole>>,
544 catalog_changes: VecDeque<CatalogChange>,
545 closed: bool,
546}
547
548struct CatalogChange {
549 corr: u64,
550 provides: Vec<ProviderRole>,
551 outcome: Option<CatalogChangeOutcome>,
552}
553
554enum CatalogChangeOutcome {
555 Accepted,
556 Rejected,
557 Unknown,
558}
559
560struct CatalogUpdateGuard {
561 shared: Arc<ModuleHandleShared>,
562 corr: u64,
563}
564
565impl Drop for CatalogUpdateGuard {
566 fn drop(&mut self) {
567 self.shared.remove_pending_catalog_update(self.corr);
568 }
569}
570
571impl ModuleHandle {
572 fn new(
573 ack: &ModuleHelloAckBody,
574 writer: mpsc::Sender<Frame>,
575 connection_token: u64,
576 close_token: CancellationToken,
577 connection_runtime: tokio::runtime::Handle,
578 ) -> Self {
579 Self {
580 shared: Arc::new(ModuleHandleShared {
581 registration: registration::Session::default(),
582 negotiated_ver: ack.negotiated_ver,
583 daemon_capabilities: ack.subc_capabilities.clone(),
584 supports_catalog_update: ack
585 .subc_ops
586 .iter()
587 .any(|op| op == MODULE_TO_SUBC_OP_CATALOG_UPDATE),
588 supports_role_declarations_update: ack
589 .subc_ops
590 .iter()
591 .any(|op| op == MODULE_TO_SUBC_OP_CATALOG_UPDATE_ROLE_DECLARATIONS),
592 supports_live_roots: ack.subc_ops.iter().any(|op| op == "supervisor.live_roots"),
593 supports_agent_commands: ack
594 .subc_ops
595 .iter()
596 .any(|op| op == "supervisor.agent_commands"),
597 supports_scope_sync: ack.subc_ops.iter().any(|op| op == SCOPE_SYNC_OP),
598 supports_scope_apply: ack.subc_ops.iter().any(|op| op == SCOPE_APPLY_OP),
599 supports_scope_describe: ack.subc_ops.iter().any(|op| op == SCOPE_DESCRIBE_OP),
600 supports_scope_watch: ack
601 .subc_ops
602 .iter()
603 .any(|op| op == subc_control::ops::SCOPE_WATCH),
604 supports_route_authorize: ack
605 .subc_ops
606 .iter()
607 .any(|op| op == subc_protocol::scope::ROUTE_AUTHORIZE_OP),
608 supports_operator_confirm: ack.subc_ops.iter().any(|op| op == OPERATOR_CONFIRM_OP),
609 supports_activity: ack
610 .subc_capabilities
611 .iter()
612 .any(|capability| capability == ACTIVITY_LEDGER_CAPABILITY),
613 connection_runtime,
614 connection_token,
615 machine_id: ack
618 .machine_id
619 .as_deref()
620 .and_then(|id| MachineId::parse(id).ok()),
621 live_routes: Mutex::new(HashMap::new()),
622 dropped_route_frames: AtomicU64::new(0),
623 close_token,
624 dispatch_pools: Mutex::new(Arc::new(DispatchPools::new(RequestPools::new()))),
625 catalog_send: tokio::sync::Mutex::new(()),
626 config: config::Session::default(),
627 served_control_ops: std::sync::OnceLock::new(),
628 inner: Mutex::new(ModuleHandleState {
629 pending_control_streams: HashMap::new(),
630 pending_claim_calls: HashMap::new(),
631 writer: Some(writer),
632 next_corr: Some(HELLO_CORR + 1),
633 pending_catalog_updates: HashMap::new(),
634 pending_operator_confirms: HashMap::new(),
635 pending_activity_records: HashMap::new(),
636 pending_scope_served_by: HashMap::new(),
637 pending_config_calls: HashMap::new(),
638 pending_agent_commands: HashMap::new(),
639 current_provides: None,
640 catalog_changes: VecDeque::new(),
641 closed: false,
642 }),
643 }),
644 }
645 }
646
647 pub fn machine_id(&self) -> Option<&MachineId> {
654 self.shared.machine_id.as_ref()
655 }
656
657 pub fn daemon_capabilities(&self) -> &[String] {
661 &self.shared.daemon_capabilities
662 }
663
664 pub fn daemon_supports(&self, capability: &str) -> bool {
671 self.shared
672 .daemon_capabilities
673 .iter()
674 .any(|advertised| advertised == capability)
675 }
676
677 pub fn closed(&self) -> impl Future<Output = ()> + Send + 'static {
681 self.shared.close_token.clone().cancelled_owned()
682 }
683
684 pub fn is_closed(&self) -> bool {
686 self.shared.close_token.is_cancelled()
687 }
688
689 pub async fn catalog_update(
694 &self,
695 provides: Vec<ProviderRole>,
696 ) -> Result<(), CatalogUpdateError> {
697 self.catalog_update_inner(Some(provides), None, None).await
698 }
699
700 pub async fn update_role_declarations(
708 &self,
709 role_declarations: BTreeMap<String, serde_json::Map<String, serde_json::Value>>,
710 ) -> Result<(), CatalogUpdateError> {
711 if !self.shared.supports_role_declarations_update {
712 return Err(CatalogUpdateError::NotSupported);
713 }
714 let body = serde_json::to_vec(
715 &ModuleControlRequestFromModule::CatalogUpdateRoleDeclarations {
716 role_declarations: serde_json::to_value(role_declarations)
717 .map_err(|err| CatalogUpdateError::Protocol(err.to_string()))?,
718 },
719 )
720 .map_err(|err| CatalogUpdateError::Protocol(err.to_string()))?;
721 let (corr, writer, rx) = self.shared.begin_catalog_update()?;
722 let _pending = CatalogUpdateGuard {
723 shared: self.shared.clone(),
724 corr,
725 };
726 let frame = Frame::build_with_version(
727 self.shared.negotiated_ver,
728 FrameType::Request,
729 control_flags(),
730 0,
731 0,
732 corr,
733 body,
734 )
735 .map_err(|err| CatalogUpdateError::Protocol(err.to_string()))?;
736 if writer.send(frame).await.is_err() {
737 return Err(CatalogUpdateError::ConnectionClosed);
738 }
739 match timeout(CATALOG_UPDATE_TIMEOUT, rx).await {
740 Ok(Ok(Ok(reply))) => match reply.control()? {
741 ModuleControlResponseToModule::CatalogUpdateRoleDeclarations {} => Ok(()),
742 _ => Err(CatalogUpdateError::Protocol(
743 "unexpected catalog.update_role_declarations response".into(),
744 )),
745 },
746 Ok(Ok(Err(err))) => Err(err),
747 Ok(Err(_)) => Err(CatalogUpdateError::ConnectionClosed),
748 Err(_) => Err(CatalogUpdateError::Timeout),
749 }
750 }
751
752 pub async fn catalog_update_with_capabilities(
758 &self,
759 provides: Vec<ProviderRole>,
760 capabilities: CapabilityDeclarations,
761 ) -> Result<(), CatalogUpdateError> {
762 self.catalog_update_inner(Some(provides), Some(capabilities), None)
763 .await
764 }
765
766 pub async fn set_ready(&self, ready: bool) -> Result<(), CatalogUpdateError> {
778 self.catalog_update_inner(None, None, Some(ready)).await
779 }
780
781 async fn catalog_update_inner(
782 &self,
783 provides: Option<Vec<ProviderRole>>,
784 capabilities: Option<CapabilityDeclarations>,
785 ready: Option<bool>,
786 ) -> Result<(), CatalogUpdateError> {
787 if !self.shared.supports_catalog_update {
788 return Err(CatalogUpdateError::NotSupported);
789 }
790
791 let send_guard = self.shared.catalog_send.lock().await;
794 let provides = match provides {
795 Some(provides) => provides,
796 None => {
797 let inner = self.shared.lock_inner();
798 if inner.closed {
799 return Err(CatalogUpdateError::ConnectionClosed);
800 }
801 inner
802 .current_provides
803 .as_ref()
804 .filter(|_| inner.catalog_changes.is_empty())
805 .cloned()
806 .ok_or_else(|| {
807 CatalogUpdateError::Protocol(
808 "current provider roles are unknown or a catalog update is in flight"
809 .into(),
810 )
811 })?
812 }
813 };
814 let body = serde_json::to_vec(&ModuleControlRequestFromModule::CatalogUpdate {
815 provides: provides.clone(),
816 capabilities,
817 ready,
818 })
819 .map_err(|err| {
820 CatalogUpdateError::Protocol(format!(
821 "failed to encode catalog.update request body: {err}"
822 ))
823 })?;
824 let (corr, writer, rx) = self.shared.begin_catalog_update()?;
825 let _pending = CatalogUpdateGuard {
826 shared: self.shared.clone(),
827 corr,
828 };
829 let frame = Frame::build_with_version(
830 self.shared.negotiated_ver,
831 FrameType::Request,
832 control_flags(),
833 0,
834 0,
835 corr,
836 body,
837 )
838 .map_err(|err| {
839 self.shared.remove_pending_catalog_update(corr);
840 CatalogUpdateError::Protocol(format!(
841 "failed to build catalog.update request frame: {err}"
842 ))
843 })?;
844
845 let permit = match writer.reserve().await {
846 Ok(permit) => permit,
847 Err(_) => {
848 self.shared.remove_pending_catalog_update(corr);
849 return Err(CatalogUpdateError::ConnectionClosed);
850 }
851 };
852 self.shared
853 .lock_inner()
854 .catalog_changes
855 .push_back(CatalogChange {
856 corr,
857 provides,
858 outcome: None,
859 });
860 permit.send(frame);
861 drop(send_guard);
862
863 match timeout(CATALOG_UPDATE_TIMEOUT, async {
864 rx.await
865 .map(|reply| reply.and_then(ModuleControlReply::control))
866 })
867 .await
868 {
869 Ok(Ok(Ok(ModuleControlResponseToModule::CatalogUpdate {}))) => Ok(()),
870 Ok(Ok(Ok(_))) => Err(CatalogUpdateError::Protocol(
871 "unexpected catalog.update response".into(),
872 )),
873 Ok(Ok(Err(err))) => Err(err),
874 Ok(Err(_)) => Err(CatalogUpdateError::ConnectionClosed),
875 Err(_) => {
876 self.shared.remove_pending_catalog_update(corr);
877 Err(CatalogUpdateError::Timeout)
878 }
879 }
880 }
881
882 pub async fn live_roots(&self) -> Result<LiveRootsSnapshot, CatalogUpdateError> {
884 if !self.shared.supports_live_roots {
885 return Err(CatalogUpdateError::NotSupported);
886 }
887 let body = serde_json::to_vec(&ModuleControlRequestFromModule::LiveRoots {})
888 .map_err(|err| CatalogUpdateError::Protocol(err.to_string()))?;
889 let (corr, writer, rx) = self.shared.begin_catalog_update()?;
890 let frame = Frame::build_with_version(
891 self.shared.negotiated_ver,
892 FrameType::Request,
893 control_flags(),
894 0,
895 0,
896 corr,
897 body,
898 )
899 .map_err(|err| {
900 self.shared.remove_pending_catalog_update(corr);
901 CatalogUpdateError::Protocol(err.to_string())
902 })?;
903 if writer.send(frame).await.is_err() {
904 self.shared.remove_pending_catalog_update(corr);
905 return Err(CatalogUpdateError::ConnectionClosed);
906 }
907 match timeout(CATALOG_UPDATE_TIMEOUT, async {
908 rx.await
909 .map(|reply| reply.and_then(ModuleControlReply::control))
910 })
911 .await
912 {
913 Ok(Ok(Ok(ModuleControlResponseToModule::LiveRoots {
914 roots,
915 unknown_root_bindings,
916 total_bindings,
917 }))) => Ok(LiveRootsSnapshot {
918 roots,
919 unknown_root_bindings,
920 total_bindings,
921 }),
922 Ok(Ok(Ok(_))) => Err(CatalogUpdateError::Protocol(
923 "unexpected live_roots response".into(),
924 )),
925 Ok(Ok(Err(err))) => Err(err),
926 Ok(Err(_)) => Err(CatalogUpdateError::ConnectionClosed),
927 Err(_) => {
928 self.shared.remove_pending_catalog_update(corr);
929 Err(CatalogUpdateError::Timeout)
930 }
931 }
932 }
933
934 pub async fn scope_sync(
950 &self,
951 generation: u64,
952 scopes: Vec<ScopeRecord>,
953 ) -> Result<ScopeSyncReply, ScopeCallError> {
954 if !self.shared.supports_scope_sync {
955 return Err(ScopeCallError::NotSupported { op: SCOPE_SYNC_OP });
956 }
957 let request = ModuleControlRequestFromModule::ScopeSync { generation, scopes };
958 match self
959 .scope_call(SCOPE_SYNC_OP, &request)
960 .await?
961 .control()
962 .map_err(ScopeCallError::from_control_error)?
963 {
964 ModuleControlResponseToModule::ScopeSync {
965 generation,
966 results,
967 ended,
968 } => Ok(ScopeSyncReply {
969 generation,
970 results,
971 ended,
972 }),
973 other => Err(ScopeCallError::Protocol(format!(
974 "unexpected {SCOPE_SYNC_OP} response: {other:?}"
975 ))),
976 }
977 }
978
979 pub async fn scope_apply(
990 &self,
991 generation: u64,
992 upsert: Vec<ScopeRecord>,
993 end: Vec<ScopeEnd>,
994 ) -> Result<ScopeApplyReply, ScopeCallError> {
995 if !self.shared.supports_scope_apply {
996 return Err(ScopeCallError::NotSupported { op: SCOPE_APPLY_OP });
997 }
998 let request = ModuleControlRequestFromModule::ScopeApply {
999 generation,
1000 upsert,
1001 end,
1002 };
1003 match self
1004 .scope_call(SCOPE_APPLY_OP, &request)
1005 .await?
1006 .control()
1007 .map_err(ScopeCallError::from_control_error)?
1008 {
1009 ModuleControlResponseToModule::ScopeApply {
1010 generation,
1011 results,
1012 end_results,
1013 ended,
1014 } => Ok(ScopeApplyReply {
1015 generation,
1016 results,
1017 end_results,
1018 ended,
1019 }),
1020 other => Err(ScopeCallError::Protocol(format!(
1021 "unexpected {SCOPE_APPLY_OP} response: {other:?}"
1022 ))),
1023 }
1024 }
1025
1026 pub async fn scope_describe(
1034 &self,
1035 owner: Principal,
1036 scope_ref: String,
1037 ) -> Result<ScopeDescribeReply, ScopeCallError> {
1038 if !self.shared.supports_scope_describe {
1039 return Err(ScopeCallError::NotSupported {
1040 op: SCOPE_DESCRIBE_OP,
1041 });
1042 }
1043 let request = ModuleControlRequestFromModule::ScopeDescribe { owner, scope_ref };
1044 match self
1045 .scope_call(SCOPE_DESCRIBE_OP, &request)
1046 .await?
1047 .control()
1048 .map_err(ScopeCallError::from_control_error)?
1049 {
1050 ModuleControlResponseToModule::ScopeDescribe {
1051 status,
1052 scope_epoch,
1053 daemon_incarnation,
1054 owner_synced,
1055 owner_configured,
1056 scope,
1057 } => Ok(ScopeDescribeReply {
1058 status,
1059 scope_epoch,
1060 daemon_incarnation,
1061 owner_synced,
1062 owner_configured,
1063 scope,
1064 }),
1065 other => Err(ScopeCallError::Protocol(format!(
1066 "unexpected {SCOPE_DESCRIBE_OP} response: {other:?}"
1067 ))),
1068 }
1069 }
1070
1071 pub async fn confirm_operator(
1083 &self,
1084 summary: &str,
1085 caller_route: &RouteHandle,
1086 ) -> Result<(), OperatorConfirmError> {
1087 self.confirm_operator_with_deadline(summary, caller_route, OPERATOR_CONFIRM_TIMEOUT)
1088 .await
1089 }
1090
1091 pub async fn confirm_operation(
1112 &self,
1113 summary: &str,
1114 caller_route: &RouteHandle,
1115 operation: &str,
1116 ) -> Result<(), OperatorConfirmError> {
1117 if operation.is_empty() {
1118 return Err(OperatorConfirmError::OperationInvalid);
1119 }
1120 self.confirm_operation_with_deadline(
1121 summary,
1122 caller_route,
1123 operation,
1124 OPERATOR_CONFIRM_TIMEOUT,
1125 )
1126 .await
1127 }
1128
1129 pub async fn confirm_enrollment(
1147 &self,
1148 summary: &str,
1149 caller_route: &RouteHandle,
1150 ) -> Result<(), OperatorConfirmError> {
1151 self.confirm_inner(
1152 summary,
1153 caller_route,
1154 Some(OperatorConfirmKind::Enrollment),
1155 None,
1156 OPERATOR_CONFIRM_TIMEOUT,
1157 )
1158 .await
1159 }
1160
1161 pub(crate) async fn confirm_operator_with_deadline(
1162 &self,
1163 summary: &str,
1164 caller_route: &RouteHandle,
1165 duration: Duration,
1166 ) -> Result<(), OperatorConfirmError> {
1167 self.confirm_inner(summary, caller_route, None, None, duration)
1168 .await
1169 }
1170
1171 async fn confirm_operation_with_deadline(
1172 &self,
1173 summary: &str,
1174 caller_route: &RouteHandle,
1175 operation: &str,
1176 duration: Duration,
1177 ) -> Result<(), OperatorConfirmError> {
1178 self.confirm_inner(
1179 summary,
1180 caller_route,
1181 Some(OperatorConfirmKind::Operation),
1182 Some(operation.to_owned()),
1183 duration,
1184 )
1185 .await
1186 }
1187
1188 async fn confirm_inner(
1189 &self,
1190 summary: &str,
1191 caller_route: &RouteHandle,
1192 kind: Option<OperatorConfirmKind>,
1193 operation: Option<String>,
1194 duration: Duration,
1195 ) -> Result<(), OperatorConfirmError> {
1196 if caller_route.connection_token() != self.shared.connection_token {
1197 return Err(OperatorConfirmError::NotPermitted);
1198 }
1199 if !self.shared.supports_operator_confirm {
1200 return Err(OperatorConfirmError::Unsupported);
1201 }
1202 let deadline = Instant::now() + duration;
1205 let body = serde_json::to_vec(
1206 &OperatorConfirmRequest::new(summary, caller_route.channel, caller_route.epoch)
1207 .with_kind(kind)
1208 .with_operation(operation),
1209 )
1210 .map_err(|_| OperatorConfirmError::PresenceUnavailable)?;
1211 let (corr, writer, rx) = self.shared.begin_operator_confirm()?;
1212 let mut guard = OperatorConfirmGuard {
1213 shared: Arc::clone(&self.shared),
1214 runtime: self.shared.connection_runtime.clone(),
1215 writer: writer.clone(),
1216 corr,
1217 accepted: false,
1218 armed: true,
1219 };
1220 let frame = Frame::build_with_version(
1221 self.shared.negotiated_ver,
1222 FrameType::Request,
1223 control_flags(),
1224 0,
1225 0,
1226 corr,
1227 body,
1228 )
1229 .map_err(|_| OperatorConfirmError::PresenceUnavailable)?;
1230 tokio::select! {
1231 result = timeout_at(deadline, writer.send(frame)) => {
1232 result.map_err(|_| OperatorConfirmError::PresenceUnavailable)?
1233 .map_err(|_| OperatorConfirmError::PresenceUnavailable)?;
1234 }
1235 _ = self.shared.close_token.cancelled() => {
1236 return Err(OperatorConfirmError::PresenceUnavailable);
1237 }
1238 }
1239 guard.accepted = true;
1240 let reply = timeout_at(deadline, rx)
1241 .await
1242 .map_err(|_| OperatorConfirmError::PresenceUnavailable)?
1243 .map_err(|_| OperatorConfirmError::PresenceUnavailable)?;
1244 guard.armed = false;
1245 match reply.header.ty {
1246 FrameType::Response => {
1247 match serde_json::from_slice::<OperatorConfirmReply>(&reply.body) {
1248 Ok(body) if body.outcome == "confirmed" => Ok(()),
1249 _ => Err(OperatorConfirmError::PresenceUnavailable),
1250 }
1251 }
1252 FrameType::Error => match serde_json::from_slice::<ErrorBody>(&reply.body) {
1253 Ok(body) => Err(match body.code.as_str() {
1254 error_codes::OPERATOR_DECLINED => {
1255 let detail = body.detail.as_ref();
1256 if detail
1257 .and_then(|detail| detail.get("reason"))
1258 .and_then(serde_json::Value::as_str)
1259 == Some("backoff")
1260 {
1261 OperatorConfirmError::Backoff {
1262 retry_after_ms: detail
1263 .and_then(|detail| detail.get("retry_after_ms"))
1264 .and_then(serde_json::Value::as_u64),
1265 }
1266 } else {
1267 OperatorConfirmError::Declined
1268 }
1269 }
1270 error_codes::OPERATOR_PRESENCE_UNAVAILABLE
1271 if body
1272 .detail
1273 .as_ref()
1274 .and_then(|detail| detail.get("reason"))
1275 .and_then(serde_json::Value::as_str)
1276 == Some("unsupported_platform") =>
1277 {
1278 OperatorConfirmError::PresenceUnsupportedPlatform
1279 }
1280 error_codes::OPERATOR_SUMMARY_INVALID => OperatorConfirmError::SummaryInvalid,
1281 error_codes::OPERATOR_REQUEST_NOT_PERMITTED | "not_registered" => {
1282 OperatorConfirmError::NotPermitted
1283 }
1284 "unsupported_control_frame" => OperatorConfirmError::Unsupported,
1285 _ => OperatorConfirmError::PresenceUnavailable,
1286 }),
1287 Err(_) => Err(OperatorConfirmError::PresenceUnavailable),
1288 },
1289 _ => Err(OperatorConfirmError::PresenceUnavailable),
1290 }
1291 }
1292
1293 async fn scope_call(
1297 &self,
1298 op: &'static str,
1299 request: &ModuleControlRequestFromModule,
1300 ) -> Result<ModuleControlReply, ScopeCallError> {
1301 let body = serde_json::to_vec(request).map_err(|err| {
1302 ScopeCallError::Protocol(format!("failed to encode {op} request body: {err}"))
1303 })?;
1304 let (corr, writer, rx) = self
1305 .shared
1306 .begin_catalog_update()
1307 .map_err(ScopeCallError::from_control_error)?;
1308 let frame = Frame::build_with_version(
1309 self.shared.negotiated_ver,
1310 FrameType::Request,
1311 control_flags(),
1312 0,
1313 0,
1314 corr,
1315 body,
1316 )
1317 .map_err(|err| {
1318 self.shared.remove_pending_catalog_update(corr);
1319 ScopeCallError::Protocol(format!("failed to build {op} request frame: {err}"))
1320 })?;
1321 if writer.send(frame).await.is_err() {
1322 self.shared.remove_pending_catalog_update(corr);
1323 return Err(ScopeCallError::ConnectionClosed);
1324 }
1325 match timeout(CATALOG_UPDATE_TIMEOUT, rx).await {
1326 Ok(Ok(reply)) => reply.map_err(ScopeCallError::from_control_error),
1327 Ok(Err(_)) => Err(ScopeCallError::ConnectionClosed),
1328 Err(_) => {
1329 self.shared.remove_pending_catalog_update(corr);
1330 Err(ScopeCallError::Timeout)
1331 }
1332 }
1333 }
1334
1335 pub async fn push(
1337 &self,
1338 handle: &RouteHandle,
1339 body: Vec<u8>,
1340 admission_class: Option<AdmissionClass>,
1341 ) -> Result<(), SubcModuleError> {
1342 self.validate_route(*handle)?;
1343 let writer = self
1344 .shared
1345 .lock_inner()
1346 .writer
1347 .clone()
1348 .ok_or(SubcModuleError::WriterClosed)?;
1349 let frame = Frame::build_with_version(
1350 self.shared.negotiated_ver,
1351 FrameType::Push,
1352 data_flags().with_admission_class(admission_class.unwrap_or(AdmissionClass::Normal)),
1353 handle.channel,
1354 handle.epoch,
1355 0,
1356 body,
1357 )
1358 .map_err(SubcModuleError::FrameBuild)?;
1359 send_outbound(&writer, frame).await
1360 }
1361
1362 pub fn dropped_route_frames(&self) -> u64 {
1364 self.shared.dropped_route_frames.load(Ordering::Relaxed)
1365 }
1366
1367 fn validate_route(&self, handle: RouteHandle) -> Result<(), SubcModuleError> {
1368 if handle.connection_token() != self.shared.connection_token {
1369 return Err(SubcModuleError::StaleRouteHandle(handle));
1370 }
1371 let routes = self
1372 .shared
1373 .live_routes
1374 .lock()
1375 .map_err(|_| SubcModuleError::InFlightPoisoned)?;
1376 if routes.get(&handle.channel) == Some(&handle) {
1377 Ok(())
1378 } else {
1379 Err(SubcModuleError::StaleRouteHandle(handle))
1380 }
1381 }
1382
1383 fn install_route(&self, handle: RouteHandle) -> Result<(), SubcModuleError> {
1384 self.shared
1385 .live_routes
1386 .lock()
1387 .map_err(|_| SubcModuleError::InFlightPoisoned)?
1388 .insert(handle.channel, handle);
1389 Ok(())
1390 }
1391
1392 fn installed_route(&self, channel: u16) -> Result<Option<RouteHandle>, SubcModuleError> {
1393 Ok(self
1394 .shared
1395 .live_routes
1396 .lock()
1397 .map_err(|_| SubcModuleError::InFlightPoisoned)?
1398 .get(&channel)
1399 .copied())
1400 }
1401
1402 fn remove_route(&self, handle: RouteHandle) -> Result<bool, SubcModuleError> {
1403 let mut routes = self
1404 .shared
1405 .live_routes
1406 .lock()
1407 .map_err(|_| SubcModuleError::InFlightPoisoned)?;
1408 if routes.get(&handle.channel) == Some(&handle) {
1409 routes.remove(&handle.channel);
1410 Ok(true)
1411 } else {
1412 Ok(false)
1413 }
1414 }
1415
1416 fn validate_ingress(&self, channel: u16, epoch: u32) -> Result<bool, SubcModuleError> {
1417 let handle = RouteHandle::new(channel, epoch, self.shared.connection_token);
1418 let valid = self
1419 .shared
1420 .live_routes
1421 .lock()
1422 .map_err(|_| SubcModuleError::InFlightPoisoned)?
1423 .get(&channel)
1424 == Some(&handle);
1425 if !valid {
1426 self.shared
1427 .dropped_route_frames
1428 .fetch_add(1, Ordering::Relaxed);
1429 }
1430 Ok(valid)
1431 }
1432
1433 fn route_handle(&self, channel: u16, epoch: u32) -> RouteHandle {
1434 RouteHandle::new(channel, epoch, self.shared.connection_token)
1435 }
1436
1437 fn handle_control_reply(&self, frame: Frame) -> bool {
1438 let Some(frame) = self.handle_control_stream_frame(frame) else {
1439 return true;
1440 };
1441 let claim_reply = self
1442 .shared
1443 .lock_inner()
1444 .pending_claim_calls
1445 .remove(&frame.header.corr);
1446 if let Some(reply) = claim_reply {
1447 let _ = reply.send(frame);
1448 return true;
1449 }
1450 let config_reply = self
1451 .shared
1452 .lock_inner()
1453 .pending_config_calls
1454 .remove(&frame.header.corr);
1455 if let Some(reply) = config_reply {
1456 let _ = reply.send(frame);
1457 return true;
1458 }
1459 if let Some(reply) = self
1460 .shared
1461 .lock_inner()
1462 .pending_agent_commands
1463 .remove(&frame.header.corr)
1464 {
1465 let _ = reply.send(frame);
1466 return true;
1467 }
1468 let served_by_reply = self
1469 .shared
1470 .lock_inner()
1471 .pending_scope_served_by
1472 .remove(&frame.header.corr);
1473 if let Some(reply) = served_by_reply {
1474 let _ = reply.send(frame);
1475 return true;
1476 }
1477 let activity_reply = self
1478 .shared
1479 .lock_inner()
1480 .pending_activity_records
1481 .remove(&frame.header.corr);
1482 if let Some(reply) = activity_reply {
1483 let _ = reply.send(frame);
1484 return true;
1485 }
1486 let operator_reply = self
1487 .shared
1488 .lock_inner()
1489 .pending_operator_confirms
1490 .remove(&frame.header.corr);
1491 if let Some(reply) = operator_reply {
1492 let _ = reply.send(frame);
1493 return true;
1494 }
1495 let Some(reply) = self.shared.take_pending_catalog_update(frame.header.corr) else {
1496 return false;
1497 };
1498 let result = match frame.header.ty {
1499 FrameType::Response => serde_json::from_slice::<ModuleControlReply>(&frame.body)
1500 .map_err(|err| {
1501 CatalogUpdateError::Protocol(format!(
1502 "invalid module control response body: {err}"
1503 ))
1504 }),
1505 FrameType::Error => match serde_json::from_slice::<ErrorBody>(&frame.body) {
1506 Ok(body) => Err(match body.code.as_str() {
1507 "catalog_update_frozen_field" => CatalogUpdateError::FrozenField(body),
1508 "not_registered" => CatalogUpdateError::NotRegistered(body),
1509 _ => CatalogUpdateError::Rejected(body),
1510 }),
1511 Err(err) => Err(CatalogUpdateError::Protocol(format!(
1512 "invalid catalog.update error body: {err}"
1513 ))),
1514 },
1515 ty => Err(CatalogUpdateError::Protocol(format!(
1516 "unexpected catalog.update terminal frame: {ty:?}"
1517 ))),
1518 };
1519 let outcome = match &result {
1520 Ok(ModuleControlReply::Control(reply))
1521 if matches!(
1522 reply.as_ref(),
1523 ModuleControlResponseToModule::CatalogUpdate {}
1524 ) =>
1525 {
1526 CatalogChangeOutcome::Accepted
1527 }
1528 Err(CatalogUpdateError::FrozenField(_))
1529 | Err(CatalogUpdateError::NotRegistered(_))
1530 | Err(CatalogUpdateError::Rejected(_)) => CatalogChangeOutcome::Rejected,
1531 _ => CatalogChangeOutcome::Unknown,
1532 };
1533 self.shared
1534 .finish_catalog_change(frame.header.corr, outcome);
1535 let _ = reply.send(result);
1536 true
1537 }
1538
1539 fn close_connection(&self) {
1540 self.shared.close_connection();
1541 }
1542}
1543
1544impl ModuleHandleShared {
1545 fn begin_catalog_update(&self) -> Result<CatalogUpdateRequest, CatalogUpdateError> {
1546 let mut inner = self.lock_inner();
1547 if inner.closed {
1548 return Err(CatalogUpdateError::ConnectionClosed);
1549 }
1550 let Some(writer) = inner.writer.clone() else {
1551 drop(inner);
1552 self.close_connection();
1553 return Err(CatalogUpdateError::ConnectionClosed);
1554 };
1555 let Some(corr) = next_module_control_corr(&mut inner) else {
1556 drop(inner);
1557 self.close_connection();
1558 return Err(CatalogUpdateError::ConnectionClosed);
1559 };
1560 let (tx, rx) = oneshot::channel();
1561 inner.pending_catalog_updates.insert(corr, tx);
1562 Ok((corr, writer, rx))
1563 }
1564
1565 fn begin_operator_confirm(&self) -> Result<OperatorConfirmRequestWaiter, OperatorConfirmError> {
1566 let mut inner = self.lock_inner();
1567 if inner.closed {
1568 return Err(OperatorConfirmError::PresenceUnavailable);
1569 }
1570 let Some(writer) = inner.writer.clone() else {
1571 drop(inner);
1572 self.close_connection();
1573 return Err(OperatorConfirmError::PresenceUnavailable);
1574 };
1575 let Some(corr) = next_module_control_corr(&mut inner) else {
1576 drop(inner);
1577 self.close_connection();
1578 return Err(OperatorConfirmError::PresenceUnavailable);
1579 };
1580 let (tx, rx) = oneshot::channel();
1581 inner.pending_operator_confirms.insert(corr, tx);
1582 Ok((corr, writer, rx))
1583 }
1584
1585 fn take_pending_catalog_update(&self, corr: u64) -> Option<CatalogUpdateReply> {
1586 self.lock_inner().pending_catalog_updates.remove(&corr)
1587 }
1588
1589 fn remove_pending_catalog_update(&self, corr: u64) {
1590 let removed = self
1591 .lock_inner()
1592 .pending_catalog_updates
1593 .remove(&corr)
1594 .is_some();
1595 if removed {
1596 self.finish_catalog_change(corr, CatalogChangeOutcome::Unknown);
1597 }
1598 }
1599
1600 fn finish_catalog_change(&self, corr: u64, outcome: CatalogChangeOutcome) {
1601 let mut inner = self.lock_inner();
1602 if let Some(change) = inner
1603 .catalog_changes
1604 .iter_mut()
1605 .find(|change| change.corr == corr)
1606 {
1607 change.outcome = Some(outcome);
1608 }
1609 while inner
1612 .catalog_changes
1613 .front()
1614 .is_some_and(|change| change.outcome.is_some())
1615 {
1616 let change = inner.catalog_changes.pop_front().expect("completed change");
1617 match change.outcome.expect("completed outcome") {
1618 CatalogChangeOutcome::Accepted => inner.current_provides = Some(change.provides),
1619 CatalogChangeOutcome::Rejected => {}
1620 CatalogChangeOutcome::Unknown => inner.current_provides = None,
1621 }
1622 }
1623 }
1624
1625 fn close_connection(&self) {
1626 let pending = {
1627 let mut inner = self.lock_inner();
1628 if inner.closed {
1629 return;
1630 }
1631 inner.closed = true;
1632 inner.writer = None;
1633 inner.current_provides = None;
1634 inner.catalog_changes.clear();
1635 self.close_token.cancel();
1636 inner.pending_operator_confirms.clear();
1638 inner.pending_activity_records.clear();
1639 inner.pending_scope_served_by.clear();
1640 inner.pending_config_calls.clear();
1641 inner.pending_agent_commands.clear();
1642 inner.pending_claim_calls.clear();
1643 inner.pending_control_streams.clear();
1644 inner
1645 .pending_catalog_updates
1646 .drain()
1647 .map(|(_, reply)| reply)
1648 .collect::<Vec<_>>()
1649 };
1650 self.clear_live_routes();
1651 for reply in pending {
1652 let _ = reply.send(Err(CatalogUpdateError::ConnectionClosed));
1653 }
1654 }
1655
1656 fn clear_live_routes(&self) {
1657 if let Ok(mut routes) = self.live_routes.lock() {
1658 routes.clear();
1659 }
1660 }
1661
1662 fn lock_inner(&self) -> std::sync::MutexGuard<'_, ModuleHandleState> {
1663 self.inner
1664 .lock()
1665 .unwrap_or_else(|poisoned| poisoned.into_inner())
1666 }
1667}
1668
1669fn next_module_control_corr(inner: &mut ModuleHandleState) -> Option<u64> {
1670 let corr = inner.next_corr?;
1671 inner.next_corr = corr.checked_add(1);
1672 Some(corr)
1673}
1674
1675struct OperatorConfirmGuard {
1676 shared: Arc<ModuleHandleShared>,
1677 runtime: tokio::runtime::Handle,
1678 writer: mpsc::Sender<Frame>,
1679 corr: u64,
1680 accepted: bool,
1681 armed: bool,
1682}
1683
1684impl Drop for OperatorConfirmGuard {
1685 fn drop(&mut self) {
1686 if !self.armed {
1687 return;
1688 }
1689 self.shared
1690 .lock_inner()
1691 .pending_operator_confirms
1692 .remove(&self.corr);
1693 if !self.accepted {
1694 return;
1695 }
1696 let Ok(cancel) = Frame::build_with_version(
1697 self.shared.negotiated_ver,
1698 FrameType::Cancel,
1699 control_flags(),
1700 0,
1701 0,
1702 self.corr,
1703 Vec::new(),
1704 ) else {
1705 return;
1706 };
1707 match self.writer.try_send(cancel) {
1708 Ok(()) | Err(mpsc::error::TrySendError::Closed(_)) => {}
1709 Err(mpsc::error::TrySendError::Full(cancel)) => {
1710 let writer = self.writer.clone();
1714 self.runtime.spawn(async move {
1715 let _ = writer.send(cancel).await;
1716 });
1717 }
1718 }
1719 }
1720}
1721
1722#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1727#[non_exhaustive]
1728pub enum OperatorConfirmError {
1729 Declined,
1730 Backoff {
1733 retry_after_ms: Option<u64>,
1734 },
1735 PresenceUnavailable,
1740 PresenceUnsupportedPlatform,
1752 SummaryInvalid,
1753 OperationInvalid,
1759 NotPermitted,
1760 Unsupported,
1761}
1762
1763impl fmt::Display for OperatorConfirmError {
1764 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1765 f.write_str(match self {
1766 Self::Declined => "operator declined the write",
1767 Self::Backoff { retry_after_ms: None } => {
1768 "operator confirmation refused without asking: a recent decline holds new prompts for a short time"
1769 }
1770 Self::PresenceUnavailable => "operator confirmation is unavailable",
1771 Self::PresenceUnsupportedPlatform => {
1772 "operator confirmation has no prompt on this platform"
1773 }
1774 Self::SummaryInvalid => "operator confirmation summary is invalid",
1775 Self::OperationInvalid => "operator confirmation operation is invalid",
1776 Self::NotPermitted => "operator confirmation is not permitted for this route",
1777 Self::Unsupported => "daemon does not support operator confirmation",
1778 Self::Backoff {
1779 retry_after_ms: Some(_),
1780 } => return write!(
1781 f,
1782 "operator confirmation refused without asking: a recent decline holds new prompts for {} s",
1783 self.backoff_seconds().expect("backoff retry duration is present")
1784 ),
1785 })
1786 }
1787}
1788
1789impl OperatorConfirmError {
1790 fn backoff_seconds(&self) -> Option<u64> {
1791 match self {
1792 Self::Backoff {
1793 retry_after_ms: Some(milliseconds),
1794 } => Some(milliseconds / 1_000 + u64::from(!milliseconds.is_multiple_of(1_000))),
1795 _ => None,
1796 }
1797 }
1798}
1799
1800impl Error for OperatorConfirmError {}
1801
1802#[derive(Debug)]
1805pub enum CatalogUpdateError {
1806 NotSupported,
1807 FrozenField(ErrorBody),
1808 NotRegistered(ErrorBody),
1809 Rejected(ErrorBody),
1810 Timeout,
1811 ConnectionClosed,
1812 Protocol(String),
1813}
1814
1815impl fmt::Display for CatalogUpdateError {
1816 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1817 match self {
1818 Self::NotSupported => write!(
1819 f,
1820 "daemon HELLO_ACK did not advertise catalog.update support"
1821 ),
1822 Self::FrozenField(body) => {
1823 write!(f, "catalog.update rejected frozen field: {}", body.message)
1824 }
1825 Self::NotRegistered(body) => write!(
1826 f,
1827 "catalog.update requires a registered module: {}",
1828 body.message
1829 ),
1830 Self::Rejected(body) => write!(
1831 f,
1832 "catalog.update rejected by subc: {} ({})",
1833 body.code, body.message
1834 ),
1835 Self::Timeout => write!(f, "catalog.update timed out waiting for an ACK"),
1836 Self::ConnectionClosed => {
1837 write!(f, "subc connection closed before catalog.update completed")
1838 }
1839 Self::Protocol(message) => write!(f, "catalog.update protocol error: {message}"),
1840 }
1841 }
1842}
1843
1844impl Error for CatalogUpdateError {}
1845
1846#[derive(Debug, Clone, PartialEq, Eq)]
1855#[non_exhaustive]
1856pub enum ScopeCallError {
1857 NotSupported { op: &'static str },
1860 Refused { code: String, message: String },
1865 Timeout,
1867 ConnectionClosed,
1869 Protocol(String),
1871}
1872
1873impl ScopeCallError {
1874 pub fn code(&self) -> Option<&str> {
1876 match self {
1877 Self::Refused { code, .. } => Some(code),
1878 _ => None,
1879 }
1880 }
1881
1882 fn from_control_error(err: CatalogUpdateError) -> Self {
1887 match err {
1888 CatalogUpdateError::FrozenField(body)
1889 | CatalogUpdateError::NotRegistered(body)
1890 | CatalogUpdateError::Rejected(body) => Self::Refused {
1891 code: body.code,
1892 message: body.message,
1893 },
1894 CatalogUpdateError::Timeout => Self::Timeout,
1895 CatalogUpdateError::ConnectionClosed => Self::ConnectionClosed,
1896 CatalogUpdateError::Protocol(message) => Self::Protocol(message),
1897 CatalogUpdateError::NotSupported => {
1900 Self::Protocol("unexpected NotSupported from the control reply table".into())
1901 }
1902 }
1903 }
1904}
1905
1906impl fmt::Display for ScopeCallError {
1907 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1908 match self {
1909 Self::NotSupported { op } => {
1910 write!(f, "daemon HELLO_ACK did not advertise {op} support")
1911 }
1912 Self::Refused { code, message } => {
1913 write!(f, "subc refused the request: {code} ({message})")
1914 }
1915 Self::Timeout => write!(f, "timed out waiting for the daemon's reply"),
1916 Self::ConnectionClosed => {
1917 write!(f, "subc connection closed before the daemon replied")
1918 }
1919 Self::Protocol(message) => write!(f, "scope call protocol error: {message}"),
1920 }
1921 }
1922}
1923
1924impl Error for ScopeCallError {}
1925
1926#[async_trait]
1974pub trait ModuleHandler: Send + Sync + 'static {
1975 async fn handle(&self, ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome;
1980
1981 async fn on_hello_ack(&self, _ack: &ModuleHelloAckBody) {}
1984
1985 fn control_ops(&self) -> Vec<String> {
1991 Vec::new()
1992 }
1993
1994 async fn on_control_request(
2007 &self,
2008 _op: &str,
2009 _body: serde_json::Value,
2010 _cancel: CancellationToken,
2011 ) -> Result<serde_json::Value, ErrorBody> {
2012 Err(ErrorBody::new(
2013 "unsupported_op",
2014 "no control handler implemented",
2015 ))
2016 }
2017
2018 fn config_declaration(&self) -> Option<config::ConfigDeclareRequest> {
2022 None
2023 }
2024
2025 async fn config_review(
2028 &self,
2029 _request: config::ConfigReviewRequest,
2030 ) -> config::ConfigReviewReply {
2031 config::ConfigReviewReply::new(
2032 vec![],
2033 vec![config::ConfigReviewRefusal::new(
2034 "value_invalid",
2035 vec![],
2036 vec!["module has no config review implementation".into()],
2037 )],
2038 )
2039 }
2040
2041 async fn config_apply(&self, _view: config::ConfigView) -> Result<(), Vec<String>> {
2045 Err(vec!["module has no config apply implementation".into()])
2046 }
2047
2048 async fn config_files(&self) {}
2051
2052 async fn on_config_state(&self, _state: config::ConfigState) {}
2054
2055 async fn on_config_error(&self, error: config::ConfigError) {
2058 tracing::warn!(%error, "module configuration request failed");
2059 }
2060
2061 async fn on_bind(&self, _req: &RouteBindRequest) -> BindDecision {
2063 BindDecision::accept()
2064 }
2065
2066 async fn on_bound(&self, _handle: &RouteHandle) {}
2068
2069 async fn health(&self) -> HealthReport {
2099 HealthReport {
2112 detail: Some("no health implementation; inherited default".to_string()),
2113 ..HealthReport::ok()
2114 }
2115 }
2116
2117 async fn on_route_gone(&self, _handle: &RouteHandle) {}
2119
2120 fn request_pools(&self) -> RequestPools {
2152 RequestPools::new()
2153 }
2154
2155 async fn on_draining(&self, _reason: RouteCloseReason, _deadline: SystemTime) {}
2173
2174 async fn on_connection_end(&self, _end: ConnectionEnd) {}
2181}
2182
2183#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2188#[non_exhaustive]
2189pub enum ConnectionEnd {
2190 Goodbye,
2192 Eof,
2194 Reset,
2197 Closed,
2199}
2200
2201impl ConnectionEnd {
2202 pub fn as_str(self) -> &'static str {
2204 match self {
2205 Self::Goodbye => "goodbye",
2206 Self::Eof => "eof",
2207 Self::Reset => "reset",
2208 Self::Closed => "closed",
2209 }
2210 }
2211}
2212
2213impl std::fmt::Display for ConnectionEnd {
2214 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2215 f.write_str(self.as_str())
2216 }
2217}
2218
2219#[derive(Debug, Clone, PartialEq)]
2221pub enum HandlerOutcome {
2222 Response(Vec<u8>),
2224 Error { code: String, message: String },
2226 ErrorWithDetail {
2228 code: String,
2229 message: String,
2230 detail: serde_json::Value,
2231 },
2232 Streamed,
2235}
2236
2237#[derive(Clone)]
2240pub struct RequestCtx {
2241 handle: RouteHandle,
2242 corr: u64,
2243 ver: u8,
2244 egress: mpsc::Sender<Frame>,
2245 module_handle: ModuleHandle,
2246 cancelled: CancellationToken,
2247 binary_reply: Arc<AtomicBool>,
2248 request_flags: Flags,
2249 request_body: Arc<[u8]>,
2250}
2251
2252impl RequestCtx {
2253 pub fn module_handle(&self) -> ModuleHandle {
2255 self.module_handle.clone()
2256 }
2257
2258 pub fn request_payload(
2263 &self,
2264 ) -> Result<Option<(serde_json::Value, &[u8])>, subc_protocol::framed_body::FramedBodyError>
2265 {
2266 if !self.request_flags.is_binary() {
2267 return Ok(None);
2268 }
2269 subc_protocol::framed_body::decode(&self.request_body).map(Some)
2270 }
2271
2272 pub fn route_handle(&self) -> RouteHandle {
2274 self.handle
2275 }
2276
2277 pub fn corr(&self) -> u64 {
2279 self.corr
2280 }
2281
2282 pub fn mark_binary_reply(&self) {
2294 self.binary_reply.store(true, Ordering::Relaxed);
2295 }
2296
2297 pub async fn emit(&self, body: Vec<u8>) -> Result<(), SubcModuleError> {
2300 self.emit_with_admission(body, None).await
2301 }
2302
2303 pub async fn emit_with_admission(
2305 &self,
2306 body: Vec<u8>,
2307 admission_class: Option<AdmissionClass>,
2308 ) -> Result<(), SubcModuleError> {
2309 self.module_handle.validate_route(self.handle)?;
2310 if self.cancelled.is_cancelled() {
2311 return Ok(());
2312 }
2313 self.send_frame(
2314 FrameType::StreamData,
2315 data_flags().with_admission_class(admission_class.unwrap_or(AdmissionClass::Normal)),
2316 body,
2317 )
2318 .await
2319 }
2320
2321 pub fn cancelled(&self) -> WaitForCancellationFuture<'_> {
2324 self.cancelled.cancelled()
2325 }
2326
2327 pub fn cancellation_token(&self) -> CancellationToken {
2329 self.cancelled.clone()
2330 }
2331
2332 async fn send_frame(
2333 &self,
2334 frame_type: FrameType,
2335 flags: Flags,
2336 body: Vec<u8>,
2337 ) -> Result<(), SubcModuleError> {
2338 self.module_handle.validate_route(self.handle)?;
2339 let (frame_type, flags, body) = bounded_terminal(frame_type, flags, body)?;
2340 let frame = Frame::build_with_version(
2341 self.ver,
2342 frame_type,
2343 flags,
2344 self.handle.channel,
2345 self.handle.epoch,
2346 self.corr,
2347 body,
2348 )
2349 .map_err(SubcModuleError::FrameBuild)?;
2350 send_outbound(&self.egress, frame).await
2351 }
2352}
2353
2354fn checked_increment(counter: &AtomicU64) -> Option<u64> {
2359 let mut current = counter.load(Ordering::Relaxed);
2360 loop {
2361 let next = current.checked_add(1)?;
2362 match counter.compare_exchange_weak(current, next, Ordering::Relaxed, Ordering::Relaxed) {
2363 Ok(previous) => return Some(previous),
2364 Err(actual) => current = actual,
2365 }
2366 }
2367}
2368
2369#[derive(Debug, Clone)]
2376#[non_exhaustive]
2377pub struct RouteBindRequest {
2378 pub handle: RouteHandle,
2379 pub target: RouteTarget,
2380 pub identity: BindIdentity,
2381 pub principal: Option<Principal>,
2382 pub consumer_capabilities: Option<Vec<String>>,
2389 pub role_versions: Option<std::collections::BTreeMap<String, String>>,
2396 pub admission_facts: Option<serde_json::Value>,
2398 pub scope: Option<ScopeStamp>,
2407 pub call_mode: CallMode,
2410 pub peer: subc_protocol::peer::RouteBindPeer,
2438}
2439
2440impl RouteBindRequest {
2441 pub fn new(handle: RouteHandle, target: RouteTarget, identity: BindIdentity) -> Self {
2446 Self {
2447 handle,
2448 target,
2449 identity,
2450 principal: None,
2451 consumer_capabilities: None,
2452 role_versions: None,
2453 admission_facts: None,
2454 scope: None,
2455 call_mode: derive_call_mode(None),
2456 peer: subc_protocol::peer::RouteBindPeer::new(),
2457 }
2458 }
2459
2460 pub fn with_peer(mut self, peer: subc_protocol::peer::RouteBindPeer) -> Self {
2463 self.peer = peer;
2464 self
2465 }
2466
2467 pub fn peer_build(&self) -> Option<&str> {
2470 self.peer.peer_build.as_deref()
2471 }
2472
2473 pub fn with_principal(mut self, principal: Principal) -> Self {
2475 self.principal = Some(principal);
2476 self
2477 }
2478
2479 pub fn with_consumer_capabilities(mut self, consumer_capabilities: Vec<String>) -> Self {
2481 self.consumer_capabilities = Some(consumer_capabilities);
2482 self
2483 }
2484
2485 pub fn with_role_versions(
2487 mut self,
2488 role_versions: std::collections::BTreeMap<String, String>,
2489 ) -> Self {
2490 self.role_versions = Some(role_versions);
2491 self
2492 }
2493
2494 pub fn with_admission_facts(mut self, admission_facts: serde_json::Value) -> Self {
2496 self.admission_facts = Some(admission_facts);
2497 self
2498 }
2499
2500 pub fn with_scope(mut self, scope: ScopeStamp) -> Self {
2503 self.call_mode = derive_call_mode(Some(&scope));
2504 self.scope = Some(scope);
2505 self
2506 }
2507
2508 pub fn with_call_mode(mut self, call_mode: CallMode) -> Self {
2510 self.call_mode = call_mode;
2511 self
2512 }
2513}
2514
2515#[derive(Debug, Clone)]
2517pub struct BindDecision {
2518 kind: BindDecisionKind,
2519}
2520
2521impl BindDecision {
2522 pub fn accept() -> Self {
2524 Self {
2525 kind: BindDecisionKind::Accept,
2526 }
2527 }
2528
2529 pub fn reject(code: impl Into<String>, message: impl Into<String>) -> Self {
2531 Self {
2532 kind: BindDecisionKind::Reject {
2533 code: code.into(),
2534 message: message.into(),
2535 detail: None,
2536 },
2537 }
2538 }
2539
2540 pub fn reject_with_detail(
2547 code: impl Into<String>,
2548 message: impl Into<String>,
2549 detail: serde_json::Value,
2550 ) -> Self {
2551 Self {
2552 kind: BindDecisionKind::Reject {
2553 code: code.into(),
2554 message: message.into(),
2555 detail: Some(detail),
2556 },
2557 }
2558 }
2559}
2560
2561#[derive(Debug, Clone)]
2562enum BindDecisionKind {
2563 Accept,
2564 Reject {
2565 code: String,
2566 message: String,
2567 detail: Option<serde_json::Value>,
2568 },
2569}
2570
2571pub async fn serve<H>(manifest: ModuleManifest, handler: H) -> Result<(), SubcModuleError>
2580where
2581 H: ModuleHandler,
2582{
2583 ServeOptions::default().serve(manifest, handler).await
2584}
2585
2586#[derive(Clone, Debug, Default)]
2590pub struct ModuleStopHandle {
2591 token: CancellationToken,
2592}
2593
2594impl ModuleStopHandle {
2595 pub fn new() -> Self {
2596 Self::default()
2597 }
2598
2599 pub fn stop(&self) {
2602 self.token.cancel();
2603 }
2604}
2605
2606#[derive(Clone, Debug)]
2609#[non_exhaustive]
2610pub struct ServeOptions {
2611 registration_channel: bool,
2612 prefix_child: bool,
2613 writer_drain_timeout: Duration,
2614 stop_handle: ModuleStopHandle,
2615}
2616
2617impl Default for ServeOptions {
2618 fn default() -> Self {
2619 Self {
2620 writer_drain_timeout: DEFAULT_WRITER_DRAIN_TIMEOUT,
2621 registration_channel: false,
2622 prefix_child: false,
2623 stop_handle: ModuleStopHandle::new(),
2624 }
2625 }
2626}
2627
2628impl ServeOptions {
2629 pub fn with_writer_drain_timeout(mut self, timeout: Duration) -> Self {
2639 self.writer_drain_timeout = timeout;
2640 self
2641 }
2642
2643 pub fn with_stop_handle(mut self, handle: ModuleStopHandle) -> Self {
2646 self.stop_handle = handle;
2647 self
2648 }
2649
2650 pub async fn serve<H: ModuleHandler>(
2652 self,
2653 mut manifest: ModuleManifest,
2654 handler: H,
2655 ) -> Result<(), SubcModuleError> {
2656 let connection_file = parse_subc_arg(env::args_os().skip(1))?;
2657 if let Some(module_id) = module_id_from_env()? {
2658 manifest.module_id = module_id;
2659 }
2660 self.serve_with(&connection_file, manifest, handler).await
2661 }
2662
2663 pub async fn serve_with<H: ModuleHandler>(
2665 self,
2666 connection_file: &Path,
2667 manifest: ModuleManifest,
2668 handler: H,
2669 ) -> Result<(), SubcModuleError> {
2670 if let Some((_handle, future)) = self
2671 .serve_with_handle(connection_file, manifest, handler)
2672 .await?
2673 {
2674 future.await?;
2675 }
2676 Ok(())
2677 }
2678
2679 pub async fn serve_from_env_with_handle<H: ModuleHandler>(
2693 self,
2694 mut manifest: ModuleManifest,
2695 handler: H,
2696 ) -> Result<Option<(ModuleHandle, ModuleServeFuture)>, SubcModuleError> {
2697 let connection_file = parse_subc_arg(env::args_os().skip(1))?;
2698 if let Some(module_id) = module_id_from_env()? {
2699 manifest.module_id = module_id;
2700 }
2701 self.serve_with_handle(&connection_file, manifest, handler)
2702 .await
2703 }
2704
2705 pub async fn serve_with_handle<H: ModuleHandler>(
2717 self,
2718 connection_file: &Path,
2719 manifest: ModuleManifest,
2720 handler: H,
2721 ) -> Result<Option<(ModuleHandle, ModuleServeFuture)>, SubcModuleError> {
2722 prepare_connection(connection_file, manifest, handler, self).await
2723 }
2724}
2725
2726pub async fn serve_from_env_with_handle<H>(
2741 manifest: ModuleManifest,
2742 handler: H,
2743) -> Result<(ModuleHandle, ModuleServeFuture), SubcModuleError>
2744where
2745 H: ModuleHandler,
2746{
2747 ServeOptions::default()
2748 .serve_from_env_with_handle(manifest, handler)
2749 .await?
2750 .ok_or(SubcModuleError::ConnectionClosedBeforeHelloAck)
2751}
2752
2753pub async fn serve_with<H>(
2756 connection_file: &Path,
2757 manifest: ModuleManifest,
2758 handler: H,
2759) -> Result<(), SubcModuleError>
2760where
2761 H: ModuleHandler,
2762{
2763 ServeOptions::default()
2764 .serve_with(connection_file, manifest, handler)
2765 .await
2766}
2767
2768pub async fn serve_with_handle<H>(
2771 connection_file: &Path,
2772 manifest: ModuleManifest,
2773 handler: H,
2774) -> Result<(ModuleHandle, ModuleServeFuture), SubcModuleError>
2775where
2776 H: ModuleHandler,
2777{
2778 ServeOptions::default()
2779 .serve_with_handle(connection_file, manifest, handler)
2780 .await?
2781 .ok_or(SubcModuleError::ConnectionClosedBeforeHelloAck)
2782}
2783
2784async fn prepare_connection<H: ModuleHandler>(
2785 connection_file: &Path,
2786 manifest: ModuleManifest,
2787 handler: H,
2788 mut options: ServeOptions,
2789) -> Result<Option<(ModuleHandle, ModuleServeFuture)>, SubcModuleError> {
2790 options.registration_channel = registration::adopt(&manifest.module_id)?;
2791 let stream = tokio::select! {
2792 biased;
2793 () = options.stop_handle.token.cancelled() => return Ok(None),
2794 stream = async {
2795 let claim = if registration::supervised() && !options.registration_channel {
2796 registration::prefix_claim(&manifest.module_id).await
2797 .map_err(|error| registration::serve_claim_error(&manifest.module_id, error))?
2798 } else {
2799 None
2800 };
2801 let mut stream = connect_to_subc(connection_file, options.registration_channel).await?;
2802 if let Some(claim) = claim {
2803 registration::present_claim(&mut stream, claim, AUTH_DEADLINE).await
2804 .map_err(|error| registration::serve_claim_error(&manifest.module_id, error))?;
2805 options.prefix_child = true;
2806 }
2807 Ok::<_, SubcModuleError>(stream)
2808 } => stream?,
2809 };
2810 register_connection(stream, manifest, handler, options).await
2811}
2812
2813async fn register_connection<S, H>(
2814 stream: S,
2815 manifest: ModuleManifest,
2816 handler: H,
2817 options: ServeOptions,
2818) -> Result<Option<(ModuleHandle, ModuleServeFuture)>, SubcModuleError>
2819where
2820 S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
2821 H: ModuleHandler,
2822{
2823 let control_ops = control_ops::validate(handler.control_ops())?;
2824 let (mut read_half, write_half) = tokio::io::split(stream);
2825 let (tx, rx) = mpsc::channel::<Frame>(EGRESS_BUFFER);
2826 let connection_runtime = tokio::runtime::Handle::current();
2827 let mut writer = tokio::spawn(drain_writer(write_half, rx));
2828 let handler = Arc::new(handler);
2829 let declaration = if options.prefix_child {
2830 None
2831 } else {
2832 handler.config_declaration()
2833 };
2834
2835 let mut hello_ack = None;
2836 let provides = manifest.provides.clone();
2837 let handshake = async {
2838 send_hello(&tx, manifest, declaration.is_some(), &control_ops).await?;
2839 hello_ack = Some(expect_hello_ack(&mut read_half).await?);
2842 handler
2843 .on_hello_ack(hello_ack.as_ref().expect("validated HELLO_ACK"))
2844 .await;
2845 Ok::<_, SubcModuleError>(())
2846 };
2847 let mut writer_result = None;
2848 let handshake_result = tokio::select! {
2849 biased;
2850 () = options.stop_handle.token.cancelled() => None,
2851 result = handshake => Some(result),
2852 result = &mut writer => {
2853 writer_result = Some(result);
2854 Some(Ok(()))
2855 }
2856 };
2857 match handshake_result {
2858 Some(Ok(())) => {}
2859 other => {
2860 let result = match other {
2861 None => {
2862 let deadline = Instant::now() + options.writer_drain_timeout;
2863 let result = timeout_at(deadline, send_goodbye(&tx)).await;
2864 drop(tx);
2865 let flush = finish_writer_and_drain(writer, &mut read_half, deadline).await;
2866 handler.on_connection_end(ConnectionEnd::Closed).await;
2867 match result.unwrap_or(Ok(())) {
2868 Ok(()) | Err(SubcModuleError::WriterClosed) => {}
2869 Err(error) => return Err(error),
2870 }
2871 match flush.0 {
2872 Err(SubcModuleError::FrameIo(FrameIoError::Io(error)))
2873 if is_disconnect(&error) => {}
2874 result => result?,
2875 }
2876 return Ok(None);
2877 }
2878 Some(Err(error)) => error,
2879 Some(Ok(_)) => unreachable!(),
2880 };
2881 drop(tx);
2882 let deadline = Instant::now() + options.writer_drain_timeout;
2883 let _ = finish_writer_and_drain(writer, &mut read_half, deadline).await;
2884 return Err(result);
2885 }
2886 }
2887 let mut ack = match hello_ack {
2888 Some(ack) => ack,
2889 None => {
2890 return Err(writer_ended(
2891 writer_result.expect("writer ended before HELLO_ACK"),
2892 ))
2893 }
2894 };
2895 if options.prefix_child {
2896 ack.subc_ops.retain(|op| {
2899 matches!(
2900 op.as_str(),
2901 "catalog.update" | "scope.describe" | "supervisor.live_roots" | "activity.record"
2902 )
2903 });
2904 }
2905 let writer_end = writer_result.map(writer_connection_end);
2908
2909 let Some(connection_token) = checked_increment(&NEXT_MODULE_CONNECTION_TOKEN) else {
2910 drop(tx);
2911 let deadline = Instant::now() + options.writer_drain_timeout;
2912 if writer_end.is_none() {
2913 let _ = finish_writer_and_drain(writer, &mut read_half, deadline).await;
2914 }
2915 return Err(SubcModuleError::ConnectionTokenExhausted);
2916 };
2917 let close_token = CancellationToken::new();
2918 let handle = ModuleHandle::new(
2919 &ack,
2920 tx.clone(),
2921 connection_token,
2922 close_token,
2923 connection_runtime,
2924 );
2925 handle.shared.lock_inner().current_provides = Some(provides);
2926 handle
2927 .shared
2928 .registration
2929 .prefix_child
2930 .store(options.prefix_child, Ordering::Release);
2931 let _ = handle.shared.served_control_ops.set(control_ops);
2932 if options.registration_channel {
2933 registration::install_owner(&handle)?;
2934 }
2935 if let Some(declaration) = declaration {
2936 let _ = handle.shared.config.declaration.set(declaration);
2937 }
2938 let serve_future = connection_serve_future_with_options(
2939 read_half,
2940 tx,
2941 handler,
2942 handle.clone(),
2943 writer,
2944 options,
2945 writer_end,
2946 );
2947 Ok(Some((handle, serve_future)))
2948}
2949
2950#[cfg(any(test, feature = "test-support"))]
2953fn connection_serve_future<R, H>(
2954 read_half: R,
2955 tx: mpsc::Sender<Frame>,
2956 handler: Arc<H>,
2957 handle: ModuleHandle,
2958 writer: tokio::task::JoinHandle<Result<(), WriterFailure>>,
2959) -> ModuleServeFuture
2960where
2961 R: AsyncRead + Unpin + Send + 'static,
2962 H: ModuleHandler,
2963{
2964 connection_serve_future_with_options(
2965 read_half,
2966 tx,
2967 handler,
2968 handle,
2969 writer,
2970 ServeOptions::default(),
2971 None,
2972 )
2973}
2974
2975fn connection_serve_future_with_options<R, H>(
2976 mut read_half: R,
2977 tx: mpsc::Sender<Frame>,
2978 handler: Arc<H>,
2979 handle: ModuleHandle,
2980 mut writer: tokio::task::JoinHandle<Result<(), WriterFailure>>,
2981 options: ServeOptions,
2982 writer_end: Option<Result<ConnectionEnd, SubcModuleError>>,
2983) -> ModuleServeFuture
2984where
2985 R: AsyncRead + Unpin + Send + 'static,
2986 H: ModuleHandler,
2987{
2988 let serve_handle = handle.clone();
2989 handle.install_dispatch_pools(handler.request_pools());
2993 Box::pin(async move {
2994 let dispatcher = RequestDispatcher::with_pools(serve_handle.dispatch_pools());
2998 if !options.prefix_child {
2999 config::start(serve_handle.clone(), Arc::clone(&handler), &dispatcher);
3000 }
3001 let mut writer_finished = writer_end.is_some();
3002 let mut loop_result = if let Some(end) = writer_end {
3003 end
3004 } else {
3005 tokio::select! {
3006 biased;
3007 result = module_loop(&mut read_half, &tx, Arc::clone(&handler), serve_handle.clone(), &dispatcher, &options.stop_handle) => result,
3008 result = &mut writer => {
3009 writer_finished = true;
3010 writer_connection_end(result)
3011 }
3012 }
3013 };
3014 if matches!(loop_result, Err(SubcModuleError::WriterClosed)) && !writer_finished {
3018 writer_finished = true;
3019 loop_result = writer_connection_end((&mut writer).await);
3020 }
3021 let deadline = Instant::now() + options.writer_drain_timeout;
3022 serve_handle.shared.config.stop.cancel();
3023 dispatcher.wait_for_draining_hooks_to_start().await;
3024 dispatcher.tasks.close();
3025 if matches!(loop_result, Ok(ConnectionEnd::Closed))
3026 && options.stop_handle.token.is_cancelled()
3027 {
3028 let _ = timeout_at(deadline, dispatcher.tasks.wait()).await;
3030 }
3031 let orderly = loop_result.is_ok();
3032 if let Some(error) = dispatcher.take_failure() {
3033 if !orderly || !matches!(error, SubcModuleError::WriterClosed) {
3034 loop_result = Err(error);
3035 }
3036 }
3037 dispatcher.cancel_all();
3038 let _ = timeout_at(deadline, dispatcher.tasks.wait()).await;
3039 let abandoned_replies = dispatcher
3040 .in_flight
3041 .lock()
3042 .unwrap_or_else(|e| e.into_inner())
3043 .len();
3044 if let Some(error) = dispatcher.take_failure() {
3045 if !orderly || !matches!(error, SubcModuleError::WriterClosed) {
3046 loop_result = Err(error);
3047 }
3048 }
3049 dispatcher.abort_all();
3050 dispatcher.tasks.wait().await;
3051 let daemon_eof = matches!(loop_result, Ok(ConnectionEnd::Eof));
3052 let locally_closed = matches!(loop_result, Ok(ConnectionEnd::Closed));
3053 let module_ended =
3058 !writer_finished && matches!(loop_result, Ok(ConnectionEnd::Closed) | Err(_));
3059 let deadline = Instant::now() + options.writer_drain_timeout;
3060 if matches!(loop_result, Ok(ConnectionEnd::Closed))
3061 && options.stop_handle.token.is_cancelled()
3062 {
3063 match timeout_at(deadline, send_goodbye(&tx)).await {
3064 Ok(Ok(())) | Err(_) => {}
3065 Ok(Err(SubcModuleError::WriterClosed)) => {}
3066 Ok(Err(error)) => loop_result = Err(error),
3067 }
3068 }
3069 serve_handle.close_connection();
3070 drop(tx);
3071 let loop_result = match loop_result {
3072 Ok(end) => {
3073 handler.on_connection_end(end).await;
3074 Ok(())
3075 }
3076 Err(error) => Err(error),
3077 };
3078
3079 let (writer_result, undelivered_replies) = if writer_finished {
3080 (Ok(()), 0)
3081 } else if module_ended {
3082 finish_writer_and_drain(writer, &mut read_half, deadline).await
3083 } else {
3084 finish_writer(writer, deadline).await
3085 };
3086 let undelivered_replies = undelivered_replies as u64
3087 + dispatcher.undelivered_replies.load(Ordering::Relaxed)
3088 + abandoned_replies as u64;
3089 if daemon_eof && undelivered_replies > 0 {
3090 tracing::warn!(
3091 undelivered_replies,
3092 "daemon EOF: replies could not be delivered during drain"
3093 );
3094 }
3095 if options.registration_channel && !locally_closed {
3096 std::process::exit(if loop_result.is_ok() { 0 } else { 1 });
3099 }
3100 match (loop_result, writer_result) {
3101 (Err(SubcModuleError::WriterClosed), Err(writer_error)) => Err(writer_error),
3102 (Err(loop_err), _) => Err(loop_err),
3103 (Ok(()), Ok(())) => Ok(()),
3104 (Ok(()), Err(SubcModuleError::FrameIo(FrameIoError::Io(err))))
3109 if is_disconnect(&err) =>
3110 {
3111 Ok(())
3112 }
3113 (Ok(()), Err(error)) => Err(error),
3114 }
3115 })
3116}
3117
3118async fn module_loop<R, H>(
3119 mut reader: R,
3120 egress: &mpsc::Sender<Frame>,
3121 handler: Arc<H>,
3122 module_handle: ModuleHandle,
3123 dispatcher: &RequestDispatcher,
3124 stop: &ModuleStopHandle,
3125) -> Result<ConnectionEnd, SubcModuleError>
3126where
3127 R: AsyncRead + Unpin,
3128 H: ModuleHandler,
3129{
3130 serve_frames(
3131 &mut reader,
3132 egress,
3133 &handler,
3134 &module_handle,
3135 dispatcher,
3136 stop,
3137 )
3138 .await
3139}
3140
3141async fn serve_frames<R, H>(
3142 reader: &mut R,
3143 egress: &mpsc::Sender<Frame>,
3144 handler: &Arc<H>,
3145 module_handle: &ModuleHandle,
3146 dispatcher: &RequestDispatcher,
3147 stop: &ModuleStopHandle,
3148) -> Result<ConnectionEnd, SubcModuleError>
3149where
3150 R: AsyncRead + Unpin,
3151 H: ModuleHandler,
3152{
3153 loop {
3154 let read = tokio::select! {
3155 biased;
3156 () = dispatcher.failed.cancelled() => return Err(dispatcher.take_failure().expect("failure signalled")),
3157 () = stop.token.cancelled() => return Ok(ConnectionEnd::Closed),
3158 () = module_handle.shared.close_token.cancelled() => return Ok(ConnectionEnd::Closed),
3159 read = read_frame(reader) => read,
3160 };
3161 let frame = match read {
3162 Ok(Some(frame)) => frame,
3163 Ok(None) => return Ok(ConnectionEnd::Eof),
3165 Err(FrameIoError::Io(error)) if is_disconnect(&error) => {
3168 return Ok(ConnectionEnd::Reset);
3169 }
3170 Err(err) => return Err(SubcModuleError::FrameIo(err)),
3171 };
3172 if !handle_frame(
3173 frame,
3174 egress,
3175 Arc::clone(handler),
3176 dispatcher.clone(),
3177 module_handle.clone(),
3178 )
3179 .await?
3180 {
3181 return Ok(ConnectionEnd::Goodbye);
3183 }
3184 }
3185}
3186
3187async fn handle_frame<H>(
3188 frame: Frame,
3189 egress: &mpsc::Sender<Frame>,
3190 handler: Arc<H>,
3191 dispatcher: RequestDispatcher,
3192 module_handle: ModuleHandle,
3193) -> Result<bool, SubcModuleError>
3194where
3195 H: ModuleHandler,
3196{
3197 if frame.header.channel != 0
3198 && !module_handle.validate_ingress(frame.header.channel, frame.header.epoch)?
3199 {
3200 return Ok(true);
3201 }
3202 match frame.header.ty {
3203 FrameType::Ping if frame.header.channel == 0 => {
3204 let pong = Frame::build_with_version(
3205 frame.header.ver,
3206 FrameType::Pong,
3207 frame.header.flags,
3208 0,
3209 0,
3210 frame.header.corr,
3211 Vec::new(),
3212 )
3213 .map_err(SubcModuleError::FrameBuild)?;
3214 send_outbound(egress, pong).await?;
3215 Ok(true)
3216 }
3217 FrameType::Goodbye if frame.header.channel == 0 => Ok(false),
3218 FrameType::Goodbye => {
3219 let handle = module_handle.route_handle(frame.header.channel, frame.header.epoch);
3220 if module_handle.remove_route(handle)? {
3221 cancel_handle(&dispatcher.in_flight, handle)?;
3222 handler.on_route_gone(&handle).await;
3223 }
3224 Ok(true)
3225 }
3226 FrameType::Response if frame.header.channel == 0 => {
3227 let _ = module_handle.handle_control_reply(frame);
3228 Ok(true)
3229 }
3230 FrameType::Error | FrameType::StreamData | FrameType::StreamEnd
3231 if frame.header.channel == 0 =>
3232 {
3233 let _ = module_handle.handle_control_reply(frame);
3234 Ok(true)
3235 }
3236 FrameType::Cancel => {
3237 handle_cancel(frame, &dispatcher.in_flight)?;
3238 Ok(true)
3239 }
3240 FrameType::Request if frame.header.channel == 0 => {
3241 handle_control_request(frame, egress, handler, dispatcher, module_handle.clone())
3242 .await?;
3243 Ok(true)
3244 }
3245 FrameType::Request => {
3246 spawn_data_request(frame, egress.clone(), handler, dispatcher, module_handle)?;
3247 Ok(true)
3248 }
3249 FrameType::Push if frame.header.channel == 0 => {
3250 if config::changed(&frame, &module_handle) {
3251 return Ok(true);
3252 }
3253 handle_control_push(&frame, handler, &dispatcher);
3254 Ok(true)
3255 }
3256 _ => Ok(true),
3257 }
3258}
3259
3260fn handle_control_push<H>(frame: &Frame, handler: Arc<H>, dispatcher: &RequestDispatcher)
3265where
3266 H: ModuleHandler,
3267{
3268 match serde_json::from_slice::<ModuleControlCommand>(&frame.body) {
3269 Ok(ModuleControlCommand::Draining {
3270 reason,
3271 deadline_ms,
3272 }) => {
3273 let started = spawn_draining_hook(
3274 handler,
3275 sdk_route_close_reason(reason),
3276 drain_deadline(deadline_ms),
3277 dispatcher,
3278 );
3279 dispatcher
3280 .draining_hooks
3281 .lock()
3282 .unwrap_or_else(|poisoned| poisoned.into_inner())
3283 .push(started);
3284 }
3285 Err(error) => {
3286 if !dispatcher
3287 .undecodable_push_logged
3288 .swap(true, Ordering::Relaxed)
3289 {
3290 let op = serde_json::from_slice::<serde_json::Value>(&frame.body)
3291 .ok()
3292 .and_then(|body| body.get("op")?.as_str().map(str::to_string));
3293 tracing::warn!(
3294 op = op.as_deref().unwrap_or("<none>"),
3295 error = %error,
3296 "ignoring a channel-0 push from subc that this SDK cannot decode; \
3297 further undecodable pushes on this connection are ignored without logging"
3298 );
3299 }
3300 }
3301 }
3302}
3303
3304fn spawn_draining_hook<H>(
3308 handler: Arc<H>,
3309 reason: RouteCloseReason,
3310 deadline: SystemTime,
3311 dispatcher: &RequestDispatcher,
3312) -> oneshot::Receiver<()>
3313where
3314 H: ModuleHandler,
3315{
3316 let (started_tx, started_rx) = oneshot::channel();
3317 dispatcher.spawn(async move {
3318 let mut hook = handler.on_draining(reason, deadline);
3319 let mut started_tx = Some(started_tx);
3320 std::future::poll_fn(|cx| {
3321 let poll = hook.as_mut().poll(cx);
3322 if let Some(started) = started_tx.take() {
3323 let _ = started.send(());
3324 }
3325 poll
3326 })
3327 .await;
3328 });
3329 started_rx
3330}
3331
3332fn sdk_route_close_reason(reason: subc_protocol::RouteCloseReason) -> RouteCloseReason {
3336 match serde_json::to_value(reason) {
3337 Ok(serde_json::Value::String(wire)) => RouteCloseReason::from_wire(&wire),
3338 _ => RouteCloseReason::Unknown(format!("{reason:?}")),
3339 }
3340}
3341
3342fn drain_deadline(deadline_ms: u64) -> SystemTime {
3346 UNIX_EPOCH
3347 .checked_add(Duration::from_millis(deadline_ms))
3348 .unwrap_or_else(SystemTime::now)
3349}
3350
3351fn spawn_data_request<H>(
3352 frame: Frame,
3353 egress: mpsc::Sender<Frame>,
3354 handler: Arc<H>,
3355 dispatcher: RequestDispatcher,
3356 module_handle: ModuleHandle,
3357) -> Result<(), SubcModuleError>
3358where
3359 H: ModuleHandler,
3360{
3361 let handle = module_handle.route_handle(frame.header.channel, frame.header.epoch);
3362 let corr = frame.header.corr;
3363 let cancellation = CancellationToken::new();
3364 {
3365 let mut guard = lock_in_flight(&dispatcher.in_flight)?;
3366 guard.insert((handle.channel, handle.epoch, corr), cancellation.clone());
3367 }
3368
3369 let ctx = RequestCtx {
3370 handle,
3371 corr,
3372 ver: frame.header.ver,
3373 egress,
3374 module_handle,
3375 cancelled: cancellation,
3376 binary_reply: Arc::new(AtomicBool::new(false)),
3377 request_flags: frame.header.flags,
3378 request_body: Arc::from(frame.body.as_slice()),
3379 };
3380 let body = frame.body;
3381 let in_flight = Arc::clone(&dispatcher.in_flight);
3382 let (pool, op) = dispatcher.pools.classify(&body);
3385 let pool = pool.clone();
3386 let wait = pool.start_waiting((handle.channel, handle.epoch, corr));
3387 dispatcher.clone().spawn(async move {
3388 let waiting = WaitingRequest {
3389 op,
3390 channel: handle.channel,
3391 corr,
3392 };
3393 let permit = match wait_for_permit(&pool, wait, waiting, &ctx.cancelled).await {
3394 PermitWaitOutcome::Acquired(permit) => Some(permit),
3395 PermitWaitOutcome::Cancelled => None,
3398 PermitWaitOutcome::Closed => {
3399 dispatcher
3401 .undelivered_replies
3402 .fetch_add(1, Ordering::Relaxed);
3403 if let Ok(mut guard) = in_flight.lock() {
3404 guard.remove(&(handle.channel, handle.epoch, corr));
3405 }
3406 return;
3407 }
3408 };
3409 let outcome = if permit.is_none() || ctx.cancelled.is_cancelled() {
3412 Ok(HandlerOutcome::Error {
3413 code: "cancelled".to_string(),
3414 message: "request cancelled".to_string(),
3415 })
3416 } else {
3417 catch_handler_panic(async { handler.handle(ctx.clone(), body).await }).await
3418 };
3419 let panicked = outcome.is_err();
3420 let outcome = outcome.unwrap_or_else(|()| HandlerOutcome::Error {
3421 code: "internal".to_string(),
3422 message: "module handler panicked".to_string(),
3423 });
3424 match send_handler_outcome(&ctx, outcome).await {
3425 Err(SubcModuleError::StaleRouteHandle(_)) if !panicked => {}
3429 Err(error) => {
3430 if matches!(error, SubcModuleError::WriterClosed) {
3431 dispatcher
3432 .undelivered_replies
3433 .fetch_add(1, Ordering::Relaxed);
3434 }
3435 dispatcher.fail(error);
3436 }
3437 Ok(()) if panicked => dispatcher.fail(SubcModuleError::HandlerPanic),
3438 Ok(()) => {}
3439 }
3440 if let Ok(mut guard) = in_flight.lock() {
3441 guard.remove(&(handle.channel, handle.epoch, corr));
3442 }
3443 });
3444 Ok(())
3445}
3446
3447fn spawn_health_request<H>(
3448 frame: Frame,
3449 egress: mpsc::Sender<Frame>,
3450 handler: Arc<H>,
3451 dispatcher: RequestDispatcher,
3452) -> Result<(), SubcModuleError>
3453where
3454 H: ModuleHandler,
3455{
3456 let channel = frame.header.channel;
3457 let epoch = frame.header.epoch;
3458 let corr = frame.header.corr;
3459 let ver = frame.header.ver;
3460 let cancellation = CancellationToken::new();
3461 {
3462 let mut guard = lock_in_flight(&dispatcher.in_flight)?;
3463 guard.insert((channel, epoch, corr), cancellation.clone());
3464 }
3465
3466 let in_flight = Arc::clone(&dispatcher.in_flight);
3467 dispatcher.clone().spawn(async move {
3468 if !cancellation.is_cancelled() {
3471 let result = async {
3472 let report = catch_handler_panic(async { handler.health().await }).await;
3473 let panicked = report.is_err();
3474 let (ty, body) = match report {
3475 Ok(report) => (
3476 FrameType::Response,
3477 serde_json::to_vec(&ModuleControlResponse::from(
3478 dispatcher.fold_health(report),
3479 ))?,
3480 ),
3481 Err(()) => (
3482 FrameType::Error,
3483 serde_json::to_vec(&ErrorBody::new("internal", "module handler panicked"))?,
3484 ),
3485 };
3486 let (ty, flags, body) = bounded_terminal(ty, control_flags(), body)?;
3487 let frame = Frame::build_with_version(ver, ty, flags, channel, epoch, corr, body)
3488 .map_err(SubcModuleError::FrameBuild)?;
3489 send_outbound(&egress, frame).await?;
3490 if panicked {
3491 return Err(SubcModuleError::HandlerPanic);
3492 }
3493 Ok(())
3494 }
3495 .await;
3496 if let Err(error) = result {
3497 if matches!(error, SubcModuleError::WriterClosed) {
3498 dispatcher
3499 .undelivered_replies
3500 .fetch_add(1, Ordering::Relaxed);
3501 }
3502 dispatcher.fail(error);
3503 }
3504 }
3505 if let Ok(mut guard) = in_flight.lock() {
3506 guard.remove(&(channel, epoch, corr));
3507 }
3508 });
3509 Ok(())
3510}
3511
3512async fn send_handler_outcome(
3513 ctx: &RequestCtx,
3514 outcome: HandlerOutcome,
3515) -> Result<(), SubcModuleError> {
3516 match outcome {
3517 HandlerOutcome::Response(body) => {
3518 let flags = Flags::new(
3519 ctx.binary_reply.load(Ordering::Relaxed),
3520 Priority::Interactive,
3521 false,
3522 );
3523 ctx.send_frame(FrameType::Response, flags, body).await
3524 }
3525 HandlerOutcome::Error { code, message } => {
3526 let body = serde_json::to_vec(&ErrorBody::new(code, message))
3527 .map_err(SubcModuleError::Json)?;
3528 ctx.send_frame(FrameType::Error, data_flags(), body).await
3529 }
3530 HandlerOutcome::ErrorWithDetail {
3531 code,
3532 message,
3533 detail,
3534 } => {
3535 let body = serde_json::to_vec(&ErrorBody::new(code, message).with_detail(detail))
3536 .map_err(SubcModuleError::Json)?;
3537 ctx.send_frame(FrameType::Error, data_flags(), body).await
3538 }
3539 HandlerOutcome::Streamed => {
3540 ctx.send_frame(FrameType::StreamEnd, data_flags(), Vec::new())
3541 .await
3542 }
3543 }
3544}
3545
3546async fn catch_handler_panic<F: Future>(future: F) -> Result<F::Output, ()> {
3549 let mut future = std::pin::pin!(future);
3550 std::future::poll_fn(
3551 |cx| match catch_unwind(AssertUnwindSafe(|| future.as_mut().poll(cx))) {
3552 Ok(poll) => poll.map(Ok),
3553 Err(_) => std::task::Poll::Ready(Err(())),
3554 },
3555 )
3556 .await
3557}
3558
3559fn bounded_terminal(
3560 ty: FrameType,
3561 flags: Flags,
3562 body: Vec<u8>,
3563) -> Result<(FrameType, Flags, Vec<u8>), SubcModuleError> {
3564 let size = subc_protocol::HEADER_LEN + body.len();
3565 let limit = subc_protocol::MAX_DELIVERED_FRAME_LEN;
3566 if matches!(ty, FrameType::Response | FrameType::Error) && size > limit {
3567 let body = serde_json::to_vec(
3568 &ErrorBody::new("frame_too_large", "module reply exceeds frame limit")
3569 .with_detail(serde_json::json!({ "size": size, "limit": limit })),
3570 )?;
3571 return Ok((FrameType::Error, flags, body));
3573 }
3574 Ok((ty, flags, body))
3575}
3576
3577fn handle_cancel(frame: Frame, in_flight: &InFlight) -> Result<(), SubcModuleError> {
3578 let guard = lock_in_flight(in_flight)?;
3579 if let Some(cancellation) =
3580 guard.get(&(frame.header.channel, frame.header.epoch, frame.header.corr))
3581 {
3582 cancellation.cancel();
3583 }
3584 Ok(())
3585}
3586
3587fn cancel_handle(in_flight: &InFlight, handle: RouteHandle) -> Result<(), SubcModuleError> {
3588 let cancelled = {
3589 let mut guard = lock_in_flight(in_flight)?;
3590 let keys = guard
3591 .keys()
3592 .copied()
3593 .filter(|(channel, epoch, _)| *channel == handle.channel && *epoch == handle.epoch)
3594 .collect::<Vec<_>>();
3595 keys.into_iter()
3596 .filter_map(|key| guard.remove(&key))
3597 .collect::<Vec<_>>()
3598 };
3599 for cancellation in cancelled {
3600 cancellation.cancel();
3601 }
3602 Ok(())
3603}
3604
3605async fn handle_control_request<H>(
3606 frame: Frame,
3607 egress: &mpsc::Sender<Frame>,
3608 handler: Arc<H>,
3609 dispatcher: RequestDispatcher,
3610 module_handle: ModuleHandle,
3611) -> Result<(), SubcModuleError>
3612where
3613 H: ModuleHandler,
3614{
3615 if control_ops::request(
3616 &frame,
3617 egress,
3618 Arc::clone(&handler),
3619 &dispatcher,
3620 &module_handle,
3621 )
3622 .await?
3623 {
3624 return Ok(());
3625 }
3626 if config::review(
3627 &frame,
3628 egress,
3629 Arc::clone(&handler),
3630 &dispatcher,
3631 &module_handle,
3632 ) {
3633 return Ok(());
3634 }
3635 let request = match serde_json::from_slice::<ModuleControlRequest>(&frame.body) {
3641 Ok(request) => request,
3642 Err(error) => {
3643 let body = serde_json::to_vec(&ErrorBody::new(
3644 "invalid_request",
3645 format!("control request could not be decoded by this module: {error}"),
3646 ))
3647 .map_err(SubcModuleError::Json)?;
3648 let refusal = Frame::build_with_version(
3649 frame.header.ver,
3650 FrameType::Error,
3651 control_flags(),
3652 0,
3653 0,
3654 frame.header.corr,
3655 body,
3656 )
3657 .map_err(SubcModuleError::FrameBuild)?;
3658 send_outbound(egress, refusal).await?;
3659 return Ok(());
3660 }
3661 };
3662 match request {
3663 ModuleControlRequest::RouteBind {
3664 route_channel,
3665 epoch,
3666 target,
3667 identity,
3668 principal,
3669 consumer_capabilities,
3670 role_versions,
3671 admission_facts,
3672 scope,
3673 call_mode,
3674 } => {
3675 if let Some(stale) = module_handle.installed_route(route_channel)? {
3682 if epoch <= stale.epoch {
3683 let body = serde_json::to_vec(&ErrorBody::new(
3684 "route_rejected",
3685 format!(
3686 "route.bind epoch {epoch} does not supersede installed epoch {} on channel {route_channel}",
3687 stale.epoch
3688 ),
3689 ))
3690 .map_err(SubcModuleError::Json)?;
3691 let reject = Frame::build_with_version(
3692 frame.header.ver,
3693 FrameType::Error,
3694 control_flags(),
3695 0,
3696 0,
3697 frame.header.corr,
3698 body,
3699 )
3700 .map_err(SubcModuleError::FrameBuild)?;
3701 send_outbound(egress, reject).await?;
3702 return Ok(());
3703 }
3704 if module_handle.remove_route(stale)? {
3705 cancel_handle(&dispatcher.in_flight, stale)?;
3706 handler.on_route_gone(&stale).await;
3707 }
3708 }
3709 let handle = module_handle.route_handle(route_channel, epoch);
3710 let peer =
3714 match serde_json::from_slice::<subc_protocol::peer::RouteBindPeer>(&frame.body) {
3715 Ok(peer) => peer,
3716 Err(error) => {
3717 tracing::warn!(
3718 channel = route_channel,
3719 epoch,
3720 %error,
3721 "route.bind peer keys did not decode; treating them as absent"
3722 );
3723 subc_protocol::peer::RouteBindPeer::new()
3724 }
3725 };
3726 let req = RouteBindRequest {
3727 handle,
3728 target,
3729 identity,
3730 principal,
3731 consumer_capabilities,
3732 role_versions,
3733 admission_facts,
3734 call_mode: call_mode.unwrap_or_else(|| derive_call_mode(scope.as_ref())),
3735 scope,
3736 peer,
3737 };
3738 let decision = handler.on_bind(&req).await;
3739 match decision.kind {
3740 BindDecisionKind::Accept => {
3741 let response = match serde_json::to_vec(&ModuleControlResponse::RouteBindAck {})
3742 .map_err(SubcModuleError::Json)
3743 .and_then(|body| {
3744 Frame::build_with_version(
3745 frame.header.ver,
3746 FrameType::Response,
3747 control_flags(),
3748 0,
3749 0,
3750 frame.header.corr,
3751 body,
3752 )
3753 .map_err(SubcModuleError::FrameBuild)
3754 }) {
3755 Ok(response) => response,
3756 Err(err) => {
3757 handler.on_route_gone(&handle).await;
3758 return Err(err);
3759 }
3760 };
3761 if let Err(err) = send_outbound(egress, response).await {
3762 handler.on_route_gone(&handle).await;
3763 return Err(err);
3764 }
3765 if let Err(err) = module_handle.install_route(handle) {
3766 handler.on_route_gone(&handle).await;
3767 return Err(err);
3768 }
3769 handler.on_bound(&handle).await;
3770 }
3771 BindDecisionKind::Reject {
3772 code,
3773 message,
3774 detail,
3775 } => {
3776 let body = match detail {
3777 Some(detail) => ErrorBody::new(code, message).with_detail(detail),
3778 None => ErrorBody::new(code, message),
3779 };
3780 let result = serde_json::to_vec(&body)
3781 .map_err(SubcModuleError::Json)
3782 .and_then(|body| {
3783 Frame::build_with_version(
3784 frame.header.ver,
3785 FrameType::Error,
3786 control_flags(),
3787 0,
3788 0,
3789 frame.header.corr,
3790 body,
3791 )
3792 .map_err(SubcModuleError::FrameBuild)
3793 });
3794 let result = match result {
3795 Ok(response) => send_outbound(egress, response).await,
3796 Err(err) => Err(err),
3797 };
3798 handler.on_route_gone(&handle).await;
3799 result?;
3800 }
3801 }
3802 }
3803 ModuleControlRequest::HealthCheck {} => {
3804 spawn_health_request(frame, egress.clone(), handler, dispatcher)?;
3805 }
3806 }
3807 Ok(())
3808}
3809
3810async fn send_hello(
3811 egress: &mpsc::Sender<Frame>,
3812 mut manifest: ModuleManifest,
3813 config_gate: bool,
3814 extra_control_ops: &[String],
3815) -> Result<(), SubcModuleError> {
3816 let launch_nonce = if registration::supervised() {
3817 None
3818 } else {
3819 match retained_launch_nonce() {
3820 Some(retained) => Some(retained),
3821 None => launch_nonce()
3822 .map_err(SubcModuleError::LaunchNonce)?
3823 .map(|nonce| nonce.value().to_string()),
3824 }
3825 };
3826 stamp_launch_nonce_source(&mut manifest, launch_nonce.as_deref());
3827 let mut control_ops = vec![MODULE_CONTROL_OP_HEALTH_CHECK.to_string()];
3828 if config_gate {
3829 control_ops.push(config::CONFIG_REVIEW_OP.to_owned());
3830 }
3831 control_ops.extend_from_slice(extra_control_ops);
3832 let body = serde_json::to_vec(&ModuleHelloBody {
3833 manifest,
3834 protocol_ver: PROTOCOL_VERSION,
3835 control_ops: Some(control_ops),
3836 launch_nonce,
3837 })
3838 .map_err(SubcModuleError::Json)?;
3839 let frame = Frame::build(FrameType::Hello, control_flags(), 0, 0, HELLO_CORR, body)
3840 .map_err(SubcModuleError::FrameBuild)?;
3841 send_outbound(egress, frame).await
3842}
3843
3844async fn expect_hello_ack<R>(reader: &mut R) -> Result<ModuleHelloAckBody, SubcModuleError>
3845where
3846 R: AsyncRead + Unpin,
3847{
3848 let Some(frame) = read_frame(reader).await.map_err(SubcModuleError::FrameIo)? else {
3849 return Err(SubcModuleError::ConnectionClosedBeforeHelloAck);
3850 };
3851 match frame.header.ty {
3852 FrameType::HelloAck => serde_json::from_slice(&frame.body).map_err(SubcModuleError::Json),
3853 FrameType::Error => {
3854 let body =
3855 serde_json::from_slice::<ErrorBody>(&frame.body).map_err(SubcModuleError::Json)?;
3856 Err(SubcModuleError::HelloRejected { body })
3857 }
3858 ty => Err(SubcModuleError::UnexpectedHelloAck { ty }),
3859 }
3860}
3861
3862pub trait ModuleStream: AsyncRead + AsyncWrite + Unpin + Send {}
3864impl<T: AsyncRead + AsyncWrite + Unpin + Send> ModuleStream for T {}
3865
3866async fn connect_to_subc(
3867 connection_file_path: &Path,
3868 registration_channel: bool,
3869) -> Result<Box<dyn ModuleStream>, SubcModuleError> {
3870 let conn = connection_file::read_for_client(connection_file_path).map_err(|source| {
3871 SubcModuleError::ConnectionFile {
3872 path: connection_file_path.to_path_buf(),
3873 source,
3874 }
3875 })?;
3876 if let Some(mut stream) = if registration_channel {
3877 registration::take_stream()?
3878 } else {
3879 None
3880 } {
3881 authenticate_client(&mut stream, &conn, AUTH_DEADLINE)
3882 .await
3883 .map_err(|source| SubcModuleError::Auth {
3884 path: connection_file_path.to_path_buf(),
3885 endpoint: "registration channel".into(),
3886 source,
3887 })?;
3888 return Ok(stream);
3889 }
3890 let endpoint = conn
3891 .endpoints
3892 .first()
3893 .ok_or_else(|| SubcModuleError::NoEndpoint {
3894 path: connection_file_path.to_path_buf(),
3895 })?;
3896 let endpoint_label = format!("{}:{}", endpoint.host, endpoint.port);
3897 let mut stream = connect_endpoint(&endpoint.host, endpoint.port)
3898 .await
3899 .map_err(|source| SubcModuleError::Connect {
3900 path: connection_file_path.to_path_buf(),
3901 endpoint: endpoint_label.clone(),
3902 source,
3903 })?;
3904 let _ = stream.set_nodelay(true);
3914 authenticate_client(&mut stream, &conn, AUTH_DEADLINE)
3915 .await
3916 .map_err(|source| SubcModuleError::Auth {
3917 path: connection_file_path.to_path_buf(),
3918 endpoint: endpoint_label,
3919 source,
3920 })?;
3921 Ok(Box::new(stream))
3922}
3923
3924async fn connect_endpoint(host: &str, port: u16) -> io::Result<TcpStream> {
3925 let host = host
3926 .strip_prefix('[')
3927 .and_then(|h| h.strip_suffix(']'))
3928 .unwrap_or(host);
3929 TcpStream::connect((host, port)).await
3930}
3931
3932async fn send_goodbye(tx: &mpsc::Sender<Frame>) -> Result<(), SubcModuleError> {
3933 let frame = Frame::build(FrameType::Goodbye, control_flags(), 0, 0, 0, Vec::new())
3934 .map_err(SubcModuleError::FrameBuild)?;
3935 send_outbound(tx, frame).await
3936}
3937
3938fn is_disconnect(error: &io::Error) -> bool {
3939 matches!(
3940 error.kind(),
3941 io::ErrorKind::ConnectionReset
3942 | io::ErrorKind::ConnectionAborted
3943 | io::ErrorKind::BrokenPipe
3944 )
3945}
3946
3947fn writer_ended(
3948 result: Result<Result<(), WriterFailure>, tokio::task::JoinError>,
3949) -> SubcModuleError {
3950 match result {
3951 Ok(Ok(())) => SubcModuleError::WriterClosed,
3952 Ok(Err(error)) => SubcModuleError::FrameIo(error.error),
3953 Err(error) => SubcModuleError::WriterTask(error),
3954 }
3955}
3956
3957fn writer_connection_end(
3958 result: Result<Result<(), WriterFailure>, tokio::task::JoinError>,
3959) -> Result<ConnectionEnd, SubcModuleError> {
3960 match writer_ended(result) {
3961 SubcModuleError::FrameIo(FrameIoError::Io(error)) if is_disconnect(&error) => {
3962 Ok(ConnectionEnd::Reset)
3963 }
3964 error => Err(error),
3965 }
3966}
3967
3968async fn finish_writer(
3969 mut writer: tokio::task::JoinHandle<Result<(), WriterFailure>>,
3970 deadline: Instant,
3971) -> (Result<(), SubcModuleError>, usize) {
3972 match timeout_at(deadline, &mut writer).await {
3973 Ok(Ok(Ok(()))) => (Ok(()), 0),
3974 Ok(Ok(Err(failure))) => (
3975 Err(SubcModuleError::FrameIo(failure.error)),
3976 failure.undelivered_replies,
3977 ),
3978 Ok(Err(error)) => (Err(SubcModuleError::WriterTask(error)), 0),
3979 Err(_) => {
3980 writer.abort();
3981 let _ = writer.await;
3982 (Ok(()), 0)
3983 }
3984 }
3985}
3986
3987struct WriterFailure {
3988 error: FrameIoError,
3989 undelivered_replies: usize,
3990}
3991
3992async fn finish_writer_and_drain<R>(
3997 writer: tokio::task::JoinHandle<Result<(), WriterFailure>>,
3998 reader: &mut R,
3999 deadline: Instant,
4000) -> (Result<(), SubcModuleError>, usize)
4001where
4002 R: AsyncRead + Unpin,
4003{
4004 let flushed = finish_writer(writer, deadline).await;
4005 if flushed.0.is_ok() {
4006 drain_until_peer_closes(reader, deadline).await;
4007 }
4008 flushed
4009}
4010
4011async fn drain_until_peer_closes<R>(reader: &mut R, deadline: Instant)
4029where
4030 R: AsyncRead + Unpin,
4031{
4032 if Instant::now() >= deadline {
4033 return;
4034 }
4035 let mut discard = [0u8; 4096];
4036 let _ = timeout_at(deadline, async {
4037 while let Ok(read) = reader.read(&mut discard).await {
4038 if read == 0 {
4039 break;
4040 }
4041 }
4042 })
4043 .await;
4044}
4045
4046fn is_reply(frame: &Frame) -> bool {
4047 matches!(
4048 frame.header.ty,
4049 FrameType::Response | FrameType::Error | FrameType::StreamEnd
4050 )
4051}
4052
4053async fn drain_writer<W>(write_half: W, mut rx: mpsc::Receiver<Frame>) -> Result<(), WriterFailure>
4054where
4055 W: AsyncWrite + Unpin,
4056{
4057 let mut writer = BufWriter::new(write_half);
4058 let mut pending_replies = 0;
4059 let result = async {
4060 while let Some(frame) = rx.recv().await {
4061 pending_replies += usize::from(is_reply(&frame));
4062 write_frame(&mut writer, &frame).await?;
4063 while let Ok(frame) = rx.try_recv() {
4064 pending_replies += usize::from(is_reply(&frame));
4065 write_frame(&mut writer, &frame).await?;
4066 }
4067 writer.flush().await.map_err(FrameIoError::Io)?;
4068 pending_replies = 0;
4069 }
4070 writer.flush().await.map_err(FrameIoError::Io)?;
4071 let _ = writer.shutdown().await;
4080 Ok(())
4081 }
4082 .await;
4083 result.map_err(|error| {
4084 rx.close();
4085 while let Ok(frame) = rx.try_recv() {
4086 pending_replies += usize::from(is_reply(&frame));
4087 }
4088 WriterFailure {
4089 error,
4090 undelivered_replies: pending_replies,
4091 }
4092 })
4093}
4094
4095async fn send_outbound(egress: &mpsc::Sender<Frame>, frame: Frame) -> Result<(), SubcModuleError> {
4096 egress
4097 .send(frame)
4098 .await
4099 .map_err(|_| SubcModuleError::WriterClosed)
4100}
4101
4102fn parse_subc_arg(args: impl IntoIterator<Item = OsString>) -> Result<PathBuf, SubcModuleError> {
4103 let mut args = args.into_iter();
4104 while let Some(arg) = args.next() {
4105 if arg == "--subc" {
4106 let value = args.next().ok_or(SubcModuleError::MissingSubcValue)?;
4107 return Ok(PathBuf::from(value));
4108 }
4109 if let Some(raw) = arg.to_str().and_then(|arg| arg.strip_prefix("--subc=")) {
4110 if raw.is_empty() {
4111 return Err(SubcModuleError::MissingSubcValue);
4112 }
4113 return Ok(PathBuf::from(raw));
4114 }
4115 }
4116 Err(SubcModuleError::MissingSubcArg)
4117}
4118
4119fn module_id_from_env() -> Result<Option<String>, SubcModuleError> {
4120 match env::var(SUBC_MODULE_ID_ENV) {
4121 Ok(value) if !value.trim().is_empty() => Ok(Some(value)),
4122 Ok(_) => Err(SubcModuleError::EmptyModuleIdEnv),
4123 Err(env::VarError::NotPresent) => Ok(None),
4124 Err(env::VarError::NotUnicode(value)) => {
4125 Err(SubcModuleError::NonUnicodeModuleIdEnv { value })
4126 }
4127 }
4128}
4129
4130fn lock_in_flight(
4131 in_flight: &InFlight,
4132) -> Result<std::sync::MutexGuard<'_, HashMap<RequestKey, CancellationToken>>, SubcModuleError> {
4133 in_flight
4134 .lock()
4135 .map_err(|_| SubcModuleError::InFlightPoisoned)
4136}
4137
4138fn control_flags() -> Flags {
4139 Flags::new(false, Priority::Passive, false)
4140}
4141
4142fn data_flags() -> Flags {
4143 Flags::new(false, Priority::Interactive, false)
4144}
4145
4146#[derive(Debug)]
4147#[non_exhaustive]
4148pub enum SubcModuleError {
4149 InvalidControlOp(String),
4151 DuplicateControlCorrelation(u64),
4153 RegistrationChannel(io::Error),
4154 MissingSubcArg,
4155 MissingSubcValue,
4156 EmptyModuleIdEnv,
4157 NonUnicodeModuleIdEnv {
4158 value: OsString,
4159 },
4160 ConnectionFile {
4161 path: PathBuf,
4162 source: ConnectionFileError,
4163 },
4164 NoEndpoint {
4165 path: PathBuf,
4166 },
4167 Connect {
4168 path: PathBuf,
4169 endpoint: String,
4170 source: io::Error,
4171 },
4172 Auth {
4173 path: PathBuf,
4174 endpoint: String,
4175 source: AuthError,
4176 },
4177 FrameIo(FrameIoError),
4178 FrameBuild(FrameBuildError),
4179 Json(serde_json::Error),
4180 WriterClosed,
4181 HandlerPanic,
4183 StaleRouteHandle(RouteHandle),
4184 ConnectionTokenExhausted,
4185 WriterTask(tokio::task::JoinError),
4186 InFlightPoisoned,
4187 ConnectionClosedBeforeHelloAck,
4188 UnexpectedHelloAck {
4189 ty: FrameType,
4190 },
4191 HelloRejected {
4192 body: ErrorBody,
4193 },
4194 LaunchNonce(launch_nonce::LaunchNonceError),
4197}
4198
4199impl fmt::Display for SubcModuleError {
4200 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4201 match self {
4202 Self::InvalidControlOp(op) => {
4203 write!(f, "invalid or reserved control operation: {op:?}")
4204 }
4205 Self::DuplicateControlCorrelation(corr) => {
4206 write!(f, "duplicate in-flight control correlation: {corr}")
4207 }
4208 Self::RegistrationChannel(error) => write!(f, "registration channel: {error}"),
4209 Self::MissingSubcArg => write!(f, "missing required --subc <connection-file> argument"),
4210 Self::MissingSubcValue => write!(f, "--subc requires a connection-file path value"),
4211 Self::EmptyModuleIdEnv => write!(f, "{SUBC_MODULE_ID_ENV} must not be empty when set"),
4212 Self::NonUnicodeModuleIdEnv { value } => write!(
4213 f,
4214 "{SUBC_MODULE_ID_ENV} must be valid UTF-8, got '{}'",
4215 value.to_string_lossy()
4216 ),
4217 Self::ConnectionFile { path, source } => write!(
4218 f,
4219 "failed to read subc connection file '{}': {source}",
4220 path.display()
4221 ),
4222 Self::NoEndpoint { path } => write!(
4223 f,
4224 "subc connection file '{}' has no endpoints",
4225 path.display()
4226 ),
4227 Self::Connect {
4228 path,
4229 endpoint,
4230 source,
4231 } => write!(
4232 f,
4233 "failed to connect to subc endpoint {endpoint} from '{}': {source}",
4234 path.display()
4235 ),
4236 Self::Auth {
4237 path,
4238 endpoint,
4239 source,
4240 } => write!(
4241 f,
4242 "failed to authenticate to subc endpoint {endpoint} from '{}': {source}",
4243 path.display()
4244 ),
4245 Self::FrameIo(err) => fmt::Display::fmt(err, f),
4246 Self::FrameBuild(err) => write!(f, "frame build error: {err}"),
4247 Self::Json(err) => write!(f, "JSON error: {err}"),
4248 Self::WriterClosed => write!(f, "module writer task closed"),
4249 Self::HandlerPanic => write!(f, "module handler panicked"),
4250 Self::StaleRouteHandle(handle) => write!(f, "stale route handle: {handle:?}"),
4251 Self::ConnectionTokenExhausted => write!(f, "module connection token exhausted"),
4252 Self::WriterTask(err) => write!(f, "module writer task failed: {err}"),
4253 Self::InFlightPoisoned => write!(f, "in-flight registry lock poisoned"),
4254 Self::ConnectionClosedBeforeHelloAck => write!(f, "connection closed before HELLO_ACK"),
4255 Self::UnexpectedHelloAck { ty } => write!(f, "expected HELLO_ACK, got {ty:?}"),
4256 Self::HelloRejected { body } => write!(
4257 f,
4258 "HELLO rejected by subc: {} ({})",
4259 body.code, body.message
4260 ),
4261 Self::LaunchNonce(err) => write!(f, "launch nonce unavailable: {err}"),
4262 }
4263 }
4264}
4265
4266impl Error for SubcModuleError {
4267 fn source(&self) -> Option<&(dyn Error + 'static)> {
4268 match self {
4269 Self::RegistrationChannel(error) => Some(error),
4270 Self::ConnectionFile { source, .. } => Some(source),
4271 Self::Connect { source, .. } => Some(source),
4272 Self::Auth { source, .. } => Some(source),
4273 Self::FrameIo(err) => Some(err),
4274 Self::FrameBuild(err) => Some(err),
4275 Self::Json(err) => Some(err),
4276 Self::LaunchNonce(err) => Some(err),
4277 Self::WriterTask(err) => Some(err),
4278 Self::MissingSubcArg
4279 | Self::InvalidControlOp(_)
4280 | Self::DuplicateControlCorrelation(_)
4281 | Self::MissingSubcValue
4282 | Self::EmptyModuleIdEnv
4283 | Self::NonUnicodeModuleIdEnv { .. }
4284 | Self::NoEndpoint { .. }
4285 | Self::WriterClosed
4286 | Self::HandlerPanic
4287 | Self::StaleRouteHandle(_)
4288 | Self::ConnectionTokenExhausted
4289 | Self::InFlightPoisoned
4290 | Self::ConnectionClosedBeforeHelloAck
4291 | Self::UnexpectedHelloAck { .. }
4292 | Self::HelloRejected { .. } => None,
4293 }
4294 }
4295}
4296
4297impl From<serde_json::Error> for SubcModuleError {
4298 fn from(err: serde_json::Error) -> Self {
4299 Self::Json(err)
4300 }
4301}
4302
4303#[cfg(test)]
4304mod call_mode_tests;
4305
4306#[cfg(test)]
4307mod tests {
4308 use std::sync::atomic::{AtomicUsize, Ordering};
4309
4310 use serde_json::json;
4311
4312 use subc_protocol::manifest::{Concurrency, ExecutionMode, IdentityScope, Tool};
4313 use tokio::sync::Semaphore;
4314 use tokio::time::{advance, timeout};
4315
4316 use super::*;
4317
4318 struct EchoHandler;
4319
4320 #[async_trait]
4321 impl ModuleHandler for EchoHandler {
4322 async fn handle(&self, _ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome {
4323 HandlerOutcome::Response(body)
4324 }
4325 }
4326
4327 struct BlockingHandler {
4328 entered: Arc<AtomicUsize>,
4329 release: Semaphore,
4330 report: HealthReport,
4331 }
4332
4333 #[async_trait]
4334 impl ModuleHandler for BlockingHandler {
4335 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
4336 self.entered.fetch_add(1, Ordering::SeqCst);
4337 self.release.acquire().await.unwrap().forget();
4338 HandlerOutcome::Streamed
4339 }
4340
4341 async fn health(&self) -> HealthReport {
4342 self.report.clone()
4343 }
4344 }
4345
4346 fn health_request(corr: u64) -> Frame {
4347 Frame::build(
4348 FrameType::Request,
4349 control_flags(),
4350 0,
4351 0,
4352 corr,
4353 serde_json::to_vec(&ModuleControlRequest::HealthCheck {}).unwrap(),
4354 )
4355 .unwrap()
4356 }
4357
4358 fn data_request(channel: u16, corr: u64) -> Frame {
4359 Frame::build(
4360 FrameType::Request,
4361 data_flags(),
4362 channel,
4363 1,
4364 corr,
4365 b"opaque".to_vec(),
4366 )
4367 .unwrap()
4368 }
4369
4370 fn catalog_update_response(corr: u64) -> Frame {
4371 Frame::build(
4372 FrameType::Response,
4373 control_flags(),
4374 0,
4375 0,
4376 corr,
4377 serde_json::to_vec(&ModuleControlResponseToModule::CatalogUpdate {}).unwrap(),
4378 )
4379 .unwrap()
4380 }
4381
4382 fn test_module_handle(subc_ops: &[&str]) -> (ModuleHandle, mpsc::Receiver<Frame>) {
4383 let (tx, rx) = mpsc::channel(4);
4384 let ack = ModuleHelloAckBody {
4385 negotiated_ver: PROTOCOL_VERSION,
4386 subc_ops: subc_ops.iter().map(|op| (*op).to_string()).collect(),
4387 subc_capabilities: Vec::new(),
4388 storage: None,
4389 machine_id: None,
4390 };
4391 (
4392 ModuleHandle::new(
4393 &ack,
4394 tx,
4395 1,
4396 CancellationToken::new(),
4397 tokio::runtime::Handle::current(),
4398 ),
4399 rx,
4400 )
4401 }
4402
4403 #[test]
4404 fn module_handle_exposes_the_acked_machine_id_and_none_otherwise() {
4405 let runtime = tokio::runtime::Runtime::new().unwrap();
4406 let handle_for = |machine_id: Option<&str>| {
4407 let (tx, _rx) = mpsc::channel(1);
4408 let ack = ModuleHelloAckBody {
4409 negotiated_ver: PROTOCOL_VERSION,
4410 subc_ops: Vec::new(),
4411 subc_capabilities: Vec::new(),
4412 storage: None,
4413 machine_id: machine_id.map(str::to_owned),
4414 };
4415 ModuleHandle::new(
4416 &ack,
4417 tx,
4418 1,
4419 CancellationToken::new(),
4420 runtime.handle().clone(),
4421 )
4422 };
4423 assert_eq!(
4424 handle_for(Some("0123456789abcdef0123456789abcdef"))
4425 .machine_id()
4426 .map(MachineId::as_str),
4427 Some("0123456789abcdef0123456789abcdef")
4428 );
4429 assert_eq!(handle_for(None).machine_id(), None);
4431 assert_eq!(handle_for(Some("not-a-machine-id")).machine_id(), None);
4432 }
4433
4434 fn test_provider_role(tool_names: &[&str]) -> ProviderRole {
4435 ProviderRole::ToolProvider {
4436 tools: tool_names
4437 .iter()
4438 .map(|name| Tool {
4439 name: (*name).to_string(),
4440 description: None,
4441 execution_mode: ExecutionMode::Pure,
4442 schema: json!({"type": "object"}),
4443 })
4444 .collect(),
4445 identity_scope: vec![IdentityScope::Project],
4446 concurrency: Concurrency::ModuleManaged,
4447 emits_push: false,
4448 sub_supervises: false,
4449 }
4450 }
4451
4452 #[tokio::test]
4453 async fn catalog_update_fails_fast_when_hello_ack_does_not_advertise_support() {
4454 let (handle, mut rx) = test_module_handle(&[]);
4455
4456 let error = handle
4457 .catalog_update(vec![test_provider_role(&["a"])])
4458 .await
4459 .unwrap_err();
4460 assert!(matches!(error, CatalogUpdateError::NotSupported));
4461 assert!(matches!(
4462 handle.set_ready(true).await,
4463 Err(CatalogUpdateError::NotSupported)
4464 ));
4465 assert!(timeout(Duration::from_millis(75), rx.recv()).await.is_err());
4466 }
4467
4468 #[tokio::test]
4469 async fn catalog_update_demuxes_multiple_in_flight_requests() {
4470 let (handle, mut rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
4471 let first_handle = handle.clone();
4472 let second_handle = handle.clone();
4473 let first = tokio::spawn(async move {
4474 first_handle
4475 .catalog_update(vec![test_provider_role(&["a"])])
4476 .await
4477 });
4478 let second = tokio::spawn(async move {
4479 second_handle
4480 .catalog_update(vec![test_provider_role(&["b"])])
4481 .await
4482 });
4483
4484 let first_frame = timeout(Duration::from_secs(1), rx.recv())
4485 .await
4486 .unwrap()
4487 .unwrap();
4488 let second_frame = timeout(Duration::from_secs(1), rx.recv())
4489 .await
4490 .unwrap()
4491 .unwrap();
4492 assert_eq!(first_frame.header.ty, FrameType::Request);
4493 assert_eq!(first_frame.header.channel, 0);
4494 assert_eq!(second_frame.header.ty, FrameType::Request);
4495 assert_eq!(second_frame.header.channel, 0);
4496 assert_ne!(first_frame.header.corr, second_frame.header.corr);
4497
4498 let (earlier, later) =
4499 if json_body(&first_frame.body)["provides"] == json!([test_provider_role(&["a"])]) {
4500 (first, second)
4501 } else {
4502 (second, first)
4503 };
4504 assert!(handle.handle_control_reply(catalog_update_response(second_frame.header.corr)));
4505 assert!(later.await.unwrap().is_ok());
4506 assert!(handle.handle_control_reply(catalog_update_response(first_frame.header.corr)));
4507 assert!(earlier.await.unwrap().is_ok());
4508
4509 let expected = json_body(&second_frame.body)["provides"].clone();
4510 let (result, ()) = tokio::join!(handle.set_ready(true), async {
4511 let frame = rx.recv().await.unwrap();
4512 assert_eq!(json_body(&frame.body)["provides"], expected);
4513 assert_eq!(json_body(&frame.body)["ready"], true);
4514 handle.handle_control_reply(catalog_update_response(frame.header.corr));
4515 });
4516 result.unwrap();
4517 }
4518
4519 fn json_body(body: &[u8]) -> serde_json::Value {
4520 serde_json::from_slice(body).unwrap()
4521 }
4522
4523 #[tokio::test]
4524 async fn role_declarations_update_requires_its_own_advertised_op() {
4525 for ops in [vec![], vec![MODULE_TO_SUBC_OP_CATALOG_UPDATE]] {
4526 let (handle, mut rx) = test_module_handle(&ops);
4527 assert!(matches!(
4528 handle.update_role_declarations(BTreeMap::new()).await,
4529 Err(CatalogUpdateError::NotSupported)
4530 ));
4531 assert!(matches!(
4532 rx.try_recv(),
4533 Err(mpsc::error::TryRecvError::Empty)
4534 ));
4535 }
4536 }
4537
4538 #[tokio::test]
4539 async fn role_declarations_update_sends_map_and_preserves_refusal() {
4540 let (handle, mut rx) =
4541 test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE_ROLE_DECLARATIONS]);
4542 let initial_roles = vec![test_provider_role(&["original"])];
4543 handle.shared.lock_inner().current_provides = Some(initial_roles.clone());
4544 for declarations in [
4545 json!({"media-provider/v1": {"engines": ["image"]}}),
4546 json!({}),
4547 ] {
4548 let map = serde_json::from_value(declarations.clone()).unwrap();
4549 let (result, ()) = tokio::join!(handle.update_role_declarations(map), async {
4550 let frame = rx.recv().await.unwrap();
4551 assert_eq!(frame.header.ty, FrameType::Request);
4552 assert_eq!(frame.header.channel, 0);
4553 assert_eq!(
4554 json_body(&frame.body),
4555 json!({"op": "catalog.update_role_declarations", "role_declarations": declarations})
4556 );
4557 handle.handle_control_reply(control_reply(
4558 FrameType::Response,
4559 frame.header.corr,
4560 serde_json::to_vec(&json!({"op": "catalog.update_role_declarations"})).unwrap(),
4561 ));
4562 });
4563 result.unwrap();
4564 }
4565 let (result, ()) = tokio::join!(handle.update_role_declarations(BTreeMap::new()), async {
4566 let frame = rx.recv().await.unwrap();
4567 handle.handle_control_reply(control_reply(FrameType::Error, frame.header.corr,
4568 serde_json::to_vec(&json!({"code": "invalid_role_declarations", "message": "role_declarations key must use capability-name grammar"})).unwrap()));
4569 });
4570 let Err(CatalogUpdateError::Rejected(body)) = result else {
4571 panic!("expected typed refusal")
4572 };
4573 assert_eq!(body.code, "invalid_role_declarations");
4574 assert_eq!(
4575 body.message,
4576 "role_declarations key must use capability-name grammar"
4577 );
4578 assert_eq!(
4579 handle.shared.lock_inner().current_provides,
4580 Some(initial_roles)
4581 );
4582 }
4583
4584 async fn ack_catalog_update(
4585 handle: &ModuleHandle,
4586 rx: &mut mpsc::Receiver<Frame>,
4587 provides: &[ProviderRole],
4588 ready: Option<bool>,
4589 capabilities: Option<&CapabilityDeclarations>,
4590 ) {
4591 let frame = rx.recv().await.unwrap();
4592 let mut expected = json!({"op": "catalog.update", "provides": provides});
4593 if let Some(ready) = ready {
4594 expected["ready"] = json!(ready);
4595 }
4596 if let Some(capabilities) = capabilities {
4597 expected["capabilities"] = json!(capabilities);
4598 }
4599 assert_eq!(json_body(&frame.body), expected);
4600 let mut wire = format!(
4601 r#"{{"op":"catalog.update","provides":{}"#,
4602 serde_json::to_string(provides).unwrap()
4603 );
4604 if let Some(capabilities) = capabilities {
4605 wire.push_str(&format!(
4606 r#","capabilities":{}"#,
4607 serde_json::to_string(capabilities).unwrap()
4608 ));
4609 }
4610 if let Some(ready) = ready {
4611 wire.push_str(&format!(r#","ready":{ready}"#));
4612 }
4613 wire.push('}');
4614 assert_eq!(frame.body, wire.as_bytes());
4615 assert!(handle.handle_control_reply(catalog_update_response(frame.header.corr)));
4616 }
4617
4618 #[tokio::test]
4619 async fn catalog_update_set_ready_preserves_registered_and_replaced_roles() {
4620 let (handle, mut rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
4621 let initial = vec![test_provider_role(&["initial", "second"])];
4622 handle.shared.lock_inner().current_provides = Some(initial.clone());
4623 let (result, ()) = tokio::join!(
4624 handle.set_ready(true),
4625 ack_catalog_update(&handle, &mut rx, &initial, Some(true), None)
4626 );
4627 result.unwrap();
4628
4629 let replaced = vec![test_provider_role(&["replacement"])];
4630 let (result, ()) = tokio::join!(
4631 handle.catalog_update(replaced.clone()),
4632 ack_catalog_update(&handle, &mut rx, &replaced, None, None)
4633 );
4634 result.unwrap();
4635 let (result, ()) = tokio::join!(
4636 handle.set_ready(false),
4637 ack_catalog_update(&handle, &mut rx, &replaced, Some(false), None)
4638 );
4639 result.unwrap();
4640
4641 let attested = vec![test_provider_role(&["attested"])];
4642 let capabilities = CapabilityDeclarations {
4643 provides: vec!["test.capability".into()],
4644 requires: Vec::new(),
4645 must_never_reach: Vec::new(),
4646 };
4647 let (result, ()) = tokio::join!(
4648 handle.catalog_update_with_capabilities(attested.clone(), capabilities.clone()),
4649 ack_catalog_update(&handle, &mut rx, &attested, None, Some(&capabilities))
4650 );
4651 result.unwrap();
4652 let (result, ()) = tokio::join!(
4653 handle.set_ready(true),
4654 ack_catalog_update(&handle, &mut rx, &attested, Some(true), None)
4655 );
4656 result.unwrap();
4657 }
4658
4659 #[tokio::test]
4660 async fn catalog_update_set_ready_refuses_unknown_or_in_flight_roles() {
4661 let (handle, mut rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
4662 assert!(matches!(
4663 handle.set_ready(true).await,
4664 Err(CatalogUpdateError::Protocol(_))
4665 ));
4666 assert!(rx.try_recv().is_err());
4667
4668 let updating = handle.clone();
4669 let update = tokio::spawn(async move {
4670 updating
4671 .catalog_update(vec![test_provider_role(&["new"])])
4672 .await
4673 });
4674 let frame = rx.recv().await.unwrap();
4675 assert!(matches!(
4676 handle.set_ready(true).await,
4677 Err(CatalogUpdateError::Protocol(_))
4678 ));
4679 assert!(rx.try_recv().is_err());
4680 update.abort();
4681 assert!(update.await.unwrap_err().is_cancelled());
4682 assert!(!handle.handle_control_reply(catalog_update_response(frame.header.corr)));
4683 assert!(matches!(
4684 handle.set_ready(true).await,
4685 Err(CatalogUpdateError::Protocol(_))
4686 ));
4687
4688 let roles = vec![test_provider_role(&["recovered"])];
4689 let (result, ()) = tokio::join!(
4690 handle.catalog_update(roles.clone()),
4691 ack_catalog_update(&handle, &mut rx, &roles, None, None)
4692 );
4693 result.unwrap();
4694 let (result, ()) = tokio::join!(
4695 handle.set_ready(true),
4696 ack_catalog_update(&handle, &mut rx, &roles, Some(true), None)
4697 );
4698 result.unwrap();
4699 }
4700
4701 #[tokio::test(start_paused = true)]
4702 async fn catalog_update_set_ready_timeout_does_not_replay_stale_roles() {
4703 let (handle, mut rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
4704 handle.shared.lock_inner().current_provides = Some(vec![test_provider_role(&["old"])]);
4705 assert!(matches!(
4706 handle
4707 .catalog_update(vec![test_provider_role(&["new"])])
4708 .await,
4709 Err(CatalogUpdateError::Timeout)
4710 ));
4711 let frame = rx.recv().await.unwrap();
4712 assert!(!handle.handle_control_reply(catalog_update_response(frame.header.corr)));
4713 assert!(matches!(
4714 handle.set_ready(true).await,
4715 Err(CatalogUpdateError::Protocol(_))
4716 ));
4717 assert!(rx.try_recv().is_err());
4718 }
4719
4720 #[tokio::test]
4721 async fn catalog_update_set_ready_rejection_retains_last_accepted_roles() {
4722 let (handle, mut rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
4723 let initial = vec![test_provider_role(&["kept"])];
4724 handle.shared.lock_inner().current_provides = Some(initial.clone());
4725 let (result, ()) = tokio::join!(
4726 handle.catalog_update(vec![test_provider_role(&["rejected"])]),
4727 async {
4728 let frame = rx.recv().await.unwrap();
4729 handle.handle_control_reply(control_reply(
4730 FrameType::Error,
4731 frame.header.corr,
4732 br#"{"code":"catalog_update_frozen_field","message":"frozen"}"#.to_vec(),
4733 ));
4734 }
4735 );
4736 assert!(matches!(result, Err(CatalogUpdateError::FrozenField(_))));
4737 let (result, ()) = tokio::join!(
4738 handle.set_ready(true),
4739 ack_catalog_update(&handle, &mut rx, &initial, Some(true), None)
4740 );
4741 result.unwrap();
4742 }
4743
4744 fn control_reply(ty: FrameType, corr: u64, body: Vec<u8>) -> Frame {
4745 Frame::build(ty, control_flags(), 0, 0, corr, body).unwrap()
4746 }
4747
4748 async fn authorize_for_test(
4749 handle: &ModuleHandle,
4750 ) -> Result<RouteAuthorizeResponse, ScopeCallError> {
4751 handle
4752 .route_authorize(
4753 Principal::Direct,
4754 RouteAuthorizeScope::new(
4755 Principal::Reserved {
4756 module_id: "owner".into(),
4757 },
4758 "stored-scope",
4759 7,
4760 ),
4761 "target".into(),
4762 RouteAuthorizeExpected::new(
4763 subc_protocol::scope::ScopeKind::Head,
4764 &subc_protocol::scope::ScopeAttributes::default(),
4765 ),
4766 )
4767 .await
4768 }
4769
4770 #[tokio::test]
4771 async fn route_authorize_requires_advertised_operation() {
4772 let (tx, mut rx) = mpsc::channel(4);
4773 let ack = ModuleHelloAckBody {
4774 negotiated_ver: PROTOCOL_VERSION,
4775 subc_ops: vec![],
4776 subc_capabilities: vec![subc_protocol::scope::ROUTE_AUTHORIZE_CAPABILITY.into()],
4778 storage: None,
4779 machine_id: None,
4780 };
4781 let handle = ModuleHandle::new(
4782 &ack,
4783 tx,
4784 1,
4785 CancellationToken::new(),
4786 tokio::runtime::Handle::current(),
4787 );
4788 let result = timeout(Duration::from_millis(100), authorize_for_test(&handle))
4789 .await
4790 .expect("an unsupported operation must return without sending or awaiting a reply");
4791 assert_eq!(
4792 result,
4793 Err(ScopeCallError::NotSupported {
4794 op: subc_protocol::scope::ROUTE_AUTHORIZE_OP,
4795 })
4796 );
4797 assert!(
4798 rx.try_recv().is_err(),
4799 "unsupported calls must send nothing"
4800 );
4801 }
4802
4803 #[tokio::test]
4804 async fn route_authorize_decodes_every_answer_and_permission_refusal() {
4805 use RouteAuthorizeOutcome::*;
4806 let (handle, mut rx) = test_module_handle(&[subc_protocol::scope::ROUTE_AUTHORIZE_OP]);
4807 for (wire, outcome, code) in [
4808 ("authorized", Authorized, None),
4809 ("scope_ended", ScopeEnded, Some("scope_not_live")),
4810 ("indeterminate", Indeterminate, Some("scope_not_synced")),
4811 ("epoch_changed", EpochChanged, Some("scope_ended")),
4812 ("claim_changed", ClaimChanged, None),
4813 (
4814 "proof_required",
4815 ProofRequired,
4816 Some("scope_bind_proof_required"),
4817 ),
4818 ("not_authorized", NotAuthorized, Some("scope_not_carrier")),
4819 ("target_absent", TargetAbsent, None),
4820 ] {
4821 let caller = handle.clone();
4822 let pending = tokio::spawn(async move { authorize_for_test(&caller).await });
4823 let request = rx.recv().await.unwrap();
4824 assert_eq!(request.header.ty, FrameType::Request);
4825 assert_eq!(request.header.channel, 0);
4826 assert_eq!(request.header.ver, PROTOCOL_VERSION);
4827 assert_eq!(
4828 serde_json::from_slice::<serde_json::Value>(&request.body).unwrap(),
4829 serde_json::json!({
4830 "op": "route.authorize", "principal": {"kind": "direct"},
4831 "scope": {"owner": {"kind": "reserved", "module_id": "owner"},
4832 "ref": "stored-scope", "epoch": 7},
4833 "target": "target", "expected": {"kind": "head"}
4834 })
4835 );
4836 let content_version = (outcome == Authorized).then_some("sha256:content");
4837 let mut body = serde_json::json!({
4838 "op": "route.authorize", "outcome": wire, "message": "judgment"
4839 });
4840 if let Some(code) = code {
4841 body["route_open_code"] = code.into();
4842 }
4843 if let Some(version) = content_version {
4844 body["content_version"] = version.into();
4845 }
4846 assert!(handle.handle_control_reply(control_reply(
4847 FrameType::Response,
4848 request.header.corr,
4849 serde_json::to_vec(&body).unwrap(),
4850 )));
4851 let reply = pending.await.unwrap().unwrap();
4852 assert_eq!(reply.outcome, outcome);
4853 assert_eq!(reply.message, "judgment");
4854 assert_eq!(reply.route_open_code.as_deref(), code);
4855 assert_eq!(reply.content_version.as_deref(), content_version);
4856 }
4857
4858 for (code, message) in [
4859 ("route_authorize_not_permitted", "not the configured owner"),
4860 ("not_registered", "connection is not registered"),
4861 ("unexpected", "a future daemon call refusal"),
4862 ] {
4863 let caller = handle.clone();
4864 let pending = tokio::spawn(async move { authorize_for_test(&caller).await });
4865 let request = rx.recv().await.unwrap();
4866 assert!(handle.handle_control_reply(control_reply(
4867 FrameType::Error,
4868 request.header.corr,
4869 serde_json::to_vec(&serde_json::json!({"code": code, "message": message})).unwrap(),
4870 )));
4871 assert_eq!(
4872 pending.await.unwrap(),
4873 Err(ScopeCallError::Refused {
4874 code: code.into(),
4875 message: message.into(),
4876 })
4877 );
4878 }
4879 }
4880
4881 #[tokio::test]
4882 async fn route_authorize_rejects_malformed_and_unexpected_replies() {
4883 let (handle, mut rx) = test_module_handle(&[subc_protocol::scope::ROUTE_AUTHORIZE_OP]);
4884 for (ty, body) in [
4885 (FrameType::Response, r#"{"op":"catalog.update"}"#),
4886 (
4887 FrameType::Response,
4888 r#"{"op":"route.authorize","outcome":"authorized"}"#,
4889 ),
4890 (
4891 FrameType::Response,
4892 r#"{"op":"route.authorize","outcome":"future","message":"new"}"#,
4893 ),
4894 (FrameType::Error, "not json"),
4895 (FrameType::Request, "{}"),
4896 ] {
4897 let caller = handle.clone();
4898 let pending = tokio::spawn(async move { authorize_for_test(&caller).await });
4899 let request = rx.recv().await.unwrap();
4900 assert!(handle.handle_control_reply(control_reply(
4901 ty,
4902 request.header.corr,
4903 body.as_bytes().to_vec(),
4904 )));
4905 assert!(
4906 matches!(pending.await.unwrap(), Err(ScopeCallError::Protocol(_))),
4907 "{body}"
4908 );
4909 }
4910 }
4911
4912 #[tokio::test]
4913 async fn scope_served_by_requires_capability_and_decodes_open_replies() {
4914 let (unsupported, mut rx) = test_module_handle(&[subc_control::SCOPE_SERVED_BY_OP]);
4915 assert_eq!(
4916 unsupported
4917 .scope_served_by("s".into(), 1, "tool".into())
4918 .await,
4919 Err(ScopeCallError::NotSupported {
4920 op: subc_control::SCOPE_SERVED_BY_OP
4921 })
4922 );
4923 assert!(rx.try_recv().is_err());
4924 let (tx, mut rx) = mpsc::channel(4);
4925 let ack = ModuleHelloAckBody {
4926 negotiated_ver: PROTOCOL_VERSION,
4927 subc_ops: vec![],
4928 subc_capabilities: vec![subc_protocol::scope::SCOPE_SERVED_BY_CAPABILITY.into()],
4929 storage: None,
4930 machine_id: None,
4931 };
4932 let handle = ModuleHandle::new(
4933 &ack,
4934 tx,
4935 1,
4936 CancellationToken::new(),
4937 tokio::runtime::Handle::current(),
4938 );
4939 for answer in ["served", "not_served", "unknown", "future"] {
4940 let caller = handle.clone();
4941 let pending =
4942 tokio::spawn(
4943 async move { caller.scope_served_by("s".into(), 7, "tool".into()).await },
4944 );
4945 let request = rx.recv().await.unwrap();
4946 let decoded: subc_control::ScopeServedByRequest =
4947 serde_json::from_slice(&request.body).unwrap();
4948 assert_eq!(
4949 (
4950 decoded.scope_ref.as_str(),
4951 decoded.scope_epoch,
4952 decoded.module_id.as_str()
4953 ),
4954 ("s", 7, "tool")
4955 );
4956 assert!(handle.handle_control_reply(control_reply(FrameType::Response, request.header.corr,
4957 serde_json::to_vec(&serde_json::json!({"op":"scope.served_by", "answer":answer, "daemon_incarnation":"d"})).unwrap())));
4958 let reply = pending.await.unwrap().unwrap();
4959 assert_eq!(reply.daemon_incarnation, "d");
4960 assert_eq!(serde_json::to_value(reply.answer).unwrap(), answer);
4961 }
4962 let caller = handle.clone();
4963 let pending =
4964 tokio::spawn(async move { caller.scope_served_by("s".into(), 7, "tool".into()).await });
4965 let request = rx.recv().await.unwrap();
4966 assert!(handle.handle_control_reply(control_reply(
4967 FrameType::Error,
4968 request.header.corr,
4969 serde_json::to_vec(&serde_json::json!({"code":"not_registered", "message":"gone"}))
4970 .unwrap()
4971 )));
4972 assert_eq!(
4973 pending.await.unwrap().unwrap_err().code(),
4974 Some("not_registered")
4975 );
4976 }
4977
4978 fn owner() -> Principal {
4979 Principal::Reserved {
4980 module_id: "owner".to_string(),
4981 }
4982 }
4983
4984 mod scope_watch {
4985 use super::*;
4986 include!("module_subscription_tests.rs");
4987 }
4988
4989 #[tokio::test]
4993 async fn scope_ops_fail_fast_when_hello_ack_does_not_advertise_them() {
4994 let (handle, mut rx) = test_module_handle(&[]);
4995 assert_eq!(
4996 handle.scope_sync(1, Vec::new()).await.unwrap_err(),
4997 ScopeCallError::NotSupported { op: SCOPE_SYNC_OP }
4998 );
4999 assert_eq!(
5000 handle
5001 .scope_describe(owner(), "s".to_string())
5002 .await
5003 .unwrap_err(),
5004 ScopeCallError::NotSupported {
5005 op: SCOPE_DESCRIBE_OP
5006 }
5007 );
5008 assert!(timeout(Duration::from_millis(75), rx.recv()).await.is_err());
5009
5010 let (describe_only, mut rx) = test_module_handle(&[SCOPE_DESCRIBE_OP]);
5011 assert_eq!(
5012 describe_only.scope_sync(1, Vec::new()).await.unwrap_err(),
5013 ScopeCallError::NotSupported { op: SCOPE_SYNC_OP }
5014 );
5015 assert!(timeout(Duration::from_millis(75), rx.recv()).await.is_err());
5016
5017 let (sync_only, mut rx) = test_module_handle(&[SCOPE_SYNC_OP]);
5018 assert_eq!(
5019 sync_only
5020 .scope_describe(owner(), "s".to_string())
5021 .await
5022 .unwrap_err(),
5023 ScopeCallError::NotSupported {
5024 op: SCOPE_DESCRIBE_OP
5025 }
5026 );
5027 assert!(timeout(Duration::from_millis(75), rx.recv()).await.is_err());
5028 }
5029
5030 #[tokio::test]
5031 async fn scope_apply_sends_nothing_without_its_own_advertised_op() {
5032 for ops in [&[][..], &[SCOPE_SYNC_OP, SCOPE_DESCRIBE_OP][..]] {
5033 let (handle, mut rx) = test_module_handle(ops);
5034 assert_eq!(
5035 handle.scope_apply(2, Vec::new(), Vec::new()).await,
5036 Err(ScopeCallError::NotSupported { op: SCOPE_APPLY_OP })
5037 );
5038 assert!(timeout(Duration::from_millis(75), rx.recv()).await.is_err());
5039 }
5040 }
5041
5042 #[tokio::test]
5043 async fn scope_apply_sends_the_delta_and_preserves_per_entry_outcomes() {
5044 let (handle, mut rx) = test_module_handle(&[SCOPE_APPLY_OP]);
5045 let apply = tokio::spawn({
5046 let handle = handle.clone();
5047 async move {
5048 handle
5049 .scope_apply(
5050 2,
5051 vec![ScopeRecord::new(
5052 "run",
5053 1,
5054 subc_protocol::scope::ScopeKind::Ephemeral,
5055 )
5056 .with_expires_at_ms(Some(12345))
5057 .with_workdir(Some("/session/folder".into()))
5058 .with_project_id(Some("project:1".into()))],
5059 vec![ScopeEnd::new("old", 3), ScopeEnd::new("missing", 1)],
5060 )
5061 .await
5062 }
5063 });
5064 let request = timeout(Duration::from_secs(1), rx.recv())
5065 .await
5066 .unwrap()
5067 .unwrap();
5068 assert_eq!(request.header.ty, FrameType::Request);
5069 assert_eq!(request.header.channel, 0);
5070 assert_eq!(
5071 serde_json::from_slice::<serde_json::Value>(&request.body).unwrap(),
5072 serde_json::json!({
5073 "op": "scope.apply", "generation": 2,
5074 "upsert": [{"ref": "run", "scope_epoch": 1, "kind": "ephemeral", "expires_at_ms": 12345,
5075 "workdir": "/session/folder", "project_id": "project:1"}],
5076 "end": [{"ref": "old", "scope_epoch": 3}, {"ref": "missing", "scope_epoch": 1}]
5077 })
5078 );
5079 let body = serde_json::to_vec(&serde_json::json!({
5080 "op": "scope.apply", "generation": 2,
5081 "results": [{"ref": "run", "scope_epoch": 1, "outcome": "refused", "code": "scope_expired"}],
5082 "end_results": [
5083 {"ref": "old", "scope_epoch": 3, "outcome": "ended"},
5084 {"ref": "missing", "scope_epoch": 1, "outcome": "not_live"}
5085 ],
5086 "ended": [{"ref": "old", "scope_epoch": 3}]
5087 }))
5088 .unwrap();
5089 assert!(handle.handle_control_reply(control_reply(
5090 FrameType::Response,
5091 request.header.corr,
5092 body
5093 )));
5094 let reply = apply.await.unwrap().unwrap();
5095 assert_eq!(reply.generation, 2);
5096 assert_eq!(reply.results.len(), 1);
5097 assert_eq!(reply.results[0].scope_ref, "run");
5098 assert_eq!(
5099 reply.results[0].outcome,
5100 subc_protocol::scope::ScopeRecordOutcome::Refused
5101 );
5102 assert_eq!(reply.results[0].code.as_deref(), Some("scope_expired"));
5103 assert_eq!(reply.end_results.len(), 2);
5104 assert_eq!(reply.end_results[0].scope_ref, "old");
5105 assert_eq!(reply.end_results[0].scope_epoch, 3);
5106 assert_eq!(
5107 reply.end_results[0].outcome,
5108 subc_protocol::scope::ScopeEndOutcome::Ended
5109 );
5110 assert_eq!(reply.end_results[1].scope_ref, "missing");
5111 assert_eq!(
5112 reply.end_results[1].outcome,
5113 subc_protocol::scope::ScopeEndOutcome::NotLive
5114 );
5115 assert_eq!(reply.ended.len(), 1);
5116 assert_eq!(reply.ended[0].scope_ref, "old");
5117 assert_eq!(reply.ended[0].scope_epoch, 3);
5118 }
5119
5120 #[tokio::test]
5121 async fn scope_apply_rejects_a_reply_for_another_op() {
5122 let (handle, mut rx) = test_module_handle(&[SCOPE_APPLY_OP]);
5123 let apply = tokio::spawn({
5124 let handle = handle.clone();
5125 async move { handle.scope_apply(2, Vec::new(), Vec::new()).await }
5126 });
5127 let request = timeout(Duration::from_secs(1), rx.recv())
5128 .await
5129 .unwrap()
5130 .unwrap();
5131 let body = serde_json::to_vec(&ModuleControlResponseToModule::ScopeSync {
5132 generation: 2,
5133 results: Vec::new(),
5134 ended: Vec::new(),
5135 })
5136 .unwrap();
5137 assert!(handle.handle_control_reply(control_reply(
5138 FrameType::Response,
5139 request.header.corr,
5140 body
5141 )));
5142 assert!(matches!(
5143 apply.await.unwrap(),
5144 Err(ScopeCallError::Protocol(_))
5145 ));
5146 }
5147
5148 #[tokio::test]
5149 async fn scope_apply_preserves_whole_call_refusal_codes() {
5150 let (handle, mut rx) = test_module_handle(&[SCOPE_APPLY_OP]);
5151 for code in [
5152 subc_protocol::error_codes::SCOPE_SYNC_REQUIRED,
5153 subc_protocol::error_codes::SCOPE_SYNC_STALE,
5154 subc_protocol::error_codes::SCOPE_SYNC_NOT_AUTHORITY,
5155 "not_registered",
5156 ] {
5157 let apply = tokio::spawn({
5158 let handle = handle.clone();
5159 async move { handle.scope_apply(2, Vec::new(), Vec::new()).await }
5160 });
5161 let request = timeout(Duration::from_secs(1), rx.recv())
5162 .await
5163 .unwrap()
5164 .unwrap();
5165 let body = serde_json::to_vec(&ErrorBody::new(code, "why")).unwrap();
5166 assert!(handle.handle_control_reply(control_reply(
5167 FrameType::Error,
5168 request.header.corr,
5169 body
5170 )));
5171 let error = apply.await.unwrap().unwrap_err();
5172 assert_eq!(
5173 error,
5174 ScopeCallError::Refused {
5175 code: code.to_string(),
5176 message: "why".to_string()
5177 }
5178 );
5179 assert_eq!(error.code(), Some(code));
5180 }
5181 }
5182
5183 #[tokio::test]
5185 async fn a_scope_reply_of_another_op_is_a_protocol_error() {
5186 let (handle, mut rx) = test_module_handle(&[SCOPE_SYNC_OP, SCOPE_DESCRIBE_OP]);
5187 let sync = tokio::spawn({
5188 let handle = handle.clone();
5189 async move { handle.scope_sync(1, Vec::new()).await }
5190 });
5191 let request = timeout(Duration::from_secs(1), rx.recv())
5192 .await
5193 .unwrap()
5194 .unwrap();
5195 let describe_body = serde_json::to_vec(&ModuleControlResponseToModule::ScopeDescribe {
5196 status: ScopeStatus::NotLive,
5197 scope_epoch: None,
5198 daemon_incarnation: "i".to_string(),
5199 owner_synced: false,
5200 owner_configured: false,
5201 scope: None,
5202 })
5203 .unwrap();
5204 assert!(handle.handle_control_reply(control_reply(
5205 FrameType::Response,
5206 request.header.corr,
5207 describe_body
5208 )));
5209 assert!(matches!(
5210 sync.await.unwrap(),
5211 Err(ScopeCallError::Protocol(_))
5212 ));
5213
5214 let describe = tokio::spawn({
5215 let handle = handle.clone();
5216 async move { handle.scope_describe(owner(), "s".to_string()).await }
5217 });
5218 let request = timeout(Duration::from_secs(1), rx.recv())
5219 .await
5220 .unwrap()
5221 .unwrap();
5222 let sync_body = serde_json::to_vec(&ModuleControlResponseToModule::ScopeSync {
5223 generation: 1,
5224 results: Vec::new(),
5225 ended: Vec::new(),
5226 })
5227 .unwrap();
5228 assert!(handle.handle_control_reply(control_reply(
5229 FrameType::Response,
5230 request.header.corr,
5231 sync_body
5232 )));
5233 assert!(matches!(
5234 describe.await.unwrap(),
5235 Err(ScopeCallError::Protocol(_))
5236 ));
5237 }
5238
5239 #[tokio::test]
5243 async fn a_scope_error_frame_keeps_the_daemons_code_and_message() {
5244 let (handle, mut rx) = test_module_handle(&[SCOPE_SYNC_OP]);
5245 for code in [
5246 subc_protocol::error_codes::SCOPE_SYNC_STALE,
5247 subc_protocol::error_codes::SCOPE_SYNC_NOT_AUTHORITY,
5248 "not_registered",
5249 ] {
5250 let sync = tokio::spawn({
5251 let handle = handle.clone();
5252 async move { handle.scope_sync(1, Vec::new()).await }
5253 });
5254 let request = timeout(Duration::from_secs(1), rx.recv())
5255 .await
5256 .unwrap()
5257 .unwrap();
5258 let body = serde_json::to_vec(&ErrorBody::new(code, "why")).unwrap();
5259 assert!(handle.handle_control_reply(control_reply(
5260 FrameType::Error,
5261 request.header.corr,
5262 body
5263 )));
5264 let error = sync.await.unwrap().unwrap_err();
5265 assert_eq!(
5266 error,
5267 ScopeCallError::Refused {
5268 code: code.to_string(),
5269 message: "why".to_string()
5270 }
5271 );
5272 assert_eq!(error.code(), Some(code));
5273 }
5274 }
5275
5276 #[tokio::test]
5280 async fn an_undecodable_control_request_is_refused_and_the_module_keeps_serving() {
5281 let (tx, mut rx) = mpsc::channel(4);
5282 let handler = Arc::new(EchoHandler);
5283 let dispatcher = RequestDispatcher::new();
5284 let (module_handle, _unused_rx) = test_module_handle(&[]);
5285 let mut body: serde_json::Value =
5288 serde_json::from_slice(&route_bind_frame(9, 1, 41).body).unwrap();
5289 body["scope"] = serde_json::json!({
5290 "owner": { "kind": "reserved", "module_id": "prefrontal-core" },
5291 "ref": "s",
5292 "scope_epoch": 1,
5293 "kind": "head",
5294 "attributes": { "a_field_from_a_newer_daemon": "x" },
5295 "owner_authorized": true
5296 });
5297 let body = serde_json::to_vec(&body).unwrap();
5298 let bind = Frame::build(FrameType::Request, control_flags(), 0, 0, 41, body).unwrap();
5299
5300 let kept_serving = handle_frame(
5301 bind,
5302 &tx,
5303 Arc::clone(&handler),
5304 dispatcher.clone(),
5305 module_handle.clone(),
5306 )
5307 .await
5308 .expect("an undecodable control request must not end the module");
5309 assert!(kept_serving);
5310 let refusal = timeout(Duration::from_secs(1), rx.recv())
5311 .await
5312 .unwrap()
5313 .unwrap();
5314 assert_eq!(refusal.header.ty, FrameType::Error);
5315 assert_eq!(refusal.header.corr, 41);
5316 let error: ErrorBody = serde_json::from_slice(&refusal.body).unwrap();
5317 assert_eq!(error.code, "invalid_request");
5318 assert!(
5321 error.message.contains("a_field_from_a_newer_daemon"),
5322 "{}",
5323 error.message
5324 );
5325
5326 assert!(
5327 handle_frame(health_request(42), &tx, handler, dispatcher, module_handle)
5328 .await
5329 .unwrap()
5330 );
5331 let health = timeout(Duration::from_secs(1), rx.recv())
5332 .await
5333 .unwrap()
5334 .unwrap();
5335 assert_eq!(health.header.ty, FrameType::Response);
5336 assert_eq!(health.header.corr, 42);
5337 }
5338
5339 #[tokio::test]
5340 async fn default_health_check_answers_ok() {
5341 let (tx, mut rx) = mpsc::channel(4);
5342 let handler = Arc::new(EchoHandler);
5343 let dispatcher = RequestDispatcher::new();
5344 let (module_handle, _unused_rx) = test_module_handle(&[]);
5345
5346 assert!(
5347 handle_frame(health_request(77), &tx, handler, dispatcher, module_handle)
5348 .await
5349 .unwrap()
5350 );
5351
5352 let response = timeout(Duration::from_secs(1), rx.recv())
5353 .await
5354 .unwrap()
5355 .unwrap();
5356 assert_eq!(response.header.ty, FrameType::Response);
5357 assert_eq!(response.header.channel, 0);
5358 assert_eq!(response.header.corr, 77);
5359
5360 let parsed = serde_json::from_slice::<ModuleControlResponse>(&response.body).unwrap();
5365 let ModuleControlResponse::HealthCheck { status, detail, .. } = parsed else {
5366 panic!("expected a health.check response");
5367 };
5368 assert_eq!(status, HealthStatus::Ok);
5371 assert!(
5375 detail
5376 .as_deref()
5377 .is_some_and(|d| d.contains("no health implementation")),
5378 "the inherited default must identify itself, got {detail:?}"
5379 );
5380 }
5381
5382 struct DispatchHarness {
5383 tx: mpsc::Sender<Frame>,
5384 rx: mpsc::Receiver<Frame>,
5385 handler: Arc<BlockingHandler>,
5386 dispatcher: RequestDispatcher,
5387 module_handle: ModuleHandle,
5388 }
5389
5390 impl DispatchHarness {
5391 fn new(report: HealthReport) -> Self {
5392 let (tx, rx) = mpsc::channel(HANDLER_TASK_CAPACITY + 4);
5393 let (module_handle, _unused_rx) = test_module_handle(&[]);
5394 module_handle
5395 .install_route(RouteHandle::new(7, 1, 1))
5396 .unwrap();
5397 Self {
5398 tx,
5399 rx,
5400 handler: Arc::new(BlockingHandler {
5401 entered: Arc::new(AtomicUsize::new(0)),
5402 release: Semaphore::new(0),
5403 report,
5404 }),
5405 dispatcher: RequestDispatcher::new(),
5406 module_handle,
5407 }
5408 }
5409
5410 async fn request(&self, corr: u64) {
5411 handle_frame(
5412 data_request(7, corr),
5413 &self.tx,
5414 Arc::clone(&self.handler),
5415 self.dispatcher.clone(),
5416 self.module_handle.clone(),
5417 )
5418 .await
5419 .unwrap();
5420 }
5421
5422 async fn wait_for_entered(&self, count: usize) {
5423 timeout(Duration::from_secs(1), async {
5424 while self.handler.entered.load(Ordering::SeqCst) != count {
5425 tokio::task::yield_now().await;
5426 }
5427 })
5428 .await
5429 .expect("data handlers should acquire the available slots");
5430 }
5431
5432 async fn saturate(&self) {
5433 for corr in 1..=HANDLER_TASK_CAPACITY as u64 {
5434 self.request(corr).await;
5435 }
5436 self.wait_for_entered(HANDLER_TASK_CAPACITY).await;
5437 self.request(HANDLER_TASK_CAPACITY as u64 + 1).await;
5438 tokio::task::yield_now().await;
5439 assert_eq!(self.dispatcher.pools.default.permits.available_permits(), 0);
5440 assert_eq!(
5441 self.dispatcher.pools.default.waiting.lock().unwrap().len(),
5442 1
5443 );
5444 assert_eq!(
5445 self.handler.entered.load(Ordering::SeqCst),
5446 HANDLER_TASK_CAPACITY
5447 );
5448 }
5449
5450 async fn health(&mut self, corr: u64) -> HealthReport {
5451 handle_frame(
5452 health_request(corr),
5453 &self.tx,
5454 Arc::clone(&self.handler),
5455 self.dispatcher.clone(),
5456 self.module_handle.clone(),
5457 )
5458 .await
5459 .unwrap();
5460 let frame = timeout(Duration::from_millis(100), self.rx.recv())
5461 .await
5462 .expect("health.check must answer within 100 ms while data slots are busy")
5463 .unwrap();
5464 assert_eq!(frame.header.ty, FrameType::Response);
5465 assert_eq!(frame.header.channel, 0);
5466 assert_eq!(frame.header.corr, corr);
5467 serde_json::from_slice::<ModuleControlResponse>(&frame.body)
5468 .unwrap()
5469 .health_report()
5470 .unwrap()
5471 }
5472
5473 async fn release(&mut self, count: usize) {
5474 self.handler.release.add_permits(count);
5475 for _ in 0..count {
5476 let frame = timeout(Duration::from_secs(1), self.rx.recv())
5477 .await
5478 .unwrap()
5479 .unwrap();
5480 assert_eq!(frame.header.ty, FrameType::StreamEnd);
5481 assert_eq!(frame.header.channel, 7);
5482 }
5483 assert!(self
5484 .dispatcher
5485 .pools
5486 .default
5487 .waiting
5488 .lock()
5489 .unwrap()
5490 .is_empty());
5491 assert!(self.dispatcher.in_flight.lock().unwrap().is_empty());
5492 assert_eq!(
5493 self.dispatcher.pools.default.permits.available_permits(),
5494 HANDLER_TASK_CAPACITY
5495 );
5496 }
5497 }
5498
5499 #[tokio::test(start_paused = true)]
5500 async fn health_check_answers_degraded_under_saturation_and_recovers() {
5501 let own_report = HealthReport {
5502 status: HealthStatus::Ok,
5503 detail: Some("module gauges healthy".to_string()),
5504 metrics: Some(json!({"transforms": 64})),
5505 };
5506 let mut harness = DispatchHarness::new(own_report.clone());
5507 harness.saturate().await;
5508 assert_eq!(harness.health(899).await, own_report);
5510 advance(Duration::from_millis(7300)).await;
5513 let report = harness.health(900).await;
5514 assert_eq!(report.status, HealthStatus::Degraded);
5515 assert_eq!(report.metrics, own_report.metrics);
5516 assert_eq!(
5517 report.detail.as_deref(),
5518 Some("request dispatch saturated: 64/64 in use, oldest waiting 7.3 s; module gauges healthy")
5519 );
5520
5521 harness.release(HANDLER_TASK_CAPACITY + 1).await;
5522 assert_eq!(harness.health(901).await, own_report);
5523 }
5524
5525 #[tokio::test(start_paused = true)]
5526 async fn health_check_preserves_failing_under_saturation() {
5527 let mut harness = DispatchHarness::new(HealthReport {
5528 status: HealthStatus::Failing,
5529 detail: Some("module dispatch heartbeat stale".to_string()),
5530 metrics: Some(json!({"heartbeat_age_s": 12})),
5531 });
5532 harness.saturate().await;
5533 advance(Duration::from_millis(7300)).await;
5534 let report = harness.health(900).await;
5535 assert_eq!(report.status, HealthStatus::Failing);
5536 assert_eq!(report.metrics, Some(json!({"heartbeat_age_s": 12})));
5537 assert_eq!(
5538 report.detail.as_deref(),
5539 Some("request dispatch saturated: 64/64 in use, oldest waiting 7.3 s; module dispatch heartbeat stale")
5540 );
5541 harness.release(HANDLER_TASK_CAPACITY + 1).await;
5542 }
5543
5544 #[tokio::test(start_paused = true)]
5545 async fn health_check_passes_module_report_through_with_free_permits() {
5546 for status in [
5547 HealthStatus::Ok,
5548 HealthStatus::Degraded,
5549 HealthStatus::Failing,
5550 ] {
5551 let own_report = HealthReport {
5552 status,
5553 detail: Some("module's own assessment".to_string()),
5554 metrics: Some(json!({"gauge": 42})),
5555 };
5556 let mut harness = DispatchHarness::new(own_report.clone());
5557 harness.request(1).await;
5558 harness.wait_for_entered(1).await;
5559 advance(Duration::from_millis(7300)).await;
5560 assert_eq!(harness.health(900).await, own_report);
5561 harness.release(1).await;
5562 }
5563 }
5564
5565 struct CorrBlockingHandler {
5566 entered: Arc<Mutex<Vec<u64>>>,
5567 release_first: Arc<Semaphore>,
5568 }
5569
5570 #[async_trait]
5571 impl ModuleHandler for CorrBlockingHandler {
5572 async fn handle(&self, ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5573 let corr = ctx.corr();
5574 self.entered.lock().unwrap().push(corr);
5575 if corr == 1 {
5576 self.release_first.acquire().await.unwrap().forget();
5577 }
5578 HandlerOutcome::Response(Vec::new())
5579 }
5580 }
5581
5582 #[tokio::test]
5586 async fn cancelled_capacity_queued_data_request_is_answered_without_waiting_for_a_slot() {
5587 let (tx, mut rx) = mpsc::channel(4);
5588 let entered = Arc::new(Mutex::new(Vec::new()));
5589 let release_first = Arc::new(Semaphore::new(0));
5590 let handler = Arc::new(CorrBlockingHandler {
5591 entered: Arc::clone(&entered),
5592 release_first: Arc::clone(&release_first),
5593 });
5594 let dispatcher = RequestDispatcher::with_pools(Arc::new(
5595 DispatchPools::with_default_limit(1, RequestPools::new()),
5596 ));
5597 let (module_handle, _unused_rx) = test_module_handle(&[]);
5598 module_handle
5599 .install_route(RouteHandle::new(7, 1, 1))
5600 .unwrap();
5601
5602 handle_frame(
5603 data_request(7, 1),
5604 &tx,
5605 Arc::clone(&handler),
5606 dispatcher.clone(),
5607 module_handle.clone(),
5608 )
5609 .await
5610 .unwrap();
5611 timeout(Duration::from_secs(1), async {
5612 while entered.lock().unwrap().as_slice() != [1] {
5613 tokio::task::yield_now().await;
5614 }
5615 })
5616 .await
5617 .unwrap();
5618
5619 handle_frame(
5620 data_request(7, 2),
5621 &tx,
5622 Arc::clone(&handler),
5623 dispatcher.clone(),
5624 module_handle.clone(),
5625 )
5626 .await
5627 .unwrap();
5628 timeout(Duration::from_secs(1), async {
5629 while !dispatcher
5630 .in_flight
5631 .lock()
5632 .unwrap()
5633 .contains_key(&(7, 1, 2))
5634 {
5635 tokio::task::yield_now().await;
5636 }
5637 })
5638 .await
5639 .unwrap();
5640 handle_frame(
5641 Frame::build(FrameType::Cancel, data_flags(), 7, 1, 2, Vec::new()).unwrap(),
5642 &tx,
5643 Arc::clone(&handler),
5644 dispatcher.clone(),
5645 module_handle,
5646 )
5647 .await
5648 .unwrap();
5649 assert!(
5650 dispatcher
5651 .in_flight
5652 .lock()
5653 .unwrap()
5654 .get(&(7, 1, 2))
5655 .unwrap()
5656 .is_cancelled(),
5657 "cancel must land while the second request waits for handler capacity"
5658 );
5659
5660 let cancelled = timeout(Duration::from_secs(1), rx.recv())
5663 .await
5664 .expect("a request cancelled while waiting must be answered without waiting for a slot")
5665 .unwrap();
5666 assert_eq!(cancelled.header.ty, FrameType::Error);
5667 assert_eq!(cancelled.header.channel, 7);
5668 assert_eq!(cancelled.header.epoch, 1);
5669 assert_eq!(cancelled.header.corr, 2);
5670 assert_eq!(
5671 serde_json::from_slice::<ErrorBody>(&cancelled.body).unwrap(),
5672 ErrorBody {
5673 code: "cancelled".to_string(),
5674 message: "request cancelled".to_string(),
5675 detail: None,
5676 }
5677 );
5678 timeout(Duration::from_secs(1), async {
5679 while dispatcher
5680 .in_flight
5681 .lock()
5682 .unwrap()
5683 .contains_key(&(7, 1, 2))
5684 {
5685 tokio::task::yield_now().await;
5686 }
5687 })
5688 .await
5689 .unwrap();
5690 assert_eq!(dispatcher.pools.default.permits.available_permits(), 0);
5691 assert!(dispatcher.pools.default.waiting.lock().unwrap().is_empty());
5692 assert_eq!(*entered.lock().unwrap(), vec![1]);
5693
5694 release_first.add_permits(1);
5695 let response = timeout(Duration::from_secs(1), rx.recv())
5696 .await
5697 .unwrap()
5698 .unwrap();
5699 assert_eq!(response.header.ty, FrameType::Response);
5700 assert_eq!(response.header.corr, 1);
5701 timeout(Duration::from_secs(1), async {
5702 while !dispatcher.in_flight.lock().unwrap().is_empty() {
5703 tokio::task::yield_now().await;
5704 }
5705 })
5706 .await
5707 .unwrap();
5708 assert_eq!(*entered.lock().unwrap(), vec![1]);
5709 assert_eq!(dispatcher.pools.default.permits.available_permits(), 1);
5710 assert!(timeout(Duration::from_millis(50), rx.recv()).await.is_err());
5711 }
5712
5713 #[tokio::test]
5714 async fn cancelled_terminal_is_not_sent_after_route_teardown() {
5715 let (tx, mut rx) = mpsc::channel(1);
5716 let (module_handle, _unused_rx) = test_module_handle(&[]);
5717 let handle = RouteHandle::new(7, 1, 1);
5718 module_handle.install_route(handle).unwrap();
5719 let ctx = RequestCtx {
5720 handle,
5721 corr: 2,
5722 ver: PROTOCOL_VERSION,
5723 egress: tx,
5724 module_handle: module_handle.clone(),
5725 cancelled: CancellationToken::new(),
5726 binary_reply: Arc::new(AtomicBool::new(false)),
5727 request_flags: Flags::new(false, Priority::Interactive, false),
5728 request_body: Arc::from([]),
5729 };
5730 assert!(module_handle.remove_route(handle).unwrap());
5731
5732 let result = send_handler_outcome(
5733 &ctx,
5734 HandlerOutcome::Error {
5735 code: "cancelled".to_string(),
5736 message: "request cancelled".to_string(),
5737 },
5738 )
5739 .await;
5740
5741 assert!(matches!(
5742 result,
5743 Err(SubcModuleError::StaleRouteHandle(stale)) if stale == handle
5744 ));
5745 assert!(rx.try_recv().is_err());
5746 }
5747
5748 struct CountingHandler {
5749 calls: Arc<AtomicUsize>,
5750 }
5751
5752 #[async_trait]
5753 impl ModuleHandler for CountingHandler {
5754 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5755 self.calls.fetch_add(1, Ordering::SeqCst);
5756 HandlerOutcome::Response(Vec::new())
5757 }
5758 }
5759
5760 #[tokio::test]
5761 async fn endpoint_validation_drops_stale_request_before_handler_dispatch() {
5762 let (tx, mut rx) = mpsc::channel(4);
5763 let calls = Arc::new(AtomicUsize::new(0));
5764 let handler = Arc::new(CountingHandler {
5765 calls: Arc::clone(&calls),
5766 });
5767 let dispatcher = RequestDispatcher::new();
5768 let (module_handle, _unused_rx) = test_module_handle(&[]);
5769 module_handle
5770 .install_route(RouteHandle::new(7, 2, 1))
5771 .unwrap();
5772 let stale = Frame::build(FrameType::Request, data_flags(), 7, 1, 55, Vec::new()).unwrap();
5773
5774 assert!(
5775 handle_frame(stale, &tx, handler, dispatcher, module_handle.clone())
5776 .await
5777 .unwrap()
5778 );
5779 tokio::task::yield_now().await;
5780 assert_eq!(calls.load(Ordering::SeqCst), 0);
5781 assert_eq!(module_handle.dropped_route_frames(), 1);
5782 assert!(rx.try_recv().is_err());
5783 }
5784
5785 struct BindOrderingHandler {
5786 module_handle: ModuleHandle,
5787 bind_emit_rejected: Arc<AtomicUsize>,
5788 bound: Arc<AtomicUsize>,
5789 cleanup: Arc<AtomicUsize>,
5790 }
5791
5792 #[async_trait]
5793 impl ModuleHandler for BindOrderingHandler {
5794 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5795 HandlerOutcome::Response(Vec::new())
5796 }
5797
5798 async fn on_bind(&self, req: &RouteBindRequest) -> BindDecision {
5799 if matches!(
5800 self.module_handle
5801 .push(&req.handle, b"too-early".to_vec(), None)
5802 .await,
5803 Err(SubcModuleError::StaleRouteHandle(_))
5804 ) {
5805 self.bind_emit_rejected.fetch_add(1, Ordering::SeqCst);
5806 }
5807 BindDecision::accept()
5808 }
5809
5810 async fn on_bound(&self, handle: &RouteHandle) {
5811 self.bound.fetch_add(1, Ordering::SeqCst);
5812 self.module_handle
5813 .push(handle, b"bound".to_vec(), Some(AdmissionClass::Expedite))
5814 .await
5815 .unwrap();
5816 }
5817
5818 async fn on_route_gone(&self, _handle: &RouteHandle) {
5819 self.cleanup.fetch_add(1, Ordering::SeqCst);
5820 }
5821 }
5822
5823 fn route_bind_frame(channel: u16, epoch: u32, corr: u64) -> Frame {
5824 let body = serde_json::to_vec(&ModuleControlRequest::RouteBind {
5825 route_channel: channel,
5826 epoch,
5827 target: RouteTarget::ToolProvider {
5828 module_id: "provider".to_string(),
5829 },
5830 identity: BindIdentity::new("test".to_string(), "bind".to_string()),
5831 principal: None,
5832 consumer_capabilities: None,
5833 role_versions: None,
5834 admission_facts: None,
5835 scope: None,
5836 call_mode: None,
5837 })
5838 .unwrap();
5839 Frame::build(FrameType::Request, control_flags(), 0, 0, corr, body).unwrap()
5840 }
5841
5842 #[tokio::test]
5843 async fn on_bound_runs_only_after_ack_queue_and_handle_install() {
5844 let (module_handle, mut rx) = test_module_handle(&[]);
5845 let tx = module_handle.shared.lock_inner().writer.clone().unwrap();
5846 let bind_emit_rejected = Arc::new(AtomicUsize::new(0));
5847 let bound = Arc::new(AtomicUsize::new(0));
5848 let cleanup = Arc::new(AtomicUsize::new(0));
5849 let handler = Arc::new(BindOrderingHandler {
5850 module_handle: module_handle.clone(),
5851 bind_emit_rejected: Arc::clone(&bind_emit_rejected),
5852 bound: Arc::clone(&bound),
5853 cleanup: Arc::clone(&cleanup),
5854 });
5855
5856 assert!(handle_frame(
5857 route_bind_frame(8, 4, 90),
5858 &tx,
5859 handler,
5860 RequestDispatcher::new(),
5861 module_handle.clone(),
5862 )
5863 .await
5864 .unwrap());
5865 assert_eq!(bind_emit_rejected.load(Ordering::SeqCst), 1);
5866 assert_eq!(bound.load(Ordering::SeqCst), 1);
5867 assert_eq!(cleanup.load(Ordering::SeqCst), 0);
5868
5869 let ack = rx.recv().await.unwrap();
5870 let push = rx.recv().await.unwrap();
5871 assert_eq!(ack.header.ty, FrameType::Response);
5872 assert_eq!(ack.header.channel, 0);
5873 assert_eq!(push.header.ty, FrameType::Push);
5874 assert_eq!((push.header.channel, push.header.epoch), (8, 4));
5875 assert_eq!(
5876 push.header.flags.admission_class(),
5877 Some(AdmissionClass::Expedite)
5878 );
5879
5880 let captured = RouteHandle::new(8, 4, 1);
5881 assert!(module_handle.remove_route(captured).unwrap());
5882 let stale = module_handle
5883 .push(&captured, Vec::new(), None)
5884 .await
5885 .unwrap_err();
5886 assert!(matches!(stale, SubcModuleError::StaleRouteHandle(_)));
5887 assert!(rx.try_recv().is_err());
5888 }
5889
5890 struct RejectingHandler {
5891 bound: Arc<AtomicUsize>,
5892 cleanup: Arc<AtomicUsize>,
5893 }
5894
5895 #[async_trait]
5896 impl ModuleHandler for RejectingHandler {
5897 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5898 HandlerOutcome::Response(Vec::new())
5899 }
5900
5901 async fn on_bind(&self, _req: &RouteBindRequest) -> BindDecision {
5902 BindDecision::reject("no", "rejected")
5903 }
5904
5905 async fn on_bound(&self, _handle: &RouteHandle) {
5906 self.bound.fetch_add(1, Ordering::SeqCst);
5907 }
5908
5909 async fn on_route_gone(&self, _handle: &RouteHandle) {
5910 self.cleanup.fetch_add(1, Ordering::SeqCst);
5911 }
5912 }
5913
5914 #[tokio::test]
5915 async fn rejected_bind_cleans_up_without_installing_or_calling_on_bound() {
5916 let (module_handle, mut rx) = test_module_handle(&[]);
5917 let tx = module_handle.shared.lock_inner().writer.clone().unwrap();
5918 let bound = Arc::new(AtomicUsize::new(0));
5919 let cleanup = Arc::new(AtomicUsize::new(0));
5920 let handler = Arc::new(RejectingHandler {
5921 bound: Arc::clone(&bound),
5922 cleanup: Arc::clone(&cleanup),
5923 });
5924 handle_frame(
5925 route_bind_frame(6, 3, 91),
5926 &tx,
5927 handler,
5928 RequestDispatcher::new(),
5929 module_handle.clone(),
5930 )
5931 .await
5932 .unwrap();
5933 let refusal = rx.recv().await.unwrap();
5934 assert_eq!(refusal.header.ty, FrameType::Error);
5935 assert_eq!(refusal.body, br#"{"code":"no","message":"rejected"}"#);
5937 assert_eq!(bound.load(Ordering::SeqCst), 0);
5938 assert_eq!(cleanup.load(Ordering::SeqCst), 1);
5939 assert!(matches!(
5940 module_handle.validate_route(RouteHandle::new(6, 3, 1)),
5941 Err(SubcModuleError::StaleRouteHandle(_))
5942 ));
5943 }
5944
5945 struct BusyHandler;
5946
5947 #[async_trait]
5948 impl ModuleHandler for BusyHandler {
5949 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5950 HandlerOutcome::Response(Vec::new())
5951 }
5952
5953 async fn on_bind(&self, _req: &RouteBindRequest) -> BindDecision {
5954 BindDecision::reject_with_detail(
5955 "bind_busy",
5956 "a read is still running on this root",
5957 serde_json::json!({"reason": "reader", "retry_after_ms": 2000}),
5958 )
5959 }
5960 }
5961
5962 #[tokio::test]
5963 async fn rejected_bind_carries_its_detail_to_the_daemon() {
5964 let (module_handle, mut rx) = test_module_handle(&[]);
5965 let tx = module_handle.shared.lock_inner().writer.clone().unwrap();
5966 handle_frame(
5967 route_bind_frame(6, 3, 92),
5968 &tx,
5969 Arc::new(BusyHandler),
5970 RequestDispatcher::new(),
5971 module_handle.clone(),
5972 )
5973 .await
5974 .unwrap();
5975 let refusal = rx.recv().await.unwrap();
5976 assert_eq!(refusal.header.ty, FrameType::Error);
5977 let body: ErrorBody = serde_json::from_slice(&refusal.body).unwrap();
5978 assert_eq!(body.code, "bind_busy");
5979 assert_eq!(
5980 body.detail,
5981 Some(serde_json::json!({"reason": "reader", "retry_after_ms": 2000}))
5982 );
5983 }
5984
5985 struct RebindCountingHandler {
5986 bound: Arc<AtomicUsize>,
5987 cleanup: Arc<AtomicUsize>,
5988 }
5989
5990 #[async_trait]
5991 impl ModuleHandler for RebindCountingHandler {
5992 async fn handle(&self, _ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
5993 HandlerOutcome::Response(Vec::new())
5994 }
5995
5996 async fn on_bound(&self, _handle: &RouteHandle) {
5997 self.bound.fetch_add(1, Ordering::SeqCst);
5998 }
5999
6000 async fn on_route_gone(&self, _handle: &RouteHandle) {
6001 self.cleanup.fetch_add(1, Ordering::SeqCst);
6002 }
6003 }
6004
6005 #[tokio::test]
6011 async fn rebind_on_installed_channel_replaces_on_higher_epoch_only() {
6012 let (module_handle, mut rx) = test_module_handle(&[]);
6013 let tx = module_handle.shared.lock_inner().writer.clone().unwrap();
6014 let bound = Arc::new(AtomicUsize::new(0));
6015 let cleanup = Arc::new(AtomicUsize::new(0));
6016 let handler = Arc::new(RebindCountingHandler {
6017 bound: Arc::clone(&bound),
6018 cleanup: Arc::clone(&cleanup),
6019 });
6020
6021 handle_frame(
6023 route_bind_frame(8, 4, 90),
6024 &tx,
6025 Arc::clone(&handler),
6026 RequestDispatcher::new(),
6027 module_handle.clone(),
6028 )
6029 .await
6030 .unwrap();
6031 assert_eq!(rx.recv().await.unwrap().header.ty, FrameType::Response);
6032 assert_eq!(
6033 (bound.load(Ordering::SeqCst), cleanup.load(Ordering::SeqCst)),
6034 (1, 0)
6035 );
6036
6037 handle_frame(
6039 route_bind_frame(8, 4, 91),
6040 &tx,
6041 Arc::clone(&handler),
6042 RequestDispatcher::new(),
6043 module_handle.clone(),
6044 )
6045 .await
6046 .unwrap();
6047 let reject = rx.recv().await.unwrap();
6048 assert_eq!(reject.header.ty, FrameType::Error);
6049 assert_eq!(
6050 (bound.load(Ordering::SeqCst), cleanup.load(Ordering::SeqCst)),
6051 (1, 0)
6052 );
6053 module_handle
6054 .validate_route(RouteHandle::new(8, 4, 1))
6055 .expect("epoch-4 install must survive the rejected rebind");
6056
6057 handle_frame(
6059 route_bind_frame(8, 3, 92),
6060 &tx,
6061 Arc::clone(&handler),
6062 RequestDispatcher::new(),
6063 module_handle.clone(),
6064 )
6065 .await
6066 .unwrap();
6067 assert_eq!(rx.recv().await.unwrap().header.ty, FrameType::Error);
6068 assert_eq!(
6069 (bound.load(Ordering::SeqCst), cleanup.load(Ordering::SeqCst)),
6070 (1, 0)
6071 );
6072
6073 handle_frame(
6076 route_bind_frame(8, 5, 93),
6077 &tx,
6078 Arc::clone(&handler),
6079 RequestDispatcher::new(),
6080 module_handle.clone(),
6081 )
6082 .await
6083 .unwrap();
6084 assert_eq!(rx.recv().await.unwrap().header.ty, FrameType::Response);
6085 assert_eq!(
6086 (bound.load(Ordering::SeqCst), cleanup.load(Ordering::SeqCst)),
6087 (2, 1)
6088 );
6089 assert!(matches!(
6090 module_handle.validate_route(RouteHandle::new(8, 4, 1)),
6091 Err(SubcModuleError::StaleRouteHandle(_))
6092 ));
6093 module_handle
6094 .validate_route(RouteHandle::new(8, 5, 1))
6095 .expect("epoch-5 install must be live after implicit replace");
6096 }
6097
6098 #[tokio::test]
6099 async fn module_control_corr_is_monotonic_and_exhausts_without_wrap() {
6100 let (module_handle, _rx) = test_module_handle(&[MODULE_TO_SUBC_OP_CATALOG_UPDATE]);
6101 let mut inner = module_handle.shared.lock_inner();
6102 inner.next_corr = Some(u64::MAX);
6103 assert_eq!(next_module_control_corr(&mut inner), Some(u64::MAX));
6104 assert_eq!(next_module_control_corr(&mut inner), None);
6105 }
6106}
6107
6108#[cfg(test)]
6111mod module_close_tests {
6112 use std::time::Instant;
6113
6114 use tokio::{io::DuplexStream, sync::Notify};
6115
6116 use super::stand_in::{serve_against_stand_in_with_ops, Served};
6117 use super::*;
6118
6119 #[derive(Clone, Copy)]
6121 enum Hold {
6122 UntilCancelled,
6124 IgnoringCancellation,
6126 }
6127
6128 struct HoldingHandler {
6129 hold: Hold,
6130 entered: Arc<Notify>,
6131 token: Arc<Mutex<Option<CancellationToken>>>,
6132 }
6133
6134 #[async_trait]
6135 impl ModuleHandler for HoldingHandler {
6136 async fn handle(&self, ctx: RequestCtx, _body: Vec<u8>) -> HandlerOutcome {
6137 *self.token.lock().unwrap() = Some(ctx.cancellation_token());
6138 self.entered.notify_one();
6139 match self.hold {
6140 Hold::UntilCancelled => {
6141 ctx.cancelled().await;
6142 HandlerOutcome::Error {
6143 code: "cancelled".to_string(),
6144 message: "request cancelled".to_string(),
6145 }
6146 }
6147 Hold::IgnoringCancellation => std::future::pending().await,
6148 }
6149 }
6150 }
6151
6152 async fn serve_against_stand_in<H: ModuleHandler>(handler: H) -> Served {
6154 serve_against_stand_in_with_ops(|_| handler, &[]).await
6155 }
6156
6157 async fn send(daemon: &mut DuplexStream, frame: Frame) {
6158 write_frame(daemon, &frame).await.unwrap();
6159 daemon.flush().await.unwrap();
6160 }
6161
6162 async fn hold_one_request(served: &mut Served, entered: &Notify) {
6165 let bind = serde_json::to_vec(&ModuleControlRequest::RouteBind {
6166 route_channel: 7,
6167 epoch: 1,
6168 target: RouteTarget::ToolProvider {
6169 module_id: "close-test".to_string(),
6170 },
6171 identity: BindIdentity::new("test".to_string(), "close".to_string()),
6172 principal: None,
6173 consumer_capabilities: None,
6174 role_versions: None,
6175 admission_facts: None,
6176 scope: None,
6177 call_mode: None,
6178 })
6179 .unwrap();
6180 send(
6181 &mut served.daemon,
6182 Frame::build(FrameType::Request, control_flags(), 0, 0, 2, bind).unwrap(),
6183 )
6184 .await;
6185 loop {
6186 let frame = read_frame(&mut served.daemon).await.unwrap().unwrap();
6187 if frame.header.channel == 0 && frame.header.corr == 2 {
6188 assert_eq!(
6189 frame.header.ty,
6190 FrameType::Response,
6191 "route.bind must be acked"
6192 );
6193 break;
6194 }
6195 }
6196 send(
6197 &mut served.daemon,
6198 Frame::build(FrameType::Request, data_flags(), 7, 1, 10, b"hold".to_vec()).unwrap(),
6199 )
6200 .await;
6201 timeout(Duration::from_secs(2), entered.notified())
6202 .await
6203 .expect("the handler must receive the request");
6204 }
6205
6206 fn goodbye() -> Frame {
6207 Frame::build(FrameType::Goodbye, control_flags(), 0, 0, 0, Vec::new()).unwrap()
6208 }
6209
6210 fn holding(
6211 hold: Hold,
6212 ) -> (
6213 HoldingHandler,
6214 Arc<Notify>,
6215 Arc<Mutex<Option<CancellationToken>>>,
6216 ) {
6217 let entered = Arc::new(Notify::new());
6218 let token = Arc::new(Mutex::new(None));
6219 let handler = HoldingHandler {
6220 hold,
6221 entered: Arc::clone(&entered),
6222 token: Arc::clone(&token),
6223 };
6224 (handler, entered, token)
6225 }
6226
6227 #[tokio::test]
6228 async fn goodbye_cancels_an_open_request_and_the_serve_future_completes() {
6229 let (handler, entered, token) = holding(Hold::UntilCancelled);
6230 let mut served = serve_against_stand_in(handler).await;
6231 hold_one_request(&mut served, &entered).await;
6232
6233 let started = Instant::now();
6234 send(&mut served.daemon, goodbye()).await;
6235 let result = timeout(Duration::from_secs(5), &mut served.serve)
6236 .await
6237 .expect("a held request must not keep the serve future alive after GOODBYE");
6238 result.unwrap().unwrap();
6239 assert!(
6240 token.lock().unwrap().as_ref().unwrap().is_cancelled(),
6241 "GOODBYE must cancel the request's token"
6242 );
6243 assert!(
6246 started.elapsed() < DEFAULT_WRITER_DRAIN_TIMEOUT,
6247 "closing took {:?}",
6248 started.elapsed()
6249 );
6250 }
6251
6252 #[tokio::test]
6253 async fn a_handler_ignoring_cancellation_cannot_keep_the_serve_future_alive() {
6254 let (handler, entered, _token) = holding(Hold::IgnoringCancellation);
6255 let mut served = serve_against_stand_in(handler).await;
6256 hold_one_request(&mut served, &entered).await;
6257
6258 let started = Instant::now();
6259 send(&mut served.daemon, goodbye()).await;
6260 let result = timeout(
6261 DEFAULT_WRITER_DRAIN_TIMEOUT + Duration::from_secs(3),
6262 &mut served.serve,
6263 )
6264 .await
6265 .expect("the writer drain must be bounded");
6266 result.unwrap().unwrap();
6267 assert!(started.elapsed() >= DEFAULT_WRITER_DRAIN_TIMEOUT);
6268 }
6269
6270 #[tokio::test]
6271 async fn closed_resolves_after_goodbye() {
6272 let served = serve_against_stand_in(EchoHandler).await;
6273 let mut served = served;
6274 assert!(!served.handle.is_closed());
6275 let closed = served.handle.closed();
6276 send(&mut served.daemon, goodbye()).await;
6277 timeout(Duration::from_secs(2), closed)
6278 .await
6279 .expect("closed() must resolve after GOODBYE");
6280 assert!(served.handle.is_closed());
6281 }
6282
6283 #[tokio::test]
6284 async fn closed_resolves_after_eof() {
6285 let Served {
6286 daemon,
6287 handle,
6288 serve: _serve,
6289 } = serve_against_stand_in(EchoHandler).await;
6290 assert!(!handle.is_closed());
6291 drop(daemon);
6292 timeout(Duration::from_secs(2), handle.closed())
6293 .await
6294 .expect("closed() must resolve after EOF");
6295 assert!(handle.is_closed());
6296 }
6297
6298 struct EchoHandler;
6299
6300 #[async_trait]
6301 impl ModuleHandler for EchoHandler {
6302 async fn handle(&self, _ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome {
6303 HandlerOutcome::Response(body)
6304 }
6305 }
6306
6307 #[derive(Clone, Default)]
6310 struct EndRecorder(Arc<Mutex<Vec<ConnectionEnd>>>);
6311
6312 #[async_trait]
6313 impl ModuleHandler for EndRecorder {
6314 async fn handle(&self, _ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome {
6315 HandlerOutcome::Response(body)
6316 }
6317 async fn on_connection_end(&self, end: ConnectionEnd) {
6318 self.0.lock().unwrap().push(end);
6319 }
6320 }
6321
6322 async fn reported_end(recorder: &EndRecorder, served: &mut Served) -> Vec<ConnectionEnd> {
6323 timeout(Duration::from_secs(5), &mut served.serve)
6324 .await
6325 .expect("serving must end")
6326 .unwrap()
6327 .unwrap();
6328 recorder.0.lock().unwrap().clone()
6329 }
6330
6331 #[tokio::test]
6332 async fn a_daemon_goodbye_is_reported_as_goodbye() {
6333 let recorder = EndRecorder::default();
6334 let mut served = serve_against_stand_in(recorder.clone()).await;
6335 send(&mut served.daemon, goodbye()).await;
6336 assert_eq!(
6337 reported_end(&recorder, &mut served).await,
6338 vec![ConnectionEnd::Goodbye]
6339 );
6340 }
6341
6342 #[tokio::test]
6343 async fn a_daemon_closing_without_goodbye_is_reported_as_eof() {
6344 let recorder = EndRecorder::default();
6345 let mut served = serve_against_stand_in(recorder.clone()).await;
6346 served.daemon.shutdown().await.unwrap();
6347 assert_eq!(
6348 reported_end(&recorder, &mut served).await,
6349 vec![ConnectionEnd::Eof]
6350 );
6351 }
6352
6353 #[derive(Debug, Clone, PartialEq)]
6355 enum Seen {
6356 Draining(RouteCloseReason, SystemTime),
6357 End(ConnectionEnd),
6358 }
6359
6360 #[derive(Clone, Default)]
6363 struct DrainRecorder {
6364 seen: Arc<Mutex<Vec<Seen>>>,
6365 park: bool,
6366 }
6367
6368 #[async_trait]
6369 impl ModuleHandler for DrainRecorder {
6370 async fn handle(&self, _ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome {
6371 HandlerOutcome::Response(body)
6372 }
6373 async fn on_draining(&self, reason: RouteCloseReason, deadline: SystemTime) {
6374 self.seen
6375 .lock()
6376 .unwrap()
6377 .push(Seen::Draining(reason, deadline));
6378 if self.park {
6379 std::future::pending::<()>().await;
6380 }
6381 }
6382 async fn on_connection_end(&self, end: ConnectionEnd) {
6383 self.seen.lock().unwrap().push(Seen::End(end));
6384 }
6385 }
6386
6387 fn control_push(body: &[u8]) -> Frame {
6388 Frame::build(FrameType::Push, control_flags(), 0, 0, 0, body.to_vec()).unwrap()
6389 }
6390
6391 fn draining_push(reason: subc_protocol::RouteCloseReason, deadline_ms: u64) -> Frame {
6392 control_push(
6393 &serde_json::to_vec(&ModuleControlCommand::Draining {
6394 reason,
6395 deadline_ms,
6396 })
6397 .unwrap(),
6398 )
6399 }
6400
6401 async fn ping_is_answered(served: &mut Served, corr: u64) {
6404 send(
6405 &mut served.daemon,
6406 Frame::build(FrameType::Ping, control_flags(), 0, 0, corr, Vec::new()).unwrap(),
6407 )
6408 .await;
6409 let pong = timeout(Duration::from_secs(2), read_frame(&mut served.daemon))
6410 .await
6411 .expect("the module must answer PING")
6412 .unwrap()
6413 .expect("the module must not close the connection");
6414 assert_eq!(pong.header.ty, FrameType::Pong);
6415 assert_eq!(pong.header.corr, corr);
6416 }
6417
6418 #[tokio::test]
6422 async fn a_drain_notice_calls_on_draining_before_the_goodbye_that_follows_it() {
6423 let recorder = DrainRecorder::default();
6424 let mut served = serve_against_stand_in(recorder.clone()).await;
6425 let deadline_ms = 4_102_444_800_000;
6428 write_frame(
6429 &mut served.daemon,
6430 &draining_push(subc_protocol::RouteCloseReason::Restart, deadline_ms),
6431 )
6432 .await
6433 .unwrap();
6434 write_frame(&mut served.daemon, &goodbye()).await.unwrap();
6435 served.daemon.flush().await.unwrap();
6436
6437 timeout(Duration::from_secs(5), &mut served.serve)
6438 .await
6439 .expect("serving must end after GOODBYE")
6440 .unwrap()
6441 .unwrap();
6442 assert_eq!(
6443 *recorder.seen.lock().unwrap(),
6444 vec![
6445 Seen::Draining(
6446 RouteCloseReason::Restart,
6447 UNIX_EPOCH + Duration::from_millis(deadline_ms)
6448 ),
6449 Seen::End(ConnectionEnd::Goodbye),
6450 ]
6451 );
6452 }
6453
6454 #[tokio::test]
6457 async fn a_drain_hook_that_never_returns_does_not_stop_the_frame_reader() {
6458 let recorder = DrainRecorder {
6459 park: true,
6460 ..DrainRecorder::default()
6461 };
6462 let mut served = serve_against_stand_in(recorder.clone()).await;
6463 send(
6464 &mut served.daemon,
6465 draining_push(subc_protocol::RouteCloseReason::Reload, 1),
6466 )
6467 .await;
6468 ping_is_answered(&mut served, 41).await;
6469 assert!(matches!(
6470 recorder.seen.lock().unwrap().as_slice(),
6471 [Seen::Draining(RouteCloseReason::Reload, _)]
6472 ));
6473
6474 send(&mut served.daemon, goodbye()).await;
6475 timeout(Duration::from_secs(5), &mut served.serve)
6476 .await
6477 .expect("a parked drain hook must not keep the serve future alive")
6478 .unwrap()
6479 .unwrap();
6480 }
6481
6482 #[tokio::test]
6486 async fn an_undecodable_channel_zero_push_is_ignored_and_the_connection_stays_up() {
6487 let recorder = DrainRecorder::default();
6488 let mut served = serve_against_stand_in(recorder.clone()).await;
6489 send(
6490 &mut served.daemon,
6491 control_push(br#"{"op":"module.some_future_command","x":1}"#),
6492 )
6493 .await;
6494 send(&mut served.daemon, control_push(b"not json")).await;
6495 send(
6496 &mut served.daemon,
6497 control_push(br#"{"op":"module.draining","reason":"restart"}"#),
6498 )
6499 .await;
6500 ping_is_answered(&mut served, 42).await;
6501 assert!(!served.handle.is_closed());
6502 assert!(!served.serve.is_finished());
6503 assert!(recorder.seen.lock().unwrap().is_empty());
6504 }
6505
6506 #[tokio::test]
6507 async fn a_module_closing_its_own_connection_is_reported_as_closed() {
6508 let recorder = EndRecorder::default();
6509 let mut served = serve_against_stand_in(recorder.clone()).await;
6510 served.handle.close_connection();
6511 assert_eq!(
6512 reported_end(&recorder, &mut served).await,
6513 vec![ConnectionEnd::Closed]
6514 );
6515 }
6516}
6517
6518#[cfg(test)]
6519mod operator_confirm_tests;
6520
6521#[cfg(test)]
6522mod binary_reply_tests;
6523
6524#[cfg(test)]
6525mod serve_lifecycle_tests;
6526
6527#[cfg(test)]
6528mod request_pool_tests;
6529
6530#[cfg(test)]
6531mod detailed_error_body_tests {
6532 use serde_json::json;
6533
6534 use subc_protocol::ErrorBody;
6535
6536 #[test]
6540 fn detailed_error_body_keeps_code_message_and_detail() {
6541 let body = ErrorBody::new("bad_request", "invalid envelope")
6542 .with_detail(json!({"reason": "missing_server"}));
6543
6544 assert_eq!(
6545 serde_json::to_value(body).unwrap(),
6546 json!({
6547 "code": "bad_request",
6548 "message": "invalid envelope",
6549 "detail": {"reason": "missing_server"},
6550 })
6551 );
6552 }
6553
6554 #[test]
6557 fn detail_less_error_body_is_byte_identical_to_the_pre_detail_wire() {
6558 let old_wire = r#"{"code":"cancelled","message":"caller cancelled"}"#;
6559 let parsed: ErrorBody = serde_json::from_str(old_wire).unwrap();
6560 assert_eq!(parsed.detail, None);
6561 assert_eq!(serde_json::to_string(&parsed).unwrap(), old_wire);
6562 }
6563}
6564
6565static RETAINED_LAUNCH_NONCE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
6568
6569pub fn retain_launch_nonce_for_hello(launch_nonce: String) -> Result<(), String> {
6572 RETAINED_LAUNCH_NONCE
6573 .set(launch_nonce)
6574 .map_err(|_| "launch nonce was already retained for this process".to_string())
6575}
6576
6577fn retained_launch_nonce() -> Option<String> {
6578 RETAINED_LAUNCH_NONCE.get().cloned()
6579}
6580
6581pub fn launch_nonce_source() -> Option<LaunchNonceSource> {
6587 launch_nonce()
6588 .ok()
6589 .flatten()
6590 .map(|nonce| LaunchNonceSource::from_wire_name(nonce.source().as_str()))
6591}
6592
6593fn stamp_launch_nonce_source(manifest: &mut ModuleManifest, sent: Option<&str>) {
6601 let Some(provenance) = manifest.provenance.as_mut() else {
6602 return;
6603 };
6604 if provenance.launch_nonce_source.is_some() {
6605 return;
6606 }
6607 if let Ok(Some(nonce)) = launch_nonce() {
6608 let launched = registration::is_launched_module(&manifest.module_id).unwrap_or(false);
6611 if launched && (registration::supervised() || sent == Some(nonce.value())) {
6612 provenance.launch_nonce_source =
6613 Some(LaunchNonceSource::from_wire_name(nonce.source().as_str()));
6614 }
6615 }
6616}
6617
6618#[cfg(test)]
6619mod checked_increment_tests {
6620 use super::checked_increment;
6621 use std::sync::atomic::{AtomicU64, Ordering};
6622
6623 #[test]
6624 fn returns_the_previous_value_and_stops_at_the_maximum() {
6625 let counter = AtomicU64::new(7);
6626 assert_eq!(checked_increment(&counter), Some(7));
6627 assert_eq!(counter.load(Ordering::Relaxed), 8);
6628
6629 let full = AtomicU64::new(u64::MAX);
6630 assert_eq!(checked_increment(&full), None);
6631 assert_eq!(
6632 full.load(Ordering::Relaxed),
6633 u64::MAX,
6634 "an exhausted counter is left unchanged"
6635 );
6636 }
6637}