mecha10_core/

prelude.rs

// Mecha10 Framework Prelude
//
// This module provides a comprehensive set of re-exports that covers
// everything needed for typical node development. The goal is to enable
// developers to write nodes with a single import:
//
// ```rust
// use mecha10::prelude::*;
// ```

// ============================================================================
// Core Traits and Types
// ============================================================================

// Core execution context
pub use crate::context::{
    Context, InfrastructureConfig, MinioConfig, MlflowConfig, PostgresConfig, Receiver, RedisConfig,
};

// Stream combinators
pub use crate::stream::ReceiverExt;

// Conditional publishing
pub use crate::publish::ContextPublishExt;

// Request/Response (RPC) pattern
pub use crate::rpc::{Request, Response, RpcExt};

// Streaming RPC for long-running operations
pub use crate::rpc_streaming::{
    StreamError, StreamMessage, StreamPayload, StreamReceiver, StreamSender, StreamingRpcExt,
};

// Service discovery
pub use crate::discovery::{DiscoveryExt, NodeMetadata, NodeStatus};

// Schema registry with versioning
pub use crate::schema::{
    CompatibilityCheck, CompatibilityMode, MessageSchema, MessageVersionInfo, SchemaEvolution, SchemaField,
    SchemaRegistryExt, SchemaVersioningExt,
};

// Authorization
pub use crate::auth::{AuthExt, Permission, Policy, Rule};

// Secrets management
pub use crate::secrets::{
    EnvironmentBackend, RedisBackend, SecretBackend, SecretsConfig, SecretsManager, VaultBackend,
};

// Health monitoring
pub use crate::health::{
    HealthMonitor, HealthReport, HealthReporter, HealthReportingExt, NodeHealthInfo, SystemHealth,
};

// Behavior interrupt trigger for autonomous behavior control
pub use crate::behavior_interrupt::{
    BehaviorControl, BehaviorInterruptConfig, BehaviorInterruptTrigger, InterruptMode,
};

// Metrics collection
pub use crate::metrics::{Counter, Gauge, Histogram, MetricsRegistry, NodeMetrics};

// Rate limiting
pub use crate::rate_limit::{MultiKeyRateLimiter, RateLimit, RateLimiter, RateLimiterManager};

// Circuit breaker for fault tolerance
pub use crate::circuit_breaker::{CircuitBreaker, CircuitBreakerConfig, CircuitState};

// Dead letter queue for failed messages
pub use crate::dead_letter::{DeadLetterConfig, DeadLetterQueue, FailedMessage};

// JSON Schema validation for configuration files
pub use crate::schema_validation::{
    export_project_schema, get_node_config_schema, get_project_schema, load_and_validate_project,
    validate_node_config_json, validate_project_config, validate_project_json,
};

// Dependency resolution for node ordering
pub use crate::dependency::{create_graph, DependencyGraph, ShutdownPlan, StartupPlan};

// Lifecycle event schemas for mode-based management
pub use crate::lifecycle::{
    get_timestamp_ms, topic_node_lifecycle, topic_node_status, ModeChanged, ModeError, ModeRequest,
    NodeLifecycleAction, NodeLifecycleEvent, NodeLifecycleStatus, NodeStatusEvent, TOPIC_MODE_CHANGED,
    TOPIC_MODE_ERROR, TOPIC_MODE_REQUEST,
};

// Topic registry for runtime introspection
pub use crate::topic_registry::{TopicInfo, TopicRegistry, TopologyStats};

// Topic utilities (categorization, formatting, metadata)
pub use crate::topic_utils::{extract_category, format_elapsed_time, TopicMetadata};

// Persistent state storage abstraction
pub use crate::state::{
    FilesystemStateManager, MemoryStateManager, StateManager, StateOptions, StateSnapshot, VersionedState,
};

// Graceful degradation and recovery policies
pub use crate::recovery::{
    BackoffStrategy, DegradationMode, RecoveryAction, RecoveryAttempt, RecoveryHistory, RecoveryManager,
    RecoveryPolicy, RecoveryPolicyBuilder, RecoveryStats,
};

