subc-daemon 0.49.3

Embeddable subc daemon: bootstrap, module supervision, and opaque-byte splice routing.
Documentation
//! Provider-owned discovery data and coalesced catalog notifications.
//!
//! Catalog reads use registration snapshots and in-memory spawn facts, never
//! the configuration owner's lock or keychain. Watchers await egress only in
//! their own tasks: neither registry nor forwarding locks span those awaits.

use super::*;
pub(crate) use crate::spawn_authority::declarations_digest;
use crate::spawn_authority::{ApprovedDeclarations, AuthorityCapture};
use subc_control::{CatalogOrigin, CatalogWatchRequest, CatalogWatchResponse};
use subc_protocol::provider_declarations::validate_hello_provider_declarations;

#[derive(Default)]
pub(super) struct CatalogCache {
    #[cfg(test)]
    pub(super) builds: u64,
    key: Option<(u64, u64)>,
    full: Vec<u8>,
    filtered: BTreeMap<String, Vec<u8>>,
    empty: Vec<u8>,
}

#[derive(Serialize)]
struct CatalogBody<'a> {
    op: &'static str,
    generation: u64,
    modules: &'a [CatalogEntry],
    subc_ops: &'a [String],
}

impl CatalogCache {
    fn body(&self, module_id: Option<&str>) -> Vec<u8> {
        match module_id {
            None => self.full.clone(),
            Some(module_id) => self.filtered.get(module_id).unwrap_or(&self.empty).clone(),
        }
    }
}

/// The config canonicalizer is the single numeric rule for declarations and
/// their digests. Refuse at HELLO so every accepted entry can be digested later.
pub(super) fn validate_hello_declarations(hello: &serde_json::Value) -> Result<(), String> {
    validate_hello_provider_declarations(hello).map_err(|err| err.to_string())?;
    if let Some(entries) = hello["manifest"]["provider_declarations"].as_object() {
        for (provider, entry) in entries {
            subc_config::canonical_json(entry).map_err(|err| {
                format!("invalid provider_declarations key {provider:?}: a number is outside the exactly representable range or the entry cannot be canonicalized: {err}")
            })?;
        }
    }
    Ok(())
}

impl ControlHandler {
    pub(super) fn cached_catalog_body(
        &self,
        corr: u64,
        module_id: Option<&str>,
    ) -> Result<Vec<u8>, RouterError> {
        let mut cache = self.catalog_cache.lock().unwrap_or_else(|p| p.into_inner());
        let key = (
            self.registry
                .generation()
                .map_err(|err| RouterError::backend(0, corr, format!("registry error: {err}")))?,
            self.catalog_readiness_revision
                .load(std::sync::atomic::Ordering::Acquire),
        );
        if cache.key == Some(key) {
            return Ok(cache.body(module_id));
        }
        let ClientControlResponse::CatalogList {
            generation,
            mut modules,
            subc_ops,
        } = self.catalog_list_snapshot(corr, None, true)?
        else {
            unreachable!("catalog snapshot returns a catalog response")
        };
        let encode = |modules: &[CatalogEntry]| {
            serde_json::to_vec(&CatalogBody {
                op: "catalog.list",
                generation,
                modules,
                subc_ops: &subc_ops,
            })
            .map_err(|err| {
                RouterError::backend(0, corr, format!("failed to encode catalog: {err}"))
            })
        };
        let mut filtered = BTreeMap::new();
        for entry in &mut modules {
            filtered.insert(
                entry.module_id.clone(),
                encode(std::slice::from_ref(entry))?,
            );
            entry.requested_declarations = None;
            entry.approved_declarations = None;
        }
        // Only registered IDs occupy the filtered cache; arbitrary absent filters
        // share the empty reply. No caller-provided value can add cache entries.
        *cache = CatalogCache {
            #[cfg(test)]
            builds: cache.builds + 1,
            key: Some(key),
            full: encode(&modules)?,
            filtered,
            empty: encode(&[])?,
        };
        // A concurrent registry or verdict update invalidates this snapshot on
        // the next request, including an update during the first serialization.
        if generation != key.0 {
            cache.key = None;
        }
        Ok(cache.body(module_id))
    }

    /// The spawn authority record is the only source of approvals;
    /// requested bytes alone never grant approval.
    fn catalog_approved_declarations(
        &self,
        authority: Option<&AuthorityCapture>,
    ) -> ApprovedDeclarations {
        authority
            .map(|capture| capture.approved.clone())
            .unwrap_or_else(ApprovedDeclarations::none_approved)
    }

