use alloc::string::{String, ToString};
use core::future::Future;
use futures_util::{SinkExt, StreamExt};
use tokio_tungstenite::tungstenite::client::IntoClientRequest;
use tokio_tungstenite::tungstenite::protocol::Message as WsMessage;
use crate::session::Session;
use crate::types::{Duration, Timestamp};
pub const PING_INTERVAL: Duration = Duration::from_secs(30);
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
#[error("transport error: {0}")]
Transport(String),
#[error("the peer closed the connection")]
Closed,
#[error("unexpected frame: {0}")]
UnexpectedFrame(String),
}
pub trait TextTransport {
fn send_text(&mut self, text: String) -> impl Future<Output = Result<(), Error>> + Send;
fn recv_text(&mut self) -> impl Future<Output = Result<Option<String>, Error>> + Send;
fn ping(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
fn close(&mut self) -> impl Future<Output = ()> + Send;
}
pub struct WebSocket<S> {
stream: tokio_tungstenite::WebSocketStream<S>,
}
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct WebSocketOptions<'a> {
pub bearer: Option<&'a str>,
pub max_message_bytes: Option<usize>,
#[cfg(feature = "connect-client")]
#[cfg_attr(docsrs, doc(cfg(feature = "connect-client")))]
pub policy: Option<&'a crate::connect::tls::TlsPolicy>,
}
impl<'a> WebSocketOptions<'a> {
#[must_use]
pub const fn bearer(mut self, bearer: &'a str) -> Self {
self.bearer = Some(bearer);
self
}
#[must_use]
pub const fn max_message_bytes(mut self, bytes: usize) -> Self {
self.max_message_bytes = Some(bytes);
self
}
#[cfg(feature = "connect-client")]
#[cfg_attr(docsrs, doc(cfg(feature = "connect-client")))]
#[must_use]
pub const fn policy(mut self, policy: &'a crate::connect::tls::TlsPolicy) -> Self {
self.policy = Some(policy);
self
}
fn limit(&self) -> usize {
self.max_message_bytes
.unwrap_or(crate::codec::DecodeOptions::DEFAULT_MAX_BYTES)
}
}
impl WebSocket<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>> {
pub async fn connect(url: &str, bearer: Option<&str>) -> Result<Self, Error> {
Self::open(
url,
&WebSocketOptions {
bearer,
..WebSocketOptions::default()
},
)
.await
}
pub async fn open(url: &str, options: &WebSocketOptions<'_>) -> Result<Self, Error> {
#[cfg(feature = "connect-client")]
let connector = match options.policy {
None => None,
Some(policy) => {
if !policy.authenticates() {
return Err(Error::Transport(
"a session must not run under the pairing-only TLS policy".to_string(),
));
}
let client = crate::connect::tls::TlsClient::new(policy)
.map_err(|e| Error::Transport(e.to_string()))?;
Some(tokio_tungstenite::Connector::Rustls(client.config()))
}
};
#[cfg(not(feature = "connect-client"))]
let connector = None;
Self::dial(url, options.bearer, connector, options.limit()).await
}
#[cfg(feature = "connect-client")]
#[cfg_attr(docsrs, doc(cfg(feature = "connect-client")))]
pub async fn connect_with_policy(
url: &str,
bearer: Option<&str>,
policy: &crate::connect::tls::TlsPolicy,
) -> Result<Self, Error> {
Self::open(
url,
&WebSocketOptions {
bearer,
policy: Some(policy),
..WebSocketOptions::default()
},
)
.await
}
async fn dial(
url: &str,
bearer: Option<&str>,
connector: Option<tokio_tungstenite::Connector>,
max_message_bytes: usize,
) -> Result<Self, Error> {
let mut request = url
.into_client_request()
.map_err(|e| Error::Transport(e.to_string()))?;
if let Some(token) = bearer {
let value = alloc::format!("Bearer {token}")
.parse()
.map_err(|_| Error::Transport("invalid bearer token".to_string()))?;
request.headers_mut().insert("Authorization", value);
}
let config = tokio_tungstenite::tungstenite::protocol::WebSocketConfig::default()
.max_message_size(Some(max_message_bytes))
.max_frame_size(Some(max_message_bytes));
let (stream, _) = tokio_tungstenite::connect_async_tls_with_config(
request,
Some(config),
false,
connector,
)
.await
.map_err(|e| Error::Transport(e.to_string()))?;
Ok(Self { stream })
}
}
impl<S> WebSocket<S> {
pub fn from_stream(stream: tokio_tungstenite::WebSocketStream<S>) -> Self {
Self { stream }
}
}
impl<S> TextTransport for WebSocket<S>
where
S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send,
{
async fn send_text(&mut self, text: String) -> Result<(), Error> {
self.stream
.send(WsMessage::text(text))
.await
.map_err(|e| Error::Transport(e.to_string()))
}
#[allow(clippy::match_same_arms)] async fn recv_text(&mut self) -> Result<Option<String>, Error> {
loop {
match self.stream.next().await {
None => return Ok(None),
Some(Err(e)) => return Err(Error::Transport(e.to_string())),
Some(Ok(WsMessage::Text(text))) => return Ok(Some(text.to_string())),
Some(Ok(WsMessage::Close(_))) => return Ok(None),
Some(Ok(WsMessage::Ping(_) | WsMessage::Pong(_) | WsMessage::Frame(_))) => {}
Some(Ok(WsMessage::Binary(_))) => {
return Err(Error::UnexpectedFrame("binary".to_string()));
}
}
}
}
async fn ping(&mut self) -> Result<(), Error> {
self.stream
.send(WsMessage::Ping(tokio_tungstenite::tungstenite::Bytes::new()))
.await
.map_err(|e| Error::Transport(e.to_string()))
}
async fn close(&mut self) {
let _ = self.stream.close(None).await;
}
}
pub struct Driver<T> {
transport: T,
ping_interval: Duration,
now: fn() -> Timestamp,
last_ping: Option<Timestamp>,
}
impl<T: TextTransport> Driver<T> {
pub fn new(transport: T) -> Self {
Self {
transport,
ping_interval: PING_INTERVAL,
now: Timestamp::now,
last_ping: None,
}
}
#[must_use]
pub fn with_clock(mut self, now: fn() -> Timestamp) -> Self {
self.now = now;
self
}
#[must_use]
pub fn with_ping_interval(mut self, interval: Duration) -> Self {
self.ping_interval = interval;
self
}
pub fn transport_mut(&mut self) -> &mut T {
&mut self.transport
}
pub async fn step<S: Session>(&mut self, session: &mut S) -> Result<(), Error> {
self.flush(session).await?;
if session.state().is_closed() {
self.transport.close().await;
return Ok(());
}
let deadline = session.poll_timeout();
match self.wait(deadline).await? {
Wake::Text(text) => {
let inbound = session.handle_text(&text, (self.now)());
crate::trace::event!(
debug,
kind = ?inbound.kind,
status = ?inbound.status,
violations = inbound.report.violations().len(),
"received"
);
if inbound.report.has_errors() {
crate::trace::event!(
warn,
kind = ?inbound.kind,
diagnostic = ?inbound.report.diagnostic_label(),
"refused an inbound message"
);
}
}
Wake::Timeout => {
crate::trace::event!(trace, "deadline reached");
session.handle_timeout((self.now)());
}
Wake::Ping => {
self.last_ping = Some((self.now)());
self.transport.ping().await?;
}
Wake::Closed => {
crate::trace::event!(info, "the transport closed");
session.transport_closed((self.now)());
}
}
self.flush(session).await
}
async fn flush<S: Session>(&mut self, session: &mut S) -> Result<(), Error> {
while let Some(out) = session.poll_transmit() {
crate::trace::event!(
debug,
kind = %out.kind.as_str(),
message_id = ?out.message_id,
bytes = out.text.len(),
"sending"
);
self.transport.send_text(out.text).await?;
}
Ok(())
}
pub async fn run<S, F>(&mut self, session: &mut S, mut on_event: F) -> Result<(), Error>
where
S: Session,
F: FnMut(S::Event, &mut S),
{
while !session.state().is_closed() {
self.step(session).await?;
while let Some(event) = session.poll_event() {
on_event(event, session);
}
}
self.flush(session).await?;
self.transport.close().await;
Ok(())
}
async fn wait(&mut self, deadline: Option<Timestamp>) -> Result<Wake, Error> {
let now = (self.now)();
let until_deadline = deadline.map_or(Duration::MAX, |at| at.saturating_duration_since(now));
let until_ping = match self.last_ping {
None => {
self.last_ping = Some(now);
self.ping_interval
}
Some(last) => self
.ping_interval
.checked_sub(now.saturating_duration_since(last))
.unwrap_or(Duration::ZERO),
};
let (sleep_for, wake) = if until_deadline <= until_ping {
(until_deadline, Wake::Timeout)
} else {
(until_ping, Wake::Ping)
};
tokio::select! {
frame = self.transport.recv_text() => match frame? {
Some(text) => Ok(Wake::Text(text)),
None => Ok(Wake::Closed),
},
() = tokio::time::sleep(core::time::Duration::from(sleep_for)) => Ok(wake),
}
}
}
enum Wake {
Text(String),
Timeout,
Ping,
Closed,
}
#[cfg(test)]
mod tests {
use super::*;
use crate::session::{RmConfig, RmSession};
use alloc::collections::VecDeque;
use alloc::vec::Vec;
struct Scripted {
inbound: VecDeque<String>,
outbound: Vec<String>,
pings: usize,
}
impl TextTransport for Scripted {
async fn send_text(&mut self, text: String) -> Result<(), Error> {
tokio::task::yield_now().await;
self.outbound.push(text);
Ok(())
}
async fn recv_text(&mut self) -> Result<Option<String>, Error> {
if let Some(text) = self.inbound.pop_front() {
return Ok(Some(text));
}
core::future::pending::<()>().await;
unreachable!()
}
async fn ping(&mut self) -> Result<(), Error> {
tokio::task::yield_now().await;
self.pings += 1;
Ok(())
}
async fn close(&mut self) {
tokio::task::yield_now().await;
}
}
fn clock() -> Timestamp {
"2024-01-01T12:00:00Z"
.parse()
.unwrap_or(Timestamp::UNIX_EPOCH)
}
#[tokio::test]
async fn a_step_flushes_the_outbox_and_feeds_back_what_arrives() {
let details = crate::testing::battery_details();
let mut rm = RmSession::new(RmConfig::default(), details);
rm.open(clock());
let transport = Scripted {
inbound: VecDeque::from([
r#"{"message_type":"Handshake","message_id":"c1","role":"CEM","supported_protocol_versions":["1.0.0"]}"#.to_string(),
]),
outbound: Vec::new(),
pings: 0,
};
let mut driver = Driver::new(transport).with_clock(clock);
driver.step(&mut rm).await.unwrap();
let written = &driver.transport_mut().outbound;
assert!(written[0].contains(r#""message_type":"Handshake""#));
assert!(written.iter().any(|m| m.contains("ReceptionStatus")));
}
struct Chatty {
gap: core::time::Duration,
pings: usize,
}
impl TextTransport for Chatty {
#[allow(clippy::unused_async_trait_impl)]
async fn send_text(&mut self, _text: String) -> Result<(), Error> {
Ok(())
}
async fn recv_text(&mut self) -> Result<Option<String>, Error> {
tokio::time::sleep(self.gap).await;
Ok(Some(
r#"{"message_type":"PowerMeasurement","message_id":"c1",
"measurement_timestamp":"2024-01-01T12:00:00Z",
"values":[{"commodity_quantity":"ELECTRIC.POWER.L1","value":1.0}]}"#
.to_string(),
))
}
#[allow(clippy::unused_async_trait_impl)]
async fn ping(&mut self) -> Result<(), Error> {
self.pings += 1;
Ok(())
}
#[allow(clippy::unused_async_trait_impl)]
async fn close(&mut self) {}
}
fn virtual_clock() -> Timestamp {
use std::sync::OnceLock;
static START: OnceLock<tokio::time::Instant> = OnceLock::new();
let start = *START.get_or_init(tokio::time::Instant::now);
let elapsed = tokio::time::Instant::now().saturating_duration_since(start);
Timestamp::from_unix(1_700_000_000, 0)
.checked_add(Duration::from_millis(
u64::try_from(elapsed.as_millis()).unwrap_or(u64::MAX),
))
.unwrap_or(Timestamp::UNIX_EPOCH)
}
#[tokio::test(start_paused = true)]
async fn a_busy_connection_still_gets_a_keep_alive() {
let details = crate::testing::battery_details();
let mut rm = RmSession::new(RmConfig::default(), details);
rm.open(virtual_clock());
let transport = Chatty {
gap: core::time::Duration::from_millis(100),
pings: 0,
};
let mut driver = Driver::new(transport)
.with_clock(virtual_clock)
.with_ping_interval(Duration::from_secs(1));
for _ in 0..34 {
driver.step(&mut rm).await.unwrap();
}
assert!(
driver.transport_mut().pings >= 2,
"expected the keep-alive to fire about once a second, got {}",
driver.transport_mut().pings
);
}
#[tokio::test(start_paused = true)]
async fn a_quiet_connection_gets_a_keep_alive() {
let details = crate::testing::battery_details();
let mut rm = RmSession::new(RmConfig::default(), details);
rm.open(clock());
let transport = Scripted {
inbound: VecDeque::new(),
outbound: Vec::new(),
pings: 0,
};
let mut driver = Driver::new(transport)
.with_clock(clock)
.with_ping_interval(Duration::from_secs(1));
driver.step(&mut rm).await.unwrap();
assert_eq!(driver.transport_mut().pings, 1);
}
}