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

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

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.

error

{
    data: ?
}

This message notifies the server that the client encountered a javascript error. The data field can be of any JSON-serializable type. This message should not result in any action or response from the server that will affect the client; it's purely for logging and related functionality. The response to this message will always be true.

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}. The auth association will persist for the duration of the session; if the client needs to deauth it should simply disconnect and reconnect.

passwd

{
    old: String,
    password: String
}

Changes an auth'd user's password. The old field should be the original (unhashed) password for the user, and new should be the new unhashed password. The response value is false if old was incorrect or the client wasn't auth'd; or a string with the new password's hashed version on success.

newpw

{
    email: String
}

Creates a new, autogenerated password for the user with the specified email. If no user with that email address exists, no action is taken. The 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.

query

{
    type: String,
    query: String?,
    sort: String?
    limit: Integer?
    offset: Integer?
}

Runs a query (docs TODO)

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 always be true. 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).

A client can subscribe to presence updates on a single user multiple times with no ill effect.

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).

not

{
    message: String,
    key: String
}

Signals that the client has a new notification. The message field is a short description of the notification, and the key field is the key/id of the relevant object (e.g. listing/d31d1ac8f31f36d22547590c5af32fe6).