1use std::{
2 collections::{BTreeMap, HashMap, HashSet},
3 error::Error,
4 fmt,
5 sync::{Arc, Mutex, MutexGuard},
6};
7
8use subc_protocol::manifest::{CapabilityDeclarations, ModuleManifest, ProviderRole};
9use tokio::sync::watch;
10use tracing::info;
11
12#[cfg(test)]
13#[path = "registry_admission_tests.rs"]
14mod admission_cache_tests;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
18pub struct ConnectionId(u64);
19
20impl ConnectionId {
21 #[cfg(test)]
24 pub const LOCAL: Self = Self(0);
25
26 pub const fn new(raw: u64) -> Self {
27 Self(raw)
28 }
29
30 pub fn get(self) -> u64 {
31 self.0
32 }
33}
34
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub enum ChannelState {
38 Active,
39 Closed,
40}
41
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44pub(crate) enum RegistrationEndReason {
45 ConnectionClosed,
46 ExplicitGoodbye,
47 Replaced,
48 SupervisorStop,
49 SupervisorRestart,
50 RegistrationFailed,
51}
52
53impl RegistrationEndReason {
54 fn as_str(self) -> &'static str {
55 match self {
56 Self::ConnectionClosed => "connection_closed",
57 Self::ExplicitGoodbye => "explicit_goodbye",
58 Self::Replaced => "replaced",
59 Self::SupervisorStop => "supervisor_stop",
60 Self::SupervisorRestart => "supervisor_restart",
61 Self::RegistrationFailed => "registration_failed",
62 }
63 }
64}
65
66#[derive(Debug, Clone, PartialEq)]
68pub struct ModuleRegistration {
69 pub manifest: ModuleManifest,
70 pub ready: bool,
71 pub negotiated_ver: u8,
72 pub state: ChannelState,
73 pub connection_id: ConnectionId,
74 pub control_ops: Vec<String>,
75}
76
77#[derive(Debug, Clone, PartialEq, Eq)]
79pub(crate) enum AdmissionRole {
80 ToolProvider,
81 ManagementSurface,
82 InternalService(String),
83}
84
85#[derive(Debug, Clone, PartialEq, Eq)]
86pub(crate) struct RouteRegistration {
87 pub(crate) module_id: String,
88 pub(crate) capabilities: Option<CapabilityDeclarations>,
89 pub(crate) roles: Vec<AdmissionRole>,
90 pub(crate) ready: bool,
91 pub(crate) state: ChannelState,
92 pub(crate) connection_id: ConnectionId,
93}
94
95impl From<&ModuleRegistration> for RouteRegistration {
96 fn from(registration: &ModuleRegistration) -> Self {
97 Self {
98 module_id: registration.manifest.module_id.clone(),
99 capabilities: registration.manifest.capabilities.clone(),
100 roles: registration
101 .manifest
102 .provides
103 .iter()
104 .filter_map(|role| match role {
105 ProviderRole::ToolProvider { .. } => Some(AdmissionRole::ToolProvider),
106 ProviderRole::ManagementSurface { .. } => {
107 Some(AdmissionRole::ManagementSurface)
108 }
109 ProviderRole::InternalService { service_id, .. } => {
110 Some(AdmissionRole::InternalService(service_id.clone()))
111 }
112 _ => None,
113 })
114 .collect(),
115 ready: registration.ready,
116 state: registration.state,
117 connection_id: registration.connection_id,
118 }
119 }
120}
121
122#[derive(Debug, PartialEq, Eq)]
125pub(crate) struct RouteAdmissionSnapshot {
126 pub(crate) modules: Vec<Arc<RouteRegistration>>,
127 pub(crate) unpublished: HashSet<ConnectionId>,
128 pub(crate) connections: HashMap<ConnectionId, Arc<RouteRegistration>>,
129}
130
131impl std::ops::Deref for RouteAdmissionSnapshot {
132 type Target = [Arc<RouteRegistration>];
133
134 fn deref(&self) -> &Self::Target {
135 &self.modules
136 }
137}
138
139#[derive(Debug, Clone, Copy, PartialEq, Eq)]
148pub enum RegistrationSlot<'a> {
149 Active(&'a str),
152 Candidate(&'a str),
154 Connection(ConnectionId),
156}
157
158#[derive(Debug, Clone, PartialEq)]
160pub struct RegistryCutover {
161 pub promoted: ModuleRegistration,
163 pub superseded: Option<ModuleRegistration>,
166}
167
168#[derive(Debug, Default)]
183pub struct Registry {
184 inner: Mutex<RegistryInner>,
185 #[cfg(test)]
186 next_lock_attempt: Mutex<Option<std::sync::mpsc::Sender<bool>>>,
187}
188
189#[derive(Debug, Default)]
190struct RegistryInner {
191 admission_cache: Option<Arc<RouteAdmissionSnapshot>>,
192 module_changes: HashMap<String, watch::Sender<u64>>,
197 modules: HashMap<String, ModuleRegistration>,
198 candidates: HashMap<String, ModuleRegistration>,
200 superseded: Vec<ModuleRegistration>,
203 nonce_verified: HashSet<ConnectionId>,
208 superseded_by: HashMap<ConnectionId, ConnectionId>,
210 unpublished: HashSet<ConnectionId>,
224 generation: u64,
225 catalog_changes: Option<watch::Sender<u64>>,
226}
227
228impl Registry {
229 pub(crate) fn subscribe_catalog_changes(&self) -> Result<watch::Receiver<u64>, RegistryError> {
232 let mut inner = self.lock_inner()?;
233 let generation = inner.generation;
234 Ok(inner
235 .catalog_changes
236 .get_or_insert_with(|| watch::channel(generation).0)
237 .subscribe())
238 }
239
240 pub fn catalog_authority_changed(&self) -> Result<(), RegistryError> {
245 self.lock_inner()?.bump_generation();
246 Ok(())
247 }
248
249 pub(crate) fn subscribe_module_changes(
252 &self,
253 module_id: &str,
254 ) -> Result<watch::Receiver<u64>, RegistryError> {
255 let mut inner = self.lock_inner()?;
256 inner
258 .module_changes
259 .retain(|_, sender| sender.receiver_count() > 0);
260 Ok(inner
261 .module_changes
262 .entry(module_id.to_string())
263 .or_insert_with(|| watch::channel(0).0)
264 .subscribe())
265 }
266
267 pub fn register_with_control_ops(
274 &self,
275 manifest: ModuleManifest,
276 negotiated_ver: u8,
277 connection_id: ConnectionId,
278 control_ops: Vec<String>,
279 ) -> Result<ModuleRegistration, RegistryError> {
280 self.register_active(
281 manifest,
282 negotiated_ver,
283 connection_id,
284 control_ops,
285 true,
286 false,
287 )
288 }
289
290 pub fn register_unpublished_with_control_ops(
299 &self,
300 manifest: ModuleManifest,
301 negotiated_ver: u8,
302 connection_id: ConnectionId,
303 control_ops: Vec<String>,
304 ) -> Result<ModuleRegistration, RegistryError> {
305 self.register_active(
306 manifest,
307 negotiated_ver,
308 connection_id,
309 control_ops,
310 false,
311 false,
312 )
313 }
314
315 pub(crate) fn register_unpublished_verified_with_control_ops(
317 &self,
318 manifest: ModuleManifest,
319 negotiated_ver: u8,
320 connection_id: ConnectionId,
321 control_ops: Vec<String>,
322 nonce_verified: bool,
323 ) -> Result<ModuleRegistration, RegistryError> {
324 self.register_active(
325 manifest,
326 negotiated_ver,
327 connection_id,
328 control_ops,
329 false,
330 nonce_verified,
331 )
332 }
333
334 fn register_active(
335 &self,
336 manifest: ModuleManifest,
337 negotiated_ver: u8,
338 connection_id: ConnectionId,
339 control_ops: Vec<String>,
340 publish: bool,
341 nonce_verified: bool,
342 ) -> Result<ModuleRegistration, RegistryError> {
343 let module_id = manifest.module_id.clone();
344 if let Err(reason) = module_id_path_hazard(&module_id) {
345 return Err(RegistryError::PathHazardModuleId { module_id, reason });
346 }
347 let mut inner = self.lock_inner()?;
348 if inner.modules.contains_key(&module_id) {
349 return Err(RegistryError::DuplicateModuleId { module_id });
350 }
351
352 let ready = manifest.ready.unwrap_or(true);
353 let registration = ModuleRegistration {
354 manifest,
355 ready,
356 negotiated_ver,
357 state: ChannelState::Active,
358 connection_id,
359 control_ops,
360 };
361
362 inner.modules.insert(module_id, registration.clone());
363 inner.admission_cache = None;
364 if nonce_verified {
365 inner.nonce_verified.insert(connection_id);
366 } else {
367 inner.nonce_verified.remove(&connection_id);
368 }
369 if publish {
370 inner.bump_generation();
371 } else {
372 inner.unpublished.insert(connection_id);
373 }
374 if let Some(sender) = inner.module_changes.get(®istration.manifest.module_id) {
375 sender.send_modify(|accepted| *accepted = accepted.wrapping_add(1));
376 }
377 Ok(registration)
378 }
379
380 pub fn register_candidate_with_control_ops(
394 &self,
395 manifest: ModuleManifest,
396 negotiated_ver: u8,
397 connection_id: ConnectionId,
398 control_ops: Vec<String>,
399 ) -> Result<ModuleRegistration, RegistryError> {
400 self.register_candidate(
401 manifest,
402 negotiated_ver,
403 connection_id,
404 control_ops,
405 true,
406 false,
407 )
408 }
409
410 pub fn register_unpublished_candidate_with_control_ops(
417 &self,
418 manifest: ModuleManifest,
419 negotiated_ver: u8,
420 connection_id: ConnectionId,
421 control_ops: Vec<String>,
422 ) -> Result<ModuleRegistration, RegistryError> {
423 self.register_candidate(
424 manifest,
425 negotiated_ver,
426 connection_id,
427 control_ops,
428 false,
429 false,
430 )
431 }
432
433 pub(crate) fn register_unpublished_verified_candidate_with_control_ops(
435 &self,
436 manifest: ModuleManifest,
437 negotiated_ver: u8,
438 connection_id: ConnectionId,
439 control_ops: Vec<String>,
440 ) -> Result<ModuleRegistration, RegistryError> {
441 self.register_candidate(
442 manifest,
443 negotiated_ver,
444 connection_id,
445 control_ops,
446 false,
447 true,
448 )
449 }
450
451 fn register_candidate(
452 &self,
453 manifest: ModuleManifest,
454 negotiated_ver: u8,
455 connection_id: ConnectionId,
456 control_ops: Vec<String>,
457 publish: bool,
458 nonce_verified: bool,
459 ) -> Result<ModuleRegistration, RegistryError> {
460 let module_id = manifest.module_id.clone();
461 if let Err(reason) = module_id_path_hazard(&module_id) {
462 return Err(RegistryError::PathHazardModuleId { module_id, reason });
463 }
464 let mut inner = self.lock_inner()?;
465 if inner.candidates.contains_key(&module_id) {
466 return Err(RegistryError::DuplicateModuleId { module_id });
467 }
468 let ready = manifest.ready.unwrap_or(true);
469 let registration = ModuleRegistration {
470 manifest,
471 ready,
472 negotiated_ver,
473 state: ChannelState::Active,
474 connection_id,
475 control_ops,
476 };
477 inner.candidates.insert(module_id, registration.clone());
478 if nonce_verified {
479 inner.nonce_verified.insert(connection_id);
480 } else {
481 inner.nonce_verified.remove(&connection_id);
482 }
483 if !publish {
484 inner.unpublished.insert(connection_id);
485 }
486 inner.notify_module_changed(®istration.manifest.module_id);
487 Ok(registration)
488 }
489
490 pub fn publish_registration(&self, connection_id: ConnectionId) -> Result<bool, RegistryError> {
502 let mut inner = self.lock_inner()?;
503 Ok(inner.publish_registration(connection_id))
504 }
505
506 pub(crate) fn publish_registration_after<E>(
516 &self,
517 connection_id: ConnectionId,
518 install: impl FnOnce() -> Result<(), E>,
519 ) -> Result<Result<bool, E>, RegistryError> {
520 let mut inner = self.lock_inner()?;
521 if let Err(err) = install() {
522 return Ok(Err(err));
523 }
524 Ok(Ok(inner.publish_registration(connection_id)))
525 }
526
527 #[cfg(test)]
528 pub(crate) fn observe_next_lock_attempt(&self) -> std::sync::mpsc::Receiver<bool> {
529 let (sender, receiver) = std::sync::mpsc::channel();
530 *self.next_lock_attempt.lock().unwrap() = Some(sender);
531 receiver
532 }
533
534 pub fn promote_candidate(
540 &self,
541 module_id: &str,
542 ) -> Result<Option<RegistryCutover>, RegistryError> {
543 let mut inner = self.lock_inner()?;
544 let Some(promoted) = inner.candidates.remove(module_id) else {
545 return Ok(None);
546 };
547 let superseded = inner
548 .modules
549 .insert(module_id.to_string(), promoted.clone());
550 if let Some(superseded) = superseded.clone() {
551 let replaced_connection_id = superseded.connection_id.get();
552 inner
553 .superseded_by
554 .insert(superseded.connection_id, promoted.connection_id);
555 inner.superseded.push(superseded);
556 info!(
557 target: "subc.registry",
558 module_id = %module_id,
559 connection_id = promoted.connection_id.get(),
560 replaced = true,
561 replaced_connection_id,
562 "module registration promoted"
563 );
564 }
565 inner.bump_generation();
566 inner.notify_module_changed(module_id);
567 Ok(Some(RegistryCutover {
568 promoted,
569 superseded,
570 }))
571 }
572
573 pub fn get_module(&self, module_id: &str) -> Result<Option<ModuleRegistration>, RegistryError> {
576 Ok(self.lock_inner()?.modules.get(module_id).cloned())
577 }
578
579 pub(crate) fn grants_control_op(
580 &self,
581 module_id: &str,
582 op: &str,
583 ) -> Result<bool, RegistryError> {
584 Ok(self
585 .lock_inner()?
586 .modules
587 .get(module_id)
588 .is_some_and(|registration| {
589 registration.control_ops.iter().any(|granted| granted == op)
590 }))
591 }
592
593 pub(crate) fn route_admission_snapshot(
598 &self,
599 ) -> Result<Arc<RouteAdmissionSnapshot>, RegistryError> {
600 let mut inner = self.lock_inner()?;
601 if let Some(snapshot) = &inner.admission_cache {
602 return Ok(snapshot.clone());
603 }
604 let mut modules = inner
605 .modules
606 .values()
607 .map(|registration| Arc::new(RouteRegistration::from(registration)))
608 .collect::<Vec<_>>();
609 modules.sort_by(|a, b| a.module_id.cmp(&b.module_id));
610 let mut connections: HashMap<_, _> = modules
611 .iter()
612 .map(|registration| (registration.connection_id, registration.clone()))
613 .collect();
614 for registration in inner.candidates.values().chain(inner.superseded.iter()) {
615 connections
616 .entry(registration.connection_id)
617 .or_insert_with(|| Arc::new(RouteRegistration::from(registration)));
618 }
619 let snapshot = Arc::new(RouteAdmissionSnapshot {
620 modules,
621 unpublished: inner.unpublished.clone(),
622 connections,
623 });
624 inner.admission_cache = Some(snapshot.clone());
625 Ok(snapshot)
626 }
627
628 pub(crate) fn route_registration_by_connection(
629 &self,
630 connection: ConnectionId,
631 ) -> Result<Option<Arc<RouteRegistration>>, RegistryError> {
632 Ok(self
633 .route_admission_snapshot()?
634 .connections
635 .get(&connection)
636 .cloned())
637 }
638
639 pub fn get_candidate(
641 &self,
642 module_id: &str,
643 ) -> Result<Option<ModuleRegistration>, RegistryError> {
644 Ok(self.lock_inner()?.candidates.get(module_id).cloned())
645 }
646
647 pub fn registration(
649 &self,
650 slot: RegistrationSlot<'_>,
651 ) -> Result<Option<ModuleRegistration>, RegistryError> {
652 let inner = self.lock_inner()?;
653 Ok(match slot {
654 RegistrationSlot::Active(module_id) => inner.modules.get(module_id).cloned(),
655 RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id).cloned(),
656 RegistrationSlot::Connection(connection_id) => inner
657 .find_by_connection(connection_id)
658 .map(|(_, registration)| registration.clone()),
659 })
660 }
661
662 pub fn active_registration_count(&self) -> Result<usize, RegistryError> {
663 Ok(self.lock_inner()?.modules.len())
664 }
665
666 pub fn list_modules(&self) -> Result<(u64, Vec<ModuleRegistration>), RegistryError> {
670 let inner = self.lock_inner()?;
671 let mut modules = inner
672 .modules
673 .values()
674 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
675 .cloned()
676 .collect::<Vec<_>>();
677 modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
678 Ok((inner.generation, modules))
679 }
680
681 pub fn list_modules_with_nonce_verification(
685 &self,
686 ) -> Result<(u64, Vec<(ModuleRegistration, bool)>), RegistryError> {
687 let inner = self.lock_inner()?;
688 let mut registrations = inner
689 .modules
690 .values()
691 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
692 .collect::<Vec<_>>();
693 registrations.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
694 let modules = registrations
695 .into_iter()
696 .map(|registration| {
697 (
698 registration.clone(),
699 inner.nonce_verified.contains(®istration.connection_id),
700 )
701 })
702 .collect();
703 Ok((inner.generation, modules))
704 }
705
706 pub fn list_registered_modules(&self) -> Result<Vec<ModuleRegistration>, RegistryError> {
712 let inner = self.lock_inner()?;
713 let mut modules = inner.modules.values().cloned().collect::<Vec<_>>();
714 modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
715 Ok(modules)
716 }
717
718 pub fn published_registration(
721 &self,
722 slot: RegistrationSlot<'_>,
723 ) -> Result<Option<ModuleRegistration>, RegistryError> {
724 let inner = self.lock_inner()?;
725 let registration = match slot {
726 RegistrationSlot::Active(module_id) => inner.modules.get(module_id),
727 RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id),
728 RegistrationSlot::Connection(connection_id) => inner
729 .find_by_connection(connection_id)
730 .map(|(_, registration)| registration),
731 };
732 Ok(registration
733 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
734 .cloned())
735 }
736
737 pub fn generation(&self) -> Result<u64, RegistryError> {
738 Ok(self.lock_inner()?.generation)
739 }
740
741 #[cfg(test)]
742 pub(crate) fn set_module_state_for_test(
743 &self,
744 module_id: &str,
745 state: ChannelState,
746 ) -> Result<bool, RegistryError> {
747 let mut inner = self.lock_inner()?;
748 let Some(registration) = inner.modules.get_mut(module_id) else {
749 return Ok(false);
750 };
751 registration.state = state;
752 inner.notify_module_changed(module_id);
753 Ok(true)
754 }
755
756 pub fn get_module_by_connection(
759 &self,
760 connection_id: ConnectionId,
761 ) -> Result<Option<ModuleRegistration>, RegistryError> {
762 Ok(self
763 .lock_inner()?
764 .find_by_connection(connection_id)
765 .map(|(_, registration)| registration.clone()))
766 }
767
768 pub(crate) fn module_id_for_connection(
769 &self,
770 connection_id: ConnectionId,
771 ) -> Result<Option<String>, RegistryError> {
772 Ok(self
773 .lock_inner()?
774 .find_by_connection(connection_id)
775 .map(|(_, registration)| registration.manifest.module_id.clone()))
776 }
777
778 pub fn replace_role_declarations_for_connection(
780 &self,
781 connection_id: ConnectionId,
782 role_declarations: BTreeMap<String, serde_json::Map<String, serde_json::Value>>,
783 ) -> Result<Option<ModuleRegistration>, RegistryError> {
784 let mut inner = self.lock_inner()?;
785 let Some((slot, _)) = inner.find_by_connection(connection_id) else {
786 return Ok(None);
787 };
788 let registration = inner
789 .registration_mut(slot, connection_id)
790 .expect("registration discovered under the same registry lock must still exist");
791 registration.manifest.role_declarations = role_declarations;
792 let updated = registration.clone();
793 if matches!(slot, SlotKind::Active) && !inner.unpublished.contains(&connection_id) {
794 inner.bump_generation();
795 }
796 inner.notify_module_changed(&updated.manifest.module_id);
797 Ok(Some(updated))
798 }
799
800 pub fn replace_catalog_for_connection(
809 &self,
810 connection_id: ConnectionId,
811 provides: Vec<ProviderRole>,
812 capabilities: Option<CapabilityDeclarations>,
813 ready: Option<bool>,
814 ) -> Result<Option<ModuleRegistration>, RegistryError> {
815 let mut inner = self.lock_inner()?;
816 let Some((slot, _)) = inner.find_by_connection(connection_id) else {
817 return Ok(None);
818 };
819 let registration = inner
820 .registration_mut(slot, connection_id)
821 .expect("registration discovered under the same registry lock must still exist");
822 if let Some(capabilities) = capabilities.as_ref() {
823 let declares_federated = |caps: Option<&CapabilityDeclarations>| {
824 caps.is_some_and(|caps| {
825 caps.provides
826 .iter()
827 .any(|cap| cap == subc_protocol::scope::SCOPE_FEDERATED_CAPABILITY)
828 })
829 };
830 if declares_federated(registration.manifest.capabilities.as_ref())
832 != declares_federated(Some(capabilities))
833 {
834 return Err(RegistryError::FederatedCapabilityChanged);
835 }
836 let declares_caller = |caps: Option<&CapabilityDeclarations>| {
840 caps.is_some_and(|caps| {
841 caps.provides
842 .iter()
843 .any(|cap| cap == subc_protocol::peer::CALLER_ATTESTATION_CAPABILITY)
844 })
845 };
846 if declares_caller(registration.manifest.capabilities.as_ref())
847 != declares_caller(Some(capabilities))
848 {
849 return Err(RegistryError::CallerAttestationCapabilityChanged);
850 }
851 }
852 registration.manifest.provides = provides;
853 if let Some(capabilities) = capabilities {
854 registration.manifest.capabilities = Some(capabilities);
855 }
856 if let Some(ready) = ready {
857 registration.ready = ready;
858 registration.manifest.ready = Some(ready);
859 }
860 let updated = registration.clone();
861 if matches!(slot, SlotKind::Active) && !inner.unpublished.contains(&connection_id) {
862 inner.bump_generation();
863 }
864 inner.notify_module_changed(&updated.manifest.module_id);
865 Ok(Some(updated))
866 }
867
868 pub fn deregister_connection(
870 &self,
871 connection_id: ConnectionId,
872 ) -> Result<Vec<ModuleRegistration>, RegistryError> {
873 self.deregister_connection_with_reason(
874 connection_id,
875 RegistrationEndReason::ConnectionClosed,
876 )
877 }
878
879 pub(crate) fn deregister_connection_with_reason(
880 &self,
881 connection_id: ConnectionId,
882 reason: RegistrationEndReason,
883 ) -> Result<Vec<ModuleRegistration>, RegistryError> {
884 let mut inner = self.lock_inner()?;
885 let was_published = !inner.unpublished.remove(&connection_id);
888 let module_ids: Vec<String> = inner
889 .modules
890 .iter()
891 .filter(|(_, registration)| registration.connection_id == connection_id)
892 .map(|(module_id, _)| module_id.clone())
893 .collect();
894
895 let mut closed: Vec<ModuleRegistration> = module_ids
896 .into_iter()
897 .filter_map(|module_id| inner.close_module(&module_id, was_published))
898 .collect();
899
900 let candidate_ids: Vec<String> = inner
901 .candidates
902 .iter()
903 .filter(|(_, registration)| registration.connection_id == connection_id)
904 .map(|(module_id, _)| module_id.clone())
905 .collect();
906 for module_id in candidate_ids {
907 if let Some(mut registration) = inner.candidates.remove(&module_id) {
908 registration.state = ChannelState::Closed;
909 closed.push(registration);
910 }
911 }
912
913 let (removed, kept): (Vec<_>, Vec<_>) = std::mem::take(&mut inner.superseded)
914 .into_iter()
915 .partition(|registration| registration.connection_id == connection_id);
916 let superseded_connections: std::collections::HashSet<_> = removed
917 .iter()
918 .map(|registration| registration.connection_id)
919 .collect();
920 inner.superseded = kept;
921 closed.extend(removed.into_iter().map(|mut registration| {
922 registration.state = ChannelState::Closed;
923 registration
924 }));
925 for registration in &closed {
926 inner.nonce_verified.remove(®istration.connection_id);
927 inner.notify_module_changed(®istration.manifest.module_id);
928 let replaced = superseded_connections.contains(®istration.connection_id);
929 let end_reason = if replaced {
930 RegistrationEndReason::Replaced
931 } else {
932 reason
933 };
934 let replaced_by_connection_id = if replaced {
935 inner
936 .superseded_by
937 .remove(®istration.connection_id)
938 .map(ConnectionId::get)
939 } else {
940 None
941 };
942 if let Some(replaced_by_connection_id) = replaced_by_connection_id {
943 info!(
944 target: "subc.registry",
945 module_id = %registration.manifest.module_id,
946 connection_id = registration.connection_id.get(),
947 reason = %end_reason.as_str(),
948 replaced_by_connection_id,
949 "module registration ended"
950 );
951 continue;
952 }
953 info!(
954 target: "subc.registry",
955 module_id = %registration.manifest.module_id,
956 connection_id = registration.connection_id.get(),
957 reason = %end_reason.as_str(),
958 "module registration ended"
959 );
960 }
961 Ok(closed)
962 }
963
964 fn lock_inner(&self) -> Result<MutexGuard<'_, RegistryInner>, RegistryError> {
965 #[cfg(test)]
966 {
967 let observer = self.next_lock_attempt.lock().unwrap().take();
968 if let Some(observer) = observer {
969 match self.inner.try_lock() {
973 Ok(inner) => {
974 observer.send(true).unwrap();
975 return Ok(inner);
976 }
977 Err(std::sync::TryLockError::WouldBlock) => observer.send(false).unwrap(),
978 Err(std::sync::TryLockError::Poisoned(_)) => {
979 return Err(RegistryError::Poisoned);
980 }
981 }
982 }
983 }
984 self.inner.lock().map_err(|_| RegistryError::Poisoned)
985 }
986}
987
988#[derive(Debug, Clone, Copy, PartialEq, Eq)]
990enum SlotKind {
991 Active,
992 Candidate,
993 Superseded,
994}
995
996impl RegistryInner {
997 fn publish_registration(&mut self, connection_id: ConnectionId) -> bool {
998 if !self.unpublished.remove(&connection_id) {
999 return false;
1000 }
1001 let Some((slot, registration)) = self.find_by_connection(connection_id) else {
1002 return false;
1003 };
1004 let module_id = registration.manifest.module_id.clone();
1005 if matches!(slot, SlotKind::Active) {
1006 self.bump_generation();
1007 }
1008 self.notify_module_changed(&module_id);
1009 true
1010 }
1011
1012 fn notify_module_changed(&mut self, module_id: &str) {
1013 self.admission_cache = None;
1016 if let Some(sender) = self.module_changes.get(module_id) {
1017 sender.send_modify(|_| {});
1018 }
1019 }
1020
1021 fn find_by_connection(
1022 &self,
1023 connection_id: ConnectionId,
1024 ) -> Option<(SlotKind, &ModuleRegistration)> {
1025 let owned_by =
1026 |registration: &&ModuleRegistration| registration.connection_id == connection_id;
1027 self.modules
1028 .values()
1029 .find(owned_by)
1030 .map(|registration| (SlotKind::Active, registration))
1031 .or_else(|| {
1032 self.candidates
1033 .values()
1034 .find(owned_by)
1035 .map(|registration| (SlotKind::Candidate, registration))
1036 })
1037 .or_else(|| {
1038 self.superseded
1039 .iter()
1040 .find(owned_by)
1041 .map(|registration| (SlotKind::Superseded, registration))
1042 })
1043 }
1044
1045 fn registration_mut(
1046 &mut self,
1047 slot: SlotKind,
1048 connection_id: ConnectionId,
1049 ) -> Option<&mut ModuleRegistration> {
1050 let owned_by =
1051 |registration: &&mut ModuleRegistration| registration.connection_id == connection_id;
1052 match slot {
1053 SlotKind::Active => self.modules.values_mut().find(owned_by),
1054 SlotKind::Candidate => self.candidates.values_mut().find(owned_by),
1055 SlotKind::Superseded => self.superseded.iter_mut().find(owned_by),
1056 }
1057 }
1058
1059 fn close_module(&mut self, module_id: &str, listed: bool) -> Option<ModuleRegistration> {
1060 let mut registration = self.modules.remove(module_id)?;
1061 registration.state = ChannelState::Closed;
1062 if listed {
1063 self.bump_generation();
1064 }
1065 Some(registration)
1066 }
1067
1068 fn bump_generation(&mut self) {
1069 self.admission_cache = None;
1070 self.generation = self.generation.wrapping_add(1);
1071 if let Some(sender) = &self.catalog_changes {
1072 sender.send_replace(self.generation);
1073 }
1074 }
1075}
1076
1077#[derive(Debug, Clone, PartialEq, Eq)]
1078pub enum RegistryError {
1079 FederatedCapabilityChanged,
1080 CallerAttestationCapabilityChanged,
1083 DuplicateModuleId {
1084 module_id: String,
1085 },
1086 PathHazardModuleId {
1095 module_id: String,
1096 reason: String,
1097 },
1098 Poisoned,
1099}
1100
1101impl fmt::Display for RegistryError {
1102 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1103 match self {
1104 Self::FederatedCapabilityChanged => write!(
1105 f,
1106 "scope-federated/v1 is fixed at HELLO; restart the module to change it"
1107 ),
1108 Self::CallerAttestationCapabilityChanged => write!(
1109 f,
1110 "caller-attestation/v1 is fixed at HELLO; restart the module to change it"
1111 ),
1112 Self::DuplicateModuleId { module_id } => {
1113 write!(f, "module_id '{module_id}' is already registered")
1114 }
1115 Self::PathHazardModuleId { module_id, reason } => {
1116 write!(
1117 f,
1118 "module_id '{}' is not usable as a path component: {reason}",
1119 module_id.escape_debug()
1120 )
1121 }
1122 Self::Poisoned => write!(f, "registry lock was poisoned"),
1123 }
1124 }
1125}
1126
1127impl Error for RegistryError {}
1128
1129pub fn module_id_path_hazard(module_id: &str) -> Result<(), String> {
1139 subc_protocol::module_id::module_id_path_hazard(module_id)
1140}
1141
1142#[cfg(test)]
1143mod change_notification_tests {
1144 use super::*;
1145
1146 fn manifest() -> ModuleManifest {
1147 ModuleManifest::builder("watched", "1.0.0")
1148 .protocol_ver(1)
1149 .build()
1150 }
1151
1152 fn changed(receiver: &mut watch::Receiver<u64>) {
1153 assert!(
1154 receiver.has_changed().unwrap(),
1155 "registry write must notify"
1156 );
1157 receiver.borrow_and_update();
1158 }
1159
1160 #[test]
1161 fn every_registration_write_notifies_only_its_module() {
1162 let registry = Registry::default();
1163 let mut events = registry.subscribe_module_changes("watched").unwrap();
1164 let other = registry.subscribe_module_changes("other").unwrap();
1165 let active = ConnectionId::new(1);
1166 let candidate = ConnectionId::new(2);
1167 registry
1168 .register_with_control_ops(manifest(), 1, active, vec![])
1169 .unwrap();
1170 changed(&mut events);
1171 registry
1172 .set_module_state_for_test("watched", ChannelState::Active)
1173 .unwrap();
1174 changed(&mut events);
1175 registry
1176 .replace_catalog_for_connection(active, vec![], None, Some(true))
1177 .unwrap();
1178 changed(&mut events);
1179 registry
1180 .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1181 .unwrap();
1182 changed(&mut events);
1183 registry
1184 .replace_catalog_for_connection(candidate, vec![], None, Some(true))
1185 .unwrap();
1186 changed(&mut events);
1187 registry.promote_candidate("watched").unwrap().unwrap();
1188 changed(&mut events);
1189 registry
1191 .replace_catalog_for_connection(active, vec![], None, Some(false))
1192 .unwrap();
1193 changed(&mut events);
1194 registry.deregister_connection(active).unwrap();
1195 changed(&mut events);
1196 registry.deregister_connection(candidate).unwrap();
1197 changed(&mut events);
1198 registry
1199 .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1200 .unwrap();
1201 changed(&mut events);
1202 registry.deregister_connection(candidate).unwrap();
1203 changed(&mut events);
1204 assert!(
1205 !other.has_changed().unwrap(),
1206 "other module must stay parked"
1207 );
1208 }
1209
1210 #[test]
1211 fn subscription_before_read_keeps_a_change_until_waited_on() {
1212 let registry = Registry::default();
1213 let mut events = registry.subscribe_module_changes("watched").unwrap();
1214 assert!(registry.get_module("watched").unwrap().is_none());
1215 registry
1216 .register_with_control_ops(manifest(), 1, ConnectionId::new(1), vec![])
1217 .unwrap();
1218 registry.get_module("watched").unwrap().unwrap();
1220 registry
1221 .replace_catalog_for_connection(ConnectionId::new(1), vec![], None, Some(true))
1222 .unwrap();
1223 changed(&mut events);
1224 assert!(!events.has_changed().unwrap());
1225 }
1226}
1227
1228#[cfg(test)]
1229mod publication_tests {
1230 use super::*;
1231
1232 fn manifest() -> ModuleManifest {
1233 ModuleManifest::builder("m", "1.0.0")
1234 .protocol_ver(1)
1235 .build()
1236 }
1237
1238 #[test]
1242 fn unpublished_registration_is_unlisted_until_published() {
1243 let registry = Registry::default();
1244 let connection = ConnectionId::new(1);
1245 registry
1246 .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1247 .unwrap();
1248 assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1249 assert!(registry.get_module("m").unwrap().is_some());
1250 assert_eq!(registry.list_registered_modules().unwrap().len(), 1);
1251 assert!(registry
1252 .published_registration(RegistrationSlot::Active("m"))
1253 .unwrap()
1254 .is_none());
1255 assert!(matches!(
1256 registry.register_with_control_ops(manifest(), 1, ConnectionId::new(2), vec![]),
1257 Err(RegistryError::DuplicateModuleId { .. })
1258 ));
1259 registry
1261 .replace_catalog_for_connection(connection, vec![], None, Some(true))
1262 .unwrap();
1263 assert_eq!(registry.generation().unwrap(), 0);
1264
1265 assert!(registry.publish_registration(connection).unwrap());
1266 let (generation, listed) = registry.list_modules().unwrap();
1267 assert_eq!(generation, 1);
1268 assert_eq!(listed.len(), 1);
1269 assert!(!registry.publish_registration(connection).unwrap());
1270 assert_eq!(registry.generation().unwrap(), 1);
1271 }
1272
1273 #[test]
1276 fn deregistering_an_unpublished_registration_leaves_the_generation() {
1277 let registry = Registry::default();
1278 let connection = ConnectionId::new(1);
1279 registry
1280 .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1281 .unwrap();
1282 assert_eq!(registry.deregister_connection(connection).unwrap().len(), 1);
1283 assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1284 assert!(!registry.publish_registration(connection).unwrap());
1285 assert_eq!(registry.generation().unwrap(), 0);
1286 }
1287
1288 #[test]
1293 fn unpublished_candidate_is_hidden_from_published_lookups() {
1294 let registry = Registry::default();
1295 let candidate = ConnectionId::new(2);
1296 registry
1297 .register_unpublished_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1298 .unwrap();
1299 assert!(registry
1300 .registration(RegistrationSlot::Candidate("m"))
1301 .unwrap()
1302 .is_some());
1303 assert!(registry
1304 .published_registration(RegistrationSlot::Candidate("m"))
1305 .unwrap()
1306 .is_none());
1307 assert!(registry
1308 .published_registration(RegistrationSlot::Connection(candidate))
1309 .unwrap()
1310 .is_none());
1311 assert!(registry.publish_registration(candidate).unwrap());
1312 assert!(registry
1313 .published_registration(RegistrationSlot::Candidate("m"))
1314 .unwrap()
1315 .is_some());
1316 assert_eq!(registry.generation().unwrap(), 0);
1317 }
1318}
1319
1320#[cfg(test)]
1321mod path_hazard_tests {
1322 use super::*;
1323 use crate::ConnectionId;
1324 use subc_protocol::manifest::ModuleManifest;
1325
1326 fn manifest(module_id: &str) -> ModuleManifest {
1327 ModuleManifest::builder(module_id, "0.1.0")
1328 .protocol_ver(1)
1329 .build()
1330 }
1331
1332 #[test]
1333 fn path_hazard_ids_are_refused_and_nothing_registers() {
1334 let registry = Registry::default();
1335 for (bad, reason_fragment) in [
1336 ("../escape", "path separator"),
1337 ("a/b", "path separator"),
1338 ("a\\b", "path separator"),
1339 ("..", "dot path component"),
1340 (".", "dot path component"),
1341 ("", "empty"),
1342 ("evil\u{0}id", "control character"),
1343 ] {
1344 let err = registry
1345 .register_with_control_ops(manifest(bad), 1, ConnectionId::new(7), Vec::new())
1346 .expect_err("path-hazard id must refuse");
1347 assert!(
1349 err.to_string().contains(reason_fragment),
1350 "id {bad:?}: expected {reason_fragment:?} in {err}"
1351 );
1352 }
1353 assert_eq!(registry.active_registration_count().unwrap(), 0);
1356 assert_eq!(registry.generation().unwrap(), 0);
1357 }
1358
1359 #[test]
1360 fn module_id_path_component_length_matches_shared_refusal_vectors() {
1361 let doc: serde_json::Value = serde_json::from_str(include_str!(
1362 "../tests/golden/module_id_path_component_refusals.json"
1363 ))
1364 .expect("refusal fixture parses");
1365
1366 for case in doc["vectors"].as_array().expect("vectors array") {
1367 let name = case["name"].as_str().expect("name");
1368 let module_id = case["module_id"]["unit"]
1369 .as_str()
1370 .expect("module_id unit")
1371 .repeat(
1372 case["module_id"]["repeat"]
1373 .as_u64()
1374 .expect("module_id repeat") as usize,
1375 );
1376 assert_eq!(
1377 module_id.len(),
1378 case["utf8_bytes"].as_u64().expect("utf8 bytes") as usize
1379 );
1380
1381 let expected = case["expect_reason"].as_str().map(str::to_owned);
1382 assert_eq!(
1383 module_id_path_hazard(&module_id).err(),
1384 expected,
1385 "shared refusal vector {name:?} diverged"
1386 );
1387 }
1388 }
1389
1390 #[test]
1391 fn working_id_shapes_register_including_namespace_colons() {
1392 let registry = Registry::default();
1393 for (i, good) in ["magic-context", "mcp:everything", "v1.2-module"]
1394 .iter()
1395 .enumerate()
1396 {
1397 registry
1398 .register_with_control_ops(
1399 manifest(good),
1400 1,
1401 ConnectionId::new(10 + i as u64),
1402 Vec::new(),
1403 )
1404 .unwrap_or_else(|err| panic!("id {good:?} must register: {err}"));
1405 }
1406 assert_eq!(registry.active_registration_count().unwrap(), 3);
1407 }
1408}
1409
1410#[cfg(test)]
1411mod swap_slot_tests {
1412 use super::*;
1413
1414 fn manifest(module_id: &str, ready: Option<bool>) -> ModuleManifest {
1415 let mut manifest = ModuleManifest::builder(module_id, "0.1.0").build();
1416 manifest.ready = ready;
1417 manifest
1418 }
1419
1420 const INCUMBENT: ConnectionId = ConnectionId(1);
1421 const CANDIDATE: ConnectionId = ConnectionId(2);
1422
1423 fn registry_with_candidate() -> Registry {
1424 let registry = Registry::default();
1425 registry
1426 .register_with_control_ops(manifest("m", None), 1, INCUMBENT, Vec::new())
1427 .unwrap();
1428 registry
1429 .register_candidate_with_control_ops(
1430 manifest("m", Some(false)),
1431 1,
1432 CANDIDATE,
1433 Vec::new(),
1434 )
1435 .unwrap();
1436 registry
1437 }
1438
1439 #[test]
1440 fn candidate_is_invisible_to_by_id_lookups_and_listing() {
1441 let registry = registry_with_candidate();
1442 let generation = registry.generation().unwrap();
1443 assert_eq!(
1444 registry.get_module("m").unwrap().unwrap().connection_id,
1445 INCUMBENT
1446 );
1447 let (listed_generation, listed) = registry.list_modules().unwrap();
1448 assert_eq!(listed.len(), 1);
1449 assert_eq!(listed[0].connection_id, INCUMBENT);
1450 assert_eq!(listed_generation, generation);
1451 assert_eq!(registry.active_registration_count().unwrap(), 1);
1452 assert_eq!(
1453 registry.get_candidate("m").unwrap().unwrap().connection_id,
1454 CANDIDATE
1455 );
1456 assert_eq!(
1457 registry
1458 .register_candidate_with_control_ops(
1459 manifest("m", None),
1460 1,
1461 ConnectionId(3),
1462 Vec::new()
1463 )
1464 .unwrap_err(),
1465 RegistryError::DuplicateModuleId {
1466 module_id: "m".to_string()
1467 }
1468 );
1469 }
1470
1471 #[test]
1472 fn promoted_candidate_keeps_its_verified_nonce_fact() {
1473 let registry = Registry::default();
1474 registry
1475 .register_unpublished_verified_candidate_with_control_ops(
1476 manifest("m", Some(true)),
1477 1,
1478 CANDIDATE,
1479 Vec::new(),
1480 )
1481 .unwrap();
1482 assert!(registry.publish_registration(CANDIDATE).unwrap());
1483 assert!(registry
1484 .list_modules_with_nonce_verification()
1485 .unwrap()
1486 .1
1487 .is_empty());
1488
1489 registry.promote_candidate("m").unwrap().unwrap();
1490 let (_, modules) = registry.list_modules_with_nonce_verification().unwrap();
1491 assert_eq!(modules.len(), 1);
1492 assert!(modules[0].1);
1493 }
1494
1495 #[test]
1498 fn candidate_catalog_update_reaches_the_candidate_registration() {
1499 let registry = registry_with_candidate();
1500 assert!(!registry.get_candidate("m").unwrap().unwrap().ready);
1501
1502 let updated = registry
1503 .replace_catalog_for_connection(CANDIDATE, Vec::new(), None, Some(true))
1504 .unwrap()
1505 .expect("the candidate's own connection finds its registration");
1506
1507 assert_eq!(updated.connection_id, CANDIDATE);
1508 assert!(registry.get_candidate("m").unwrap().unwrap().ready);
1509 assert_eq!(
1510 registry.get_module_by_connection(CANDIDATE).unwrap(),
1511 Some(updated)
1512 );
1513 assert_eq!(
1514 registry.get_module("m").unwrap().unwrap().connection_id,
1515 INCUMBENT,
1516 "a candidate's update must not touch the active registration"
1517 );
1518 }
1519
1520 #[test]
1521 fn promotion_swaps_slots_and_each_connection_still_deregisters_its_own() {
1522 let registry = registry_with_candidate();
1523 let before = registry.generation().unwrap();
1524 let cutover = registry.promote_candidate("m").unwrap().unwrap();
1525 assert_eq!(cutover.promoted.connection_id, CANDIDATE);
1526 assert_eq!(cutover.superseded.unwrap().connection_id, INCUMBENT);
1527 assert_ne!(registry.generation().unwrap(), before);
1528 assert_eq!(registry.promote_candidate("m").unwrap(), None);
1529
1530 assert_eq!(
1531 registry
1532 .registration(RegistrationSlot::Active("m"))
1533 .unwrap()
1534 .unwrap()
1535 .connection_id,
1536 CANDIDATE
1537 );
1538 assert!(registry
1539 .registration(RegistrationSlot::Candidate("m"))
1540 .unwrap()
1541 .is_none());
1542 assert!(registry
1543 .registration(RegistrationSlot::Connection(INCUMBENT))
1544 .unwrap()
1545 .is_some());
1546
1547 let closed = registry.deregister_connection(INCUMBENT).unwrap();
1548 assert_eq!(closed.len(), 1);
1549 assert_eq!(closed[0].connection_id, INCUMBENT);
1550 assert_eq!(closed[0].state, ChannelState::Closed);
1551 assert!(registry
1552 .registration(RegistrationSlot::Connection(INCUMBENT))
1553 .unwrap()
1554 .is_none());
1555 assert_eq!(
1556 registry.get_module("m").unwrap().unwrap().connection_id,
1557 CANDIDATE
1558 );
1559 }
1560
1561 #[test]
1562 fn a_dropped_candidate_deregisters_from_the_candidate_slot_only() {
1563 let registry = registry_with_candidate();
1564 let closed = registry.deregister_connection(CANDIDATE).unwrap();
1565 assert_eq!(closed.len(), 1);
1566 assert_eq!(closed[0].connection_id, CANDIDATE);
1567 assert!(registry.get_candidate("m").unwrap().is_none());
1568 assert_eq!(
1569 registry.get_module("m").unwrap().unwrap().connection_id,
1570 INCUMBENT
1571 );
1572 }
1573}