harmony/harmony/src/domain/topology/mod.rs

mod ha_cluster;
mod host_binding;
mod http;
pub mod installable;
mod k8s_anywhere;
mod localhost;
pub mod oberservability;
pub mod tenant;
use derive_new::new;
pub use k8s_anywhere::*;
pub use localhost::*;
pub mod k8s;
mod load_balancer;
mod router;
mod tftp;
use async_trait::async_trait;
pub use ha_cluster::*;
pub use load_balancer::*;
pub use router::*;
mod network;
pub use host_binding::*;
pub use http::*;
pub use network::*;
use serde::Serialize;
pub use tftp::*;

mod helm_command;
pub use helm_command::*;

use super::{
    executors::ExecutorError,
    instrumentation::{self, HarmonyEvent},
};
use std::error::Error;
use std::net::IpAddr;

/// Represents a logical view of an infrastructure environment providing specific capabilities.
///
/// A Topology acts as a self-contained "package" responsible for managing access
/// to its underlying resources and ensuring they are in a ready state before use.
/// It defines the contract for the capabilities it provides through implemented
/// capability traits (e.g., `HasK8sCapability`, `HasDnsServer`).
#[async_trait]
pub trait Topology: Send + Sync {
    /// Returns a unique identifier or name for this specific topology instance.
    /// This helps differentiate between multiple instances of potentially the same type.
    fn name(&self) -> &str;

    /// Ensures that the topology and its required underlying components or services
    /// are ready to provide their declared capabilities.
    ///
    /// Implementations of this method MUST be idempotent. Subsequent calls after a
    /// successful readiness check should ideally be cheap NO-OPs.
    ///
    /// This method encapsulates the logic for:
    /// 1.  **Checking Current State:** Assessing if the required resources/services are already running and configured.
    /// 2.  **Discovery:** Identifying the runtime environment (e.g., local Docker, AWS, existing cluster).
    /// 3.  **Initialization/Bootstrapping:** Performing necessary setup actions if not already ready. This might involve:
    ///     *   Making API calls.
    ///     *   Running external commands (e.g., `k3d`, `docker`).
    ///     *   **Internal Orchestration:** For complex topologies, this method might manage dependencies on other sub-topologies, ensuring *their* `ensure_ready` is called first. Using nested `Maestros` to run setup `Scores` against these sub-topologies is the recommended pattern for non-trivial bootstrapping, allowing reuse of Harmony's core orchestration logic.
    ///
    /// # Returns
    /// - `Ok(PreparationOutcome)`: Indicates the topology is now ready. The `Outcome` status might be `SUCCESS` if actions were taken, or `NOOP` if it was already ready. The message should provide context.
    /// - `Err(PreparationError)`: Indicates the topology could not reach a ready state due to configuration issues, discovery failures, bootstrap errors, or unsupported environments.
    async fn ensure_ready(&self) -> Result<PreparationOutcome, PreparationError>;
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PreparationOutcome {
    Success { details: String },
    Noop,
}

#[derive(Debug, Clone, new)]
pub struct PreparationError {
    msg: String,
}

impl std::fmt::Display for PreparationError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.msg)
    }
}

impl Error for PreparationError {}

impl From<ExecutorError> for PreparationError {
    fn from(value: ExecutorError) -> Self {
        Self {
            msg: format!("InterpretError : {value}"),
        }
    }
}

impl From<kube::Error> for PreparationError {
    fn from(value: kube::Error) -> Self {
        Self {
            msg: format!("PreparationError : {value}"),
        }
    }
}

impl From<String> for PreparationError {
    fn from(value: String) -> Self {
        Self {
            msg: format!("PreparationError : {value}"),
        }
    }
}

#[derive(Clone, Debug, PartialEq)]
pub enum TopologyStatus {
    Queued,
    Preparing,
    Success,
    Noop,
    Error,
}

pub struct TopologyState {
    pub topology: String,
    pub status: TopologyStatus,
}

impl TopologyState {
    pub fn new(topology: String) -> Self {
        let instance = Self {
            topology,
            status: TopologyStatus::Queued,
        };

        instrumentation::instrument(HarmonyEvent::TopologyStateChanged {
            topology: instance.topology.clone(),
            status: instance.status.clone(),
            message: None,
        })
        .unwrap();

        instance
    }

    pub fn prepare(&mut self) {
        self.status = TopologyStatus::Preparing;

        instrumentation::instrument(HarmonyEvent::TopologyStateChanged {
            topology: self.topology.clone(),
            status: self.status.clone(),
            message: None,
        })
        .unwrap();
    }

    pub fn success(&mut self, message: String) {
        self.status = TopologyStatus::Success;

        instrumentation::instrument(HarmonyEvent::TopologyStateChanged {
            topology: self.topology.clone(),
            status: self.status.clone(),
            message: Some(message),
        })
        .unwrap();
    }

    pub fn noop(&mut self) {
        self.status = TopologyStatus::Noop;

        instrumentation::instrument(HarmonyEvent::TopologyStateChanged {
            topology: self.topology.clone(),
            status: self.status.clone(),
            message: None,
        })
        .unwrap();
    }

