Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

13.4 KB
Raw Blame
//! Plain WebSocket carrier.
//!
//! Both peers of the WebSocket are symmetric: either side can push a logical
//! message onto the wire the instant the socket exists, and the other side
//! just reads it. There is no RPC session, no method dispatch, no request id,
//! and no subscribe/unsubscribe handshake to establish first - a WebSocket
//! frame is not itself JSON-RPC, unlike the ACP payload it can carry.
//!
//! One WebSocket text frame carries exactly one complete logical message -
//! [`crate::domain::schema::v0::ToRuntimeMessage`] or
//! [`crate::domain::schema::v0::ToServerMessage`], `"type"`-tagged as
//! described in [`crate::domain::schema`]:
//!
//! ```json
//! { "type": "event", "event": "agent/stopped" }
//! ```

use std::sync::Arc;
use std::time::Duration;

use axum::Router;
use axum::extract::State;
use axum::extract::ws::{Message as AxumMessage, WebSocket, WebSocketUpgrade};
use axum::response::Response;
use axum::routing::get;
use futures::{Sink, SinkExt, Stream, StreamExt};
use serde::Serialize;
use serde::de::DeserializeOwned;
use tokio::io::{AsyncRead, AsyncWrite};
use tokio::sync::Mutex as AsyncMutex;
use tokio::sync::mpsc;
// Tokio's clock rather than the standard library's, so the silence deadline is
// on the same clock as the interval that checks it - and so a test can drive
// both without waiting out six real seconds.
use tokio::time::Instant;
use tokio_tungstenite::WebSocketStream;
use tokio_tungstenite::tungstenite::Message as TungsteniteMessage;

use crate::domain::channel::{Channel, pump};
use crate::domain::ports::{Transport, TransportError, TransportSender};

#[cfg(test)]
mod test;

/// How often each peer sends a WebSocket ping.
///
/// Both ends ping on their own timer rather than one pinging and the other
/// answering. Keepalive would only need one side - any frame resets an idle
/// proxy's timer - but *detection* is per-endpoint: the gateway has to notice
/// a daemon that went away, and a daemon has to notice a gateway that did, so
/// each end needs traffic it can time out on. Symmetric also means neither
/// end depends on the other being new enough to ping.
const PING_INTERVAL: Duration = Duration::from_secs(2);

/// How long a socket may go without any inbound frame before this side
/// declares it dead.
///
/// Three missed pings. A live peer answers every ping with a pong, and a pong
/// is an inbound frame, so silence this long means the peer is gone or the
/// path to it is - the case a half-open socket produces, where writes keep
/// succeeding into a connection that will never answer again.
const SILENCE_TIMEOUT: Duration = Duration::from_secs(6);

/// A physical WebSocket frame type: one JSON text payload, or a ping.
///
/// Implemented for both `axum`'s and `tokio-tungstenite`'s message types so
/// the pump loop below can drive either a server-accepted or a
/// client-dialed socket without caring which library it came from.
trait WireFrame: Sized {
    /// Wrap a JSON payload as a text frame.
    fn text(payload: String) -> Self;

    /// An empty ping frame.
    fn ping() -> Self;

    /// Extract this frame's text payload, if it has one.
    ///
    /// Non-text frames (ping/pong/binary/close) are not part of the logical
    /// protocol and are silently skipped by the pump loop - but they still
    /// count as liveness, which is the whole point of the pings.
    fn into_text(self) -> Option<String>;
}

impl WireFrame for AxumMessage {
    fn text(payload: String) -> Self {
        Self::Text(payload.into())
    }

    fn ping() -> Self {
        Self::Ping(Default::default())
    }

    fn into_text(self) -> Option<String> {
        match self {
            Self::Text(text) => Some(text.to_string()),
            _ => None,
        }
    }
}

impl WireFrame for TungsteniteMessage {
    fn text(payload: String) -> Self {
        Self::Text(payload.into())
    }

    fn ping() -> Self {
        Self::Ping(Default::default())
    }

    fn into_text(self) -> Option<String> {
        match self {
            Self::Text(text) => Some(text.to_string()),
            _ => None,
        }
    }
}

