WebAPI/SimplePush/Protocol: Difference between revisions

Jump to navigation Jump to search

WebAPI/SimplePush/Protocol (view source)

Revision as of 00:35, 3 April 2013

1,200 bytes added ,  3 April 2013
Expand example messages and fix typos
(Undo revision 640755 by Nikhilm (talk))
(Expand example messages and fix typos)
Line 79: Line 79:
After the WebSocket is established, the UserAgent begins communication by
After the WebSocket is established, the UserAgent begins communication by
sending a <tt>hello</tt> message.  The hello message contains the UAID if the
sending a <tt>hello</tt> message.  The hello message contains the UAID if the
UserAgent has one. The UserAgent also transmits the channelIDs it knows so the
UserAgent has one, either generated by the UserAgent for the first handshake or
server may synchronize its state.
returned by the server from an earlier handshake. The UserAgent also transmits
the channelIDs it knows so the server may synchronize its state.


The server is MAY respect this UAID, but it is at liberty to ask the UserAgent
The server is MAY respect this UAID, but it is at liberty to ask the UserAgent
Line 119: Line 120:
   {
   {
     "messageType": "hello",
     "messageType": "hello",
     "uaid": "1234567890",
     "uaid": "fd52438f-1c49-41e0-a2e4-98e49833cc9c",
     "channelIDs": ["r2d2", "c3po"]
     "channelIDs": ["431b4391-c78f-429a-a134-f890b5adc0bb", "a7695fa0-9623-4890-9c08-cce0231e4b36"]
   }
   }


Line 132: Line 133:


; uaid string '''REQUIRED'''
; uaid string '''REQUIRED'''
: If the UserAgent sent no UAID, generate a new one. If the UserAgent send a valid UAID and the PushServer is in sync with the UserAgent, send back the same UAID, otherwise send a new UAID.
: If the UserAgent sent no UAID, generate a new one. If the UserAgent send a valid UAID and the PushServer is in sync with the UserAgent, send back the same UAID, otherwise the PushServer should generate a new UAID.


===== Example =====
===== Example =====


   {
   {
     messageType: “hello”,
     "messageType": "hello",
     uaid: <if not provided by previous call, a new valid one will be generated>
     "uaid": "fd52438f-1c49-41e0-a2e4-98e49833cc9c"
   }
   }


Line 149: Line 150:
The request is considered successful only after a response is received with a status code of 200. On success the UserAgent MUST:
The request is considered successful only after a response is received with a status code of 200. On success the UserAgent MUST:


* Update it's persistent storage based on the response
* Update its persistent storage based on the response
* Notify the application of a successful registration.  
* Notify the application of a successful registration.  
 
* On error, the UserAgent MUST notify the application as soon as possible.
On error, the UserAgent MUST notify the application as soon as possible.


NOTE: The register call is made by the UserAgent on behalf of an application. The UserAgent SHOULD have reasonable timeouts in place so that the application is not kept waiting for too long if the server does not respond or the UserAgent has to retry the connection.
NOTE: The register call is made by the UserAgent on behalf of an application. The UserAgent SHOULD have reasonable timeouts in place so that the application is not kept waiting for too long if the server does not respond or the UserAgent has to retry the connection.
Line 162: Line 162:
;channelID string '''REQUIRED'''
;channelID string '''REQUIRED'''
:A unique identifier generated by the UserAgent, distinct from any existing channelIDs it has registered. It is RECOMMENDED that this is a UUIDv4 token.
:A unique identifier generated by the UserAgent, distinct from any existing channelIDs it has registered. It is RECOMMENDED that this is a UUIDv4 token.
===== Example =====
  {
    "messageType": "register",
    "channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd"
  }


==== PushServer -> UserAgent ====
==== PushServer -> UserAgent ====
Line 177: Line 184:


;pushEndpoint string '''REQUIRED'''
;pushEndpoint string '''REQUIRED'''
: Should be the URL sent to the application by the UserAgent. AppServer's will contact the PushServer at this URL to update the version of the channel identified by channelID.
: Should be the URL sent to the application by the UserAgent. AppServers will contact the PushServer at this URL to update the version of the channel identified by channelID.
 
===== Example =====
 
  {
    "messageType": "register",
    "channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd",
    "status": 200,
    "pushEndpoint": "http://pushserver.example.org/"
  }


