Websockets Diff - sociam/indx GitHub Wiki

Basics

Requesting a diff stream to start, where a new frame is returned over the websocket whenever a change is made to the box. Use an action of value diff in all requests.

Diffs can be optionally filtered, by IDs and/or a query. If no filter is applied, all diffs are returned. If IDs are specified, only diff elements about those IDs will be returned. If a query is set, only elements that match that query (either before or after the diff has been performed) will be returned. When IDs and a query are set, diff elements about the either of the IDs or the IDs matched by the query will be returned (i.e. the union of these ID sets).

Fields

  • token - All diff requests must specify an authenticated token (see Websockets/Auth).

NB: A token is tied to a specific box, so a box is never specified in the protocol.

  • diffid - The ID of the diff stream, issued by the start action.

Operations

All diff request frames specify an operation:

  • start - Create a new diff stream, and issues a diffid.

Optionally specify a query and/or ids to filter this diff with.

Responds with fields:

success: true / false (see below).

diffid: A new UUID issued to this ongoing diff request.

respond_to: The value is diff/start.

  • stop - Stop the diff stream (requires diffid).

Responds with fields:

success: true / false (see below).

respond_to: The value is diff/stop.

  • addIDs - Add IDs to the diff stream filter, specifying an array of IDs in the ids field.

  • setIDs - Replace the IDs in the diff stream filter, specifying an array of IDs in the ids field.

  • removeIDs - Remove the IDs from the diff stream filter, specifying an array of IDs in the ids field.

  • setQuery - Set a query to filer the stream, specifying an query string in the query field.

Response operations

  • update - Used in a response back to a client when a diff is to be sent, the payload is the diff itself, includes the diffid so it can be reconciled with the diff that was started.

The field data contains the actual diff.

Errors

In the case of an error, a response with success set to false and with a value in an error field will be sent.