ocpi_tariffs/

lib.rs

//! # OCPI Tariffs library
//!
//! Calculate the (sub)totals of a [charge session](https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_cdrs.asciidoc)
//! using the [`cdr::price`] function and use the generated [`price::Report`] to review and compare the calculated
//! totals versus the sources from the `CDR`.
//!
//! See the [`price::Report`] for a detailed list of all the fields that help analyze and valitate the pricing of a `CDR`.
//!
//! - Use the [`cdr::parse`] and [`tariff::parse`] function to parse and guess which OCPI version of a CDR or tariff you have.
//! - Use the [`cdr::parse_with_version`] and [`tariff::parse_with_version`] functions to parse a CDR of tariff as the given version.
//! - Use the [`tariff::lint`] to lint a tariff: flag common errors, bugs, dangerous constructs and stylistic flaws in the tariff.
//!
//! # Examples
//!
//! ## Price a CDR with embedded tariff
//!
//! If you have a CDR JSON with an embedded tariff you can price the CDR with the following code:
//!
//! ```rust
//! # use ocpi_tariffs::{cdr, price, Version};
//! #
//! # const CDR_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time/cdr.json");
//!
//! let report = cdr::parse_with_version(CDR_JSON, Version::V211)?;
//! let cdr::ParseReport {
//!     cdr,
//!     unexpected_fields,
//! } = report;
//!
//! # if !unexpected_fields.is_empty() {
//! #     eprintln!("Strange... there are fields in the CDR that are not defined in the spec.");
//! #
//! #     for path in &unexpected_fields {
//! #         eprintln!("{path}");
//! #     }
//! # }
//!
//! let report = cdr::price(cdr, price::TariffSource::UseCdr, chrono_tz::Tz::Europe__Amsterdam)?;
//!
//! if !report.warnings.is_empty() {
//!     eprintln!("Pricing the CDR resulted in `{}` warnings", report.warnings.len());
//!
//!     for price::WarningReport { kind } in &report.warnings {
//!         eprintln!("  - {kind}");
//!     }
//! }
//!
//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
//! ```
//!
//! ## Price a CDR using tariff in separate JSON file
//!
//! If you have a CDR JSON with a tariff in a separate JSON file you can price the CDR with the
//! following code:
//!
//! ```rust
//! # use ocpi_tariffs::{cdr, price, Version};
//! #
//! # const CDR_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/cdr.json");
//! # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
//!
//! let report = cdr::parse_with_version(CDR_JSON, Version::V211)?;
//! let cdr::ParseReport {
//!     cdr,
//!     unexpected_fields,
//! } = report;
//!
//! # if !unexpected_fields.is_empty() {
//! #     eprintln!("Strange... there are fields in the CDR that are not defined in the spec.");
//! #
//! #     for path in &unexpected_fields {
//! #         eprintln!("{path}");
//! #     }
//! # }
//!
//! let report = cdr::price(cdr, price::TariffSource::Override(vec![TARIFF_JSON.to_string()]), chrono_tz::Tz::Europe__Amsterdam)?;
//!
//! if !report.warnings.is_empty() {
//!     eprintln!("Pricing the CDR resulted in `{}` warnings", report.warnings.len());
//!
//!     for price::WarningReport { kind } in &report.warnings {
//!         eprintln!("  - {kind}");
//!     }
//! }
//!
//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
//! ```
//!
//! ## Lint a tariff
//!
//! ```rust
//! # use ocpi_tariffs::{guess, tariff, warning};
//! #
//! # const TARIFF_JSON: &str = include_str!("../test_data/v211/real_world/time_and_parking_time_separate_tariff/tariff.json");
//!
//! let report = tariff::parse_and_report(TARIFF_JSON)?;
//! let guess::Report {
//!     unexpected_fields,
//!     version,
//! } = report;
//!
//! if !unexpected_fields.is_empty() {
//!     eprintln!("Strange... there are fields in the tariff that are not defined in the spec.");
//!
//!     for path in &unexpected_fields {
//!         eprintln!("  * {path}");
//!     }
//!
//!     eprintln!();
//! }
//!
//! let guess::Version::Certain(tariff) = version else {
//!     return Err("Unable to guess the version of given CDR JSON.".into());
//! };
//!
//! let report = tariff::lint(&tariff)?;
//! let warnings = report.into_warning_report();
//!
//! eprintln!("`{}` lint warnings found", warnings.len());
//!
//! for warning::ElementReport { element, warnings } in warnings.iter(tariff.as_element()) {
//!     eprintln!(
//!         "Warnings reported for `json::Element` at path: `{}`",
//!         element.path()
//!     );
//!
//!     for warning in warnings {
//!         eprintln!("  * {warning}");
//!     }
//!
//!     eprintln!();
//! }
//!
//! # Ok::<(), Box<dyn std::error::Error + Send + Sync + 'static>>(())
//! ```

