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)
 │ │