blvm_sdk/composition/
types.rs

1//! Composition Framework Types
2//!
3//! Core types for module registry and node composition.
4
5use serde::{Deserialize, Serialize};
6use std::collections::HashMap;
7use std::path::PathBuf;
8use thiserror::Error;
9
10/// Module information from registry
11#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
12pub struct ModuleInfo {
13    /// Module name (unique identifier)
14    pub name: String,
15    /// Module version (semantic versioning)
16    pub version: String,
17    /// Human-readable description
18    pub description: Option<String>,
19    /// Module author
20    pub author: Option<String>,
21    /// Capabilities this module declares it can use
22    pub capabilities: Vec<String>,
23    /// Required dependencies (module names with versions)
24    pub dependencies: HashMap<String, String>,
25    /// Module entry point (binary name or path)
26    pub entry_point: String,
27    /// Path to module directory
28    pub directory: Option<PathBuf>,
29    /// Path to module binary
30    pub binary_path: Option<PathBuf>,
31    /// Module configuration schema (optional)
32    pub config_schema: HashMap<String, String>,
33}
34
35/// Module source for installation
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub enum ModuleSource {
38    /// Install from local path
39    Path(PathBuf),
40    /// Install from remote registry (URL, optional module name to select from index)
41    Registry {
42        url: String,
43        #[serde(skip_serializing_if = "Option::is_none")]
44        name: Option<String>,
45    },
46    /// Install from git repository
47    Git { url: String, tag: Option<String> },
48}
49
50/// Module lifecycle status
51#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
52pub enum ModuleStatus {
53    /// Module is not installed
54    NotInstalled,
55    /// Module is installed but not running
56    Stopped,
57    /// Module is initializing
58    Initializing,
59    /// Module is running normally
60    Running,
61    /// Module is stopping
62    Stopping,
63    /// Module has crashed or errored
64    Error(String),
65}
66
67/// Module health status
68#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
69pub enum ModuleHealth {
70    /// Module is healthy and responding
71    Healthy,
72    /// Module is degraded but functioning
73    Degraded,
74    /// Module is unhealthy or not responding
75    Unhealthy(String),
76    /// Health status unknown
77    Unknown,
78}
79
80/// Network type for node composition
81#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
82pub enum NetworkType {
83    /// Bitcoin mainnet
84    Mainnet,
85    /// Bitcoin testnet
86    Testnet,
87    /// Regression test network
88    Regtest,
89}
90
91/// Node specification for composition
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct NodeSpec {
94    /// Node name
95    pub name: String,
96    /// Node version
97    pub version: Option<String>,
98    /// Network type
99    pub network: NetworkType,
100    /// Modules to include
101    pub modules: Vec<ModuleSpec>,
102}
103
104/// Module specification in node composition
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct ModuleSpec {
107    /// Module name
108    pub name: String,
109    /// Module version (optional, uses latest if not specified)
110    pub version: Option<String>,
111    /// Whether module is enabled
112    pub enabled: bool,
113    /// Module-specific configuration
114    #[serde(default)]
115    pub config: HashMap<String, serde_json::Value>,
116}
117
118/// Loaded module information
119#[derive(Debug, Clone)]
120pub struct LoadedModule {
121    /// Module information
122    pub info: ModuleInfo,
123    /// Module status
124    pub status: ModuleStatus,
125    /// Module health
126    pub health: ModuleHealth,
127}
128
129/// Composed node result
130#[derive(Debug, Clone)]
131pub struct ComposedNode {
132    /// Node specification
133    pub spec: NodeSpec,
134    /// Loaded modules
135    pub modules: Vec<LoadedModule>,
136    /// Overall node status
137    pub status: NodeStatus,
138}
139
140/// Node status
141#[derive(Debug, Clone, PartialEq, Eq)]
142pub enum NodeStatus {
143    /// Node is stopped
144    Stopped,
145    /// Node is starting up
146    Starting,
147    /// Node is running
148    Running,
149    /// Node is stopping
150    Stopping,
151    /// Node has errors
152    Error(String),
153}
154
155/// Composition validation result
156#[derive(Debug, Clone)]
157pub struct ValidationResult {
158    /// Whether composition is valid
159    pub valid: bool,
160    /// Validation errors
161    pub errors: Vec<String>,
162    /// Validation warnings
163    pub warnings: Vec<String>,
164    /// Resolved dependencies
165    pub dependencies: Vec<ModuleInfo>,
166}
167
168/// Composition errors
169#[derive(Debug, Error)]
170pub enum CompositionError {
171    #[error("Module not found: {0}")]
172    ModuleNotFound(String),
173
174    #[error("Module version not found: {0} {1}")]
175    ModuleVersionNotFound(String, String),
176
177    #[error("Dependency resolution failed: {0}")]
178    DependencyResolutionFailed(String),
179
180    #[error("Module installation failed: {0}")]
181    InstallationFailed(String),
182
183    #[error("Invalid configuration: {0}")]
184    InvalidConfiguration(String),
185
186    #[error("Composition validation failed: {0}")]
187    ValidationFailed(String),
188
189    #[error("IO error: {0}")]
190    IoError(#[from] std::io::Error),
191
192    #[error("Serialization error: {0}")]
193    SerializationError(String),
194}
195
196pub type Result<T> = std::result::Result<T, CompositionError>;
blvm_sdk/composition/types.rs

blvm_sdk/composition/
types.rs
