The Ably Realtime service supports client connections over multiple transports. The WebSocket transport is the primary transport for efficient connection by browser clients that are websocket-capable, and any other client environment that offers direct TCP socket access.
The WebSocket transport transmits Protocol Messages in a single WebSocket data frame. In the binary transport, these are sent as binary data frames, with the Protocol Message being encoded with MessagePack encoding. In the text transport these are sent as text data frames containing JSON-encoded ProtocolMessage objects. The protocol definition specifies the content and interpretation of the various protocol messages.
This section defines details that are transport-specific, covering:
Establishment of a WebSocket transport requires that the client makes a WebSocket or secure WebSocket connection to the Ably WebSocket host (realtime.ably.io or a fallback host). The client library must allow the client to specify a non-default host or environment, at least to be able to connect to the sandbox environment at sandbox-realtime.ably.io.
Certain apps may be configured to require TLS connections and will reject non-TLS connections.
The connection URI must be a valid WebSocket URI as specified in https://tools.ietf.org/html/rfc6455#section-3 with an empty path component. The URI must include a valid set of authorization params and a valid set of connection params, each as specified below.
Authorisation params must be either basic authorization params or token authorization params.
Basic auth params:
key (mandatory API key string with name and secret in format NAME:SECRET)Token auth params:
access_token (mandatory token ID)If the library has been initialized with a clientId then the authorization params must include a “client_id” param with the clientId value. In the case of token auth, the token must either have been issued against that clientId or against the wildcard clientId.
Connection params cover protocol mode and recovery mode.
Protocol mode is specified with the protocol param:
protocol; possible values “msgpack” for the binary MessagePack encoding, “json” for the text based JSON encodingThe connection recovery mode is one of “clean”, “resume” or “recover”. Clean mode is the default, and is assumed if no connection params are specified.
Resume or recover mode are specified by including a resume or recover param respectively. In each case the value of that param is the private connectionKey string of the connection that is being recovered.
Resume and recover mode also require a connection_serial param to be specified whose value is the (decimal representation of the) serial number of the last message received.
In the event of a connection failure, the service may respond in two ways.
First, the service may simply refuse the connection and there will be no handshake. The library must report this to the client as a 401 Unauthorized error with no further error information.
Alternatively, the service may accept the WebSocket connection and complete the handshake, and then send an ERROR Protocol Message with further error information, followed by a normal close of the WebSocket connection. In this case the library must report that error information as the reason for connection failure to the client.
At any time after a successful connection, the service may initiate termination of the connection by sending an ERROR message; this might occur for example if the credentials have been revoked, or the account has breached a hard connection limit. If a connection ERROR message is received, the error information must be passed to the client as the failure reason.
Disconnection of the transport, in the case that the client wishes to be able to recover connection state, simply requires the client to perform a normal close on the WebSocket.
Closing the connection, resulting in disposal of connection state, is achieved by sending a CLOSE message. The client should then wait a short period for a CLOSED message, however the client can also simply perform a normal close on the WebSocket.
Abnormal termination for whatever reason (a transition to the failed connection state) again just requires a normal close of the WebSocket.
WebSocket close events that are initiated by the remote end are handled as follows.
A normal close, if the client end had already initiated an explicit CLOSE, are reported to the client as a transition to the closed state once a CLOSED message is received or the connection is closed.
Any other normal close, or a close with one of the following codes:
GOING_AWAY (1001)ABNORMAL_CLOSE (1006)is reported to the client as a transition to the disconnected or the suspended state, depending on whether or not the client has exceeded the suspended timeout.
Any close with any of the following codes:
CLOSE_PROTOCOL_ERROR (1002)REFUSE (1003)NO_UTF8 (1007)POLICY_VALIDATION (1008)TOOBIG (1009)EXTENSION (1010)UNEXPECTED_CONDITION (1011)TLS_ERROR (1015)is reported as a transition to the failed state. The reason code is derived from the reported WebSocket reason code as follows:
REFUSE, POLICY_VALIDATION (0100)TOOBIG (40000)Clients must use the RFC 6455 WebSocket protocol. Browsers that support earlier drafts are accommodated by the service based on specific knowledge of the state of those browser’s conformance to a particular draft; the Ably service does attempt to comply with any draft other than the RFC.