use core::fmt;
use core::str::FromStr;
use serde::{Deserialize, Serialize};
use super::builder::strict_builder;
use super::text::Text;
use super::validate::{Validate, Validator, ViolationCode, validate_fields};
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum Code {
Success,
HubjectSystemError,
HubjectDatabaseError,
DataTransactionError,
UnauthorizedAccess,
InconsistentEvseId,
InconsistentEvcoId,
SystemError,
DataError,
QrCodeAuthenticationFailed,
RfidInvalidUid,
RfidCardNotReadable,
PlcInvalidEvcoId,
NoPositiveAuthenticationResponse,
QrCodeAppTimeout,
PlcInvalidUnderlyingEvcoId,
PlcInvalidCertificate,
PlcTimeout,
EvcoIdLocked,
NoValidContract,
PartnerNotFound,
PartnerDidNotRespond,
ServiceNotAvailable,
SessionIsInvalid,
CommunicationToEvseFailed,
NoEvConnectedToEvse,
EvseAlreadyReserved,
EvseAlreadyInUse,
UnknownEvseId,
EvseIdNotHubjectCompatible,
EvseOutOfService,
Custom(String),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum CodeArea {
General,
InternalSystem,
Authentication,
Session,
Evse,
Unknown,
}
macro_rules! code_table {
($( $variant:ident = $wire:literal, $area:ident, $text:literal );* $(;)?) => {
impl Code {
pub const ALL: &'static [Self] = &[ $( Self::$variant ),* ];
#[must_use]
pub fn as_str(&self) -> &str {
match self {
$( Self::$variant => $wire, )*
Self::Custom(s) => s.as_str(),
}
}
#[must_use]
pub fn description(&self) -> &str {
match self {
$( Self::$variant => $text, )*
Self::Custom(_) => "a status code this version of oicp-kit does not know",
}
}
#[must_use]
pub fn area(&self) -> CodeArea {
match self {
$( Self::$variant => CodeArea::$area, )*
Self::Custom(_) => CodeArea::Unknown,
}
}
#[must_use]
pub fn is_known(&self) -> bool {
!matches!(self, Self::Custom(_))
}
}
impl From<&str> for Code {
fn from(s: &str) -> Self {
match s {
$( $wire => Self::$variant, )*
other => Self::Custom(other.to_owned()),
}
}
}
};
}
code_table! {
Success = "000", General, "Success";
HubjectSystemError = "001", InternalSystem, "Hubject system error";
HubjectDatabaseError = "002", InternalSystem, "Hubject database error";
DataTransactionError = "009", InternalSystem, "Data transaction error";
UnauthorizedAccess = "017", InternalSystem, "Unauthorized Access";
InconsistentEvseId = "018", InternalSystem, "Inconsistent EvseID";
InconsistentEvcoId = "019", InternalSystem, "Inconsistent EvcoID";
SystemError = "021", General, "System error";
DataError = "022", General, "Data error";
QrCodeAuthenticationFailed = "101", Authentication, "QR Code Authentication failed - Invalid Credentials";
RfidInvalidUid = "102", Authentication, "RFID Authentication failed - invalid UID";
RfidCardNotReadable = "103", Authentication, "RFID Authentication failed - card not readable";
PlcInvalidEvcoId = "105", Authentication, "PLC Authentication failed - invalid EvcoID";
NoPositiveAuthenticationResponse = "106", Authentication, "No positive authentication response";
QrCodeAppTimeout = "110", Authentication, "QR Code App Authentication failed - time out error";
PlcInvalidUnderlyingEvcoId = "120", Authentication, "PLC (ISO/IEC 15118) Authentication failed - invalid underlying EvcoID";
PlcInvalidCertificate = "121", Authentication, "PLC (ISO/IEC 15118) Authentication failed - invalid certificate";
PlcTimeout = "122", Authentication, "PLC (ISO/IEC 15118) Authentication failed - time out error";
EvcoIdLocked = "200", Authentication, "EvcoID locked";
NoValidContract = "210", Session, "No valid contract";
PartnerNotFound = "300", Session, "Partner not found";
PartnerDidNotRespond = "310", Session, "Partner did not respond";
ServiceNotAvailable = "320", Session, "Service not available";
SessionIsInvalid = "400", Session, "Session is invalid";
CommunicationToEvseFailed = "501", Evse, "Communication to EVSE failed";
NoEvConnectedToEvse = "510", Evse, "No EV connected to EVSE";
EvseAlreadyReserved = "601", Evse, "EVSE already reserved";
EvseAlreadyInUse = "602", Evse, "EVSE already in use/ wrong token";
UnknownEvseId = "603", Evse, "Unknown EVSE ID";
EvseIdNotHubjectCompatible = "604", Evse, "EVSE ID is not Hubject compatible";
EvseOutOfService = "700", Evse, "EVSE out of service";
}
impl Code {
#[must_use]
pub fn is_success(&self) -> bool {
matches!(self, Self::Success)
}
#[must_use]
pub fn is_retryable(&self) -> bool {
matches!(
self,
Self::HubjectSystemError
| Self::HubjectDatabaseError
| Self::DataTransactionError
| Self::SystemError
| Self::PartnerDidNotRespond
| Self::ServiceNotAvailable
)
}
#[must_use]
pub fn is_authorization_failure(&self) -> bool {
self.area() == CodeArea::Authentication || matches!(self, Self::NoValidContract)
}
#[must_use]
pub fn is_evse_problem(&self) -> bool {
self.area() == CodeArea::Evse
}
}
impl fmt::Display for Code {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{} {}", self.as_str(), self.description())
}
}
impl FromStr for Code {
type Err = core::convert::Infallible;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Ok(Self::from(s))
}
}
impl Serialize for Code {
fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
s.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for Code {
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
struct V;
impl serde::de::Visitor<'_> for V {
type Value = Code;
fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("an OICP status code")
}
fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Code, E> {
Ok(Code::from(v))
}
fn visit_u64<E: serde::de::Error>(self, v: u64) -> Result<Code, E> {
Ok(Code::from(format!("{v:03}").as_str()))
}
fn visit_i64<E: serde::de::Error>(self, v: i64) -> Result<Code, E> {
Ok(Code::from(format!("{v:03}").as_str()))
}
}
d.deserialize_any(V)
}
}
#[cfg(feature = "schema")]
impl schemars::JsonSchema for Code {
fn schema_name() -> std::borrow::Cow<'static, str> {
"StatusCodeValue".into()
}
fn json_schema(_g: &mut schemars::SchemaGenerator) -> schemars::Schema {
schemars::json_schema!({ "type": "string", "pattern": "^[0-9]{3}$" })
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, bon::Builder)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
#[builder(finish_fn = build_unchecked)]
pub struct StatusCode {
#[serde(rename = "Code")]
pub code: Code,
#[serde(rename = "Description", default, skip_serializing_if = "Option::is_none")]
#[builder(into)]
pub description: Option<Text<200>>,
#[serde(rename = "AdditionalInfo", default, skip_serializing_if = "Option::is_none")]
#[builder(into)]
pub additional_info: Option<Text<1000>>,
}
impl StatusCode {
#[must_use]
pub fn new(code: Code) -> Self {
let description = Text::new(code.description()).ok();
Self { code, description, additional_info: None }
}
#[must_use]
pub fn success() -> Self {
Self::new(Code::Success)
}
#[must_use]
pub fn with_info(code: Code, additional_info: impl Into<String>) -> Self {
Self { additional_info: Text::new_unchecked(additional_info).into(), ..Self::new(code) }
}
#[must_use]
pub fn is_success(&self) -> bool {
self.code.is_success()
}
}
impl fmt::Display for StatusCode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.code)?;
if let Some(info) = &self.additional_info {
write!(f, " ({info})")?;
}
Ok(())
}
}
impl Validate for StatusCode {
fn validate_in(&self, v: &mut Validator) {
if let Code::Custom(value) = &self.code {
v.report_at(
"Code",
ViolationCode::PatternMismatch,
format!("{value:?} is not one of the {} status codes OICP 2.3 defines", Code::ALL.len()),
);
}
validate_fields!(self, v, description as "Description", additional_info as "AdditionalInfo");
}
}
impl From<Code> for StatusCode {
fn from(code: Code) -> Self {
Self::new(code)
}
}
strict_builder!(StatusCode, StatusCodeBuilder, status_code_builder);
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_code_in_the_spec_table_round_trips() {
for code in Code::ALL {
let json = serde_json::to_string(code).unwrap();
let back: Code = serde_json::from_str(&json).unwrap();
assert_eq!(*code, back);
assert_eq!(code.as_str().len(), 3);
}
assert_eq!(Code::ALL.len(), 31);
}
#[test]
fn an_unknown_code_is_preserved_not_dropped() {
let code: Code = serde_json::from_str(r#""999""#).unwrap();
assert!(!code.is_known());
assert_eq!(code.as_str(), "999");
assert_eq!(serde_json::to_string(&code).unwrap(), r#""999""#);
}
#[test]
fn a_code_sent_as_a_number_is_understood() {
let code: Code = serde_json::from_str("0").unwrap();
assert_eq!(code, Code::Success);
assert_eq!(serde_json::to_string(&code).unwrap(), r#""000""#);
}
#[test]
fn retry_semantics_come_from_the_table_not_from_guesswork() {
assert!(Code::HubjectSystemError.is_retryable());
assert!(Code::PartnerDidNotRespond.is_retryable());
assert!(Code::ServiceNotAvailable.is_retryable());
assert!(!Code::NoValidContract.is_retryable());
assert!(!Code::EvseAlreadyReserved.is_retryable());
assert!(!Code::UnauthorizedAccess.is_retryable());
assert!(!Code::Success.is_retryable());
}
#[test]
fn authorization_failures_are_classified_as_such() {
assert!(Code::RfidInvalidUid.is_authorization_failure());
assert!(Code::EvcoIdLocked.is_authorization_failure());
assert!(Code::NoValidContract.is_authorization_failure());
assert!(!Code::EvseOutOfService.is_authorization_failure());
assert!(Code::EvseOutOfService.is_evse_problem());
}
#[test]
fn a_status_carries_the_specs_own_description_by_default() {
let status = StatusCode::new(Code::UnknownEvseId);
assert_eq!(status.description.as_ref().unwrap().as_str(), "Unknown EVSE ID");
assert!(status.validate().is_ok());
}
}