    pub fn error(&mut self, message: String) {
        self.status = TopologyStatus::Error;

        instrumentation::instrument(HarmonyEvent::TopologyStateChanged {
            topology: self.topology.clone(),
            status: self.status.clone(),
            message: Some(message),
        })
        .unwrap();
    }
}

#[derive(Debug)]
pub enum DeploymentTarget {
    LocalDev,
    Staging,
    Production,
}

pub trait MultiTargetTopology: Topology {
    fn current_target(&self) -> DeploymentTarget;
}

pub type IpAddress = IpAddr;

#[derive(Debug, Clone)]
pub enum Url {
    LocalFolder(String),
    Url(url::Url),
}

impl Serialize for Url {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        match self {
            Url::LocalFolder(path) => serializer.serialize_str(path),
            Url::Url(url) => serializer.serialize_str(url.as_str()),
        }
    }
}

impl std::fmt::Display for Url {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Url::LocalFolder(path) => write!(f, "{}", path),
            Url::Url(url) => write!(f, "{}", url),
        }
    }
}

/// Represents a logical member of a cluster that provides one or more services.
///
/// A LogicalHost can represent various roles within the infrastructure, such as:
/// - A firewall appliance hosting DHCP, DNS, PXE, and load balancer services
/// - A Kubernetes worker node
/// - A combined Kubernetes worker and Ceph storage node
/// - A control plane node
///
/// This abstraction focuses on the logical role and services, independent of the physical hardware.
#[derive(Debug, Clone, Serialize)]
pub struct LogicalHost {
    /// The IP address of this logical host.
    pub ip: IpAddress,
    /// The name of this logical host.
    pub name: String,
}

impl LogicalHost {
    /// Creates a list of `LogicalHost` instances.
    ///
    /// # Arguments
    ///
    /// * `number_hosts` - The number of logical hosts to create.
    /// * `start_ip` - The starting IP address. Each subsequent host's IP will be incremented.
    /// * `hostname_prefix` - The prefix for the host names. Host names will be in the form `prefix<index>`.
    ///
    /// # Returns
    ///
    /// A `Vec<LogicalHost>` containing the specified number of logical hosts, each with a unique IP and name.
    ///
    /// # Panics
    ///
    /// This function will panic if adding `number_hosts` to `start_ip` exceeds the valid range of IP addresses.
    ///
    /// # Examples
    ///
    /// ```
    /// use std::str::FromStr;
    /// use harmony::topology::{IpAddress, LogicalHost};
    ///
    /// let start_ip = IpAddress::from_str("192.168.0.20").unwrap();
    /// let hosts = LogicalHost::create_hosts(3, start_ip, "worker");
    ///
    /// assert_eq!(hosts.len(), 3);
    /// assert_eq!(hosts[0].ip, IpAddress::from_str("192.168.0.20").unwrap());
    /// assert_eq!(hosts[0].name, "worker0");
    /// assert_eq!(hosts[1].ip, IpAddress::from_str("192.168.0.21").unwrap());
    /// assert_eq!(hosts[1].name, "worker1");
    /// assert_eq!(hosts[2].ip, IpAddress::from_str("192.168.0.22").unwrap());
    /// assert_eq!(hosts[2].name, "worker2");
    /// ```
    pub fn create_hosts(
        number_hosts: u32,
        start_ip: IpAddress,
        hostname_prefix: &str,
    ) -> Vec<LogicalHost> {
        let mut hosts = Vec::with_capacity(number_hosts.try_into().unwrap());
        for i in 0..number_hosts {
            let new_ip = increment_ip(start_ip, i).expect("IP address overflow");
            let name = format!("{}{}", hostname_prefix, i);
            hosts.push(LogicalHost { ip: new_ip, name });
        }
        hosts
    }
}

/// Increments an IP address by a given value.
///
/// # Arguments
///
/// * `ip` - The starting IP address.
/// * `increment` - The amount to add to the IP address.
///
/// # Returns
///
/// A new `IpAddress` that is the result of incrementing the original by `increment`.
///
/// # Panics
///
/// This function panics if the resulting IP address exceeds the valid range.
fn increment_ip(ip: IpAddress, increment: u32) -> Option<IpAddress> {
    match ip {
        IpAddress::V4(ipv4) => {
            let new_ip = u32::from(ipv4) + increment;
            Some(IpAddress::V4(new_ip.into()))
        }
        IpAddress::V6(_) => {
            todo!("Ipv6 not supported yet")
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json;

    #[test]
    fn test_serialize_local_folder() {
        let url = Url::LocalFolder("path/to/folder".to_string());
        let serialized = serde_json::to_string(&url).unwrap();
        assert_eq!(serialized, "\"path/to/folder\"");
    }

    #[test]
    fn test_serialize_url() {
        let url = Url::Url(url::Url::parse("https://example.com").unwrap());
        let serialized = serde_json::to_string(&url).unwrap();
        assert_eq!(serialized, "\"https://example.com/\"");
    }
}