ocpi-tariffs 0.52.0

//! Types for parsing v2.2.1 tariffs.

#[cfg(test)]
mod test_every_field_set;

#[cfg(test)]
mod test_from_schema;

use std::convert::Infallible;

use chrono::{DateTime, NaiveDate, NaiveTime, TimeDelta, Utc};
use rust_decimal::Decimal;

use super::{v2x, CpoId, Warning};
use crate::{
    country, currency,
    duration::Seconds,
    energy::{Ampere, Kw, Kwh},
    money::VatOrigin,
    number::FromDecimal as _,
    schema, string,
    warning::{self, GatherWarnings as _, IntoCaveat as _, IntoInfallible as _},
    FromSchema, Money, Price, Verdict, Weekday,
};

/// A tariff description used to generate a CDR.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#131-tariff-object>.
///
/// Note: The `country_code` and `party_id` fields are merged for simplicity as the two fields
/// represent a single CPO ID. Representing them as independent `Option` fields means we have to
/// handle the impossible case of `(Some, None)` and `(None, Some)` when a `v211` tariff is converted
/// to this `v221` tariff.
///
/// Note: We don't parse the `type`, `tariff_alt_text`, `tariff_alt_url`, `energy_mix` or `last_updated` fields
/// as they do not affect the generation of the CDR.
#[derive(Debug)]
pub(crate) struct Tariff<'buf> {
    /// The five character ID of the CPO that 'owns' this tariff.
    ///
    /// The first two characters are the ISO-3166 alpha-2 country code of the CPO.
    /// The remaining three characters are the ISO-15118 ID of the CPO.
    ///
    /// Note: `ocpi-tariffs` considers the `v221` tariff to be the "normalized" version.
    /// A `v211` tariff is converted to a `v221` tariff for various operations.
    /// The `v211` version does not contain `country_code` or `party_id` fields.
    /// When the `v211` version is converted into the "normalized" `v221` version
    /// the `party_id` field will by `None`.
    pub party_id: Option<CpoId<'buf>>,

    /// Uniquely identifies the tariff within the CPO's platform (and sub-operator platforms).
    pub id: string::CiMaxLen<'buf, 36>,

    /// ISO-4217 code of the currency of this tariff.
    pub currency: currency::Code,

    /// When this field is set, a Charging Session with this tariff will at least cost this amount.
    ///
    /// The generation of the CDR does not take VAT into account.
    pub min_price: Option<Price>,

    /// When this field is set, a Charging Session with this tariff will NOT cost more than this amount.
    ///
    /// The generation of the CDR does not take VAT into account.
    pub max_price: Option<Price>,

    /// The time when this tariff becomes active, in UTC, `time_zone` field of the Location can be used to convert to local time.
    /// Typically used for a new tariff that is already given with the location, before it becomes active.
    pub start_date_time: Option<DateTime<Utc>>,

    /// The time after which this tariff is no longer valid, in UTC, `time_zone` field if the Location can be used to convert to local time.
    /// Typically used when this tariff is going to be replaced with a different tariff in the near future.
    pub end_date_time: Option<DateTime<Utc>>,

    /// List of at least one Element.
    pub elements: Vec<Element>,
}

/// A Tariff Element is a group of Price Components that share a set of restrictions under which they apply.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#144-tariffelement-class>.
#[derive(Debug)]
pub(crate) struct Element {
    /// List of Price Components that each describe how a certain dimension is priced.
    pub price_components: Vec<PriceComponent>,

    /// Restrictions that describe under which circumstances the Price Components of this Tariff Element apply.
    pub restrictions: Option<Restrictions>,
}

/// List of price components that make up the pricing of this tariff.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_pricecomponent_class>.
#[derive(Debug)]
pub(crate) struct PriceComponent {
    /// The dimension that is being priced.
    pub dimension_type: v2x::DimensionType,

    /// Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.
    /// Not providing a VAT is different from 0% VAT, which would be a value of 0.0 here.
    pub vat: VatOrigin,

    /// Price per unit (excl. VAT) for this dimension.
    pub price: Money,

    /// Minimum amount to be billed. That is, the dimension will be billed in this `step_size` blocks.
    /// Consumed amounts are rounded up to the smallest multiple of `step_size` that is greater than the consumed amount.
    pub step_size: u64,
}

