v0.24.0

This release has some adjustments required for Centrifugo v4.

Please take a look at example below which emphasizes the important migration step of your server-side code regarding join/leave messages.

We are not switching to client protocol v2 here yet (in v0.23.0 we mentioned it could be the part of the next minor release, but turned out we need an additional intermediate step before we can do the switch).

• change subscribe option names to be more meaningful
• support asking for join/leave messages from the client side
• send initial ping with random delay in client protocol v2 to smooth syscalls (and thus a CPU usage) after a massive reconnect scenario
• make client.handleCommand public (client.HandleCommand) to have a possibility to handle protocol commands when decoding happens on Transport layer
• fix SSEHandler default max body size (used in case of POST requests)

The important thing is that SubscribeOptions now have 2 flags related to join/leave messages: SubscribeOptions.EmitJoinLeave and SubscribeOptions.PushJoinLeave. This means the program like this:

client.OnSubscribe(func(e centrifuge.SubscribeEvent, cb centrifuge.SubscribeCallback) {
	cb(centrifuge.SubscribeReply{
		Options: centrifuge.SubscribeOptions{
			JoinLeave: true,
		},
	}, nil)
})

Must be replaced with this code to inherit the previous behavior:

client.OnSubscribe(func(e centrifuge.SubscribeEvent, cb centrifuge.SubscribeCallback) {
	cb(centrifuge.SubscribeReply{
		Options: centrifuge.SubscribeOptions{
			EmitJoinLeave:     true,
			PushJoinLeave:     true,
		},
	}, nil)
})

I.e. we tell Centrifuge that it should emit join/leave messages for a particular channel subscription, and it should send (push) join/leave messages to this particular client connection. The same applies to server-side subscriptions also, see how we adopted our own examples in repo in #233 where the change was introduced.

gorelease -base v0.23.1 -version v0.24.0
# github.com/centrifugal/centrifuge
## incompatible changes
SubscribeOptions.JoinLeave: removed
SubscribeOptions.Position: removed
SubscribeOptions.Presence: removed
SubscribeOptions.Recover: removed
WithJoinLeave: removed
WithPosition: removed
WithPresence: removed
WithRecover: removed
## compatible changes
(*Client).HandleCommand: added
SubscribeEvent.JoinLeave: added
SubscribeOptions.EmitJoinLeave: added
SubscribeOptions.EmitPresence: added
SubscribeOptions.EnablePositioning: added
SubscribeOptions.EnableRecovery: added
SubscribeOptions.PushJoinLeave: added
WithEmitJoinLeave: added
WithEmitPresence: added
WithPositioning: added
WithPushJoinLeave: added
WithRecovery: added

# summary
v0.24.0 is a valid semantic version for this release.

v0.23.1

• Fix emitting Join message in Client.Subscribe call, #231.

v0.23.0

This release is a work concentrated around two main things:

• More work on client protocol v2. This should become part of Centrifugo v4. New SDKs which work over new protocol and have new API will be soon released. SDKs will behave according to client SDK API spec. Probably in next major release of Centrifuge we will switch using protocol v2 by default. For now things should be backwards compatible with current protocol.
• Introducing our own EXPERIMENTAL bidirectional emulation layer using HTTP-streaming and EventSource transports. There are a couple of examples which demonstrate how to use it. Examples located in _examples/experimental directory (they require new centrifuge-js SDK served locally from v3_dev branch). The important thing about our emulation implementation is that it does not require sticky sessions on load balancer in distributed case. This should be a more lightweight alternative to SockJS, and the cool thing is that our new Javascript SDK will be able to automatically fallback to HTTP-based transports in case of problems with WebSocket connection. More information will be available soon upon Centrifugo v4 release.

Lots of changes here but in most cases it should be straightforward to adapt. Don't hesitate to reach out with questions in community chat rooms.

Some important release highlights:

