CloudServices/Roadmaps/EditionServer: Difference between revisions
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
<span style="color:red">This is a draft document. It is a work in progress.</span> | <span style="color:red">This is a draft document. It is a work in progress.</span> | ||
<h1><i> | <h1><i>PlaceHolder Server</i></h1> | ||
==Overview== | ==Overview== | ||
Provide a service to allow Third Party Application servers to notify their Web Apps that an event has occurred and action may be required, without requiring a web page to be constantly present and connected to the Third Party Application Server. The Editon Server provides best effort to notify Apps of a version update, however delivery is not guaranteed. | Provide a service to allow Third Party Application servers to notify their Web Apps that an event has occurred and action may be required, without requiring a web page to be constantly present and connected to the Third Party Application Server. The Editon Server provides best effort to notify Apps of a version update, however delivery is not guaranteed. | ||
===Why " | ===Why "PlaceHolder Server"?=== | ||
placeholder is a temporary name while this document is being edited in order to prevent Wiki conflicts. | |||
In order to scale easily, a system should require the least amount of data necessary. While it would be ideal that there be no data exchanged, we realized that having a tiny amount would not alter the overall design or change the desired behaviors. | In order to scale easily, a system should require the least amount of data necessary. While it would be ideal that there be no data exchanged, we realized that having a tiny amount would not alter the overall design or change the desired behaviors. | ||
| Line 21: | Line 23: | ||
In addition, an App Server may wish to notify an App of an event or action and not be able to send a message directly to the App or device. | In addition, an App Server may wish to notify an App of an event or action and not be able to send a message directly to the App or device. | ||
To accomplish this, App Servers can send Version Events to Apps. A Version event is a simple, fire and forget "ping" style event that the | To accomplish this, App Servers can send Version Events to Apps. A Version event is a simple, fire and forget "ping" style event that the PlaceHolder Server will make a best effort to deliver to the App. | ||
There are a few Caveats that should be stated: | There are a few Caveats that should be stated: | ||
| Line 33: | Line 35: | ||
==Use Cases== | ==Use Cases== | ||
<b>An App wishes to be notified when new email arrives</b>. A User installs an <i>App</i> on a mobile device which notifies her when someone adds a note to her bulletin board. The <i>App</i> calls the Registration function, which returns an <i>EndPoint</i>. The <i>App</i> sends the <i>EndPoint</i> to the <i>AppServer</i> using the magic of "Not-Part-Of-This-Protocol". The <i>AppServer</i> stores the <i>EndPoint</i> in the User's information. When a new note is added, the <i>AppServer</i> fetches the <i>EndPoint</i> and PUTs a new version value to it. This alerts | <b>An App wishes to be notified when new email arrives</b>. A User installs an <i>App</i> on a mobile device which notifies her when someone adds a note to her bulletin board. The <i>App</i> calls the Registration function, which returns an <i>EndPoint</i>. The <i>App</i> sends the <i>EndPoint</i> to the <i>AppServer</i> using the magic of "Not-Part-Of-This-Protocol". The <i>AppServer</i> stores the <i>EndPoint</i> in the User's information. When a new note is added, the <i>AppServer</i> fetches the <i>EndPoint</i> and PUTs a new version value to it. This alerts PlaceHolderServer Client, which wakes the <i>App</i> and sends a version event via a registered callback. This causes the <i>App</i> to refresh it's messages (again using the magical "Not-Part-Of-This-Protocol" system), and User gets a screen full of adorable kittens. | ||
<b>An AppServer wishes to notify Apps of an update</b>. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an <i>App</i> registers with | <b>An AppServer wishes to notify Apps of an update</b>. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an <i>App</i> registers with PlaceHolderServer, gets an <i>EndPoint</i> which it relays to <i>AppServer</i>. <i>AppServer</i> then PUTs a '000' version to the <i>EndPoint</i> which triggers an "update" event for the App, which silently acknowledges that all is well. At some later time, <i>AppServer</i> PUTs '001' to the <i>EndPoint</i> which PlaceHolderServer relays to <i>App</i> which then updates itself using "Not-Part-Of-This-Protocol-Either". | ||
<b>An incoming request from a WebRTC </b>. Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call. | <b>An incoming request from a WebRTC </b>. Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call. | ||
| Line 50: | Line 52: | ||
;APP: A possibly third party provided Web Application located on a remote User Agent. The end consumer of VERSION EVENTS. | ;APP: A possibly third party provided Web Application located on a remote User Agent. The end consumer of VERSION EVENTS. | ||
;APPID: A globally unique identifier for a given App. | ;APPID: A globally unique identifier for a given App. | ||
; | ;PLACEHOLDER CLIENT: The application or library that acts as the intermediary between the APP and the PLACEHOLDER SERVER. This provides the APP with VERSION EVENT callbacks. | ||
; | ;PLACEHOLDER SERVER: The application or library that acts as the intermediary between the APP SERVER and the PLACEHOLDER CLIENT. This provides ENDPOINTs for the APP SERVER. | ||
;ENDPOINT: A URL which accepts VERSION updates to trigger eventual APP VERSION EVENT. | ;ENDPOINT: A URL which accepts VERSION updates to trigger eventual APP VERSION EVENT. | ||
;UAID: A globally unique identifier for a given User Agent. | ;UAID: A globally unique identifier for a given User Agent. | ||
;VERSION EVENT: A request from APP SERVER to notify an APP to take action. | ;VERSION EVENT: A request from APP SERVER to notify an APP to take action. | ||
==Requirements== | ==Requirements== | ||
[File: | [File:PlaceHolderServerDiagram.pdf A diagram of the PlaceHolderServer interaction points.] | ||
# APP requests an ENDPOINT from the | # APP requests an ENDPOINT from the PLACEHOLDER CLIENT and shall register two callback functions, one for receipt of the ENDPOINT, and a second for handling of a VERSION EVENT | ||
# If not already present, | # If not already present, PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the UserAgent (UAID) | ||
# | # PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the APP (<abbr title="Previously known as the CHID">APPID</abbr>) | ||
# | # PLACEHOLDER CLIENT shall send UAID, APPID and any additional information required for proprietary KICK to the PLACEHOLDER SERVER | ||
# | # PLACEHOLDER SERVER shall create an ENDPOINT for the UAID and APPID and return it to the PLACEHOLDER CLIENT. | ||
# If a KICK driver is present, | # If a KICK driver is present, PLACEHOLDER SERVER shall relay appropriate PLACEHOLDER CLIENT provided information to the KICK driver. | ||
# | # PLACEHOLDER CLIENT tenders the ENDPOINT to APP via callback. | ||
# APP sends ENDPOINT to the APP SERVER | # APP sends ENDPOINT to the APP SERVER | ||
# On VERSION EVENT, APP SERVER PUTs version value to ENDPOINT | # On VERSION EVENT, APP SERVER PUTs version value to ENDPOINT | ||
# If a | # If a PLACEHOLDER CLIENT is currently connected to APP SERVER, APP SERVER relays an UPDATE containing currently pending VERSION EVENTS. | ||
# If a | # If a PLACEHOLDER CLIENT is NOT currently connected, an optional, proprietary KICK driver may be called to wake devices associated with the corresponding ENDPOINT UAID. | ||
# If a | # If a PLACEHOLDER SERVER is unable to immediately deliver a VERSION EVENT, the VERSION EVENT is logged to short term storage. | ||
# | # PLACEHOLDER CLIENT connects to the PLACEHOLDER SERVER and shall identify a list of one or more UAIDs it is responsible for. | ||
# If there are VERSION EVENTS pending for requested UAIDs, | # If there are VERSION EVENTS pending for requested UAIDs, PLACEHOLDER SERVER sends an UPDATE packet (For this template, italicized names would be replaced by actual values): | ||
{ <i>UAID</i>: { | { <i>UAID</i>: { | ||
{<i>APPID</i>: <i>VERSION</i>}, | {<i>APPID</i>: <i>VERSION</i>}, | ||
... }, | ... }, | ||
... } | ... } | ||
# If no VERSION EVENTS are pending for the requested UAIDs, | # If no VERSION EVENTS are pending for the requested UAIDs, PLACEHOLDER SERVER may return a status indicating no data available (for REST implementations) or simply not return content (for WebSocket) | ||
# During the transmission of the UPDATE, a | # During the transmission of the UPDATE, a PLACEHOLDER SERVER may wish to return a 503 (Service Unavailable) error to APP SERVERS for any VERSION EVENT associated with an in progress UAID, so as to prevent potential race conditions. | ||
# On receipt of UPDATE, | # On receipt of UPDATE, PLACEHOLDER CLIENT shall return an ACK to the PLACEHOLDER SERVER. | ||
# The ACK shall contain a list of UAIDs for which all APPIDs have been properly received. | # The ACK shall contain a list of UAIDs for which all APPIDs have been properly received. | ||
# The | # The PLACEHOLDER SERVER shall then clear APPID version information from short term storage, and re-allow version updates for those UAIDs if currently blocked. | ||
# The | # The PLACEHOLDER CLIENT shall then notify APPs of the VERSION EVENT using the appropriate callback, and passing the VERSION | ||
NOTE: a | NOTE: a PLACEHOLDER RELAY may be created by combining the polling aspects of the PLACEHOLDER CLIENT with the data management and KICK driver of the PLACEHOLDER SERVER. This would allow a VERSION EVENT system to enter protected networks or use restricted means to communicate to USER AGENTs. It is important to note that once a PLACEHOLDER SERVER has received an ACK for a given UAID, the PLACEHOLDER SERVER is under no obligation to retain that data, and proper relay of the VERSION EVENT is the PLACEHOLDER RELAY's problem. | ||
==Get Involved== | ==Get Involved== | ||
Revision as of 16:37, 6 March 2013
This is a draft document. It is a work in progress.
PlaceHolder Server
Overview
Provide a service to allow Third Party Application servers to notify their Web Apps that an event has occurred and action may be required, without requiring a web page to be constantly present and connected to the Third Party Application Server. The Editon Server provides best effort to notify Apps of a version update, however delivery is not guaranteed.
Why "PlaceHolder Server"?
placeholder is a temporary name while this document is being edited in order to prevent Wiki conflicts.
In order to scale easily, a system should require the least amount of data necessary. While it would be ideal that there be no data exchanged, we realized that having a tiny amount would not alter the overall design or change the desired behaviors.
And "Version Control System" had baggage issues of it's own.
Project Contacts
Principal Point of Contact - Doug Turner dougt@mozilla
IRC - #channel
Group Email - TBD
Goals
Apps need to know when something happens on their servers. One way to do that is to poll relentlessly back to their servers. The problem with that is that with each app performing it's own poll, you can wind up with a tremendous amount of traffic, all consisting of "Anything yet?" "Nope."
In addition, an App Server may wish to notify an App of an event or action and not be able to send a message directly to the App or device.
To accomplish this, App Servers can send Version Events to Apps. A Version event is a simple, fire and forget "ping" style event that the PlaceHolder Server will make a best effort to deliver to the App.
There are a few Caveats that should be stated:
- Version Events are lossy.
- A Version Event may expire before reaching the App. (You probably don't care about a traffic accident that happened a week ago.)
- A Version Event may be lost due to intermediary server error.
- The App should reconnect with the App Server in order to provide positive confirmation of an Event, the App Server may retry sending an Event to the App if this confirmation does not occur.
- While best effort will be made to reduce the possibility, an App may receive the same or only slightly different Version Event in rapid succession. It is advised that the App and App Server use a method to only act on the highest Version.
- Version Events, and the information around them are not encrypted. Since this is a low information system, it is strongly encouraged that information that requires security ONLY be exchanged between the App and the App Server using properly secure methods.
- Endpoints may be used to identify individual users. Since the service's role is to alert apps to connect back to the AppServer (and thus expose additional info such as the IP address, MAC, and any account info), it was felt that this is should not surprise users and implementers.
Use Cases
An App wishes to be notified when new email arrives. A User installs an App on a mobile device which notifies her when someone adds a note to her bulletin board. The App calls the Registration function, which returns an EndPoint. The App sends the EndPoint to the AppServer using the magic of "Not-Part-Of-This-Protocol". The AppServer stores the EndPoint in the User's information. When a new note is added, the AppServer fetches the EndPoint and PUTs a new version value to it. This alerts PlaceHolderServer Client, which wakes the App and sends a version event via a registered callback. This causes the App to refresh it's messages (again using the magical "Not-Part-Of-This-Protocol" system), and User gets a screen full of adorable kittens.
An AppServer wishes to notify Apps of an update. Since a server doesn't want to be deluged by millions of pings from devices every hour, the developers wisely decide to opt for a Push mechanism. Much like the other example, an App registers with PlaceHolderServer, gets an EndPoint which it relays to AppServer. AppServer then PUTs a '000' version to the EndPoint which triggers an "update" event for the App, which silently acknowledges that all is well. At some later time, AppServer PUTs '001' to the EndPoint which PlaceHolderServer relays to App which then updates itself using "Not-Part-Of-This-Protocol-Either".
An incoming request from a WebRTC . Bob uses Ringo’s STAR webrtc service. Bob is using the Desktop browser, but the tab/window isn't open to the Ringo service. Alice makes a webrtc call from work to Bob. Bob sees a notification about an incoming call.
Additional potential scenarios to consider
Kenji works at a powerplant located on the Eastern Shore of an island country. He has set up a service that sends him alerts when the wave levels have increased above a certain threshold. His vacation home is located in a section of town supported by only two cell towers, and is constructed using Stucco walls and a steel roof, which greatly impedes the level of signal that he can receive. His phone may be 4G in his living room, but step down to 3g in the hallway, and only 1x in his office. It's rather important that he receive the alerts indicating that wave levels have begun increasing.
Alice is traveling from Brazil to America. An unexpected storm delays her connections forcing her to overnight in a location with no network or cell access. When she lands, she turns on her phone and connects to the first available network that provides data. Unfortunately, this network routes traffic to an authorization server until she agrees to the network terms, then provides minimal connection capacities. While connecting back to her home server, the connection is proxied and limited to only well known TCP ports, slow and routinely drops providing only partial results to the client.
Definitions
- ACK
- An acknowledgement message.
- APP SERVER
- A possibly third party provided server that provides information to the APP. The originator of VERSION EVENTS.
- APP
- A possibly third party provided Web Application located on a remote User Agent. The end consumer of VERSION EVENTS.
- APPID
- A globally unique identifier for a given App.
- PLACEHOLDER CLIENT
- The application or library that acts as the intermediary between the APP and the PLACEHOLDER SERVER. This provides the APP with VERSION EVENT callbacks.
- PLACEHOLDER SERVER
- The application or library that acts as the intermediary between the APP SERVER and the PLACEHOLDER CLIENT. This provides ENDPOINTs for the APP SERVER.
- ENDPOINT
- A URL which accepts VERSION updates to trigger eventual APP VERSION EVENT.
- UAID
- A globally unique identifier for a given User Agent.
- VERSION EVENT
- A request from APP SERVER to notify an APP to take action.
Requirements
[File:PlaceHolderServerDiagram.pdf A diagram of the PlaceHolderServer interaction points.]
- APP requests an ENDPOINT from the PLACEHOLDER CLIENT and shall register two callback functions, one for receipt of the ENDPOINT, and a second for handling of a VERSION EVENT
- If not already present, PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the UserAgent (UAID)
- PLACEHOLDER CLIENT shall generate a unique UUID4 Identifier for the APP (APPID)
- PLACEHOLDER CLIENT shall send UAID, APPID and any additional information required for proprietary KICK to the PLACEHOLDER SERVER
- PLACEHOLDER SERVER shall create an ENDPOINT for the UAID and APPID and return it to the PLACEHOLDER CLIENT.
- If a KICK driver is present, PLACEHOLDER SERVER shall relay appropriate PLACEHOLDER CLIENT provided information to the KICK driver.
- PLACEHOLDER CLIENT tenders the ENDPOINT to APP via callback.
- APP sends ENDPOINT to the APP SERVER
- On VERSION EVENT, APP SERVER PUTs version value to ENDPOINT
- If a PLACEHOLDER CLIENT is currently connected to APP SERVER, APP SERVER relays an UPDATE containing currently pending VERSION EVENTS.
- If a PLACEHOLDER CLIENT is NOT currently connected, an optional, proprietary KICK driver may be called to wake devices associated with the corresponding ENDPOINT UAID.
- If a PLACEHOLDER SERVER is unable to immediately deliver a VERSION EVENT, the VERSION EVENT is logged to short term storage.
- PLACEHOLDER CLIENT connects to the PLACEHOLDER SERVER and shall identify a list of one or more UAIDs it is responsible for.
- If there are VERSION EVENTS pending for requested UAIDs, PLACEHOLDER SERVER sends an UPDATE packet (For this template, italicized names would be replaced by actual values):
{ UAID: {
{APPID: VERSION},
... },
... }
- If no VERSION EVENTS are pending for the requested UAIDs, PLACEHOLDER SERVER may return a status indicating no data available (for REST implementations) or simply not return content (for WebSocket)
- During the transmission of the UPDATE, a PLACEHOLDER SERVER may wish to return a 503 (Service Unavailable) error to APP SERVERS for any VERSION EVENT associated with an in progress UAID, so as to prevent potential race conditions.
- On receipt of UPDATE, PLACEHOLDER CLIENT shall return an ACK to the PLACEHOLDER SERVER.
- The ACK shall contain a list of UAIDs for which all APPIDs have been properly received.
- The PLACEHOLDER SERVER shall then clear APPID version information from short term storage, and re-allow version updates for those UAIDs if currently blocked.
- The PLACEHOLDER CLIENT shall then notify APPs of the VERSION EVENT using the appropriate callback, and passing the VERSION
NOTE: a PLACEHOLDER RELAY may be created by combining the polling aspects of the PLACEHOLDER CLIENT with the data management and KICK driver of the PLACEHOLDER SERVER. This would allow a VERSION EVENT system to enter protected networks or use restricted means to communicate to USER AGENTs. It is important to note that once a PLACEHOLDER SERVER has received an ACK for a given UAID, the PLACEHOLDER SERVER is under no obligation to retain that data, and proper relay of the VERSION EVENT is the PLACEHOLDER RELAY's problem.
Get Involved
Call to action for folks who want to help.
Design
Points of Contact
Server Engineer - JR Conlin jrconlin@mozilla Client Engineer -
API Reference/Documentation
Data Schema
Local storage is best determined by the implementation.
For Mozilla, we are considering using Memcache and keeping the version information as simple key/value pairs,
UAID => APPID:VERSION,...
API
How to call the data
method URI
description
Arguments argument descriptions Returns: returned contents
Platform Requirements
What are the things this needs (OS, language, databases, etc.)?
Libraries Required
List of external project dependencies. (Stuff that's not pulled in via the installation script)
Code Repository
Links to the published code bases
Release Schedule
Predicted code delivery dates
QA
Points of Contact
Engineer - Name contact@info
Test Framework
Security and Privacy
Fill out the security & privacy bug template: https://bugzilla.mozilla.org/form.moz-project-review (https://wiki.mozilla.org/Websites/Kick-Off_Form)
Points of Contact
Questionnaire Answers
1.1 Goal of Feature
2. Potential Threat Vectors and Mitigation Points
Review Status
Bugzilla Tracking # - see https://wiki.mozilla.org/Security/Reviews
Issues and Resolutions
Operations
Points of Contact
Deployment Architecture
Bugzilla Tracking # -