pub mod cdr;
pub mod country;
pub mod currency;
pub mod datetime;
pub mod duration;
mod energy;
pub mod guess;
pub mod json;
pub mod lint;
pub mod money;
pub mod number;
pub mod price;
pub mod string;
pub mod tariff;
pub mod timezone;
mod v211;
mod v221;
pub mod warning;
pub mod weekday;

use std::{collections::BTreeSet, fmt};

#[expect(unused_imports, reason = "Soon to be used in `mod generator`")]
use string::CiString;
use warning::IntoCaveat;
use weekday::Weekday;

#[doc(inline)]
pub use duration::{ToDuration, ToHoursDecimal};
#[doc(inline)]
pub use energy::{Ampere, Kw, Kwh};
#[doc(inline)]
pub use money::{Cost, Money, Price, Vat, VatApplicable};
#[doc(inline)]
pub use warning::{Caveat, Verdict, VerdictExt, Warning};

/// Set of unexpected fields encountered while parsing a CDR or tariff.
pub type UnexpectedFields = BTreeSet<String>;

/// The Id for a tariff used in the pricing of a CDR.
pub type TariffId = String;

/// The OCPI versions supported by this crate
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Version {
    V221,
    V211,
}

impl Versioned for Version {
    fn version(&self) -> Version {
        *self
    }
}

impl fmt::Display for Version {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Version::V221 => f.write_str("v221"),
            Version::V211 => f.write_str("v211"),
        }
    }
}

/// An object for a specific OCPI [`Version`].
pub trait Versioned: fmt::Debug {
    /// Return the OCPI `Version` of this object.
    fn version(&self) -> Version;
}

/// An object with an uncertain [`Version`].
pub trait Unversioned: fmt::Debug {
    /// The concrete [`Versioned`] type.
    type Versioned: Versioned;

    /// Forced an [`Unversioned`] object to be the given [`Version`].
    ///
    /// This does not change the structure of the OCPI object.
    /// It simply relabels the object as a different OCPI Version.
    ///
    /// Use this with care.
    fn force_into_versioned(self, version: Version) -> Self::Versioned;
}

/// Out of range error type used in various converting APIs
#[derive(Clone, Copy, Hash, PartialEq, Eq)]
pub struct OutOfRange(());

impl std::error::Error for OutOfRange {}

impl OutOfRange {
    const fn new() -> OutOfRange {
        OutOfRange(())
    }
}

impl fmt::Display for OutOfRange {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "out of range")
    }
}

impl fmt::Debug for OutOfRange {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "out of range")
    }
}

/// Errors that can happen if a JSON str is parsed.
pub struct ParseError {
    /// The type of object we were trying to deserialize.
    object: ObjectType,

    /// The error that occurred while deserializing.
    kind: ParseErrorKind,
}

