Proposed changes

This pull request adopts client Protocol Version 2. The initial motivation described in centrifugal/centrifuge#217 and implementation is in centrifugal/centrifuge#218.

Two important differences in client protocol v2 at the moment are:

• Remove message layering inside Command and Reply messages. Previously we could have 2 nested Raw bytes payloads which could be decoded/encoded based on Reply or Command type. Now we define all fields on top-level. This means protocol frames will be structured differently so client connectors need to support new format.
• In protocol version 2 we change how disconnects behave. See Refactor disconnects – avoid JSON in reason centrifuge#221. We won't use JSON in disconnect reason, reconnect advice will be based on disconnect Code. Client connectors must support this change also.

v2 client protocol framing changes

This comparison demonstrates well what was changed in client protocol definitions for client protocol v2.

v2 client protocol disconnect behavior changes

Client protocol v2 does not use Reconnect field in Disconnect Reason (encoded previously as JSON).

Reconnect advice now depends on disconnect Code. The rules described below.

Disconnect codes in range 0-2999 should not be used by a Centrifugo user. Those are reserved for the client-side and transport specific needs. Codes in range >=5000 should not be used also. Those are reserved by Centrifugo.

Client should reconnect upon receiving code in range 3000-3499, 4000-4499, >=5000. For codes <3000 reconnect behavior can be adjusted for the specific transport.

Codes in range 3500-3999 and 4500-4999 are application terminal codes, no automatic reconnect should be made by a client implementation.

Centrifugo users supposed to use codes in range 4000-4999 for creating custom disconnects in proxy handlers.

Backwards compatibility and migration plan

• In Centrifugo v3 we will adopt Centrifuge library with Protocol v2 support, but will use ProtocolVersion1 by default. This should be fully backwards compatible. Clients will be able to use cf_protocol_version=v2 URL param to tell server that client speaks v2 protocol version.
• In Centrifugo v3 we allow changing handlers to use ProtocolVersion2 by default with "use_client_protocol_v2": true at some point.
• In Centrifugo v4 we will make v2 the default, but still need to support v1 for some time. Users will be able to set "use_client_protocol_v1": true so routes will use v1 by default and existing connectors will work fine. To enable using protocol v2 users can set ?cf_protocol_version=v2 in URL. As soon as all clients migrated to protocol v2 developers can remove option "use_client_protocol_v1": true from the configuration. Since this moment ?cf_protocol_version=v2 may be removed from client connection URLs.
• In Centrifugo v5 we will remove support for protocol v1 by removing use_client_protocol_v1 option.

When this will be shipped

We intend to merge this for Centrifugo v3.2.0. Centrifugo v4 will be released only when all existing client connectors will support client protocol v2. At the moment we have the following PRs:

• Support client protocol v2 centrifuge-js#174
• Support client protocol v2 and new API iteration centrifuge-go#59
• More to come later