WebSocket Based Changes Feed

Couchbase Lite supports a WebSocket connection to the server's _changes feed. This is an extension of the CouchDB sync API.

WebSocket mode is conceptually the same as continuous mode -- both leave the socket open and send new notifications from the server as changes occur -- but it should avoid issues with proxy servers and gateways that cause continuous mode to fail in many real-world mobile use cases. (The primary problem is buggy HTTP chunked-mode body parsing that buffers up the entire response before sending any of it on; since the continuous feed response never ends, nothing gets through to the client.)

Connecting

The client requests WebSockets by setting the _changes URL's feed query parameter to websocket, and opening a WebSocket connection to that URL:

GET /db/_changes?feed=websocket&since=12345 HTTP/1.1
Connection: Upgrade
Upgrade: websocket
...

(Unfortunately Apache CouchDB does not return an error on such a request, even though it doesn't support WebSockets; instead it just reverts to normal feed. This means a client will have to determine whether the server supports WebSockets before requesting a _changes feed, probably from reading the tea leaves returned by GET /.)

Messages

Once the connection is open, the server sends textual messages. The messages are JSON; each contains one or more change notifications (in the same format as the regular feed) wrapped in an array:

[ {"seq":1022,"id":"beer_Indiana_Amber","changes":[{"rev":"1-e8f6b2e1f220fa4c8a64d65e68469842"}]},
  {"seq":1023,"id":"beer_Iowa_Pale_Ale","changes":[{"rev":"1-db962c6d93c3f1720cc7d3b6e50ac9df"}]}
]

(The current server implementation sends at most one notification per message, but this could change. Clients should accept any number.)

An empty array is a special case: it denotes that at this point the feed has finished sending the backlog of existing revisions, and will now wait until new revisions are created. It thus indicates that the client has "caught up" with the current state of the database.

The websocket mode behaves like the continuous mode: after the backlog of notifications is sent, the connection remains open and new notifications are sent as they occur.