/// The kind of Error that occurred.
pub enum ParseErrorKind {
    /// Some Error types are erased to abvoid leaking dependencies.
    Erased(Box<dyn std::error::Error + Send + Sync + 'static>),

    /// The integrated JSON parser was unable to parse a JSON str.
    Json(json::Error),

    /// The OCPI object should be a JSON object.
    ShouldBeAnObject,
}

impl std::error::Error for ParseError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match &self.kind {
            ParseErrorKind::Erased(err) => Some(&**err),
            ParseErrorKind::Json(err) => Some(err),
            ParseErrorKind::ShouldBeAnObject => None,
        }
    }
}

impl fmt::Debug for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

impl fmt::Display for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "while deserializing {:?}: ", self.object)?;

        match &self.kind {
            ParseErrorKind::Erased(err) => write!(f, "{err}"),
            ParseErrorKind::Json(err) => write!(f, "{err}"),
            ParseErrorKind::ShouldBeAnObject => f.write_str("The root element should be an object"),
        }
    }
}

impl ParseError {
    /// Create a [`ParseError`] from a generic std Error for a CDR object.
    fn from_cdr_err(err: json::Error) -> Self {
        Self {
            object: ObjectType::Tariff,
            kind: ParseErrorKind::Json(err),
        }
    }

    /// Create a [`ParseError`] from a generic std Error for a tariff object.
    fn from_tariff_err(err: json::Error) -> Self {
        Self {
            object: ObjectType::Tariff,
            kind: ParseErrorKind::Json(err),
        }
    }

    /// Create a [`ParseError`] from a generic std Error for a CDR object.
    fn from_cdr_serde_err(err: serde_json::Error) -> Self {
        Self {
            object: ObjectType::Cdr,
            kind: ParseErrorKind::Erased(err.into()),
        }
    }

    /// Create a [`ParseError`] from a generic std Error for a tariff object.
    fn from_tariff_serde_err(err: serde_json::Error) -> Self {
        Self {
            object: ObjectType::Tariff,
            kind: ParseErrorKind::Erased(err.into()),
        }
    }

    fn cdr_should_be_object() -> ParseError {
        Self {
            object: ObjectType::Cdr,
            kind: ParseErrorKind::ShouldBeAnObject,
        }
    }

    fn tariff_should_be_object() -> ParseError {
        Self {
            object: ObjectType::Tariff,
            kind: ParseErrorKind::ShouldBeAnObject,
        }
    }

    /// Deconstruct the error.
    pub fn into_parts(self) -> (ObjectType, ParseErrorKind) {
        (self.object, self.kind)
    }
}

/// The type of OCPI objects that can be parsed.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum ObjectType {
    /// An OCPI Charge Detail Record.
    ///
    /// * See: [OCPI spec 2.2.1: CDR](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_cdrs.asciidoc>)
    Cdr,

    /// An OCPI tariff.
    ///
    /// * See: [OCPI spec 2.2.1: Tariff](<https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc>)
    Tariff,
}

/// Add two types together and saturate to max if the addition operation overflows.
///
/// This is private to the crate as `ocpi-tarifffs` does not want to provide numerical types for use by other crates.
pub(crate) trait SaturatingAdd {
    /// Add two types together and saturate to max if the addition operation overflows.
    #[must_use]
    fn saturating_add(self, other: Self) -> Self;
}

/// Subtract two types from each other and saturate to zero if the subtraction operation overflows.
///
/// This is private to the crate as `ocpi-tarifffs` does not want to provide numerical types for use by other crates.
pub(crate) trait SaturatingSub {
    /// Subtract two types from each other and saturate to zero if the subtraction operation overflows.
    #[must_use]
    fn saturating_sub(self, other: Self) -> Self;
}

/// A debug utility to `Display` an `Option<T>` as either `Display::fmt(T)` or the null set `∅`.
pub(crate) struct DisplayOption<T>(Option<T>)
where
    T: fmt::Display;

