1use std::{
2 collections::{HashMap, HashSet},
3 error::Error,
4 fmt,
5 sync::{Mutex, MutexGuard},
6};
7
8use subc_protocol::manifest::{CapabilityDeclarations, ModuleManifest, ProviderRole};
9use tokio::sync::watch;
10use tracing::info;
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
14pub struct ConnectionId(u64);
15
16impl ConnectionId {
17 #[cfg(test)]
20 pub const LOCAL: Self = Self(0);
21
22 pub const fn new(raw: u64) -> Self {
23 Self(raw)
24 }
25
26 pub fn get(self) -> u64 {
27 self.0
28 }
29}
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub enum ChannelState {
34 Active,
35 Closed,
36}
37
38#[derive(Debug, Clone, Copy, PartialEq, Eq)]
40pub(crate) enum RegistrationEndReason {
41 ConnectionClosed,
42 ExplicitGoodbye,
43 Replaced,
44 SupervisorStop,
45 SupervisorRestart,
46 RegistrationFailed,
47}
48
49impl RegistrationEndReason {
50 fn as_str(self) -> &'static str {
51 match self {
52 Self::ConnectionClosed => "connection_closed",
53 Self::ExplicitGoodbye => "explicit_goodbye",
54 Self::Replaced => "replaced",
55 Self::SupervisorStop => "supervisor_stop",
56 Self::SupervisorRestart => "supervisor_restart",
57 Self::RegistrationFailed => "registration_failed",
58 }
59 }
60}
61
62#[derive(Debug, Clone, PartialEq)]
64pub struct ModuleRegistration {
65 pub manifest: ModuleManifest,
66 pub ready: bool,
67 pub negotiated_ver: u8,
68 pub state: ChannelState,
69 pub connection_id: ConnectionId,
70 pub control_ops: Vec<String>,
71}
72
73pub(crate) struct RouteAdmissionSnapshot {
75 pub(crate) modules: Vec<ModuleRegistration>,
76 pub(crate) unpublished: HashSet<ConnectionId>,
77}
78
79impl std::ops::Deref for RouteAdmissionSnapshot {
80 type Target = [ModuleRegistration];
81
82 fn deref(&self) -> &Self::Target {
83 &self.modules
84 }
85}
86
87#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96pub enum RegistrationSlot<'a> {
97 Active(&'a str),
100 Candidate(&'a str),
102 Connection(ConnectionId),
104}
105
106#[derive(Debug, Clone, PartialEq)]
108pub struct RegistryCutover {
109 pub promoted: ModuleRegistration,
111 pub superseded: Option<ModuleRegistration>,
114}
115
116#[derive(Debug, Default)]
131pub struct Registry {
132 inner: Mutex<RegistryInner>,
133}
134
135#[derive(Debug, Default)]
136struct RegistryInner {
137 module_changes: HashMap<String, watch::Sender<u64>>,
142 modules: HashMap<String, ModuleRegistration>,
143 candidates: HashMap<String, ModuleRegistration>,
145 superseded: Vec<ModuleRegistration>,
148 nonce_verified: HashSet<ConnectionId>,
153 superseded_by: HashMap<ConnectionId, ConnectionId>,
155 unpublished: HashSet<ConnectionId>,
169 generation: u64,
170}
171
172impl Registry {
173 pub(crate) fn subscribe_module_changes(
176 &self,
177 module_id: &str,
178 ) -> Result<watch::Receiver<u64>, RegistryError> {
179 let mut inner = self.lock_inner()?;
180 inner
182 .module_changes
183 .retain(|_, sender| sender.receiver_count() > 0);
184 Ok(inner
185 .module_changes
186 .entry(module_id.to_string())
187 .or_insert_with(|| watch::channel(0).0)
188 .subscribe())
189 }
190
191 pub fn register_with_control_ops(
198 &self,
199 manifest: ModuleManifest,
200 negotiated_ver: u8,
201 connection_id: ConnectionId,
202 control_ops: Vec<String>,
203 ) -> Result<ModuleRegistration, RegistryError> {
204 self.register_active(
205 manifest,
206 negotiated_ver,
207 connection_id,
208 control_ops,
209 true,
210 false,
211 )
212 }
213
214 pub fn register_unpublished_with_control_ops(
223 &self,
224 manifest: ModuleManifest,
225 negotiated_ver: u8,
226 connection_id: ConnectionId,
227 control_ops: Vec<String>,
228 ) -> Result<ModuleRegistration, RegistryError> {
229 self.register_active(
230 manifest,
231 negotiated_ver,
232 connection_id,
233 control_ops,
234 false,
235 false,
236 )
237 }
238
239 pub(crate) fn register_unpublished_verified_with_control_ops(
241 &self,
242 manifest: ModuleManifest,
243 negotiated_ver: u8,
244 connection_id: ConnectionId,
245 control_ops: Vec<String>,
246 nonce_verified: bool,
247 ) -> Result<ModuleRegistration, RegistryError> {
248 self.register_active(
249 manifest,
250 negotiated_ver,
251 connection_id,
252 control_ops,
253 false,
254 nonce_verified,
255 )
256 }
257
258 fn register_active(
259 &self,
260 manifest: ModuleManifest,
261 negotiated_ver: u8,
262 connection_id: ConnectionId,
263 control_ops: Vec<String>,
264 publish: bool,
265 nonce_verified: bool,
266 ) -> Result<ModuleRegistration, RegistryError> {
267 let module_id = manifest.module_id.clone();
268 if let Err(reason) = module_id_path_hazard(&module_id) {
269 return Err(RegistryError::PathHazardModuleId { module_id, reason });
270 }
271 let mut inner = self.lock_inner()?;
272 if inner.modules.contains_key(&module_id) {
273 return Err(RegistryError::DuplicateModuleId { module_id });
274 }
275
276 let ready = manifest.ready.unwrap_or(true);
277 let registration = ModuleRegistration {
278 manifest,
279 ready,
280 negotiated_ver,
281 state: ChannelState::Active,
282 connection_id,
283 control_ops,
284 };
285
286 inner.modules.insert(module_id, registration.clone());
287 if nonce_verified {
288 inner.nonce_verified.insert(connection_id);
289 } else {
290 inner.nonce_verified.remove(&connection_id);
291 }
292 if publish {
293 inner.bump_generation();
294 } else {
295 inner.unpublished.insert(connection_id);
296 }
297 if let Some(sender) = inner.module_changes.get(®istration.manifest.module_id) {
298 sender.send_modify(|accepted| *accepted = accepted.wrapping_add(1));
299 }
300 Ok(registration)
301 }
302
303 pub fn register_candidate_with_control_ops(
317 &self,
318 manifest: ModuleManifest,
319 negotiated_ver: u8,
320 connection_id: ConnectionId,
321 control_ops: Vec<String>,
322 ) -> Result<ModuleRegistration, RegistryError> {
323 self.register_candidate(
324 manifest,
325 negotiated_ver,
326 connection_id,
327 control_ops,
328 true,
329 false,
330 )
331 }
332
333 pub fn register_unpublished_candidate_with_control_ops(
340 &self,
341 manifest: ModuleManifest,
342 negotiated_ver: u8,
343 connection_id: ConnectionId,
344 control_ops: Vec<String>,
345 ) -> Result<ModuleRegistration, RegistryError> {
346 self.register_candidate(
347 manifest,
348 negotiated_ver,
349 connection_id,
350 control_ops,
351 false,
352 false,
353 )
354 }
355
356 pub(crate) fn register_unpublished_verified_candidate_with_control_ops(
358 &self,
359 manifest: ModuleManifest,
360 negotiated_ver: u8,
361 connection_id: ConnectionId,
362 control_ops: Vec<String>,
363 ) -> Result<ModuleRegistration, RegistryError> {
364 self.register_candidate(
365 manifest,
366 negotiated_ver,
367 connection_id,
368 control_ops,
369 false,
370 true,
371 )
372 }
373
374 fn register_candidate(
375 &self,
376 manifest: ModuleManifest,
377 negotiated_ver: u8,
378 connection_id: ConnectionId,
379 control_ops: Vec<String>,
380 publish: bool,
381 nonce_verified: bool,
382 ) -> Result<ModuleRegistration, RegistryError> {
383 let module_id = manifest.module_id.clone();
384 if let Err(reason) = module_id_path_hazard(&module_id) {
385 return Err(RegistryError::PathHazardModuleId { module_id, reason });
386 }
387 let mut inner = self.lock_inner()?;
388 if inner.candidates.contains_key(&module_id) {
389 return Err(RegistryError::DuplicateModuleId { module_id });
390 }
391 let ready = manifest.ready.unwrap_or(true);
392 let registration = ModuleRegistration {
393 manifest,
394 ready,
395 negotiated_ver,
396 state: ChannelState::Active,
397 connection_id,
398 control_ops,
399 };
400 inner.candidates.insert(module_id, registration.clone());
401 if nonce_verified {
402 inner.nonce_verified.insert(connection_id);
403 } else {
404 inner.nonce_verified.remove(&connection_id);
405 }
406 if !publish {
407 inner.unpublished.insert(connection_id);
408 }
409 inner.notify_module_changed(®istration.manifest.module_id);
410 Ok(registration)
411 }
412
413 pub fn publish_registration(&self, connection_id: ConnectionId) -> Result<bool, RegistryError> {
425 let mut inner = self.lock_inner()?;
426 if !inner.unpublished.remove(&connection_id) {
427 return Ok(false);
428 }
429 let Some((slot, registration)) = inner.find_by_connection(connection_id) else {
430 return Ok(false);
431 };
432 let module_id = registration.manifest.module_id.clone();
433 if matches!(slot, SlotKind::Active) {
434 inner.bump_generation();
435 }
436 inner.notify_module_changed(&module_id);
437 Ok(true)
438 }
439
440 pub fn promote_candidate(
446 &self,
447 module_id: &str,
448 ) -> Result<Option<RegistryCutover>, RegistryError> {
449 let mut inner = self.lock_inner()?;
450 let Some(promoted) = inner.candidates.remove(module_id) else {
451 return Ok(None);
452 };
453 let superseded = inner
454 .modules
455 .insert(module_id.to_string(), promoted.clone());
456 if let Some(superseded) = superseded.clone() {
457 let replaced_connection_id = superseded.connection_id.get();
458 inner
459 .superseded_by
460 .insert(superseded.connection_id, promoted.connection_id);
461 inner.superseded.push(superseded);
462 info!(
463 target: "subc.registry",
464 module_id = %module_id,
465 connection_id = promoted.connection_id.get(),
466 replaced = true,
467 replaced_connection_id,
468 "module registration promoted"
469 );
470 }
471 inner.bump_generation();
472 inner.notify_module_changed(module_id);
473 Ok(Some(RegistryCutover {
474 promoted,
475 superseded,
476 }))
477 }
478
479 pub fn get_module(&self, module_id: &str) -> Result<Option<ModuleRegistration>, RegistryError> {
482 Ok(self.lock_inner()?.modules.get(module_id).cloned())
483 }
484
485 pub(crate) fn route_admission_snapshot(&self) -> Result<RouteAdmissionSnapshot, RegistryError> {
490 let inner = self.lock_inner()?;
491 let mut modules = inner.modules.values().cloned().collect::<Vec<_>>();
492 modules.sort_by(|a, b| a.manifest.module_id.cmp(&b.manifest.module_id));
493 Ok(RouteAdmissionSnapshot {
494 modules,
495 unpublished: inner.unpublished.clone(),
496 })
497 }
498
499 pub fn get_candidate(
501 &self,
502 module_id: &str,
503 ) -> Result<Option<ModuleRegistration>, RegistryError> {
504 Ok(self.lock_inner()?.candidates.get(module_id).cloned())
505 }
506
507 pub fn registration(
509 &self,
510 slot: RegistrationSlot<'_>,
511 ) -> Result<Option<ModuleRegistration>, RegistryError> {
512 let inner = self.lock_inner()?;
513 Ok(match slot {
514 RegistrationSlot::Active(module_id) => inner.modules.get(module_id).cloned(),
515 RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id).cloned(),
516 RegistrationSlot::Connection(connection_id) => inner
517 .find_by_connection(connection_id)
518 .map(|(_, registration)| registration.clone()),
519 })
520 }
521
522 pub fn active_registration_count(&self) -> Result<usize, RegistryError> {
523 Ok(self.lock_inner()?.modules.len())
524 }
525
526 pub fn list_modules(&self) -> Result<(u64, Vec<ModuleRegistration>), RegistryError> {
530 let inner = self.lock_inner()?;
531 let mut modules = inner
532 .modules
533 .values()
534 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
535 .cloned()
536 .collect::<Vec<_>>();
537 modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
538 Ok((inner.generation, modules))
539 }
540
541 pub fn list_modules_with_nonce_verification(
545 &self,
546 ) -> Result<(u64, Vec<(ModuleRegistration, bool)>), RegistryError> {
547 let inner = self.lock_inner()?;
548 let mut registrations = inner
549 .modules
550 .values()
551 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
552 .collect::<Vec<_>>();
553 registrations.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
554 let modules = registrations
555 .into_iter()
556 .map(|registration| {
557 (
558 registration.clone(),
559 inner.nonce_verified.contains(®istration.connection_id),
560 )
561 })
562 .collect();
563 Ok((inner.generation, modules))
564 }
565
566 pub fn list_registered_modules(&self) -> Result<Vec<ModuleRegistration>, RegistryError> {
572 let inner = self.lock_inner()?;
573 let mut modules = inner.modules.values().cloned().collect::<Vec<_>>();
574 modules.sort_by(|left, right| left.manifest.module_id.cmp(&right.manifest.module_id));
575 Ok(modules)
576 }
577
578 pub fn published_registration(
581 &self,
582 slot: RegistrationSlot<'_>,
583 ) -> Result<Option<ModuleRegistration>, RegistryError> {
584 let inner = self.lock_inner()?;
585 let registration = match slot {
586 RegistrationSlot::Active(module_id) => inner.modules.get(module_id),
587 RegistrationSlot::Candidate(module_id) => inner.candidates.get(module_id),
588 RegistrationSlot::Connection(connection_id) => inner
589 .find_by_connection(connection_id)
590 .map(|(_, registration)| registration),
591 };
592 Ok(registration
593 .filter(|registration| !inner.unpublished.contains(®istration.connection_id))
594 .cloned())
595 }
596
597 pub fn generation(&self) -> Result<u64, RegistryError> {
598 Ok(self.lock_inner()?.generation)
599 }
600
601 #[cfg(test)]
602 pub(crate) fn set_module_state_for_test(
603 &self,
604 module_id: &str,
605 state: ChannelState,
606 ) -> Result<bool, RegistryError> {
607 let mut inner = self.lock_inner()?;
608 let Some(registration) = inner.modules.get_mut(module_id) else {
609 return Ok(false);
610 };
611 registration.state = state;
612 inner.notify_module_changed(module_id);
613 Ok(true)
614 }
615
616 pub fn get_module_by_connection(
619 &self,
620 connection_id: ConnectionId,
621 ) -> Result<Option<ModuleRegistration>, RegistryError> {
622 Ok(self
623 .lock_inner()?
624 .find_by_connection(connection_id)
625 .map(|(_, registration)| registration.clone()))
626 }
627
628 pub fn replace_catalog_for_connection(
637 &self,
638 connection_id: ConnectionId,
639 provides: Vec<ProviderRole>,
640 capabilities: Option<CapabilityDeclarations>,
641 ready: Option<bool>,
642 ) -> Result<Option<ModuleRegistration>, RegistryError> {
643 let mut inner = self.lock_inner()?;
644 let Some((slot, _)) = inner.find_by_connection(connection_id) else {
645 return Ok(None);
646 };
647 let registration = inner
648 .registration_mut(slot, connection_id)
649 .expect("registration discovered under the same registry lock must still exist");
650 if let Some(capabilities) = capabilities.as_ref() {
651 let declares_federated = |caps: Option<&CapabilityDeclarations>| {
652 caps.is_some_and(|caps| {
653 caps.provides
654 .iter()
655 .any(|cap| cap == subc_protocol::scope::SCOPE_FEDERATED_CAPABILITY)
656 })
657 };
658 if declares_federated(registration.manifest.capabilities.as_ref())
660 != declares_federated(Some(capabilities))
661 {
662 return Err(RegistryError::FederatedCapabilityChanged);
663 }
664 }
665 registration.manifest.provides = provides;
666 if let Some(capabilities) = capabilities {
667 registration.manifest.capabilities = Some(capabilities);
668 }
669 if let Some(ready) = ready {
670 registration.ready = ready;
671 registration.manifest.ready = Some(ready);
672 }
673 let updated = registration.clone();
674 if matches!(slot, SlotKind::Active) && !inner.unpublished.contains(&connection_id) {
675 inner.bump_generation();
676 }
677 inner.notify_module_changed(&updated.manifest.module_id);
678 Ok(Some(updated))
679 }
680
681 pub fn deregister_connection(
683 &self,
684 connection_id: ConnectionId,
685 ) -> Result<Vec<ModuleRegistration>, RegistryError> {
686 self.deregister_connection_with_reason(
687 connection_id,
688 RegistrationEndReason::ConnectionClosed,
689 )
690 }
691
692 pub(crate) fn deregister_connection_with_reason(
693 &self,
694 connection_id: ConnectionId,
695 reason: RegistrationEndReason,
696 ) -> Result<Vec<ModuleRegistration>, RegistryError> {
697 let mut inner = self.lock_inner()?;
698 let was_published = !inner.unpublished.remove(&connection_id);
701 let module_ids: Vec<String> = inner
702 .modules
703 .iter()
704 .filter(|(_, registration)| registration.connection_id == connection_id)
705 .map(|(module_id, _)| module_id.clone())
706 .collect();
707
708 let mut closed: Vec<ModuleRegistration> = module_ids
709 .into_iter()
710 .filter_map(|module_id| inner.close_module(&module_id, was_published))
711 .collect();
712
713 let candidate_ids: Vec<String> = inner
714 .candidates
715 .iter()
716 .filter(|(_, registration)| registration.connection_id == connection_id)
717 .map(|(module_id, _)| module_id.clone())
718 .collect();
719 for module_id in candidate_ids {
720 if let Some(mut registration) = inner.candidates.remove(&module_id) {
721 registration.state = ChannelState::Closed;
722 closed.push(registration);
723 }
724 }
725
726 let (removed, kept): (Vec<_>, Vec<_>) = std::mem::take(&mut inner.superseded)
727 .into_iter()
728 .partition(|registration| registration.connection_id == connection_id);
729 let superseded_connections: std::collections::HashSet<_> = removed
730 .iter()
731 .map(|registration| registration.connection_id)
732 .collect();
733 inner.superseded = kept;
734 closed.extend(removed.into_iter().map(|mut registration| {
735 registration.state = ChannelState::Closed;
736 registration
737 }));
738 for registration in &closed {
739 inner.nonce_verified.remove(®istration.connection_id);
740 inner.notify_module_changed(®istration.manifest.module_id);
741 let replaced = superseded_connections.contains(®istration.connection_id);
742 let end_reason = if replaced {
743 RegistrationEndReason::Replaced
744 } else {
745 reason
746 };
747 let replaced_by_connection_id = if replaced {
748 inner
749 .superseded_by
750 .remove(®istration.connection_id)
751 .map(ConnectionId::get)
752 } else {
753 None
754 };
755 if let Some(replaced_by_connection_id) = replaced_by_connection_id {
756 info!(
757 target: "subc.registry",
758 module_id = %registration.manifest.module_id,
759 connection_id = registration.connection_id.get(),
760 reason = %end_reason.as_str(),
761 replaced_by_connection_id,
762 "module registration ended"
763 );
764 continue;
765 }
766 info!(
767 target: "subc.registry",
768 module_id = %registration.manifest.module_id,
769 connection_id = registration.connection_id.get(),
770 reason = %end_reason.as_str(),
771 "module registration ended"
772 );
773 }
774 Ok(closed)
775 }
776
777 fn lock_inner(&self) -> Result<MutexGuard<'_, RegistryInner>, RegistryError> {
778 self.inner.lock().map_err(|_| RegistryError::Poisoned)
779 }
780}
781
782#[derive(Debug, Clone, Copy, PartialEq, Eq)]
784enum SlotKind {
785 Active,
786 Candidate,
787 Superseded,
788}
789
790impl RegistryInner {
791 fn notify_module_changed(&self, module_id: &str) {
792 if let Some(sender) = self.module_changes.get(module_id) {
793 sender.send_modify(|_| {});
794 }
795 }
796
797 fn find_by_connection(
798 &self,
799 connection_id: ConnectionId,
800 ) -> Option<(SlotKind, &ModuleRegistration)> {
801 let owned_by =
802 |registration: &&ModuleRegistration| registration.connection_id == connection_id;
803 self.modules
804 .values()
805 .find(owned_by)
806 .map(|registration| (SlotKind::Active, registration))
807 .or_else(|| {
808 self.candidates
809 .values()
810 .find(owned_by)
811 .map(|registration| (SlotKind::Candidate, registration))
812 })
813 .or_else(|| {
814 self.superseded
815 .iter()
816 .find(owned_by)
817 .map(|registration| (SlotKind::Superseded, registration))
818 })
819 }
820
821 fn registration_mut(
822 &mut self,
823 slot: SlotKind,
824 connection_id: ConnectionId,
825 ) -> Option<&mut ModuleRegistration> {
826 let owned_by =
827 |registration: &&mut ModuleRegistration| registration.connection_id == connection_id;
828 match slot {
829 SlotKind::Active => self.modules.values_mut().find(owned_by),
830 SlotKind::Candidate => self.candidates.values_mut().find(owned_by),
831 SlotKind::Superseded => self.superseded.iter_mut().find(owned_by),
832 }
833 }
834
835 fn close_module(&mut self, module_id: &str, listed: bool) -> Option<ModuleRegistration> {
836 let mut registration = self.modules.remove(module_id)?;
837 registration.state = ChannelState::Closed;
838 if listed {
839 self.bump_generation();
840 }
841 Some(registration)
842 }
843
844 fn bump_generation(&mut self) {
845 self.generation = self.generation.wrapping_add(1);
846 }
847}
848
849#[derive(Debug, Clone, PartialEq, Eq)]
850pub enum RegistryError {
851 FederatedCapabilityChanged,
852 DuplicateModuleId {
853 module_id: String,
854 },
855 PathHazardModuleId {
864 module_id: String,
865 reason: String,
866 },
867 Poisoned,
868}
869
870impl fmt::Display for RegistryError {
871 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
872 match self {
873 Self::FederatedCapabilityChanged => write!(f, "scope-federated/v1 is fixed at HELLO; re-register on a new connection to change it"),
874 Self::DuplicateModuleId { module_id } => {
875 write!(f, "module_id '{module_id}' is already registered")
876 }
877 Self::PathHazardModuleId { module_id, reason } => {
878 write!(
879 f,
880 "module_id '{}' is not usable as a path component: {reason}",
881 module_id.escape_debug()
882 )
883 }
884 Self::Poisoned => write!(f, "registry lock was poisoned"),
885 }
886 }
887}
888
889impl Error for RegistryError {}
890
891pub fn module_id_path_hazard(module_id: &str) -> Result<(), String> {
901 subc_protocol::manifest::validate_module_id(module_id)
902}
903
904#[cfg(test)]
905mod change_notification_tests {
906 use super::*;
907
908 fn manifest() -> ModuleManifest {
909 ModuleManifest::builder("watched", "1.0.0")
910 .protocol_ver(1)
911 .build()
912 }
913
914 fn changed(receiver: &mut watch::Receiver<u64>) {
915 assert!(
916 receiver.has_changed().unwrap(),
917 "registry write must notify"
918 );
919 receiver.borrow_and_update();
920 }
921
922 #[test]
923 fn every_registration_write_notifies_only_its_module() {
924 let registry = Registry::default();
925 let mut events = registry.subscribe_module_changes("watched").unwrap();
926 let other = registry.subscribe_module_changes("other").unwrap();
927 let active = ConnectionId::new(1);
928 let candidate = ConnectionId::new(2);
929 registry
930 .register_with_control_ops(manifest(), 1, active, vec![])
931 .unwrap();
932 changed(&mut events);
933 registry
934 .set_module_state_for_test("watched", ChannelState::Active)
935 .unwrap();
936 changed(&mut events);
937 registry
938 .replace_catalog_for_connection(active, vec![], None, Some(true))
939 .unwrap();
940 changed(&mut events);
941 registry
942 .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
943 .unwrap();
944 changed(&mut events);
945 registry
946 .replace_catalog_for_connection(candidate, vec![], None, Some(true))
947 .unwrap();
948 changed(&mut events);
949 registry.promote_candidate("watched").unwrap().unwrap();
950 changed(&mut events);
951 registry
953 .replace_catalog_for_connection(active, vec![], None, Some(false))
954 .unwrap();
955 changed(&mut events);
956 registry.deregister_connection(active).unwrap();
957 changed(&mut events);
958 registry.deregister_connection(candidate).unwrap();
959 changed(&mut events);
960 registry
961 .register_candidate_with_control_ops(manifest(), 1, candidate, vec![])
962 .unwrap();
963 changed(&mut events);
964 registry.deregister_connection(candidate).unwrap();
965 changed(&mut events);
966 assert!(
967 !other.has_changed().unwrap(),
968 "other module must stay parked"
969 );
970 }
971
972 #[test]
973 fn subscription_before_read_keeps_a_change_until_waited_on() {
974 let registry = Registry::default();
975 let mut events = registry.subscribe_module_changes("watched").unwrap();
976 assert!(registry.get_module("watched").unwrap().is_none());
977 registry
978 .register_with_control_ops(manifest(), 1, ConnectionId::new(1), vec![])
979 .unwrap();
980 registry.get_module("watched").unwrap().unwrap();
982 registry
983 .replace_catalog_for_connection(ConnectionId::new(1), vec![], None, Some(true))
984 .unwrap();
985 changed(&mut events);
986 assert!(!events.has_changed().unwrap());
987 }
988}
989
990#[cfg(test)]
991mod publication_tests {
992 use super::*;
993
994 fn manifest() -> ModuleManifest {
995 ModuleManifest::builder("m", "1.0.0")
996 .protocol_ver(1)
997 .build()
998 }
999
1000 #[test]
1004 fn unpublished_registration_is_unlisted_until_published() {
1005 let registry = Registry::default();
1006 let connection = ConnectionId::new(1);
1007 registry
1008 .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1009 .unwrap();
1010 assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1011 assert!(registry.get_module("m").unwrap().is_some());
1012 assert_eq!(registry.list_registered_modules().unwrap().len(), 1);
1013 assert!(registry
1014 .published_registration(RegistrationSlot::Active("m"))
1015 .unwrap()
1016 .is_none());
1017 assert!(matches!(
1018 registry.register_with_control_ops(manifest(), 1, ConnectionId::new(2), vec![]),
1019 Err(RegistryError::DuplicateModuleId { .. })
1020 ));
1021 registry
1023 .replace_catalog_for_connection(connection, vec![], None, Some(true))
1024 .unwrap();
1025 assert_eq!(registry.generation().unwrap(), 0);
1026
1027 assert!(registry.publish_registration(connection).unwrap());
1028 let (generation, listed) = registry.list_modules().unwrap();
1029 assert_eq!(generation, 1);
1030 assert_eq!(listed.len(), 1);
1031 assert!(!registry.publish_registration(connection).unwrap());
1032 assert_eq!(registry.generation().unwrap(), 1);
1033 }
1034
1035 #[test]
1038 fn deregistering_an_unpublished_registration_leaves_the_generation() {
1039 let registry = Registry::default();
1040 let connection = ConnectionId::new(1);
1041 registry
1042 .register_unpublished_with_control_ops(manifest(), 1, connection, vec![])
1043 .unwrap();
1044 assert_eq!(registry.deregister_connection(connection).unwrap().len(), 1);
1045 assert_eq!(registry.list_modules().unwrap(), (0, Vec::new()));
1046 assert!(!registry.publish_registration(connection).unwrap());
1047 assert_eq!(registry.generation().unwrap(), 0);
1048 }
1049
1050 #[test]
1055 fn unpublished_candidate_is_hidden_from_published_lookups() {
1056 let registry = Registry::default();
1057 let candidate = ConnectionId::new(2);
1058 registry
1059 .register_unpublished_candidate_with_control_ops(manifest(), 1, candidate, vec![])
1060 .unwrap();
1061 assert!(registry
1062 .registration(RegistrationSlot::Candidate("m"))
1063 .unwrap()
1064 .is_some());
1065 assert!(registry
1066 .published_registration(RegistrationSlot::Candidate("m"))
1067 .unwrap()
1068 .is_none());
1069 assert!(registry
1070 .published_registration(RegistrationSlot::Connection(candidate))
1071 .unwrap()
1072 .is_none());
1073 assert!(registry.publish_registration(candidate).unwrap());
1074 assert!(registry
1075 .published_registration(RegistrationSlot::Candidate("m"))
1076 .unwrap()
1077 .is_some());
1078 assert_eq!(registry.generation().unwrap(), 0);
1079 }
1080}
1081
1082#[cfg(test)]
1083mod path_hazard_tests {
1084 use super::*;
1085 use crate::ConnectionId;
1086 use subc_protocol::manifest::ModuleManifest;
1087
1088 fn manifest(module_id: &str) -> ModuleManifest {
1089 ModuleManifest::builder(module_id, "0.1.0")
1090 .protocol_ver(1)
1091 .build()
1092 }
1093
1094 #[test]
1095 fn path_hazard_ids_are_refused_and_nothing_registers() {
1096 let registry = Registry::default();
1097 for (bad, reason_fragment) in [
1098 ("../escape", "path separator"),
1099 ("a/b", "path separator"),
1100 ("a\\b", "path separator"),
1101 ("..", "dot path component"),
1102 (".", "dot path component"),
1103 ("", "empty"),
1104 ("evil\u{0}id", "control character"),
1105 ] {
1106 let err = registry
1107 .register_with_control_ops(manifest(bad), 1, ConnectionId::new(7), Vec::new())
1108 .expect_err("path-hazard id must refuse");
1109 assert!(
1111 err.to_string().contains(reason_fragment),
1112 "id {bad:?}: expected {reason_fragment:?} in {err}"
1113 );
1114 }
1115 assert_eq!(registry.active_registration_count().unwrap(), 0);
1118 assert_eq!(registry.generation().unwrap(), 0);
1119 }
1120
1121 #[test]
1122 fn module_id_path_component_length_matches_shared_refusal_vectors() {
1123 let doc: serde_json::Value = serde_json::from_str(include_str!(
1124 "../tests/golden/module_id_path_component_refusals.json"
1125 ))
1126 .expect("refusal fixture parses");
1127
1128 for case in doc["vectors"].as_array().expect("vectors array") {
1129 let name = case["name"].as_str().expect("name");
1130 let module_id = case["module_id"]["unit"]
1131 .as_str()
1132 .expect("module_id unit")
1133 .repeat(
1134 case["module_id"]["repeat"]
1135 .as_u64()
1136 .expect("module_id repeat") as usize,
1137 );
1138 assert_eq!(
1139 module_id.len(),
1140 case["utf8_bytes"].as_u64().expect("utf8 bytes") as usize
1141 );
1142
1143 let expected = case["expect_reason"].as_str().map(str::to_owned);
1144 assert_eq!(
1145 module_id_path_hazard(&module_id).err(),
1146 expected,
1147 "shared refusal vector {name:?} diverged"
1148 );
1149 }
1150 }
1151
1152 #[test]
1153 fn working_id_shapes_register_including_namespace_colons() {
1154 let registry = Registry::default();
1155 for (i, good) in ["magic-context", "mcp:everything", "v1.2-module"]
1156 .iter()
1157 .enumerate()
1158 {
1159 registry
1160 .register_with_control_ops(
1161 manifest(good),
1162 1,
1163 ConnectionId::new(10 + i as u64),
1164 Vec::new(),
1165 )
1166 .unwrap_or_else(|err| panic!("id {good:?} must register: {err}"));
1167 }
1168 assert_eq!(registry.active_registration_count().unwrap(), 3);
1169 }
1170}
1171
1172#[cfg(test)]
1173mod swap_slot_tests {
1174 use super::*;
1175
1176 fn manifest(module_id: &str, ready: Option<bool>) -> ModuleManifest {
1177 let mut manifest = ModuleManifest::builder(module_id, "0.1.0").build();
1178 manifest.ready = ready;
1179 manifest
1180 }
1181
1182 const INCUMBENT: ConnectionId = ConnectionId(1);
1183 const CANDIDATE: ConnectionId = ConnectionId(2);
1184
1185 fn registry_with_candidate() -> Registry {
1186 let registry = Registry::default();
1187 registry
1188 .register_with_control_ops(manifest("m", None), 1, INCUMBENT, Vec::new())
1189 .unwrap();
1190 registry
1191 .register_candidate_with_control_ops(
1192 manifest("m", Some(false)),
1193 1,
1194 CANDIDATE,
1195 Vec::new(),
1196 )
1197 .unwrap();
1198 registry
1199 }
1200
1201 #[test]
1202 fn candidate_is_invisible_to_by_id_lookups_and_listing() {
1203 let registry = registry_with_candidate();
1204 let generation = registry.generation().unwrap();
1205 assert_eq!(
1206 registry.get_module("m").unwrap().unwrap().connection_id,
1207 INCUMBENT
1208 );
1209 let (listed_generation, listed) = registry.list_modules().unwrap();
1210 assert_eq!(listed.len(), 1);
1211 assert_eq!(listed[0].connection_id, INCUMBENT);
1212 assert_eq!(listed_generation, generation);
1213 assert_eq!(registry.active_registration_count().unwrap(), 1);
1214 assert_eq!(
1215 registry.get_candidate("m").unwrap().unwrap().connection_id,
1216 CANDIDATE
1217 );
1218 assert_eq!(
1219 registry
1220 .register_candidate_with_control_ops(
1221 manifest("m", None),
1222 1,
1223 ConnectionId(3),
1224 Vec::new()
1225 )
1226 .unwrap_err(),
1227 RegistryError::DuplicateModuleId {
1228 module_id: "m".to_string()
1229 }
1230 );
1231 }
1232
1233 #[test]
1234 fn promoted_candidate_keeps_its_verified_nonce_fact() {
1235 let registry = Registry::default();
1236 registry
1237 .register_unpublished_verified_candidate_with_control_ops(
1238 manifest("m", Some(true)),
1239 1,
1240 CANDIDATE,
1241 Vec::new(),
1242 )
1243 .unwrap();
1244 assert!(registry.publish_registration(CANDIDATE).unwrap());
1245 assert!(registry
1246 .list_modules_with_nonce_verification()
1247 .unwrap()
1248 .1
1249 .is_empty());
1250
1251 registry.promote_candidate("m").unwrap().unwrap();
1252 let (_, modules) = registry.list_modules_with_nonce_verification().unwrap();
1253 assert_eq!(modules.len(), 1);
1254 assert!(modules[0].1);
1255 }
1256
1257 #[test]
1260 fn candidate_catalog_update_reaches_the_candidate_registration() {
1261 let registry = registry_with_candidate();
1262 assert!(!registry.get_candidate("m").unwrap().unwrap().ready);
1263
1264 let updated = registry
1265 .replace_catalog_for_connection(CANDIDATE, Vec::new(), None, Some(true))
1266 .unwrap()
1267 .expect("the candidate's own connection finds its registration");
1268
1269 assert_eq!(updated.connection_id, CANDIDATE);
1270 assert!(registry.get_candidate("m").unwrap().unwrap().ready);
1271 assert_eq!(
1272 registry.get_module_by_connection(CANDIDATE).unwrap(),
1273 Some(updated)
1274 );
1275 assert_eq!(
1276 registry.get_module("m").unwrap().unwrap().connection_id,
1277 INCUMBENT,
1278 "a candidate's update must not touch the active registration"
1279 );
1280 }
1281
1282 #[test]
1283 fn promotion_swaps_slots_and_each_connection_still_deregisters_its_own() {
1284 let registry = registry_with_candidate();
1285 let before = registry.generation().unwrap();
1286 let cutover = registry.promote_candidate("m").unwrap().unwrap();
1287 assert_eq!(cutover.promoted.connection_id, CANDIDATE);
1288 assert_eq!(cutover.superseded.unwrap().connection_id, INCUMBENT);
1289 assert_ne!(registry.generation().unwrap(), before);
1290 assert_eq!(registry.promote_candidate("m").unwrap(), None);
1291
1292 assert_eq!(
1293 registry
1294 .registration(RegistrationSlot::Active("m"))
1295 .unwrap()
1296 .unwrap()
1297 .connection_id,
1298 CANDIDATE
1299 );
1300 assert!(registry
1301 .registration(RegistrationSlot::Candidate("m"))
1302 .unwrap()
1303 .is_none());
1304 assert!(registry
1305 .registration(RegistrationSlot::Connection(INCUMBENT))
1306 .unwrap()
1307 .is_some());
1308
1309 let closed = registry.deregister_connection(INCUMBENT).unwrap();
1310 assert_eq!(closed.len(), 1);
1311 assert_eq!(closed[0].connection_id, INCUMBENT);
1312 assert_eq!(closed[0].state, ChannelState::Closed);
1313 assert!(registry
1314 .registration(RegistrationSlot::Connection(INCUMBENT))
1315 .unwrap()
1316 .is_none());
1317 assert_eq!(
1318 registry.get_module("m").unwrap().unwrap().connection_id,
1319 CANDIDATE
1320 );
1321 }
1322
1323 #[test]
1324 fn a_dropped_candidate_deregisters_from_the_candidate_slot_only() {
1325 let registry = registry_with_candidate();
1326 let closed = registry.deregister_connection(CANDIDATE).unwrap();
1327 assert_eq!(closed.len(), 1);
1328 assert_eq!(closed[0].connection_id, CANDIDATE);
1329 assert!(registry.get_candidate("m").unwrap().is_none());
1330 assert_eq!(
1331 registry.get_module("m").unwrap().unwrap().connection_id,
1332 INCUMBENT
1333 );
1334 }
1335}