/// Drive one physical WebSocket until it closes or fails: outgoing JSON text
/// pulled from `outgoing` is written to the socket, and incoming text frames
/// are decoded and pushed onto `incoming`. When `outgoing` ends, this side
/// sends its close frame and keeps reading until the peer closes (or goes
/// silent), so nothing the peer already sent is lost.
///
/// A frame that fails to decode as `Rx` is dropped with a warning rather than
/// closing the connection - the rest of the logical stream is unaffected by
/// one malformed message.
async fn run_pump<Rx, Socket, Frame, Error>(
    socket: Socket,
    mut outgoing: mpsc::UnboundedReceiver<String>,
    incoming: mpsc::UnboundedSender<Rx>,
) where
    Rx: DeserializeOwned,
    Frame: WireFrame,
    Socket: Sink<Frame, Error = Error> + Stream<Item = Result<Frame, Error>> + Unpin,
{
    let (mut sink, mut stream) = socket.split();
    let mut ping = tokio::time::interval(PING_INTERVAL);
    // A pump that was busy longer than one tick owes one ping, not a burst of
    // however many it slept through.
    ping.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
    let mut last_inbound = Instant::now();
    // Set once this side has nothing more to send: its close frame is out,
    // and the pump keeps reading until the peer closes too.
    let mut closing = false;
    loop {
        tokio::select! {
            next_outgoing = outgoing.recv(), if !closing => {
                let Some(payload) = next_outgoing else {
                    // Frames the peer sent before it sees the close are still
                    // delivered; dropping the socket here would discard them.
                    if sink.close().await.is_err() {
                        break;
                    }
                    closing = true;
                    continue;
                };
                if sink.send(Frame::text(payload)).await.is_err() {
                    break;
                }
            }
            next_incoming = stream.next() => {
                // Every frame counts, text or not: a pong carries no logical
                // message and is exactly what proves the peer is still there.
                last_inbound = Instant::now();
                match next_incoming {
                    Some(Ok(frame)) => {
                        let Some(text) = frame.into_text() else { continue };
                        match serde_json::from_str::<Rx>(&text) {
                            Ok(message) => {
                                if incoming.send(message).is_err() {
                                    break;
                                }
                            }
                            Err(error) => {
                                tracing::warn!(error = ?error, "dropping malformed WebSocket frame");
                            }
                        }
                    }
                    Some(Err(_)) | None => break,
                }
            }
            _ = ping.tick() => {
                let silent_for = last_inbound.elapsed();
                if silent_for >= SILENCE_TIMEOUT {
                    tracing::warn!(
                        silent_for_ms = silent_for.as_millis(),
                        "closing a WebSocket that stopped answering pings"
                    );
                    break;
                }
                // Both halves of a split socket share one connection, so this
                // is also what flushes any pong the read half queued.
                if !closing && sink.send(Frame::ping()).await.is_err() {
                    break;
                }
            }
        }
    }
}

/// [`Transport`] adapter over one peer's plain WebSocket.
///
/// Sending serializes straight to a JSON string and hands it to the spawned
/// pump task's write half; receiving drains the channel that pump feeds from
/// the socket's read half.
///
/// Crate-visible rather than private so the interface-conformance tests in
/// [`crate::testing::wire_conformance`] can exercise it directly through the
/// [`Transport`] trait, the same way they exercise
/// [`crate::testing::fake_wire::FakeTransport`].
pub(crate) struct WebSocketWire<Rx> {
    outgoing: mpsc::UnboundedSender<String>,
    incoming: mpsc::UnboundedReceiver<Rx>,
}

/// The sending half: serializes and hands the text to the pump's write half.
///
/// Not parameterized by the message type: the wire carries JSON text, so any
/// serializable message can go out on it, and which one does is the caller's
/// business rather than this half's.
pub(crate) struct WebSocketSender {
    outgoing: mpsc::UnboundedSender<String>,
}

impl<Tx> TransportSender<Tx> for WebSocketSender
where
    Tx: Serialize + Send + Sync + 'static,
{
    async fn send(&self, message: Tx) -> Result<(), TransportError> {
        let payload = serde_json::to_string(&message)
            .map_err(|error| TransportError::Client(error.to_string()))?;
        self.outgoing
            .send(payload)
            .map_err(|_| TransportError::Client("WebSocket connection closed".to_owned()))
    }
}

impl<Tx, Rx> Transport<Tx, Rx> for WebSocketWire<Rx>
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: Send + 'static,
{
    type Sender = WebSocketSender;
    type Receiver = mpsc::UnboundedReceiver<Rx>;

    fn split(self) -> (Self::Sender, Self::Receiver) {
        (
            WebSocketSender {
                outgoing: self.outgoing,
            },
            self.incoming,
        )
    }
}

