database_bootstrap/

step.rs

//! Bootstrap step trait and related types.

use async_trait::async_trait;
use std::collections::HashMap;
use std::fmt::Display;
use uuid::Uuid;

use crate::BootstrapError;
use crate::traits::DatabaseConnection;

/// Result of verifying whether a bootstrap step's data exists.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VerifyResult {
    /// The data is present and correct.
    Present,
    /// The data is missing entirely.
    Missing,
    /// The data is partially present (inconsistent state).
    Partial,
}

/// Detailed verification result with entity-level information.
///
/// This type allows steps to pass verification data to run() to avoid
/// redundant database queries.
#[derive(Debug, Clone)]
pub struct VerifyDetails {
    /// Overall verification result.
    pub result: VerifyResult,
    /// Entity existence status (entity_name -> exists).
    pub entities: HashMap<&'static str, bool>,
    /// Entity IDs discovered during verification (entity_name -> id).
    pub ids: HashMap<&'static str, Uuid>,
}

impl VerifyDetails {
    /// Creates a new details instance with the given result.
    pub fn new(result: VerifyResult) -> Self {
        Self {
            result,
            entities: HashMap::new(),
            ids: HashMap::new(),
        }
    }

    /// Records an entity's existence status.
    pub fn entity(mut self, name: &'static str, exists: bool) -> Self {
        self.entities.insert(name, exists);
        self
    }

    /// Records an entity's existence status with its ID.
    pub fn entity_with_id(mut self, name: &'static str, exists: bool, id: Uuid) -> Self {
        self.entities.insert(name, exists);
        if exists {
            self.ids.insert(name, id);
        }
        self
    }

    /// Returns true if all entities exist.
    pub fn all_present(&self) -> bool {
        self.entities.values().all(|&v| v)
    }

    /// Returns true if any entity exists.
    pub fn any_present(&self) -> bool {
        self.entities.values().any(|&v| v)
    }

    /// Returns true if no entities exist.
    pub fn none_present(&self) -> bool {
        !self.any_present()
    }

    /// Checks if a specific entity exists.
    pub fn has(&self, name: &str) -> bool {
        self.entities.get(name).copied().unwrap_or(false)
    }

    /// Gets the ID for an entity, if it exists.
    pub fn id(&self, name: &str) -> Option<Uuid> {
        self.ids.get(name).copied()
    }
}

/// Requirement level for bootstrap step data.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Requirement {
    /// Data must be present after bootstrap.
    /// Verification will fail if the step completes but data is still missing.
    Required,
    /// Data is optional.
    /// Verification will pass even if the step cannot create the data.
    Optional,
}

/// Output from a bootstrap step that should be displayed in the summary.
///
/// Used for secrets like passwords and tokens that are generated during bootstrap
/// and need to be shown to the operator exactly once.
#[derive(Debug, Clone)]
pub struct StepOutput {
    /// Human-readable title for this output.
    pub title: String,
    /// Key-value pairs to display.
    pub fields: Vec<(String, String)>,
    /// Whether this output contains sensitive data (passwords, tokens, etc.).
    pub is_sensitive: bool,
}

impl StepOutput {
    /// Creates a new output with a title.
    pub fn new(title: impl Into<String>) -> Self {
        Self {
            title: title.into(),
            fields: Vec::new(),
            is_sensitive: false,
        }
    }

    /// Adds a field to the output.
    pub fn field(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.fields.push((key.into(), value.into()));
        self
    }

    /// Marks the output as containing sensitive data.
    pub fn sensitive(mut self) -> Self {
        self.is_sensitive = true;
        self
    }
}

impl Display for StepOutput {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "  {}", self.title)?;
        for (key, value) in &self.fields {
            writeln!(f, "    {key}: {value}")?;
        }
        Ok(())
    }
}

/// Factory for creating bootstrap steps.
///
/// Used for type-safe dependency declarations. When a step declares a dependency,
/// it provides a factory that can create the dependency step if it's not already
/// registered in the runner.
pub trait StepFactory<T: DatabaseConnection>: Send + Sync {
    /// Returns the name of the step this factory creates.
    fn step_name(&self) -> &'static str;

    /// Creates a new instance of the step.
    fn create(&self) -> Box<dyn BootstrapStep<T>>;
}

/// A single bootstrap step that can verify and create seed data.
///
/// Steps can depend on other steps, forming a DAG. The runner executes
/// steps in topological order after verifying dependencies are satisfied.
///
/// # Example
///
/// ```ignore
/// struct MyStep;
///
/// #[async_trait]
/// impl BootstrapStep for MyStep {
///     fn name(&self) -> &'static str { "my_step" }
///     fn description(&self) -> &'static str { "Does something" }
///     
///     async fn verify(&self, txn: &DatabaseTransaction) -> Result<VerifyDetails, BootstrapError> {
///         // Check if data exists
///         Ok(VerifyDetails::new(VerifyResult::Missing))
///     }
///     
///     async fn run(&self, txn: &DatabaseTransaction, details: &VerifyDetails) -> Result<Option<StepOutput>, BootstrapError> {
///         // Create data
///         Ok(Some(StepOutput::new("My Step Output")
///             .field("key", "value")
///             .sensitive()))
///     }
/// }
/// ```
#[async_trait]
pub trait BootstrapStep<T: DatabaseConnection>: Send + Sync {
    /// Unique identifier for this step.
    fn name(&self) -> &'static str;

    /// Human-readable description of what this step does.
    fn description(&self) -> &'static str;

    /// Factories for steps that must run before this one.
    ///
    /// If a dependency is not registered in the runner, it will be
    /// automatically created using the factory and executed first.
    fn dependencies(&self) -> Vec<Box<dyn StepFactory<T>>> {
        Vec::new()
    }

    /// Whether this step's data is required or optional.
    fn requirement(&self) -> Requirement {
        Requirement::Required
    }

    /// Whether to skip this step with a warning if data is missing.
    ///
    /// When `true` and verify returns `Missing`:
    /// - Logs a warning
    /// - Marks step as completed without running
    /// - Does not auto-create the data
    ///
    /// When `false` (default) and verify returns `Missing`:
    /// - Runs the step to create the data
    fn skip_if_missing(&self) -> bool {
        false
    }

    /// Check if the data for this step already exists.
    ///
    /// Returns detailed information about each entity's existence status.
    /// This information is passed to run() to avoid redundant queries.
    async fn verify(&self, txn: &T::DatabaseTransaction) -> Result<VerifyDetails, BootstrapError<T::Error>>;

    /// Create the data for this step. Called only if verify returns Missing or Partial.
    ///
    /// Receives the verification details to avoid redundant queries.
    /// Returns `Some(StepOutput)` if there are secrets or other information
    /// that should be displayed in the bootstrap summary.
    async fn run(
        &self,
        txn: &T::DatabaseTransaction,
        details: &VerifyDetails,
    ) -> Result<Option<StepOutput>, BootstrapError<T::Error>>;
}