=== Unregister ===
=== Unregister ===
Line 213: Line 229:
;channelID string '''REQUIRED'''
;channelID string '''REQUIRED'''
: This is sort of obvious isn't it? :)
: This is sort of obvious isn't it? :)
===== Example =====
  {
    "messageType": "unregister",
    "channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd"
  }


==== PushServer -> UserAgent ====
==== PushServer -> UserAgent ====
Line 225: Line 248:
* 200 - OK. Success. Idempotent: If the PushServer receives a unregister for a non-existent channelID it should respond with success. If the channelID is associated with a DIFFERENT UAID, it MUST NOT delete the channelID, but still MUST respond with success to this UserAgent.
* 200 - OK. Success. Idempotent: If the PushServer receives a unregister for a non-existent channelID it should respond with success. If the channelID is associated with a DIFFERENT UAID, it MUST NOT delete the channelID, but still MUST respond with success to this UserAgent.
* 500 - Internal server error. Database offline or whatever other reason due to which the PushServer could not grant this unregistration. UserAgent SHOULD avoid retrying immediately.
* 500 - Internal server error. Database offline or whatever other reason due to which the PushServer could not grant this unregistration. UserAgent SHOULD avoid retrying immediately.
===== Example =====
  {
    "messageType": "unregister",
    "channelID": "d9b74644-4f97-46aa-b8fa-9393985cd6cd",
    "status": 200
  }


=== Notification ===
=== Notification ===
Line 254: Line 285:
;updates list  '''REQUIRED'''
;updates list  '''REQUIRED'''
:The list contains one or more {"channelID": "id", "version": N } pairs.
:The list contains one or more {"channelID": "id", "version": N } pairs.
===== Example =====
  {
    "messageType": "notification",
    "updates": [{ "channelID": "431b4391-c78f-429a-a134-f890b5adc0bb", "version": 23 }, { "channelID": "a7695fa0-9623-4890-9c08-cce0231e4b36", "version": 42 } ]
  }


==== UserAgent -> PushServer ====
==== UserAgent -> PushServer ====
Line 263: Line 301:
;updates list
;updates list
;The list contains one or more {"channelID": channelID, "version": N} pairs.
;The list contains one or more {"channelID": channelID, "version": N} pairs.
===== Example =====
  {
    "messageType": "ack",
    "updates": [{ "channelID": "431b4391-c78f-429a-a134-f890b5adc0bb", "version": 23 }, { "channelID": "a7695fa0-9623-4890-9c08-cce0231e4b36", "version": 42 } ]
  }


== Synchronization of server and client state ==
== Synchronization of server and client state ==


== Acheiving reliable delivery ==
== Achieving reliable delivery ==


At any time, if the PushServer reaches an inconsistent condition, due to database failure, network failure, or any other reason, it MAY drop all state. It MUST then disconnect all active clients, forcing them to reconnect and begin a handshake to get synchronized.
At any time, if the PushServer reaches an inconsistent condition, due to database failure, network failure, or any other reason, it MAY drop all state. It MUST then disconnect all active clients, forcing them to reconnect and begin a handshake to get synchronized.
Line 272: Line 317:
== Garbage collection ==
== Garbage collection ==


The PushServer MAY perform occassional garbage collection to reduce its disk/memory usage.
The PushServer MAY perform occasional garbage collection to reduce its disk/memory usage.
UserAgents that have not contacted the PushServer for a long period of time (a few days. TODO decide minimum) are eligible for garbage collection.
UserAgents that have not contacted the PushServer for a long period of time (a few days. TODO decide minimum) are eligible for garbage collection.
To do this, the PushServer simply deletes the UAID and all associated ChannelIDs and other associated data (including versions and Endpoints).
To do this, the PushServer simply deletes the UAID and all associated ChannelIDs and other associated data (including versions and Endpoints).
Line 284: Line 329:
== Alternative communication ==
== Alternative communication ==


In environments or devices where maintaining an always alive WebSocket is difficult, UserAgents and PushServer's MAY implement alternative means to notify UserAgents about updates. This out of band notification SHOULD be restricted to request the UserAgent to establish the WebSocket. SimplePush state SHOULD NOT be transmitted out of band, since reliable delivery may not be guaranteed.
In environments or devices where maintaining an always alive WebSocket is difficult, UserAgents and PushServers MAY implement alternative means to notify UserAgents about updates. This out of band notification SHOULD be restricted to request the UserAgent to establish the WebSocket. SimplePush state SHOULD NOT be transmitted out of band, since reliable delivery may not be guaranteed.
Cpeterson
Confirmed users
3,339

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/643511"

Navigation menu