• DefaultConfig removed, use Config{} as a starting point. I.e. centrifuge.New(centrifuge.Config{}) is equivalent to centrifuge.New(centrifuge.DefaultConfig).
• We are avoiding using pointers for Disconnects. We got rid of nil Disconnect inside OnDisconnect callback when connection closing was not forced by a server. Where we previously had nil we now always have DisconnectConnectionClosed. This should make library usage more safe and better describes the reason of disconnection.
• Refactor unsubscribe reasons, make unsubscribe first-class citizen with unsubscribe codes.
• Introducing Temporary flag for Error to indicate temporary errors to a client. This allows making Subscriptions more resilient in client protocol v2 - subscriptions will re-subscribe automatically upon receiving temporary errors.
• There are updated rules in code numbers used for errors, unsubscribes and disconnects. This allows splitting code number space and avoid code overlap. While these rules may be tricky to follow – we believe that in most cases library users do not deal with them a lot in application code:
  • For errors: error codes must be in range [0, 1999]. Codes [0, 99] are reserved for client-side errors. Codes [100, 399] are reserved for Centrifuge library internal usage. So applications must use codes in range [400, 1999] when creating custom errors.
  • For unsubscribe codes: codes must be in range [2000, 2999]. Unsubscribe codes >= 2500 coming from server to client result into resubscribe attempt in client protocol V2. Codes [2000, 2099] and [2500, 2599] are reserved for Centrifuge library internal usage. In client protocol v2 we are making Subscriptions to behave isolated from Connection. For example, some individual subscriptions can expire, but it does not result into connection close, only that individual Subscription will re-subscribe if required.
  • For disconnect codes: codes must be in range [3000, 4999]. Codes [3000, 3999] are reserved for Centrifuge library internal usage. Upon receiving disconnect code in range [3000, 3499] or [4000, 4499] client won't reconnect to a server. Splitting disconnect codes to ranges allows getting rid of sending JSON-encoded data in WebSocket CLOSE frame in client protocol v2. Thus – less network traffic and more lightweight disconnection process.
• OnStateSnapshot callback for connection to return Client current state to the external code, useful for connection introspection. This is EXPERIMENTAL and a subject to change.
• Remove an unnecessary lock - #230

As you can see many changes in this release are concentrated around making library more strict in some aspects, this is a part of standardization and unifying client protocol and SDK API/behavior we want to achieve.

❯ gorelease -base v0.22.2 -version v0.23.0
# github.com/centrifugal/centrifuge
## incompatible changes
(*Client).Disconnect: changed from func(*Disconnect) to func(...Disconnect)
(*Client).Unsubscribe: changed from func(string) error to func(string, ...Unsubscribe)
DefaultConfig: removed
DisconnectBadRequest: changed from *Disconnect to Disconnect
DisconnectChannelLimit: changed from *Disconnect to Disconnect
DisconnectConnectionLimit: changed from *Disconnect to Disconnect
DisconnectEvent.Disconnect: changed from *Disconnect to Disconnect
DisconnectExpired: changed from *Disconnect to Disconnect
DisconnectForceNoReconnect: changed from *Disconnect to Disconnect
DisconnectForceReconnect: changed from *Disconnect to Disconnect
DisconnectInsufficientState: changed from *Disconnect to Disconnect
DisconnectInvalidToken: changed from *Disconnect to Disconnect
DisconnectNoPong: changed from *Disconnect to Disconnect
DisconnectNormal: removed
DisconnectServerError: changed from *Disconnect to Disconnect
DisconnectShutdown: changed from *Disconnect to Disconnect
DisconnectSlow: changed from *Disconnect to Disconnect
DisconnectStale: changed from *Disconnect to Disconnect
DisconnectSubExpired: changed from *Disconnect to Disconnect
DisconnectWriteError: changed from *Disconnect to Disconnect
Error.Error: removed
Hub: old is comparable, new is not
Transport.Close: changed from func(*Disconnect) error to func(Disconnect) error
TransportInfo.Emulation: added
UnsubscribeEvent.Reason: removed
UnsubscribeReason: removed
UnsubscribeReasonClient: removed
UnsubscribeReasonDisconnect: removed
UnsubscribeReasonServer: removed
WithDisconnect: removed
## compatible changes
(*Client).OnStateSnapshot: added
(*Client).StateSnapshot: added
(*Disconnect).CloseText: added
(*Hub).Connections: added
Disconnect.Error: added
Disconnect.String: added
DisconnectConnectionClosed: added
DisconnectEvent.Code: added
DisconnectEvent.Reason: added
DisconnectEvent.Reconnect: added
EmulationConfig: added
EmulationHandler: added
Error.Temporary: added
HTTPStreamConfig: added
HTTPStreamHandler: added
NewEmulationHandler: added
NewHTTPStreamHandler: added
NewSSEHandler: added
SSEConfig: added
SSEHandler: added
StateSnapshotHandler: added
SubscribeEvent.Positioned: added
SubscribeEvent.Recoverable: added
Unsubscribe.String: added
Unsubscribe: added
UnsubscribeCodeClient: added
UnsubscribeCodeDisconnect: added
UnsubscribeCodeExpired: added
UnsubscribeCodeInsufficient: added
UnsubscribeCodeServer: added
UnsubscribeEvent.Code: added
UnsubscribeEvent.Unsubscribe: added
WithCustomDisconnect: added
WithCustomUnsubscribe: added

# summary
v0.23.0 is a valid semantic version for this release.

v0.22.2

• Bump dependencies.

UPD.: jumped over a minor version occasionally - this had to be v0.21.2...

v0.21.1

• Fix regression of v0.21.0: periodic stream position check was off due to missing zero value in Config.

v0.21.0

