[whatwg] ConnectionPeer experiences

[Patrik Persson J]

We have done some experimentation with the ConnectionPeer API. We have
an initial implementation of a subset of the API, using ICE (RFC 5245)
for the peer-to-peer handshaking.  Our implementation is
WebKit/GTK+/gstreamer-based, and we of course intend to submit it to
WebKit, but the implementation is not quite ready for that yet.

More information about our work so far can be found here:
https://labs.ericsson.com/developer-community/blog/beyond-html5-peer-peer-conversational-video

However, we have bumped into some details that we'd like to discuss
here right away.  The following is our mix of proposals and questions.

1. We propose adding a readyState attribute, to decouple the
   onconnect() callback from any observers (such as the UI).

      const unsigned short CONNECTING = 0;
      const unsigned short CONNECTED = 1;
      const unsigned short CLOSED = 2;
      readonly attribute unsigned short readyState;

2. We propose replacing the onstream event with custom events of type
   RemoteStreamEvent, to distinguish between adding and removing
   streams.

      attribute Function onstreamadded;   // RemoteStreamEvent
      attribute Function onstreamremoved; // RemoteStreamEvent
      ...
      interface RemoteStreamEvent : Event {
         readonly attribute Stream stream;
      };

   The 'stream' attribute indicates which stream was added/removed.

3. We propose renaming addRemoteConfiguration to
   setRemoteConfiguration.  Our understanding of the ConnectionPeer is
   that it provides a single-point-to-single-point connection; hence,
   only one remote peer configuration is to be set, rather than many
   to be added.

      void setRemoteConfiguration(in DOMString configuration, in optional DOMString remoteOrigin);

4. We propose swapping the ConnectionPeerConfigurationCallback
   callback parameters. The current example seems to use only one (the
   second one).  Swapping them allows clients that care about 'server'
   to do so, and clients that ignore it (such as the current example)
   to do so too.

      [Callback=FunctionOnly, NoInterfaceObject]
      interface ConnectionPeerConfigurationCallback {
         void handleEvent(in DOMString configuration, in ConnectionPeer server);
      };

5. Should a size limit to text messages be specified? Text messages
   with UDP-like behavior (unimportant=true) can't really be reliably
   split into several UDP packets.  For such long chunks of data, file
   transfer seems like a better option anyway.

In summary, then, our proposal for a revised ConnectionPeer looks as follows:

   [Constructor(in DOMString serverConfiguration)]
   interface ConnectionPeer {
      void sendText(in DOMString text, in optional boolean unimportant); // if second arg is true, then use unreliable low-latency transport (UDP-like), otherwise guarantee delivery (TCP-like)
      attribute Function ontext; // receiving

      void sendBitmap(in HTMLImageElement image);
      attribute Function onbitmap; // receiving

      void sendFile(in File file);
      attribute Function onfile; // receiving

      void addStream(in Stream stream, in optional DOMString metadata, in optional String mediaFormat);
                               //Start stream, add meta data and encoding parameters
      void removeStream(in Stream stream);
      readonly attribute Stream[] localStreams;
      readonly attribute Stream[] remoteStreams;

      attribute Function onstreamadded; // receiving new stream
      attribute Function onstreamremoved; // stream not received any more

      void getLocalConfiguration(in ConnectionPeerConfigurationCallback callback); // maybe this should be in the constructor, or be an event
      void setRemoteConfiguration(in DOMString configuration, in optional DOMString remoteOrigin); // remote origin is assumed to be same-origin if not specified. If specified, has to match remote origin (checked in handshake). Should support leading "*." to mean "any subdomain of".
      void close(); // disconnects and stops listening

      attribute Function onconnect;
      attribute Function onerror;
      attribute Function ondisconnect;

      const unsigned short CONNECTING = 0;
      const unsigned short CONNECTED = 1;
      const unsigned short CLOSED = 2;
      readonly attribute unsigned short readyState;
   };

   interface RemoteStreamEvent : Event {
      readonly attribute Stream stream;
   };

   [Callback=FunctionOnly, NoInterfaceObject]
   interface ConnectionPeerConfigurationCallback {
      void handleEvent(in DOMString configuration, in ConnectionPeer server);
   };

What do you think?

In addition to the above there is a need to add support for
identifying streams (so that the receiving end can use the right
element for rendering) and for influencing the media format.  Those
parts we're still working on.

--
   Patrik Persson, Ericsson Research
   mailto:patrik.j.persson at ericsson.com