canic-core 0.100.2

//! Module: config::schema::component_spec
//!
//! Responsibility: define flat Component Spec, direct-child, placement, and funding shapes.
//! Does not own: topology validation, placement execution, or runtime canister state.
//! Boundary: config schema re-exports these data shapes for validated models.

use crate::{
    cdk::{
        candid::{CandidType, Principal},
        types::Cycles,
    },
    ids::CanisterRole,
};
use serde::{Deserialize, Serialize};
use std::{
    collections::{BTreeMap, BTreeSet},
    fmt,
};

mod defaults {
    use super::Cycles;
    use crate::cdk::types::TC;

    pub const fn initial_cycles() -> Cycles {
        Cycles::new(5_000_000_000_000)
    }

    pub const fn topup_threshold() -> Cycles {
        Cycles::new(10 * TC)
    }

    pub const fn topup_amount() -> Cycles {
        Cycles::new(5 * TC)
    }

    pub const fn cycles_funding_max_per_request() -> Cycles {
        Cycles::new(crate::domain::policy::pure::cycles_funding::DEFAULT_MAX_PER_REQUEST)
    }

    pub const fn cycles_funding_max_per_child() -> Cycles {
        Cycles::new(crate::domain::policy::pure::cycles_funding::DEFAULT_MAX_PER_CHILD)
    }

    pub const fn cycles_funding_cooldown_secs() -> u64 {
        crate::domain::policy::pure::cycles_funding::DEFAULT_COOLDOWN_SECS
    }

    pub const fn component_maximum_children() -> u32 {
        super::DEFAULT_COMPONENT_MAXIMUM_CHILDREN
    }

    pub const fn component_maximum_registry_bytes() -> u64 {
        super::DEFAULT_COMPONENT_MAXIMUM_REGISTRY_BYTES
    }

    pub const fn component_cycles_funding_window_secs() -> u64 {
        super::DEFAULT_COMPONENT_CYCLES_FUNDING_WINDOW_SECS
    }

    pub const fn component_cycles_funding_maximum_cycles() -> Cycles {
        Cycles::new(super::DEFAULT_COMPONENT_CYCLES_FUNDING_MAXIMUM_CYCLES)
    }
}

/// Default aggregate direct-child ceiling for one concrete Component.
pub const DEFAULT_COMPONENT_MAXIMUM_CHILDREN: u32 = 4_096;
/// Default maximum canonical Component Registry bytes for one Component.
pub const DEFAULT_COMPONENT_MAXIMUM_REGISTRY_BYTES: u64 = 2_097_152;
/// Default aggregate Component cycles-funding budget window.
pub const DEFAULT_COMPONENT_CYCLES_FUNDING_WINDOW_SECS: u64 = 3_600;
/// Default aggregate Component cycles-funding budget per window.
pub const DEFAULT_COMPONENT_CYCLES_FUNDING_MAXIMUM_CYCLES: u128 = 1_000_000_000_000_000;

///
/// ComponentSpecConfig
///
/// Configuration for one permitted Component and its direct children.
/// Owned by config schema and validated before topology workflows use it.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ComponentSpecConfig {
    /// Role of the Component directly managed by a Fleet Subnet Root.
    pub component_role: CanisterRole,

    /// Fleet-wide ceiling for concrete instances of this Component Spec.
    pub maximum_instances: u32,

    #[serde(default)]
    pub limits: ComponentLimitsConfig,

    #[serde(
        default = "defaults::initial_cycles",
        deserialize_with = "Cycles::from_config"
    )]
    pub initial_cycles: Cycles,

    #[serde(default)]
    pub topup: Option<TopupPolicy>,

    #[serde(default)]
    pub cycles_funding: CyclesFundingPolicyConfig,

    #[serde(default)]
    pub scaling: Option<ScalingConfig>,

    #[serde(default)]
    pub sharding: Option<ShardingConfig>,

    #[serde(default)]
    pub binding: Option<BindingConfig>,

    #[serde(default)]
    pub auth: CanisterAuthConfig,

    #[serde(default)]
    pub standards: StandardsCanisterConfig,

    #[serde(default)]
    pub diagnostics: DiagnosticsCanisterConfig,

    #[serde(default)]
    pub metrics: MetricsCanisterConfig,

    /// Exact direct children owned by each instance of this Component.
    #[serde(default)]
    pub children: BTreeMap<CanisterRole, ComponentChildConfig>,
}

