WebAPI/Inter App Communication Alt proposal

Description

This proposal is just a tweaked version of the Inter App Communication API. Its description, intend and use cases do not defer from the previous proposal, only the API does.

API

Caller

 partial interface Application {
   // The returned Promise will be resolved if at least one peer is
   // allowed to connect with the application and will contain in that
   // case an array of MessagePort, each of them representing a peer
   // that allowed the connection.
   // If no peer is allowed to connect with the app, the Promise will
   // be rejected.
   Promise connect(DOMString keyword, object rules);
 
   // The returned Future will contain true if at least a peer is allowed
   // to communicate with the application, false otherwise.
   Promise connectionRegistered(DOMString keyword);
   
   Promise getConnectionMessages(DOMString keyword);
 };

where

• keyword is the key string subject of the connection. Only apps advertising themselves as able to connect through this keyword will receive a connection request (if the user allows to and the app fulfills the requirements specified in the rules argument).
• rules is an object containing a set of constraints for the requested connection. Only apps fulfilling these constraints will receive a connection request. These rules may contain:
  • minimumAccessLevel is the minimum level of access (one of https://developer.mozilla.org/en-US/docs/Web/Apps/Manifest#type) that the receiver app requires in order to be able to receive the connection request.
  • origin (array) can be used to set specific receiverers by a list of origins.
  • installOrigin (array) list of install origins. Only apps with an install origin listed within this field will receive a connection request.
  • developer (array) list of objects identifying app authors whose apps are allowed to receive a connection request.

Receiver

Applications can advertise themselves as able to connect given an specific keyword by adding an entry named connect in the manifest containing an object list where each object represents the description and details of each potential connection.

 {
   'name': 'Foobar application',
   /* ... */
   'connect': {
     'keyword1': {
       'handler_path': '/handler1.html',
       'description': 'Do something for keyword1 connection'
     },
     'keyword2': {
       'handler_path': '/handler2.html',
       'description': 'Do something for keyword2 connection',
       'defer': false
     }
   }
 }

where

• handler_path is the path of the page where the handler of the connection request lives in the app's code. If 'handling_path' is absent, the 'launch_patch' will be taken as default.
• description is the message to be shown to the user during the connection request that should describe why the connection is required and what does the app intends to do within that connection.
• defer is a flag to allow apps to be woken up because of a connection request. If 'defer' is not present, it will default to true. The 'defer' value will be ignored if the connection has not being previously accepted by the receiver and the user.

Connection acknowledgement

Applications that have the required minimum level of access specified in the .connect() call and have explicitly been allowed by the user to connect with the caller application will receive a system message named 'connect' containing a ConnectionRequest object of this form as a message.

 Dictionary ConnectionRequest {
   MessagePort port;
   DOMString   keyword;
   object      callerInfo;
 };

where

• port is an instance of MessagePort that will be the message channel for the connection.
• keyword is the key string given with the .connect() call.
• callerInfo is an object containing basic information about the app requesting the connection channel. This information will allow the receiver to decide if the connection is secure enough or not. It may contain the following data (TODO: we need to decide which data do we want to provider. We might want to provide the whole caller app manifest):
  • origin which is the origin of the app requesting the connection.
  • installOrigin which is the origin from where the app requesting the connection was installed.
  • accessLevel which is the access level of the app requesting the connection.
  • developer which contains the information about the developer of the app requesting the connection. It may contain the name and url of the developer.

MessagePort

A MessagePort is the channel that connects two apps and allow them to send and receive messages.

  interface MessagePort {
   void postMessage(...);
   attribute object onmessage;
 };

Defer mechanism

TODO

Offline message queues

TODO

Usage examples

Lockscreen and Music

(Disclaimer: this is just a rough example of a possible solution for this use case)

The lockscreen wants to be able to control the music played by the Gaia Music app or any other 3rd party music app installed from the Firefox Marketplace and show its currently played track.

In order to receive information about the currently played music track, the System app needs to add the following 'connect' field to its manifest

{
   'name': 'System',
   /* ... */
   'connect': {
     'musictrack': {
       'description': 'Show the currently played music track information in the lockscreen'
     }
   }
}

where it advertises itself as able to receive connection requests through the 'musictrack' keyword.

On the other side, music apps (lets say the Gaia Music app, a fictitious Songbirdy app installed from the Firefox Marketplace and an also fictitious iTunos app installed from an unknown source) that wants to be controlled from the lockscreen should add the following 'connect' field to its manifest:

 {
   'name': 'Music', (or Songbirdy or iTunos)
   'description': 'Gaia Music app', (or whatever description for the other music apps)
   /* ... */
   'connect': {
     'musicremotecontrol': {
       'description': 'Play, pause and stop music tracks'
     }
   }
 }

TODO

Other use case

TODO

Open Questions

• Should we change 'connect' verbs for 'pub/sub' verbs? Like

 partial interface Application { 
   Promise publish(DOMString keyword, object rules);
 
   Promise subcriptionsRegistered(DOMString keyword);
   
   Promise getSubcriptionMessages(DOMString keyword);
 };