Skip to content

Instantly share code, notes, and snippets.

@izhar

izhar/SigServ WS API.md

Created May 22, 2013 10:58
Show Gist options
  • Save izhar/5626764 to your computer and use it in GitHub Desktop.
Save izhar/5626764 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
SigServ WS API.md

It is recommeded to read the 'Introduction' section in rest_api.md before continuing here.

Websockets Connection URL

It is possible to connect to sigserv websockets with three URLs:

  • ws://HOST:PORT/v1/sub/GID/SID/TID1,TID2,TIDn?clear=0|1&timeout=T&idle_timeout=TI&verbose=0|1&aon=0|1 - Subscribe as GID + SID to topics TID1, TID2, ... TIDn
  • ws://HOST:PORT/v1/sub/GID/SID?clear=0|1&timeout=T&idle_timeout=TI&verbose=0|1&aon=0|1 - Subscribe as GID + SID

Query string parameters:

  • timeout - how long a client can idle before we remove it from sigserv (client_proxy life timeout).
  • idle_timeout - server will send idle message every idle_timeout seconds in order to fool proxies. If set to 0 this is disabled. If this parameter does not appear, a default value is selected.
  • verbose - if set to true, error replies will contain human readable description strings.

The aon parameter is the same as in the subscribe command (see below). The clear parameter is the same as in the subscribe command (see below).

In case a URI for a different version than v1 is given, server will reply with

{"error":"unsupported"}

In case a malformed URI was given, sigserv will reply with

{"error":"bad_request"}

Requests from client to server

Message structure

[TBD: do we remove id?]

Messages are JSON objects with a type ('type' field), a message id ('id' field). Server responses to messages with replies. A reply can be either a successful reply or an error reply. Successful replies are JSON objects with a "result" field containing request result.

Error replies are JSON objects with an "error" field containing request error. If verbose is set to true [via subscribe or via URI] then error replies will also contain an "info" field containing error information as a human readable string. Replies are encapsulated in a josn object with reply type (see Messages From Server).

Send

{
   "type": "send",
   "id":   "1",
   "to":   ["SID1","SID2","SIDn"],
   "raw":  false,
   "msg":  JSONorString
}

Send a message to another subscriber. If sending is done to a SID without a resource, message will be sent to the user for all resources (i.e. if SID is 'ori', then 'ori', 'ori:pc', 'ori:mobile', etc. will get msg).

Fields are:

  • to - list of target subscriber IDs.
  • raw - If true - message will be published as raw (i.e. without JSON envelope with topics and from). Default is false.
  • msg - The message to publish, Cab be JSON object or JSON string.

Possible replies are:

{"result":"ok"}
{"error":"bad_params"}
{"error":"unknown"}
{"error":"throttling"}
{"error":"unauthorized"}

Publish

{
   "type":     "publish",
   "id":       "1",
   "topics":   ["TID1","TID2","TIDn"],
   "raw":      false,
   "msg":      JSONorString,
   "aon":      false
}

Publish a message to a topic. [TBD can this run if the connection does not have sid yet?, is sid separate from pid? I would recommend not]

Fields are:

  • topics - List of topics to publish to.
  • raw - If true - message will be published as raw (i.e. without JSON envelope with topics and from). Default is false.
  • msg - The message to publish, Cab be JSON object or JSON string.
  • aon - Publish to topics subscribed to with AON, will only reach clients that subscribed ALL topics in the publish, not a subset of them.

Possible replies are:

{"result":"ok"}
{"error":"bad_params"}
{"error":"unknown"}
{"error":"throttling"}
{"error":"unauthorized"}

Subscribe

{
   "type":   "subscribe",
   "id":     "1",
   "topics": ["TID1","TID2","TIDn"],
   "clear":  true,
   "aon":    false
}

Subscribe to one or multiple topics.

Fields are:

  • topics - list of topics to which client subscribes
  • clear - set to true if the client also wishes to unsubscribe from all previous topics, false otherwise.
  • aon - Subscribe to topics in All-Or-Nothing mode. This means that if someone sends a publish with aon to these topic, only those who registered to all of them with aon will get it. Note that aon topics will have their own namespace. Note that aon registration to several topics cannot be split among several subscriptions (i.e. if you want to subscribe to T1,T2,T3 in AON, it needs to be done in one request)

