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 recv(&mut self) -> impl Future<Output = Result<Option<Received>, Error>> + Send {
use futures_util::FutureExt as _;
self.recv_text()
.map(|frame| frame.map(|text| text.map(Received::Text)))
}
fn ping(&mut self) -> impl Future<Output = Result<(), Error>> + Send;
fn close(&mut self) -> impl Future<Output = ()> + Send;
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Received {
Text(String),
Alive,
}
pub const IDLE_LIMIT: Duration = Duration::from_secs(90);
pub struct WebSocket<S> {
stream: tokio_tungstenite::WebSocketStream<S>,
}
pub type Dialled = WebSocket<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct WebSocketOptions<'a> {
pub bearer: Option<&'a str>,
pub max_message_bytes: Option<usize>,
pub policy: Option<&'a crate::connect::tls::TlsPolicy>,
pub allow_insecure_bearer: bool,
}
impl<'a> WebSocketOptions<'a> {
#[must_use]
pub const fn allow_insecure_bearer(mut self) -> Self {
self.allow_insecure_bearer = true;
self
}
#[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
}
#[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 Dialled {
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> {
use crate::connect::tls::TlsPolicy;
if let Some(policy) = options.policy
&& !policy.authenticates()
{
return Err(Error::Transport(
"a session must not run under the pairing-only TLS policy".to_string(),
));
}
let web = TlsPolicy::Web;
let policy = options.policy.unwrap_or(&web);
Self::dial(
url,
options.bearer,
policy,
options.limit(),
options.allow_insecure_bearer,
)
.await
}
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>,
policy: &crate::connect::tls::TlsPolicy,
max_message_bytes: usize,
allow_insecure_bearer: bool,
) -> Result<Self, Error> {
let mut request = url
.into_client_request()
.map_err(|e| Error::Transport(e.to_string()))?;
let connector = if request
.uri()
.scheme_str()
.is_some_and(|s| s.eq_ignore_ascii_case("wss"))
{
let client = crate::connect::tls::TlsClient::new(policy)
.map_err(|e| Error::Transport(e.to_string()))?;
Some(tokio_tungstenite::Connector::Rustls(client.config()))
} else {
None
};
if bearer.is_some() && connector.is_none() && !allow_insecure_bearer {
return Err(Error::Transport(
"refusing to send a bearer token over plaintext ws:// (S2C §Encrypted connection)"
.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.recv().await? {
None => return Ok(None),
Some(Received::Text(text)) => return Ok(Some(text)),
Some(Received::Alive) => {}
}
}
}
async fn recv(&mut self) -> Result<Option<Received>, Error> {
loop {
match self.stream.next().await {
None | Some(Ok(WsMessage::Close(_))) => return Ok(None),
Some(Err(e)) => return Err(Error::Transport(e.to_string())),
Some(Ok(WsMessage::Text(text))) => {
return Ok(Some(Received::Text(text.to_string())));
}
Some(Ok(WsMessage::Ping(_) | WsMessage::Pong(_))) => {
return Ok(Some(Received::Alive));
}
Some(Ok(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>,
last_heard: Option<Timestamp>,
idle_limit: Option<Duration>,
#[cfg(feature = "tracing")]
span: tracing::Span,
#[cfg(feature = "tracing")]
recorded_state: Option<String>,
}
impl<T: TextTransport> Driver<T> {
pub fn new(transport: T) -> Self {
Self {
transport,
ping_interval: PING_INTERVAL,
now: Timestamp::now,
last_ping: None,
last_heard: None,
idle_limit: Some(IDLE_LIMIT),
#[cfg(feature = "tracing")]
span: tracing::info_span!(
"s2.session",
state = tracing::field::Empty,
version = tracing::field::Empty,
),
#[cfg(feature = "tracing")]
recorded_state: None,
}
}
#[cfg(feature = "tracing")]
#[must_use]
pub fn with_span(mut self, span: tracing::Span) -> Self {
self.span = span;
self
}
#[must_use]
pub fn with_clock(mut self, now: fn() -> Timestamp) -> Self {
self.now = now;
self
}
#[must_use]
pub fn with_idle_limit(mut self, limit: Option<Duration>) -> Self {
self.idle_limit = limit;
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> {
#[cfg(feature = "tracing")]
{
use tracing::Instrument as _;
let span = self.span.clone();
let result = self.step_inner(session).instrument(span).await;
self.record_state(session);
result
}
#[cfg(not(feature = "tracing"))]
self.step_inner(session).await
}
#[cfg(feature = "tracing")]
fn record_state<S: Session>(&mut self, session: &S) {
let state = alloc::format!("{:?}", session.state());
if self.recorded_state.as_deref() == Some(state.as_str()) {
return;
}
self.span.record("state", state.as_str());
if let Some(version) = session.negotiated_version() {
self.span.record("version", version.as_str());
}
self.span
.in_scope(|| tracing::info!(state = %state, "session state"));
self.recorded_state = Some(state);
}
async fn step_inner<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,
message_id = ?inbound.message_id,
kind = ?inbound.kind,
status = ?inbound.status,
violations = inbound.report.violations().len(),
"received"
);
if !inbound.accepted() {
crate::trace::event!(
warn,
message_id = ?inbound.message_id,
kind = ?inbound.kind,
status = ?inbound.status,
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::Alive => {}
Wake::Closed => {
crate::trace::event!(info, "the transport closed");
session.transport_closed((self.now)());
}
Wake::Idle => {
crate::trace::event!(warn, "nothing heard from the peer within the idle limit");
self.transport.close().await;
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 until_idle = match (self.idle_limit, self.last_heard) {
(None, _) => Duration::MAX,
(Some(limit), None) => {
self.last_heard = Some(now);
limit
}
(Some(limit), Some(heard)) => limit
.checked_sub(now.saturating_duration_since(heard))
.unwrap_or(Duration::ZERO),
};
let (sleep_for, wake) = [
(until_deadline, Wake::Timeout),
(until_ping, Wake::Ping),
(until_idle, Wake::Idle),
]
.into_iter()
.min_by_key(|(after, _)| *after)
.unwrap_or((until_deadline, Wake::Timeout));
tokio::select! {
frame = self.transport.recv() => {
let frame = frame?;
if frame.is_some() {
self.last_heard = Some((self.now)());
}
Ok(match frame {
Some(Received::Text(text)) => Wake::Text(text),
Some(Received::Alive) => Wake::Alive,
None => Wake::Closed,
})
},
() = tokio::time::sleep(core::time::Duration::from(sleep_for)) => Ok(wake),
}
}
}
enum Wake {
Text(String),
Timeout,
Ping,
Alive,
Closed,
Idle,
}
#[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")));
}
#[tokio::test(start_paused = true)]
async fn a_link_that_goes_silent_is_closed_rather_than_pinged_for_ever() {
let details = crate::testing::battery_details();
let mut rm = RmSession::new(RmConfig::default(), details);
rm.open(virtual_clock());
let transport = Scripted {
inbound: VecDeque::new(),
outbound: Vec::new(),
pings: 0,
};
let mut driver = Driver::new(transport)
.with_clock(virtual_clock)
.with_ping_interval(Duration::from_secs(1))
.with_idle_limit(Some(Duration::from_secs(3)));
for _ in 0..64 {
driver.step(&mut rm).await.unwrap();
if rm.state().is_closed() {
break;
}
}
assert!(
rm.state().is_closed(),
"silence past the limit must end the session"
);
assert!(driver.transport_mut().pings >= 2, "it was pinged first");
}
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);
}
}