wss://relay.materi.dev/collab/document/{document_id}

GET /collab/document/doc_abc123 HTTP/1.1
Host: relay.materi.dev
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: materi-collab-v1
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: materi-collab-v1

┌────────────────┬────────────────┬─────────────────────┐
│ Message Type   │ Sequence ID    │ Payload (protobuf)  │
│ (1 byte)       │ (4 bytes)      │ (variable)          │
└────────────────┴────────────────┴─────────────────────┘

syntax = "proto3";

message Operation {
  string id = 1;
  string document_id = 2;
  string actor_id = 3;
  uint64 timestamp = 4;
  VectorClock vector_clock = 5;
  oneof op_type {
    InsertOp insert = 6;
    DeleteOp delete = 7;
    FormatOp format = 8;
    RetainOp retain = 9;
  }
}

message InsertOp {
  uint32 position = 1;
  string content = 2;
  map<string, string> attributes = 3;
}

message DeleteOp {
  uint32 position = 1;
  uint32 length = 2;
}

message FormatOp {
  uint32 position = 1;
  uint32 length = 2;
  map<string, string> attributes = 3;
}

message RetainOp {
  uint32 length = 1;
}

message VectorClock {
  map<string, uint64> clocks = 1;
}

message PresenceUpdate {
  string user_id = 1;
  string document_id = 2;
  PresenceState state = 3;
  CursorPosition cursor = 4;
  Selection selection = 5;
  uint64 timestamp = 6;
}

message PresenceState {
  bool online = 1;
  bool typing = 2;
  bool focused = 3;
  string activity = 4;  // "editing", "viewing", "idle"
}

message CursorPosition {
  uint32 line = 1;
  uint32 column = 2;
  uint32 offset = 3;
}

message Selection {
  CursorPosition anchor = 1;
  CursorPosition head = 2;
}

message OperationAck {
  string operation_id = 1;
  VectorClock server_clock = 2;
  bool success = 3;
  string error = 4;
}

message ErrorMessage {
  uint32 code = 1;
  string message = 2;
  string details = 3;
  bool recoverable = 4;
}

{
  "type": "operation",
  "id": "op_123456",
  "document_id": "doc_abc123",
  "actor_id": "user_789",
  "vector_clock": {"user_789": 42, "user_456": 38},
  "operation": {
    "insert": {
      "position": 150,
      "content": "Hello, World!",
      "attributes": {"bold": "true"}
    }
  }
}

{
  "type": "presence",
  "user_id": "user_789",
  "document_id": "doc_abc123",
  "state": {
    "online": true,
    "typing": true,
    "focused": true,
    "activity": "editing"
  },
  "timestamp": 1704067200000
}

{
  "type": "cursor",
  "user_id": "user_789",
  "document_id": "doc_abc123",
  "cursor": {
    "line": 10,
    "column": 25,
    "offset": 450
  },
  "selection": {
    "anchor": {"line": 10, "column": 20, "offset": 445},
    "head": {"line": 10, "column": 30, "offset": 455}
  }
}

{
  "type": "heartbeat",
  "timestamp": 1704067200000,
  "client_id": "client_xyz"
}

{
  "type": "sync_request",
  "document_id": "doc_abc123",
  "last_known_clock": {"user_789": 40, "user_456": 35}
}

{
  "type": "operation_broadcast",
  "operation": {
    "id": "op_987654",
    "actor_id": "user_456",
    "vector_clock": {"user_789": 42, "user_456": 39},
    "insert": {
      "position": 200,
      "content": "New text"
    }
  },
  "transformed": true
}

{
  "type": "operation_ack",
  "operation_id": "op_123456",
  "server_clock": {"user_789": 43, "user_456": 39},
  "success": true
}

{
  "type": "presence_broadcast",
  "users": [
    {
      "user_id": "user_456",
      "name": "Alice",
      "avatar_url": "https://...",
      "state": {"online": true, "typing": false, "activity": "viewing"},
      "cursor": {"line": 5, "column": 10, "offset": 200}
    }
  ]
}

{
  "type": "sync_response",
  "document_id": "doc_abc123",
  "content": "Full document content...",
  "vector_clock": {"user_789": 43, "user_456": 39},
  "operations_since": [/* missed operations */],
  "active_users": [/* current collaborators */]
}

{
  "type": "error",
  "code": 4003,
  "message": "Permission denied",
  "details": "User does not have write access to this document",
  "recoverable": false
}

const RECONNECT_CONFIG = {
  initialDelay: 1000,      // 1 second
  maxDelay: 30000,         // 30 seconds
  multiplier: 1.5,
  maxRetries: 10,
  jitter: 0.1              // 10% random jitter
};

function calculateBackoff(attempt) {
  const delay = Math.min(
    RECONNECT_CONFIG.initialDelay * Math.pow(RECONNECT_CONFIG.multiplier, attempt),
    RECONNECT_CONFIG.maxDelay
  );
  const jitter = delay * RECONNECT_CONFIG.jitter * (Math.random() * 2 - 1);
  return delay + jitter;
}

// Server-side heartbeat monitoring
pub struct HeartbeatMonitor {
    last_heartbeat: Instant,
    timeout: Duration,
}

impl HeartbeatMonitor {
    pub fn new() -> Self {
        Self {
            last_heartbeat: Instant::now(),
            timeout: Duration::from_secs(60),
        }
    }

    pub fn record_heartbeat(&mut self) {
        self.last_heartbeat = Instant::now();
    }

    pub fn is_expired(&self) -> bool {
        self.last_heartbeat.elapsed() > self.timeout
    }
}

{
  "type": "error",
  "code": 4001,
  "message": "Authentication failed",
  "details": "JWT token signature verification failed",
  "recoverable": true,
  "retry_after": 5000
}

{
  "type": "error",
  "code": 4006,
  "message": "Rate limit exceeded",
  "details": "Operation rate: 150/sec exceeds limit of 100/sec",
  "recoverable": true,
  "retry_after": 1000
}

┌────────────────┬────────────────┬─────────────────────┐
│ Compression    │ Original Size  │ Compressed Payload  │
│ Flag (1 bit)   │ (4 bytes)      │ (LZ4 compressed)    │
└────────────────┴────────────────┴─────────────────────┘

class CollaborationClient {
  private ws: WebSocket;
  private messageQueue: Message[] = [];
  private vectorClock: VectorClock;
  private reconnectAttempts = 0;

  async connect(documentId: string, token: string): Promise<void> {
    const url = `wss://relay.materi.dev/collab/document/${documentId}`;

    this.ws = new WebSocket(url, ['materi-collab-v1']);
    this.ws.binaryType = 'arraybuffer';

    this.ws.onopen = () => {
      // Send authentication
      this.send({
        type: 'auth',
        token: token
      });
    };

    this.ws.onmessage = (event) => {
      const message = this.decode(event.data);
      this.handleMessage(message);
    };

    this.ws.onclose = (event) => {
      if (event.code === 4002) {
        // Token expired, refresh and reconnect
        this.refreshTokenAndReconnect();
      } else if (this.shouldReconnect(event.code)) {
        this.scheduleReconnect();
      }
    };

    this.startHeartbeat();
  }

  sendOperation(operation: Operation): void {
    operation.vectorClock = this.vectorClock.increment(this.userId);
    this.messageQueue.push(operation);
    this.send({
      type: 'operation',
      ...operation
    });
  }

  private startHeartbeat(): void {
    setInterval(() => {
      this.send({
        type: 'heartbeat',
        timestamp: Date.now(),
        client_id: this.clientId
      });
    }, 30000);
  }
}