mecha10-core 0.6.2

//! Mecha10 Framework Macros
//!
//! This module provides convenience macros to reduce boilerplate in node and driver implementations.

/// Run a node with automatic config loading and context creation
///
/// This macro eliminates boilerplate by automatically handling:
/// - Config loading with fallback (from env var, file, or default)
/// - Context creation with node name
/// - Calling run_node with proper types
///
/// # Arguments
///
/// * `$node_type` - The NodeImpl type (e.g., CameraFakeNode)
/// * `$node_name` - The node name string (e.g., "camera_fake")
/// * `$env_var` - Environment variable for config file path (e.g., "CAMERA_CONFIG")
/// * `$config_file` - Default config file path (e.g., "config/drivers/realsense_d435.json")
/// * `$env_prefix` - Environment variable prefix for config overrides (e.g., "CAMERA")
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Debug)]
/// struct CameraFakeNode {
///     config: CameraConfig,
/// }
///
/// #[derive(Debug, Clone, Deserialize, Serialize, Default)]
/// struct CameraConfig {
///     fps: f32,
/// }
///
/// #[async_trait]
/// impl NodeImpl for CameraFakeNode {
///     type Config = CameraConfig;
///
///     async fn init(config: Self::Config) -> Result<Self> {
///         Ok(Self { config })
///     }
///
///     async fn run(&mut self, ctx: &Context) -> Result<()> {
///         // Node logic here
///         Ok(())
///     }
/// }
///
/// // Instead of 13 lines:
/// // pub async fn run() -> Result<()> {
/// //     info!("Starting fake camera driver");
/// //     let config = load_config_with_fallback(
/// //         "CAMERA_CONFIG",
/// //         "config/drivers/realsense_d435.json",
/// //         "CAMERA",
/// //         Some(CameraConfig::default())
/// //     )?;
/// //     let ctx = Context::new("camera_fake");
/// //     run_node::<CameraFakeNode>(config, ctx).await
/// // }
///
/// // Simply use 1 line:
/// run_node_simple!(
///     CameraFakeNode,
///     "camera_fake",
///     "CAMERA_CONFIG",
///     "config/drivers/realsense_d435.json",
///     "CAMERA"
/// );
/// ```
#[macro_export]
macro_rules! run_node_simple {
    ($node_type:ty, $node_name:expr, $env_var:expr, $config_file:expr, $env_prefix:expr) => {
        pub async fn run() -> $crate::error::Result<()> {
            // Load config with fallback
            let config = $crate::config::load_config_with_fallback(
                $env_var,
                $config_file,
                $env_prefix,
                Some(<$node_type as $crate::node::NodeImpl>::Config::default()),
            )?;

            // Create context
            let ctx = $crate::context::Context::new($node_name);

            // Run the node with default health reporting
            $crate::node::run_node::<$node_type>(config, ctx, $crate::node::HealthReportingConfig::default()).await
        }
    };
}

