frame_core/
component.rs

1//! Component identity and declarations.
2
3use std::time::Duration;
4
5use frame_capability::CapabilityRequest;
6use serde::{Deserialize, Serialize};
7
8pub use frame_capability::{ComponentId, ComponentIdParseError};
9
10/// Metadata declaring a native component's identity, process tree, and contracts.
11#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
12pub struct ComponentMeta {
13    /// Stable identity, independent of version and bytecode.
14    pub id: ComponentId,
15    /// Human-readable component name.
16    pub name: String,
17    /// Version that may change without changing [`Self::id`].
18    pub version: String,
19    /// Registered components that must be running before this component starts.
20    pub requires: Vec<ComponentId>,
21    /// Service-wiring contracts contributed to the system.
22    ///
23    /// This is lexically distinct from host authority in
24    /// [`crate::capability`].
25    pub provides: Vec<ServiceCapability>,
26    /// Host-mediated authority requested by the manifest, never granted by declaration.
27    pub needs: Vec<CapabilityRequest>,
28    /// Retained specifications for linked child processes, in stop order.
29    pub children: Vec<ChildSpec>,
30    /// Explicit one-for-one policy; absence is rejected during registration.
31    pub supervision: Option<SupervisionPolicy>,
32    /// Declared component actions (F-6a R1); validated atomically at
33    /// registration, visible in the authoritative action snapshot only while
34    /// this component's incarnation is Running. Empty means no actions.
35    #[serde(default)]
36    pub actions: Vec<crate::action::ActionDeclaration>,
37    /// Declared view fragments (F-5a R1/R2); validated atomically at
38    /// registration against the host's caller-supplied byte limit, visible
39    /// in the authoritative fragment snapshot only while this component's
40    /// incarnation is Running. The ID set is static per incarnation;
41    /// content is live through the registry's update operation. Empty means
42    /// no fragments.
43    #[serde(default)]
44    pub fragments: Vec<crate::fragment::FragmentDeclaration>,
45}
46
47/// A named service-wiring contract that a component contributes.
48///
49/// Host authority is represented separately by [`crate::capability::Capability`].
50#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
51pub struct ServiceCapability {
52    /// Globally unique capability identifier.
53    pub id: String,
54    /// Human-readable description.
55    pub description: String,
56}
57
58/// A retained specification for one persistent linked child.
59#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
60pub struct ChildSpec {
61    /// Name used for status, commands, and failure reports.
62    pub name: String,
63    /// Loaded BEAM module containing the entrypoint.
64    pub module: String,
65    /// Exported entry function.
66    pub function: String,
67    /// Entrypoint arguments materialized when the child is spawned.
68    pub arguments: Vec<ChildArgument>,
69    /// Integer mailbox message used for a liveness round-trip.
70    pub liveness_message: i64,
71    /// Integer mailbox message requesting an orderly normal exit.
72    pub stop_message: i64,
73}
74
75/// A serializable child-entrypoint argument supported by the native host seam.
76#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
77pub enum ChildArgument {
78    /// PID of the component's host-native supervisor.
79    SupervisorPid,
80    /// A BEAM small integer.
81    Integer(i64),
82    /// An atom interned in the scheduler's atom table.
83    Atom(String),
84}
85
86/// Required one-for-one restart intensity declaration.
87#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
88pub struct SupervisionPolicy {
89    /// Maximum replacements admitted during one rolling window.
90    pub max_restarts: usize,
91    /// Rolling window used to count replacements.
92    pub window: Duration,
93}
frame_core/component.rs

frame_core/
component.rs
