poolsim-core 0.1.0

Core simulation engine for poolsim
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

//! Error types and helpers for the public `poolsim-core` API.
//!
//! `PoolsimError` is designed to work for both library callers and service
//! adapters:
//!
//! - stable machine-readable codes via [`PoolsimError::code`]
//! - optional structured error details via [`PoolsimError::details`]
//! - human-readable messages via `Display`
//!
//! This makes the same error type suitable for direct Rust usage, CLI
//! rendering, and HTTP/WebSocket translation in `poolsim-web`.

use serde_json::Value;
use thiserror::Error;

/// Error type returned by `poolsim-core` public APIs.
#[derive(Debug, Error)]
pub enum PoolsimError {
    /// Invalid input payload or violated input constraints.
    #[error("{message}")]
    InvalidInput {
        /// Stable machine-readable error code.
        code: &'static str,
        /// Human-readable error message.
        message: String,
        /// Optional structured details for API responses.
        details: Option<Value>,
    },

    /// System is saturated (`rho >= 1.0`) for the requested configuration.
    #[error("system saturated at rho={rho:.4}")]
    Saturated {
        /// Utilization ratio (`rho`) at failure time.
        rho: f64,
    },

    /// Distribution fitting/sampling failure.
    #[error("distribution error: {0}")]
    Distribution(String),

    /// Simulation runtime failure.
    #[error("simulation error: {0}")]
    Simulation(String),
}

impl PoolsimError {
    /// Creates a standardized invalid-input error.
    pub fn invalid_input(code: &'static str, message: impl Into<String>, details: Option<Value>) -> Self {
        Self::InvalidInput {
            code,
            message: message.into(),
            details,
        }
    }

    /// Returns the stable machine-readable error code.
    pub fn code(&self) -> &'static str {
        match self {
            Self::InvalidInput { code, .. } => code,
            Self::Saturated { .. } => "SATURATED",
            Self::Distribution(_) => "DISTRIBUTION_ERROR",
            Self::Simulation(_) => "SIMULATION_ERROR",
        }
    }

    /// Returns optional structured details associated with this error.
    pub fn details(&self) -> Option<&Value> {
        match self {
            Self::InvalidInput { details, .. } => details.as_ref(),
            _ => None,
        }
    }
}