impl ComponentSpecConfig {
    /// Get the runtime configuration for this Component or one direct child.
    #[must_use]
    pub fn get_canister(&self, role: &CanisterRole) -> Option<CanisterConfig> {
        if role == &self.component_role {
            return Some(self.component_canister_config());
        }

        self.children
            .get(role)
            .map(ComponentChildConfig::canister_config)
    }

    /// The one direct Component role created from this Spec.
    #[must_use]
    pub fn auto_create_roles(&self) -> BTreeSet<CanisterRole> {
        BTreeSet::from([self.component_role.clone()])
    }

    /// The one direct Component role exposed through the root-local Directory.
    #[must_use]
    pub fn component_directory_roles(&self) -> BTreeSet<CanisterRole> {
        self.auto_create_roles()
    }

    /// All roles structurally owned by this Spec.
    pub fn roles(&self) -> impl Iterator<Item = &CanisterRole> {
        std::iter::once(&self.component_role).chain(self.children.keys())
    }

    /// Iterate the Component and direct children as common runtime projections.
    pub fn canister_configs(&self) -> impl Iterator<Item = (&CanisterRole, CanisterConfig)> + '_ {
        std::iter::once((&self.component_role, self.component_canister_config())).chain(
            self.children
                .iter()
                .map(|(role, child)| (role, child.canister_config())),
        )
    }

    /// Convert the structurally identified Component into the common runtime view.
    #[must_use]
    pub fn component_canister_config(&self) -> CanisterConfig {
        CanisterConfig {
            kind: CanisterKind::Service,
            initial_cycles: self.initial_cycles.clone(),
            topup: self.topup.clone(),
            icp_refill: None,
            cycles_funding: self.cycles_funding.clone(),
            scaling: self.scaling.clone(),
            sharding: self.sharding.clone(),
            binding: self.binding.clone(),
            auth: self.auth.clone(),
            standards: self.standards.clone(),
            diagnostics: self.diagnostics,
            metrics: self.metrics,
        }
    }
}

///
/// ComponentLimitsConfig
///
/// Configurable aggregate limits compiled into every concrete Component binding.
///

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ComponentLimitsConfig {
    #[serde(default = "defaults::component_maximum_children")]
    pub maximum_children: u32,

    #[serde(default = "defaults::component_maximum_registry_bytes")]
    pub maximum_registry_bytes: u64,

    #[serde(default)]
    pub cycles_funding: CyclesFundingBudgetConfig,
}

impl Default for ComponentLimitsConfig {
    fn default() -> Self {
        Self {
            maximum_children: defaults::component_maximum_children(),
            maximum_registry_bytes: defaults::component_maximum_registry_bytes(),
            cycles_funding: CyclesFundingBudgetConfig::default(),
        }
    }
}

///
/// CyclesFundingBudgetConfig
///
/// Aggregate cycles-funding ceiling for one Component over one bounded window.
///

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CyclesFundingBudgetConfig {
    #[serde(default = "defaults::component_cycles_funding_window_secs")]
    pub window_secs: u64,

    #[serde(
        default = "defaults::component_cycles_funding_maximum_cycles",
        deserialize_with = "Cycles::from_config"
    )]
    pub maximum_cycles: Cycles,
}

impl Default for CyclesFundingBudgetConfig {
    fn default() -> Self {
        Self {
            window_secs: defaults::component_cycles_funding_window_secs(),
            maximum_cycles: defaults::component_cycles_funding_maximum_cycles(),
        }
    }
}

///
/// ComponentChildConfig
///
/// Configuration for one direct child role owned by a Component instance.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ComponentChildConfig {
    pub kind: ComponentChildKind,
    pub maximum_instances: u32,

    #[serde(
        default = "defaults::initial_cycles",
        deserialize_with = "Cycles::from_config"
    )]
    pub initial_cycles: Cycles,

    #[serde(default)]
    pub topup: Option<TopupPolicy>,

    #[serde(default)]
    pub cycles_funding: CyclesFundingPolicyConfig,

    #[serde(default)]
    pub auth: CanisterAuthConfig,

    #[serde(default)]
    pub standards: StandardsCanisterConfig,

    #[serde(default)]
    pub diagnostics: DiagnosticsCanisterConfig,

    #[serde(default)]
    pub metrics: MetricsCanisterConfig,
}

