MozillaWiki - User contributions [en]

CloudServices/Meetings/2011-05-03

2011-05-03T05:40:55Z

Sdasilva: /* Notifications (Shane/Alex) */

CloudServices/Meetings/2011-05-03

2011-05-03T05:40:25Z

Sdasilva: /* Notifications (Shane/Alex) */

CloudServices/Meetings/2011-04-26

2011-04-26T16:23:10Z

Sdasilva: /* Server */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, North Bridge
|confId=8616
}}

'''[https://mail.mozilla.com/home/rnewman@mozilla.com/Services%20Team%20Availability.html Who's away?]''': philiKON.

= Technical =

== Ops ==
*Build for loadtest cluster in SCL2 blocked on NetOps (bug [https://bugzilla.mozilla.org/show_bug.cgi?id=649212 649212]). Actively working with NetOps to move forward.

== Engineering ==

=== Python Sync Server (Tarek) ===

* waiting for the test cluster to work out the deployment w/ Pete

=== Python Registration Server (reg/sreg) (Tarek) ===

* will work this week on some sreg changes w/ Toby. Everything should be ready next monday

=== PHP Sync Server (Toby) ===
Updates to handle new LDAP schema deployed yesterday. No problems noted.

=== Identity Server (JR/rnewman) ===
* added write checking to mongo db storage
* clean up of display pages (more consistent UI)
* added test cases for new functions
* began work on redis rebuild for new system
* Stefan booting work environment

Next:

* finish redis rebuild.
* review w/ Thunder
* send code to QA for testing

=== F1 (Share) (Philipp/Tarek) ===

* Server-side
** working on the libmemcached client to talk to membase this week [tarek]
* Client
** {{bug|651668}} tracks minimal landing in Firefox
** {{bug|642684}} tracks final UX for minimal landing

=== Firefox Home (Stefan) ===

=== Sync Client (rnewman) ===

Handed off to QA (thanks philiKON for the bug list):

* Bug 649783 [STRs]: don't attempt to delete client-specific data if Sync doesn't have a cluster URL.
* Bug 649739 [qa-]: send userabort reason for J-PAKE cancelation.
* Bug 648371 [qa-]: Convert async tests to use run_next_test helper.
* Bug 646910 [qa-]: attempt to fix random orange in test_clients_engine.
* Bug 645918 [qa-]: attempt to fix random orange in test_bookmarks_engine.
* Bug 650208 [STRs]: More considered handling of key generation
* Bug 651596 [qa-]: eliminate IWeaveCrypto.
* Bug 652182 [qa-]: eliminate Resource status == 0 check missed in landing of Bug 623080.
* Bug 652666 [STRs]: fix a missing rename in prefs engine.
* Bug 652341 [STRs] - Firefox Sync key document doesn't align to the right on RTL

We have the Alder branch for [[Services/Sync/FxSync/WarOnSync|War on Sync]], and I'm busy [https://github.com/rnewman/alder hacking away on GitHub].

=== Monitoring and Blocking (rtilder) ===

=== Notifications (Shane/Alex) ===
==== Client ====
*Got together a TODO list for remaining items.
*Currently working on a more centralized error handling to prevent random English strings moving around in code ( and will l10n them after).
*Most work involved in cleaning up the code for ease of readability.
*Will also work on writing a complete set of tests for AMQP (or document them in the least).
==== Server ====
* Finished harnessing and writing tests for Client Agent
* Now beginning process of writing documentation/general brain dump for server to get successor up to speed faster

=== QA (tracy) ===
* Sync s-c client sign-off EOD today (4/26)
* Expecting hand-off from server team on Wednesday. Will sign-off by EOD Friday (4/29)
* Finalize services QA plan based on the strategy of weekly pushes of s-c to m-c.
* Tony is in the process of interviewing a few candidates for services QA positions.
* Meeting with thunder today to discuss QA for Identity.

= Deployment Requests =

As per the [[Services/Process/ServerReleaseProcess|production release process]] any production change requests for the next release window (Monday afternoon) must be called out here by the developer requesting the update, with all required bugs/test plans already complete by the start of the meeting.

== Key Exchange Server ==

* keyexchange 0.3-1, {{bug|650328}}

== Python Reg/Sreg ==

Likely to happen after Tarek and Toby talk today. Will have details this afternoon.

= Metrics =

= Product =

= Security =

= Marketing =

= Roundtable =

* Last chance to harass Justin

== Notes and actions ==

== Follow ups from last week ==

=== Other issues ===

CloudServices/Meetings/2011-04-26

2011-04-26T16:22:20Z

Sdasilva: /* Notifications (Shane/Alex) */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, North Bridge
|confId=8616
}}

'''[https://mail.mozilla.com/home/rnewman@mozilla.com/Services%20Team%20Availability.html Who's away?]''': philiKON.

= Technical =

