Live Collaboration & Real-time Synchronization

When users open shared documents in Osvauld, the system automatically discovers collaborators and attempts to establish real-time editing sessions. This process enables immediate synchronization of every keystroke while maintaining connection resilience and handling document switching gracefully.

Connection Establishment for Collaboration

When a user opens a shared document, the system triggers a collaborative session setup process that discovers potential collaborators and establishes connections for real-time editing.

Shared User Discovery

The document opening process queries the local database to find all users who have access to the current document, along with their associated devices:

Connection State Categories

The system maintains two distinct categories of peer connections:

Active Connections: Peers currently editing the same document who receive immediate updates for every keystroke and change.

Inactive Connections: Peers who are connected but editing different documents, who receive periodic state synchronization updates.

This categorization enables efficient resource usage by sending real-time updates only to collaborators who need them while maintaining document consistency across all connected peers.

Document Check Protocol

When connections are established, peers must verify whether they’re editing the same document before enabling real-time synchronization. This verification prevents unnecessary real-time updates between peers working on different documents.

Document Verification Process

Document Check Message Flow

The document verification uses a specific message protocol:

DocumentCheck: Sent by the connection initiator with the current resource_id DocumentCheckResponse: Peer responds with is_match boolean and state_vectors if matched StateVectorExchange: If matched, begin immediate CRDT synchronization UpdateExchange: Bidirectional update exchange for state convergence

This protocol ensures that peers only engage in expensive real-time synchronization when they’re actually collaborating on the same document.

Real-time Synchronization

Once peers are categorized as active connections (editing the same document), every change is immediately broadcast to maintain synchronized document states across all collaborators.

Keystroke-Level Collaboration

Real-time Message Types

The system uses specific message types for different aspects of real-time collaboration:

DocumentUpdate: Contains CRDT operations for document content changes, client ID, and document type AwarenessUpdate: Contains cursor position, selection state, and user presence information

Both message types are sent immediately upon local changes and applied directly to peer’s document states, ensuring sub-second synchronization across all active collaborators.

Connection Resilience and Reconciliation

The system includes multiple mechanisms to maintain stable collaboration sessions even when network conditions are poor or connections are temporarily lost.

Periodic Reconciliation

Connection Health Monitoring

The system continuously monitors connection health through:

Message Send Monitoring: Failed message sends immediately trigger reconnection attempts QUIC Connection Status: Regular checks of underlying connection state Timeout Detection: Connections that become unresponsive are marked for recovery

Failed connections are automatically removed from active connection lists and reconnection attempts are made asynchronously, ensuring that temporary network issues don’t disrupt collaboration for other peers.

Document Switching and State Cleanup

When users switch between documents, the system must gracefully handle connection state transitions and ensure all peers receive final synchronization updates before transitioning to new collaboration contexts.

Document Switch Protocol

State Transition Management

During document switching, the system maintains connection state carefully:

Active → Inactive Transition: Active collaborators are notified via DocumentChange messages and automatically moved to inactive status, stopping real-time updates but preserving the connection.

Final Synchronization: Inactive connections receive final state vector synchronization to ensure they have the most recent document state before the user switches away.

Connection Preservation: Established QUIC connections are preserved across document switches, allowing for efficient reconnection when users return to shared documents.

Document Switch Edge Cases

The system handles several edge cases during document switching:

Same Document Switch: If the user “switches” to the same document, the system detects this and skips the cleanup process entirely.

Null Document: When closing all documents, the system clears all connection lists and stops collaboration processes.

Failed Notifications: If DocumentChange notifications fail to send, the system continues with cleanup to prevent hanging in inconsistent states.

Message Protocol Summary

The live collaboration system uses a comprehensive message protocol built on the existing P2P infrastructure:

Core Message Types

pub enum LiveEditMessage {
    DocumentCheck {
        resource_id: String,
    },
    StateVectorExchange {
        resource_id: String,
        state_vectors: String,
    },
    UpdateExchange {
        resource_id: String,
        updates: String,
    },
    UpdateExchangeResponse {
        resource_id: String,
        updates: String,
    },
    NotSameDocument,
    DocumentChange {
        resource_id: String,
    },
    DocumentUpdate {
        updates: Vec<u8>,
        resource_id: String,
        client_id: u32,
        doc_type: String,
    },
    AwarenessUpdate {
        resource_id: String,
        client_id: u32,
        awareness_data: Vec<u8>,
    },
}

Message Flow Patterns

Connection Establishment: DocumentCheck → StateVectorExchange → UpdateExchange → UpdateExchangeResponse

Real-time Collaboration: DocumentUpdate (continuous) + AwarenessUpdate (continuous)

Periodic Reconciliation: StateVectorExchange → UpdateExchange → UpdateExchangeResponse

Document Switching: DocumentChange → connection state transitions

Connection Recovery: Automatic reconnection → DocumentCheck → full synchronization

System Architecture Benefits

This live collaboration architecture provides several key advantages:

Immediate Responsiveness: Keystroke-level synchronization provides Google Docs-like collaboration experience without central servers.

Network Efficiency: Only active collaborators receive real-time updates, while inactive connections use efficient periodic sync.

Connection Resilience: Automatic reconnection and reconciliation ensure collaboration sessions survive network disruptions.

Resource Optimization: Connection state management prevents unnecessary processing and network usage.

Scalable Collaboration: The system supports multiple simultaneous collaboration sessions across different documents with proper resource isolation.

The combination of real-time updates, connection resilience, and efficient state management creates a robust collaborative editing experience that operates entirely through peer-to-peer connections without requiring central coordination servers.