// Distributed tracing
pub use crate::tracing_otel::{
    JaegerExporter, SpanBuilder, SpanData, TraceContext, TraceExporter, TracedMessage, TracingConfig, TracingExt,
    TracingHandle, ZipkinExporter,
};

// Performance profiling
pub use crate::profiling::{
    measure_latency, ExecutionStats, LatencyStats, MemoryStats, PerformanceMetrics, PerformanceReport, ProfilingExt,
    ThroughputStats, TimerGuard,
};

// Service pattern for infrastructure components
pub use crate::service::Service;
pub use crate::service_manager::ServiceManager;

// Node lifecycle management
pub use crate::node::{run_node, HealthPriority, HealthReportingConfig, HealthStatusExt, Node, NodeImpl, RateConfig};

// Configuration loading and validation
pub use crate::config::{load_and_validate, load_config, load_config_from_env, substitute_env_vars, Validate};

// Model configuration utilities for AI nodes
pub use crate::model::{load_labels, load_model_config, CustomLabelsConfig, ModelConfig, PreprocessingConfig};

// Convenience macros for reducing boilerplate
pub use crate::run_node_simple;
pub use crate::run_node_with_instance;

// Message trait
pub use crate::messages::Message;

// All shared types (Image, LaserScan, Odometry, Twist, etc.)
pub use crate::types::*;

// ============================================================================
// Error Handling
// ============================================================================

/// Result type with Mecha10 error
pub use crate::error::{Mecha10Error, Result};

// ============================================================================
// Async Runtime
// ============================================================================

/// async_trait macro for async trait methods
pub use async_trait::async_trait;

/// Tokio re-exports
pub use tokio::{
    self, select,
    time::{interval, sleep, timeout, Duration, Instant},
};

/// JoinHandle for background tasks
pub use tokio::task::JoinHandle;

// ============================================================================
// Serialization
// ============================================================================

/// Serde re-exports
pub use serde::{Deserialize, Serialize};
pub use serde_json::{self, json, Value as JsonValue};

// ============================================================================
// Logging
// ============================================================================

/// Tracing macros for structured logging
pub use tracing::{debug, error, info, instrument, trace, warn, Level};

// ============================================================================
// Derive Macros (when available)
// ============================================================================

/// Derive macro for Node trait
///
/// # Example
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Node)]
/// #[subscribe("/input")]
/// #[publish("/output")]
/// struct MyNode {
///     config: MyConfig,
/// }
/// ```
#[cfg(feature = "macros")]
pub use mecha10_macros::Node;

/// Derive macro for Message trait
///
/// Automatically implements: Debug, Clone, Serialize, Deserialize, Message
///
/// # Example
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Message)]
/// struct CustomMessage {
///     pub value: f32,
///     pub timestamp: u64,
/// }
/// ```
// Note: Message trait is defined in messages::mod, no derive macro needed
// #[cfg(feature = "macros")]
// pub use mecha10_macros::Message as DeriveMessage;
/// Derive macro for Config with validation
///
/// # Example
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Config)]
/// struct MyConfig {
///     #[validate(range = "0.0..=10.0")]
///     max_speed: f32,
/// }
/// ```
#[cfg(feature = "macros")]
pub use mecha10_macros::Config;

/// Derive macro for ConfigDefaults
///
/// Automatically generates default_* functions for config fields
///
/// # Example
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(ConfigDefaults)]
/// struct MyConfig {
///     #[config(default = 10.0)]
///     max_speed: f32,
/// }
/// ```
#[cfg(feature = "macros")]
pub use mecha10_macros::ConfigDefaults;

// ============================================================================
// Utility Functions (stubs for now)
// ============================================================================

/// Get current time in microseconds since UNIX epoch
pub fn now_micros() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_micros() as u64
}