== Ops ==
*Build for loadtest cluster in SCL2 blocked on NetOps (bug [https://bugzilla.mozilla.org/show_bug.cgi?id=649212 649212]). Actively working with NetOps to move forward.

== Engineering ==

=== Python Sync Server (Tarek) ===

* waiting for the test cluster to work out the deployment w/ Pete

=== Python Registration Server (reg/sreg) (Tarek) ===

* will work this week on some sreg changes w/ Toby. Everything should be ready next monday

=== PHP Sync Server (Toby) ===
Updates to handle new LDAP schema deployed yesterday. No problems noted.

=== Identity Server (JR/rnewman) ===

=== F1 (Share) (Philipp/Tarek) ===

* Server-side
** working on the libmemcached client to talk to membase this week [tarek]
* Client
** {{bug|651668}} tracks minimal landing in Firefox
** {{bug|642684}} tracks final UX for minimal landing

=== Firefox Home (Stefan) ===

=== Sync Client (rnewman) ===

Handed off to QA (thanks philiKON for the bug list):

* Bug 649783 [STRs]: don't attempt to delete client-specific data if Sync doesn't have a cluster URL.
* Bug 649739 [qa-]: send userabort reason for J-PAKE cancelation.
* Bug 648371 [qa-]: Convert async tests to use run_next_test helper.
* Bug 646910 [qa-]: attempt to fix random orange in test_clients_engine.
* Bug 645918 [qa-]: attempt to fix random orange in test_bookmarks_engine.
* Bug 650208 [STRs]: More considered handling of key generation
* Bug 651596 [qa-]: eliminate IWeaveCrypto.
* Bug 652182 [qa-]: eliminate Resource status == 0 check missed in landing of Bug 623080.
* Bug 652666 [STRs]: fix a missing rename in prefs engine.
* Bug 652341 [STRs] - Firefox Sync key document doesn't align to the right on RTL

We have the Alder branch for [[Services/Sync/FxSync/WarOnSync|War on Sync]], and I'm busy [https://github.com/rnewman/alder hacking away on GitHub].

=== Monitoring and Blocking (rtilder) ===

=== Notifications (Shane/Alex) ===
==== Client ====
*Got together a TODO list for remaining items.
*Currently working on a more centralized error handling to prevent random English strings moving around in code ( and will l10n them after).
*Most work involved in cleaning up the code for ease of readability.
*Will also work on writing a complete set of tests for AMQP (or document them in the least).
==== Server ====
* Finished harnessing and writing tests for Client Agent
* Now beginning process of writing documentation for server for successor

=== QA (tracy) ===
* Sync s-c client sign-off EOD today (4/26)
* Expecting hand-off from server team on Wednesday. Will sign-off by EOD Friday (4/29)
* Finalize services QA plan based on the strategy of weekly pushes of s-c to m-c.
* Tony is in the process of interviewing a few candidates for services QA positions.
* Meeting with thunder today to discuss QA for Identity.

= Deployment Requests =

As per the [[Services/Process/ServerReleaseProcess|production release process]] any production change requests for the next release window (Monday afternoon) must be called out here by the developer requesting the update, with all required bugs/test plans already complete by the start of the meeting.

== Key Exchange Server ==

* keyexchange 0.3-1, {{bug|650328}}

== Python Reg/Sreg ==

Likely to happen after Tarek and Toby talk today. Will have details this afternoon.

= Metrics =

= Product =

= Security =

= Marketing =

= Roundtable =

* Last chance to harass Justin

== Notes and actions ==

== Follow ups from last week ==

=== Other issues ===

CloudServices/Notifications/Server

2011-04-15T23:43:18Z

Sdasilva: /* Provide Mechanism to Move Client to a Different POST Office */

The following page contains a list of open discussion points about the '''Mozilla Push Notifications''' server.

= Hide Broker Behind HTTP REST API =
== Pros ==
* Can pool multiple connections into one connection (using multiple channels on that one connection)
* Simpler for developers to build their own client (just do long-lived HTTP requests)
* Better security by preventing direct access to broker (if broker has a security hole, we would need to wait for a fix)
* Allows us to abstract away how messages are routed
* Allows us to support idea #7 by returning a 302 directing client to the new POST Office
== Cons ==
* Extra server overhead

= Enforce Exclusive Queues =
== Pros ==
* Easy to do with AMQP
* Extra security: can tell if someone else is "snooping" on your queue and take action (create a new one, forward all messages to new queue, delete old queue)
== Cons ==
* Can't "share" single queue amongst multiple clients (not sure if we even want this -- does it even make sense?)

= Persistent POST Office Connections =
== Pros ==
* Makes it easier for us to detect a DoS attack? (Apple uses this approach with APNS)
* Allow web apps to send bulk transfer of notifications (very useful for bulk senders like GMail)
== Cons ==
* Makes it more complicated for providers as it requires they have a pool of persistent connections with which to send notifications
* Adds complexity to POST Office so we can support it?

= Implement TTLs for Queues (and Messages) =
== Pros ==
* Easy to do with RabbitMQ extensions (see http://www.rabbitmq.com/extensions.html#queue-ttl and http://www.rabbitmq.com/extensions.html#queue-leases)
* Prevents server from being flooded with old messages that will never be read
== Cons ==
* Could this be annoying for users? Probably not so long as we have a long enough TTL and make it clear to users it's enforced.

= Alert Providers When Subscription Cancelled =
== Pros ==
* Providers only send notifications to "active" subscriptions (saves resources)
== Cons ==
* To return error message from POST Office would be time consuming and would probably make the service incapable of large spikes in traffic (so we shouldn't do this)
* To return an error message asynchronously would require providers build a separate service for accepting cancellation messages. Another option is to have clients send a cancellation message, but this really should be done by the Client Agent to maintain users' anonymity (or should it?)

= Send ACK to Provider When Notification Received =
== Pros ==
* Can support messages for which delivery must be assured
== Cons ==
* Requires we build an entire messaging system that goes the other way? OR we could just reuse the current framework and have providers subscribe as a client. OR (even better) we could just spec a special notification type that allows the client to confirm the receipt of a notification (i.e. include a URL client can send ACK to).

= Provide Mechanism to Move Client to a Different POST Office =
== Pros ==
* Allows us to re-balance our servers
* Gives users the power to move from Mozilla to their own server
== Cons ==
* Could have security implications? (if attacker took control of Mozilla's servers and moved all its users to another notification server, for example)

= Make POST Office in Charge of Generating Subscription Token =
== Pros ==
* One less thing clients can screw up (also prevents generation of insecure tokens such as AAAAAAA...A)
== Cons ==
* If other users implemented a POST Office, they could assign tokens that are personally identifying (is this really something we need to worry about? Who would even bother doing this?)

CloudServices/Notifications/Server

2011-04-15T00:40:17Z

Sdasilva: /* Alert Providers When Subscription Cancelled = */

CloudServices/Notifications/Server

2011-04-15T00:39:25Z

Sdasilva: Created page with "The following page contains a list of open discussion points about the '''Mozilla Push Notifications''' server. = Hide Broker Behind HTTP REST API = == Pros == * Can pool multip..."

The following page contains a list of open discussion points about the '''Mozilla Push Notifications''' server.

= Hide Broker Behind HTTP REST API =
== Pros ==
* Can pool multiple connections into one connection (using multiple channels on that one connection)
* Simpler for developers to build their own client (just do long-lived HTTP requests)
* Better security by preventing direct access to broker (if broker has a security hole, we would need to wait for a fix)
* Allows us to abstract away how messages are routed
* Allows us to support idea #7 by returning a 302 directing client to the new POST Office
== Cons ==
* Extra server overhead

= Enforce Exclusive Queues =
== Pros ==
* Easy to do with AMQP
* Extra security: can tell if someone else is "snooping" on your queue and take action (create a new one, forward all messages to new queue, delete old queue)
== Cons ==
* Can't "share" single queue amongst multiple clients (not sure if we even want this -- does it even make sense?)

= Persistent POST Office Connections =
== Pros ==
* Makes it easier for us to detect a DoS attack? (Apple uses this approach with APNS)
* Allow web apps to send bulk transfer of notifications (very useful for bulk senders like GMail)
== Cons ==
* Makes it more complicated for providers as it requires they have a pool of persistent connections with which to send notifications
* Adds complexity to POST Office so we can support it?

= Implement TTLs for Queues (and Messages) =
== Pros ==
* Easy to do with RabbitMQ extensions (see http://www.rabbitmq.com/extensions.html#queue-ttl and http://www.rabbitmq.com/extensions.html#queue-leases)
* Prevents server from being flooded with old messages that will never be read
== Cons ==
* Could this be annoying for users? Probably not so long as we have a long enough TTL and make it clear to users it's enforced.

= Alert Providers When Subscription Cancelled ==
== Pros ==
* Providers only send notifications to "active" subscriptions (saves resources)
== Cons ==
* To return error message from POST Office would be time consuming and would probably make the service incapable of large spikes in traffic (so we shouldn't do this)
* To return an error message asynchronously would require providers build a separate service for accepting cancellation messages. Another option is to have clients send a cancellation message, but this really should be done by the Client Agent to maintain users' anonymity (or should it?)

= Send ACK to Provider When Notification Received =
== Pros ==
* Can support messages for which delivery must be assured
== Cons ==
* Requires we build an entire messaging system that goes the other way? OR we could just reuse the current framework and have providers subscribe as a client. OR (even better) we could just spec a special notification type that allows the client to confirm the receipt of a notification (i.e. include a URL client can send ACK to).

= Provide Mechanism to Move Client to a Different POST Office =
== Pros ==
* Allows us to re-balance our servers
* Gives users the power to move from Mozilla to their own server
== Cons ==
* Could have security implications? (if attacker took control of Mozilla's servers and moved all its users to another notification server, for example)

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T22:26:56Z

Sdasilva: /* Message HMAC */

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==" // Initialization vector to use in decrypting ciphertext
}
</pre>

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type": "notification",
"title": "You've got mail!",
"body": "There are current 2 messages in your inbox.",
"url": "http://mail.google.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

== Message HMAC ==
The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard [http://en.wikipedia.org/wiki/HMAC HMAC algorithm] with the [http://en.wikipedia.org/wiki/SHA-2#SHA-256_.28a_SHA-2_variant.29_pseudocode SHA-256 hash function].

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T22:26:17Z

Sdasilva: /* Message Body */

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==" // Initialization vector to use in decrypting ciphertext
}
</pre>

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type": "notification",
"title": "You've got mail!",
"body": "There are current 2 messages in your inbox.",
"url": "http://mail.google.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

== Message HMAC ==
The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard [http://en.wikipedia.org/wiki/HMAC HMAC algorithm] with a [http://en.wikipedia.org/wiki/SHA-2#SHA-256_.28a_SHA-2_variant.29_pseudocode SHA-256 hash function].

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T22:25:47Z

Sdasilva: /* Ciphertext Contents */

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==", // Initialization vector to use in decrypting ciphertext
}
</pre>

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type": "notification",
"title": "You've got mail!",
"body": "There are current 2 messages in your inbox.",
"url": "http://mail.google.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

== Message HMAC ==
The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard [http://en.wikipedia.org/wiki/HMAC HMAC algorithm] with a [http://en.wikipedia.org/wiki/SHA-2#SHA-256_.28a_SHA-2_variant.29_pseudocode SHA-256 hash function].

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T22:25:30Z

Sdasilva: /* Ciphertext Contents */

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==", // Initialization vector to use in decrypting ciphertext
}
</pre>

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"You've got mail!",
"body":"There are current 2 messages in your inbox.",
"url":"http://mail.google.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

== Message HMAC ==
The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard [http://en.wikipedia.org/wiki/HMAC HMAC algorithm] with a [http://en.wikipedia.org/wiki/SHA-2#SHA-256_.28a_SHA-2_variant.29_pseudocode SHA-256 hash function].

CloudServices/Notifications/Specification

2011-04-14T22:22:32Z

Sdasilva: /* Terminology */

= Overview =

'''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 ==

* Alex Amariutei
* 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 =

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 ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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 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.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Providers ==

=== 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. 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 message it wishes to send
# Web app sends the message to the notification server.

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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.

* '''Client Queue''': Entity within the message broker where all messages destined for a particular client of a user are sent (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T22:21:29Z

Sdasilva: /* Requirements */

= Overview =

'''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 ==

* Alex Amariutei
* 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 =

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 ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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 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.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Providers ==

=== 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. 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 message it wishes to send
# Web app sends the message to the notification server.

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications

2011-04-14T22:16:23Z

Sdasilva:

CloudServices/Notifications/Specification/ClientAgent

2011-04-14T22:10:02Z

Sdasilva: /* Broadcast Messages */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenarios =

== New (Potentially First) Client ==

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

== New Subscription ==
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "BASE64=="}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync.
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app.
</li>
</ol>

== Terminate Subscription ==

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

== Client-To-All-Clients Broadcast ==
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body": "{\"IV\":\"IV in Base 64\",...",
"HMAC": "BASE64=="
}
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is the payload encrypted using AES-256-CBC and base-64 encoded. For an example of what payloads would look like, see [[#Broadcast Messages|Broadcast Messages]]
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

=== Broadcast Messages Types ===

Each broadcast message is encrypted and contained entirely within the "ciphertext" attribute of the message body. The following is a list of the type of broadcast messages supported by browser clients.

==== Send Tab To Client ====
Copies a tab from one client and sends it to another client.

<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// OPTIONAL: Implement either one of the following fields to transfer tab history and form data
"moztabinfo": "{Serialized Tab State}" // Value returned by nsISessionStore.getTabState()
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // Generic format (STILL NEEDS SPECING)
}
</pre>

Note that this message is broadcasted, so the "client_id" field must be compared against the client's own ID to make sure the message was intended for it.

==== Sync Now ====
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of client who sent this message
"engines": ["bookmarks", "tabs", ...] // Optional list of engines to sync
}
</pre>

CloudServices/Notifications/Specification/ClientAgent

2011-04-14T22:08:45Z

Sdasilva: /* Broadcast to Other Clients */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenarios =

== New (Potentially First) Client ==

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

== New Subscription ==
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "BASE64=="}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync.
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app.
</li>
</ol>

== Terminate Subscription ==

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

== Client-To-All-Clients Broadcast ==
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body": "{\"IV\":\"IV in Base 64\",...",
"HMAC": "BASE64=="
}
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is the payload encrypted using AES-256-CBC and base-64 encoded. For an example of what payloads would look like, see [[#Broadcast Messages|Broadcast Messages]]
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

=== Broadcast Messages ===

Each broadcast message is encrypted and contained entirely within the "ciphertext" attribute of the message body. The following is a list of the type of broadcast messages supported by browser clients.

==== Send Tab To Client ====
Copies a tab from one client and sends it to another client.

<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// OPTIONAL: Implement either one of the following fields to transfer tab history and form data
"moztabinfo": "{Serialized Tab State}" // Value returned by nsISessionStore.getTabState()
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // Generic format (STILL NEEDS SPECING)
}
</pre>

Note that this message is broadcasted, so the "client_id" field must be compared against the client's own ID to make sure the message was intended for it.

==== Sync Now ====
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of client who sent this message
"engines": ["bookmarks", "tabs", ...] // Optional list of engines to sync
}
</pre>

CloudServices/Notifications/Specification/ClientAgent

2011-04-14T22:06:16Z

Sdasilva:

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenarios =

== New (Potentially First) Client ==

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

== New Subscription ==
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "BASE64=="}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync.
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app.
</li>
</ol>

== Terminate Subscription ==

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

== Broadcast to Other Clients ==
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body": "{\"IV\":\"IV in Base 64\",...",
"HMAC": "BASE64=="
}
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is the payload encrypted using AES-256-CBC and base-64 encoded. For an example of what payloads would look like, see [[#Broadcast Messages|Broadcast Messages]]
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

=== Broadcast Messages ===

Each broadcast message is encrypted and contained entirely within the "ciphertext" attribute of the message body. The following is a list of the type of broadcast messages supported by browser clients.

==== Send Tab To Client ====
Copies a tab from one client and sends it to another client.

<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// OPTIONAL: Implement either one of the following fields to transfer tab history and form data
"moztabinfo": "{Serialized Tab State}" // Value returned by nsISessionStore.getTabState()
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // Generic format (STILL NEEDS SPECING)
}
</pre>

Note that this message is broadcasted, so the "client_id" field must be compared against the client's own ID to make sure the message was intended for it.

==== Sync Now ====
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of client who sent this message
"engines": ["bookmarks", "tabs", ...] // Optional list of engines to sync
}
</pre>

CloudServices/Notifications/Specification

2011-04-14T21:51:03Z

Sdasilva: /* Engineers Involved */

= Overview =

'''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 ==

* Alex Amariutei
* 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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 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.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Providers ==

=== 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. 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 message it wishes to send
# Web app sends the message to the notification server.

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:49:46Z

Sdasilva: /* Web App Use Cases */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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 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.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Providers ==

=== 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. 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 message it wishes to send
# Web app sends the message to the notification server.

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:46:54Z

Sdasilva: /* Subscribe to Notifications */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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 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.
# Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:46:20Z

Sdasilva: /* Register with Notifications Service */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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''': [[#Add a New Client|Add a New Client]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:45:39Z

Sdasilva: /* Set Up an Additional Client */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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 (note: the goal is to have this be virtually identical to Firefox Sync).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:45:11Z

Sdasilva: /* User Use Cases */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== Users ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:43:59Z

Sdasilva: /* Terminology */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== 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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:41:07Z

Sdasilva: /* Overview */

= Overview =

'''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 ==

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

== Terminology ==

* '''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 =

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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:38:55Z

Sdasilva: /* Engineers Involved */

= Overview =

'''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.

= 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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:37:31Z

Sdasilva: /* Set Up an Additional Client */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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).

<ul>
<li>'''Option A: Using JPAKE''' 

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>
<li>'''Option B: Using Credentials and Secret Key''' 

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

</li>
</ul>

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:30:26Z

Sdasilva: /* Client ToDo */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:26:29Z

Sdasilva: /* Developer Requirements */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''Easy Adoption''': Web apps and custom clients ''SHOULD'' be able to add notification support to their applications with relatively little effort.

= Use Cases =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:25:28Z

Sdasilva: /* User Requirements */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''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.

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''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 =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:23:09Z

Sdasilva: /* User Requirements */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''Security''': From the point a message leaves the sender until it arrives at its intended recipient, all communications ''MUST NOT'' be readable by unauthorized persons (e.g. anyone besides the sender and the recipient).

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''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 =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:22:37Z

Sdasilva: /* User Requirements */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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.

* '''Security''': From the point a message leaves the sender until it arrives at its intended recipient, all communications should not be readable by unauthorized persons (e.g. anyone besides the sender and the recipient).

* '''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).

* '''Portability''': Service ''MUST'' work with any device that supports the protocol.

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''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 =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification

2011-04-14T21:17:47Z

Sdasilva: /* Overview */

= Overview =

'''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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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)

* '''Portable''': Service ''MUST'' work with any device that supports the protocol

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''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 =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T21:15:54Z

Sdasilva:

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==", // Initialization vector to use in decrypting ciphertext
}
</pre>

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"...",
"body":"...",
"url":"http://foobar.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

== Message HMAC ==
The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard [http://en.wikipedia.org/wiki/HMAC HMAC algorithm] with a [http://en.wikipedia.org/wiki/SHA-2#SHA-256_.28a_SHA-2_variant.29_pseudocode SHA-256 hash function].

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T21:08:26Z

Sdasilva: /* Web App Sends Notification */

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Sending Notifications =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body": "{\"token\":\"BASE64==\", ...}",
"HMAC": "BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
</ol>

== Message Body ==
The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:
<pre>
{
"token": "BASE64==", // Subscription Token
"timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
"ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
"ciphertext": "BASE64==", // Encrypted payload
"IV": "BASE64==", // Initialization vector to use in decrypting ciphertext
}
</pre>

=== Ciphertext Contents ===
The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"...",
"body":"...",
"url":"http://foobar.com"
}
</pre>

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T20:49:32Z

Sdasilva:

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

= Web App Sends Notification =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body":"{\"token\":\"T in Base 64\",...",
"HMAC":"BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
<li>Body is a JSON serialization of

<pre>
{
"token": "T in Base 64",
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is a JSON serialization encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"...",
"body":"...",
"url":"http://foobar.com"
}
</pre>
</li>
</ol>

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T20:49:13Z

Sdasilva:

The POST Office supports a very simple REST API allowing web apps to send notifications to a subscription token.

= Web App Sends Notification =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body":"{\"token\":\"T in Base 64\",...",
"HMAC":"BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
<li>Body is a JSON serialization of

<pre>
{
"token": "T in Base 64",
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is a JSON serialization encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"...",
"body":"...",
"url":"http://foobar.com"
}
</pre>
</li>
</ol>

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T20:46:28Z

Sdasilva: /* Web App Sends Notification */

The POST Office supports a very simple REST API allowing web apps to send notifications will relatively little effort. It forwards the notifications to the Message Broker on behalf of the web apps.

= Web App Sends Notification =

<ol>
<li>
Web app sends notification to POST Office.

<pre>
W: POST /1.0/notification HTTP/1.1
W:
W: {
"body":"{\"token\":\"T in Base 64\",...",
"HMAC":"BASE64=="
}
P: HTTP/1.1 202 ACCEPTED
</pre>
</li>
<li>Body is a JSON serialization of

<pre>
{
"token": "T in Base 64",
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre>
</li>

<li>Ciphertext is a JSON serialization encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message. For example, the payload of a standard notification will look like the following:
<pre>
{
"type":"notification",
"title":"...",
"body":"...",
"url":"http://foobar.com"
}
</pre>
</li>
</ol>

CloudServices/Notifications/Specification/POSTOffice

2011-04-14T20:45:12Z

Sdasilva: /* Web App Sends Notification */

CloudServices/Notifications/Specification

2011-04-12T22:12:27Z

Sdasilva: /* Client ToDo */

= Overview =

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 =

* Philipp von Weitershausen
* Toby Elliot
* Alex Amariutei
* Shane da Silva

= 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.

== User Requirements ==

* '''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)

* '''Portable''': Service ''MUST'' work with any device that supports the protocol

== System Requirements ==

TODO

== Developer Requirements ==

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

* '''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 =

This section outlines the use cases of the service from both the user's and web app's point of view.

== User Use Cases ==

=== Register with Notifications Service ===

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

# User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
# Client asks user for account credentials, or points user to a link to create an account.
# User enters their account credentials (or simply uses their Sync account)
# Client remembers credentials for later use

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]]

=== Subscribe to Notifications ===

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.
# 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.

'''Related Use Cases''': [[#Cancel a Subscription|Cancel a Subscription]]

=== Cancel a Subscription ===

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

# User navigates to the list of subscriptions on their client.
# User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

'''Related Use Cases''': [[#Subscribe to Notifications|Subscribe to Notifications]]

=== 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.

==== Option A: Using JPAKE ====

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.

==== Option B: Using Credentials and Secret Key ====

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:

# User indicates they have already registered and wish to add an additional client manually.
# User enters credentials along with their secret key.
# Client registers itself with the notification server.

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

== Web App Use Cases ==

=== 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:

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

= Implementation =

== Terminology ==

[[Image:PN-HighLevelCommLines.png|thumb|250px|High-level overview of the lines of communication between the entities in the system.]]

[[Image:PN-HighLevelNotifFlow.png|thumb|250px|Overview of how notifications travel from web apps to clients.]]

* '''User''': Individual who receives notifications.

* '''Client''': One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

* '''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''': 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.

* '''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.

* '''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" by the web app to send notifications to the user.

* '''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 (one queue per client).

== APIs ==

* [[Services/Notifications/Specification/POSTOffice | POST Office API]]

* [[Services/Notifications/Specification/ClientAgent | Client Agent API]]

* [[Services/Notifications/Specification/BrowserJS | Browser JavaScript API]]

== Security Considerations ==

===DOS Defense===
* Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
** Configurable threshold for adding IP address to Blacklist/Penalty Box
** Configurable time-out for IP addresses added to Blacklist/Penalty Box
* A single shared blacklist will exist within memcache
* LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
* All thresholds will be controlled via the configuration page

===Logging Points===

* What are we going to log server-side?

=== Administration Features===

* What features will we provide for administrators of the server?

== Meeting Notes ==

* General notes from meetings over the course of development

== Client ToDo ==

* When adding a new subscription, the pref window should update if open
* Code clean up
* Resolve issue where messages larger than 8000 bytes are not transmitted (FOCUS)
* Android
** Send to tab (hook up UI)
** Hide previous notifications button when notifications disabled
* Cleanup on disable notifications

CloudServices/Notifications/Specification/ClientAgent

2011-04-08T22:24:47Z

Sdasilva: /* Sync Now */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenario 1: New (Potentially First) Client =

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

= Scenario 2: New Subscription =
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app (see Scenario Alpha).
</li>
</ol>

= Scenario 3: Terminate Subscription =

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

= Scenario 4: Broadcast to Other Clients =
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body":"{\"IV\":\"IV in Base 64\",...",
"HMAC":"BASE64=="
}
S: HTTP/1.1 200 OK
</pre></li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre></li>

<li>Ciphertext is the payload encrypted with the client key using AES-256-CBC and base64 encoded. For example:
<pre>
{
"type":"send_tab",
"client_id":"base64url==", // Sync client ID
"url":"...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo":{serialized tab info} // optional
"tabinfo":[{"url":"...", "title":"...", "formdata":"..."}] // optional
}
</pre>
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

== Broadcast Messages ==

Each broadcast message is encrypted and contained entirely within the ciphertext attribute of the message body. The following is a list of the type of broadcast messages supported by clients.

=== Send Tab To Client ===
Copies a tab from one client and sends it to another client.
<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo": {serialized tab info} // optional
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // optional (still needs specing)
}
</pre>

=== Sync Now ===
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of client who sent this message
"engines": ["bookmarks", "tabs",...] // Optional list of engines to sync
}
</pre>

CloudServices/Notifications/Specification/ClientAgent

2011-04-08T22:10:18Z

Sdasilva: /* Sync Now */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenario 1: New (Potentially First) Client =

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

= Scenario 2: New Subscription =
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app (see Scenario Alpha).
</li>
</ol>

= Scenario 3: Terminate Subscription =

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

= Scenario 4: Broadcast to Other Clients =
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body":"{\"IV\":\"IV in Base 64\",...",
"HMAC":"BASE64=="
}
S: HTTP/1.1 200 OK
</pre></li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre></li>

<li>Ciphertext is the payload encrypted with the client key using AES-256-CBC and base64 encoded. For example:
<pre>
{
"type":"send_tab",
"client_id":"base64url==", // Sync client ID
"url":"...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo":{serialized tab info} // optional
"tabinfo":[{"url":"...", "title":"...", "formdata":"..."}] // optional
}
</pre>
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

== Broadcast Messages ==

Each broadcast message is encrypted and contained entirely within the ciphertext attribute of the message body. The following is a list of the type of broadcast messages supported by clients.

=== Send Tab To Client ===
Copies a tab from one client and sends it to another client.
<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo": {serialized tab info} // optional
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // optional (still needs specing)
}
</pre>

=== Sync Now ===
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of client who sent this message
"engines": ["Clients", "Bookmarks", ...] // Optional list of engines to sync
}
</pre>

CloudServices/Notifications/Specification/ClientAgent

2011-04-08T22:01:00Z

Sdasilva: /* Scenario 4: Broadcast to Other Clients */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenario 1: New (Potentially First) Client =

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

= Scenario 2: New Subscription =
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app (see Scenario Alpha).
</li>
</ol>

= Scenario 3: Terminate Subscription =

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

= Scenario 4: Broadcast to Other Clients =
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body":"{\"IV\":\"IV in Base 64\",...",
"HMAC":"BASE64=="
}
S: HTTP/1.1 200 OK
</pre></li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre></li>

<li>Ciphertext is the payload encrypted with the client key using AES-256-CBC and base64 encoded. For example:
<pre>
{
"type":"send_tab",
"client_id":"base64url==", // Sync client ID
"url":"...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo":{serialized tab info} // optional
"tabinfo":[{"url":"...", "title":"...", "formdata":"..."}] // optional
}
</pre>
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

== Broadcast Messages ==

Each broadcast message is encrypted and contained entirely within the ciphertext attribute of the message body. The following is a list of the type of broadcast messages supported by clients.

=== Send Tab To Client ===
Copies a tab from one client and sends it to another client.
<pre>
{
"type": "send_tab",
"client_id": "BASE64==", // Sync client ID
"url": "...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo": {serialized tab info} // optional
"tabinfo": [{"url":"...", "title":"...", "formdata":"..."}] // optional (still needs specing)
}
</pre>

=== Sync Now ===
Send a message to clients indicating that important data has been synced, and so all clients should sync ASAP.
<pre>
{
"type": "sync_now",
"sender_id": "BASE64==", // Sync client ID of sender
}
</pre>

CloudServices/Notifications/Specification/ClientAgent

2011-03-31T17:14:29Z

Sdasilva: /* Scenario 4: Broadcast to Other Clients */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenario 1: New (Potentially First) Client =

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

= Scenario 2: New Subscription =
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app (see Scenario Alpha).
</li>
</ol>

= Scenario 3: Terminate Subscription =

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

= Scenario 4: Broadcast to Other Clients =
<ol>
<li>Client broadcasts message to other clients of the authorized user. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body":"{\"IV\":\"IV in Base 64\",...",
"HMAC":"BASE64=="
}
S: HTTP/1.1 200 OK
</pre></li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre></li>

<li>Ciphertext is the payload encrypted with the client key using AES-256-CBC and base64 encoded. For example:
<pre>
{
"type":"send_tab",
"client_id":"base64url==", // Sync client ID
"url":"...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo":{serialized tab info} // optional
"tabinfo":[{"url":"...", "title":"...", "formdata":"..."}] // optional
}
</pre>
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

CloudServices/Notifications/Specification/ClientAgent

2011-03-31T17:13:52Z

Sdasilva: /* Scenario 4: Broadcast to Other Clients */

The Client Agent supports an RPC-like API which allows clients to register themselves with the notification service, as well as create and remove subscriptions to web app notifications.

= Scenario 1: New (Potentially First) Client =

<ol>
<li>
Client registers with Client Agent
<pre>
C: POST /1.0/new_queue HTTP/1.1
C: Authorization: Basic BASE64==
</pre>
</li>

<li>
Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.
<pre>
S: HTTP/1.1 200 OK
S:
S: {"host":"amqp.services.mozilla.com",
"port":5672,
"queue_id": "ASCII (max 255 chars)"}
</pre>
</li>

<li>
Client records CID.
</li>

<li>
Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:
<pre>
{ "T in Base64": {
"app_name": "GMail",
"app_host": "mail.google.com",
"app_account": "sdasilva@gmail.com", // Optional
"key": "BASE64=="
},
"T2 in Base64": {...}
}
</pre>
</li>
</ol>

= Scenario 2: New Subscription =
<ol>
<li>
Client generates symmetric key ''K'' = 256 random bits AES and and token ''T'' = 256 random bits.
</li>

<li>
Client registers token ''T'' with Client Agent.
<pre>
C: POST /1.0/new_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent subscribes User Exchange to token ''T''.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>

<li>Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
</li>

<li>Client passes key ''K'', token ''T'', and POST Office URL to web app (see Scenario Alpha).
</li>
</ol>

= Scenario 3: Terminate Subscription =

<ol>
<li>
Client tells Client Agent to remove subscription with specified token ''T''.
<pre>
C: POST /1.0/remove_subscription HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {"token": "T in Base 64"}
</pre>
</li>

<li>
Client Agent removes binding ''T'' from User Exchange.
<pre>
S: HTTP/1.1 200 OK
</pre>
</li>
</ol>

= Scenario 4: Broadcast to Other Clients =
<ol>
<li>Client broadcasts message to other clients. The format is very similar to that of the POST Office API.
<pre>
C: POST /1.0/broadcast HTTP/1.1
C: Authorization: Basic BASE64==
C:
C: {
"body":"{\"IV\":\"IV in Base 64\",...",
"HMAC":"BASE64=="
}
S: HTTP/1.1 200 OK
</pre></li>

<li>Body is a JSON serialization of:

<pre>
{
"timestamp": ######## (in seconds UTC), // Optional,
"ttl": ######## (in seconds), // Optional
"ciphertext": "BASE64==",
"IV": "BASE64==",
}
</pre></li>

<li>Ciphertext is the payload encrypted with the client key using AES-256-CBC and base64 encoded. For example:
<pre>
{
"type":"send_tab",
"client_id":"base64url==", // Sync client ID
"url":"...",
// implement either one of the following fields to transfer tab history and form data
"moztabinfo":{serialized tab info} // optional
"tabinfo":[{"url":"...", "title":"...", "formdata":"..."}] // optional
}
</pre>
</li>

<li>Client Agent routes the notifications to the appropriate user exchange.</li>
</ol>

CloudServices/Meetings/2011-03-29

2011-03-29T16:15:10Z

Sdasilva: /* Notifications (Shane/Alex) */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, Warp Core
|confId=8616
}}

