wowlab_engine_ports/

error.rs

wowlab_engine_macros::define_error! {
/// Failures while turning an authored encounter into combat-ready data.
#[derive(Debug)]
pub struct EncounterConstructionError {
    #[source]
    kind: EncounterConstructionErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum EncounterConstructionErrorKind {
    #[error("invalid encounter definition: {0}")]
    InvalidDefinition(#[from] wowlab_types::sim::EncounterValidationError),
    #[error("resolved encounter enemy count mismatch: expected {expected}, found {found}")]
    ResolvedEnemyCountMismatch { expected: usize, found: usize },
    #[error("resolved encounter enemy index {index} does not fit EnemyIdx")]
    ResolvedEnemyIndexOutOfRange {
        index: usize,
        #[source]
        source: std::num::TryFromIntError,
    },
    #[error(
        "resolved encounter identity mismatch at position {index}: authored {authored:?}, resolved {resolved:?}"
    )]
    ResolvedEnemyIdentityMismatch {
        index: usize,
        authored: wowlab_types::sim::EnemyIdx,
        resolved: wowlab_types::sim::EnemyIdx,
    },
    #[error("resolved enemy {enemy:?} level mismatch: expected {expected}, found {found}")]
    ResolvedEnemyLevelMismatch {
        enemy: wowlab_types::sim::EnemyIdx,
        expected: u16,
        found: u16,
    },
    #[error("resolved enemy {enemy:?} does not match its authored identity input")]
    ResolvedEnemyIdentityMetadataMismatch { enemy: wowlab_types::sim::EnemyIdx },
    #[error("resolved enemy {enemy:?} does not match its authored runtime metadata")]
    ResolvedEnemyMetadataMismatch { enemy: wowlab_types::sim::EnemyIdx },
    #[error("resolved enemy {enemy:?} health model requires max health {expected}, found {found}")]
    ResolvedHealthModelMismatch {
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
    },
    #[error("resolved enemy {enemy:?} has an empty display name")]
    EmptyResolvedDisplayName { enemy: wowlab_types::sim::EnemyIdx },
    #[error("resolved enemy {enemy:?} has invalid {field}: {found}")]
    InvalidResolvedEnemyStat {
        enemy: wowlab_types::sim::EnemyIdx,
        field: &'static str,
        found: f64,
    },
    #[error(
        "combat creature armor for enemy {enemy:?} does not match resolved armor: expected {expected}, found {found}"
    )]
    CombatCreatureArmorMismatch {
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
    },
    #[error("combat armor constant for enemy {enemy:?} must be finite and positive, found {found}")]
    InvalidCombatArmorConstant {
        enemy: wowlab_types::sim::EnemyIdx,
        found: f64,
    },
    #[error(
        "combat armor constant modifier for enemy {enemy:?} must be finite and positive, found {found}"
    )]
    InvalidCombatArmorConstantMod {
        enemy: wowlab_types::sim::EnemyIdx,
        found: f64,
    },
    #[error(
        "effective combat armor constant for enemy {enemy:?} does not match resolved value: expected {expected}, found {found} from armor_constant {armor_constant} * armor_constant_mod {armor_constant_mod}"
    )]
    CombatEffectiveArmorConstantMismatch {
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
        armor_constant: f64,
        armor_constant_mod: f64,
    },
}
}