impl<T> fmt::Display for DisplayOption<T>
where
    T: fmt::Display,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.0 {
            Some(v) => fmt::Display::fmt(v, f),
            None => f.write_str("∅"),
        }
    }
}

#[cfg(test)]
mod test {
    #![allow(
        clippy::unwrap_in_result,
        reason = "unwraps are allowed anywhere in tests"
    )]

    use std::{env, fmt, io::IsTerminal as _, path::Path, sync::Once};

    use chrono::{DateTime, Utc};
    use rust_decimal::Decimal;
    use serde::{
        de::{value::StrDeserializer, IntoDeserializer as _},
        Deserialize,
    };
    use tracing::debug;
    use tracing_subscriber::util::SubscriberInitExt as _;

    use crate::{datetime, json, number};

    /// Creates and sets the default tracing subscriber if not already done.
    #[track_caller]
    pub fn setup() {
        static INITIALIZED: Once = Once::new();

        INITIALIZED.call_once_force(|state| {
            if state.is_poisoned() {
                return;
            }

            let is_tty = std::io::stderr().is_terminal();

            let level = match env::var("RUST_LOG") {
                Ok(s) => s.parse().unwrap_or(tracing::Level::INFO),
                Err(err) => match err {
                    env::VarError::NotPresent => tracing::Level::INFO,
                    env::VarError::NotUnicode(_) => {
                        panic!("`RUST_LOG` is not unicode");
                    }
                },
            };

            let subscriber = tracing_subscriber::fmt()
                .with_ansi(is_tty)
                .with_file(true)
                .with_level(false)
                .with_line_number(true)
                .with_max_level(level)
                .with_target(false)
                .with_test_writer()
                .without_time()
                .finish();

            subscriber
                .try_init()
                .expect("Init tracing_subscriber::Subscriber");
        });
    }

    /// Approximately compares two objects in tests.
    ///
    /// We need to approximately compare values in tests as we are not concerned with bitwise
    /// accuracy. Only that the values are equal within an object specific tolerance.
    ///
    /// # Examples
    ///
    /// - A `Money` object considers an amount equal if there is only 2 cent difference.
    /// - A `HoursDecimal` object considers a duration equal if there is only 3 second difference.
    pub trait ApproxEq<Rhs = Self> {
        #[must_use]
        fn approx_eq(&self, other: &Rhs) -> bool;
    }

    impl<T> ApproxEq for Option<T>
    where
        T: ApproxEq,
    {
        fn approx_eq(&self, other: &Self) -> bool {
            match (self, other) {
                (Some(a), Some(b)) => a.approx_eq(b),
                (None, None) => true,
                _ => false,
            }
        }
    }

    /// Approximately compare two `Decimal` values.
    pub fn approx_eq_dec(a: Decimal, mut b: Decimal, tolerance: Decimal, precision: u32) -> bool {
        let a = a.round_dp(precision);
        b.rescale(number::SCALE);
        let b = b.round_dp(precision);
        (a - b).abs() <= tolerance
    }

    #[track_caller]
    pub fn assert_no_unexpected_fields(unexpected_fields: &json::UnexpectedFields<'_>) {
        if !unexpected_fields.is_empty() {
            const MAX_FIELD_DISPLAY: usize = 20;

            if unexpected_fields.len() > MAX_FIELD_DISPLAY {
                let truncated_fields = unexpected_fields
                    .iter()
                    .take(MAX_FIELD_DISPLAY)
                    .map(|path| path.to_string())
                    .collect::<Vec<_>>();

                panic!(
                    "Unexpected fields found({}); displaying the first ({}): \n{}\n... and {} more",
                    unexpected_fields.len(),
                    truncated_fields.len(),
                    truncated_fields.join(",\n"),
                    unexpected_fields.len() - truncated_fields.len(),
                )
            } else {
                panic!(
                    "Unexpected fields found({}):\n{}",
                    unexpected_fields.len(),
                    unexpected_fields.to_strings().join(",\n")
                )
            };
        }
    }

    #[track_caller]
    pub fn assert_unexpected_fields(
        unexpected_fields: &json::UnexpectedFields<'_>,
        expected: &[&'static str],
    ) {
        if unexpected_fields.len() != expected.len() {
            let unexpected_fields = unexpected_fields
                .into_iter()
                .map(|path| path.to_string())
                .collect::<Vec<_>>();

            panic!(
                "The unexpected fields and expected fields lists have different lengths.\n\nUnexpected fields found:\n{}",
                unexpected_fields.join(",\n")
            );
        }

        let unmatched_paths = unexpected_fields
            .into_iter()
            .zip(expected.iter())
            .filter(|(a, b)| a != *b)
            .collect::<Vec<_>>();

        if !unmatched_paths.is_empty() {
            let unmatched_paths = unmatched_paths
                .into_iter()
                .map(|(a, b)| format!("{a} != {b}"))
                .collect::<Vec<_>>();

            panic!(
                "The unexpected fields don't match the expected fields.\n\nUnexpected fields found:\n{}",
                unmatched_paths.join(",\n")
            );
        }
    }

    /// A Field in the expect JSON.
    ///
    /// We need to distinguish between a field that's present and null and absent.
    #[derive(Debug, Default)]
    pub enum Expectation<T> {
        /// The field is present.
        Present(ExpectValue<T>),

        /// The field is not preent.
        #[default]
        Absent,
    }

    /// The value of an expectation field.
    #[derive(Debug)]
    pub enum ExpectValue<T> {
        /// The field has a value.
        Some(T),

        /// The field is set to `null`.
        Null,
    }

    impl<T> ExpectValue<T>
    where
        T: fmt::Debug,
    {
        /// Convert the expectation into an `Option`.
        pub fn into_option(self) -> Option<T> {
            match self {
                Self::Some(v) => Some(v),
                Self::Null => None,
            }
        }

        /// Consume the expectation and return the inner value of type `T`.
        ///
        /// # Panics
        ///
        /// Panics if the `FieldValue` is `Null`.
        #[track_caller]
        pub fn expect_value(self) -> T {
            match self {
                ExpectValue::Some(v) => v,
                ExpectValue::Null => panic!("the field expects a value"),
            }
        }
    }

    impl<'de, T> Deserialize<'de> for Expectation<T>
    where
        T: Deserialize<'de>,
    {
        #[expect(clippy::unwrap_in_result, reason = "This is test util code")]
        #[track_caller]
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: serde::Deserializer<'de>,
        {
            let value = serde_json::Value::deserialize(deserializer)?;

            if value.is_null() {
                return Ok(Expectation::Present(ExpectValue::Null));
            }

            let v = T::deserialize(value).unwrap();
            Ok(Expectation::Present(ExpectValue::Some(v)))
        }
    }

    /// Create a `DateTime` from a RFC 3339 formatted string.
    #[track_caller]
    pub fn datetime_from_str(s: &str) -> DateTime<Utc> {
        let de: StrDeserializer<'_, serde::de::value::Error> = s.into_deserializer();
        datetime::deser_to_utc(de).unwrap()
    }

    /// Try read an expectation JSON file based on the name of the given object JSON file.
    ///
    /// If the JSON object file is called `cdr.json` with a feature of `price` an expectation file
    /// called `expect_cdr_price.json` is searched for.
    #[track_caller]
    pub fn read_expect_json(json_file_path: &Path, feature: &str) -> Option<String> {
        let json_dir = json_file_path
            .parent()
            .expect("The given file should live in a dir");

        let json_file_name = json_file_path
            .file_stem()
            .expect("The `json_file_path` should be a file")
            .to_str()
            .expect("The `json_file_path` should have a valid name");

        // An underscore is prefixed to the filename to exclude the file from being included
        // as input for a `test_each` glob driven test.
        let expect_file_name = format!("output_{feature}__{json_file_name}.json");

        debug!("Try to read expectation file: `{expect_file_name}`");

        let s = std::fs::read_to_string(json_dir.join(&expect_file_name))
            .ok()
            .map(|mut s| {
                json_strip_comments::strip(&mut s).ok();
                s
            });

        debug!("Successfully Read expectation file: `{expect_file_name}`");
        s
    }

    #[track_caller]
    pub fn assert_approx_eq_failed(
        left: &dyn fmt::Debug,
        right: &dyn fmt::Debug,
        args: Option<fmt::Arguments<'_>>,
    ) -> ! {
        match args {
            Some(args) => panic!(
                "assertion `left == right` failed: {args}
left: {left:?}
right: {right:?}"
            ),
            None => panic!(
                "assertion `left == right` failed
left: {left:?}
right: {right:?}"
            ),
        }
    }

    /// This code s copied from the std lib `assert_eq!` and modified for use with `ApproxEq`.
    #[macro_export]
    macro_rules! assert_approx_eq {
        ($left:expr, $right:expr $(,)?) => ({
            use $crate::test::ApproxEq;

            match (&$left, &$right) {
                (left_val, right_val) => {
                    if !((*left_val).approx_eq(&*right_val)) {
                        // The reborrows below are intentional. Without them, the stack slot for the
                        // borrow is initialized even before the values are compared, leading to a
                        // noticeable slow down.
                        $crate::test::assert_approx_eq_failed(
                            &*left_val,
                            &*right_val,
                            std::option::Option::None
                        );
                    }
                }
            }
        });
        ($left:expr, $right:expr, $($arg:tt)+) => ({
            use $crate::test::ApproxEq;

            match (&$left, &$right) {
                (left_val, right_val) => {
                    if !((*left_val).approx_eq(&*right_val)) {
                        // The reborrows below are intentional. Without them, the stack slot for the
                        // borrow is initialized even before the values are compared, leading to a
                        // noticeable slow down.
                        $crate::test::assert_approx_eq_failed(
                            &*left_val,
                            &*right_val,
                            std::option::Option::Some(std::format_args!($($arg)+))
                        );
                    }
                }
            }
        });
    }
}

#[cfg(test)]
mod test_rust_decimal_arbitrary_precision {
    use rust_decimal_macros::dec;

    #[test]
    fn should_serialize_decimal_with_12_fraction_digits() {
        let dec = dec!(0.123456789012);
        let actual = serde_json::to_string(&dec).unwrap();
        assert_eq!(actual, r#""0.123456789012""#.to_owned());
    }

    #[test]
    fn should_serialize_decimal_with_8_fraction_digits() {
        let dec = dec!(37.12345678);
        let actual = serde_json::to_string(&dec).unwrap();
        assert_eq!(actual, r#""37.12345678""#.to_owned());
    }

    #[test]
    fn should_serialize_0_decimal_without_fraction_digits() {
        let dec = dec!(0);
        let actual = serde_json::to_string(&dec).unwrap();
        assert_eq!(actual, r#""0""#.to_owned());
    }

    #[test]
    fn should_serialize_12_num_with_4_fraction_digits() {
        let num = dec!(0.1234);
        let actual = serde_json::to_string(&num).unwrap();
        assert_eq!(actual, r#""0.1234""#.to_owned());
    }

    #[test]
    fn should_serialize_8_num_with_4_fraction_digits() {
        let num = dec!(37.1234);
        let actual = serde_json::to_string(&num).unwrap();
        assert_eq!(actual, r#""37.1234""#.to_owned());
    }

    #[test]
    fn should_serialize_0_num_without_fraction_digits() {
        let num = dec!(0);
        let actual = serde_json::to_string(&num).unwrap();
        assert_eq!(actual, r#""0""#.to_owned());
    }
}