= Technical =

== Ops ==
...is awesome.

== Engineering ==

=== Python Sync Server (Tarek) ===

Coordination:
* waiting for proper bench environment from ops

=== Python Reg Server (Tarek) ===

Coordination:
* waiting for ops plans on pushing to prod (after storage server I guess)

=== PHP Sync Server (Toby) ===

=== Identity Server (JR/rnewman) ===
Done:

* unpack/setup
* tried to fix login test (can't figure out how to remove beaker session cookie)
* rebuild of web4 (and assoc. make file)
* Styling of login, authorize pages.
* update deployment Makefile (accidentally broke dev deployment)
* initial flake8 fixes to code
* prelim. security review for ID server
* resolve bug with IAR returns
* finished rough version of the user info page (allow user control of cookies, etc.)

Next:

* figure out beaker session issue (remove login cookie)
* code review of ID server (yes, I'm behind on this.)

Coordination:

* work with apps team to make sure they can understand/use current code.
* work with thunder to ensure that demo script works as intended/planned.

=== F1 (Share) (Philipp/Tarek) ===

* client-side
** Released 0.8.2 add-on
*** restartless
*** moved button from toolbar to location bar
** Integrated into Firefox
*** m-c project branch: https://hg.mozilla.org/users/pweitershausen_mozilla.com/fx-share/
** Next
*** split web bits off into https://github.com/mozilla/client-share-web
*** implement new APIs
*** write tests
*** waiting on UX for final UI
** WE HAVE TWO WEEKS TO LAND
* server-side
** done
*** split the oauth lib as a standalone pylons-free lib
*** code is now tested (63%),
*** started the services status DB
** next
*** more tests
*** remove pylons in the web app
*** work in pylibmc

=== Firefox Home (Stefan) ===

=== Sync Client (rnewman) ===

=== Notifications (Shane/Alex) ===
* Ready for presentation/demo today @ 3PM
* Will incorporate feedback from presentation in future iterations
* Meeting with Toby/Philipp sometime after demo to discuss future steps

= QA =

= Metrics =

= Product =

= Security =

= Marketing =

= Roundtable =

== Notes and actions ==

== Follow ups from last week ==

=== Other issues ===

CloudServices/Meetings/2011-03-15

2011-03-15T16:18:44Z

Sdasilva: /* Notifications (Shane/Alex) */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, Warp Core
|confId=8616
}}

