1use 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#[async_trait]
40pub trait ClaimMinter: Send + Sync {
41 async fn mint(&self, request: ClaimMintRequest) -> Result<ClaimMintReply, ClaimError>;
42}
43
44#[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
75pub fn adopt_channel() -> Result<Option<Box<dyn ModuleStream>>, RegistrationError> {
88 init_supervised();
89 take_channel_stream()
90}
91
92pub 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#[derive(Debug)]
139#[non_exhaustive]
140pub enum ClaimError {
141 Unavailable,
142 Timeout,
143 Protocol,
144 Refused {
145 code: String,
146 },
147 Handoff,
148 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 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 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 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 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 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 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;