WebAPI/SimplePush/Protocol: Difference between revisions

Jump to navigation Jump to search

WebAPI/SimplePush/Protocol (view source)

Revision as of 22:29, 25 March 2013

117 bytes added ,  25 March 2013
Undo revision 640755 by Nikhilm (talk)
(remove web facing versions)
(Undo revision 640755 by Nikhilm (talk))
Line 27: Line 27:
;ChannelID
;ChannelID
:Unique identifier for a Channel. Generated by UserAgent for a particular application. Opaque identifier for both UserAgent and PushServer. This MUST NOT be exposed to an application.
:Unique identifier for a Channel. Generated by UserAgent for a particular application. Opaque identifier for both UserAgent and PushServer. This MUST NOT be exposed to an application.
;Version
:Version or Sequence Number is used between the PushServer and the UserAgent to ensure reliable acknowledgement of notifications delivered to the UserAgent. It is not exposed to the client JavaScript API nor to the Application Server. It is a 64-bit monotonically increasing number.


;Endpoint
;Endpoint
;A REST-ful HTTP URL uniquely associated to a channel. Requests to this URL should update the PushServer state for the channel. MUST be exposed to applications.
;A REST-ful HTTP URL uniquely associated to a channel. Requests to this URL should update the PushServer state for the channel. MUST be exposed to applications.
;Version
Monotonically increasing 64-bit integer describing the application state. This
holds meaning as a primary key or similar only to the AppServer. The PushServer
and UserAgent and App should use this only for detecting changes. MUST be exposed to applications.


;Application
;Application
Line 39: Line 41:
== Protocol Overview ==
== Protocol Overview ==


The SimplePush protocol defines how UserAgents and PushServers communicate to ensure reliable delivery of the latest 'wake up' signal from the AppServer to the UserAgent.
The SimplePush protocol defines how UserAgents and PushServers communicate to ensure reliable delivery of the latest version of a channel from the PushServer to the UserAgent.


The SimplePush communication channel is WebSockets, and the wire protocol is JSON, with messages defined below.
The SimplePush communication channel is WebSockets, and the wire protocol is JSON, with messages defined below.
Line 175: Line 177:


;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 request the App associated with the endpoint to be woken up.
: 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.


=== Unregister ===
=== Unregister ===
Line 222: Line 224:
: Used to indicate success/failure. MUST be one of:
: Used to indicate success/failure. MUST be one of:
* 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 is free to ignore this.
* 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.


=== Notification ===
=== Notification ===
Line 229: Line 231:


The AppServer MUST make a HTTP '''PUT''' request to the Endpoint received from the App.
The AppServer MUST make a HTTP '''PUT''' request to the Endpoint received from the App.
The body of the request MUST be empty.
The body of the request MUST contain the string "version=N" and the Content-Type MUST be <tt>application/x-www-form-urlencoded</tt>.


==== PushServer -> AppServer ====
==== PushServer -> AppServer ====
Line 273: Line 275:
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).
The deletion of the UAID should be done first, and ''atomically''. Other details may be deleted when the server has spare cycles. Now if the UserAgent with said UAID connects to the PushServer, it will be assigned a new UAID, the handshake will occur and Apps on the server will learn the latest version  
The deletion of the UAID should be done first, and ''atomically''. Other details may be deleted when the server has spare cycles. Now if the UserAgent with said UAID connects to the PushServer, it will be assigned a new UAID, the handshake will occur and Apps on the server will learn the latest version (TODO: really need NotifyUnknown!)


The PushServer MUST NOT delete channelIDs without deleting the associated UAID, except when one of the following occurs:
The PushServer MUST NOT delete channelIDs without deleting the associated UAID, except when one of the following occurs:
Nikhilm
Confirmed users
93

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/641285"

Navigation menu