impl ComponentChildConfig {
    #[must_use]
    pub fn canister_config(&self) -> CanisterConfig {
        CanisterConfig {
            kind: self.kind.into(),
            initial_cycles: self.initial_cycles.clone(),
            topup: self.topup.clone(),
            icp_refill: None,
            cycles_funding: self.cycles_funding.clone(),
            scaling: None,
            sharding: None,
            binding: None,
            auth: self.auth.clone(),
            standards: self.standards.clone(),
            diagnostics: self.diagnostics,
            metrics: self.metrics,
        }
    }
}

///
/// ComponentChildKind
///
/// Lifecycle class for a direct Component Child.
///

#[derive(CandidType, Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub enum ComponentChildKind {
    #[serde(rename = "singleton")]
    Singleton,

    #[serde(rename = "replica")]
    Replica,

    #[serde(rename = "shard")]
    Shard,

    #[serde(rename = "instance")]
    Instance,
}

impl fmt::Display for ComponentChildKind {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let label = match self {
            Self::Singleton => "singleton",
            Self::Replica => "replica",
            Self::Shard => "shard",
            Self::Instance => "instance",
        };
        formatter.write_str(label)
    }
}

impl From<ComponentChildKind> for CanisterKind {
    fn from(kind: ComponentChildKind) -> Self {
        match kind {
            ComponentChildKind::Singleton => Self::Singleton,
            ComponentChildKind::Replica => Self::Replica,
            ComponentChildKind::Shard => Self::Shard,
            ComponentChildKind::Instance => Self::Instance,
        }
    }
}

///
/// PoolImport
///
/// Per-environment import lists for canister pools.
/// Owned by config schema and consumed by pool import workflows.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PoolImport {
    /// Optional count of canisters to import immediately before queuing the rest.
    #[serde(default)]
    pub initial: Option<u16>,

    #[serde(default)]
    pub local: Vec<Principal>,

    #[serde(default)]
    pub ic: Vec<Principal>,
}

///
/// CanisterPool
///
/// Pool sizing and import configuration for root-managed canister pools.
/// Owned by config schema and validated before pool workflows use it.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CanisterPool {
    pub minimum_size: u8,
    #[serde(default)]
    pub import: PoolImport,
}

///
/// CanisterAuthConfig
///
/// Canister-local auth feature flags.
/// Owned by config schema and consumed by auth/cache setup.
///

// Build the implicit canister configuration for the mandatory store role.
pub fn implicit_wasm_store_canister_config() -> CanisterConfig {
    CanisterConfig {
        kind: CanisterKind::Singleton,
        initial_cycles: defaults::initial_cycles(),
        topup: None,
        icp_refill: None,
        cycles_funding: CyclesFundingPolicyConfig::default(),
        scaling: None,
        sharding: None,
        binding: None,
        auth: CanisterAuthConfig::default(),
        standards: StandardsCanisterConfig::default(),
        diagnostics: DiagnosticsCanisterConfig::default(),
        metrics: MetricsCanisterConfig::default(),
    }
}

/// Build the non-configurable Fleet Subnet Root runtime defaults.
#[must_use]
pub fn implicit_root_canister_config() -> CanisterConfig {
    CanisterConfig {
        kind: CanisterKind::Root,
        initial_cycles: defaults::initial_cycles(),
        topup: None,
        icp_refill: None,
        cycles_funding: CyclesFundingPolicyConfig::default(),
        scaling: None,
        sharding: None,
        binding: None,
        auth: CanisterAuthConfig::default(),
        standards: StandardsCanisterConfig::default(),
        diagnostics: DiagnosticsCanisterConfig::default(),
        metrics: MetricsCanisterConfig::default(),
    }
}

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CanisterAuthConfig {
    #[serde(default)]
    pub delegated_token_issuer: bool,

    #[serde(default)]
    pub delegated_token_verifier: bool,

    #[serde(default)]
    pub role_attestation_cache: bool,
}

///
/// StandardsCanisterConfig
///
/// Canister-local standards feature flags.
/// Owned by config schema and consumed by standards dispatch.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct StandardsCanisterConfig {
    #[serde(default)]
    pub icrc21: bool,
}

///
/// DiagnosticsCanisterConfig
///
/// Canister-local diagnostics feature flags.
/// Owned by config schema and consumed by diagnostics endpoints.
///

