Protocol

HS Protocol

The protocol is asymmetrical.

Message Format

Messages are sent as UTF-8, and formatted as follows:

[type]:[data]

Where type is a string matching [a-z\-], and data is an optional JSON data structure. If data is not present the separating : is optional.

Client Messages

All client messages contain the id field in the data, set to an integer. As such, every client message must include data.

Every client message will receive a response with a return value, formatted like so:

response:{"id": [original client message id], "value": [response value]}

See response at the bottom of this page for details.

auth

{
    email: String,
    ?password: String
}

Attempts to authorize the client. The email field should contain the user's email address. If they haven't auth'd before, an account will be created for them and a password (salted and hashed; see below) returned in the response; the password field should not be present for this case. If the user has auth'd previously and the password field is missing or is not set to SHA256(password + email), the response value will be false. If the user has auth'd previously, and the password field is correct and present, the response value will be true and the user will be authenticated.

deauth

{
    //nothing (except the mandatory `id` field)
}

De-authenticates the client, if it has successfully auth'd during this connection. Response value is always true.

sub

{
    key: String
}

Subscribes on a key. The response value will contain the contents of the object, if it exists, and false otherwise. Until unsub is sent with this key, the server will begin pushing data changes on that key.

A key may be subscribed to multiple times with no ill effects (well, aside from wasting a bit of time).

unsub

{
    key: String
}

Unsubscribes on a key. If the client wasn't already subscribed to the key, the response value will be false. If the client was subscribed to the key, the response value will be true, and the client will no longer be subscribed or receive changes on that key.

create

{
    type: String,
    data: Object
}

Creates of new object of the specified type, containing data. The response value will be false if there was a validation error, or the ID of the new object on success. Note that the data itself may not be stored in the new object verbatim -- think of create as more of a constructor rather than an insert operation.

This message will not result in a subscription to the object. If the client requires access to the newly-created object it should call sub with the returned ID.

update

{
    key: String,
    diff: Object
}

Applies the diff to the object. The response value will be true if the update was successful, or false if it failed. As with create, data in the actual object may not be set exactly as was in the diff. Clients subscribed to the object being updated should not apply the diff to the object, but instead wait for the appropriate publish message from the server.

Server Messages

response

{
    id: String,
    value: ?
}

This message is sent in response to every client message. The field id is set to the ID of the original message sent by the client, and value is the resulting return value -- its type will depend on the original message.

Note that there are two reserved values for value, used for error handling: "error-validation" and "error-server". The former specifies an issue with the contents of a message's data, and the latter indicates that a server error occurred.

pub

{
    key: String,
    diff: Object
}

Notifies the client that one of the objects its subscribed to (identified by key) has changed. The diff object should be applied to the object to update it.