/// Whether a `TariffElement` applies only to reservation sessions.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_reservationrestrictiontype_enum>.
#[derive(Copy, Clone, Debug)]
pub(crate) enum ReservationRestrictionType {
    /// The element applies only to reservation sessions.
    Reservation,
    /// The element applies only when a reservation expires without the driver starting to charge.
    ReservationExpires,
}

impl FromSchema<'_, schema::v221::ReservationRestrictionType> for ReservationRestrictionType {
    type Warning = Infallible;

    fn from_schema(
        source: &schema::v221::ReservationRestrictionType,
    ) -> Verdict<Self, Self::Warning> {
        use schema::v221::ReservationRestrictionType;

        let v = match source {
            ReservationRestrictionType::Reservation => Self::Reservation,
            ReservationRestrictionType::ReservationExpires => Self::ReservationExpires,
        };

        Ok(v.into_infallible_caveat())
    }
}

/// A `TariffRestrictions` object describes if and when a Tariff Element becomes active or inactive during a Charging Session.
/// These restrictions are not to be interpreted as making the Tariff Element applicable or not applicable for the entire Charging Session.
///
/// When more than one restriction is set, they are to be treated as a logical AND.
/// So a Tariff Element is active if and only if all the properties in its `TariffRestrictions` match.
///
/// See: <https://github.com/ocpi/ocpi/blob/release-2.2.1-bugfixes/mod_tariffs.asciidoc#mod_tariffs_tariffrestrictions_class>.
#[derive(Debug)]
pub(crate) struct Restrictions {
    /// The `Element` is valid from this time of day in local time.
    ///
    /// The time zone is defined in the `time_zone` field of the Location.
    pub start_time: Option<NaiveTime>,

    /// The `Element` is valid until this time of day in local time.
    ///
    /// The time zone is defined in the `time_zone` field of the Location.
    pub end_time: Option<NaiveTime>,

    /// The `Element` is valid from this date (inclusive) in local time.
    ///
    /// The time zone is defined in the `time_zone` field of the Location.
    pub start_date: Option<NaiveDate>,

    /// The `Element` is valid until this date (exclusive) in local time.
    ///
    /// The time zone is defined in the `time_zone` field of the Location.
    pub end_date: Option<NaiveDate>,

    /// Minimum consumed energy in kWh, for example 20, valid from this amount of energy (inclusive) being used.
    pub min_kwh: Option<Kwh>,

    /// Maximum consumed energy in kWh, for example 50, valid until this amount of energy (exclusive) being used.
    pub max_kwh: Option<Kwh>,

    /// If the charging current is equal to or lower than this value, the associated `TariffElement` becomes inactive.
    pub min_current: Option<Ampere>,

    /// If the charging current is equal to or higher than this value, the associated `TariffElement` becomes inactive.
    pub max_current: Option<Ampere>,

    /// If the charging power is equal to or lower than this value, the associated `TariffElement` becomes inactive.
    pub min_power: Option<Kw>,

    /// If the charging power is equal to or higher than this value, the associated `TariffElement` becomes inactive.
    pub max_power: Option<Kw>,

    /// Minimum duration in seconds the Charging Session MUST last (inclusive).
    ///
    /// When the duration of a Charging Session is longer than the defined value, this `TariffElement` is or becomes active.
    /// Before that moment, this `TariffElement` is not yet active.
    pub min_duration: Option<TimeDelta>,

    /// Maximum duration in seconds the Charging Session MUST last (exclusive).
    ///
    /// When the duration of a Charging Session is shorter than the defined value, this `TariffElement` is or becomes active.
    /// After that moment, this `TariffElement` is no longer active.
    pub max_duration: Option<TimeDelta>,

    /// Which day(s) of the week this `TariffElement` is active.
    pub day_of_week: Option<Vec<Weekday>>,

    /// Whether this `TariffElement` applies only to reservation sessions.
    ///
    /// If set, this element never applies during a regular charging session.
    pub reservation: Option<ReservationRestrictionType>,
}

impl<'buf> FromSchema<'buf, schema::v221::Tariff<'buf>> for Tariff<'buf> {
    type Warning = Warning;