• It's now possible to use Config directly when creating new Centrifuge Node, without using DefaultConfig which is now deprecated.
• Removed some constants with default values, added better comments which reflect zero value behavior - no need to jump to const definition when reading code/docs.
• Some allocation optimizations in WebSocket disconnect process.
• Continue working on ProtocolVersion2 – introducing application-level server-to-client pings. This is still EXPERIMENTAL at the moment and may be changed in later releases. #224

gorelease -base v0.20.0 -version v0.21.0
# github.com/centrifugal/centrifuge
## incompatible changes
DefaultWebsocketMessageSizeLimit: removed
DefaultWebsocketPingInterval: removed
DefaultWebsocketWriteTimeout: removed
TransportInfo.AppLevelPing: added
## compatible changes
AppLevelPing: added
DisconnectNoPong: added
SockjsConfig.AppLevelPingInterval: added
SockjsConfig.AppLevelPongTimeout: added
WebsocketConfig.AppLevelPingInterval: added
WebsocketConfig.AppLevelPongTimeout: added
WebsocketConfig.PongTimeout: added

# summary
v0.21.0 is a valid semantic version for this release.

v0.20.0

• Support client protocol v2. As of v0.20.0 it's considered experimental and can have some adjustments in the following releases. But the plan is to make it default at some point. The initial motivation described in #217 and implementation is in #218. Client connectors which support client protocol v2 will be released soon. Both WebsocketConfig and SockjsConfig now have an option to set default protocol version handler will expect from connecting clients. It's also possible to override that option by using cf_protocol_version URL parameter (v1 or v2) when connecting to the server. This should provide a way to migrate to new protocol gradually.
• Refactor disconnect semantics for client protocol v2. We are getting rid of JSON in close reason by introducing strict ranges for disconnect codes - see #221. Client connectors will expose disconnect codes when working with client protocol v2. Client-side disconnect reasons will also have its own codes – according to this comment.
• Various optimizations in message broadcast, client command handling, client initial connect – fewer things now escape to the heap.
• TransportWriteEvent.IsPush field is removed (we can discuss putting it back later if required).
• Node Survey API now allows choosing the node to which we want to send survey request.
• Warn log level introduced between Info and Error.
• Publication now has Tags field (map[string]string) – this may help to put some useful info into publication without modifying payload. It can help to avoid processing payload in some scenarios.
• Support for setting auth user in Redis shard configuration – for Redis itself and for Sentinel. This is useful if ACL-based auth used on Redis side.

gorelease -base v0.19.0 -version v0.20.0
# github.com/centrifugal/centrifuge
## incompatible changes
(*Disconnect).CloseText: changed from func() string to func(ProtocolVersion) string
(*Node).Survey: changed from func(context.Context, string, []byte) (map[string]SurveyResult, error) to func(context.Context, string, []byte, string) (map[string]SurveyResult, error)
LogLevelError: value changed from 4 to 5
PublishOptions: old is comparable, new is not
PublishReply: old is comparable, new is not
TransportInfo.ProtocolVersion: added
TransportWriteEvent.IsPush: removed
## compatible changes
LogLevelWarn: added
ProtocolVersion1: added
ProtocolVersion2: added
ProtocolVersion: added
Publication.Tags: added
PublishOptions.Tags: added
RedisShardConfig.SentinelUser: added
RedisShardConfig.User: added
SockjsConfig.ProtocolVersion: added
WebsocketConfig.ProtocolVersion: added
WithTags: added

# summary
v0.20.0 is a valid semantic version for this release.

v0.19.0

• JSON protocol performance improvements. See #215 for details. We are now more strict in parsing multiple command frames: in a multiple command JSON frame individual Commands must be separated by exactly one new line symbol and have an optional new line after the last command. This was always this way and current client connectors work according to these requirements – but since the parser becoming more strict this can theoretically cause some problems with third-party connector implementations.
• Support custom data from a client passed in a subscribe command, this data is then available in SubscribeEvent.

gorelease -base v0.18.9 -version v0.19.0
# github.com/centrifugal/centrifuge
## incompatible changes
SubscribeEvent: old is comparable, new is not
## compatible changes
SubscribeEvent.Data: added

# summary
v0.19.0 is a valid semantic version for this release.

v0.18.9

• Add unsubscribe Reason and optional Disconnect to UnsubscribeEvent. See issue #211 and pr #213.

gorelease -base v0.18.8 -version v0.18.9
# github.com/centrifugal/centrifuge
## compatible changes
UnsubscribeEvent.Disconnect: added
UnsubscribeEvent.Reason: added
UnsubscribeReason: added
UnsubscribeReasonClient: added
UnsubscribeReasonDisconnect: added
UnsubscribeReasonServer: added

# summary
v0.18.9 is a valid semantic version for this release.

v0.18.8

• Fix subscription cleanup on client close. Pull request with a fix.