ocpi_tariffs/

guess.rs

//! Guess the `Version` of the given `CDR` or tariff.
use std::fmt;

use tracing::debug;

use crate::{cdr, json, tariff, v211, v221, ParseError, Unversioned, Versioned};

/// The result of calling `cdr::parse`.
pub type CdrVersion<'buf> = Version<cdr::Versioned<'buf>, cdr::Unversioned<'buf>>;

/// The result of calling `cdr::parse_and_report`.
pub type CdrReport<'buf> = Report<'buf, cdr::Versioned<'buf>, cdr::Unversioned<'buf>>;

/// Guess the `Version` of the given CDR.
///
/// See: `cdr::guess_version`.
pub(crate) fn cdr_version(cdr_json: &str) -> Result<CdrVersion<'_>, ParseError> {
    guess_cdr_version(cdr_json)
}

/// Guess the `Version` of the given CDR and report on any unexpected fields in the JSON.
///
/// See: `cdr::guess_version_with_report`.
pub(crate) fn cdr_version_and_report(cdr_json: &str) -> Result<CdrReport<'_>, ParseError> {
    let version = guess_cdr_version(cdr_json)?;

    let Version::Certain(cdr) = version else {
        return Ok(Report {
            version,
            unexpected_fields: json::UnexpectedFields::empty(),
        });
    };

    let schema = match cdr.version() {
        crate::Version::V211 => &v211::CDR_SCHEMA,
        crate::Version::V221 => &v221::CDR_SCHEMA,
    };

    let report = json::parse_with_schema(cdr_json, schema).map_err(ParseError::from_cdr_err)?;
    let json::ParseReport {
        element: _,
        unexpected_fields,
    } = report;

    Ok(CdrReport {
        unexpected_fields,
        version: Version::Certain(cdr),
    })
}

/// Try guess a CDR's [`Version`] and return a [`CdrVersion`] with the outcome.
fn guess_cdr_version(source: &str) -> Result<CdrVersion<'_>, ParseError> {
    /// The list of field names exclusively defined in the `v221` spec.
    const V211_EXCLUSIVE_FIELDS: &[&str] = &["stop_date_time"];

    /// The list of field names shared between the `v211` and `v221` specs.
    const V221_EXCLUSIVE_FIELDS: &[&str] = &["end_date_time", "cdr_location", "cdr_token"];

    let element = json::parse(source).map_err(ParseError::from_cdr_err)?;
    let value = element.value();
    let json::Value::Object(fields) = value else {
        return Err(ParseError::cdr_should_be_object());
    };

    for field in fields {
        let key = field.key().as_raw();

        if V211_EXCLUSIVE_FIELDS.contains(&key) {
            return Ok(Version::Certain(cdr::Versioned::new(
                source,
                element,
                crate::Version::V211,
            )));
        } else if V221_EXCLUSIVE_FIELDS.contains(&key) {
            return Ok(Version::Certain(cdr::Versioned::new(
                source,
                element,
                crate::Version::V221,
            )));
        }
    }

    Ok(Version::Uncertain(cdr::Unversioned::new(source, element)))
}

/// The result of calling `tariff::parse`.
pub type TariffVersion<'buf> = Version<tariff::Versioned<'buf>, tariff::Unversioned<'buf>>;

/// The result of calling `tariff::parse_and_report`.
pub type TariffReport<'buf> = Report<'buf, tariff::Versioned<'buf>, tariff::Unversioned<'buf>>;

/// Guess the `Version` of the given tariff.
///
/// See: [`tariff::parse`]
pub(super) fn tariff_version(tariff_json: &str) -> Result<TariffVersion<'_>, ParseError> {
    guess_tariff_version(tariff_json)
}

/// Guess the `Version` of the given tariff and report on any unexpected fields in the JSON.
///
/// See: [`tariff::parse_and_report`]
pub(super) fn tariff_version_with_report(
    tariff_json: &str,
) -> Result<TariffReport<'_>, ParseError> {
    let version = guess_tariff_version(tariff_json)?;

    let Version::Certain(object) = version else {
        return Ok(Report {
            version,
            unexpected_fields: json::UnexpectedFields::empty(),
        });
    };

    let schema = match object.version() {
        crate::Version::V211 => &v211::TARIFF_SCHEMA,
        crate::Version::V221 => &v221::TARIFF_SCHEMA,
    };

    let report =
        json::parse_with_schema(tariff_json, schema).map_err(ParseError::from_tariff_err)?;
    let json::ParseReport {
        element: _,
        unexpected_fields,
    } = report;

    Ok(TariffReport {
        unexpected_fields,
        version: Version::Certain(object),
    })
}

