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.

ping

ping will cause a response message to be returned, but otherwise has no effects. It is useful to test if a connection is functioning correctly.

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

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 the auth attempt will succeed; 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 auth attempt will succeed.

If the auth succeeded, the return value will be {password: String, userid: String}.

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.

delete

{
    key: String
}

Deletes the object with the specified key. The response value will always be true.

sub-presence

{
    user: String
}

Subscribes to presence updates for the specified user. The response value will be false if the client is already subscribed on this presence, or true otherwise. If the specified user doesn't exist, the presence subscription will still occur. The user's initial presence, and all subsequent presence updates, will be pushed to the client via presence messages (described below).

unsub-presence

{
    user: String
}

Unsubscribes to presence updates for the specified user. The response value will always be true.

Server Messages

response

{
    id: String,
    value || error: ?
}

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.

If there was an error when processing this message, the value field will not be present, and instead the response will contains the error field, which contains error information.

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.

presence

{
    user: String,
    state: Integer
}

Notifies the client that a user it subscribed to for presence notifications has had a change of presence status. The user field is the ID of the appropriate User model, and state is the presence status (0: offline; 1: online, 2: away).