Skip to main content

subc_client_rs/
lib.rs

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};
77/// The one launch-nonce reader for a module process: `launch_nonce()` reads
78/// the inherited Unix descriptor, the Windows named pipe, or, when neither is
79/// named, the `SUBC_LAUNCH_NONCE` environment copy once and caches it. The SDK's
80/// HELLO and route opens go through it too; a module's own readers must as well.
81/// Read before spawning children so they cannot inherit an unread Unix pipe
82/// containing the module's credential.
83pub 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;
136/// A full dispatcher is normal during a burst. Report dispatch impairment only
137/// once a data request has waited more than two seconds for a handler slot.
138const DISPATCH_SATURATION_WAIT: Duration = Duration::from_secs(2);
139const HELLO_CORR: u64 = 1;
140const DEFAULT_WRITER_DRAIN_TIMEOUT: Duration = Duration::from_secs(2);
141/// When a module's daemon connection ends (GOODBYE, EOF, reset, or module stop),
142/// how long the serve loop waits for each `on_draining` hook it already
143/// spawned to start running before it cancels requests and calls
144/// `on_connection_end`. The wait is only for the hook's first step, which is
145/// normally immediate; the bound matters because the daemon kills a module
146/// that has not exited within its stop timeout after GOODBYE, and a hook that
147/// blocks its thread must not hold the shutdown up that long.
148const DRAINING_HOOK_START_LIMIT: Duration = Duration::from_secs(2);
149static NEXT_MODULE_CONNECTION_TOKEN: AtomicU64 = AtomicU64::new(1);
150/// The connection token of a [`RouteHandle::detached`] handle. Module
151/// connection tokens start at 1 (above) and a consumer's generation starts at
152/// 1 and only grows, so no live connection ever has this token.
153const DETACHED_CONNECTION_TOKEN: u64 = 0;
154
155type RequestKey = (u16, u32, u64);
156type InFlight = Arc<Mutex<HashMap<RequestKey, CancellationToken>>>;
157
158/// Immutable identity of one route binding on one live connection.
159///
160/// Only `channel` and `epoch` are serialized. The private connection token prevents
161/// work retained from an earlier connection from acting on a later connection that
162/// happens to reuse the same wire pair.
163#[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    /// A handle for `channel` and `epoch` that belongs to no connection, for
173    /// building values in tests, such as a [`RouteBindRequest`] passed to a
174    /// module's own `on_bind`. It is never bound to a connection and cannot
175    /// become one.
176    ///
177    /// Every operation that would reach a connection fails with the error
178    /// it returns for a closed or stale route, and sends nothing:
179    /// [`ModuleHandle::push`] returns [`SubcModuleError::StaleRouteHandle`];
180    /// [`SubcConsumer::request`], [`SubcConsumer::subscribe_route`],
181    /// [`SubcConsumer::poll_route`], [`SubcConsumer::push_events`] and
182    /// [`SubcConsumer::close_handle`] return [`CallError::StaleRouteHandle`];
183    /// [`Self::on_request`] and [`Self::on_request_fallible`] return
184    /// [`ReverseRequestRegistrationError::NotConsumerRoute`].
185    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/// A single read-lock snapshot of bound and pending project routes.
277#[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/// The daemon's answer to an accepted [`ModuleHandle::scope_sync`].
285///
286/// A refusal of the whole sync is never a reply: it is
287/// [`ScopeCallError::Refused`], and the daemon changed nothing.
288#[derive(Debug, Clone, PartialEq, Eq)]
289#[non_exhaustive]
290pub struct ScopeSyncReply {
291    /// The generation the daemon accepted, echoed from the request.
292    pub generation: u64,
293    /// One result per record sent, in request order. A record refused on its
294    /// own merits is here with outcome `refused` and its code; the rest of the
295    /// sync still applied.
296    pub results: Vec<ScopeRecordResult>,
297    /// Scopes of this owner that the sync ended, by leaving them out, sending
298    /// a higher epoch for the same ref, or sweeping their expired deadlines.
299    pub ended: Vec<ScopeEnded>,
300}
301
302/// The daemon's answer to an accepted [`ModuleHandle::scope_apply`].
303///
304/// A refusal of the whole delta is [`ScopeCallError::Refused`]; nothing changed.
305#[derive(Debug, Clone, PartialEq, Eq)]
306#[non_exhaustive]
307pub struct ScopeApplyReply {
308    /// The generation the daemon accepted, echoed from the request.
309    pub generation: u64,
310    /// One result per upsert, in request order, including per-record refusals.
311    pub results: Vec<ScopeRecordResult>,
312    /// One result per requested end, in request order. A ref not live at the
313    /// named epoch has outcome `not_live`, which does not refuse the delta.
314    pub end_results: Vec<ScopeEndResult>,
315    /// Scopes this call ended, once each, through explicit ends, higher-epoch
316    /// upserts, or the calling owner's expiry sweep.
317    pub ended: Vec<ScopeEnded>,
318}
319
320/// The daemon's answer to [`ModuleHandle::scope_describe`] about one
321/// `(owner, ref)`.
322#[derive(Debug, Clone, PartialEq, Eq)]
323#[non_exhaustive]
324pub struct ScopeDescribeReply {
325    pub status: ScopeStatus,
326    /// The live epoch, or for `ended` the most recent epoch that ended.
327    pub scope_epoch: Option<u64>,
328    /// Identifies the daemon process that answered. A different value means
329    /// the daemon restarted, and owners re-sync after a restart.
330    pub daemon_incarnation: String,
331    /// Whether the owner has synced since this daemon incarnation started.
332    pub owner_synced: bool,
333    /// Whether the owner is a module in the daemon's supervised roster.
334    pub owner_configured: bool,
335    /// The stamped fields, present only when `status` is `live`. The daemon
336    /// includes `attributes.on_behalf_of_agent` only when this module's manifest
337    /// provides `scope-on-behalf-of/v1`; the field is attribution, never authority.
338    pub scope: Option<ScopeStamp>,
339}
340
341// The protocol's module-control enum predates the separately typed authorization
342// reply. Keep both wire types in the same correlation table and deadline path.
343#[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
366/// Future returned by [`serve_with_handle`] that runs the module until GOODBYE or EOF.
367pub 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    /// The connection's handler-slot pools, shared with its [`ModuleHandle`]
374    /// so the module can read their figures.
375    pools: Arc<DispatchPools>,
376    /// One receiver per `on_draining` hook spawned on this connection, resolved
377    /// once that hook has started running. The connection waits on them before
378    /// acting on its end, so a hook is always called before the GOODBYE that
379    /// follows its drain is handled.
380    draining_hooks: Arc<Mutex<Vec<oneshot::Receiver<()>>>>,
381    /// Set after the first channel-0 push this SDK could not decode has been
382    /// logged, so a daemon that repeats a newer push cannot flood the log.
383    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    /// A dispatcher with the default pool only, as a module that declares no
393    /// classifier gets.
394    #[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    /// Wait, within [`DRAINING_HOOK_START_LIMIT`], until every `on_draining`
461    /// hook spawned on this connection has started. Only the start is awaited:
462    /// a hook may still be finishing its work after the connection has ended.
463    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            // A dropped sender means the hook task ended (or panicked) before
473            // reporting; either way there is nothing left to wait for.
474            if tokio::time::timeout_at(deadline, hook).await.is_err() {
475                return;
476            }
477        }
478    }
479
480    /// Cancel every request still in flight and refuse ones still waiting for a
481    /// handler slot, as a route's GOODBYE does for that route's requests. Run
482    /// when the connection ends: each request task holds a sender to the egress
483    /// channel, so until they finish the writer never sees the channel close.
484    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/// Cloneable handle for module-originated control RPCs on channel 0.
497#[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    /// The handler-slot pools this connection's dispatcher uses. Replaced once,
524    /// with the pools the module's handler declares, before serving starts.
525    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                // A value that does not parse is treated like an absent one:
616                // the module learns nothing rather than a name that is wrong.
617                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    /// The daemon's machine id, as delivered on HELLO_ACK.
648    ///
649    /// `None` means the daemon did not send one (it predates the machine id, or
650    /// was embedded without one) or sent a malformed value. Read that as "the
651    /// daemon has not named this machine", never as "no machine", and never mint
652    /// a substitute. The id is a name, never an authority: see [`MachineId`].
653    pub fn machine_id(&self) -> Option<&MachineId> {
654        self.shared.machine_id.as_ref()
655    }
656
657    /// The daemon capability identifiers delivered in this connection's HELLO_ACK.
658    ///
659    /// The list preserves the daemon's order and unknown capability identifiers.
660    pub fn daemon_capabilities(&self) -> &[String] {
661        &self.shared.daemon_capabilities
662    }
663
664    /// Whether this daemon advertised `capability` in this connection's HELLO_ACK.
665    ///
666    /// Scope owners should check
667    /// `daemon_supports(subc_protocol::manifest::CAP_SCOPE_BIND_PROOF_V1)`
668    /// before setting `ScopeRecord.bind_proof_sha256` on records sent over
669    /// this connection.
670    pub fn daemon_supports(&self, capability: &str) -> bool {
671        self.shared
672            .daemon_capabilities
673            .iter()
674            .any(|advertised| advertised == capability)
675    }
676
677    /// Resolves once this module's connection to the daemon has closed: after a
678    /// channel-0 GOODBYE, EOF, or a connection error. A module ends its own
679    /// background work on it, so nothing outlives the connection.
680    pub fn closed(&self) -> impl Future<Output = ()> + Send + 'static {
681        self.shared.close_token.clone().cancelled_owned()
682    }
683
684    /// Whether this module's connection to the daemon has closed.
685    pub fn is_closed(&self) -> bool {
686        self.shared.close_token.is_cancelled()
687    }
688
689    /// Ask the daemon to replace this module's advertised provider roles in place.
690    ///
691    /// The returned result resolves when the daemon ACKs the update, rejects it with
692    /// a typed channel-0 Error frame, the request times out, or the connection dies.
693    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    /// Replace this module's complete registered role-declaration map in place.
701    ///
702    /// An empty map (`{}` on the wire) clears all declarations. Requires
703    /// subc-daemon 0.44.9 or later; returns [`CatalogUpdateError::NotSupported`]
704    /// without sending when HELLO_ACK does not advertise the operation. Invalid
705    /// declarations are refused by the daemon as [`CatalogUpdateError::Rejected`],
706    /// preserving the previous map and the refusal's code and reason.
707    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    /// Replace provider roles and attest a new static capability declaration.
753    ///
754    /// The declaration must be the same static metadata emitted by the module's
755    /// current manifest; this update exists so the daemon can reconcile live routes
756    /// when that attested metadata changes.
757    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    /// Change readiness without changing provider roles or capability declarations.
767    ///
768    /// Register with `ready(false)`, start polling the serving future immediately,
769    /// and do slow startup work on another task before calling `set_ready(true)`.
770    /// Setting readiness to false refuses new binds but leaves existing routes up.
771    /// Requires subc-daemon 0.20.3 or later (including subc-daemon 0.38.x).
772    ///
773    /// Returns [`CatalogUpdateError::Protocol`] without sending if the current roles
774    /// are unknown: a catalog replacement is still in flight, or an earlier update
775    /// timed out, was cancelled or had an undecodable reply. After an uncertain result, a successful
776    /// explicit catalog replacement establishes the roles again.
777    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        // Order role snapshots and outbound updates together, but release the lock
792        // before waiting for ACKs so existing concurrent catalog RPCs still work.
793        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    /// Snapshot the roots served by this module's routable endpoint.
883    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    /// Register this module's full scope set with the daemon (`scope.sync`).
935    ///
936    /// Owners can set [`ScopeRecord::workdir`] and [`ScopeRecord::project_id`] with
937    /// the record builders after discovering `scope-workdir/v1`. These fields
938    /// attribute the session and grant no authority.
939    ///
940    /// The owner is this module; nothing in the request names it. `scopes` is
941    /// the whole set: a live scope left out ends. `generation` must be larger
942    /// than the last one the daemon accepted from this owner's sync authority,
943    /// or the sync is refused with `scope_sync_stale`.
944    ///
945    /// A refusal of the whole sync comes back as [`ScopeCallError::Refused`]
946    /// carrying the daemon's code (see `subc_protocol::error_codes`, e.g.
947    /// `SCOPE_SYNC_STALE`, `SCOPE_SYNC_NOT_AUTHORITY`), and nothing changed.
948    /// Only a module the daemon itself launched can hold sync authority.
949    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    /// Apply a delta to this module's scope set (`scope.apply`).
980    ///
981    /// This connection must first have established sync authority through an
982    /// accepted [`Self::scope_sync`]. `generation` shares the full-sync sequence
983    /// and must exceed the last accepted generation. Unnamed scopes stay live;
984    /// `end` ends only the named ref at the named epoch.
985    ///
986    /// Whole-call refusals return [`ScopeCallError::Refused`] without changing
987    /// the set or generation. Per-record refusals and `not_live` ends remain in
988    /// the reply. Without `scope.apply` in HELLO_ACK, nothing is sent.
989    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    /// Read one scope's current state (`scope.describe`). Any registered
1027    /// module may read any owner's scope.
1028    ///
1029    /// An unknown ref is not an error: the daemon answers it with status
1030    /// `not_live`. `owner_synced` says whether the owner has synced since this
1031    /// daemon started (if so, the scope is gone), and `owner_configured` whether
1032    /// the owner is a module the daemon supervises (if not, it never will sync).
1033    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    /// Ask the operator to authorise one in-flight, unchanged write.
1072    ///
1073    /// Every error means the module must refuse the write. `Ok(())` authorises
1074    /// only the write this call was made for; it must never be cached or reused.
1075    /// The daemon checks the summary and whether this module may ask for the
1076    /// caller's route. No failure is retried.
1077    ///
1078    /// A consumer call that may trigger confirmation must set
1079    /// [`CallOptions::timeout`] to at least 300 seconds. This helper waits up to
1080    /// 290 seconds, including egress backpressure, and dropping it withdraws an
1081    /// accepted request.
1082    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    /// Ask the operator to authorise one in-flight, unchanged write for a named
1092    /// management operation.
1093    ///
1094    /// This sends the same `operator.confirm` request as [`Self::confirm_operator`],
1095    /// with `kind` set to `"operation"` and `operation` set to the given name.
1096    /// It shares the same deadline, withdrawal-on-drop and error mapping: every
1097    /// error means the module must refuse the write, and `Ok(())` authorises
1098    /// only the write this call was made for; it must never be cached or reused.
1099    ///
1100    /// A later daemon may answer without a prompt only when the name is listed
1101    /// in this module's manifest `confirm_operations`; the daemon decides.
1102    /// Naming an operation the module did not declare still prompts; it is not
1103    /// refused.
1104    /// An empty name is refused locally as
1105    /// [`OperatorConfirmError::OperationInvalid`] without sending anything.
1106    ///
1107    /// A consumer call that may trigger confirmation must set
1108    /// [`CallOptions::timeout`] to at least 300 seconds. This helper waits up to
1109    /// 290 seconds, including egress backpressure, and dropping it withdraws an
1110    /// accepted request.
1111    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    /// Ask the operator to authorise pairing or enrolling a device or credential.
1130    ///
1131    /// This sends the same `operator.confirm` request as [`Self::confirm_operator`],
1132    /// with `kind` set to `"enrollment"`. It shares the same deadline,
1133    /// withdrawal-on-drop and error mapping: every error means the module must
1134    /// refuse the enrollment, and `Ok(())` authorises only the enrollment this
1135    /// call was made for; it must never be cached or reused.
1136    ///
1137    /// The daemon never approves an enrollment without an operator prompt; it
1138    /// may still refuse one before prompting, as for any confirmation. A
1139    /// daemon built against subc-protocol before 0.33.5 ignores the kind and
1140    /// treats the request as [`Self::confirm_operator`] does.
1141    ///
1142    /// A consumer call that may trigger confirmation must set
1143    /// [`CallOptions::timeout`] to at least 300 seconds. This helper waits up to
1144    /// 290 seconds, including egress backpressure, and dropping it withdraws an
1145    /// accepted request.
1146    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        // Use the same absolute deadline for both capacity and the reply: a
1203        // slow writer must not extend the time a confirmation can remain live.
1204        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    /// Send one channel-0 control request and wait for its reply, through the
1294    /// same correlation table, writer and timeout as `catalog_update` and
1295    /// `live_roots`. The caller checks that the reply is the right variant.
1296    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    /// Emit an uncorrelated Push on a live route.
1336    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    /// Number of unknown or stale route frames silently dropped by endpoint validation.
1363    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        // Replies may arrive out of order. Apply their effects in send order,
1610        // including replies whose caller dropped its waiting future.
1611        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            // Dropping these senders wakes raw-frame waiters immediately.
1637            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                // The connection owns this task even if the future was polled
1711                // on another runtime or dropped from a plain thread. A full
1712                // egress buffer delays withdrawal; it must not discard it.
1713                let writer = self.writer.clone();
1714                self.runtime.spawn(async move {
1715                    let _ = writer.send(cancel).await;
1716                });
1717            }
1718        }
1719    }
1720}
1721
1722/// Failure to authorise a write through [`ModuleHandle::confirm_operator`],
1723/// [`ModuleHandle::confirm_operation`] or [`ModuleHandle::confirm_enrollment`].
1724/// Every variant requires the module to refuse the write, with one exception
1725/// described on [`OperatorConfirmError::PresenceUnsupportedPlatform`].
1726#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1727#[non_exhaustive]
1728pub enum OperatorConfirmError {
1729    Declined,
1730    /// The daemon did not ask because a recent decline is still in effect.
1731    /// Older daemons omit the remaining cooldown, so `retry_after_ms` may be absent.
1732    Backoff {
1733        retry_after_ms: Option<u64>,
1734    },
1735    /// The daemon could not get an answer from the operator: the prompt
1736    /// failed or timed out, the connection dropped, or the reply was unknown
1737    /// or malformed. A withdrawn prompt can instead come back as
1738    /// [`OperatorConfirmError::Declined`].
1739    PresenceUnavailable,
1740    /// The daemon has no operator prompt on this platform (today Linux), so
1741    /// it showed none. It answered `operator_presence_unavailable` with
1742    /// `detail.reason` `unsupported_platform`. Every other
1743    /// `operator_presence_unavailable` reply stays
1744    /// [`OperatorConfirmError::PresenceUnavailable`].
1745    ///
1746    /// Like every variant, this refuses the write by default. A module may
1747    /// treat it differently only where its owner has ruled that, on a platform
1748    /// without a prompt, a confirmation typed by a person in a local app
1749    /// counts, and the product says so. It must never treat a
1750    /// `PresenceUnavailable` that way.
1751    PresenceUnsupportedPlatform,
1752    SummaryInvalid,
1753    /// The operation name for [`ModuleHandle::confirm_operation`] was empty.
1754    /// Operation names have no lexical grammar in Rust; membership in the
1755    /// module's manifest `confirm_operations` is decided by the daemon, which
1756    /// prompts for any name it does not recognise. Only the empty string can
1757    /// never name an operation, so it is refused before sending.
1758    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/// Errors returned by [`ModuleHandle::catalog_update`], [`ModuleHandle::set_ready`]
1803/// and [`ModuleHandle::update_role_declarations`].
1804#[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/// Errors returned by [`ModuleHandle::scope_sync`], [`ModuleHandle::scope_apply`] and
1847/// [`ModuleHandle::scope_describe`].
1848///
1849/// Non-exhaustive so a later failure kind can be added without breaking
1850/// callers' matches. Match the variants you handle, and treat any other variant
1851/// as a call whose effect you cannot know: after `scope_sync` or `scope_apply`,
1852/// send a full `scope_sync` at a higher generation rather than assume the change
1853/// did or did not apply.
1854#[derive(Debug, Clone, PartialEq, Eq)]
1855#[non_exhaustive]
1856pub enum ScopeCallError {
1857    /// HELLO_ACK did not advertise the operation (or its required capability),
1858    /// so nothing was sent.
1859    NotSupported { op: &'static str },
1860    /// The daemon refused the request with a channel-0 Error frame. `code` is
1861    /// the daemon's code as sent, to compare against the constants in
1862    /// `subc_protocol::error_codes` (`SCOPE_SYNC_STALE`,
1863    /// `SCOPE_SYNC_NOT_AUTHORITY`, `SCOPE_LIVE_LIMIT_EXCEEDED`, ...).
1864    Refused { code: String, message: String },
1865    /// No reply arrived in time. The daemon may still have applied the change.
1866    Timeout,
1867    /// The connection closed before a reply arrived.
1868    ConnectionClosed,
1869    /// The reply could not be read, or was a reply to a different op.
1870    Protocol(String),
1871}
1872
1873impl ScopeCallError {
1874    /// The daemon's error code, when the daemon refused the request.
1875    pub fn code(&self) -> Option<&str> {
1876        match self {
1877            Self::Refused { code, .. } => Some(code),
1878            _ => None,
1879        }
1880    }
1881
1882    /// Convert an error from the pending-reply handling that scope calls share
1883    /// with `catalog_update`, which reports failures as `CatalogUpdateError`.
1884    /// For a daemon Error frame, keep the daemon's code and message whatever
1885    /// the code is.
1886    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            // The shared reply handling never returns this: whether the
1898            // daemon supports an op is checked before the request is sent.
1899            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/// Trait implemented by a module for its business logic. The serve functions in
1927/// this crate own all wire-protocol plumbing.
1928///
1929/// # Stopping cleanly: drains
1930///
1931/// Before the daemon stops a module (restart, reload, disable, swap, or its own
1932/// shutdown) it closes route admission, tells the module with
1933/// [`ModuleHandler::on_draining`], waits for the module's in-flight requests to
1934/// finish, and only then sends GOODBYE and closes the connection. The wait ends
1935/// at the drain deadline whether or not the work is done.
1936///
1937/// Requests the daemon forwarded are counted by the daemon itself. Work it
1938/// cannot see (a job a request started in the background, a batch being
1939/// flushed) holds the drain open only if the module says so. The module does
1940/// that with a counter it reports in its health answer (a "health gauge"),
1941/// and a manifest entry telling the daemon that the counter means "busy": a
1942/// `Busy` self-signal anchored to those health gauges. Declare it, and report those
1943/// gauges in [`ModuleHandler::health`]'s `metrics` above zero until the work
1944/// has finished. During a drain the daemon probes `health` and waits until
1945/// every declared gauge reads 0 (or the deadline passes); a declared gauge
1946/// missing from the report counts as busy. The manifest entry, as built by the
1947/// `echo-module` example in this crate:
1948///
1949/// ```
1950/// use subc_protocol::manifest::{
1951///     ModuleManifest, SelfSignalDeclaration, SelfSignalEffect, SelfSignalKind, SignalAnchor,
1952/// };
1953///
1954/// let manifest = ModuleManifest::builder("my-module", "1.0.0")
1955///     .self_signals(Some(vec![SelfSignalDeclaration {
1956///         name: "background_work".to_string(),
1957///         kind: SelfSignalKind::Busy,
1958///         effect: SelfSignalEffect::Observe,
1959///         anchored_to: SignalAnchor::HealthGauges {
1960///             gauges: vec!["background_jobs".to_string()],
1961///         },
1962///         cadence: None,
1963///         domain: None,
1964///         note: None,
1965///     }]))
1966///     .build();
1967/// # let _ = manifest;
1968/// ```
1969///
1970/// and `health` then reports `{"background_jobs": <count>}` in `metrics`. Count
1971/// only work whose result would still be delivered if it finished during the
1972/// drain; see [`SelfSignalDeclaration::kind`](subc_protocol::manifest::SelfSignalDeclaration::kind).
1973#[async_trait]
1974pub trait ModuleHandler: Send + Sync + 'static {
1975    /// Handle a data-plane request on a route channel. Return a unary response, a
1976    /// typed error, or stream interim events via [`RequestCtx::emit`] and return
1977    /// [`HandlerOutcome::Streamed`]. Each request runs in its own task so one slow
1978    /// handler cannot head-of-line-block another route.
1979    async fn handle(&self, ctx: RequestCtx, body: Vec<u8>) -> HandlerOutcome;
1980
1981    /// Called once after HELLO_ACK so the module can inspect the ack body for
1982    /// negotiated capabilities and any storage descriptor supplied by the daemon.
1983    async fn on_hello_ack(&self, _ack: &ModuleHelloAckBody) {}
1984
1985    /// Extra daemon-to-module operations served on channel 0, such as `consent/v1`.
1986    /// Read and validated once before HELLO: names must be nonempty ASCII names
1987    /// using letters, digits, `.`, `_`, `-` or `/`, with no empty segments.
1988    /// Duplicates and SDK-owned `health.check`, `config.review` and `route.bind`
1989    /// are refused with [`SubcModuleError::InvalidControlOp`] before advertising.
1990    fn control_ops(&self) -> Vec<String> {
1991        Vec::new()
1992    }
1993
1994    /// Handle a declared control op with its entire decoded JSON request body.
1995    /// The control name is the body's `op` string; for a protocol-tagged request
1996    /// with no `op`, such as `consent/v1`, it is the body's `protocol` string.
1997    /// Return a JSON RESPONSE body or an [`ErrorBody`] carrying a wire error code
1998    /// and message. Runs off the reader, independently of routes, health and
1999    /// config review, with at most 16 concurrent calls per connection and no
2000    /// queue; overload returns `resource_exhausted`. There is no SDK time limit.
2001    ///
2002    /// CANCEL for this request's correlation, or disconnect, signals `cancel`.
2003    /// A reply produced after cancellation is discarded. Cooperate with the
2004    /// signal to release resources promptly; a cancelled call still holds its
2005    /// slot until it returns, and connection teardown eventually aborts it.
2006    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    /// Opt in once per connection. The SDK advertises `config.review`, declares
2019    /// these locations, and fetches immutable views before calling `config_apply`.
2020    /// Returning `None` leaves the existing module wire and file reader unchanged.
2021    fn config_declaration(&self) -> Option<config::ConfigDeclareRequest> {
2022        None
2023    }
2024
2025    /// Pure review of supplied snapshots and base. Do not read mutable files,
2026    /// environment, network or secrets here. Runs off the connection reader.
2027    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    /// Atomically apply a complete view, or leave the previous view intact and
2042    /// return secret-free NACK reasons. Readiness is included in a successful
2043    /// return. Runs off the reader; health and drain hooks remain independent.
2044    async fn config_apply(&self, _view: config::ConfigView) -> Result<(), Vec<String>> {
2045        Err(vec!["module has no config apply implementation".into()])
2046    }
2047
2048    /// Use the module's existing file reader. Called only for an opted-in module
2049    /// whose HELLO_ACK lacks `config.gate`, never after a gate refusal.
2050    async fn config_files(&self) {}
2051
2052    /// Observe wire status and refusals without ending the serving connection.
2053    async fn on_config_state(&self, _state: config::ConfigState) {}
2054
2055    /// Observe transport, malformed-reply and other config errors. These never
2056    /// authorize a file fallback or end the module connection.
2057    async fn on_config_error(&self, error: config::ConfigError) {
2058        tracing::warn!(%error, "module configuration request failed");
2059    }
2060
2061    /// Decide a route.bind. This hook is decision-only and must not emit route traffic.
2062    async fn on_bind(&self, _req: &RouteBindRequest) -> BindDecision {
2063        BindDecision::accept()
2064    }
2065
2066    /// Called after an accepted bind ACK is queued and the handle is installed.
2067    async fn on_bound(&self, _handle: &RouteHandle) {}
2068
2069    /// Return cheap in-memory health for the module.
2070    ///
2071    /// The default reports `Ok` with the detail "no health implementation;
2072    /// inherited default". The detail lets an operator reading
2073    /// `ck health <module>` tell "measured, nothing wrong" from "nobody
2074    /// measured", but the daemon decides on the status alone and never parses
2075    /// the detail, so to the daemon the default looks like a module that checked
2076    /// itself and found nothing wrong. It stays a default because health is
2077    /// optional: a module that advertises no health capability is never probed,
2078    /// so the value is never read. A module that does advertise health and
2079    /// keeps this default can report no fault beyond the serve helper's own
2080    /// saturation check.
2081    ///
2082    /// The serve helper calls this when the daemon sends `health.check`, on a
2083    /// task of its own rather than in a handler-slot pool, so a health check
2084    /// never waits behind the requests it reports on. It then folds in
2085    /// dispatch saturation: if every slot of a pool is in use and a request
2086    /// has waited more than two seconds for one, an `Ok` reply becomes
2087    /// `Degraded`, and the pool's slot count and oldest wait are prepended to
2088    /// `detail` (naming the pool when the module declared a long-held pool in
2089    /// [`ModuleHandler::request_pools`]). A `Degraded` or `Failing` status,
2090    /// the module's own detail and its metrics are kept.
2091    ///
2092    /// An implementation must not block: no blocking lock, no disk access and
2093    /// no subprocess on this path. Derive the status from signals the dispatch
2094    /// path already records in memory, such as a monotonic heartbeat or the age
2095    /// of the oldest queued item. A health reply that waits on a slow shared
2096    /// resource stalls under exactly the conditions it is meant to report,
2097    /// because that resource is what degrades first.
2098    async fn health(&self) -> HealthReport {
2099        // Say that nobody measured, rather than that everything is fine.
2100        //
2101        // The status stays Ok because a module advertising no health capability
2102        // is never probed, and one that advertises health but has nothing to
2103        // report is not unhealthy. What changes is that the report identifies
2104        // itself as the inherited default, so an operator reading
2105        // `ck health <module>` can tell "measured, nothing wrong" from "nobody
2106        // wrote a health path" -- which were previously the same bytes.
2107        //
2108        // `detail` is carried verbatim by the daemon and rendered for humans;
2109        // nothing parses it, so this is display-only and cannot change any
2110        // supervision decision.
2111        HealthReport {
2112            detail: Some("no health implementation; inherited default".to_string()),
2113            ..HealthReport::ok()
2114        }
2115    }
2116
2117    /// A route was torn down, rejected, or abandoned before its bind ACK was queued.
2118    async fn on_route_gone(&self, _handle: &RouteHandle) {}
2119
2120    /// How this module's data requests share handler slots. Called once per
2121    /// connection, before the serve loop reads its first frame after HELLO_ACK.
2122    ///
2123    /// Each data request waits for a slot before [`ModuleHandler::handle`]
2124    /// runs and holds it until `handle` returns. The default is one pool of
2125    /// 64 slots for every request, waited for in arrival order. A module whose
2126    /// requests can be held for minutes should declare a long-held pool for
2127    /// them, so they cannot take every slot and leave short requests queued
2128    /// behind them where the daemon cannot see:
2129    ///
2130    /// ```
2131    /// use subc_client_rs::{RequestClass, RequestPools};
2132    ///
2133    /// fn request_pools() -> RequestPools {
2134    ///     RequestPools::new().with_long_held(16, |body| {
2135    ///         if body.starts_with(br#"{"op":"research.run""#) {
2136    ///             RequestClass::long_held().with_op("research.run")
2137    ///         } else {
2138    ///             RequestClass::default_pool()
2139    ///         }
2140    ///     })
2141    /// }
2142    /// # let _ = request_pools();
2143    /// ```
2144    ///
2145    /// A request that waits two seconds for a slot is logged once at WARN
2146    /// while it is still waiting. While the connection is open, a request
2147    /// cancelled while waiting is answered `cancelled` at once; when the
2148    /// connection ends, waiting requests end without a reply, as before.
2149    /// [`ModuleHandle::request_pool_snapshots`]
2150    /// reports each pool's figures. Health checks never use a pool.
2151    fn request_pools(&self) -> RequestPools {
2152        RequestPools::new()
2153    }
2154
2155    /// The daemon has started draining this module: it will stop it for
2156    /// `reason` (a restart, reload, disable, or the daemon's own shutdown), and
2157    /// has already stopped admitting new routes to it. Stop taking new work
2158    /// here and finish or hand off what is in flight; see the trait docs for
2159    /// how to keep the drain open while background work finishes.
2160    ///
2161    /// `deadline` is the wall-clock time by which the module must be done. It
2162    /// is "no later than", never a grant of that much time: the daemon enforces
2163    /// its own ceiling on a monotonic clock and tears the connection down when
2164    /// that runs out, and after the host sleeps the ceiling can fall before
2165    /// this wall-clock time does. Aim to finish early.
2166    ///
2167    /// Called once for each drain notice the daemon sends, on its own task, so
2168    /// a slow hook never holds up pings, requests, or the GOODBYE that ends the
2169    /// drain. It is started before that GOODBYE is handled (and before
2170    /// [`ModuleHandler::on_connection_end`]). Connection teardown aborts hooks
2171    /// that have not finished within the drain budget.
2172    async fn on_draining(&self, _reason: RouteCloseReason, _deadline: SystemTime) {}
2173
2174    /// The connection ended orderly: a daemon GOODBYE is a planned stop, EOF
2175    /// or Reset means the daemon went away without one, and `Closed` is a
2176    /// module stop. Called once, after request tasks have finished or been
2177    /// cancelled. A module that wants a different exit code for an unannounced
2178    /// end can decide here. Not called for handler or protocol failures. A
2179    /// later, unexpected writer failure can still make serving return an error.
2180    async fn on_connection_end(&self, _end: ConnectionEnd) {}
2181}
2182
2183/// How a registered module's daemon connection ended. After the handshake, EOF
2184/// and socket disconnects are orderly ends on every platform: serving calls
2185/// `on_connection_end` and returns `Ok(())`. Handshake, handler, protocol and
2186/// other transport failures return errors.
2187#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2188#[non_exhaustive]
2189pub enum ConnectionEnd {
2190    /// The daemon sent GOODBYE on channel 0: a planned stop.
2191    Goodbye,
2192    /// The daemon closed the connection without GOODBYE.
2193    Eof,
2194    /// The socket was reset or aborted, or its writer disconnected. This is how
2195    /// Windows reports a daemon that died, which Unix reports as [`Self::Eof`].
2196    Reset,
2197    /// The module closed the connection itself, including a [`ModuleStopHandle`] stop.
2198    Closed,
2199}
2200
2201impl ConnectionEnd {
2202    /// Stable lower-case name for logs: `goodbye`, `eof`, `reset`, `closed`.
2203    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/// The terminal result of a module request handler.
2220#[derive(Debug, Clone, PartialEq)]
2221pub enum HandlerOutcome {
2222    /// Send a Response frame carrying these bytes.
2223    Response(Vec<u8>),
2224    /// Send an Error frame carrying an [`ErrorBody`] with this code and message.
2225    Error { code: String, message: String },
2226    /// Send an Error frame with stable machine-readable detail.
2227    ErrorWithDetail {
2228        code: String,
2229        message: String,
2230        detail: serde_json::Value,
2231    },
2232    /// The handler emitted stream data with [`RequestCtx::emit`]; the serve code
2233    /// sends the StreamEnd terminal frame.
2234    Streamed,
2235}
2236
2237/// Per-request context. Retains the full route handle and correlation id, provides
2238/// interim stream emission, and exposes a cancellation signal.
2239#[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    /// Clone the connection's control handle, for readiness and other module RPCs.
2254    pub fn module_handle(&self) -> ModuleHandle {
2255        self.module_handle.clone()
2256    }
2257
2258    /// Decodes a framed request only when ingress carried `FLAG_BINARY`.
2259    /// Call this only for management operations that declared `operation_payload`.
2260    /// Return a malformed body's named error as a refusal before doing any work;
2261    /// the serve helper deliberately leaves that policy to the handler.
2262    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    /// Full route handle retained from ingress.
2273    pub fn route_handle(&self) -> RouteHandle {
2274        self.handle
2275    }
2276
2277    /// Correlation id for this request.
2278    pub fn corr(&self) -> u64 {
2279        self.corr
2280    }
2281
2282    /// Declare this request's terminal [`HandlerOutcome::Response`] as raw bytes,
2283    /// not JSON, by setting `FLAG_BINARY` on its frame.
2284    ///
2285    /// Mark a reply only when the operation's contract defines a raw-byte reply,
2286    /// never for JSON contracts such as tool results or JSON management replies.
2287    /// The body is sent unchanged either way; the flag only declares that it is
2288    /// not JSON, and the daemon forwards it as is. The delivered frame is still
2289    /// bounded by [`subc_protocol::MAX_DELIVERED_FRAME_LEN`], including its header.
2290    ///
2291    /// All clones of this request's context share the mark; other requests do not.
2292    /// It has no effect on errors, interim stream frames, or `Streamed` outcomes.
2293    pub fn mark_binary_reply(&self) {
2294        self.binary_reply.store(true, Ordering::Relaxed);
2295    }
2296
2297    /// Emit an interim StreamData frame on this request's `(channel, corr)`. Once
2298    /// the request is cancelled or its route is gone, late emits are dropped.
2299    pub async fn emit(&self, body: Vec<u8>) -> Result<(), SubcModuleError> {
2300        self.emit_with_admission(body, None).await
2301    }
2302
2303    /// Emit StreamData with an explicit admission class. `None` means NORMAL.
2304    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    /// Completes when the other side sends Cancel for this request or the route
2322    /// is torn down.
2323    pub fn cancelled(&self) -> WaitForCancellationFuture<'_> {
2324        self.cancelled.cancelled()
2325    }
2326
2327    /// Return a cloneable cancellation token for code that prefers token polling.
2328    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
2354/// Adds one to `counter` and returns the value it held before, or `None` once
2355/// the counter is at `u64::MAX`. Written as a compare-exchange loop rather than
2356/// with `fetch_update` (deprecated in Rust 1.99) or its replacement
2357/// `try_update` (absent before 1.99), so it builds on both toolchains.
2358fn 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/// Route-bind request delivered on channel 0.
2370///
2371/// `#[non_exhaustive]` so it can gain fields in a later release without
2372/// breaking the handlers that read it. The SDK builds it from the daemon's
2373/// bind; code outside this crate (a module's own tests of its `on_bind`)
2374/// builds one with [`RouteBindRequest::new`] and the `with_*` setters.
2375#[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    /// Consumer-declared reverse-request families and provider-contract
2383    /// capabilities for this bind. For example, `tool-result/v1` declares that a
2384    /// consumer understands the tool-provider content result format. This is an
2385    /// unverified declaration, not a privilege grant; providers treat an absent
2386    /// field as no declared capability. Known MCP method-family values today
2387    /// are "elicitation", "sampling", and "roots".
2388    pub consumer_capabilities: Option<Vec<String>>,
2389    /// The versions of provider roles the consumer declared it speaks on this
2390    /// route, role name to version (`{"tool-provider": "v1"}`), as the daemon
2391    /// forwarded them. A declaration, not a verified privilege: use it to pick
2392    /// which version of a role's wire shape to speak. `None` means the consumer
2393    /// declared none (a legacy consumer, or a daemon that predates the field);
2394    /// it is never an empty map.
2395    pub role_versions: Option<std::collections::BTreeMap<String, String>>,
2396    /// Opaque admission facts relayed by subc from its configured carrier.
2397    pub admission_facts: Option<serde_json::Value>,
2398    /// The daemon's stamp of the scope the route was admitted under (owner,
2399    /// ref, epoch, kind, attributes), copied from the bind unchanged. It is
2400    /// the daemon's, never the opener's. `attributes.on_behalf_of_agent` is
2401    /// attribution only, never authority, consent or access to per-agent handles.
2402    /// A target must declare `scope-on-behalf-of/v1` to receive that field. The stamp
2403    /// is fixed for the route's life: a change that revokes authority closes
2404    /// the route. `None` means the route was opened without a scope, or by a
2405    /// daemon that predates scopes.
2406    pub scope: Option<ScopeStamp>,
2407    /// The daemon's call mode, or the mode derived from `scope` when an older
2408    /// daemon omits it. Providers must refuse [`CallMode::Unknown`].
2409    pub call_mode: CallMode,
2410    /// The daemon's facts about the connection that opened this route, read
2411    /// from the same bind. Like the scope stamp, they are the daemon's, never
2412    /// the opener's.
2413    ///
2414    /// - `observed_peer` is sent only when this module's manifest lists
2415    ///   `observed-peer/v1` in `capabilities.provides`. It is then always
2416    ///   present, possibly with status `unobserved`; only an `observed` status
2417    ///   carries the peer's identity.
2418    /// - `operator_app` is sent only when the manifest lists `operator-app/v1`,
2419    ///   the daemon's operator-app policy for this platform is switched on,
2420    ///   and the daemon recognised the connection as an operator app when it
2421    ///   was made. It records that recognition at connection time. It is not
2422    ///   authority: a write on the person's behalf still asks the daemon with
2423    ///   `operator.confirm`. Released daemons switch this policy off, so they
2424    ///   never send it yet.
2425    ///
2426    /// - `caller` is sent only for `caller-attestation/v1`. Automatic provider
2427    ///   permission grants require a well-formed caller with claim `own` and `first_party: true`.
2428    ///   An absent or incomplete caller establishes no first-party mark.
2429    ///
2430    /// - `peer_build` is sent only for `peer-build/v1`, when the opener is
2431    ///   `reserved:callosum` and its phone build claim was exactly `production`.
2432    ///   Otherwise it is absent; the opener's raw `build_class` is never relayed.
2433    ///
2434    /// The peer keys decode together. If they don't decode, the bind still
2435    /// reaches [`ModuleHandler::on_bind`] with all absent and a warning is
2436    /// logged, so a handler that admits only on `operator_app` refuses it.
2437    pub peer: subc_protocol::peer::RouteBindPeer,
2438}
2439
2440impl RouteBindRequest {
2441    /// A bind with the members every bind has and every optional one absent:
2442    /// no principal, no consumer capabilities, no role versions, no admission
2443    /// facts and no scope. The call mode is classic. Set fields with the
2444    /// `with_*` methods.
2445    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    /// Set [`Self::peer`] to synthetic daemon facts, for testing a handler.
2461    /// It checks nothing: a real bind's facts come only from the daemon.
2462    pub fn with_peer(mut self, peer: subc_protocol::peer::RouteBindPeer) -> Self {
2463        self.peer = peer;
2464        self
2465    }
2466
2467    /// The daemon's attested phone build fact, present only for `peer-build/v1`.
2468    /// A supporting daemon sends only `production`, otherwise the key is absent.
2469    pub fn peer_build(&self) -> Option<&str> {
2470        self.peer.peer_build.as_deref()
2471    }
2472
2473    /// Set [`Self::principal`].
2474    pub fn with_principal(mut self, principal: Principal) -> Self {
2475        self.principal = Some(principal);
2476        self
2477    }
2478
2479    /// Set [`Self::consumer_capabilities`].
2480    pub fn with_consumer_capabilities(mut self, consumer_capabilities: Vec<String>) -> Self {
2481        self.consumer_capabilities = Some(consumer_capabilities);
2482        self
2483    }
2484
2485    /// Set [`Self::role_versions`].
2486    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    /// Set [`Self::admission_facts`].
2495    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    /// Set [`Self::scope`] and derive its call mode. To override the derived
2501    /// mode, call [`Self::with_call_mode`] afterwards.
2502    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    /// Set [`Self::call_mode`], overriding the mode derived from the scope.
2509    pub fn with_call_mode(mut self, call_mode: CallMode) -> Self {
2510        self.call_mode = call_mode;
2511        self
2512    }
2513}
2514
2515/// Decision returned by [`ModuleHandler::on_bind`].
2516#[derive(Debug, Clone)]
2517pub struct BindDecision {
2518    kind: BindDecisionKind,
2519}
2520
2521impl BindDecision {
2522    /// Accept the route.bind request.
2523    pub fn accept() -> Self {
2524        Self {
2525            kind: BindDecisionKind::Accept,
2526        }
2527    }
2528
2529    /// Reject the route.bind request with a typed Error frame.
2530    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    /// Reject the route.bind request with a typed Error frame whose `detail`
2541    /// carries the code's machine-readable fields, such as `bind_busy`'s
2542    /// `reason` and `retry_after_ms`. Pass a JSON object: a JSON `null` is
2543    /// dropped on the way, since an absent detail and a null one encode the
2544    /// same. The daemon relays the code, message and detail to the opener,
2545    /// so the detail must never hold secrets.
2546    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
2571/// Run a module to completion. Reads `--subc <connection-file>` from args, uses
2572/// `SUBC_MODULE_ID` when set by the process that launched the module, connects,
2573/// authenticates, sends HELLO, waits for HELLO_ACK, then serves frames until
2574/// GOODBYE, clean EOF or a socket disconnect. How it ended is passed to
2575/// [`ModuleHandler::on_connection_end`].
2576/// A validated inherited registration channel replaces TCP when available.
2577/// It is never reconnected; its end exits the process after the lifecycle hook
2578/// and teardown, so the supervisor can restart the module with a new channel.
2579pub 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/// A cooperative stop signal that can be created before connecting to the daemon.
2587/// Clones share the same, irreversible stop request. Await the serving future
2588/// after calling [`stop`](Self::stop); dropping it does not perform teardown.
2589#[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    /// Stop the handshake or stop admitting requests, drain accepted work, send
2600    /// GOODBYE and flush. The serving future completes the teardown.
2601    pub fn stop(&self) {
2602        self.token.cancel();
2603    }
2604}
2605
2606/// Configuration for a module's connection lifecycle. Existing `serve*`
2607/// functions use the defaults; use these builder methods to customize serving.
2608#[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    /// Set the writer drain budget (default: two seconds). A module stop also
2630    /// gives in-flight handlers up to this long to finish before sending
2631    /// GOODBYE, then gives the writer its own budget to flush. Other connection
2632    /// ends cancel handlers immediately. Work still running at a drain
2633    /// deadline is aborted.
2634    ///
2635    /// Keep the combined handler and writer waits below the daemon's per-module
2636    /// stop budget: the daemon caps it at 25 seconds, and a module may be
2637    /// configured with less. Leave room for lifecycle hooks as well.
2638    pub fn with_writer_drain_timeout(mut self, timeout: Duration) -> Self {
2639        self.writer_drain_timeout = timeout;
2640        self
2641    }
2642
2643    /// Install a stop handle created before calling `serve` or `serve_with`,
2644    /// so a stop also interrupts connection establishment and HELLO.
2645    pub fn with_stop_handle(mut self, handle: ModuleStopHandle) -> Self {
2646        self.stop_handle = handle;
2647        self
2648    }
2649
2650    /// Serve using the same launch arguments and environment as [`serve`].
2651    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    /// Serve with an explicit connection file and an unchanged manifest.
2664    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    /// Connect and register using the same launch inputs as [`Self::serve`],
2680    /// returning a cloneable handle and the future that keeps the module serving.
2681    ///
2682    /// Reads `--subc <connection-file>` (or `--subc=<connection-file>`) from argv
2683    /// and overrides the manifest's module id with `SUBC_MODULE_ID` when present.
2684    /// Uses this options value's stop handle and writer drain timeout. A requested
2685    /// stop before registration completes returns `Ok(None)`; this is an expected
2686    /// outcome, not a connection error.
2687    ///
2688    /// The returned serve future **must be awaited or spawned**. A module can give
2689    /// the returned handle to its handler's shared state before starting that future.
2690    /// Spawn the serve future before slow startup work or awaiting control RPCs:
2691    /// it reads their replies and answers health and stop.
2692    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    /// Connect with an explicit connection file and an unchanged manifest,
2706    /// returning a cloneable handle and the future that keeps the module serving.
2707    ///
2708    /// Uses this options value's stop handle and writer drain timeout. A requested
2709    /// stop before registration completes returns `Ok(None)`; this is an expected
2710    /// outcome, not a connection error.
2711    ///
2712    /// The returned serve future **must be awaited or spawned**. A module can give
2713    /// the returned handle to its handler's shared state before starting that future.
2714    /// Spawn the serve future before slow startup work or awaiting control RPCs:
2715    /// it reads their replies and answers health and stop.
2716    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
2726/// Connect and register using the same launch inputs as [`serve`], returning a
2727/// cloneable handle and the future that keeps the module serving.
2728///
2729/// Reads `--subc <connection-file>` (or `--subc=<connection-file>`) from argv
2730/// and overrides the manifest's module id with `SUBC_MODULE_ID` when present.
2731/// Authentication, the launch-secret pipe, HELLO and their errors are identical
2732/// to [`serve`]. Unlike [`serve_with_handle`], the caller need not duplicate
2733/// argument parsing or launch-environment handling.
2734///
2735/// The returned serve future **must be awaited or spawned**. A module can give
2736/// the returned handle to its handler's shared state before starting that future,
2737/// so the handler can call [`ModuleHandle::confirm_operator`] or
2738/// [`ModuleHandle::set_ready`]. Spawn the serve future before slow startup work
2739/// or awaiting control RPCs: it reads their replies and answers health and stop.
2740pub 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
2753/// Run a module with an explicit connection-file path. The manifest is sent as
2754/// provided; callers that need a nonstandard module id should set it before calling.
2755pub 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
2768/// Connect, register the module, and return a cloneable handle plus the future that
2769/// must be awaited or spawned to keep serving the connection.
2770pub 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        // A validated ACK means the daemon accepted the module, even while the
2840        // module's callback is pending. Keep that boundary when the writer wins.
2841        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        // A prefix registration is brokered, not another primary channel. Keep
2897        // its registration RPCs while refusing owner-only operations locally.
2898        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    // The callback can be cancelled by a writer failure, but a failure after
2906    // acceptance belongs to the serving lifecycle, including its teardown hook.
2907    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// Both real connections and the in-memory test stand-in run this lifecycle,
2951// including request cancellation, connection-end hooks and the writer drain.
2952#[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    // Before the caller gets the future (and before the serve loop reads its
2990    // first frame after HELLO_ACK), so the
2991    // handle's pool figures describe the pools the dispatcher will use.
2992    handle.install_dispatch_pools(handler.request_pools());
2993    Box::pin(async move {
2994        // Connection loss ends this serve future. Module serving retains no
2995        // reconnect task or in-flight reconnect gate; a supervisor that needs
2996        // recovery starts a fresh serve_with_handle invocation.
2997        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        // A failed terminal enqueue can win the select just before the writer
3015        // reports why it closed. Classify that same disconnect before calling
3016        // the connection-end hook, rather than exposing a scheduling race.
3017        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            // Keep routes live until accepted work has sent its terminal reply.
3029            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        // The module ended the connection itself: a stop, an internal close
3054        // or a module-side error. Close it in order, so the daemon reads a
3055        // FIN rather than a reset. When the daemon ended it (EOF, GOODBYE or
3056        // a reset) or the writer already failed, there is nothing to drain.
3057        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            // An inherited registration cannot be recreated. Finish the hook
3097            // and teardown before letting the supervisor restart the process.
3098            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            // EOF or GOODBYE can precede a failed flush, especially when a
3105            // daemon restart outlasts its drain budget. Once the daemon has
3106            // ended the connection, Windows RST and Unix BrokenPipe are
3107            // consequences of that orderly end, not independent failures.
3108            (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            // Clean EOF: the daemon closed the connection.
3164            Ok(None) => return Ok(ConnectionEnd::Eof),
3165            // A killed daemon can close with FIN on Unix and RST on Windows.
3166            // Both end serving and run the same connection-end teardown hook.
3167            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            // handle_frame returns false only for a channel-0 GOODBYE.
3182            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
3260/// Act on a one-way channel-0 command from the daemon. Never fails the
3261/// connection: a push this SDK cannot decode is most likely a newer daemon's
3262/// command, and ignoring it is what an older module did before this SDK
3263/// decoded any of them.
3264fn 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
3304/// Run `on_draining` on its own task, so a slow hook cannot stall the frame
3305/// reader. The returned receiver resolves once the hook has been polled for
3306/// the first time, i.e. has run up to its first await.
3307fn 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
3332/// Convert the wire reason into this crate's public [`RouteCloseReason`], via
3333/// its wire name so a reason this crate has no variant for arrives as
3334/// [`RouteCloseReason::Unknown`] rather than being dropped.
3335fn 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
3342/// The drain deadline as a wall-clock time. A value too large for this
3343/// platform's clock becomes "now": the deadline is a "no later than", so
3344/// reading it early is the safe direction.
3345fn 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    // The module's classifier picks the pool from the raw body before the
3383    // request takes a slot; the SDK passes the body on without interpreting it.
3384    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            // Cancelled while waiting: answered below at once, without a
3396            // slot, rather than after one frees.
3397            PermitWaitOutcome::Cancelled => None,
3398            PermitWaitOutcome::Closed => {
3399                // A closed dispatcher means connection teardown will release every route credit.
3400                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        // A slot and the cancellation can become ready together and the slot
3410        // is taken first, so check again before running the handler.
3411        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            // A route GOODBYE/rebind withdraws the reply destination. Dropping
3426            // that late terminal is intentional; an egress failure on a live
3427            // route is not. A panic remains fatal even if its route is gone.
3428            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        // Health must not queue behind the data work whose liveness it reports.
3469        // Registration and cancellation still use the same in-flight registry.
3470        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
3546/// Catch unwinds across every poll, including construction of the handler future.
3547/// Never expose the panic payload on the wire: it may contain request data.
3548async 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        // Keep the original priority: a control-plane reply stays passive.
3572        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    // A control request this SDK cannot decode (most likely a newer daemon's
3636    // field or operation) is refused on its own correlation id, and the
3637    // connection stays up. Returning the decode error would end the serve loop,
3638    // so one unknown field on one route.bind would stop the whole module, and
3639    // the next such bind after its respawn would stop it again.
3640    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            // Implicit-replace rule (wire spec 3.3.0): the daemon never rebinds a live
3676            // channel, but its route-gone GOODBYE to modules is best-effort, so a bind
3677            // can arrive for a channel this endpoint still believes installed. A
3678            // strictly higher epoch proves the daemon freed the old binding: tear the
3679            // stale install down locally and proceed. Equal or lower epoch is a
3680            // protocol violation the daemon cannot produce: reject the bind.
3681            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            // The peer keys sit beside the bind's members in the same body.
3711            // They decode as one value: if any is malformed all read as
3712            // absent, and the bind still goes to `on_bind`, which decides.
3713            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
3862/// Owned byte transport for a module connection, before or after authentication.
3863pub 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    // This socket carries the module's replies back to the daemon, so Nagle here
3905    // delays every response rather than every request -- the same cost on the
3906    // return leg. Both ends of the hop have to disable it for either to help.
3907    //
3908    // The result is deliberately dropped rather than logged: this crate takes no
3909    // logging dependency, and the only ways setting a socket option on a
3910    // just-connected stream fail leave the socket unusable, which the handshake on
3911    // the very next line reports as a typed Auth error. Swallowing it here would
3912    // hide nothing that stays hidden.
3913    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
3992/// [`finish_writer`] for a connection the module ends itself: once the writer
3993/// has flushed and shut down the sending side, drain the reader as
3994/// [`drain_until_peer_closes`] describes. A writer that failed means the socket
3995/// is already broken, so there is nothing to drain.
3996async 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
4011/// Orderly close for a connection the module ends itself (a stop, an internal
4012/// close or a module-side error), called once the writer has flushed its last
4013/// frame and shut down the sending side.
4014///
4015/// Closing a TCP socket while received bytes are still unread makes the OS
4016/// send a reset (RST) instead of an orderly FIN. Linux and Windows do this;
4017/// where an OS does not, the drain below only waits for a close that comes
4018/// anyway. A daemon that receives the reset can fail its next read with
4019/// `ConnectionReset` and lose data it had not read yet, including the module's
4020/// GOODBYE, so a planned stop would look like a crash. Frames the daemon sent
4021/// after the module stopped reading (a PING, a request, its own GOODBYE) are
4022/// exactly such unread bytes. So keep reading and discarding until the daemon
4023/// closes its side, which it does once it reads the module's FIN.
4024///
4025/// `deadline` is the writer drain deadline, so a daemon that never closes
4026/// cannot hold the stop past the drain budget. Read errors end the drain: the
4027/// socket is already broken and nothing is left to protect.
4028async 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        // Every sender is gone, so nothing more will be written: shut down the
4072        // sending side so the daemon reads a FIN (EOF) right after the last
4073        // frame, typically the module's GOODBYE. The socket stays open for
4074        // reading, which `drain_until_peer_closes` relies on. When the daemon
4075        // ended the connection first, this sends the same FIN that dropping
4076        // the socket would. A failure here only means the socket is already
4077        // broken; whatever was flushed has been handed to the OS, so it is
4078        // not an undelivered-frame error.
4079        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    /// A module declared a malformed, duplicate or SDK-owned control operation.
4150    InvalidControlOp(String),
4151    /// A daemon reused an outstanding channel-0 request's correlation.
4152    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    /// A request handler panicked. Its payload is never sent to the daemon.
4182    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    /// The descriptor named for the launch nonce could not be read. HELLO is
4195    /// not sent without it, and the environment copy is not tried instead.
4196    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        // An older daemon sends nothing, and nothing is invented in its place.
4430        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            // A module-provided capability is not the daemon's op advertisement.
4777            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    /// Each scope op is gated on its own `subc_ops` entry: a daemon that
4990    /// lists one but not the other gets only the one it listed, and a gated
4991    /// call sends nothing.
4992    #[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    /// A reply carrying another op's body is not taken as an answer.
5184    #[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    /// Every Error-frame code reaches the caller as sent, including codes the
5240    /// reply handling shared with `catalog_update` sorts into its own
5241    /// `CatalogUpdateError` variants (`not_registered`).
5242    #[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    /// A route.bind whose scope stamp carries a field this SDK does not know
5277    /// (a newer daemon's attribute) must be refused on its own correlation id,
5278    /// and the module must keep serving: the next control request is answered.
5279    #[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        // A well-formed bind from this SDK's own types, then one scope
5286        // attribute this SDK does not know, so that is the only defect.
5287        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        // Prove the refusal is about the unknown attribute, not some other
5319        // defect in this fixture.
5320        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        // Assert the PROPERTIES that matter rather than byte-equality with
5361        // HealthReport::ok(). Comparing against the constructor made this test a
5362        // restatement of the implementation: it reddened on any change to the
5363        // default without saying which property had broken.
5364        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        // A module that never implemented health is not UNHEALTHY -- the daemon
5369        // must not escalate on it.
5370        assert_eq!(status, HealthStatus::Ok);
5371        // ...but the report must SAY that nobody measured, so an operator can
5372        // tell it from a real all-clear. Substring rather than exact text: the
5373        // wording is for humans and nothing parses it.
5374        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        // A brief burst is not dispatch impairment, even with no slot free.
5509        assert_eq!(harness.health(899).await, own_report);
5510        // Advance the real dispatch stamp's monotonic clock, not a test-only
5511        // health gauge. Keeping handlers blocked proves the transport isolation.
5512        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    /// A request cancelled while it waits for a handler slot is answered
5583    /// `cancelled` at once: it does not wait for a slot to free just to say
5584    /// so, it never takes one, and its handler never runs.
5585    #[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        // The first request still holds the only slot, so the answer below
5661        // cannot have come from a slot freeing.
5662        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        // A plain rejection keeps its detail-free bytes.
5936        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    // Wire spec 3.3.0: a bind on an installed channel with a strictly higher epoch
6006    // replaces the stale install (the daemon freed that binding; its route-gone
6007    // GOODBYE is best-effort and can be dropped), firing the replaced install's
6008    // route-gone teardown. Equal-or-lower epoch is a protocol violation: rejected,
6009    // installed route untouched.
6010    #[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        // Install epoch 4 on channel 8.
6022        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        // Same epoch: rejected, install untouched, no teardown fired.
6038        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        // Lower epoch: same rejection shape.
6058        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        // Strictly higher epoch: implicit replace — stale install torn down
6074        // (route-gone fired exactly once), new epoch installed and bound.
6075        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/// How a served module ends when its connection closes, driven against a stand-in
6109/// daemon on a framed in-memory connection with the real writer task and drain.
6110#[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    /// How the test handler treats the one request it is given.
6120    #[derive(Clone, Copy)]
6121    enum Hold {
6122        /// Hold the request open until it is cancelled, then answer.
6123        UntilCancelled,
6124        /// Hold the request open forever, whatever happens.
6125        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    /// Serve `handler` on the shared stand-in and hand its framed connection to the test.
6153    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    /// Bind route 7/1 and send one data request on it, returning once the
6163    /// handler holds it.
6164    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        // Well inside the writer's drain limit: the handler answered its
6244        // cancellation, so nothing had to be aborted.
6245        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    /// Records every `on_connection_end` call, so a test can assert both the
6308    /// cause and that it was reported exactly once.
6309    #[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    /// What a drain-recording handler saw, in the order it saw it.
6354    #[derive(Debug, Clone, PartialEq)]
6355    enum Seen {
6356        Draining(RouteCloseReason, SystemTime),
6357        End(ConnectionEnd),
6358    }
6359
6360    /// Records drain notices and the connection end. With `park` set, the
6361    /// drain hook never returns after recording, to stand for a slow hook.
6362    #[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    /// Send a channel-0 PING and require the PONG, proving the frame reader
6402    /// is still serving.
6403    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    /// The daemon sends `module.draining` and, once the drain settles, GOODBYE;
6419    /// with nothing to wait for, both can land in one read. The hook runs on its
6420    /// own task, and must still be called before the GOODBYE is acted on.
6421    #[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        // Any fixed value works; this one (2100-01-01T00:00:00Z) is far enough
6426        // ahead to be plainly a future deadline.
6427        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    /// A drain lasts until the daemon's deadline, and the daemon keeps pinging
6455    /// through it; a hook still busy must not stop the module answering.
6456    #[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    /// A channel-0 push this SDK cannot decode (a newer daemon's command, or a
6483    /// malformed body) is ignored: no hook is called and the connection keeps
6484    /// serving.
6485    #[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    /// The wire bytes a detail-carrying module error serializes to are pinned
6537    /// here because subc-mcp and route consumers parse them; the shape predates
6538    /// ErrorBody.detail and must not drift now that ErrorBody subsumes it.
6539    #[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    /// A detail-less body serializes byte-identically to the pre-detail wire:
6555    /// deserializing the old two-field shape and re-serializing adds nothing.
6556    #[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
6565// A reserved module may scrub its launch nonce before it opens a daemon
6566// connection. The retained copy exists only for encoding that module's HELLO.
6567static RETAINED_LAUNCH_NONCE: std::sync::OnceLock<String> = std::sync::OnceLock::new();
6568
6569/// Retain a reserved module's launch nonce for its HELLO after the module has
6570/// scrubbed the nonce from the process environment.
6571pub 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
6581/// The cached launch-nonce source (`fd`, `pipe` or `env`), or `None` when no
6582/// nonce is available. The SDK records this in the registration message's
6583/// `manifest.provenance.launch_nonce_source`; the daemon stores that declaration
6584/// for `ck provenance` to display. A module constructing that record can use:
6585/// `.with_launch_nonce_source(subc_client_rs::launch_nonce_source())`.
6586pub 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
6593/// Fill in `launch_nonce_source` on a module's declared provenance, so
6594/// `ck provenance` can tell a module reading the pipe from one still reading
6595/// the environment variable. Only when the module declared provenance and left the field
6596/// unset. A registration channel supplies authority without sending a nonce,
6597/// but an unstamped launch may still supply a legacy nonce whose source is
6598/// diagnostic. Otherwise the nonce HELLO carries must be the one the accessor
6599/// read: a module-retained nonce may have come from somewhere else.
6600fn 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        // A re-export may send the owner's legacy nonce, but cannot claim the
6609        // launched module's nonce provenance.
6610        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}