#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DiagnosticsCanisterConfig {
    #[serde(default)]
    pub memory_ledger: bool,
}

///
/// CanisterConfig
///
/// Configuration for one declared canister role.
/// Owned by config schema and consumed by bootstrap and topology workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CanisterConfig {
    /// Kind and placement semantics for this canister role.
    pub kind: CanisterKind,

    #[serde(
        default = "defaults::initial_cycles",
        deserialize_with = "Cycles::from_config"
    )]
    pub initial_cycles: Cycles,

    #[serde(default)]
    pub topup: Option<TopupPolicy>,

    #[serde(default)]
    pub icp_refill: Option<IcpRefillPolicy>,

    #[serde(default)]
    pub cycles_funding: CyclesFundingPolicyConfig,

    #[serde(default)]
    pub scaling: Option<ScalingConfig>,

    #[serde(default)]
    pub sharding: Option<ShardingConfig>,

    #[serde(default)]
    pub binding: Option<BindingConfig>,

    #[serde(default)]
    pub auth: CanisterAuthConfig,

    #[serde(default)]
    pub standards: StandardsCanisterConfig,

    #[serde(default)]
    pub diagnostics: DiagnosticsCanisterConfig,

    #[serde(default)]
    pub metrics: MetricsCanisterConfig,
}

impl CanisterConfig {
    /// Resolve the effective metrics profile for a canister role.
    #[must_use]
    pub fn resolved_metrics_profile(&self, role: &CanisterRole) -> MetricsProfile {
        if let Some(profile) = self.metrics.profile {
            return profile;
        }

        if self.kind == CanisterKind::Root || role.is_root() {
            return MetricsProfile::Root;
        }

        if role.is_wasm_store() {
            return MetricsProfile::Storage;
        }

        if self.scaling.is_some() || self.sharding.is_some() || self.binding.is_some() {
            return MetricsProfile::Hub;
        }

        MetricsProfile::Leaf
    }

    /// Return child roles referenced by exact role-bearing placement fields.
    #[must_use]
    pub fn role_bearing_child_roles(&self) -> Vec<&CanisterRole> {
        let scaling_roles = self
            .scaling
            .iter()
            .flat_map(|scaling| scaling.pools.values().map(|pool| &pool.canister_role));
        let sharding_roles = self
            .sharding
            .iter()
            .flat_map(|sharding| sharding.pools.values().map(|pool| &pool.canister_role));
        let binding_roles = self
            .binding
            .iter()
            .flat_map(|binding| binding.pools.values().map(|pool| &pool.canister_role));

        scaling_roles
            .chain(sharding_roles)
            .chain(binding_roles)
            .collect()
    }
}

///
/// CyclesFundingPolicyConfig
///
/// Parent funding limits applied when this role requests cycles from its parent.
/// Owned by config schema and consumed by cycles funding authorization.
///

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CyclesFundingPolicyConfig {
    #[serde(
        default = "defaults::cycles_funding_max_per_request",
        deserialize_with = "Cycles::from_config"
    )]
    pub max_per_request: Cycles,

    #[serde(
        default = "defaults::cycles_funding_max_per_child",
        deserialize_with = "Cycles::from_config"
    )]
    pub max_per_child: Cycles,

    #[serde(default = "defaults::cycles_funding_cooldown_secs")]
    pub cooldown_secs: u64,
}

impl Default for CyclesFundingPolicyConfig {
    fn default() -> Self {
        Self {
            max_per_request: defaults::cycles_funding_max_per_request(),
            max_per_child: defaults::cycles_funding_max_per_child(),
            cooldown_secs: defaults::cycles_funding_cooldown_secs(),
        }
    }
}

///
/// MetricsCanisterConfig
///
/// Canister-local metrics profile override.
/// Owned by config schema and consumed by metrics setup.
///

#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct MetricsCanisterConfig {
    #[serde(default)]
    pub profile: Option<MetricsProfile>,
}

///
/// MetricsProfile
///
/// Metrics collection profile for a configured canister role.
/// Owned by config schema and consumed by metrics setup.
///

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MetricsProfile {
    Leaf,
    Hub,
    Storage,
    Root,
    Full,
}

///
/// CanisterKind
///
/// Kind semantics for canister roles within the topology.
///
/// Do not encode parent relationships here; this is role-level intent only.
///

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CanisterKind {
    Root,
    Service,
    Singleton,
    Replica,
    Shard,
    Instance,
}

