use crate::errors::{BusRequestError, BusRequestErrorCode, TransportError};
use crate::event_bus::EventBus;
use crate::locked;
use crate::required::{Fault, fault_of, schema};
use crate::types::{
AnchoredTextAnswer, CreateResourceResponse, GetAnnotationsResponse, GetResourceResponse,
HealthResponse, MediaTokenResponse, ProtectedResourceMetadata, StatusResponse, UserResponse,
};
use crate::types::{AnnotationId, JobId};
use crate::types::{BusFrame, ResourceId, Schema};
use bytes::Bytes;
use futures_core::Stream;
use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::fmt;
use std::future::{Future, IntoFuture};
use std::pin::Pin;
use std::sync::{Arc, Mutex};
use std::task::{Context, Poll};
use tokio::sync::{broadcast, mpsc, oneshot, watch};
use tokio_stream::wrappers::BroadcastStream;
use tokio_stream::wrappers::errors::BroadcastStreamRecvError;
pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
pub const STREAM_BACKLOG: usize = 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ConnectionState {
Initial,
Connecting,
Open,
Reconnecting,
Degraded,
Unauthenticated,
Closed,
}
impl ConnectionState {
pub const fn as_str(self) -> &'static str {
match self {
ConnectionState::Initial => "initial",
ConnectionState::Connecting => "connecting",
ConnectionState::Open => "open",
ConnectionState::Reconnecting => "reconnecting",
ConnectionState::Degraded => "degraded",
ConnectionState::Unauthenticated => "unauthenticated",
ConnectionState::Closed => "closed",
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Envelope {
pub correlation_id: Option<String>,
pub scope: Option<ResourceId>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TraceCarrier {
pub traceparent: String,
pub tracestate: Option<String>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct Frame {
pub channel: String,
pub payload: Map<String, Value>,
pub correlation_id: Option<String>,
pub scope: Option<ResourceId>,
pub trace: Option<TraceCarrier>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameRefusalReason {
Lacks,
Malformed,
}
impl FrameRefusalReason {
const EVERY: [FrameRefusalReason; 2] =
[FrameRefusalReason::Lacks, FrameRefusalReason::Malformed];
pub const fn as_str(self) -> &'static str {
match self {
FrameRefusalReason::Lacks => "lacks",
FrameRefusalReason::Malformed => "malformed",
}
}
}
impl Serialize for FrameRefusalReason {
fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for FrameRefusalReason {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let spelled = String::deserialize(deserializer)?;
FrameRefusalReason::EVERY
.into_iter()
.find(|reason| reason.as_str() == spelled)
.ok_or_else(|| de::Error::custom(format!("no refusal's reason is spelled {spelled:?}")))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FrameRefusal {
pub channel: String,
pub member: String,
pub reason: FrameRefusalReason,
pub payload: Option<Value>,
pub scope: Option<ResourceId>,
pub correlation_id: Option<String>,
}
impl fmt::Display for FrameRefusal {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let fault = Fault {
member: self.member.clone(),
reason: self.reason,
};
write!(
f,
"a frame on {} is not that channel's: {fault}",
self.channel
)
}
}
impl FrameRefusal {
pub fn of(frame: &Value, channel: String, scope: Option<ResourceId>) -> Option<FrameRefusal> {
let fault = fault_of(schema(BusFrame::NAME), frame)?;
Some(FrameRefusal {
channel,
member: fault.member,
reason: fault.reason,
payload: frame.get("payload").cloned(),
scope,
correlation_id: correlation_in(frame),
})
}
}
fn correlation_in(frame: &Value) -> Option<String> {
let id = frame.get("correlationId")?;
let Some((_, allowed)) = schema(BusFrame::NAME)
.members
.iter()
.find(|(name, _)| *name == "correlationId")
else {
panic!("BusFrame names no correlationId");
};
match fault_of(allowed, id) {
None => id.as_str().map(str::to_owned),
Some(_) => None,
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Lagged(pub u64);
impl fmt::Display for Lagged {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "a reader fell behind and missed {} items", self.0)
}
}
impl std::error::Error for Lagged {}
pub struct Events<T> {
inner: BroadcastStream<T>,
}
impl<T: Clone + Send + 'static> Events<T> {
pub fn new(receiver: broadcast::Receiver<T>) -> Events<T> {
Events {
inner: BroadcastStream::new(receiver),
}
}
pub async fn next(&mut self) -> Option<Result<T, Lagged>> {
std::future::poll_fn(|cx| Pin::new(&mut *self).poll_next(cx)).await
}
}
impl<T: Clone + Send + 'static> Stream for Events<T> {
type Item = Result<T, Lagged>;
fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
Pin::new(&mut self.inner).poll_next(cx).map(|item| {
item.map(|received| {
received.map_err(|BroadcastStreamRecvError::Lagged(missed)| Lagged(missed))
})
})
}
}
pub type Frames = Events<Result<Frame, FrameRefusal>>;
pub type Failures = Events<TransportError>;
pub(crate) type Broadcast = broadcast::Sender<Result<Frame, FrameRefusal>>;
pub struct FrameHub {
channels: Mutex<Option<HashMap<String, Broadcast>>>,
}
impl Default for FrameHub {
fn default() -> FrameHub {
FrameHub {
channels: Mutex::new(Some(HashMap::new())),
}
}
}
impl FrameHub {
pub fn new() -> FrameHub {
FrameHub::default()
}
pub fn frames(&self, channel: &str) -> Frames {
match locked(&self.channels).as_mut() {
Some(channels) => Events::new(
channels
.entry(channel.to_owned())
.or_insert_with(|| broadcast::channel(STREAM_BACKLOG).0)
.subscribe(),
),
None => Events::new(broadcast::channel(1).1),
}
}
pub fn deliver(&self, carried: Result<Frame, FrameRefusal>) -> usize {
let channel = match &carried {
Ok(frame) => &frame.channel,
Err(refusal) => &refusal.channel,
};
let mut channels = locked(&self.channels);
let Some(channels) = channels.as_mut() else {
return 0;
};
let Some(sender) = channels.get(channel) else {
return 0;
};
if sender.receiver_count() == 0 {
channels.remove(channel);
return 0;
}
sender.send(carried).unwrap_or(0)
}
pub fn close(&self) {
*locked(&self.channels) = None;
}
}
struct Awaited {
channels: Vec<String>,
reply: oneshot::Sender<Result<Frame, FrameRefusal>>,
}
pub struct ReplyRouter {
awaited: Mutex<Option<HashMap<String, Awaited>>>,
}
impl ReplyRouter {
pub fn new() -> Arc<ReplyRouter> {
Arc::new(ReplyRouter {
awaited: Mutex::new(Some(HashMap::new())),
})
}
pub fn track(self: &Arc<Self>, correlation_id: &str, reply_channels: &[&str]) -> PendingReply {
let (reply, receiver) = oneshot::channel();
if let Some(awaited) = locked(&self.awaited).as_mut() {
awaited.insert(
correlation_id.to_owned(),
Awaited {
channels: reply_channels.iter().map(|c| (*c).to_owned()).collect(),
reply,
},
);
}
PendingReply {
router: self.clone(),
correlation_id: correlation_id.to_owned(),
receiver,
}
}
pub fn route(&self, carried: Result<&Frame, &FrameRefusal>) {
let (correlation_id, channel) = match carried {
Ok(frame) => (&frame.correlation_id, &frame.channel),
Err(refusal) => (&refusal.correlation_id, &refusal.channel),
};
let Some(correlation_id) = correlation_id else {
return;
};
let mut awaited = locked(&self.awaited);
let Some(awaited) = awaited.as_mut() else {
return;
};
if awaited
.get(correlation_id)
.is_some_and(|a| a.channels.contains(channel))
&& let Some(request) = awaited.remove(correlation_id)
{
let _ = request
.reply
.send(carried.cloned().map_err(FrameRefusal::clone));
}
}
pub fn awaited(&self) -> Vec<String> {
let mut ids: Vec<String> = locked(&self.awaited)
.as_ref()
.map(|awaited| awaited.keys().cloned().collect())
.unwrap_or_default();
ids.sort();
ids
}
pub fn close(&self) {
*locked(&self.awaited) = None;
}
}
pub struct PendingReply {
router: Arc<ReplyRouter>,
correlation_id: String,
receiver: oneshot::Receiver<Result<Frame, FrameRefusal>>,
}
impl PendingReply {
pub async fn frame(&mut self) -> Option<Result<Frame, FrameRefusal>> {
(&mut self.receiver).await.ok()
}
}
impl Drop for PendingReply {
fn drop(&mut self) {
if let Some(awaited) = locked(&self.router.awaited).as_mut() {
awaited.remove(&self.correlation_id);
}
}
}
pub struct ResourceHold {
release: Option<Box<dyn FnOnce() + Send + Sync>>,
}
impl ResourceHold {
pub fn new(release: impl FnOnce() + Send + Sync + 'static) -> ResourceHold {
ResourceHold {
release: Some(Box::new(release)),
}
}
}
impl Drop for ResourceHold {
fn drop(&mut self) {
if let Some(release) = self.release.take() {
release();
}
}
}
pub trait Transport: Send + Sync + 'static {
fn base_url(&self) -> &str;
fn emit<'a>(
&'a self,
channel: &'a str,
payload: Map<String, Value>,
envelope: Envelope,
) -> BoxFuture<'a, Result<Option<u64>, TransportError>>;
fn frames(&self, channel: &str) -> Result<Frames, BusRequestError>;
fn is_subscribed(&self, channel: &str) -> bool;
fn subscribe_to_resource(&self, resource_id: &ResourceId) -> ResourceHold;
fn state(&self) -> watch::Receiver<ConnectionState>;
fn failures(&self) -> Failures;
fn track_reply(&self, correlation_id: &str, reply_channels: &[&str]) -> PendingReply;
fn bridge_into(&self, bus: Arc<EventBus>);
fn close(&self) -> BoxFuture<'_, ()>;
}
pub fn unsubscribed(channel: &str) -> BusRequestError {
BusRequestError::new(
BusRequestErrorCode::Unsubscribed,
format!(
"Transport is not subscribed to {channel}: a frame on it can never arrive on this connection. Add the channel to this client's channels."
),
)
}
#[derive(Debug, Clone, PartialEq)]
pub struct PutBinaryRequest {
pub name: String,
pub bytes: Bytes,
pub format: String,
pub storage_uri: String,
pub entity_types: Vec<String>,
pub language: Option<String>,
pub source_annotation_id: Option<AnnotationId>,
pub source_resource_id: Option<ResourceId>,
pub generation_prompt: Option<String>,
pub generator: Option<Value>,
pub job_id: Option<JobId>,
pub is_draft: Option<bool>,
pub clone_token: Option<String>,
pub archive_original: Option<bool>,
}
impl PutBinaryRequest {
pub fn new(
name: impl Into<String>,
bytes: Bytes,
format: impl Into<String>,
storage_uri: impl Into<String>,
) -> Self {
Self {
name: name.into(),
bytes,
format: format.into(),
storage_uri: storage_uri.into(),
entity_types: Vec::new(),
language: None,
source_annotation_id: None,
source_resource_id: None,
generation_prompt: None,
generator: None,
job_id: None,
is_draft: None,
clone_token: None,
archive_original: None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct UploadProgress {
pub bytes_uploaded: u64,
pub total_bytes: u64,
}
pub struct Upload {
progress: mpsc::UnboundedReceiver<UploadProgress>,
sending: Option<BoxFuture<'static, Result<CreateResourceResponse, TransportError>>>,
outcome: Option<Result<CreateResourceResponse, TransportError>>,
}
impl Upload {
pub fn new(
progress: mpsc::UnboundedReceiver<UploadProgress>,
sending: BoxFuture<'static, Result<CreateResourceResponse, TransportError>>,
) -> Upload {
Upload {
progress,
sending: Some(sending),
outcome: None,
}
}
fn drive(&mut self, cx: &mut Context<'_>) {
if let Some(sending) = self.sending.as_mut()
&& let Poll::Ready(outcome) = sending.as_mut().poll(cx)
{
self.outcome = Some(outcome);
self.sending = None;
}
}
}
impl Stream for Upload {
type Item = UploadProgress;
fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
self.drive(cx);
match self.progress.poll_recv(cx) {
Poll::Ready(Some(progress)) => Poll::Ready(Some(progress)),
Poll::Ready(None) => Poll::Ready(None),
Poll::Pending if self.sending.is_none() => Poll::Ready(None),
Poll::Pending => Poll::Pending,
}
}
}
impl IntoFuture for Upload {
type Output = Result<CreateResourceResponse, TransportError>;
type IntoFuture = BoxFuture<'static, Self::Output>;
fn into_future(mut self) -> Self::IntoFuture {
Box::pin(async move {
std::future::poll_fn(|cx| {
self.drive(cx);
match self.outcome.take() {
Some(outcome) => Poll::Ready(outcome),
None => Poll::Pending,
}
})
.await
})
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct Content {
pub bytes: Bytes,
pub content_type: String,
}
pub struct ContentStream {
pub bytes: Pin<Box<dyn Stream<Item = Result<Bytes, TransportError>> + Send>>,
pub content_type: String,
}
pub trait ContentTransport: Send + Sync + 'static {
fn put_binary(&self, request: PutBinaryRequest) -> Upload;
fn get_binary<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<Content, TransportError>>;
fn get_binary_stream<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<ContentStream, TransportError>>;
fn get_resource_graph<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<GetResourceResponse, TransportError>>;
fn get_annotations<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<GetAnnotationsResponse, TransportError>>;
fn get_anchored_text<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<AnchoredTextAnswer, TransportError>>;
}
pub trait GatewayOperations: Send + Sync + 'static {
fn get_current_user(&self) -> BoxFuture<'_, Result<UserResponse, TransportError>>;
fn get_media_token<'a>(
&'a self,
resource_id: &'a ResourceId,
) -> BoxFuture<'a, Result<MediaTokenResponse, TransportError>>;
fn get_protected_resource_metadata(
&self,
) -> BoxFuture<'_, Result<ProtectedResourceMetadata, TransportError>>;
fn health_check(&self) -> BoxFuture<'_, Result<HealthResponse, TransportError>>;
fn get_status(&self) -> BoxFuture<'_, Result<StatusResponse, TransportError>>;
}
#[cfg(test)]
mod tests {
use super::*;
fn frame(channel: &str, correlation_id: Option<&str>) -> Frame {
Frame {
channel: channel.to_owned(),
payload: Map::new(),
correlation_id: correlation_id.map(str::to_owned),
scope: None,
trace: None,
}
}
#[tokio::test]
async fn a_reader_of_one_channel_is_not_lagged_by_another() {
let hub = FrameHub::new();
let mut quiet = hub.frames("quiet");
let _busy = hub.frames("busy");
for _ in 0..(STREAM_BACKLOG * 3) {
hub.deliver(Ok(frame("busy", None)));
}
hub.deliver(Ok(frame("quiet", None)));
assert_eq!(quiet.next().await, Some(Ok(Ok(frame("quiet", None)))));
}
#[tokio::test]
async fn a_reader_that_fell_behind_is_told_how_far() {
let hub = FrameHub::new();
let mut frames = hub.frames("busy");
for _ in 0..(STREAM_BACKLOG + 5) {
hub.deliver(Ok(frame("busy", None)));
}
assert_eq!(frames.next().await, Some(Err(Lagged(5))));
assert!(matches!(frames.next().await, Some(Ok(_))));
}
#[tokio::test]
async fn a_closed_hub_ends_every_stream() {
let hub = FrameHub::new();
let mut before = hub.frames("a");
hub.close();
assert_eq!(before.next().await, None);
assert_eq!(hub.frames("a").next().await, None);
}
#[tokio::test]
async fn a_reply_reaches_the_request_that_awaits_it_and_no_other() {
let router = ReplyRouter::new();
let mut mine = router.track("cid-1", &["result", "failure"]);
let mut theirs = router.track("cid-2", &["result", "failure"]);
assert_eq!(router.awaited(), ["cid-1", "cid-2"]);
router.route(Ok(&frame("progress", Some("cid-1"))));
router.route(Ok(&frame("result", Some("cid-1"))));
assert_eq!(mine.frame().await, Some(Ok(frame("result", Some("cid-1")))));
assert_eq!(router.awaited(), ["cid-2"]);
router.close();
assert_eq!(theirs.frame().await, None);
}
fn refusal(channel: &str, correlation_id: Option<&str>) -> FrameRefusal {
FrameRefusal {
channel: channel.to_owned(),
member: "addedByALaterGateway".to_owned(),
reason: FrameRefusalReason::Malformed,
payload: Some(serde_json::json!({ "response": {} })),
scope: None,
correlation_id: correlation_id.map(str::to_owned),
}
}
#[tokio::test]
async fn a_refused_reply_reaches_the_request_its_correlation_id_names_and_one_naming_none_reaches_none()
{
let router = ReplyRouter::new();
let mut mine = router.track("cid-1", &["result", "failure"]);
let _theirs = router.track("cid-2", &["result", "failure"]);
router.route(Err(&refusal("result", None)));
router.route(Err(&refusal("progress", Some("cid-1"))));
assert_eq!(router.awaited(), ["cid-1", "cid-2"]);
router.route(Err(&refusal("result", Some("cid-1"))));
assert_eq!(
mine.frame().await,
Some(Err(refusal("result", Some("cid-1"))))
);
assert_eq!(router.awaited(), ["cid-2"]);
}
#[tokio::test]
async fn a_dropped_wait_is_named_no_more() {
let router = ReplyRouter::new();
let pending = router.track("cid-1", &["result"]);
drop(pending);
assert!(router.awaited().is_empty());
}
#[tokio::test]
async fn a_hold_is_released_once_when_dropped() {
let released = Arc::new(Mutex::new(0));
let count = released.clone();
let hold = ResourceHold::new(move || *locked(&count) += 1);
drop(hold);
assert_eq!(*locked(&released), 1);
}
}