/// Run a node with instance support for multi-instance deployments
///
/// This macro extends `run_node_simple!` with support for instance names,
/// allowing the same node implementation to run multiple instances with
/// different names and configurations.
///
/// # Arguments
///
/// * `$node_type` - The NodeImpl type (e.g., CameraFakeNode)
/// * `$node_name` - The base node name string (e.g., "camera_fake")
/// * `$instance_env` - Environment variable for instance name (e.g., "CAMERA_INSTANCE")
/// * `$env_var` - Environment variable for config file path (e.g., "CAMERA_CONFIG")
/// * `$config_file` - Default config file path (e.g., "config/drivers/camera/default.json")
/// * `$env_prefix` - Environment variable prefix for config overrides (e.g., "CAMERA")
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Debug)]
/// struct CameraFakeNode {
///     config: CameraConfig,
/// }
///
/// #[derive(Debug, Clone, Deserialize, Serialize, Default)]
/// struct CameraConfig {
///     fps: f32,
/// }
///
/// #[async_trait]
/// impl NodeImpl for CameraFakeNode {
///     type Config = CameraConfig;
///
///     async fn init(config: Self::Config) -> Result<Self> {
///         Ok(Self { config })
///     }
///
///     async fn run(&mut self, ctx: &Context) -> Result<()> {
///         // Node logic here - publishes to instance-scoped topics
///         Ok(())
///     }
/// }
///
/// run_node_with_instance!(
///     CameraFakeNode,
///     "camera_fake",
///     "CAMERA_INSTANCE",  // Set to "left" or "right" etc.
///     "CAMERA_CONFIG",
///     "config/drivers/camera/default.json",
///     "CAMERA"
/// );
/// ```
///
/// # Environment Variables
///
/// - `$instance_env`: Instance name (e.g., "left", "right", "front_left")
/// - `$env_var`: Config file path
/// - `${env_prefix}_*`: Config overrides
///
/// # Instance Naming
///
/// If `$instance_env` is set to "left":
/// - Node ID: "camera_fake/left"
/// - Topics published via `publish_to_scoped()`: "/sensor/camera/rgb/left"
///
/// Generate a fluent builder setter method.
///
/// Eliminates the `pub fn <name>(mut self, <arg>: <ty>) -> Self { self.<field> = <expr>; self }`
/// boilerplate repeated across this workspace's many builder structs (`RuntimeBuilder`,
/// `RecoveryPolicyBuilder`, `LauncherServiceBuilder`, etc). Three shapes are supported,
/// matching every setter pattern actually in use:
///
/// - `assign`: plain assignment, no conversion — `self.field = value; self`
/// - `into`: `Into`-convert into a non-`Option` field — `self.field = value.into(); self`
/// - `into_some`: `Into`-convert, wrapped in `Some` — `self.field = Some(value.into()); self`
/// - `insert`: `Into`-convert a key/value pair and insert into a `HashMap` field —
///   `self.field.insert(key.into(), value.into()); self`
///
/// Many builders in this workspace store their fields on a nested config struct
/// (e.g. `RuntimeBuilder { config: RuntimeConfig }`) rather than directly on the
/// builder. Each shape also accepts a one-level `holder.field` path in that position
/// to target `self.holder.field` instead of `self.field`.
///
/// Doc comments (including doctests) are forwarded onto the generated method, so callers
/// can still document each setter's behavior individually.
///
/// # Examples
///
/// ```rust
/// use mecha10_core::builder_setter;
/// use std::time::Duration;
///
/// #[derive(Default)]
/// struct FooConfig {
///     timeout: Duration,
/// }
///
/// #[derive(Default)]
/// struct FooBuilder {
///     name: String,
///     endpoint: Option<String>,
///     config: FooConfig,
///     metadata: std::collections::HashMap<String, String>,
/// }
///
/// impl FooBuilder {
///     builder_setter!(assign, timeout, config.timeout, Duration);
///     builder_setter!(
///         /// Set the service name.
///         into, with_name, name, impl Into<String>
///     );
///     builder_setter!(into_some, with_endpoint, endpoint, impl Into<String>);
///     builder_setter!(insert, with_metadata, metadata, impl Into<String>, impl Into<String>);
/// }
///
/// let foo = FooBuilder::default()
///     .timeout(Duration::from_secs(5))
///     .with_name("svc")
///     .with_endpoint("https://example.com")
///     .with_metadata("region", "us-east-1");
/// assert_eq!(foo.name, "svc");
/// assert_eq!(foo.endpoint, Some("https://example.com".to_string()));
/// assert_eq!(foo.config.timeout, Duration::from_secs(5));
/// assert_eq!(foo.metadata.get("region"), Some(&"us-east-1".to_string()));
/// ```
#[macro_export]
macro_rules! builder_setter {
    ($(#[$meta:meta])* assign, $name:ident, $field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$field = $field;
            self
        }
    };
    ($(#[$meta:meta])* assign, $name:ident, $holder:ident.$field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$holder.$field = $field;
            self
        }
    };
    ($(#[$meta:meta])* into, $name:ident, $field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$field = $field.into();
            self
        }
    };
    ($(#[$meta:meta])* into, $name:ident, $holder:ident.$field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$holder.$field = $field.into();
            self
        }
    };
    ($(#[$meta:meta])* into_some, $name:ident, $field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$field = Some($field.into());
            self
        }
    };
    ($(#[$meta:meta])* into_some, $name:ident, $holder:ident.$field:ident, $ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, $field: $ty) -> Self {
            self.$holder.$field = Some($field.into());
            self
        }
    };
    ($(#[$meta:meta])* insert, $name:ident, $field:ident, $key_ty:ty, $val_ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, key: $key_ty, value: $val_ty) -> Self {
            self.$field.insert(key.into(), value.into());
            self
        }
    };
    ($(#[$meta:meta])* insert, $name:ident, $holder:ident.$field:ident, $key_ty:ty, $val_ty:ty) => {
        $(#[$meta])*
        pub fn $name(mut self, key: $key_ty, value: $val_ty) -> Self {
            self.$holder.$field.insert(key.into(), value.into());
            self
        }
    };
}

/// Generate a str-returning accessor method for a fieldless-variant enum.
///
/// Eliminates the `fn <name>(&self) -> &str { match self { Self::A => "a", ... } }`
/// boilerplate repeated across this workspace's many "kind" enums for methods like
/// `as_str`, `display_name`, `description`, `label`, and `icon`. Each enum typically
/// needs several of these (one per method), so the macro is invoked once per method
/// and expands to its own `impl EnumName { .. }` block — multiple invocations for the
/// same enum simply produce multiple inherent impl blocks, which Rust allows.
///
/// Only fits the plain "one string literal per variant" shape. If a method has extra
/// logic (conditionals, formatting, computed values), leave it hand-written.
///
/// # Examples
///
/// ```rust
/// use mecha10_core::enum_str_method;
///
/// #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// enum TargetArch {
///     X86_64,
///     Aarch64,
/// }
///
/// enum_str_method!(
///     /// Get string representation for metadata.
///     pub fn as_str(TargetArch) -> &str {
///         X86_64 => "x86_64",
///         Aarch64 => "aarch64",
///     }
/// );
///
/// enum_str_method!(
///     pub fn display_name(TargetArch) -> &str {
///         X86_64 => "x86_64 (Linux)",
///         Aarch64 => "ARM64 (Linux)",
///     }
/// );
///
/// assert_eq!(TargetArch::X86_64.as_str(), "x86_64");
/// assert_eq!(TargetArch::Aarch64.display_name(), "ARM64 (Linux)");
/// ```
#[macro_export]
macro_rules! enum_str_method {
    (
        $(#[$meta:meta])*
        $vis:vis fn $method:ident($enum:ident) -> $ret:ty {
            $($variant:ident => $lit:literal),+ $(,)?
        }
    ) => {
        impl $enum {
            $(#[$meta])*
            $vis fn $method(&self) -> $ret {
                match self {
                    $(Self::$variant => $lit,)+
                }
            }
        }
    };
}

/// Generate a node crate's standard entrypoint: `pub async fn run() -> Result<()>`.
///
/// Eliminates the `Context::new` -> `load_node_config` -> `run_node` boilerplate that is
/// repeated byte-for-byte (module the node name and node type) at the bottom of every
/// node crate's `lib.rs`. Health reporting defaults to `HealthReportingConfig::normal()`;
/// pass the `HealthReportingConfig` constructor to use (e.g. `critical`, `background`) as
/// a third argument when a node needs a different priority.
///
/// # Arguments
///
/// * `$node_type` - The `NodeImpl` type to run (e.g. `CameraNode`)
/// * `$node_name` - The node name string, used for both context creation and config
///   loading (e.g. `"camera"`)
/// * `$health` - Optional `HealthReportingConfig` constructor name; defaults to `normal`
///
/// # Examples
///
/// ```rust
/// use mecha10_core::node_main;
/// use mecha10_core::prelude::*;
///
/// #[derive(Debug, Clone, Deserialize, Serialize, Default)]
/// struct CameraConfig {
///     fps: f32,
/// }
///
/// #[derive(Debug)]
/// struct CameraNode {
///     config: CameraConfig,
/// }
///
/// #[async_trait]
/// impl NodeImpl for CameraNode {
///     type Config = CameraConfig;
///
///     async fn init(config: Self::Config) -> Result<Self> {
///         Ok(Self { config })
///     }
///
///     async fn run(&mut self, ctx: &Context) -> Result<()> {
///         Ok(())
///     }
/// }
///
/// // Instead of:
/// // pub async fn run() -> Result<()> {
/// //     let ctx = Context::new("camera").await?;
/// //     let config: CameraConfig = ctx.load_node_config("camera").await?;
/// //     run_node::<CameraNode>(config, ctx, HealthReportingConfig::normal()).await
/// // }
/// //
/// // Simply use:
/// node_main!(CameraNode, "camera");
///
/// // Or, for a non-default health priority:
/// // node_main!(CameraNode, "camera", critical);
/// ```
#[macro_export]
macro_rules! node_main {
    ($node_type:ty, $node_name:expr) => {
        $crate::node_main!($node_type, $node_name, normal);
    };
    ($node_type:ty, $node_name:expr, $health:ident) => {
        pub async fn run() -> $crate::error::Result<()> {
            let ctx = $crate::context::Context::new($node_name).await?;
            let config: <$node_type as $crate::node::NodeImpl>::Config = ctx.load_node_config($node_name).await?;
            $crate::node::run_node::<$node_type>(config, ctx, $crate::node::HealthReportingConfig::$health()).await
        }
    };
}

#[macro_export]
macro_rules! run_node_with_instance {
    ($node_type:ty, $node_name:expr, $instance_env:expr, $env_var:expr, $config_file:expr, $env_prefix:expr) => {
        pub async fn run() -> $crate::error::Result<()> {
            // Load config with fallback
            let config = $crate::config::load_config_with_fallback(
                $env_var,
                $config_file,
                $env_prefix,
                Some(<$node_type as $crate::node::NodeImpl>::Config::default()),
            )?;

            // Create context
            let mut ctx = $crate::context::Context::new($node_name).await?;

            // Apply instance name if set
            if let Ok(instance) = std::env::var($instance_env) {
                ctx = ctx.with_instance(&instance);
                $crate::prelude::info!("Running node '{}' with instance '{}'", $node_name, instance);
            } else {
                $crate::prelude::info!("Running node '{}' (no instance)", $node_name);
            }

            // Run the node with default health reporting
            $crate::node::run_node::<$node_type>(config, ctx, $crate::node::HealthReportingConfig::default()).await
        }
    };
}