/// Create a periodic interval from a frequency in Hz
///
/// This is a convenience helper that converts frequency (Hz) to a tokio interval.
/// Commonly used for periodic publishing in drivers and nodes.
///
/// # Arguments
///
/// * `hz` - Frequency in Hertz (cycles per second)
///
/// # Returns
///
/// A tokio::time::Interval that ticks at the specified frequency
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// # async fn example() {
/// // Instead of:
/// // let interval_duration = Duration::from_secs_f32(1.0 / 30.0);
/// // let mut interval = tokio::time::interval(interval_duration);
///
/// // Simply use:
/// let mut interval = interval_at_hz(30.0);
///
/// loop {
///     interval.tick().await;
///     // Publish at 30 Hz
/// }
/// # }
/// ```
pub fn interval_at_hz(hz: f32) -> tokio::time::Interval {
    let duration = std::time::Duration::from_secs_f32(1.0 / hz);
    tokio::time::interval(duration)
}

/// Initialize logging with sensible defaults
///
/// This function is safe to call multiple times - it will silently succeed if
/// a tracing subscriber is already set (e.g., when running bundled in the CLI).
///
/// The logging system will automatically include node context (node_id) in all
/// log messages when using the Context's logging methods or the `in_node_context!` macro.
pub fn init_logging() {
    use tracing_subscriber::EnvFilter;

    // Use try_init() which silently succeeds if a subscriber is already set.
    // This allows nodes to be run both standalone (where they init logging)
    // and bundled in the CLI (where CLI already initialized logging).
    let _ = tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info")))
        .try_init();
}

/// Macro to execute code within a node's logging context
///
/// This macro creates a tracing span with the node_id field, ensuring all logs
/// within the scope are automatically tagged with the node identifier.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// # async fn example(ctx: &Context) -> Result<()> {
/// in_node_context!(ctx, {
///     info!("Starting processing");  // Will show: node_id=my-node Starting processing
///     debug!("Details here");         // Will show: node_id=my-node Details here
/// });
/// # Ok(())
/// # }
/// ```
#[macro_export]
macro_rules! in_node_context {
    ($ctx:expr, $body:block) => {{
        let _span = tracing::info_span!("node", node_id = $ctx.node_id()).entered();
        $body
    }};
}

/// Re-export the in_node_context macro
pub use in_node_context;

// ============================================================================
// Additional Time & Timestamp Helpers
// ============================================================================

/// Get the current time in milliseconds since UNIX epoch
///
/// This is useful when microsecond precision is excessive (logs, metrics, etc.).
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let timestamp_ms = now_millis();
/// println!("Current time: {} ms", timestamp_ms);
/// ```
pub fn now_millis() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .expect("Time went backwards")
        .as_millis() as u64
}

/// Calculate time elapsed in microseconds since a given timestamp
///
/// # Arguments
///
/// * `timestamp_micros` - A timestamp in microseconds (from `now_micros()`)
///
/// # Returns
///
/// Elapsed time in microseconds
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let start = now_micros();
/// // ... do work ...
/// let elapsed = elapsed_micros(start);
/// println!("Operation took {} μs", elapsed);
/// ```
pub fn elapsed_micros(timestamp_micros: u64) -> u64 {
    now_micros().saturating_sub(timestamp_micros)
}

/// Calculate time elapsed in milliseconds since a given timestamp
///
/// # Arguments
///
/// * `timestamp_millis` - A timestamp in milliseconds (from `now_millis()`)
///
/// # Returns
///
/// Elapsed time in milliseconds
pub fn elapsed_millis(timestamp_millis: u64) -> u64 {
    now_millis().saturating_sub(timestamp_millis)
}

/// Convert a microsecond timestamp to seconds (as f64)
///
/// Useful for displaying timestamps in human-readable format.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let timestamp = now_micros();
/// let seconds = timestamp_as_secs(timestamp);
/// println!("Time: {:.6} seconds", seconds);
/// ```
pub fn timestamp_as_secs(timestamp_micros: u64) -> f64 {
    timestamp_micros as f64 / 1_000_000.0
}