= Technical =

== Ops ==
* SCL status
** Py out, PHP in
** DB deadlock preventer
** Capacity status
*** We can spool up enough machines to *at least* handle all of what's in PHX now.
*** 72 DBs total, 5 live right now.
*** Still capacity testing (next to prod)
* Reminder -- Ops is in "lock down" until at least 24 Mar 2011

== Engineering ==

=== Python Sync Server (Tarek) ===

=== Python Reg Server (Tarek) ===

=== PHP Sync Server (Toby) ===

* Reverting to PHP in SCL for FF4 launch
* Working on infra scripts that were abandoned due to Python changeover
* Indexes in production do not match the ones in stage or documented in code. This includes PHX (SCL ones were way off)
** Unclear if this is a problem - is cheaper write load offsetting lack of a range index?

=== Identity Server (JR/rnewman) ===
Done:
* added new functions for latest rev of spec
* added new test cases
* Worked on milestones for latest rev https://wiki.mozilla.org/MozillaID#Releases.2FRoadmap with etherpad at http://etherpad.mozilla.com:9000/Y6PJYj9Oa8
* Worked with rnewman to get FE Library running.
* Talked with petef re: ops (provided initial schema for data storage considerations)
* put together draft timeline for M1 & M2

Next:
* Continue work on M1 tasks.
* Continue work with rnewman re: JS Lib interface.
* move everybody else's crap to the new digs?