Possible replies are:

{"result":"ok"}
{"error":"bad_params"}
{"error":"throttling"}
{"error":"unknown"}

Unsubscribe

{
   "type":   "unsubscribe",
   "id":     "1",
   "topics": ["TID1","TID2","TIDn"],
   "aon":    false
}

Unsubscribe from one or multiple topics. This message can only be used if subscription occured before (either via subscribe JSON or via URI).

Fields are:

  • topics - list of topic IDs to which client unsubscribes
  • aon - Unregister from topics registered to with AON. Note that when unsubscribing from AON topics, you must unsubscribe from the exact set of topics you subscribed to with AON, not a subset.

Possible replies are:

{"result":"ok"}
{"error":"unknown"}

Logout

{
   "type": "logout",
   "id":   "1"
}

Log out subscriber from server.

Possible replies are:

{"result":"ok"}     // this will be followed by a disconnection of websocket session
{"error":"unknown"}

Get Time

Get current UTC time:

{
   "type": "time",
   "id":   "123",
}

with reply:

{"type":"reply","id":"123","reply":{"result":"ok","time":"2011-10-10 21:02:10.286 UTC"}}

Information

TBD: not implemented yet

{
   "type":     "info",
   "id":       "1",
   "key":      "subscriber_list", 
   "key_args": ["CT1"]
}

Get information.

Fields are:

  • key - Determines which information we wish to get for the topic, current allowed keys are topic_subscriber_list or topic_subscriber_count. In the future other keys may be used to access topic metadata (for games, etc).
  • key_args - Some info keys need arguments. The topic_subscriber_list and topic_subscriber_count keys require a topic argument.

Possible replies are:

{"error":"bad_param"}
{"error":"unknown"}
{"error":"unauthorized"}
{"result":["SID1","SID2","SIDn"]} // in response to subscriber_list
{"result":number-of-sids}         // in response to subscriber_count

Responses from server to client

Reply (generic)

{
   "type":   "reply",
   "id":     "1", 
   "reply":  reply-data
}

Encapsulates replies. Fields are:

  • id - id of client message to which we reply
  • reply - the reply itself.

Unknown JSON reply

If a JSON is given which doesn't correspond to any of the above, server will disconnect the client. If verbose was enabled, server will reply with:

{
   "error": "bad_request",
   "info":  "unknown request JSON in websocket",
   "json":  unknown-JSON-request
}

Malformed JSON reply

In case a malformed JSON was sent, server will disconnect the client. If verbose was enabled, server will reply with:

{
   "error": "bad_json", 
   "info":  "Non JSON data sent to server", 
   "data":  non-JSON-string-from-clieint
}

Raw message (published or sent)

In case message was published or sent with raw = true:

{
   "type": "msg",
   "msg":  RawJSONorString
}

Published non-raw message

In case message was published with raw = false (default):

{
   "type": "msg",
   "msg":  {
              "topics": ["TID1","TID2","TIDn"],
              "from":  "SID123",
              "msg":   JSONorString
           }
}

A message was published to a topic(s). Fields are:

  • topics - list of topics to which this message was published
  • from - SID published this message
  • msg - the message itself

Private non-raw message

In case message was published with raw = false (default):

{
   "type": "msg",
   "msg":  {
              "from":  "SID123",
              "msg":   JSONorString
           }
}

A private message was sent to the client. Fields are:

  • from - sender
  • msg - the message itself

Presence message

If subscribed to !TID456 user will start getting presence messages each time somebody subscribed or unsubscribed to/from topic TID456.

For example if user "SID123" subscribed/joined topic "TID456":

{
   "type": "msg",
   "msg":  {
              "type":   "presence",
              "sid":    "SID123",
              "topic":  "TID456",
              "joined": true
           }
}

Or if user "SID123" unsubscribed/left topic "TID456":

{
   "type": "msg",
   "msg":  {
              "type":   "presence",
              "sid":    "SID123",
              "topic":  "TID456",
              "joined": false
           }
}

Idle

{"type": "idle"}

Prevents proxies from terminating websocket connection, should be ignored by client.

Multiple connections

sigserv allows only one connection per SID, if a SID tries to connect twice, the older connection will be disconnected, with a reply message containing {\"error\":\"another_connection\"}.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment