use std::collections::BTreeMap;
use std::sync::Arc;
use std::time::Duration;
use http::Uri;
use tokio::net::TcpStream;
use tokio::sync::{broadcast, mpsc, watch};
use crate::decode::DecodeOptions;
use crate::engine::{
Backoff, BootState, CallFailure, Engine, EngineConfig, Jitter, MemStore, MessageStore, Role,
};
use crate::types::Identity;
use crate::version::{Subprotocol, Version};
use super::TransportError;
use super::connection::{Driver, Ended, Event, Handle, Handler, Keepalive, SessionState, Shared};
use super::network_profile::{NetworkProfile, NetworkProfiles, ProfileCycler};
use super::security::{BasicAuthPassword, SecurityProfile, basic_auth_header};
use super::stream::MaybeTls;
use super::ws::handshake::{ClientRequest, client_handshake, percent_encode};
use super::ws::{Config as WsConfig, Role as WsRole, WebSocket, WsCodec};
pub struct StationBuilder<S: MessageStore = MemStore> {
identity: Option<Identity>,
url: Option<String>,
versions: Subprotocol,
profile: SecurityProfile,
password: Option<BasicAuthPassword>,
#[cfg(feature = "rustls")]
tls: Option<super::tls::ClientTls>,
keepalive: Keepalive,
backoff: Backoff,
reconnect: bool,
decode: DecodeOptions,
engine: Option<EngineConfig>,
handler: Option<Arc<dyn Handler>>,
store: S,
store_poll: Option<Duration>,
ws_config: WsConfig,
#[cfg(feature = "compression")]
compression: bool,
profiles: Option<NetworkProfiles>,
}
impl Default for StationBuilder<MemStore> {
fn default() -> Self {
Self {
identity: None,
url: None,
versions: Subprotocol::default(),
profile: SecurityProfile::BasicAuth,
password: None,
#[cfg(feature = "rustls")]
tls: None,
keepalive: Keepalive::default(),
backoff: Backoff::default(),
reconnect: true,
decode: DecodeOptions::strict(),
engine: None,
handler: None,
store: MemStore::new(),
store_poll: None,
ws_config: WsConfig::default(),
#[cfg(feature = "compression")]
compression: true,
profiles: None,
}
}
}
impl<S: MessageStore + Send + 'static> StationBuilder<S> {
pub fn identity(mut self, identity: &str) -> Result<Self, TransportError> {
self.identity = Some(
Identity::new(identity)
.map_err(|error| TransportError::Configuration(error.to_string()))?,
);
Ok(self)
}
#[must_use]
pub fn url(mut self, url: impl Into<String>) -> Self {
self.url = Some(url.into());
self
}
#[must_use]
pub fn versions(mut self, versions: impl IntoIterator<Item = Version>) -> Self {
self.versions = Subprotocol::new(versions);
self
}
#[must_use]
pub fn security_profile(mut self, profile: SecurityProfile) -> Self {
self.profile = profile;
self
}
#[must_use]
pub fn password(mut self, password: BasicAuthPassword) -> Self {
self.password = Some(password);
self
}
#[cfg(feature = "rustls")]
#[must_use]
pub fn tls(mut self, tls: super::tls::ClientTls) -> Self {
self.tls = Some(tls);
self
}
#[must_use]
pub fn ping_interval(mut self, interval: Option<Duration>) -> Self {
self.keepalive.interval = interval;
self
}
#[must_use]
pub fn keepalive(mut self, keepalive: Keepalive) -> Self {
self.keepalive = keepalive;
self
}
#[must_use]
pub fn backoff(mut self, backoff: Backoff) -> Self {
self.backoff = backoff;
self
}
#[must_use]
pub fn reconnect(mut self, reconnect: bool) -> Self {
self.reconnect = reconnect;
self
}
#[must_use]
pub fn decode_options(mut self, options: DecodeOptions) -> Self {
self.ws_config.max_message_size = options.max_payload_size;
self.ws_config.max_frame_size = options.max_payload_size;
self.decode = options;
self
}
#[cfg(feature = "compression")]
#[must_use]
pub fn compression(mut self, enabled: bool) -> Self {
self.compression = enabled;
self
}
#[must_use]
pub fn engine_config(mut self, config: EngineConfig) -> Self {
self.engine = Some(config);
self
}
#[must_use]
pub fn handler(mut self, handler: impl Handler) -> Self {
self.handler = Some(Arc::new(handler));
self
}
#[must_use]
pub fn network_profiles(mut self, profiles: NetworkProfiles) -> Self {
self.profiles = Some(profiles);
self
}
pub fn store<T: MessageStore + Send + 'static>(self, store: T) -> StationBuilder<T> {
StationBuilder {
identity: self.identity,
url: self.url,
versions: self.versions,
profile: self.profile,
password: self.password,
#[cfg(feature = "rustls")]
tls: self.tls,
keepalive: self.keepalive,
backoff: self.backoff,
reconnect: self.reconnect,
decode: self.decode,
engine: self.engine,
handler: self.handler,
store,
store_poll: self.store_poll,
ws_config: self.ws_config,
#[cfg(feature = "compression")]
compression: self.compression,
profiles: self.profiles,
}
}
#[must_use]
pub fn store_poll(mut self, interval: Duration) -> Self {
self.store_poll = Some(interval);
self
}
pub fn build(self) -> Result<Station<S>, TransportError> {
let identity = self
.identity
.ok_or_else(|| TransportError::Configuration("identity is required".into()))?;
let profiles = if let Some(mut profiles) = self.profiles {
if let Some(password) = &self.password {
profiles.default_password(password);
}
profiles
} else {
{
let url = self.url.ok_or_else(|| {
TransportError::Configuration(
"either `url` or `network_profiles` is required".into(),
)
})?;
let mut profile = NetworkProfile::new(0, url).security_profile(self.profile);
if let Some(password) = self.password {
profile = profile.password(password);
}
#[cfg(feature = "rustls")]
if let Some(tls) = self.tls {
profile = profile.tls(tls);
}
NetworkProfiles::new([profile])
}
};
let preferred = *self.versions.offered().first().ok_or_else(|| {
TransportError::Configuration("at least one version must be offered".into())
})?;
let mut endpoints = Vec::with_capacity(profiles.configured_slots().len());
for slot in profiles.configured_slots() {
let profile = profiles.get(slot).expect("configured");
endpoints.push(Endpoint::for_profile(profile, &identity, &self.versions)?);
}
let mut engine_config = self
.engine
.unwrap_or_else(|| EngineConfig::new(Role::ChargingStation, preferred));
engine_config.role = Role::ChargingStation;
engine_config.version = preferred;
engine_config.backoff = self.backoff;
Ok(Station {
connector: Connector {
identity,
versions: self.versions,
profiles,
endpoints: endpoints.into_iter().map(|e| (e.slot, e)).collect(),
ws_config: self.ws_config,
#[cfg(feature = "compression")]
compression: self.compression,
},
keepalive: self.keepalive,
backoff: self.backoff,
reconnect: self.reconnect,
decode: self.decode,
engine_config,
handler: self
.handler
.unwrap_or_else(|| Arc::new(super::connection::NotImplemented)),
store: self.store,
store_poll: self.store_poll,
})
}
}
struct Connector {
identity: Identity,
versions: Subprotocol,
profiles: NetworkProfiles,
endpoints: BTreeMap<i32, Endpoint>,
ws_config: WsConfig,
#[cfg(feature = "compression")]
compression: bool,
}
pub struct Station<S: MessageStore = MemStore> {
connector: Connector,
keepalive: Keepalive,
backoff: Backoff,
reconnect: bool,
decode: DecodeOptions,
engine_config: EngineConfig,
handler: Arc<dyn Handler>,
store: S,
store_poll: Option<Duration>,
}
impl Station<MemStore> {
#[must_use]
pub fn builder() -> StationBuilder<MemStore> {
StationBuilder::default()
}
}
impl<S: MessageStore + Send + 'static> Station<S> {
pub async fn run(self) -> Result<(), TransportError> {
let (handle, task) = self.into_parts()?;
drop(handle);
task.await
}
pub fn spawn(self) -> Result<Handle, TransportError> {
let (handle, task) = self.into_parts()?;
tokio::spawn(async move {
if let Err(error) = task.await {
#[cfg(feature = "tracing")]
tracing::error!(%error, "charging station stopped");
let _ = error;
}
});
Ok(handle)
}
fn into_parts(
self,
) -> Result<
(
Handle,
impl std::future::Future<Output = Result<(), TransportError>>,
),
TransportError,
> {
let (commands_tx, mut commands_rx) = mpsc::channel(64);
let (events_tx, _) = broadcast::channel(256);
let (state_tx, state_rx) = watch::channel(SessionState {
connected: false,
version: self.engine_config.version,
boot: BootState::Idle,
queued: 0,
});
let shared = Arc::new(Shared {
session: super::connection::SessionContext::empty(),
identity: self.connector.identity.clone(),
remote: None,
decode: self.decode.clone(),
commands: commands_tx,
events: events_tx,
state: state_rx,
});
let handle = Handle::new(shared.clone());
let engine = Engine::with_store(self.engine_config, self.store)?;
let mut driver = Driver::new(engine, shared.clone(), self.handler, state_tx);
driver.store_poll = self.store_poll;
let connector = self.connector;
let keepalive = self.keepalive;
let backoff = self.backoff;
let default_call_timeout = driver.engine.config().call_timeout;
let reconnect = self.reconnect;
let task = async move {
let mut attempt = 0u32;
let mut cycler = ProfileCycler::new(&connector.profiles);
let mut announced = None;
let mut last_connected: Option<i32> = None;
loop {
let (profile, _) = connector.profile_at(cycler.index());
let slot = profile.slot();
if announced != Some(slot) {
announced = Some(slot);
let _ = shared.events.send(Event::NetworkProfileSelected {
configuration_slot: slot,
url: profile.url().to_owned(),
});
}
let message_timeout = profile.message_timeout;
match connector.connect(cycler.index()).await {
Ok((socket, version)) => {
attempt = 0;
cycler.succeeded();
if last_connected.is_some_and(|previous| previous != slot) {
let now = driver.now();
driver.engine.require_boot(now);
}
last_connected = Some(slot);
driver
.engine
.set_call_timeout(message_timeout.unwrap_or(default_call_timeout));
let ended = driver
.run(socket, &mut commands_rx, version, keepalive)
.await;
if matches!(ended, Ended::Closed(_)) || !reconnect {
driver.abandon(&CallFailure::Disconnected);
return Ok(());
}
#[cfg(feature = "tracing")]
if let Ended::Disconnected(reason) = &ended {
tracing::info!(%reason, slot, "the session ended; reconnecting");
}
}
Err(error) => {
if !reconnect {
return Err(error);
}
#[cfg(feature = "tracing")]
tracing::warn!(%error, attempt, slot, "connection to the CSMS failed");
let _ = &error;
cycler.failed();
}
}
if !reconnect {
return Ok(());
}
let delay = backoff.delay(attempt, jitter());
let _ = shared.events.send(Event::Reconnecting { attempt, delay });
attempt = attempt.saturating_add(1);
tokio::time::sleep(delay).await;
}
};
Ok((handle, task))
}
}
impl Connector {
fn profile_at(&self, index: usize) -> (&NetworkProfile, &Endpoint) {
let profile = self.profiles.at(index);
let endpoint = self
.endpoints
.get(&profile.slot)
.expect("validated at build time");
(profile, endpoint)
}
async fn connect(
&self,
index: usize,
) -> Result<(WebSocket<MaybeTls>, Version), TransportError> {
let (profile, endpoint) = self.profile_at(index);
let versions = profile.versions.as_ref().unwrap_or(&self.versions);
let tcp = TcpStream::connect((endpoint.host.as_str(), endpoint.port)).await?;
tcp.set_nodelay(true)?;
let mut stream = if endpoint.secure {
#[cfg(feature = "rustls")]
{
let tls = profile.tls.as_ref().expect("checked by the builder");
let name = super::tls::ClientTls::server_name(&endpoint.host)
.map_err(|error| TransportError::Configuration(error.to_string()))?;
MaybeTls::ClientTls(Box::new(tls.connector().connect(name, tcp).await?))
}
#[cfg(not(feature = "rustls"))]
{
return Err(TransportError::Configuration(
"TLS needs the `rustls` feature".into(),
));
}
} else {
MaybeTls::Plain(tcp)
};
let authorization = if profile.security.uses_basic_auth() {
let password = profile.password.as_ref().expect("checked by the builder");
Some(basic_auth_header(&endpoint.identity, password))
} else {
None
};
#[allow(unused_mut)]
let mut extensions: Option<String> = None;
#[cfg(feature = "compression")]
if self.compression {
extensions = Some(super::ws::deflate::DeflateParams::default().client_offer());
}
let handshake = client_handshake(
&mut stream,
&ClientRequest {
host: &endpoint.authority,
path: &endpoint.path,
subprotocols: &versions.header_value(),
authorization: authorization.as_deref(),
extensions: extensions.as_deref(),
},
)
.await?;
let version = versions.accept(handshake.subprotocol.as_deref())?;
#[allow(unused_mut)]
let mut codec = WsCodec::new(WsRole::Client, self.ws_config);
#[cfg(feature = "compression")]
if extensions.is_some() {
match super::ws::deflate::accept_response(handshake.extensions.as_deref()) {
Ok(Some(params)) => codec = codec.with_deflate(params),
Ok(None) => {}
Err(error) => {
return Err(TransportError::Configuration(format!(
"permessage-deflate negotiation failed: {error}"
)));
}
}
}
Ok((super::ws::attach(stream, codec, &handshake.rest), version))
}
}
#[derive(Clone, Debug)]
struct Endpoint {
slot: i32,
host: String,
port: u16,
secure: bool,
authority: String,
path: String,
url: String,
identity: Identity,
}
impl Endpoint {
fn for_profile(
profile: &NetworkProfile,
identity: &Identity,
default_versions: &Subprotocol,
) -> Result<Self, TransportError> {
let identity = profile.identity.as_ref().unwrap_or(identity);
let endpoint = Self::parse(profile.slot, &profile.url, identity)?;
let slot = profile.slot;
let security = profile.security;
if endpoint.secure != security.is_transport_encrypted() {
return Err(TransportError::Configuration(format!(
"configuration slot {slot}: {security} and the URL {} disagree about TLS",
endpoint.url
)));
}
let offered = profile
.versions
.as_ref()
.unwrap_or(default_versions)
.offered();
if security == SecurityProfile::Unsecured
&& offered.iter().any(|v| *v != crate::version::Version::V1_6)
{
return Err(TransportError::Configuration(format!(
"configuration slot {slot}: {security} is OCPP 1.6 only — 2.x requires HTTP \
Basic at least (A00.FR.202); offer only 1.6, or use profile 1"
)));
}
if security.uses_basic_auth() && profile.password.is_none() {
return Err(TransportError::Configuration(format!(
"configuration slot {slot}: {security} needs a password"
)));
}
#[cfg(feature = "rustls")]
if security.is_transport_encrypted() && profile.tls.is_none() {
return Err(TransportError::Configuration(format!(
"configuration slot {slot}: {security} needs a TLS configuration"
)));
}
#[cfg(not(feature = "rustls"))]
if security.is_transport_encrypted() {
return Err(TransportError::Configuration(
"TLS needs the `rustls` feature".into(),
));
}
if profile
.versions
.as_ref()
.unwrap_or(default_versions)
.offered()
.is_empty()
{
return Err(TransportError::Configuration(format!(
"configuration slot {slot}: at least one version must be offered"
)));
}
Ok(endpoint)
}
fn parse(slot: i32, base: &str, identity: &Identity) -> Result<Self, TransportError> {
let uri: Uri = base
.parse()
.map_err(|_| TransportError::Url(base.to_owned()))?;
let scheme = uri.scheme_str().unwrap_or("ws");
let secure = match scheme {
"ws" | "http" => false,
"wss" | "https" => true,
_ => return Err(TransportError::Url(base.to_owned())),
};
let host = uri
.host()
.ok_or_else(|| TransportError::Url(base.to_owned()))?
.to_owned();
let port = uri.port_u16().unwrap_or(if secure { 443 } else { 80 });
let path = format!(
"{}/{}",
uri.path().trim_end_matches('/'),
percent_encode(identity.as_str())
);
let authority = if uri.port().is_some() {
format!("{host}:{port}")
} else {
host.clone()
};
let url = format!("{}://{authority}{path}", if secure { "wss" } else { "ws" });
Ok(Self {
slot,
host,
port,
secure,
authority,
path,
url,
identity: identity.clone(),
})
}
}
fn jitter() -> Jitter {
let mut bytes = [0u8; 4];
if getrandom::fill(&mut bytes).is_err() {
return Jitter::from_ratio(1, 2);
}
Jitter::from_random_u32(u32::from_le_bytes(bytes))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_identity_becomes_the_last_path_segment() {
let identity = Identity::new("CS-0001").unwrap();
let endpoint = Endpoint::parse(0, "wss://csms.example.com/ocpp", &identity).unwrap();
assert_eq!(endpoint.url, "wss://csms.example.com/ocpp/CS-0001");
assert_eq!(endpoint.port, 443);
assert!(endpoint.secure);
let endpoint = Endpoint::parse(0, "ws://localhost:9000/", &identity).unwrap();
assert_eq!(endpoint.url, "ws://localhost:9000/CS-0001");
assert_eq!(endpoint.port, 9000);
assert!(!endpoint.secure);
}
#[test]
fn identities_that_need_escaping_still_produce_one_segment() {
let identity = Identity::new("station/one").unwrap();
let endpoint = Endpoint::parse(0, "ws://host/ocpp", &identity).unwrap();
assert_eq!(endpoint.url, "ws://host/ocpp/station%2Fone");
}
#[test]
fn the_builder_refuses_contradictory_security_settings() {
let error = Station::builder()
.identity("CS-0001")
.unwrap()
.url("ws://host/ocpp")
.security_profile(SecurityProfile::TlsBasicAuth)
.build()
.err()
.expect("a TLS profile on a ws:// URL is a contradiction");
assert!(matches!(error, TransportError::Configuration(_)), "{error}");
let error = Station::builder()
.identity("CS-0001")
.unwrap()
.url("ws://host/ocpp")
.security_profile(SecurityProfile::BasicAuth)
.build()
.err()
.expect("profile 1 needs a password");
assert!(error.to_string().contains("needs a password"), "{error}");
}
#[test]
fn a_profile_can_connect_under_its_own_identity() {
use super::super::network_profile::{NetworkProfile, NetworkProfiles};
let password = || BasicAuthPassword::utf8("0123456789abcdef").unwrap();
let station = Station::builder()
.identity("CS-0001")
.unwrap()
.network_profiles(NetworkProfiles::new([
NetworkProfile::new(0, "ws://primary/ocpp").password(password()),
NetworkProfile::new(1, "ws://other-csms/ocpp")
.identity(Identity::new("OTHER-7").unwrap())
.password(password()),
]))
.build()
.unwrap();
let endpoints = &station.connector.endpoints;
assert_eq!(endpoints[&0].path, "/ocpp/CS-0001");
assert_eq!(endpoints[&1].path, "/ocpp/OTHER-7");
assert_eq!(endpoints[&1].identity.as_str(), "OTHER-7");
}
#[test]
fn a_profile_without_a_password_uses_the_stations() {
use super::super::network_profile::{NetworkProfile, NetworkProfiles};
let own = BasicAuthPassword::utf8("ffffffffffffffff").unwrap();
let station = Station::builder()
.identity("CS-0001")
.unwrap()
.password(BasicAuthPassword::utf8("0123456789abcdef").unwrap())
.network_profiles(NetworkProfiles::new([
NetworkProfile::new(0, "ws://fallback/ocpp")
.security_profile(SecurityProfile::BasicAuth),
NetworkProfile::new(1, "ws://primary/ocpp")
.security_profile(SecurityProfile::BasicAuth)
.password(own.clone()),
]))
.build()
.expect("slot 0 falls back to the station password");
let profiles = &station.connector.profiles;
assert!(profiles.get(0).unwrap().password.is_some());
assert_eq!(
profiles
.get(1)
.unwrap()
.password
.as_ref()
.map(BasicAuthPassword::as_bytes),
Some(own.as_bytes())
);
}
#[test]
fn every_configuration_slot_is_validated_at_build_time() {
use super::super::network_profile::{NetworkProfile, NetworkProfiles};
let error = Station::builder()
.identity("CS-0001")
.unwrap()
.network_profiles(
NetworkProfiles::new([
NetworkProfile::new(0, "ws://fallback/ocpp")
.security_profile(SecurityProfile::BasicAuth),
NetworkProfile::new(1, "ws://primary/ocpp")
.security_profile(SecurityProfile::BasicAuth)
.password(BasicAuthPassword::utf8("0123456789abcdef").unwrap()),
])
.priority([1, 0])
.unwrap(),
)
.build()
.err()
.expect("slot 0 has no password");
assert!(
error.to_string().contains("configuration slot 0"),
"{error}"
);
}
}