Advanced topic. The protocol is handled transparently by @ManagedService and atmosphere.js. This page documents the wire format for framework integrators or custom client implementations.

The Atmosphere Protocol is a lightweight handshake and message framing layer that works on top of any transport (WebSocket, SSE, long-polling, streaming).

When enableProtocol is true (default), the first message from the server contains metadata:

uuid|heartbeatInterval|heartbeatPaddingChar

Example:

a1b2c3d4-e5f6-7890-abcd-ef1234567890|30|X

The client stores the UUID and uses it for reconnection.

When trackMessageLength is true, messages are prefixed with their length:

<length>|<message>

Example:

42|{"author":"Alice","message":"Hello!","time":1708200000000}

This ensures complete message delivery over streaming and long-polling transports where message boundaries may not be preserved.

The server sends a single character (the heartbeatPaddingChar, default X) at regular intervals to keep connections alive across proxies and load balancers.

The client can also send heartbeats to the server, handled by the @Heartbeat annotation.

The client connects with its preferred transport. If it fails:

1. Client tries transport (e.g., websocket)
2. If connection fails → tries fallbackTransport (e.g., long-polling)
3. Notifies via transportFailure handler
4. On disconnect → auto-reconnects with exponential backoff

disconnected → connecting → connected → reconnecting → connected
                                     ↘ closed
                                     ↘ error

Client                          Server
  │                               │
  ├──── GET /chat (upgrade) ─────→│  WebSocket handshake
  │                               │
  │←── uuid|30|X ────────────────│  Protocol handshake
  │                               │
  │←── X ────────────────────────│  Heartbeat
  │                               │
  ├──── {"author":"A","msg":"Hi"}→│  Client message
  │                               │
  │←── 35|{"author":"A","msg":"Hi"}│  Broadcast (with length prefix)
  │                               │