/// The private impl for detecting a tariff's version
fn guess_tariff_version(source: &str) -> Result<TariffVersion<'_>, ParseError> {
    /// The list of field names exclusively defined in the `v221` spec.
    const V221_EXCLUSIVE_FIELDS: &[&str] = &[
        "country_code",
        "party_id",
        "type",
        "min_price",
        "max_price",
        "start_date_time",
        "end_date_time",
    ];

    /// The list of field names shared between the `v211` and `v221` specs.
    const V211_V221_SHARED_FIELDS: &[&str] = &[
        "id",
        "currency",
        "tariff_alt_text",
        "tariff_alt_url",
        "elements",
        "energy_mix",
        "last_updated",
    ];

    // Parse the tariff without a schema first to determine the version.
    let element = json::parse(source).map_err(ParseError::from_tariff_err)?;
    let value = element.value();
    let json::Value::Object(fields) = value else {
        return Err(ParseError::tariff_should_be_object());
    };

    for field in fields {
        let key = field.key().as_raw();

        // If the field is in the v221 exclusive list we know without a doubt that it's a v221 tariff.
        if V221_EXCLUSIVE_FIELDS.contains(&key) {
            debug!("Tariff is v221 because of field: `{key}`");
            return Ok(TariffVersion::Certain(tariff::Versioned::new(
                source,
                element,
                crate::Version::V221,
            )));
        }
    }

    for field in fields {
        let key = field.key().as_raw();

        if V211_V221_SHARED_FIELDS.contains(&key) {
            return Ok(TariffVersion::Certain(tariff::Versioned::new(
                source,
                element,
                crate::Version::V211,
            )));
        }
    }

    Ok(TariffVersion::Uncertain(tariff::Unversioned::new(
        source, element,
    )))
}

/// An OCPI object with a certain or uncertain version.
#[derive(Debug)]
pub enum Version<V, U>
where
    V: Versioned,
    U: fmt::Debug,
{
    /// The version of the object `V` is certain.
    Certain(V),

    /// The version of the object `U` is uncertain.
    Uncertain(U),
}

impl<V, U> Version<V, U>
where
    V: Versioned,
    U: Unversioned<Versioned = V>,
{
    /// Convert the OCPI object into it's [`Version`](crate::Version) if it's [`Versioned`].
    /// Otherwise return `Uncertain(())`.
    pub fn into_version(self) -> Version<crate::Version, ()> {
        match self {
            Version::Certain(v) => Version::Certain(v.version()),
            Version::Uncertain(_) => Version::Uncertain(()),
        }
    }

    /// Convert a reference to the an OCPI object into it's [`Version`](crate::Version) if it's [`Versioned`].
    /// Otherwise return `Uncertain(())`.
    pub fn as_version(&self) -> Version<crate::Version, ()> {
        match self {
            Version::Certain(v) => Version::Certain(v.version()),
            Version::Uncertain(_) => Version::Uncertain(()),
        }
    }

    /// Return the contained OCPI object if it's [`Versioned`]. Otherwise force convert the object
    /// to the given [`Version`](crate::Version).
    pub fn certain_or(self, fallback: crate::Version) -> V {
        match self {
            Version::Certain(v) => v,
            Version::Uncertain(u) => u.force_into_versioned(fallback),
        }
    }

    /// Return `Some` OCPI object if it's [`Versioned`]. Otherwise return None if the object's version is uncertain.
    pub fn certain_or_none(self) -> Option<V> {
        match self {
            Version::Certain(v) => Some(v),
            Version::Uncertain(_) => None,
        }
    }
}

/// The guess version report.
///
/// This contains the guessed version of the given JSON object and a list of unexpected fields
/// if the JSON contains fields not specified in the guessed version of the OCPI spec.
///
/// The `unexpected_fields` list will always be empty if the guessed `Version` is `Uncertain`.
#[derive(Debug)]
pub struct Report<'buf, V, U>
where
    V: Versioned,
    U: fmt::Debug,
{
    /// A list of fields that were not expected: The schema did not define them.
    ///
    /// This list will always be empty if the guessed `Version` is `Uncertain`.
    pub unexpected_fields: json::UnexpectedFields<'buf>,

    /// The guessed version.
    ///
    /// The `unexpected_fields` list will always be empty if the guessed `Version` is `Uncertain`.
    pub version: Version<V, U>,
}

#[cfg(test)]
mod test {
    use super::{Unversioned, Version, Versioned};

    impl<V, U> Version<V, U>
    where
        V: Versioned,
        U: Unversioned<Versioned = V>,
    {
        /// Return the `Versioned` object if the `Version` is `Certain`.
        ///
        /// # Panics
        ///
        /// Will panic if the `Version` is `Uncertain`.
        pub fn unwrap_certain(self) -> V {
            match self {
                Version::Certain(v) => v,
                Version::Uncertain(_) => panic!("The version of the object is unknown"),
            }
        }
    }
}

#[cfg(test)]
mod test_guess_cdr {
    use assert_matches::assert_matches;

    use crate::{test, Versioned as _};

    use super::{cdr_version_and_report, Report, Version};

    #[test]
    fn should_guess_cdr_version_v211() {
        const JSON: &str = include_str!("../test_data/v211/lint/every_field_set/cdr.json");

        test::setup();

        let Report {
            version,
            unexpected_fields,
        } = cdr_version_and_report(JSON).unwrap();

        let cdr = assert_matches!(version, Version::Certain ( cdr ) => cdr );
        assert_matches!(cdr.version(), crate::Version::V211);

        test::assert_no_unexpected_fields(&unexpected_fields);
    }

    #[test]
    fn should_guess_cdr_version_v221() {
        const JSON: &str = include_str!("../test_data/v221/lint/every_field_set/cdr.json");

        test::setup();

        let Report {
            version,
            unexpected_fields,
        } = cdr_version_and_report(JSON).unwrap();

        let cdr = assert_matches!(version, Version::Certain ( cdr ) => cdr );
        assert_matches!(cdr.version(), crate::Version::V221);

        test::assert_no_unexpected_fields(&unexpected_fields);
    }
}

#[cfg(test)]
mod test_guess_tariff {
    use assert_matches::assert_matches;

    use crate::{test, Versioned as _};

    use super::{tariff_version_with_report, Report, Version};

    #[test]
    fn should_guess_tariff_version_v211() {
        const JSON: &str = include_str!("../test_data/v211/lint/every_field_set/tariff.json");

        test::setup();

        let Report {
            version,
            unexpected_fields,
        } = tariff_version_with_report(JSON).unwrap();

        let tariff = assert_matches!(version, Version::Certain ( tariff ) => tariff );
        assert_matches!(tariff.version(), crate::Version::V211);

        test::assert_no_unexpected_fields(&unexpected_fields);
    }

    #[test]
    fn should_guess_tariff_version_v221() {
        const JSON: &str = include_str!("../test_data/v221/lint/every_field_set/tariff.json");

        test::setup();

        let Report {
            version,
            unexpected_fields,
        } = tariff_version_with_report(JSON).unwrap();

        let tariff = assert_matches!(version, Version::Certain ( tariff ) => tariff );
        assert_matches!(tariff.version(), crate::Version::V221);

        test::assert_no_unexpected_fields(&unexpected_fields);
    }
}

#[cfg(test)]
mod test_real_world {
    use std::path::Path;

    use assert_matches::assert_matches;

    use crate::{test, Versioned as _};

    use super::{cdr_version_and_report, tariff_version_with_report, Report, Version};

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v221/real_world/*/cdr*.json",
        name(segments = 2)
    )]
    fn should_guess_version_v221(cdr_json: &str, path: &Path) {
        test::setup();

        {
            let Report {
                version,
                unexpected_fields,
            } = cdr_version_and_report(cdr_json).unwrap();

            let tariff = assert_matches!(version, Version::Certain ( tariff ) => tariff );
            assert_matches!(tariff.version(), crate::Version::V221);

            test::assert_no_unexpected_fields(&unexpected_fields);
        }

        {
            let tariff = std::fs::read_to_string(path.parent().unwrap().join("tariff.json")).ok();

            if let Some(tariff) = tariff {
                let Report {
                    version: guess,
                    unexpected_fields,
                } = tariff_version_with_report(&tariff).unwrap();

                let tariff = assert_matches!(guess, Version::Certain ( tariff ) => tariff);
                assert_matches!(tariff.version(), crate::Version::V221);

                test::assert_no_unexpected_fields(&unexpected_fields);
            }
        }
    }

    #[test_each::file(
        glob = "ocpi-tariffs/test_data/v211/lint/*/cdr*.json",
        name(segments = 2)
    )]
    fn should_guess_version_v211(cdr_json: &str, path: &Path) {
        test::setup();

        {
            let Report {
                version: guess,
                unexpected_fields,
            } = cdr_version_and_report(cdr_json).unwrap();

            let cdr = assert_matches!(guess, Version::Certain ( cdr ) => cdr);
            assert_matches!(cdr.version(), crate::Version::V211);

            test::assert_no_unexpected_fields(&unexpected_fields);
        }

        {
            let tariff_json =
                std::fs::read_to_string(path.parent().unwrap().join("tariff.json")).ok();

            if let Some(tariff) = tariff_json {
                let Report {
                    version: guess,
                    unexpected_fields,
                } = tariff_version_with_report(&tariff).unwrap();

                let tariff = assert_matches!(guess, Version::Certain ( tariff ) => tariff);
                assert_matches!(tariff.version(), crate::Version::V211);

                test::assert_no_unexpected_fields(&unexpected_fields);
            }
        }
    }
}