mod registry;
#[cfg(all(
feature = "ws-web",
not(feature = "ws-native"),
not(target_arch = "wasm32")
))]
compile_error!(
"plexus-client: feature `ws-web` is the wasm32 browser backend. Off \
wasm32-unknown-unknown, enable `ws-native` instead (both features \
expose the same `WsTransport`)."
);
#[cfg(feature = "ws-native")]
#[path = "native.rs"]
mod backend;
#[cfg(all(feature = "ws-web", not(feature = "ws-native")))]
#[path = "web.rs"]
mod backend;
use crate::error::TransportError;
use crate::transport::{InputItem, InputItems, ItemStream, MethodRef, RawItemStream, Transport};
use futures_util::{stream, Stream, StreamExt};
use registry::{end_frame, input_frame, subscribe_frame, Delivered, InputSignal, Items, Registry, SubSlot};
use serde_json::Value;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
fn trace(direction: &str, frame: &str) {
use std::sync::OnceLock;
static ON: OnceLock<bool> = OnceLock::new();
if *ON.get_or_init(|| std::env::var("PLEXUS_WS_TRACE").is_ok()) {
eprintln!("ws {direction} {frame}");
}
}
#[derive(Debug, Clone)]
pub struct WsTransport {
conn: backend::Conn,
registry: Arc<Registry>,
_closer: Arc<Closer>,
}
#[derive(Debug)]
struct Closer {
conn: backend::Conn,
}
impl Drop for Closer {
fn drop(&mut self) {
self.conn.close();
}
}
impl WsTransport {
pub async fn connect(url: &str, hub_namespace: &str) -> Result<Self, TransportError> {
let registry = Arc::new(Registry::new(Arc::from(hub_namespace)));
let conn = backend::connect(url, registry.clone()).await?;
Ok(Self {
_closer: Arc::new(Closer { conn: conn.clone() }),
conn,
registry,
})
}
#[cfg(all(feature = "ws-web", not(feature = "ws-native")))]
pub async fn adopt(socket: web_sys::WebSocket, hub_namespace: &str) -> Result<Self, TransportError> {
let registry = Arc::new(Registry::new(Arc::from(hub_namespace)));
let conn = backend::adopt(socket, registry.clone()).await?;
Ok(Self {
_closer: Arc::new(Closer { conn: conn.clone() }),
conn,
registry,
})
}
#[cfg(feature = "ws-native")]
pub async fn connect_with_headers(
url: &str,
hub_namespace: &str,
headers: &[(String, String)],
) -> Result<Self, TransportError> {
let registry = Arc::new(Registry::new(Arc::from(hub_namespace)));
let conn = backend::connect_with_headers(url, headers, registry.clone()).await?;
Ok(Self {
_closer: Arc::new(Closer { conn: conn.clone() }),
conn,
registry,
})
}
pub fn hub_namespace(&self) -> &str {
self.registry.hub_namespace()
}
pub fn is_closed(&self) -> bool {
self.registry.is_closed()
}
fn subscribe(&self, method: MethodRef, params: Value, raw: bool) -> Result<Awaiting, TransportError> {
let request_id = self.registry.next_request_id();
let slot = SubSlot::new();
let reply = self.registry.register_pending(request_id, slot.clone(), raw)?;
let frame = subscribe_frame(
request_id,
self.registry.hub_namespace(),
&method.qualified(),
¶ms,
);
trace("→", &frame);
if let Err(e) = self.conn.send(frame) {
self.registry.forget_pending(request_id);
return Err(e);
}
Ok(Awaiting {
reply,
guard: SubGuard {
conn: self.conn.clone(),
registry: self.registry.clone(),
slot,
},
})
}
}
impl Transport for WsTransport {
fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_> {
Box::pin(self.items(method, params, false).map(|item| item.map(Delivered::into_item)))
}
fn call_raw(&self, method: MethodRef, params: Value) -> RawItemStream<'_> {
Box::pin(self.items(method, params, true).map(|item| item.map(Delivered::into_raw)))
}
fn call_with_input<'a>(&'a self, method: MethodRef, params: Value, input: InputItems<'a>) -> ItemStream<'a> {
Box::pin(self.items_with_input(method, params, input, false).map(|item| item.map(Delivered::into_item)))
}
fn call_raw_with_input<'a>(&'a self, method: MethodRef, params: Value, input: InputItems<'a>) -> RawItemStream<'a> {
Box::pin(self.items_with_input(method, params, input, true).map(|item| item.map(Delivered::into_raw)))
}
}
impl WsTransport {
fn items(&self, method: MethodRef, params: Value, raw: bool) -> impl Stream<Item = Result<Delivered, TransportError>> + '_ {
let start = match self.subscribe(method, params, raw) {
Ok(awaiting) => CallState::Awaiting(awaiting),
Err(e) => CallState::Failed(e),
};
stream::unfold(start, |state| async move {
match state {
CallState::Awaiting(awaiting) => match awaiting.established().await {
Err(e) => Some((Err(e), CallState::Ended)),
Ok(mut active) => active
.next_item()
.await
.map(|item| (item, CallState::Active(active))),
},
CallState::Active(mut active) => active
.next_item()
.await
.map(|item| (item, CallState::Active(active))),
CallState::Failed(e) => Some((Err(e), CallState::Ended)),
CallState::Ended => None,
}
})
}
fn items_with_input<'a>(&'a self, method: MethodRef, params: Value, input: InputItems<'a>, raw: bool) -> impl Stream<Item = Result<Delivered, TransportError>> + 'a {
let start = match self.subscribe(method, params, raw) {
Ok(awaiting) => {
let feed = Feed { input: Some(input), credit: 0, seq: 0, conn: self.conn.clone(), registry: self.registry.clone(), failed: false };
Feeding::Awaiting(awaiting, feed)
}
Err(e) => Feeding::Failed(e),
};
stream::unfold(start, |state| async move {
let (mut active, mut feed) = match state {
Feeding::Awaiting(awaiting, feed) => match awaiting.established().await {
Err(e) => return Some((Err(e), Feeding::Ended)),
Ok(active) => (active, feed),
},
Feeding::Active(active, feed) => (active, feed),
Feeding::Failed(e) => return Some((Err(e), Feeding::Ended)),
Feeding::Ended => return None,
};
let item = std::future::poll_fn(|cx| feed.poll_next(&mut active, cx)).await?;
let failed = feed.failed;
Some((item, if failed { Feeding::Ended } else { Feeding::Active(active, feed) }))
})
}
}
enum Feeding<'a> {
Awaiting(Awaiting, Feed<'a>),
Active(Active, Feed<'a>),
Failed(TransportError),
Ended,
}
const FRAME_ITEMS: usize = 256;
const FRAME_BYTES: usize = 1024 * 1024;
struct Feed<'a> {
input: Option<InputItems<'a>>,
credit: u64,
seq: u64,
conn: backend::Conn,
registry: Arc<Registry>,
failed: bool,
}
impl Feed<'_> {
fn poll_next(&mut self, active: &mut Active, cx: &mut Context<'_>) -> Poll<Option<Result<Delivered, TransportError>>> {
loop {
let read = match active.items.poll_next_unpin(cx) {
Poll::Ready(Some(Ok(Delivered::Input(InputSignal::Credit(n))))) => {
self.credit = self.credit.saturating_add(n);
true
}
Poll::Ready(Some(Ok(Delivered::Input(InputSignal::Ack)))) => true,
Poll::Ready(Some(Ok(Delivered::Input(InputSignal::Closed)))) => {
self.input = None;
true
}
Poll::Ready(Some(item)) => {
if let Ok(item) = &item {
if item.is_terminal() {
self.input = None;
active.guard.slot.mark_finished();
}
}
return Poll::Ready(Some(item));
}
Poll::Ready(None) => return Poll::Ready(None),
Poll::Pending => false,
};
match self.feed(active, cx) {
Err(e) => {
self.failed = true;
return Poll::Ready(Some(Err(e)));
}
Ok(fed) if read || fed => continue,
Ok(_) => return Poll::Pending,
}
}
}
fn feed(&mut self, active: &Active, cx: &mut Context<'_>) -> Result<bool, TransportError> {
let Some(subscription) = active.guard.slot.subscription() else { return Ok(false) };
let Some(input) = &mut self.input else { return Ok(false) };
let mut items = String::new();
let mut count = 0;
let mut over = false;
let ns = self.registry.hub_namespace();
let mut binaries = 0;
while self.credit > 0 && count < FRAME_ITEMS && items.len() < FRAME_BYTES {
match Pin::new(&mut *input).poll_next(cx) {
Poll::Ready(Some(Ok(InputItem::Json(item)))) => {
if count > 0 {
items.push(',');
}
items.push_str(&item.to_string());
count += 1;
self.credit -= 1;
}
Poll::Ready(Some(Ok(InputItem::Binary(payload)))) => {
if count > 0 {
let frame = input_frame(ns, &subscription, self.seq, &items);
trace("→", &frame);
self.conn.send(frame)?;
self.seq += 1;
items.clear();
count = 0;
}
self.conn.send_binary(binary_frame(&subscription, self.seq, &payload)?)?;
self.seq += 1;
self.credit -= 1;
binaries += 1;
}
Poll::Ready(Some(Err(e))) => return Err(e),
Poll::Ready(None) => {
over = true;
break;
}
Poll::Pending => break,
}
}
if count > 0 {
let frame = input_frame(ns, &subscription, self.seq, &items);
trace("→", &frame);
self.conn.send(frame)?;
self.seq += 1;
}
if over {
self.input = None;
let frame = end_frame(ns, &subscription, self.seq);
trace("→", &frame);
self.conn.send(frame)?;
}
Ok(count > 0 || binaries > 0 || over)
}
}
fn binary_frame(subscription: &Value, seq: u64, payload: &[u8]) -> Result<Vec<u8>, TransportError> {
let Some(subscription) = subscription.as_u64() else {
return Err(TransportError::protocol(format!("a binary input frame needs an integer subscription id, not {subscription}")));
};
let mut frame = Vec::with_capacity(17 + payload.len());
frame.push(0x01);
frame.extend_from_slice(&subscription.to_be_bytes());
frame.extend_from_slice(&seq.to_be_bytes());
frame.extend_from_slice(payload);
Ok(frame)
}
enum CallState {
Awaiting(Awaiting),
Active(Active),
Failed(TransportError),
Ended,
}
struct Awaiting {
reply: futures_channel::oneshot::Receiver<Result<Items, TransportError>>,
guard: SubGuard,
}
impl Awaiting {
async fn established(self) -> Result<Active, TransportError> {
match self.reply.await {
Ok(Ok(items)) => Ok(Active {
items,
guard: self.guard,
}),
Ok(Err(e)) => Err(e),
Err(_) => Err(TransportError::closed(
"connection closed before the subscription was acknowledged",
)),
}
}
}
struct Active {
guard: SubGuard,
items: Items,
}
impl Active {
async fn next_item(&mut self) -> Option<Result<Delivered, TransportError>> {
loop {
match self.items.next().await {
Some(Ok(Delivered::Input(_))) => continue,
Some(Ok(item)) => {
if item.is_terminal() {
self.guard.slot.mark_finished();
}
return Some(Ok(item));
}
Some(Err(e)) => return Some(Err(e)),
None => return None,
}
}
}
}
struct SubGuard {
conn: backend::Conn,
registry: Arc<Registry>,
slot: Arc<SubSlot>,
}
impl Drop for SubGuard {
fn drop(&mut self) {
let Some(subscription) = self.slot.on_dropped() else {
return;
};
self.registry.forget_sub(&subscription);
let frame = self.registry.unsubscribe(&subscription);
trace("→", &frame);
let _ = self.conn.send(frame);
}
}