frame-core 0.2.0

//! Component identity and declarations.

use std::time::Duration;

use frame_capability::CapabilityRequest;
use serde::{Deserialize, Serialize};

pub use frame_capability::{ComponentId, ComponentIdParseError};

/// Metadata declaring a native component's identity, process tree, and contracts.
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct ComponentMeta {
    /// Stable identity, independent of version and bytecode.
    pub id: ComponentId,
    /// Human-readable component name.
    pub name: String,
    /// Version that may change without changing [`Self::id`].
    pub version: String,
    /// Registered components that must be running before this component starts.
    pub requires: Vec<ComponentId>,
    /// Service-wiring contracts contributed to the system.
    ///
    /// This is lexically distinct from host authority in
    /// [`crate::capability`].
    pub provides: Vec<ServiceCapability>,
    /// Host-mediated authority requested by the manifest, never granted by declaration.
    pub needs: Vec<CapabilityRequest>,
    /// Retained specifications for linked child processes, in stop order.
    pub children: Vec<ChildSpec>,
    /// Explicit one-for-one policy; absence is rejected during registration.
    pub supervision: Option<SupervisionPolicy>,
}

/// A named service-wiring contract that a component contributes.
///
/// Host authority is represented separately by [`crate::capability::Capability`].
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct ServiceCapability {
    /// Globally unique capability identifier.
    pub id: String,
    /// Human-readable description.
    pub description: String,
}

/// A retained specification for one persistent linked child.
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct ChildSpec {
    /// Name used for status, commands, and failure reports.
    pub name: String,
    /// Loaded BEAM module containing the entrypoint.
    pub module: String,
    /// Exported entry function.
    pub function: String,
    /// Entrypoint arguments materialized when the child is spawned.
    pub arguments: Vec<ChildArgument>,
    /// Integer mailbox message used for a liveness round-trip.
    pub liveness_message: i64,
    /// Integer mailbox message requesting an orderly normal exit.
    pub stop_message: i64,
}

/// A serializable child-entrypoint argument supported by the native host seam.
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub enum ChildArgument {
    /// PID of the component's host-native supervisor.
    SupervisorPid,
    /// A BEAM small integer.
    Integer(i64),
    /// An atom interned in the scheduler's atom table.
    Atom(String),
}

/// Required one-for-one restart intensity declaration.
#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
pub struct SupervisionPolicy {
    /// Maximum replacements admitted during one rolling window.
    pub max_restarts: usize,
    /// Rolling window used to count replacements.
    pub window: Duration,
}