Pub/Sub JSON Dialect

The directives and responses used by Pub/Sub sockets are JSON records. Standard HTTP status codes are used to indicate outcomes since their meanings are well known.

General Responses

Catch-all error response

An uncategorized error occurs on the server.

{
  "seq": <client-supplied-unique-integer>,
  "action": "<original-action>",
  "code": 500,
  "message": "Internal Error",
  "details": "<detailed-error-description-which-may-contain-stack-traces>"
}

Invalid format response

The directive was invalid (malformed JSON, bad attributes or types, etc.)

{
  "seq": <client-supplied-unique-integer>,
  "action": "<original-action>",
  "code": 400,
  "message": "Invalid Format",
  "details": "<detailed-error-description-which-may-contain-stack-trace>"
}

Invalid-request response

A request was received without a sequence whose format was invalid.

{
  "action": "invalid-request",
  "code": 400,
  "message": "Invalid Request",
  "details": "<detailed-error-description-which-may-contain-stack-trace>",
  "bad_request": "<the-request-which-was-rejected>"
}

Get the Session UUID

Whether the client sent in a session UUID as part of its authentication payload, or it was assigned a new session UUID automatically, they should be able to fetch it at any time via this directive.

Session-uuid request

{
  "seq": <client-supplied-unique-integer>,
  "action": "session-uuid"
}

Successful response

{
  "seq": <client-supplied-unique-integer>,
  "action": "session-uuid",
  "code": 200,
  "uuid": "<session-uuid>"
}

Subscribe to a Channel

Subscribe request

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscribe",
  "channel": "<channel-name>"
}

Successful subscription response

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscribe",
  "code": 200,
  "channels": [
    <list-of-all-channel-subscriptions>
  ]
}

Incorrect permissions response

A read perm-key was not supplied when the socket was established.

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscribe",
  "code": 401,
  "message": "Not Authorized",
  "details": "You do not have read permissions on this socket, and therefore cannot subscribe to channels."
}

Unsubscribe from a Channel

Unsubscribe request

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe",
  "channel": "<channel-name>"
}

Successful unsubscribe response

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe",
  "code": 200,
  "channels": [
    <list-of-all-channel-subscriptions>
  ]
}

Incorrect permissions response

A read perm-key was not supplied when the socket was established.

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe",
  "code": 401,
  "message": "Not Authorized",
  "details": "You do not have read permissions on this socket. You have been unsubscribed from all channels."
}

Subscription not found response

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe",
  "code": 404,
  "message": "Not Found",
  "details": "You are not subscribed to the specified channel."
}

Unsubscribe from All Channels

Unsubscribe-all request

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe-all"
}

Successful unsubscribe-all response

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe-all",
  "code": 200,
  "channels": [
    <list-of-all-prior-channel-subscriptions>
  ]
}

The channels field is the list of channels to which this client was subscribed before the unsubscribe-all directive was sent.

Incorrect permissions response

A read perm-key was not supplied when the socket was established.

{
  "seq": <client-supplied-unique-integer>,
  "action": "unsubscribe-all",
  "code": 401,
  "message": "Not Authorized",
  "details": "You do not have read permissions on this socket. You have been unsubscribed from all channels."
}

List All Subscriptions

Subscriptions listing request

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscriptions"
}

Successful subscriptions listing response

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscriptions",
  "code": 200,
  "channels": [
    <list-of-all-channel-subscriptions>
  ]
}

Incorrect permissions response

A read perm-key was not supplied when the socket was established.

{
  "seq": <client-supplied-unique-integer>,
  "action": "subscriptions",
  "code": 401,
  "message": "Not Authorized",
  "details": "You do not have read permissions on this socket, and therefore cannot list subscriptions."
}

Publish a Message

Publish request

Publish requests are limited to 64KiB. Any request larger will result in the termination of the websocket connection.

{
  "seq": <client-supplied-unique-integer>,
  "action": "pub",
  "chan": "<channel-name>",
  "msg": "<message-body>",
  "ack": <boolean>
}

Publish acknowledgement

Only supplied if the publish request contained an ack parameter set to true

{
  "seq": <client-supplied-unique-integer>,
  "action": "pub",
  "code": 200,
  "id": "<message-uuid>"
}

Incorrect permissions response

A write perm-key was not supplied when the socket was established.

{
  "seq": <client-supplied-unique-integer>,
  "action": "pub",
  "code": 401,
  "message": "Not Authorized",
  "details": "You do not have write permissions on this socket, and therefore cannot publish to channels."
}

No subscriptions response

{
  "seq": <client-supplied-unique-integer>,
  "action": "pub",
  "code": 404,
  "message": "Not Found",
  "details": "There are no subscribers to the specified channel, so the message could not be delivered."
}

Message Format

Messages delivered to subscribers have the following format:

{
  "id": "<message-uuid>",
  "action": "msg",
  "time": "<iso-8601-timestamp>",
  "chan": "<channel-name">,
  "msg": "<message-body">
}