use futures_core::Stream;
use futures_util::StreamExt as _;
use serde::de::DeserializeOwned;
use serde_json::value::RawValue;
use super::http::{ClientConfig, Transport, warn_on_identity_mismatch};
use super::identity::{ClientIdentity, IdentityWarning};
use crate::cpo::{AuthorizeRemoteStartRequest, AuthorizeRemoteStopRequest, ChargeDetailRecord};
use crate::emp::{
ChargeDetailRecordsResponse, EvsePricingResponse, EvseStatusByIdResponse, EvseStatusResponse,
GetChargeDetailRecordsRequest, Page, PricingProductDataResponse, PullEvseDataRecord, PullEvseDataRequest,
PullEvsePricingRequest, PullEvseStatusByIdRequest, PullEvseStatusByOperatorIdRequest,
PullEvseStatusRequest, PullPricingProductDataRequest, PushAuthenticationDataRequest,
};
use crate::transport::{HubjectEnv, OicpError, Operation, PageQuery, PathId, Result};
use crate::types::{Acknowledgement, ProviderId, Validate};
#[derive(Debug, thiserror::Error)]
pub enum CrawlError {
#[error("page {page} could not be fetched: {source}")]
Page {
page: u32,
#[source]
source: OicpError,
},
#[error("record {index} on page {page} could not be decoded: {message}")]
Record {
page: u32,
index: usize,
message: String,
},
#[error("page {page} is inconsistent: {message}")]
PageInconsistent {
page: u32,
message: String,
},
}
fn decode_page<T: DeserializeOwned>(
page: Page<Box<RawValue>>,
query: PageQuery,
) -> (Vec<core::result::Result<T, CrawlError>>, Option<PageQuery>) {
let mut items: Vec<core::result::Result<T, CrawlError>> = Vec::with_capacity(page.content.len() + 1);
let counted = page.total_pages > 0;
let more_by_count = counted && query.page + 1 < page.total_pages;
let more_by_flag = !page.last;
let (next, complaint) = if page.content.is_empty() {
(None, more_by_flag.then(|| format!("page {} is empty but last is false", page.number)))
} else if more_by_flag && (more_by_count || !counted) {
(Some(query.next()), None)
} else if more_by_flag {
(None, Some(format!("last is false on page {} of {}", page.number, page.total_pages)))
} else if more_by_count {
(
Some(query.next()),
Some(format!(
"last is true on page {} of {}; crawling on by totalPages rather than stopping",
page.number, page.total_pages
)),
)
} else {
(None, None)
};
if let Some(message) = complaint {
items.push(Err(CrawlError::PageInconsistent { page: query.page, message }));
}
for (index, raw) in page.content.into_iter().enumerate() {
items.push(match serde_json::from_str::<T>(raw.get()) {
Ok(record) => Ok(record),
Err(error) => Err(CrawlError::Record { page: query.page, index, message: error.to_string() }),
});
}
(items, next)
}
#[derive(Debug, Clone)]
pub struct EmpClient {
transport: Transport,
provider_id: ProviderId,
identity_warning: Option<IdentityWarning>,
}
#[derive(Default)]
pub struct EmpClientBuilder {
environment: Option<HubjectEnv>,
provider_id: Option<ProviderId>,
identity: Option<ClientIdentity>,
config: Option<ClientConfig>,
}
impl EmpClientBuilder {
#[must_use]
pub fn environment(mut self, environment: HubjectEnv) -> Self {
self.environment = Some(environment);
self
}
#[must_use]
pub fn provider_id(mut self, provider_id: ProviderId) -> Self {
self.provider_id = Some(provider_id);
self
}
#[must_use]
pub fn identity(mut self, identity: ClientIdentity) -> Self {
self.identity = Some(identity);
self
}
#[must_use]
pub fn config(mut self, config: ClientConfig) -> Self {
self.config = Some(config);
self
}
pub fn build(self) -> Result<EmpClient> {
let provider_id = self.provider_id.ok_or_else(|| {
OicpError::transport("an EmpClient needs a ProviderID: it goes in every URL path")
})?;
let mut config = self.config.unwrap_or_default();
if let Some(environment) = self.environment {
config.environment = environment;
}
let identity_warning = warn_on_identity_mismatch(self.identity.as_ref(), provider_id.as_str());
let transport = Transport::new(config, self.identity.as_ref())?;
Ok(EmpClient { transport, provider_id, identity_warning })
}
}
impl EmpClient {
#[must_use]
pub fn builder() -> EmpClientBuilder {
EmpClientBuilder::default()
}
#[must_use]
pub const fn provider_id(&self) -> &ProviderId {
&self.provider_id
}
#[must_use]
pub const fn transport(&self) -> &Transport {
&self.transport
}
#[must_use]
pub const fn identity_warning(&self) -> Option<&IdentityWarning> {
self.identity_warning.as_ref()
}
fn path_id(&self) -> PathId {
PathId::Provider(self.provider_id.clone())
}
pub async fn pull_evse_data_page(
&self,
request: &PullEvseDataRequest,
query: PageQuery,
) -> Result<Page<PullEvseDataRecord>> {
let page = self.pull_evse_data_page_raw(request, query).await?;
let mut index = 0_usize;
page.try_map(|raw| {
let decoded = serde_json::from_str(raw.get()).map_err(|error| OicpError::Decode {
pointer: Some(format!("/content/{index}")),
message: error.to_string(),
});
index += 1;
decoded
})
}
pub async fn pull_evse_data_page_raw(
&self,
request: &PullEvseDataRequest,
query: PageQuery,
) -> Result<Page<Box<RawValue>>> {
if self.transport.config().validate_requests {
request.validate()?;
}
let base =
Operation::PullEvseData.url(self.transport.config().environment.base_url(), &self.path_id())?;
let url = query.append_to(&base);
self.transport.post_raw(Operation::PullEvseData, &url, request).await
}
pub fn crawl_evse_data(
&self,
request: PullEvseDataRequest,
start: PageQuery,
) -> impl Stream<Item = core::result::Result<PullEvseDataRecord, CrawlError>> + '_ {
futures_util::stream::unfold(Some(start), move |state| {
let request = request.clone();
async move {
let query = state?;
match self.pull_evse_data_page_raw(&request, query).await {
Err(source) => Some((vec![Err(CrawlError::Page { page: query.page, source })], None)),
Ok(page) => Some(decode_page(page, query)),
}
}
})
.flat_map(futures_util::stream::iter)
}
pub async fn pull_evse_status(&self, request: &PullEvseStatusRequest) -> Result<EvseStatusResponse> {
self.transport.post(Operation::PullEvseStatus, &self.path_id(), request).await
}
pub async fn pull_evse_status_by_id(
&self,
request: &PullEvseStatusByIdRequest,
) -> Result<EvseStatusByIdResponse> {
self.transport.post(Operation::PullEvseStatus, &self.path_id(), request).await
}
pub async fn pull_evse_status_by_operator_id(
&self,
request: &PullEvseStatusByOperatorIdRequest,
) -> Result<EvseStatusResponse> {
self.transport.post(Operation::PullEvseStatus, &self.path_id(), request).await
}
pub async fn authorize_remote_start(
&self,
request: &AuthorizeRemoteStartRequest,
) -> Result<Acknowledgement> {
self.transport.post(Operation::AuthorizeRemoteStart, &self.path_id(), request).await
}
pub async fn authorize_remote_stop(
&self,
request: &AuthorizeRemoteStopRequest,
) -> Result<Acknowledgement> {
self.transport.post(Operation::AuthorizeRemoteStop, &self.path_id(), request).await
}
pub async fn get_charge_detail_records(
&self,
request: &GetChargeDetailRecordsRequest,
query: PageQuery,
) -> Result<ChargeDetailRecordsResponse> {
self.transport
.post_raw(Operation::GetChargeDetailRecords, &self.cdr_url(request, query)?, request)
.await
}
pub async fn get_charge_detail_records_raw(
&self,
request: &GetChargeDetailRecordsRequest,
query: PageQuery,
) -> Result<Page<Box<RawValue>>> {
self.transport
.post_raw(Operation::GetChargeDetailRecords, &self.cdr_url(request, query)?, request)
.await
}
fn cdr_url(&self, request: &GetChargeDetailRecordsRequest, query: PageQuery) -> Result<String> {
if self.transport.config().validate_requests {
request.validate()?;
}
let base = Operation::GetChargeDetailRecords
.url(self.transport.config().environment.base_url(), &self.path_id())?;
Ok(query.append_to(&base))
}
pub fn crawl_charge_detail_records(
&self,
request: GetChargeDetailRecordsRequest,
start: PageQuery,
) -> impl Stream<Item = core::result::Result<ChargeDetailRecord, CrawlError>> + '_ {
futures_util::stream::unfold(Some(start), move |state| {
let request = request.clone();
async move {
let query = state?;
match self.get_charge_detail_records_raw(&request, query).await {
Err(source) => Some((vec![Err(CrawlError::Page { page: query.page, source })], None)),
Ok(page) => Some(decode_page(page, query)),
}
}
})
.flat_map(futures_util::stream::iter)
}
pub async fn push_authentication_data(
&self,
request: &PushAuthenticationDataRequest,
) -> Result<Acknowledgement> {
self.transport.post(Operation::PushAuthenticationData, &self.path_id(), request).await
}
pub async fn pull_pricing_product_data(
&self,
request: &PullPricingProductDataRequest,
) -> Result<PricingProductDataResponse> {
self.transport.post(Operation::PullPricingProductData, &self.path_id(), request).await
}
pub async fn pull_evse_pricing(&self, request: &PullEvsePricingRequest) -> Result<EvsePricingResponse> {
self.transport.post(Operation::PullEvsePricing, &self.path_id(), request).await
}
}
#[cfg(all(test, feature = "testkit"))]
mod tests {
use super::*;
#[test]
fn a_client_without_a_provider_id_says_why_it_cannot_be_built() {
let err = EmpClient::builder().build().unwrap_err();
assert!(err.to_string().contains("ProviderID"), "{err}");
}
#[test]
fn a_client_builds_and_keeps_its_identifier_verbatim() {
let client = EmpClient::builder().provider_id("DE-DCB".parse().unwrap()).build().unwrap();
assert_eq!(client.provider_id().as_str(), "DE-DCB");
}
use crate::testkit::samples;
fn raw_page(number: u32, total_pages: u32, last: bool, records: &[&str]) -> Page<Box<RawValue>> {
let content: Vec<Box<RawValue>> =
records.iter().map(|r| RawValue::from_string((*r).to_owned()).unwrap()).collect();
Page {
number_of_elements: u32::try_from(content.len()).unwrap(),
content,
number,
size: 2,
total_elements: u64::from(total_pages) * 2,
total_pages,
first: number == 0,
last,
empty: None,
pageable: None,
status_code: None,
extensions: crate::types::Extensions::new(),
}
}
#[test]
fn one_malformed_record_costs_one_record_and_not_the_page() {
let good = serde_json::to_string(&samples::pull_evse_data_record("DE*ABC*E1")).unwrap();
let page = raw_page(0, 1, true, &[&good, r#"{"EvseID":"DE*ABC*E2"}"#, &good]);
let (items, next) = decode_page::<PullEvseDataRecord>(page, PageQuery::at(0, 2));
assert!(next.is_none());
assert_eq!(items.len(), 3);
assert!(items[0].is_ok());
assert!(items[2].is_ok(), "the record after the bad one still arrives");
let Err(CrawlError::Record { page, index, .. }) = &items[1] else {
panic!("expected a per-record failure, got {:?}", items[1]);
};
assert_eq!((*page, *index), (0, 1));
}
#[test]
fn a_last_flag_that_would_truncate_a_crawl_does_not() {
let good = serde_json::to_string(&samples::pull_evse_data_record("DE*ABC*E1")).unwrap();
let (items, next) =
decode_page::<PullEvseDataRecord>(raw_page(0, 3, true, &[&good]), PageQuery::at(0, 2));
assert_eq!(next, Some(PageQuery::at(1, 2)), "the crawl goes on by totalPages");
assert!(matches!(items[0], Err(CrawlError::PageInconsistent { page: 0, .. })));
assert!(items[1].is_ok(), "and the page's records still arrive");
}
#[test]
fn a_last_flag_that_would_never_end_is_bounded_by_total_pages() {
let good = serde_json::to_string(&samples::pull_evse_data_record("DE*ABC*E1")).unwrap();
let (items, next) =
decode_page::<PullEvseDataRecord>(raw_page(2, 3, false, &[&good]), PageQuery::at(2, 2));
assert_eq!(next, None, "totalPages ends the crawl");
assert!(matches!(items[0], Err(CrawlError::PageInconsistent { page: 2, .. })));
assert!(items[1].is_ok());
}
#[test]
fn an_empty_page_that_claims_more_ends_the_crawl_rather_than_looping() {
let (items, next) =
decode_page::<PullEvseDataRecord>(raw_page(0, 9, false, &[]), PageQuery::at(0, 2));
assert_eq!(next, None);
assert!(matches!(items[0], Err(CrawlError::PageInconsistent { .. })));
}
#[test]
fn an_ordinary_page_asks_for_the_next_one_at_the_same_size() {
let good = serde_json::to_string(&samples::pull_evse_data_record("DE*ABC*E1")).unwrap();
let (items, next) =
decode_page::<PullEvseDataRecord>(raw_page(1, 3, false, &[&good]), PageQuery::at(1, 500));
assert_eq!(next, Some(PageQuery::at(2, 500)));
assert_eq!(items.len(), 1);
assert!(items[0].is_ok());
}
}