=== Firefox Home (Stefan) ===

=== Sync Client (Philipp ===

=== Notifications (Shane/Alex) ===
* End-to-end crypto fully functional
* Working on harnessing test framework for client-side code
* Waiting on ops to set up a VM to use as a demo server
* Building demo web apps to run on VM once set up

= QA =
* Working on a Sync testing helpful tips video for QMO.
* Let us know if you need testing for anything in particular this week.

= Metrics =

= Product =

= Security =

= Marketing =

* Desktop video for launch: https://videos.mozilla.org/manage/marketing/foxy3300.mp4
* Setup video being updated
* Launch blog post: http://etherpad.mozilla.com:9000/sync-launch-post

= Roundtable =

== Notes and actions ==

== Follow ups from last week ==

* By next meeting we should have a project plan for Identity ready for review.
* Fennec Perf - we have done everything we can from Sync's end. Other fixes will need changes to APIs Sync uses (like Password Manager, Places etc).
** MConnor to follow up with Stuart to ensure we're all on the same page.
* <strike>1.7 add-on QA sign off targeting tomorrow (assuming no major issues).</strike> Tested and Shipped
* <strike>Jeff and Tony to figure out sign off process.</strike> Worked it out with team, more notification upfront

=== Fx 4 client ===
=== Fx 4 server ===

=== Other issues ===

CloudServices/Notifications/Specification/ClientAgent

2011-03-10T01:06:26Z

Sdasilva: /* Scenario 1: New (Potentially First) Client */

CloudServices/Meetings/2011-03-08

2011-03-08T17:29:37Z

Sdasilva: /* Notifications (Shane/Alex) */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, Warp Core
|confId=8616
}}