    pub(super) fn catalog_discovery_entry(
        &self,
        registration: &crate::registry::ModuleRegistration,
        filtered: bool,
    ) -> Result<CatalogEntry, String> {
        let requested = registration
            .manifest
            .provider_declarations
            .clone()
            .unwrap_or_default();
        // Release the forwarding read lock before capturing authority state.
        // Connection identity distinguishes registrations even when their
        // module ids match during a process replacement.
        let authority = self
            .forwarding
            .target_authority_for_connection(registration.connection_id)
            .map_err(|err| err.to_string())?
            .and_then(|record| record.capture());
        let approved = self.catalog_approved_declarations(authority.as_ref());
        let mut entry = CatalogEntry::new(&registration.manifest.module_id, vec![], vec![]);
        entry.incarnation = Some(authority.as_ref().map_or_else(
            || self.supervisor.spawn_snapshot().cursor.daemon_incarnation,
            |capture| capture.incarnation.clone(),
        ));
        entry.spawn = authority.as_ref().map(|capture| capture.key.spawn);
        // Discovery only: providers authorize on the bind's `caller`.
        entry.first_party = Some(
            authority
                .as_ref()
                .is_some_and(|capture| capture.first_party),
        );
        entry.origin = Some(match authority.as_ref().map(|capture| capture.origin) {
            Some(subc_protocol::peer::CallerOrigin::Development) => CatalogOrigin::Development,
            Some(subc_protocol::peer::CallerOrigin::Release) => CatalogOrigin::Release,
            _ => CatalogOrigin::Other,
        });
        entry.requested_declarations_digest = Some(declarations_digest(&requested)?);
        entry.approved_declarations_digest = Some(approved.digest);
        if filtered {
            entry.requested_declarations = Some(requested);
            entry.approved_declarations = Some(approved.entries);
        }
        Ok(entry)
    }

    pub(super) fn handle_catalog_watch(
        &self,
        ctx: &RouteCtx,
        frame: Frame,
    ) -> Result<Vec<Frame>, RouterError> {
        if serde_json::from_slice::<CatalogWatchRequest>(&frame.body).is_err() {
            return Ok(vec![control_error_frame(
                &frame,
                "invalid_control_body",
                "malformed catalog.watch",
            )?]);
        }
        let mut receiver = self
            .registry
            .subscribe_catalog_changes()
            .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
        let initial = *receiver.borrow_and_update();
        let key = (ctx.connection_id, frame.header.corr);
        let mut streams = self
            .catalog_streams
            .lock()
            .unwrap_or_else(|p| p.into_inner());
        streams.retain(|_, task| !task.is_finished());
        if streams.contains_key(&key) {
            return Ok(vec![control_error_frame(
                &frame,
                "duplicate_subscription",
                "catalog.watch correlation id already in use",
            )?]);
        }
        let sink = ctx.egress.clone();
        let task = tokio::spawn(async move {
            let push = |generation| -> Result<Frame, RouterError> {
                let body = serde_json::to_vec(&CatalogWatchResponse::new(generation))
                    .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))?;
                Frame::build_with_version(
                    response_version(&frame),
                    FrameType::StreamData,
                    control_flags(),
                    0,
                    0,
                    frame.header.corr,
                    body,
                )
                .map_err(|err| RouterError::backend(0, frame.header.corr, err.to_string()))
            };
            let Ok(first) = push(initial) else {
                return;
            };
            if sink.send(first).await.is_err() {
                return;
            }
            while receiver.changed().await.is_ok() {
                // Wait for space before reading the value, so a slow watcher
                // gets the latest generation, not a replay of missed advances.
                let Ok(permit) = sink.reserve_owned().await else {
                    return;
                };
                let generation = *receiver.borrow_and_update();
                let Ok(next) = push(generation) else {
                    return;
                };
                if permit.send(next) {
                    return;
                }
            }
        });
        streams.insert(key, task.abort_handle());
        Ok(Vec::new())
    }

    pub(super) fn cancel_catalog_subscription(&self, connection: ConnectionId, corr: u64) -> bool {
        if let Some(task) = self
            .catalog_streams
            .lock()
            .unwrap_or_else(|p| p.into_inner())
            .remove(&(connection, corr))
        {
            task.abort();
            true
        } else {
            false
        }
    }

    pub(super) fn close_catalog_subscriptions(&self, connection: ConnectionId) {
        self.catalog_streams
            .lock()
            .unwrap_or_else(|p| p.into_inner())
            .retain(|(owner, _), task| {
                if *owner == connection {
                    task.abort();
                    false
                } else {
                    true
                }
            });
    }
}