MozillaWiki

CloudServices/Notifications/Specification: Difference between revisions

Page Discussion

CloudServices/Notifications/Specification (view source)

Revision as of 19:51, 19 November 2013

1,617 bytes removed ,  19 November 2013
m
Telliott moved page Services/Notifications/Specification to CloudServices/Notifications/Specification
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Overview  =
= Overview  =


Push Notifications is a project that aims to design and create a system that allows for notifications from clients (such as web applications or services) directly to the browsers of its users. A typical example where such a system could be useful is the eBay auctioning system. If a user makes a bid on an item, it would be convenient if that user could leave eBay and start browsing another web site, but still receive notifications if another user bids on that item, allowing them to act on the bid.
'''Mozilla Push Notifications''' is a project that aims to create a system that allows for notifications from clients (such as web applications or services) to be sent directly to the browsers of its users. A typical example where such a system could be useful is the eBay auctioning system. If a user makes a bid on an item, it would be convenient if that user could leave eBay and start browsing another web site, but still receive notifications if another user bids on that item, allowing them to act on the bid.


= Engineers Involved  =
== Engineers Involved  ==


* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Alex Amariutei
* Shane da Silva
* Shane da Silva
* Toby Elliott
* Philipp von Weitershausen
== Terminology ==
* '''Notification''': A message intended to alert its recipient to some event or occurrence.
* '''Provider''': A notification provider, or '''web app''', is any web service that is capable of sending notifications.
* '''User''': End-user; someone who receives notifications.


= Requirements =
= Requirements =


The following section outlines the requirements of the service with respect to the user, the system itself, as well as the third-party developers (a special type of user) who will have to interact with the system.
The following section outlines the requirements of the service with respect to the user, third-party developers (a special type of user) who will have to interact with the system. It also outlines the requirements of the system itself.


== User Requirements  ==
== User Requirements  ==
Line 18: Line 24:
* '''Transparency''': Process ''MUST'' be transparent to user. For example, other than clicking "Yes" or "No" to a dialog of the web app requesting to send notifications, the user should not be aware of the underlying mechanics of the process.
* '''Transparency''': Process ''MUST'' be transparent to user. For example, other than clicking "Yes" or "No" to a dialog of the web app requesting to send notifications, the user should not be aware of the underlying mechanics of the process.


* '''Anonymity''': Web apps ''MUST'' not know anything about user (insofar as the communication between web app and server is concerned; if the user is logged in to GMail and GMail requests to send notifications, then obviously Google knows who it is making the request to)
* '''Security''': From the point a message leaves the sender until it arrives at its intended recipient, all communications ''MUST NOT'' be easily readable by unauthorized persons (e.g. anyone besides the sender and the recipient). By "easily" we mean it should not be trivial to decrypt a message, but take a long enough time and resources so that such effort is not viable.


* '''Portable''': Service ''MUST'' work with any device that supports the protocol
* '''Anonymity''': Web apps ''MUST'' not know anything about user (insofar as the communication between the web app and server is concerned; if the user is logged in to GMail and signs up for notifications, then obviously Google can associate the resulting subscription with the user who created it).


== System Requirements ==
* '''Portability''': Service ''MUST'' work with any device that supports the protocol.
 
TODO


== Developer Requirements ==
== Developer Requirements ==
Line 31: Line 35:


* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.
* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.
* '''Simple Client Implementation''': Third-party developers ''SHOULD'' be able to implement a notification client with relatively little effort.


= Use Cases =
= Use Cases =
Line 38: Line 40:
This section outlines the use cases of the service from both the user's and web app's point of view.
This section outlines the use cases of the service from both the user's and web app's point of view.


== User Use Cases ==
== Users ==


=== Register with Notifications Service ===
=== Register with Notifications Service ===
Line 51: Line 53:
If the user has already registered with the notification service, then they can add an additional client to receive notifications. See the list of related use cases below.
If the user has already registered with the notification service, then they can add an additional client to receive notifications. See the list of related use cases below.