impl EncounterConstructionError {
    pub(crate) fn resolved_enemy_count_mismatch(expected: usize, found: usize) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyCountMismatch { expected, found },
        }
    }

    pub(crate) fn resolved_enemy_index_out_of_range(
        index: usize,
        source: std::num::TryFromIntError,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyIndexOutOfRange { index, source },
        }
    }

    pub(crate) fn resolved_enemy_identity_mismatch(
        index: usize,
        authored: wowlab_types::sim::EnemyIdx,
        resolved: wowlab_types::sim::EnemyIdx,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyIdentityMismatch {
                index,
                authored,
                resolved,
            },
        }
    }

    pub(crate) fn resolved_enemy_level_mismatch(
        enemy: wowlab_types::sim::EnemyIdx,
        expected: u16,
        found: u16,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyLevelMismatch {
                enemy,
                expected,
                found,
            },
        }
    }

    pub(crate) fn resolved_enemy_identity_metadata_mismatch(
        enemy: wowlab_types::sim::EnemyIdx,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyIdentityMetadataMismatch { enemy },
        }
    }

    pub(crate) fn resolved_enemy_metadata_mismatch(enemy: wowlab_types::sim::EnemyIdx) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedEnemyMetadataMismatch { enemy },
        }
    }

    pub(crate) fn resolved_health_model_mismatch(
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::ResolvedHealthModelMismatch {
                enemy,
                expected,
                found,
            },
        }
    }

    pub(crate) fn empty_resolved_display_name(enemy: wowlab_types::sim::EnemyIdx) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::EmptyResolvedDisplayName { enemy },
        }
    }

    pub(crate) fn invalid_resolved_enemy_stat(
        enemy: wowlab_types::sim::EnemyIdx,
        field: &'static str,
        found: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::InvalidResolvedEnemyStat {
                enemy,
                field,
                found,
            },
        }
    }

    pub(crate) fn combat_creature_armor_mismatch(
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::CombatCreatureArmorMismatch {
                enemy,
                expected,
                found,
            },
        }
    }

    pub(crate) fn invalid_combat_armor_constant(
        enemy: wowlab_types::sim::EnemyIdx,
        found: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::InvalidCombatArmorConstant { enemy, found },
        }
    }

    pub(crate) fn invalid_combat_armor_constant_mod(
        enemy: wowlab_types::sim::EnemyIdx,
        found: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::InvalidCombatArmorConstantMod { enemy, found },
        }
    }

    pub(crate) fn combat_effective_armor_constant_mismatch(
        enemy: wowlab_types::sim::EnemyIdx,
        expected: f64,
        found: f64,
        armor_constant: f64,
        armor_constant_mod: f64,
    ) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::CombatEffectiveArmorConstantMismatch {
                enemy,
                expected,
                found,
                armor_constant,
                armor_constant_mod,
            },
        }
    }

    #[cfg(test)]
    #[must_use]
    pub(crate) fn is_combat_creature_armor_mismatch(&self) -> bool {
        matches!(
            self.kind,
            EncounterConstructionErrorKind::CombatCreatureArmorMismatch { .. }
        )
    }

    #[cfg(test)]
    #[must_use]
    pub(crate) fn is_invalid_combat_armor_constant(&self) -> bool {
        matches!(
            self.kind,
            EncounterConstructionErrorKind::InvalidCombatArmorConstant { .. }
        )
    }

    #[cfg(test)]
    #[must_use]
    pub(crate) fn is_invalid_combat_armor_constant_mod(&self) -> bool {
        matches!(
            self.kind,
            EncounterConstructionErrorKind::InvalidCombatArmorConstantMod { .. }
        )
    }

    #[cfg(test)]
    #[must_use]
    pub(crate) fn is_combat_effective_armor_constant_mismatch(&self) -> bool {
        matches!(
            self.kind,
            EncounterConstructionErrorKind::CombatEffectiveArmorConstantMismatch { .. }
        )
    }
}

impl From<wowlab_types::sim::EncounterValidationError> for EncounterConstructionError {
    fn from(error: wowlab_types::sim::EncounterValidationError) -> Self {
        Self {
            kind: EncounterConstructionErrorKind::InvalidDefinition(error),
        }
    }
}

wowlab_engine_macros::define_error! {
/// Failure while driving one simulation iteration.
#[derive(Debug)]
#[non_exhaustive]
pub struct SimRunError {
    #[source]
    kind: SimRunErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum SimRunErrorKind {
    #[error("event budget exceeded: simulator processed {count} events without converging")]
    EventBudgetExceeded { count: u32 },
    #[error("spec handler failed while processing an event")]
    Handler {
        #[source]
        source: crate::SpecRuntimeError,
    },
}
}

impl SimRunError {
    /// Creates a non-converging event-loop failure.
    #[must_use]
    pub const fn event_budget_exceeded(count: u32) -> Self {
        Self {
            kind: SimRunErrorKind::EventBudgetExceeded { count },
        }
    }

    /// Creates a handler-dispatch failure while retaining its runtime source.
    #[must_use]
    pub const fn handler(source: crate::SpecRuntimeError) -> Self {
        Self {
            kind: SimRunErrorKind::Handler { source },
        }
    }

    /// Returns the processed-event count for a budget failure.
    #[must_use]
    pub const fn event_count(&self) -> Option<u32> {
        match self.kind {
            SimRunErrorKind::EventBudgetExceeded { count } => Some(count),
            SimRunErrorKind::Handler { .. } => None,
        }
    }
}

/// Construction stage that retained a lower-layer failure.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum EngineConstructionStage {
    RotationCompile,
    SpecConstruction,
}

