Skip to main content

subc_daemon/
registry.rs

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/// Per-connection identity assigned by [`crate::Router`] while serving a socket.
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
14pub struct ConnectionId(u64);
15
16impl ConnectionId {
17    /// Synthetic connection id used by unit tests. Router-issued connection ids
18    /// start at 1, so this 0 value never collides with a real socket owner.
19    #[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/// Lifecycle state for a module's channel allocation.
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub enum ChannelState {
34    Active,
35    Closed,
36}
37
38/// Why a module registration stopped belonging to its connection.
39#[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/// Registry record for one active module registration.
63#[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
73/// Active routing registrations and their publication state from one lock.
74pub(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/// Which registration a lookup or a lifecycle wait is about.
88///
89/// A module id alone stops naming one process once a blue/green swap runs two
90/// processes under the same id: the incumbent in the active slot, the
91/// replacement in the candidate slot, and, after cutover, the old incumbent
92/// demoted until its connection goes away. A wait keyed on the bare id would
93/// confuse them (a successful swap never empties the id's active slot, and a
94/// candidate's "has it registered yet" would be answered by the incumbent).
95#[derive(Debug, Clone, Copy, PartialEq, Eq)]
96pub enum RegistrationSlot<'a> {
97    /// The routable registration for this module id. This is what every plain
98    /// start, stop and restart path means by "the module is registered".
99    Active(&'a str),
100    /// A swap candidate registered under this module id and not yet promoted.
101    Candidate(&'a str),
102    /// Whatever registration this module connection holds, in any slot.
103    Connection(ConnectionId),
104}
105
106/// The result of promoting a module's candidate registration to active.
107#[derive(Debug, Clone, PartialEq)]
108pub struct RegistryCutover {
109    /// The registration that is now active (the former candidate).
110    pub promoted: ModuleRegistration,
111    /// The former active registration, now demoted. `None` when the incumbent
112    /// had already gone away before the promotion.
113    pub superseded: Option<ModuleRegistration>,
114}
115
116/// Control-plane registry for module manifests and supervision ownership.
117///
118/// Duplicate active `module_id`s are rejected rather than replaced. Rejection is
119/// the safer v1 behavior because replacing a still-connected module could hijack
120/// in-flight routes. Stale registrations are removed by connection cleanup; a
121/// reconnect after the old connection drops can then register the same id again.
122///
123/// A blue/green swap is the one sanctioned way two processes hold the same id.
124/// The replacement registers into a separate candidate slot, which every by-id
125/// lookup ignores, so it stays unroutable until [`Registry::promote_candidate`]
126/// swaps it in. The old incumbent is then kept as "superseded" until its
127/// connection deregisters. Lookups keyed by connection id search all three
128/// slots, because a connection must be able to update and remove its own
129/// registration whichever slot it currently sits in.
130#[derive(Debug, Default)]
131pub struct Registry {
132    inner: Mutex<RegistryInner>,
133}
134
135#[derive(Debug, Default)]
136struct RegistryInner {
137    /// Only subscribed module ids have a sender. Changes coalesce, and writers
138    /// never wait for a supervisor to receive them.
139    // The value counts accepted active registrations. Keep that evidence even
140    // when register and disconnect coalesce before a supervisor receives them.
141    module_changes: HashMap<String, watch::Sender<u64>>,
142    modules: HashMap<String, ModuleRegistration>,
143    /// Swap candidates by module id: registered, never routable, never listed.
144    candidates: HashMap<String, ModuleRegistration>,
145    /// Former incumbents demoted by a promotion, kept only so their own
146    /// connection can still find and remove them. Never routable, never listed.
147    superseded: Vec<ModuleRegistration>,
148    /// Connections whose HELLO passed the launch-nonce check required for a
149    /// reserved module or swap candidate. Kept outside ModuleRegistration so
150    /// adding this catalog fact does not break callers that construct the public
151    /// registration struct.
152    nonce_verified: HashSet<ConnectionId>,
153    /// The active connection that displaced each superseded registration.
154    superseded_by: HashMap<ConnectionId, ConnectionId>,
155    /// Connections whose registration is reserved but not yet published.
156    ///
157    /// A HELLO registers in the registry before the daemon installs the
158    /// module's forwarding endpoint, and until that endpoint exists a
159    /// `route.open` to the module cannot be relayed. A registration in this set
160    /// already holds its module id (a duplicate HELLO is refused) and is found
161    /// by every lookup except two: [`Registry::list_modules`], which feeds
162    /// `catalog.list`, and [`Registry::published_registration`], which the swap
163    /// supervisor reads to decide that a candidate has registered. Adding a
164    /// registration to this set does not bump the catalog generation;
165    /// [`Registry::publish_registration`] removes it and bumps the generation
166    /// in the same critical section, so a catalog reader sees the module and
167    /// the new generation together.
168    unpublished: HashSet<ConnectionId>,
169    generation: u64,
170}
171
172impl Registry {
173    /// Subscribe before reading a registration so a change between the read
174    /// and the supervisor's wait remains pending on this receiver.
175    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        // Retired supervisors must not leave an ever-growing set of ids.
181        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    /// Register a module manifest with the module's effective granted control op set.
192    ///
193    /// The registration is published at once: it is listed by
194    /// [`Self::list_modules`] and bumps the catalog generation. The HELLO path
195    /// uses [`Self::register_unpublished_with_control_ops`] instead, because it
196    /// still has to install the module's forwarding endpoint.
197    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    /// Register a module manifest without listing it yet.
215    ///
216    /// The registration holds its module id and is visible to every lookup
217    /// except [`Self::list_modules`] (and so `catalog.list`) and
218    /// [`Self::published_registration`]. The catalog generation does not move.
219    /// Call [`Self::publish_registration`] once the module can actually be
220    /// routed to; if that never becomes possible, deregistering the connection
221    /// removes the entry without the catalog ever having listed it.
222    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    /// Register a module after its HELLO is accepted, without listing it before forwarding is installed.
240    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(&registration.manifest.module_id) {
298            sender.send_modify(|accepted| *accepted = accepted.wrapping_add(1));
299        }
300        Ok(registration)
301    }
302
303    /// Register a swap candidate for `manifest.module_id` into the candidate slot.
304    ///
305    /// The candidate is invisible to [`Self::get_module`], [`Self::list_modules`]
306    /// and every other by-id lookup until [`Self::promote_candidate`]. An active
307    /// registration for the id is not required, because the incumbent may die
308    /// while the swap is open; deciding whether a candidate may register at all
309    /// belongs to the caller that admits it. A second candidate for the same id
310    /// is refused.
311    ///
312    /// The candidate is published at once, meaning candidate-slot lookups
313    /// through [`Self::published_registration`] return it immediately. The
314    /// HELLO path uses
315    /// [`Self::register_unpublished_candidate_with_control_ops`] instead.
316    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    /// Register a swap candidate that [`Self::published_registration`] does not
334    /// return until [`Self::publish_registration`] is called for its
335    /// connection. The swap supervisor reads that lookup to decide the
336    /// candidate has registered, and it promotes a ready candidate straight
337    /// away; promoting one whose forwarding endpoint is not installed yet would
338    /// fail the cutover.
339    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    /// Register a blue/green swap candidate after its required launch nonce has been verified.
357    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(&registration.manifest.module_id);
410        Ok(registration)
411    }
412
413    /// Publish the registration `connection_id` holds, in whichever slot.
414    ///
415    /// For an active registration this is the moment `catalog.list` starts
416    /// listing the module, and the catalog generation advances under the same
417    /// lock, so no reader can see the new generation without the module or the
418    /// module without the new generation. A candidate is not listed either way;
419    /// publishing it only makes it visible to
420    /// [`Self::published_registration`].
421    ///
422    /// Returns `false` when there is nothing to publish: the connection holds
423    /// no registration any more, or it was already published.
424    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    /// Move the candidate for `module_id` into the active slot and demote the
441    /// previous active registration, in one registry critical section.
442    ///
443    /// Returns `Ok(None)` when there is no candidate to promote. Bumps the
444    /// catalog generation, because the listed registration for the id changed.
445    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    /// The ACTIVE registration for `module_id`. Candidates and superseded
480    /// incumbents are never returned: this is the lookup routing decisions use.
481    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    /// Unlike the published-only catalog view, admission sees staged active
486    /// registrations too, exactly as `get_module` does. A target whose
487    /// registration is accepted but not yet published in the catalog must
488    /// answer `target_unavailable`, not `unknown_module`, on an ordinary open.
489    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    /// The swap candidate registered for `module_id`, if any.
500    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    /// The registration held in one specific slot. See [`RegistrationSlot`].
508    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    /// The catalog generation and the active registrations `catalog.list`
527    /// shows. Unpublished registrations (see
528    /// [`Self::register_unpublished_with_control_ops`]) are left out.
529    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(&registration.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    /// List published active registrations together with their HELLO nonce-verification status.
542    /// Both values are captured under the registry lock so a concurrent swap or
543    /// disconnect cannot separate a registration from its verification fact.
544    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(&registration.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(&registration.connection_id),
560                )
561            })
562            .collect();
563        Ok((inner.generation, modules))
564    }
565
566    /// Every active registration, including unpublished ones.
567    ///
568    /// For the capability evaluator and the capability deny census, which
569    /// count a module as soon as it has registered. Whether `catalog.list`
570    /// shows the module yet does not change their verdicts.
571    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    /// Like [`Self::registration`], but a registration that is not published
579    /// yet is reported as absent.
580    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(&registration.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    /// The registration owned by `connection_id`, searching the active,
617    /// candidate and superseded slots in that order.
618    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    /// Replace the provider role list and, when supplied, the attested capability
629    /// declaration for the module owned by `connection_id`.
630    ///
631    /// Searches every slot: a swap candidate declares itself ready through this
632    /// call, and if only the active slot were searched its update would find
633    /// nothing and the candidate would never become ready. Only a change to the
634    /// active slot bumps the catalog generation, because only the active slot is
635    /// listed, and only once that registration is published.
636    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            // Pending binds rely on this declaration while the target module's outbound queue is full.
659            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    /// Deregister every module owned by a dropped connection, in any slot.
682    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        // A registration that was never published was never listed, so
699        // removing it leaves the catalog, and its generation, as they were.
700        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(&registration.connection_id);
740            inner.notify_module_changed(&registration.manifest.module_id);
741            let replaced = superseded_connections.contains(&registration.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(&registration.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/// Which internal slot a connection-keyed lookup found its registration in.
783#[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    /// The id is unusable as a single path component. Enforced at
856    /// registration because the daemon MINTS A STORAGE DESCRIPTOR from the
857    /// self-claimed id verbatim (`<data_home>/cortexkit/<module_id>/store.db`),
858    /// so an id carrying separators or dot components is a path-traversal or
859    /// store-collision primitive handed to whoever claims it (issue #32). The
860    /// derivations deliberately do NOT sanitize instead: sanitizing here would
861    /// silently re-path every deployed store and desynchronize the Rust and TS
862    /// derivations, while refusal changes nothing for any id that ever worked.
863    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
891/// Why `module_id` cannot serve as a single path component, or `Ok(())`.
892///
893/// This is a REFUSAL predicate, not a sanitizer: every currently-working fleet
894/// id passes untouched, and anything refused here never worked meaningfully --
895/// it either escaped `<data_home>/cortexkit/` (separators, dot components) or
896/// aliased another module's store (`a/b` vs `a//b` collapsing on POSIX).
897/// Colons are allowed: reserved-namespace children (`mcp:...`) register today
898/// and a colon cannot traverse. Windows path legality is the store library's
899/// concern, not an identity rule.
900pub 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        // Superseded connections can still update and deregister their slot.
952        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        // Neither a later lookup nor a coalesced catalog update consumes it.
981        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    /// An unpublished registration holds its id and answers routing lookups,
1001    /// but `list_modules` leaves it out and the generation stays put until
1002    /// it is published; publishing lists it and bumps the generation once.
1003    #[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        // A catalog update before publication does not move the generation.
1022        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    /// Removing a registration that was never published leaves no catalog
1036    /// trace: the generation does not move, and a later publish is a no-op.
1037    #[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    /// An unpublished candidate holds the candidate slot but
1051    /// `published_registration` does not return it until it is published.
1052    /// Publishing a candidate does not bump the generation: candidates are
1053    /// never listed.
1054    #[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            // Reason asserted so a predicate throwing the WRONG refusal fails.
1110            assert!(
1111                err.to_string().contains(reason_fragment),
1112                "id {bad:?}: expected {reason_fragment:?} in {err}"
1113            );
1114        }
1115        // THE EFFECT, not just the verdicts: no refusal left a registration
1116        // behind, and the generation never moved.
1117        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    /// Without the candidate slot in the connection-keyed search, this update
1258    /// returns `Ok(None)` and the candidate never becomes ready.
1259    #[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}