'''Related Use Cases''': [[#Set Up an Additional Client|Set Up an Additional Client]]
'''Related Use Cases''': [[#Add a New Client|Add a New Client]]


=== Subscribe to Notifications ===
=== Subscribe to Notifications ===
Line 57: Line 59:
Once set up the user will the be able to subscribe to web sites which they wish to receive push notification from. The process is as follows:
Once set up the user will the be able to subscribe to web sites which they wish to receive push notification from. The process is as follows:


# User clicks a button (ideally) or otherwise interacts with a web page such that the page requests to send notifications.
# User clicks a button or otherwise interacts with a web page such that the page requests to send notifications.
# Client displays a confirmation box asking user if they wish to receive notifications from the web page in question.
# Client displays a confirmation box asking user if they wish to receive notifications from the web page in question.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.
Line 72: Line 74:
'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]
'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]


=== Set Up an Additional Client ===
=== Add a New Client ===


One of the main advantages of the service is it allows users to receive notifications on multiple clients, be it their browser, mobile phone, etc. Thus setting up another client to receive notifications is likely to be a common operation. The following are two possible methods the user can use to set up an additional client.
One of the main advantages of the service is it allows users to receive notifications on multiple clients, be it their browser, mobile phone, etc. Thus setting up another client to receive notifications is likely to be a common operation. The following are two possible methods the user can use to set up an additional client (note: the goal is to have this be virtually identical to Firefox Sync).


==== Option A: Using JPAKE ====
<ul>
<li>'''Option A: Using JPAKE'''<br />


JPAKE is a mechanism for securely exchanging keys between two clients. This is the same process that is used by the Sync service when adding a new device.
JPAKE is a mechanism for securely exchanging keys between two clients. This is the same process that is used by the Sync service when adding a new device.
</li>
==== Option B: Using Credentials and Secret Key ====
<li>'''Option B: Using Credentials and Secret Key'''<br />


If the user does not have a client that is already connected, they will have to have their credentials ready along with their secret key (which is used to decrypt the messages sent to them). Provided they have this information, the following process could also be used to connect a new client:
If the user does not have a client that is already connected, they will have to have their credentials ready along with their secret key (which is used to decrypt the messages sent to them). Provided they have this information, the following process could also be used to connect a new client:
Line 87: Line 90:
# User enters credentials along with their secret key.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.
# Client registers itself with the notification server.
</li>
</ul>


'''Related Use Cases''': [[#Register with Notifications Service|Register with Notifications Service]]
'''Related Use Cases''': [[#Register with Notifications Service|Register with Notifications Service]]


== Web App Use Cases ==
== Providers ==


=== Send a Notification ===
=== Send a Notification ===


The web app is able to send a message (i.e. the notification) to a specific user using a '''routing key''' that was given to it by the user's client. The routing key can be thought of as an address that specifies the destination "mailbox" of the message. The process from the point of view of the web app is as follows:
The web app is able to send a message (i.e. the notification) to a specific user using a '''routing key''' that was given to it by the user's client. The routing key can be thought of as an address that specifies the destination "mailbox" of the message. It maintains the user's anonymity while still allowing the service to communicate with the user. The process from the web app's point of view is as follows:


# Web app creates a JSON string encompassing the notification it wishes to send (as well as which user to send it to)
# Web app creates a message it wishes to send
# Web app sends the JSON string to the notification server.
# Web app sends the message to the notification server.


= Implementation =
= Implementation =
Line 113: Line 119:
* '''Web App''': Third-party web application that actually produces the notifications. The user subscribes to notifications from this app via a web page.
* '''Web App''': Third-party web application that actually produces the notifications. The user subscribes to notifications from this app via a web page.


* '''Message Broker''': Handles the sending and receiving of messages. See [http://www.rabbitmq.com RabbitMQ] for more information.
* '''Message Broker''': Facilitates the transportation of messages. See [http://www.rabbitmq.com RabbitMQ] for more information.
 
* '''POST Office''': Responsible for forwarding all notifications sent by web apps to the Message Broker.


* '''Agent''': Responsible for all REST-API calls, this handles the creation of any messages within the message broker on behalf of web apps, and handles the creation of exchanges and queues on behalf of clients.
* '''Client Agent''': Handles the creation of exchanges and queues within the Message Broker on behalf of clients. The Client uses the Client Agent as a means to register itself and create and remove subscriptions.


* '''Subscription''': Represents the relationship between a web app and a user who wishes to receive notifications from said web app. A subscription consists of the "link" that allows the web app to send notifications to the user.
* '''Subscription''': Represents the relationship between a web app and a user who wishes to receive notifications from said web app. A subscription consists of the "link" that allows the web app to send notifications to the user.


* '''Routing Key''': A unique identifier generated by the Agent when a user subscribes to notifications from a web app. The routing key is used as a "mailbox address" by the web app to send notifications to the user.
* '''Routing Key/Token''': A unique identifier generated by the Agent when a user subscribes to notifications from a web app. The routing key is used as a "mailbox address" to send notifications to the user.


* '''User Exchange''': Entity within the message broker where all messages destined for a particular user are sent.
* '''User Exchange''': Entity within the message broker where all messages destined for a particular user are sent.


* '''Client Queue''': Entity within the message broker where all messages destined for a particular client of a user are sent (i.e. one queue per client).
* '''Client Queue''': Entity within the message broker where all messages destined for a particular client of a user are sent (one queue per client).
 
== Agent API ==
 
The Agent API consists of a standard REST API, using HTTP GET, POST, PUT, and DELETE commands to retrieve and manipulate resources. The following table gives a summary of the API supported by the Agent:


{| class="wikitable"
== APIs ==
|-
! Path
! Description
|-
| /notifications
| Methods: '''POST'''
Used by web apps to send notifications. The body of the HTTP request should contain a JSON string of the following form:
<pre>
{"routing_key": "routing_key",
"type": "the type of notification",
"timestamp": "UNIX timestamp",
"payload": "notification message"}
</pre>


|-
* [[Services/Notifications/Specification/POSTOffice | POST Office API]]
| /users/'''name'''/subscriptions
| Methods: '''GET''', '''POST'''
Requires authentication.
GETting this retrieves all subscriptions for the user with the specified name. Appending a query string at the end of the URL (e.g. ''?app_host=mail.google.com&app_name=GMail'') will filter the results by the fields specified. This is useful for determining if a particular subscription exists for a given application name/host pair. The list is returned as a JSON string of the form:
<pre>
[{"routing_key": "routing_key",
  "app_name": "Name of app",
  "app_host": "Domain of app",
  "reg_date": "Creation date"},
...
]
</pre>
Each item in the JSON array corresponds to a subscription for the specified user.


You can create a new subscription by POSTing to this resource with a HTTP body of the following form:
* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]
<pre>
{"app_name": "Application name",
"app_host": "Domain of web app"}
</pre>
If the application name and host field values are unique as a pair, the subscription is created and the following JSON string is returned:
<pre>
{"routing_key": "the routing key created"}
</pre>


|-
* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]
| /users/'''name'''/subscriptions/'''routing_key'''
|  Methods: '''GET''', '''DELETE'''
Requires authentication.
GETting this resource will return information about the subscription with the specified routing key. The returned information is of the following form:
<pre>
{"app_name": "Name of app",
"app_host": "Domain of app",
"reg_date": "Creation date"}
</pre>
If you are DELETEing this resource it will remove the subscription and send a notification to all of the user's other clients, telling them the subscription is no longer valid.
 
|-
| /users/'''name'''
|  Methods: '''PUT'''
''Will eventually require a more secure method of creation, e.g. CAPTCHA''
 
To PUT a user (i.e. create new user account) you'll need an HTTP body looking like the following:
<pre>
{"password": "user's account password"}
</pre>
|}


== Security Considerations ==
== Security Considerations ==
Line 209: Line 158:


* What features will we provide for administrators of the server?
* What features will we provide for administrators of the server?
== Meeting Notes ==
* General notes from meetings over the course of development
Telliott
canmove, Confirmed users
1,173

edits

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