/// Create a Duration from a frequency in Hz
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let duration = duration_from_hz(30.0);  // 33.33ms for 30Hz
/// ```
pub fn duration_from_hz(hz: f32) -> Duration {
    Duration::from_secs_f32(1.0 / hz)
}

// ============================================================================
// Angle & Rotation Helpers
// ============================================================================

/// Normalize an angle in radians to the range [-π, π]
///
/// This is essential for angle calculations to avoid unwanted wraparound effects.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let angle = normalize_angle(7.0);  // Returns ~0.717 (7.0 - 2π)
/// let angle2 = normalize_angle(-4.0); // Returns ~2.283 (-4.0 + 2π)
/// ```
pub fn normalize_angle(angle: f32) -> f32 {
    use std::f32::consts::PI;
    let mut normalized = angle;
    while normalized > PI {
        normalized -= 2.0 * PI;
    }
    while normalized < -PI {
        normalized += 2.0 * PI;
    }
    normalized
}

/// Normalize an angle in degrees to the range [-180, 180]
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let angle = normalize_angle_degrees(270.0);  // Returns -90.0
/// ```
pub fn normalize_angle_degrees(angle: f32) -> f32 {
    let mut normalized = angle;
    while normalized > 180.0 {
        normalized -= 360.0;
    }
    while normalized < -180.0 {
        normalized += 360.0;
    }
    normalized
}

/// Calculate the shortest angular difference between two angles in radians
///
/// Returns the angular distance in the range [-π, π].
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let diff = angle_difference(0.1, 6.2);  // Shortest path wrapping around
/// ```
pub fn angle_difference(from: f32, to: f32) -> f32 {
    normalize_angle(to - from)
}

/// Convert degrees to radians
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let radians = degrees_to_radians(180.0);  // Returns π
/// ```
pub fn degrees_to_radians(degrees: f32) -> f32 {
    degrees * std::f32::consts::PI / 180.0
}

/// Convert radians to degrees
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let degrees = radians_to_degrees(std::f32::consts::PI);  // Returns 180.0
/// ```
pub fn radians_to_degrees(radians: f32) -> f32 {
    radians * 180.0 / std::f32::consts::PI
}

// ============================================================================
// Math & Safety Helpers
// ============================================================================

/// Safely divide two numbers, returning a default value if divisor is zero
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let result = safe_divide(10.0, 2.0, 0.0);   // Returns 5.0
/// let result = safe_divide(10.0, 0.0, 99.0);  // Returns 99.0 (default)
/// ```
pub fn safe_divide(numerator: f32, denominator: f32, default: f32) -> f32 {
    if denominator.abs() < f32::EPSILON {
        default
    } else {
        numerator / denominator
    }
}

/// Clamp a value between a minimum and maximum
///
/// This is available in std but this wrapper makes it more discoverable.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let value = clamp(15.0, 0.0, 10.0);  // Returns 10.0
/// ```
pub fn clamp<T: PartialOrd>(value: T, min: T, max: T) -> T {
    if value < min {
        min
    } else if value > max {
        max
    } else {
        value
    }
}

/// Linear interpolation between two values
///
/// # Arguments
///
/// * `a` - Start value
/// * `b` - End value
/// * `t` - Interpolation factor [0.0, 1.0]
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// let mid = lerp(0.0, 10.0, 0.5);  // Returns 5.0
/// ```
pub fn lerp(a: f32, b: f32, t: f32) -> f32 {
    a + (b - a) * t
}

// ============================================================================
// Common Standard Library Types
// ============================================================================

/// HashMap and HashSet from std
pub use std::collections::{HashMap, HashSet};

/// Sync primitives
pub use std::sync::{Arc, Mutex};

/// Path types
pub use std::path::{Path, PathBuf};

// ============================================================================
// Convenience Type Aliases
// ============================================================================

/// Shared pointer to a value
pub type Shared<T> = Arc<T>;

/// Shared mutable state
pub type SharedMut<T> = Arc<Mutex<T>>;