    fn from_schema(source: &schema::v221::Tariff<'buf>) -> Verdict<Self, Self::Warning> {
        let mut warnings = warning::Set::new();

        let country_code = warnings.ok_or_bail(&source.country_code)?;
        let country_code =
            country::CodeSet::from_schema(country_code)?.gather_warnings_into(&mut warnings);

        // We don't care if the country code is spec compliant, we just want the data.
        let country_code = match country_code {
            country::CodeSet::Alpha2(code) | country::CodeSet::Alpha3(code) => code,
        };

        let currency = warnings.ok_or_bail(&source.currency)?;
        let currency = currency::Code::from_schema(currency)?.gather_warnings_into(&mut warnings);

        let id = warnings.ok_or_bail(&source.id)?;
        let id = string::CiMaxLen::<'_, 36>::from_schema(id)?.gather_warnings_into(&mut warnings);

        let party_id = warnings.ok_or_bail(&source.party_id)?;
        let party_id =
            string::CiExactLen::<'_, 3>::from_schema(party_id)?.gather_warnings_into(&mut warnings);

        // The `v2.1.1` bare-number form and the `v2.2.1` object form are both already encoded
        // by `schema::v221::Price`, so there is no `PriceOrNumber` step here.
        let min_price = warnings.ok_or_bail(&source.min_price)?;
        let min_price = min_price
            .as_ref()
            .map(Price::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let max_price = warnings.ok_or_bail(&source.max_price)?;
        let max_price = max_price
            .as_ref()
            .map(Price::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let start_date_time = warnings.ok_or_bail(&source.start_date_time)?;
        let start_date_time = start_date_time
            .as_ref()
            .map(DateTime::<Utc>::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let end_date_time = warnings.ok_or_bail(&source.end_date_time)?;
        let end_date_time = end_date_time
            .as_ref()
            .map(DateTime::<Utc>::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        // An element the schema could not build rejects the tariff rather than being skipped:
        // a tariff missing one of its elements prices a session at the wrong rate.
        //
        // An `elements` array that is present but empty is not rejected here. The schema walk
        // reports it as a located `Cardinality` warning (the field is a `required_array`), and
        // no element is retained for an `Integrity::Ok` array, so this layer has nowhere to
        // anchor a warning of its own. `tariff::Versioned::to_v221` rejects such a tariff.
        let elements = warnings.ok_or_bail(&source.elements)?;
        let mut lowered = Vec::with_capacity(elements.len());
        for element in elements {
            let element = warnings.ok_or_bail(element)?;
            lowered.push(Element::from_schema(element)?.gather_warnings_into(&mut warnings));
        }

        let tariff = Tariff {
            currency,
            // Combine the `country_code` and `party_id` into a single CPO ID.
            party_id: Some(CpoId {
                country_code,
                id: party_id,
            }),
            id,
            min_price,
            max_price,
            start_date_time,
            end_date_time,
            elements: lowered,
        };

        Ok(tariff.into_caveat(warnings))
    }
}

impl<'buf> FromSchema<'buf, schema::v221::Element<'buf>> for Element {
    type Warning = Warning;

    fn from_schema(source: &schema::v221::Element<'buf>) -> Verdict<Self, Self::Warning> {
        let mut warnings = warning::Set::new();

        // `price_components` is required; an element that prices nothing is rejected.
        let components = warnings.ok_or_bail(&source.price_components)?;

        // A component lowers to `None` when its `type` is unknown, which drops it as
        // unpriceable. A component the schema could not build at all is a different case: the
        // element is rejected rather than silently priced without one of its components.
        let mut price_components = Vec::with_capacity(components.len());
        for component in components {
            let component = warnings.ok_or_bail(component)?;
            let component = Option::<PriceComponent>::from_schema(component)?
                .gather_warnings_into(&mut warnings);

            if let Some(component) = component {
                price_components.push(component);
            }
        }

        // `restrictions` is optional; absent or `null` leaves the element unrestricted. A
        // present but unusable value is rejected, because an element that silently loses its
        // restrictions applies more widely than authored and changes the price.
        let restrictions = warnings.ok_or_bail(&source.restrictions)?;
        let restrictions = restrictions
            .as_ref()
            .map(Restrictions::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let elem = Element {
            price_components,
            restrictions,
        };

        Ok(elem.into_caveat(warnings))
    }
}

impl<'buf> FromSchema<'buf, schema::v221::PriceComponent<'buf>> for Option<PriceComponent> {
    type Warning = Warning;

    fn from_schema(source: &schema::v221::PriceComponent<'buf>) -> Verdict<Self, Self::Warning> {
        let mut warnings = warning::Set::new();

        // An unknown (or wrong-typed) `type` makes the component unpriceable, so it is
        // dropped
        if let schema::Integrity::Err(_) = &source.dimension_type {
            return Ok(None.into_caveat(warnings));
        }
        let dimension_type = warnings.ok_or_bail(&source.dimension_type)?;
        let dimension_type =
            v2x::DimensionType::from_schema(&dimension_type.value()).into_infallible();

        // `vat` is optional. An absent or unusable value means no VAT is applicable, which is
        // distinct from an explicit `0.0`.
        let vat = source
            .vat
            .map_some(VatOrigin::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings)
            .unwrap_or(VatOrigin::NotProvided);

        let price = warnings.ok_or_bail(&source.price)?;
        let price = Decimal::from_schema(price)?.gather_warnings_into(&mut warnings);

        let step_size = warnings.ok_or_bail(&source.step_size)?;
        let step_size = u64::from_schema(step_size)?.gather_warnings_into(&mut warnings);

        let comp = PriceComponent {
            dimension_type,
            vat,
            price: Money::from_decimal(price),
            step_size,
        };

        Ok(Some(comp).into_caveat(warnings))
    }
}

impl<'buf> FromSchema<'buf, schema::v221::Restrictions<'buf>> for Restrictions {
    type Warning = Warning;

    fn from_schema(source: &schema::v221::Restrictions<'buf>) -> Verdict<Self, Self::Warning> {
        let mut warnings = warning::Set::new();

        // Every field is optional, so an absent one is `Ok(None)`. A field that is present but
        // unusable rejects the whole `Restrictions` instead of being dropped: silently
        // discarding one restriction widens or narrows when the element is active, which
        // changes the price.
        let start_time = warnings.ok_or_bail(&source.start_time)?;
        let start_time = start_time
            .as_ref()
            .map(NaiveTime::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let end_time = warnings.ok_or_bail(&source.end_time)?;
        let end_time = end_time
            .as_ref()
            .map(NaiveTime::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let start_date = warnings.ok_or_bail(&source.start_date)?;
        let start_date = start_date
            .as_ref()
            .map(NaiveDate::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let end_date = warnings.ok_or_bail(&source.end_date)?;
        let end_date = end_date
            .as_ref()
            .map(NaiveDate::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let min_kwh = warnings.ok_or_bail(&source.min_kwh)?;
        let min_kwh = min_kwh
            .as_ref()
            .map(Kwh::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let max_kwh = warnings.ok_or_bail(&source.max_kwh)?;
        let max_kwh = max_kwh
            .as_ref()
            .map(Kwh::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let min_current = warnings.ok_or_bail(&source.min_current)?;
        let min_current = min_current
            .as_ref()
            .map(Ampere::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let max_current = warnings.ok_or_bail(&source.max_current)?;
        let max_current = max_current
            .as_ref()
            .map(Ampere::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let min_power = warnings.ok_or_bail(&source.min_power)?;
        let min_power = min_power
            .as_ref()
            .map(Kw::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let max_power = warnings.ok_or_bail(&source.max_power)?;
        let max_power = max_power
            .as_ref()
            .map(Kw::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings);

        let min_duration = warnings.ok_or_bail(&source.min_duration)?;
        let min_duration = min_duration
            .as_ref()
            .map(Seconds::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings)
            .map(TimeDelta::from);

        let max_duration = warnings.ok_or_bail(&source.max_duration)?;
        let max_duration = max_duration
            .as_ref()
            .map(Seconds::from_schema)
            .transpose()?
            .gather_warnings_into(&mut warnings)
            .map(TimeDelta::from);

        // A `day_of_week` entry that could not be built is rejected for the same reason: a
        // list missing one of its days silently changes when the element applies.
        let day_of_week = warnings.ok_or_bail(&source.day_of_week)?;
        let day_of_week = match day_of_week {
            Some(days) => {
                let mut weekdays = Vec::with_capacity(days.len());
                for day in days {
                    let day = warnings.ok_or_bail(day)?;
                    weekdays.push(Weekday::from_schema(&day.value()).into_infallible());
                }
                Some(weekdays)
            }
            None => None,
        };

        let reservation = warnings.ok_or_bail(&source.reservation)?;
        let reservation = reservation.as_ref().map(|reservation| {
            ReservationRestrictionType::from_schema(&reservation.value()).into_infallible()
        });

        let res = Restrictions {
            start_time,
            end_time,
            start_date,
            end_date,
            min_kwh,
            max_kwh,
            min_current,
            max_current,
            min_power,
            max_power,
            min_duration,
            max_duration,
            day_of_week,
            reservation,
        };

        Ok(res.into_caveat(warnings))
    }
}