impl fmt::Display for CanisterKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let label = match self {
            Self::Root => "root",
            Self::Service => "service",
            Self::Singleton => "singleton",
            Self::Replica => "replica",
            Self::Shard => "shard",
            Self::Instance => "instance",
        };

        f.write_str(label)
    }
}

///
/// TopupPolicy
///
/// Cycle top-up policy for one configured canister role.
/// Owned by config schema and consumed by funding workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct TopupPolicy {
    #[serde(
        default = "defaults::topup_threshold",
        deserialize_with = "Cycles::from_config"
    )]
    pub threshold: Cycles,

    #[serde(
        default = "defaults::topup_amount",
        deserialize_with = "Cycles::from_config"
    )]
    pub amount: Cycles,
}

impl Default for TopupPolicy {
    fn default() -> Self {
        Self {
            threshold: defaults::topup_threshold(),
            amount: defaults::topup_amount(),
        }
    }
}

///
/// IcpRefillPolicy
///
/// Manual ICP-funded cycle refill policy for the root canister.
/// Owned by config schema and consumed by ICP refill workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct IcpRefillPolicy {
    pub max_refill_e8s_per_call: u64,

    #[serde(default)]
    pub min_xdr_permyriad_per_icp: Option<u64>,

    #[serde(default)]
    pub ledger_canister_id: Option<Principal>,

    #[serde(default)]
    pub cmc_canister_id: Option<Principal>,

    #[serde(default)]
    pub allow_ic_system_canister_overrides: bool,
}

///
/// ScalingConfig
///
/// Stateless replica-group placement configuration.
/// Owned by config schema and consumed by scaling placement workflows.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ScalingConfig {
    #[serde(default)]
    pub pools: BTreeMap<String, ScalePool>,
}

///
/// ScalePool
///
/// One stateless replica group.
/// Owned by config schema and consumed by scaling placement workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ScalePool {
    pub canister_role: CanisterRole,

    #[serde(default)]
    pub policy: ScalePoolPolicy,
}

///
/// ScalePoolPolicy
///
/// Worker bounds for one stateless replica group.
/// Owned by config schema and consumed by scaling placement policy.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct ScalePoolPolicy {
    /// Number of replica canisters to create during startup warmup
    pub initial_workers: u32,

    /// Minimum number of replica canisters to keep alive
    pub min_workers: u32,

    /// Maximum number of replica canisters to allow
    pub max_workers: u32,
}

impl Default for ScalePoolPolicy {
    fn default() -> Self {
        Self {
            initial_workers: 1,
            min_workers: 1,
            max_workers: 32,
        }
    }
}

///
/// ShardingConfig
///
/// Stateful partitioned shard-pool configuration.
/// Owned by config schema and consumed by sharding placement workflows.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ShardingConfig {
    #[serde(default)]
    pub pools: BTreeMap<String, ShardPool>,
}

///
/// BindingConfig
///
/// Keyed instance placement binding configuration.
/// Owned by config schema and consumed by keyed placement workflows.
///

#[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BindingConfig {
    #[serde(default)]
    pub pools: BTreeMap<String, BindingPool>,
}

///
/// BindingPool
///
/// One keyed instance placement binding pool.
/// Owned by config schema and consumed by keyed placement workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct BindingPool {
    pub canister_role: CanisterRole,
    pub key_name: String,
}

///
/// ShardPool
///
/// One stateful shard placement pool.
/// Owned by config schema and consumed by sharding placement workflows.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ShardPool {
    pub canister_role: CanisterRole,

    #[serde(default)]
    pub policy: ShardPoolPolicy,
}

///
/// ShardPoolPolicy
///
/// Capacity and shard-count bounds for one shard pool.
/// Owned by config schema and consumed by sharding placement policy.
///

#[derive(Clone, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields, default)]
pub struct ShardPoolPolicy {
    pub capacity: u32,
    pub initial_shards: u32,
    pub max_shards: u32,
}

impl Default for ShardPoolPolicy {
    fn default() -> Self {
        Self {
            capacity: 1_000,
            initial_shards: 1,
            max_shards: 4,
        }
    }
}

// -----------------------------------------------------------------------------
// Tests
// -----------------------------------------------------------------------------

#[cfg(test)]
mod tests;