Skip to main content

subc_client_rs/
registration.rs

1//! One process owner for registration and claim minting. No synchronous mutex is
2//! held over I/O. The async pool lock serializes consumer creation, not minting
3//! or the registration reader, so a HELLO/claim reply can always make progress.
4
5use super::*;
6use consumer::{ConsumerError, ConsumerOptions, SubcConsumer};
7use std::sync::{OnceLock, Weak};
8use subc_os::registration_channel as os;
9use subc_protocol::claim::{
10    Claim, ClaimMintReply, ClaimMintRequest, ClaimPresentReply, ClaimPresentRequest, ClaimPurpose,
11    ClaimRateLimitedDetail,
12};
13
14static OWNER: OnceLock<Arc<dyn ClaimMinter>> = OnceLock::new();
15static OWNER_READY: tokio::sync::Notify = tokio::sync::Notify::const_new();
16static HELPER_BOUND: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
17static SUPERVISED: OnceLock<bool> = OnceLock::new();
18static CHANNEL_TAKEN: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
19static CHANNEL_ADOPTED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
20
21/// A custom module loop's channel-0 `claim.mint` RPC implementation.
22///
23/// Startup order is: call [`adopt_channel`], authenticate the returned stream,
24/// send the launched module's HELLO without `launch_nonce`, validate HELLO_ACK,
25/// call [`install_claim_minter`], then open consumers. If adoption returns `None`,
26/// use the legacy connection and launch-nonce path instead; do not install a minter.
27///
28/// Implement with [`crate::async_trait`]. Send each request on the adopted module
29/// connection and correlate its reply while continuing to read that connection.
30/// Validate the reply's type and operation, map daemon refusals to
31/// [`ClaimError::Refused`], and honor `claim_rate_limited` retry delays within a
32/// bounded budget. Return [`ClaimError::Unavailable`] when the connection closes;
33/// never reconnect the registration channel or fall back to nonce authentication.
34/// The SDK bounds each mint and ignores the reply's informational wall-clock expiry.
35///
36/// A module using this path must not pass
37/// [`CallOptions::consumer_identity`](crate::consumer::CallOptions::consumer_identity):
38/// a claim-bound connection refuses that override before sending it.
39#[async_trait]
40pub trait ClaimMinter: Send + Sync {
41    async fn mint(&self, request: ClaimMintRequest) -> Result<ClaimMintReply, ClaimError>;
42}
43
44/// Failure to adopt or install the process's registration owner.
45#[derive(Debug)]
46#[non_exhaustive]
47pub enum RegistrationError {
48    Channel(os::RegistrationChannelError),
49    Transport(io::Error),
50    NotAdopted,
51    AlreadyInstalled,
52}
53
54impl fmt::Display for RegistrationError {
55    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56        match self {
57            Self::Channel(error) => error.fmt(f),
58            Self::Transport(_) => f.write_str("could not open registration transport"),
59            Self::NotAdopted => f.write_str("registration channel has not been adopted"),
60            Self::AlreadyInstalled => f.write_str("registration owner already installed"),
61        }
62    }
63}
64
65impl Error for RegistrationError {
66    fn source(&self) -> Option<&(dyn Error + 'static)> {
67        match self {
68            Self::Channel(error) => Some(error),
69            Self::Transport(error) => Some(error),
70            _ => None,
71        }
72    }
73}
74
75/// Take the daemon's private registration stream for a custom module loop.
76///
77/// Call once at startup, before spawning children. In a Tokio runtime:
78/// adopt, authenticate, send HELLO without `launch_nonce`, validate HELLO_ACK,
79/// install the owner with [`install_claim_minter`], then open consumers.
80/// See [`ClaimMinter`] for the loop's RPC and connection-lifetime obligations.
81/// A second call, even after `None`, returns
82/// [`RegistrationError::Channel`] containing
83/// [`os::RegistrationChannelError::AlreadyTaken`].
84///
85/// `None` means no validated channel was handed to this process (for example,
86/// an older daemon or a non-daemon launch); keep the legacy nonce path then.
87pub fn adopt_channel() -> Result<Option<Box<dyn ModuleStream>>, RegistrationError> {
88    init_supervised();
89    take_channel_stream()
90}
91
92/// Install a custom loop's claim minter after HELLO_ACK and before opening consumers.
93///
94/// Refuses installation before channel adoption or after any owner was installed,
95/// including an owner installed by [`crate::serve`]. The process retains the minter;
96/// it must report a closed registration connection as unavailable. Installation
97/// cannot be undone and must never authorize reconnecting the registration channel.
98pub fn install_claim_minter(minter: Arc<dyn ClaimMinter>) -> Result<(), RegistrationError> {
99    if !CHANNEL_ADOPTED.load(Ordering::Acquire) {
100        return Err(RegistrationError::NotAdopted);
101    }
102    OWNER
103        .set(minter)
104        .map_err(|_| RegistrationError::AlreadyInstalled)?;
105    OWNER_READY.notify_waiters();
106    Ok(())
107}
108
109struct SdkClaimMinter(Weak<ModuleHandleShared>);
110
111#[async_trait]
112impl ClaimMinter for SdkClaimMinter {
113    async fn mint(&self, request: ClaimMintRequest) -> Result<ClaimMintReply, ClaimError> {
114        ModuleHandle {
115            shared: self.0.upgrade().ok_or(ClaimError::Unavailable)?,
116        }
117        .mint_claim_reply(request)
118        .await
119    }
120}
121
122#[derive(Default)]
123pub(crate) struct Session {
124    active: std::sync::atomic::AtomicBool,
125    pub(super) prefix_child: std::sync::atomic::AtomicBool,
126    pool: tokio::sync::Mutex<Vec<PoolEntry>>,
127}
128
129struct PoolEntry {
130    path: PathBuf,
131    options: ConsumerOptions,
132    local: bool,
133    consumer: Weak<SubcConsumer>,
134}
135
136/// Claim failures never permit continuing with an unbound connection. Debug and
137/// Display omit daemon-authored messages and bodies, which can contain secrets.
138#[derive(Debug)]
139#[non_exhaustive]
140pub enum ClaimError {
141    Unavailable,
142    Timeout,
143    Protocol,
144    Refused {
145        code: String,
146    },
147    Handoff,
148    /// Prefix children cannot open consumer connections in this SDK yet.
149    PrefixChildConsumer,
150}
151
152impl fmt::Display for ClaimError {
153    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
154        if matches!(self, Self::PrefixChildConsumer) {
155            f.write_str("prefix children have no consumer connections in this SDK yet")
156        } else {
157            f.write_str("claim authentication failed")
158        }
159    }
160}
161impl Error for ClaimError {}
162
163pub(crate) fn supervised() -> bool {
164    SUPERVISED.get().copied().unwrap_or(false)
165}
166
167pub(crate) fn adopt(module_id: &str) -> Result<bool, SubcModuleError> {
168    let supervised = init_supervised();
169    // The inherited channel belongs to the launched module, not every module
170    // exported by its process. Sharing a process does not grant other module ids
171    // the launched module's authority; they need separate registration authority.
172    Ok(supervised && is_launched_module(module_id)?)
173}
174
175fn init_supervised() -> bool {
176    *SUPERVISED.get_or_init(|| {
177        let supervised = os::supervised();
178        if let Some(reason) = os::registration_refusal() {
179            tracing::warn!(%reason, "registration channel not adopted");
180        }
181        supervised
182    })
183}
184
185pub(crate) fn is_launched_module(module_id: &str) -> Result<bool, SubcModuleError> {
186    Ok(module_id_from_env()?.is_none_or(|launched_id| launched_id == module_id))
187}
188
189pub(crate) fn take_stream() -> Result<Option<Box<dyn ModuleStream>>, SubcModuleError> {
190    if !supervised() {
191        return Ok(None);
192    }
193    match take_channel_stream() {
194        Err(RegistrationError::Channel(os::RegistrationChannelError::AlreadyTaken)) => {
195            let error = match module_id_from_env()? {
196                Some(module_id) => io::Error::other(format!(
197                    "launched module {module_id:?} is already serving on the registration channel"
198                )),
199                None => io::Error::other(os::RegistrationChannelError::AlreadyTaken),
200            };
201            Err(SubcModuleError::RegistrationChannel(error))
202        }
203        Err(RegistrationError::Transport(error)) => {
204            Err(SubcModuleError::RegistrationChannel(error))
205        }
206        result => {
207            result.map_err(|error| SubcModuleError::RegistrationChannel(io::Error::other(error)))
208        }
209    }
210}
211
212fn take_channel_stream() -> Result<Option<Box<dyn ModuleStream>>, RegistrationError> {
213    if CHANNEL_TAKEN.swap(true, Ordering::AcqRel) {
214        return Err(RegistrationError::Channel(
215            os::RegistrationChannelError::AlreadyTaken,
216        ));
217    }
218    let channel = os::take_registration_channel().map_err(RegistrationError::Channel)?;
219    let Some(channel) = channel else {
220        return Ok(None);
221    };
222    #[cfg(unix)]
223    let stream = {
224        let stream = channel.into_unix_stream();
225        stream
226            .set_nonblocking(true)
227            .map_err(RegistrationError::Transport)?;
228        tokio::net::UnixStream::from_std(stream).map_err(RegistrationError::Transport)?
229    };
230    #[cfg(windows)]
231    let stream = channel
232        .into_tokio_pipe_client()
233        .map_err(RegistrationError::Transport)?;
234    #[cfg(any(unix, windows))]
235    {
236        CHANNEL_ADOPTED.store(true, Ordering::Release);
237        Ok(Some(Box::new(stream)))
238    }
239    #[cfg(not(any(unix, windows)))]
240    {
241        let _ = channel;
242        Err(RegistrationError::Transport(io::Error::new(
243            io::ErrorKind::Unsupported,
244            "registration transport unsupported",
245        )))
246    }
247}
248
249pub(crate) fn install_owner(handle: &ModuleHandle) -> Result<(), SubcModuleError> {
250    handle
251        .shared
252        .registration
253        .active
254        .store(true, Ordering::Release);
255    install_claim_minter(Arc::new(SdkClaimMinter(Arc::downgrade(&handle.shared))))
256        .map_err(|error| SubcModuleError::RegistrationChannel(io::Error::other(error)))
257}
258
259pub(crate) async fn prefix_claim(module_id: &str) -> Result<Option<Claim>, ClaimError> {
260    let deadline = Instant::now() + CATALOG_UPDATE_TIMEOUT;
261    timeout_at(deadline, async {
262        let owner = loop {
263            // Register the waiter before checking OWNER so installation cannot
264            // race the transition to sleep.
265            let ready = OWNER_READY.notified();
266            tokio::pin!(ready);
267            ready.as_mut().enable();
268            if let Some(owner) = OWNER.get() {
269                break owner;
270            }
271            ready.await;
272        };
273        match mint_claim(
274            owner.as_ref(),
275            ClaimPurpose::Prefix {
276                module_id: module_id.to_owned(),
277            },
278        )
279        .await
280        {
281            Err(ClaimError::Refused { code }) if code == error_codes::CLAIM_PREFIX_REFUSED => {
282                Ok(None)
283            }
284            result => result.map(Some),
285        }
286    })
287    .await
288    .map_err(|_| ClaimError::Timeout)?
289}
290
291pub(crate) fn serve_claim_error(module_id: &str, error: ClaimError) -> SubcModuleError {
292    let code = match error {
293        ClaimError::Refused { code } => code,
294        ClaimError::Unavailable => "claim_unavailable".into(),
295        ClaimError::Timeout => "claim_timeout".into(),
296        _ => "claim_protocol".into(),
297    };
298    SubcModuleError::RegistrationChannel(io::Error::other(format!(
299        "prefix registration for module {module_id:?} failed: {code}"
300    )))
301}
302
303impl ModuleHandle {
304    /// Open or reuse a self-bound TCP consumer. The pool belongs to this spawn's
305    /// registration binding; keys compare the exact path and every option. It
306    /// holds only weak references: dropping the last Arc closes the connection.
307    /// Await or spawn the serve future before calling this method.
308    pub async fn consumer(
309        &self,
310        path: &Path,
311        options: ConsumerOptions,
312    ) -> Result<Arc<SubcConsumer>, ConsumerError> {
313        self.pooled_consumer(path, options, false).await
314    }
315
316    /// Like [`Self::consumer`], but local-only. Local and TCP connections never
317    /// share a pool entry, even when their connection file and options match.
318    pub async fn consumer_local(
319        &self,
320        path: &Path,
321        options: ConsumerOptions,
322    ) -> Result<Arc<SubcConsumer>, ConsumerError> {
323        self.pooled_consumer(path, options, true).await
324    }
325
326    async fn pooled_consumer(
327        &self,
328        path: &Path,
329        options: ConsumerOptions,
330        local: bool,
331    ) -> Result<Arc<SubcConsumer>, ConsumerError> {
332        if self
333            .shared
334            .registration
335            .prefix_child
336            .load(Ordering::Acquire)
337        {
338            return Err(ConsumerError::claim(ClaimError::PrefixChildConsumer));
339        }
340        if !self.shared.registration.active.load(Ordering::Acquire)
341            || self.shared.close_token.is_cancelled()
342        {
343            return Err(ConsumerError::claim(ClaimError::Unavailable));
344        }
345        let mut pool = self.shared.registration.pool.lock().await;
346        pool.retain(|entry| {
347            entry
348                .consumer
349                .upgrade()
350                .is_some_and(|consumer| consumer.pool_reusable())
351        });
352        if let Some(consumer) = pool
353            .iter()
354            .find(|entry| entry.path == path && entry.local == local && entry.options == options)
355            .and_then(|entry| entry.consumer.upgrade())
356            .filter(|consumer| consumer.pool_reusable())
357        {
358            return Ok(consumer);
359        }
360        let consumer = Arc::new(if local {
361            SubcConsumer::connect_local(path, options.clone()).await?
362        } else {
363            SubcConsumer::connect(path, options.clone()).await?
364        });
365        pool.push(PoolEntry {
366            path: path.into(),
367            options,
368            local,
369            consumer: Arc::downgrade(&consumer),
370        });
371        Ok(consumer)
372    }
373
374    /// Pass a helper-purpose claim through subc-os's one-read pipe. The helper
375    /// acts for the module, but its calls are attested as delegated, not its own.
376    /// No self claim or launch nonce is ever put into the child's environment or
377    /// argv. On Unix, install this handoff last on the helper's Command. On
378    /// Windows, configure the Command before spawning, then serve the handoff
379    /// with the live child's PID on a blocking thread, retaining the child.
380    pub async fn helper_claim_handoff(&self) -> Result<os::HelperClaimHandoff, ClaimError> {
381        let claim = self.mint_claim(ClaimPurpose::Helper).await?;
382        os::HelperClaimHandoff::new(claim.expose_secret()).map_err(|_| ClaimError::Handoff)
383    }
384
385    async fn mint_claim(&self, purpose: ClaimPurpose) -> Result<Claim, ClaimError> {
386        self.mint_claim_reply(ClaimMintRequest::new(purpose))
387            .await
388            .map(|reply| reply.claim)
389    }
390
391    async fn mint_claim_reply(
392        &self,
393        request: ClaimMintRequest,
394    ) -> Result<ClaimMintReply, ClaimError> {
395        if !self.shared.registration.active.load(Ordering::Acquire) {
396            return Err(ClaimError::Unavailable);
397        }
398        let deadline = Instant::now() + CATALOG_UPDATE_TIMEOUT;
399        loop {
400            let reply = timeout_at(deadline, self.claim_call(&request))
401                .await
402                .map_err(|_| ClaimError::Timeout)??;
403            if reply.header.ty == FrameType::Error {
404                let error: ErrorBody =
405                    serde_json::from_slice(&reply.body).map_err(|_| ClaimError::Protocol)?;
406                if error.code == error_codes::CLAIM_RATE_LIMITED {
407                    let detail: ClaimRateLimitedDetail =
408                        serde_json::from_value(error.detail.ok_or(ClaimError::Protocol)?)
409                            .map_err(|_| ClaimError::Protocol)?;
410                    // Use the daemon's delay, never its informational wall-clock
411                    // claim expiry. A bounded call must not retry past its budget.
412                    timeout_at(
413                        deadline,
414                        tokio::time::sleep(Duration::from_millis(detail.retry_after_ms)),
415                    )
416                    .await
417                    .map_err(|_| ClaimError::Timeout)?;
418                    continue;
419                }
420                return Err(ClaimError::Refused { code: error.code });
421            }
422            if reply.header.ty != FrameType::Response {
423                return Err(ClaimError::Protocol);
424            }
425            let reply: ClaimMintReply =
426                serde_json::from_slice(&reply.body).map_err(|_| ClaimError::Protocol)?;
427            return Ok(reply);
428        }
429    }
430
431    async fn claim_call(&self, request: &ClaimMintRequest) -> Result<Frame, ClaimError> {
432        let body = serde_json::to_vec(request).map_err(|_| ClaimError::Protocol)?;
433        let (corr, writer, rx) = {
434            let mut inner = self.shared.lock_inner();
435            let writer = inner.writer.clone().ok_or(ClaimError::Unavailable)?;
436            let corr = next_module_control_corr(&mut inner).ok_or(ClaimError::Unavailable)?;
437            let (tx, rx) = oneshot::channel();
438            inner.pending_claim_calls.insert(corr, tx);
439            (corr, writer, rx)
440        };
441        let _guard = ClaimWaiter {
442            handle: self.clone(),
443            corr,
444        };
445        let frame = Frame::build_with_version(
446            self.shared.negotiated_ver,
447            FrameType::Request,
448            control_flags(),
449            0,
450            0,
451            corr,
452            body,
453        )
454        .map_err(|_| ClaimError::Protocol)?;
455        writer
456            .send(frame)
457            .await
458            .map_err(|_| ClaimError::Unavailable)?;
459        rx.await.map_err(|_| ClaimError::Unavailable)
460    }
461}
462
463struct ClaimWaiter {
464    handle: ModuleHandle,
465    corr: u64,
466}
467impl Drop for ClaimWaiter {
468    fn drop(&mut self) {
469        self.handle
470            .shared
471            .lock_inner()
472            .pending_claim_calls
473            .remove(&self.corr);
474    }
475}
476
477pub(crate) fn bound() -> bool {
478    supervised() || HELPER_BOUND.load(Ordering::Acquire)
479}
480
481async fn mint_claim(minter: &dyn ClaimMinter, purpose: ClaimPurpose) -> Result<Claim, ClaimError> {
482    timeout(
483        CATALOG_UPDATE_TIMEOUT,
484        minter.mint(ClaimMintRequest::new(purpose)),
485    )
486    .await
487    .map_err(|_| ClaimError::Timeout)?
488    .map(|reply| reply.claim)
489}
490
491pub(crate) async fn bind_consumer<S: AsyncRead + AsyncWrite + Unpin>(
492    stream: &mut S,
493    deadline: Duration,
494) -> Result<(), ClaimError> {
495    let claim = if supervised() {
496        let owner = OWNER.get().ok_or(ClaimError::Unavailable)?;
497        Some(mint_claim(owner.as_ref(), ClaimPurpose::SelfConnection).await?)
498    } else {
499        os::helper_claim()
500            .map_err(|_| ClaimError::Handoff)?
501            .map(|claim| {
502                HELPER_BOUND.store(true, Ordering::Release);
503                Claim::new(claim.value())
504            })
505    };
506    let Some(claim) = claim else {
507        return Ok(());
508    };
509    present_claim(stream, claim, deadline).await
510}
511
512pub(crate) async fn present_claim<S: AsyncRead + AsyncWrite + Unpin>(
513    stream: &mut S,
514    claim: Claim,
515    deadline: Duration,
516) -> Result<(), ClaimError> {
517    let frame = Frame::build(
518        FrameType::Request,
519        control_flags(),
520        0,
521        0,
522        1,
523        serde_json::to_vec(&ClaimPresentRequest::new(claim)).map_err(|_| ClaimError::Protocol)?,
524    )
525    .map_err(|_| ClaimError::Protocol)?;
526    let reply = timeout(deadline, async {
527        write_frame(stream, &frame)
528            .await
529            .map_err(|_| ClaimError::Unavailable)?;
530        read_frame(stream)
531            .await
532            .map_err(|_| ClaimError::Unavailable)?
533            .ok_or(ClaimError::Unavailable)
534    })
535    .await
536    .map_err(|_| ClaimError::Timeout)??;
537    if reply.header.channel != 0 || reply.header.epoch != 0 || reply.header.corr != 1 {
538        return Err(ClaimError::Protocol);
539    }
540    if reply.header.ty == FrameType::Error {
541        let error: ErrorBody =
542            serde_json::from_slice(&reply.body).map_err(|_| ClaimError::Protocol)?;
543        return Err(ClaimError::Refused { code: error.code });
544    }
545    if reply.header.ty != FrameType::Response {
546        return Err(ClaimError::Protocol);
547    }
548    serde_json::from_slice::<ClaimPresentReply>(&reply.body).map_err(|_| ClaimError::Protocol)?;
549    Ok(())
550}
551
552#[cfg(all(test, any(unix, windows)))]
553#[path = "registration_tests.rs"]
554mod registration_contract;