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 only one notification per message, but this could change. Clients should accept any number.)

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.