fn wire_channel<Tx, Rx>(
    outgoing: mpsc::UnboundedSender<String>,
    incoming: mpsc::UnboundedReceiver<Rx>,
) -> Channel<Tx, Rx>
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: Send + 'static,
{
    pump(WebSocketWire { outgoing, incoming })
}

/// An axum WebSocket acceptor and its stream of accepted runtime connections.
///
/// One accepted WebSocket is exactly one logical session: there is no
/// caller-chosen identifier and no way to multiplex several logical sessions
/// over one socket.
pub struct ServerTransport<Tx, Rx> {
    incoming_tx: mpsc::UnboundedSender<Channel<Tx, Rx>>,
    incoming: AsyncMutex<mpsc::UnboundedReceiver<Channel<Tx, Rx>>>,
}

impl<Tx, Rx> ServerTransport<Tx, Rx> {
    /// Construct an empty server carrier.
    #[must_use]
    pub fn new() -> Self {
        let (incoming_tx, incoming) = mpsc::unbounded_channel();
        Self {
            incoming_tx,
            incoming: AsyncMutex::new(incoming),
        }
    }

    /// Wait for the next accepted runtime connection.
    pub async fn accept(&self) -> Option<Channel<Tx, Rx>> {
        self.incoming.lock().await.recv().await
    }
}

impl<Tx, Rx> Default for ServerTransport<Tx, Rx> {
    fn default() -> Self {
        Self::new()
    }
}

impl<Tx, Rx> ServerTransport<Tx, Rx>
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: DeserializeOwned + Send + Sync + 'static,
{
    /// Build a router with one route that upgrades an incoming WebSocket
    /// into a runtime connection, delivered on [`ServerTransport::accept`].
    pub fn into_router(self: Arc<Self>) -> Router {
        Router::new()
            .route("/", get(upgrade::<Tx, Rx>))
            .with_state(self)
    }
}

async fn upgrade<Tx, Rx>(
    State(transport): State<Arc<ServerTransport<Tx, Rx>>>,
    ws: WebSocketUpgrade,
) -> Response
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: DeserializeOwned + Send + Sync + 'static,
{
    ws.on_upgrade(move |socket: WebSocket| async move {
        let _ = transport.incoming_tx.send(connect_socket(socket));
    })
}

/// Bridge an already-upgraded WebSocket into its logical channel, spawning the
/// frame pump as an independent task and returning the `Channel` immediately.
///
/// Unlike [`ServerTransport`], this doesn't own routing or session
/// identification - it's the building block for a caller that needs to key
/// connections by something in the upgrade request (e.g. a query parameter):
/// build a plain axum route with a [`WebSocketUpgrade`] extractor, do
/// whatever routing the request needs, and hand the resulting socket here.
pub fn connect_socket<Tx, Rx>(socket: WebSocket) -> Channel<Tx, Rx>
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: DeserializeOwned + Send + Sync + 'static,
{
    let (outgoing_tx, outgoing_rx) = mpsc::unbounded_channel();
    let (incoming_tx, incoming_rx) = mpsc::unbounded_channel();
    tokio::spawn(run_pump(socket, outgoing_rx, incoming_tx));
    wire_channel(outgoing_tx, incoming_rx)
}

/// Build the runtime-side wire over an already-connected WebSocket stream.
///
/// Unlike the service side, the runtime doesn't go through axum: it dials out
/// and drives the socket itself, so this takes an already-connected
/// [`WebSocketStream`] directly.
pub(crate) fn client_wire<Rx, S>(stream: WebSocketStream<S>) -> WebSocketWire<Rx>
where
    Rx: DeserializeOwned + Send + Sync + 'static,
    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
    let (outgoing_tx, outgoing_rx) = mpsc::unbounded_channel();
    let (incoming_tx, incoming_rx) = mpsc::unbounded_channel();
    tokio::spawn(run_pump(stream, outgoing_rx, incoming_tx));

    WebSocketWire {
        outgoing: outgoing_tx,
        incoming: incoming_rx,
    }
}

/// Bridge a runtime-side WebSocket stream into its logical channel.
pub fn connect_runtime<Tx, Rx, S>(stream: WebSocketStream<S>) -> Channel<Tx, Rx>
where
    Tx: Serialize + Send + Sync + 'static,
    Rx: DeserializeOwned + Send + Sync + 'static,
    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
    pump(client_wire::<Rx, S>(stream))
}