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.

15.3 KB
Raw Blame
use bebop::{Record, SliceWrapper};
use loro::{VersionVector, awareness::EphemeralStore};
use tracing::trace;
use worker::Result;

use crate::{
    auth::WriteAccess,
    domain::document::writing_peers,
    durable_object::{SyncSession, Wsm},
    error::ResultExt,
    generated::schema::{FromPeer, FromRemote},
    lexical_service::LexicalServiceClient,
    socket::Socket,
    state::DocumentState,
    storage::SessionStorage,
};

/// Decodes an inbound WebSocket payload once, before its trace span is created.
pub fn deserialize_message(message: &[u8]) -> Result<FromPeer<'_>> {
    if message.len() > MAX_MESSAGE_SIZE {
        tracing::warn!("received message might be too large {}", message.len());
    }
    FromPeer::deserialize(message).context(format!(
        "failed to deserialize message, message length {}",
        message.len()
    ))
}

/// Returns the protocol-level type of an inbound WebSocket message.
pub fn message_type(message: &FromPeer<'_>) -> &'static str {
    match message {
        FromPeer::PeerRegisterId { .. } => "register_id",
        FromPeer::PeerUpdate { .. } => "update",
        FromPeer::PeerCommentUpdate { .. } => "comment_update",
        FromPeer::PeerAwareness { .. } => "awareness",
        FromPeer::PeerRequestSince { .. } => "request_since",
        FromPeer::PeerRequestSnapshot { .. } => "request_snapshot",
        FromPeer::Unknown => "unknown",
    }
}

/// Diagnostic fields collected while handling an inbound WebSocket message.
pub struct InboundMessageTelemetry {
    document_id: Option<String>,
    ws_id: Option<String>,
    message_type: &'static str,
    message_bytes: usize,
    error_stage: &'static str,
    op_id: Option<String>,
    peer_id: Option<u64>,
    update_bytes: Option<usize>,
    response_bytes: Option<usize>,
    broadcast_targets: Option<usize>,
}

impl InboundMessageTelemetry {
    /// Start collecting diagnostics without creating a span.
    pub fn new(message_bytes: usize) -> Self {
        Self {
            document_id: None,
            ws_id: None,
            message_type: "unknown",
            message_bytes,
            error_stage: "unknown",
            op_id: None,
            peer_id: None,
            update_bytes: None,
            response_bytes: None,
            broadcast_targets: None,
        }
    }

    /// Record identifiers available from the Durable Object callback.
    pub fn record_context(&mut self, document_id: &str, ws_id: Option<String>) {
        self.document_id = Some(document_id.to_string());
        self.ws_id = ws_id;
    }

    /// Record the decoded protocol message type.
    pub fn record_message_type(&mut self, message_type: &'static str) {
        self.message_type = message_type;
    }

    /// Record which stage of message handling failed.
    pub fn record_error_stage(&mut self, error_stage: &'static str) {
        self.error_stage = error_stage;
    }

    /// Create the only span emitted for this message, after handling fails.
    pub fn error_span(&self) -> tracing::Span {
        let span = tracing::error_span!(
            "ws.message.error",
            document.id = tracing::field::Empty,
            ws.id = tracing::field::Empty,
            message.type = self.message_type,
            message.bytes = self.message_bytes,
            error.stage = self.error_stage,
            op.id = tracing::field::Empty,
            peer.id = tracing::field::Empty,
            update.bytes = tracing::field::Empty,
            response.bytes = tracing::field::Empty,
            broadcast.targets = tracing::field::Empty,
        );

        if let Some(document_id) = &self.document_id {
            span.record("document.id", document_id.as_str());
        }
        if let Some(ws_id) = &self.ws_id {
            span.record("ws.id", ws_id.as_str());
        }
        if let Some(op_id) = &self.op_id {
            span.record("op.id", op_id.as_str());
        }
        if let Some(peer_id) = self.peer_id {
            span.record("peer.id", peer_id);
        }
        if let Some(update_bytes) = self.update_bytes {
            span.record("update.bytes", update_bytes);
        }
        if let Some(response_bytes) = self.response_bytes {
            span.record("response.bytes", response_bytes);
        }
        if let Some(broadcast_targets) = self.broadcast_targets {
            span.record("broadcast.targets", broadcast_targets);
        }

        span
    }
}

/// Sends the initial sync message to a single peer.
/// The initial sync message contains the snapshot of the current state of the document
pub fn send_initial_sync(socket: &Socket, snapshot: &[u8], awareness: &[u8]) -> Result<()> {
    socket.send(FromRemote::RemoteInitialSync {
        snapshot: SliceWrapper::Raw(snapshot),
        awareness: SliceWrapper::Raw(awareness),
    })
}

/// Broadcasts an awareness update to every connected peer except `from`.
pub fn broadcast_awareness(dss: &SyncSession, from: &Socket, awareness: &[u8]) -> Result<()> {
    for socket in dss.get_sockets() {
        if socket == *from {
            continue;
        }
        // A dead peer socket must not abort delivery to the remaining peers.
        if let Err(e) = socket.send(FromRemote::RemoteAwareness {
            awareness: SliceWrapper::Raw(awareness),
        }) {
            tracing::warn!(error = ?e, "failed to send awareness to a peer; continuing");
        }
    }
    Ok(())
}

// Max receiving websocket message is 1Mb
const MAX_MESSAGE_SIZE: usize = 1000 * 1000;

#[allow(
    clippy::too_many_arguments,
    reason = "lots of args lets us avoid having multiple mutable refs to same object"
)]
pub async fn process_message(
    sender: &Socket,
    document_id: &str,
    document_state: &DocumentState,
    session_storage: &SessionStorage,
    awareness: &EphemeralStore,
    message: FromPeer<'_>,
    dss: &SyncSession,
    telemetry: &mut InboundMessageTelemetry,
) -> Result<()> {
    // Loading the document after hibernation can yield to a revocation. Check
    // the surface grant again immediately before handling any protocol message.
    if !dss
        .validate_surface_sockets(Some(sender.websocket()))
        .await?
    {
        return Ok(());
    }
    trace!(
        message = tracing::field::display(&message),
        "process websocket message"
    );
    let comment_only = matches!(message, FromPeer::PeerCommentUpdate { .. });
    match message {
        // Handle peer id registration
        // This registers a peer id to the owner of the current websocket
        FromPeer::PeerRegisterId { peerid } => {
            telemetry.peer_id = Some(peerid);
            Wsm::new(dss, sender.websocket())
                .add_new_peerid(peerid, document_id)
                .await?;
        }
        // Handle an incoming update from a peer
        // Should extract binary update and broadcast it to all other connected peers
        // Should also store the update in the operation log to be applied to the remote doc
        FromPeer::PeerUpdate { updates, id } | FromPeer::PeerCommentUpdate { updates, id } => {
            telemetry.op_id = Some(id.to_string());
            telemetry.update_bytes = Some(updates.iter().map(|u| u.len()).sum());
            match Wsm::new(dss, sender.websocket()).write_access().await? {
                WriteAccess::None => {
                    tracing::warn!("received update from peer without edit permission");
                    return Ok(());
                }
                WriteAccess::CommentMarks => {
                    if !changes_only_comment_marks(dss, document_state, &updates, document_id, id)
                        .await
                    {
                        return Ok(());
                    }
                }
                WriteAccess::Full => {
                    if comment_only
                        && !changes_only_comment_marks(
                            dss,
                            document_state,
                            &updates,
                            document_id,
                            id,
                        )
                        .await
                    {
                        return Ok(());
                    }
                }
            }

            let attribution = match Wsm::new(dss, sender.websocket()).edit_attribution().await {
                Ok(attribution) => attribution,
                Err(error) => {
                    tracing::warn!(error = ?error, "failed to resolve optional edit attribution");
                    None
                }
            };
            let peer_ids = Wsm::new(dss, sender.websocket())
                .get_peer_ids(true)
                .await
                .unwrap_or_default();
            let peer_id = peer_ids.first().copied();
            telemetry.peer_id = peer_id;
            let now_ms = web_time::SystemTime::now()
                .duration_since(web_time::UNIX_EPOCH)
                .map(|d| d.as_millis() as i64)
                .unwrap_or(0);
            for update in &updates {
                let imported = session_storage
                    .append_pending_operation(update, document_state)
                    .await?;
                if imported.changed {
                    dss.record_editor(attribution.as_ref());
                }
                if !imported.touched_nodes.is_empty()
                    && let Some(peer_id) = peer_id
                {
                    dss.push_blame_events(
                        imported
                            .touched_nodes
                            .into_iter()
                            .map(|node_id| crate::d1::BlameEvent {
                                document_id: document_id.to_string(),
                                node_id,
                                peer_id,
                                timestamp_ms: now_ms,
                            })
                            .collect(),
                    );
                }
            }

            // Map every peer the update was written with, not only the one the
            // client registered, so history can name its author. Before the
            // ack: a failure here makes the client resend and retry it.
            let mut writers = Vec::new();
            for update in &updates {
                writers.extend(
                    writing_peers(update)
                        .map_err(|error| worker::Error::from(error.to_string()))?,
                );
            }
            Wsm::new(dss, sender.websocket())
                .add_writing_peerids(&writers, document_id)
                .await?;

            // ACK only after the update is durably stored.
            sender
                .send(FromRemote::RemoteUpdateAck { id })
                .inspect_err(|error| {
                    tracing::error!(error = ?error, op.id = %id, "failed to send update ack");
                })
                .context("failed to send update ack")?;

            let sockets = dss.get_sockets();
            let targets: Vec<&Socket> = sockets.iter().filter(|socket| *socket != sender).collect();
            telemetry.broadcast_targets = Some(targets.len());
            for update in &updates {
                for socket in &targets {
                    if let Err(error) = socket.send(FromRemote::RemoteUpdate {
                        update: SliceWrapper::Raw(update),
                    }) {
                        tracing::warn!(error = ?error, "failed to send update to a peer; continuing");
                    }
                }
            }
        }
        // Handle an incoming awareness update from a peer
        // Should apply the update to the local epehemeral awareness strore
        FromPeer::PeerAwareness {
            awareness: awareness_update,
        } => {
            if let Err(e) = awareness.apply(*awareness_update) {
                tracing::warn!(error = ?e, "failed to apply awareness update; ignoring it");
                return Ok(());
            }
            let encodede = awareness.encode_all();
            let sockets = dss.get_sockets();
            telemetry.broadcast_targets =
                Some(sockets.iter().filter(|socket| *socket != sender).count());
            broadcast_awareness(dss, sender, &encodede).context("failed to broadcast awareness")?;
        }
        // Handle a peer requesting a specific set of updates from the document.
        // The client sends a version vector (not frontiers) so unknown peers
        // — e.g. a peer that made offline edits the server hasn't seen yet —
        // don't cause a panic in `frontiersToVV` lookup.
        FromPeer::PeerRequestSince { vv } => {
            let decoded = VersionVector::decode(*vv).context("failed to decode version vector")?;

            let update = document_state
                .export_updates_since(&decoded)
                .context("failed to export updates")?;
            // Server end of the client's `doc.sync.catchup` span.
            telemetry.response_bytes = Some(update.len());

            // Echo the client's *original* vv bytes back, not a re-encoded copy.
            // The client correlates the response by byte-exact match on the vv it
            // sent; `decode(vv).encode()` is not guaranteed to reproduce the same
            // bytes for a multi-peer version vector, which would make the client
            // discard a perfectly good response and time out.
            sender
                .send(FromRemote::RemoteUpdateSince {
                    update: SliceWrapper::Raw(&update),
                    vv,
                })
                .context("failed to send update")?;
        }
        // Peer is requesting a snapshot from the remote
        FromPeer::PeerRequestSnapshot {} => {
            let snapshot = document_state.export_shallow_snapshot()?;
            telemetry.response_bytes = Some(snapshot.len());

            sender
                .send(FromRemote::RemoteSnapshot {
                    snapshot: SliceWrapper::Raw(&snapshot),
                })
                .context("failed to send snapshot")?;
        }
        FromPeer::Unknown => {
            return Err(worker::Error::from("unknown message type"));
        }
    };

    Ok(())
}

/// A commenter's updates are accepted only when they change nothing but
/// comment marks. Anything that cannot be checked is refused.
#[tracing::instrument(skip_all, fields(document.id = %document_id, op.id = %op_id))]
async fn changes_only_comment_marks(
    dss: &SyncSession,
    document_state: &DocumentState,
    updates: &[SliceWrapper<'_, u8>],
    document_id: &str,
    op_id: &str,
) -> bool {
    let updates: Vec<&[u8]> = updates.iter().map(|update| &update[..]).collect();
    let change = match document_state.root_change(&updates) {
        Ok(Some(change)) => change,
        Ok(None) => {
            tracing::warn!("refused commenter update outside the document body or its history");
            return false;
        }
        Err(error) => {
            tracing::warn!(error = ?error, "refused commenter update that failed to import");
            return false;
        }
    };
    match LexicalServiceClient::new(dss.env())
        .is_comment_only_change(&change)
        .await
    {
        Ok(true) => true,
        Ok(false) => {
            tracing::warn!("refused commenter update that changes more than comment marks");
            false
        }
        Err(error) => {
            tracing::error!(error = ?error, "refused commenter update: comment check failed");
            false
        }
    }
}