protocol.md

Handshake

The handshake is required before any requests can be served. If the first message sent cannot be parsed as a handshake, the connection will be dropped. The handshake will be used to associate the client with a specific user (and set of security rules) on the server. This should be extensible in the same way as #12.

For now let's just leave this a placeholder, since we haven't gotten to authentication yet.

Handshake Request

{
  "request_id": <NUMBER>,
  "method": "unauthenticated" | "anonymous" | "token",
  "token": <STRING>,
}

• request_id is a number uniquely identifying this request, it will be returned in the response.
• method designates the type of authentication to be performed.
  • unauthenticated performs no further steps and will not associate the connection with any user.
  • anonymous will create a new account with no external authentication provider.
  • token will associate the connection with the user in the horizon access token provided.
• token is the horizon access token that the client must already possess.
  • This field is required when method is token, and invalid otherwise.

Handshake Response

{
  "request_id": <NUMBER>,
  "token": <STRING>
}

• token is the horizon access token that is associated with this connection.
  • This token may be used to establish new connections under the same user account until the token expires.

Handshake Error Response

{
  "request_id": <NUMBER>,
  "error": <STRING>,
  "error_code": <NUMBER>
}

Requests

All requests match the following pattern:

{
  "request_id": <NUMBER>,
  "type": <STRING>,
  "options": <OBJECT>
}

• request_id is a number uniquely identifying this request, it will be returned in any responses
• type is the endpoint for the query - one of query, subscribe, store_error, store_replace, update, or remove.
• options is an object structured differently for each endpoint.

query, subscribe

{
  "request_id": <NUMBER>,
  "type": "query" | "subscribe",
  "options": {
    "collection": <STRING>,
    "order": [ <ARRAY>, "ascending" | "descending"],
    "above": [ <OBJECT>, "open" | "closed" ],
    "below": [ <OBJECT>, "open" | "closed" ],
    "find": <OBJECT>,
    "find_all": [<OBJECT>, ...],
    "limit": <NUMBER>,
  }
}

• collection describes which table to operate on in the horizon database.
• order orders the results according to an array of fields - optional.
  • The first argument is an array of field names, most-significant first.
  • The second argument determines which direction the results are sorted in.
• above and below are arrays describing the boundaries regarding order - optional.
  • above and below can only be specified if order is provided.
  • The first argument is an object whose key-value pairs correspond to fields in order.
  • The second argument should be closed to include the boundary, and open otherwise.
• find returns one object in collection that exactly matches the fields in the object given - optional.
  • find cannot be used with find_all, order, above, or below.
• find_all is an array of objects whose key-value pairs correspond to keys in index - optional.
  • Returns any object in collection that exactly matches the fields in any of the objects given.
  • find_all cannot be used with find.
  • find_all with multiple objects cannot be used with order, above, or below.
• limit limits the number of results to be selected - optional.

insert, store, upsert, replace, update, remove

{
  "request_id": <NUMBER>,
  "type": "store" | "update" | "upsert" | "insert" | "replace" | "remove",
  "options": {
    "collection": <STRING>,
    "data": [<OBJECT>, ... ]
  }
}

• collection describes which table to operate on in the horizon database
• data is the documents to be written (or removed)
  • data[i].id is required for remove operations, all other fields are optional
  • data[i].id may be omitted in an insert, store, or upsert operations: a new row will be inserted in the collection
• type is the write operation to perform
  • insert inserts new documents, erroring if any document already exists
  • update updates existing documents. It errors if any document does not already exist
  • upsert updates existing documents or inserts them if they do not exist
  • replace replaces existing documents entirely. It errors if any document does not already exist
  • store replaces existing documents entirely, or inserts them if they don't exist.
  • remove removes documents. It will not error if a document does not exist

end_subscription

Tells the horizon server to stop sending data for a given subscription. Data may still be received until the server has processed this and sent a "state": "complete" response for the subscription.

{
  "request_id": <NUMBER>,
  "type": "end_subscription"
}

Keepalive

This is used by the client to perform an empty request to avoid connection interruption.

{
  "request_id": <NUMBER>,
  "type": "keepalive"
}

Responses

Error Response

This can be sent for any request at any time. Once an error response is sent, no further responses shall be sent for the corresponding request_id.

{
  "request_id": <NUMBER>,
  "error": <STRING>,
  "error_code": <INTEGER>
}

• request_id is the same as the request_id in the corresponding request
• error is a descriptive error string
• error_code is a code that can be used to identify the type of error, values TBD

query, subscribe

query and subscribe requests will result in a stream of results from the horizon server to the client. The stream will be an ordered set of messages from the server following the structure below. If an error occurs, the above Error Response structure will be used, and the stream is considered "complete". An Error Response may still be sent even after a successful data response, but not after "state": "complete".

{
  "request_id": <NUMBER>,
  "data": <ARRAY>,
  "state": "synced" | "complete"
}

• request_id is the same as the request_id in the corresponding request
• data is an array of results for the query or subscribe, and may be empty
• state is optional, and indicates a change in the stream of data:
  • synced means that following the consumption of data, the client has all the initial results of a subscribe
  • complete means that following the consumption of data, no more results will be returned for the request

Write responses

store, replace, insert, update, upsert, and remove requests will be given a single response. This may be an Error Response, or:

{
  "request_id": <NUMBER>,
  "data": [ { "id": <DOCUMENT_ID>, "$hz_v$": <DOCUMENT_VERSION> } | { "error": <STRING>, "error_code": <INTEGER> }, ...],
  "state": "complete"
}

• data is an array of objects corresponding to the documents specified in the write (whether or not a change occurred). For inserted documents it will be the id generated by the server as well as the latest version field for the affected document. If an error occurred, there will instead be an error description string and an error code in the object . The items in the array correspond directly to the changes in the request, in the same order.
• state can only be "complete" for write responses

Keepalive

keepalive requests will be given a single response. This will never be an error response unless there is a protocol error.

{
  "request_id": <NUMBER>,
  "state": "complete"
}