= Technical =

== Ops ==

=== SCL2 work ===

=== Upcoming production work ===

== Engineering ==

=== Account Management Portal (Toby) ===
Done. Live. Woot!

=== Next-gen Reg/Sync Server (Tarek) ===

=== PAKE server (Tarek) ===

=== Identity Server (JR) ===
Done:
* Handed over spec to Thunder for refinements and additions. (Published publicly
* coded mongo db interfaces, & test cases. Built prelim. server API (continuing test cases)
* Various ID discussions with rnewman & thunder

Next:
* finish test cases
* talk with petef re: opt. db server deployment
* add latest spec deltas

=== Firefox Home 2.0 ===

First rough demo on http://fxho.me .. contains both live sync data and fake data.

Later today first meeting to figure out a more concrete plan for version 1.0.

=== Fennec performance issues (philipp) ===

* Killed most history events >150ms
* Broke up long blocking password and form events into smaller chunks. They're now bound by the synchronous I/O which is in the 500-2000ms range.
* Pretty much any improvement at this point requires platform API support, e.g.:
** async bulk APIs for forms, passwords, bookmarks
** improved API for history (less callbacks, accept strings instead of nsIURI, etc.)
** tailoured crypto API to encrypt and sign records

=== Fx4 Sync Blockers (philipp/rnewman) ===

* Our last Fennec blockers landed on m-c last night.
* fx-sync is on its way to retirement, for add-on bugfixes only. Long live services-central!

=== Notifications (Shane/Alex) ===
* Full-circle workflow is now fully functional
* Sync key exchange on multiple clients
* Currently wrapping up encryption and HMAC support

= QA =
* Testing 1.7; extension and interaction with Fx4

= Metrics =

= Product =

* Planning currently underway for Fx 5 and beyond within Product team. See #services for link.
* Expect conversations around this in the upcoming days to jump start projects.

= Security =

= Marketing =

= Roundtable =

== Notes and actions ==

* SCL2 roll out went well. We have a few thousand users now.
* Account portal is up and live.
* PHX firewall issue is being monitored, not expected to have major impact on Sync users.
*

== Follow ups from last week ==

* SCL2 should be ready to take on live users this week (target: Wed)
* Load tests are being run right now. Target for initial sync is 100K/hour.
* Account Portal is going to be launched in production today and be user facing either Wed/Thurs.
* Tomorrow's nightly is a good target for all the perf fixes to be tested by a wider audience.
* March 15 is the target readiness date.
* General consensus around the room that everyone is good and confident with that date.
* An add-on update will be required to be completed by 3/15 as well to bring add-on users up to the latest sync changes and also auto disable itself on Fx 4.

=== Fx 4 client ===
=== Fx 4 server ===

=== Other issues ===

CloudServices/Meetings/2011-03-08

2011-03-08T17:27:22Z

Sdasilva: /* Notifications (Shane/Alex) */

{{MeetingInfo
|dayOfWeek=Tuesday
|est=12:15 PM
|pst=9:15 AM
|utc=5:15 PM
|room=Mozilla HQ, Warp Core
|confId=8616
}}

= Technical =

== Ops ==

=== SCL2 work ===

=== Upcoming production work ===

== Engineering ==

=== Account Management Portal (Toby) ===
Done. Live. Woot!

=== Next-gen Reg/Sync Server (Tarek) ===

=== PAKE server (Tarek) ===

=== Identity Server (JR) ===
Done:
* Handed over spec to Thunder for refinements and additions. (Published publicly
* coded mongo db interfaces, & test cases. Built prelim. server API (continuing test cases)
* Various ID discussions with rnewman & thunder

Next:
* finish test cases
* talk with petef re: opt. db server deployment
* add latest spec deltas

=== Firefox Home 2.0 ===

First rough demo on http://fxho.me .. contains both live sync data and fake data.

Later today first meeting to figure out a more concrete plan for version 1.0.

=== Fennec performance issues (philipp) ===

* Killed most history events >150ms
* Broke up long blocking password and form events into smaller chunks. They're now bound by the synchronous I/O which is in the 500-2000ms range.
* Pretty much any improvement at this point requires platform API support, e.g.:
** async bulk APIs for forms, passwords, bookmarks
** improved API for history (less callbacks, accept strings instead of nsIURI, etc.)
** tailoured crypto API to encrypt and sign records

=== Fx4 Sync Blockers (philipp/rnewman) ===

* Our last Fennec blockers landed on m-c last night.
* fx-sync is on its way to retirement, for add-on bugfixes only. Long live services-central!

=== Notifications (Shane/Alex) ===
* Full-circle workflow is now fully functional
* Sync key exchange on multiple clients
* Encryption and HMAC support almost done

= QA =
* Testing 1.7; extension and interaction with Fx4

= Metrics =

= Product =

* Planning currently underway for Fx 5 and beyond within Product team. See #services for link.
* Expect conversations around this in the upcoming days to jump start projects.

= Security =

= Marketing =

= Roundtable =

== Notes and actions ==

== Follow ups from last week ==

* SCL2 should be ready to take on live users this week (target: Wed)
* Load tests are being run right now. Target for initial sync is 100K/hour.
* Account Portal is going to be launched in production today and be user facing either Wed/Thurs.
* Tomorrow's nightly is a good target for all the perf fixes to be tested by a wider audience.
* March 15 is the target readiness date.
* General consensus around the room that everyone is good and confident with that date.
* An add-on update will be required to be completed by 3/15 as well to bring add-on users up to the latest sync changes and also auto disable itself on Fx 4.

=== Fx 4 client ===
=== Fx 4 server ===

=== Other issues ===