CloudServices/Notifications/Specification/ClientAgent

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

1. Client registers with Client Agent

   C: POST /1.0/new_queue HTTP/1.1
   C: Authorization: Basic BASE64==
   

2. Client agent generates Client ID (CID), creates User Exchange if necessary, creates and binds Client Queue CID, returns CID to Client.

   S: HTTP/1.1 200 OK
   S:
   S: {"host":"amqp.services.mozilla.com",
       "port":5672,
       "queue_id": "ASCII (max 255 chars)"}
   

3. Client records CID.
4. Client fetches notifications/subscriptions WBO from Sync, decrypts with sync key. This returns the following (encrypted) JSON:

   { "T in Base64": {
       "app_name": "GMail", 
       "app_host": "mail.google.com", 
       "app_account": "sdasilva@gmail.com",  // Optional
       "key": "BASE64=="
     },
     "T2 in Base64": {...}
   }
   

Scenario 2: New Subscription

1. Client generates symmetric key K = 256 random bits AES and and token T = 256 random bits.
2. Client registers token T with Client Agent.

   C: POST /1.0/new_subscription HTTP/1.1
   C: Authorization: Basic BASE64==
   C:
   C: {"token": "T in Base 64"}
   

3. Client Agent subscribes User Exchange to token T.

   S: HTTP/1.1 200 OK
   

4. Client uploads new notifications/subscriptions WBO to Sync (see Scenario 1, Step 4).
5. Client passes key K, token T, and POST Office URL to web app (see Scenario Alpha).

Scenario 3: Terminate Subscription

1. Client tells Client Agent to remove subscription with specified token T.

   C: POST /1.0/remove_subscription HTTP/1.1
   C: Authorization: Basic BASE64==
   C: 
   C: {"token": "T in Base 64"}
   

2. Client Agent removes binding T from User Exchange.

   S: HTTP/1.1 200 OK
   

Scenario 4: Broadcast to Other Users

1. Client tells another Client to open a tab through the Client Agent with the client id ID.

   
   C: POST /1.0/broadcast HTTP/1.1
   C: Authorization: Basic BASE64==
   C: 
   C: body  ciphertext{ ....
                        "type": "send_tab",
                        "client_id" : BASE64 ==,
                        "url": "...",
                        "fxtabinfo": "..." / "tabinfo" : {abstract data}
                      }
   
   

2. Client Agent puts this notification in the appropriate queues for a client.