wowlab_engine_macros::define_error! {
/// Typed engine-construction failure with its concrete lower-layer source.
#[non_exhaustive]
pub struct EngineConstructionError {
    #[source]
    kind: EngineConstructionErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum EngineConstructionErrorKind {
    #[error("rotation compile error: {source}")]
    RotationCompile {
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },
    #[error("spec construction error: {source}")]
    SpecConstruction {
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },
}
}

impl EngineConstructionError {
    fn new(
        stage: EngineConstructionStage,
        source: impl std::error::Error + Send + Sync + 'static,
    ) -> Self {
        let source = Box::new(source);
        let kind = match stage {
            EngineConstructionStage::RotationCompile => {
                EngineConstructionErrorKind::RotationCompile { source }
            }
            EngineConstructionStage::SpecConstruction => {
                EngineConstructionErrorKind::SpecConstruction { source }
            }
        };

        Self { kind }
    }

    /// Returns the construction stage that failed.
    #[must_use]
    pub const fn stage(&self) -> EngineConstructionStage {
        match self.kind {
            EngineConstructionErrorKind::RotationCompile { .. } => {
                EngineConstructionStage::RotationCompile
            }
            EngineConstructionErrorKind::SpecConstruction { .. } => {
                EngineConstructionStage::SpecConstruction
            }
        }
    }
}

impl std::fmt::Debug for EngineConstructionError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("EngineConstructionError")
            .field("stage", &self.stage())
            .finish_non_exhaustive()
    }
}

wowlab_engine_macros::define_error! {
/// Engine error categories.
#[non_exhaustive]
pub struct EngineError {
    #[source]
    kind: EngineErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum EngineErrorKind {
    #[error("intent validation error: {message}")]
    IntentValidation { message: String },
    #[error("chunk validation error: {message}")]
    ChunkValidation { message: String },
    #[error("resolver error: {0}")]
    Resolver(#[from] crate::resolver::ResolverError),
    #[error("encounter construction error: {0}")]
    EncounterConstruction(#[from] EncounterConstructionError),
    #[error("spec metadata error: {0}")]
    SpecMetadata(#[from] crate::DeclaredSpecMetadataError),
    #[error("content catalog error: {0}")]
    ContentCatalog(#[from] crate::ContentCatalogError),
    #[error("{context}: {source}")]
    SpellIdConversion {
        context: &'static str,
        #[source]
        source: crate::SpellIdConversionError,
    },
    #[error("{0}")]
    Construction(#[source] EngineConstructionError),
    #[error("spec construction error: {message}")]
    SpecConstruction { message: String },
    #[error("spec not found: {message}")]
    SpecNotFound { message: String },
    #[error("simulation runtime error: {message}")]
    SimulationRuntime { message: String },
    #[error("simulation runtime error: {0}")]
    SimulationRun(#[from] SimRunError),
}
}

macro_rules! engine_error_ctor {
    ($($ctor:ident => $variant:ident),+ $(,)?) => {
        impl EngineError {
            $(
                pub fn $ctor(message: impl Into<String>) -> Self {
                    Self {
                        kind: EngineErrorKind::$variant {
                            message: message.into(),
                        },
                    }
                }
            )+
        }
    };
}

impl EngineError {
    /// Retains a typed rotation-construction source behind the Ports boundary.
    #[must_use]
    pub fn rotation_compile(source: impl std::error::Error + Send + Sync + 'static) -> Self {
        Self {
            kind: EngineErrorKind::Construction(EngineConstructionError::new(
                EngineConstructionStage::RotationCompile,
                source,
            )),
        }
    }

    /// Retains a typed combat-system construction source behind the Ports boundary.
    #[must_use]
    pub fn spec_construction_source(
        source: impl std::error::Error + Send + Sync + 'static,
    ) -> Self {
        Self {
            kind: EngineErrorKind::Construction(EngineConstructionError::new(
                EngineConstructionStage::SpecConstruction,
                source,
            )),
        }
    }

    /// Wraps a runtime-to-database spell-ID conversion with use-case context.
    #[must_use]
    pub const fn spell_id_conversion(
        context: &'static str,
        source: crate::SpellIdConversionError,
    ) -> Self {
        Self {
            kind: EngineErrorKind::SpellIdConversion { context, source },
        }
    }

    #[must_use]
    pub fn is_intent_validation(&self) -> bool {
        matches!(self.kind, EngineErrorKind::IntentValidation { .. })
    }

    #[must_use]
    pub fn is_chunk_validation(&self) -> bool {
        matches!(self.kind, EngineErrorKind::ChunkValidation { .. })
    }

    /// Returns whether this is a spec-construction failure.
    #[must_use]
    pub fn is_spec_construction(&self) -> bool {
        match &self.kind {
            EngineErrorKind::Construction(error) => {
                error.stage() == EngineConstructionStage::SpecConstruction
            }
            EngineErrorKind::SpecConstruction { .. }
            | EngineErrorKind::SpecMetadata(_)
            | EngineErrorKind::ContentCatalog(_)
            | EngineErrorKind::SpellIdConversion { .. } => true,
            _ => false,
        }
    }

    #[must_use]
    pub fn message(&self) -> Option<&str> {
        match &self.kind {
            EngineErrorKind::IntentValidation { message }
            | EngineErrorKind::ChunkValidation { message }
            | EngineErrorKind::SpecConstruction { message }
            | EngineErrorKind::SpecNotFound { message }
            | EngineErrorKind::SimulationRuntime { message } => Some(message),
            EngineErrorKind::Resolver(_)
            | EngineErrorKind::EncounterConstruction(_)
            | EngineErrorKind::SpecMetadata(_)
            | EngineErrorKind::ContentCatalog(_)
            | EngineErrorKind::Construction(_)
            | EngineErrorKind::SpellIdConversion { .. }
            | EngineErrorKind::SimulationRun(_) => None,
        }
    }

    #[cfg(test)]
    pub(crate) fn into_encounter_construction(self) -> Option<EncounterConstructionError> {
        match self.kind {
            EngineErrorKind::EncounterConstruction(error) => Some(error),
            _ => None,
        }
    }
}

impl From<wowlab_engine_gamedata::GameDataError> for EngineError {
    fn from(source: wowlab_engine_gamedata::GameDataError) -> Self {
        Self::spec_construction_source(source)
    }
}

impl std::fmt::Debug for EngineError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if let EngineErrorKind::Construction(error) = &self.kind {
            return f
                .debug_struct("EngineError")
                .field("construction_stage", &error.stage())
                .finish_non_exhaustive();
        }

        f.debug_struct("EngineError")
            .field("kind", &self.kind)
            .finish()
    }
}

impl From<crate::resolver::ResolverError> for EngineError {
    fn from(error: crate::resolver::ResolverError) -> Self {
        Self {
            kind: EngineErrorKind::Resolver(error),
        }
    }
}

impl From<EncounterConstructionError> for EngineError {
    fn from(error: EncounterConstructionError) -> Self {
        Self {
            kind: EngineErrorKind::EncounterConstruction(error),
        }
    }
}

impl From<wowlab_types::sim::EncounterValidationError> for EngineError {
    fn from(error: wowlab_types::sim::EncounterValidationError) -> Self {
        EncounterConstructionError::from(error).into()
    }
}

impl From<crate::DeclaredSpecMetadataError> for EngineError {
    fn from(error: crate::DeclaredSpecMetadataError) -> Self {
        Self {
            kind: EngineErrorKind::SpecMetadata(error),
        }
    }
}

impl From<crate::ContentCatalogError> for EngineError {
    fn from(error: crate::ContentCatalogError) -> Self {
        Self {
            kind: EngineErrorKind::ContentCatalog(error),
        }
    }
}

impl From<SimRunError> for EngineError {
    fn from(error: SimRunError) -> Self {
        Self {
            kind: EngineErrorKind::SimulationRun(error),
        }
    }
}

engine_error_ctor! {
    intent_validation   => IntentValidation,
    chunk_validation    => ChunkValidation,
    spec_construction   => SpecConstruction,
    spec_not_found      => SpecNotFound,
    simulation_runtime  => SimulationRuntime,
}

#[cfg(test)]
mod construction_error_tests {
    use std::error::Error as _;

    use googletest::prelude::*;

    use super::*;

    #[gtest]
    fn typed_construction_source_preserves_stage_display_chain_and_redaction() -> Result<()> {
        let error = EngineError::spec_construction_source(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            "private builder payload",
        ));

        verify_true!(error.is_spec_construction())?;
        verify_that!(
            error.to_string(),
            eq("spec construction error: private builder payload")
        )?;
        let construction = error
            .source()
            .and_then(std::error::Error::source)
            .and_then(|source| source.downcast_ref::<EngineConstructionError>())
            .or_fail()?;

        verify_that!(
            construction.stage(),
            eq(EngineConstructionStage::SpecConstruction)
        )?;
        verify_true!(
            construction
                .source()
                .and_then(std::error::Error::source)
                .is_some_and(<dyn std::error::Error>::is::<std::io::Error>)
        )?;
        let debug = format!("{error:?}");

        verify_that!(&debug, contains_substring("Construction"))?;

        verify_that!(&debug, not(contains_substring("private builder payload")))
    }

    #[gtest]
    fn game_data_error_conversion_preserves_spec_construction_source() -> Result<()> {
        let mut builder = wowlab_engine_gamedata::ResolvedGameData::builder();

        builder.insert_base_points(wowlab_types::sim::SpellIdx::from_raw(1), 1, 1.0);
        let source = builder
            .build()
            .require_base_points(wowlab_types::sim::SpellIdx::from_raw(2), 1)
            .err()
            .or_fail()?;
        let error = EngineError::from(source);

        verify_true!(error.is_spec_construction())?;

        verify_true!(
            error
                .source()
                .and_then(std::error::Error::source)
                .and_then(|source| source.downcast_ref::<EngineConstructionError>())
                .and_then(std::error::Error::source)
                .and_then(std::error::Error::source)
                .is_some_and(<dyn std::error::Error>::is::<wowlab_engine_gamedata::GameDataError>)
        )
    }
}