Re: Proposed data channel API

(As individual):

I am having some problem to decide what I think of this proposal.

My initial feeling was that there is no role for the DataStream 
interface. We have MediaStreams, but those are different since they are 
not produced by the application (but by e.g. microphones and cameras) 
nor consumed by the application (but by media elements). Basically they 
are there to give the application some means to control stuff that is 
produced and consumed in lower layers.

With data it is different. The application produces ('send') and 
consumes data ('onmessage') directly, so having an object outside 
PeerConnection makes little sense. Further, things like priority has no 
meaning (?) outside the actual transport.

So far my thinking was in the direction that the data channel should be 
in a PeerConnection only. We could have things like 'setupData', 'send' 
methods with different channels, priority and reliability as options, 
bufferedAmount attributes to read an so on. Basically it would be 
similar to WebSockets, with the addition of channels, priority and a 
non-reliable mode.

What made me think again was re-reading the Streams API proposal 
<http://html5labs.interoperabilitybridges.com/streamsapi/>, explained a 
bit more in 
<http://lists.w3.org/Archives/Public/public-webapps/2011JulSep/1569.html>. 
Here a proposal on more advanced stream functionalities is outlined. 
Basically the core is a Stream (meaning an object that has unspecified 
length), a Stream can be dealt with using StreamBuilders and StreamReaders.

If this is the direction we should go, then there is definitely a role 
for a DataStream interface, but perhaps it should be extended a bit (to 
be more similar to the Stream API).

What do others think?

Br,
Stefan

On 11/01/2011 09:49 PM, Justin Uberti wrote:
> The document at the link below has been updated with feedback from
> yesterday's discussion, specifically:
> - initial section on security added
> - minor changes to make DataStream more like WebSockets
> (sendMessage->send, added bufferedAmount)
> - Added DataStream ctor
>
> Open issues:
> - Use case for acking of unreliable sends
> - onReadyToSend: WebSockets requires polling to determine when
> bufferedAmount == 0. The onReadyToSend callback provides a way to handle
> this more cleanly, and it's optional, so I'm reluctant to remove it.
>
> On Mon, Oct 31, 2011 at 12:50 AM, Justin Uberti <juberti@google.com
> <mailto:juberti@google.com>> wrote:
>
>     https://docs.google.com/document/pub?id=16csYCaHxIYP83DzCZJL7relQm2QNxT-qkay4-jLxoKA
>     *
>     *
>
>     A proposal
>     for<http://dev.w3.org/2011/webrtc/editor/webrtc.html>http://dev.w3.org/2011/webrtc/editor/webrtc.html,
>     to discuss in tomorrow's TPAC meeting.
>
>
>           5 The data stream
>
>     In addition to the MediaStreams defined earlier in this document,
>     here we introduce the concept of DataStreams for PeerConnection.
>     DataStreams are bidirectional p2p channels for real-time exchange of
>     arbitrary application data in the form of datagrams. DataStreams can
>     either be reliable, like TCP, or unreliable, like UDP, and have
>     built-in congestion control, using a TCP-fair congestion control
>     algorithm.
>
>     DataStreams are created via the new PeerConnection.createDataStream
>     method. This method creates a new DataStream object, with specified
>     "label" and "reliable" attributes; these attributes can not be
>     changed after creation. DataStreams can then be added to a
>     PeerConnection, much in the same way that MediaStreams are added.
>     Since the semantics of the existing addStream API don't fit
>     perfectly here (i.e. MediaStreamHints), we add the new addDataStream
>     and removeDataStream APIs for this purpose. As with
>     addStream/removeStream, these APIs update the internal session
>     description of the PeerConnection, and cause a new offer to be
>     generated and signaled through the PeerConnection signaling
>     callback. Note that there is no requirement to add a MediaStream
>     first before adding a DataStream; rather, it is expected that many
>     uses of PeerConnection will be solely for application data exchange.
>
>     Like MediaStreams, multiple DataStreams can be multiplexed over a
>     single PeerConnection. Each DataStream has a priority, which
>     indicates what preference should be given to each DataStream when a
>     flow-control state is entered. DataStreams with the highest priority
>     are given the first notification and ability to send when flow
>     control lifts.
>
>     In reliable mode, in-order delivery of messaging is guaranteed,
>     which implies head-of-line blocking. In unreliable mode, messages
>     may arrive out of order. In either mode, notifications of message
>     delivery are communicated to the application via a callback; in
>     unreliable mode, failures (defined as an elapsing of 2 RTT without
>     an acknowledgement) are communicated through the same callback.
>
>     There is no maximum size to a datagram that can be sent over the
>     data stream. However, messages are not interleaved on the wire, so a
>     very large message will prevent other messages from being sent until
>     its own send completes.
>
>     Encryption of the data stream is required. It is expected that
>     applications that support DataStreams will support DTLS and
>     DTLS-SRTP; while SDES-SRTP, or plain old RTP may be supported for
>     legacy compatibility, there is no need to support DataStreams in
>     these scenarios.
>
>     In this draft, there is no inheritance relationship between
>     MediaStream and DataStream, which is intentional due to the lack of
>     a "is-a" relationship. However, it may make sense to hoist a Stream
>     ancestor class for both MediaStream and DataStream, which would
>     allow many of the existing PeerConnection APIs (localstreams,
>     remotestreams, onaddstream, onremovestream, maybe removeStream) to
>     refer to a Stream instead of the MediaStream that they currently
>     reference. This would eliminate the need for "data" variants of all
>     the aforementioned functions.
>
>
>             5.1 Changes to PeerConnection
>
>     interface PeerConnection {
>
>         [...]
>
>         // Creates a data stream, either reliable or unreliable.
>
>         // Reliability cannot be changed for a stream after it is created.
>
>         DataStream createDataStream(in DOMString label, in boolean
>     reliable);
>
>         // Adds a datastream to this PeerConnection. Will trigger new
>     signaling.
>
>         void add
>     <http://dev.w3.org/2011/webrtc/editor/webrtc.html#widl-PeerConnection-addStream-void-MediaStream-stream-MediaStreamHints-hints>DataStream
>     <http://dev.w3.org/2011/webrtc/editor/webrtc.html#widl-PeerConnection-addStream-void-MediaStream-stream-MediaStreamHints-hints> (in
>     DataStream
>     <http://dev.w3.org/2011/webrtc/editor/webrtc.html#idl-def-MediaStream> stream);
>
>         // Removes a datastream from this PeerConnection. Will trigger
>     new signaling.
>         void removeDataStream
>     <http://dev.w3.org/2011/webrtc/editor/webrtc.html#widl-PeerConnection-removeStream-void-MediaStream-stream> (in
>     DataStream
>     <http://dev.w3.org/2011/webrtc/editor/webrtc.html#idl-def-MediaStream> stream);
>
>         [...]
>     };
>
>
>             5.2 The DataStream interface
>
>     interface DataStream {
>
>         // Label, like MediaStream's |label|.
>
>         // Maps to a lower-level stream identifier.
>         readonly attribute DOMString label;
>
>         // Whether this stream has been configured as reliable.
>
>         readonly attribute boolean reliable;
>
>         // The relative priority of this stream.
>
>         // If bandwidth is limited, higher priority streams get preference.
>
>         // Default priority is zero.
>
>         attribute long priority;
>
>         // States, as in MediaStream.
>         const unsigned short LIVE = 1;
>
>         const unsigned short ENDED = 2;
>         readonly attribute unsigned short readyState;
>         attribute Function onReadyStateChange;
>
>         // Sends the supplied datagram.
>
>         // Returns a nonnegative message id if the send was successful.
>
>         // Returns -1 if the stream is flow-controlled.
>
>         long sendMessage(in DOMString message);
>
>         // Called when a message is received.
>
>         // Arguments: DOMString message
>
>         attribute Function onMessage;
>
>         // Called when flow control lifts for this stream.
>
>         // Arguments: None
>
>         attribute Function onReadyToSend;
>
>         // Called when a message has been delivered (or lost, if
>     unreliable).
>
>         // Arguments: long id, bool success
>
>         attribute Function onSendResult;
>     }
>
>
>             5.3 Example
>
>     // standard setup from existing example
>     var local = new
>     PeerConnection('TURNS<http://example.net/>example.net
>     <http://example.net/>', sendSignalingChannel);
>
>     // create and attach a data stream
>     var aLocalDataStream = local.createDataStream("myChannel", false);
>
>     local.addDataStream(aLocalDataStream);
>
>     // outgoing SDP is dispatched, including a media block like:
>
>          m=application 49200 <TBD> 127
>
>          a=rtpmap:127 application/html-peer-connection-data
>
>     // this SDP is plugged into the remote onSignalingMessage, firing
>     onAddStream
>
>     [remote] onAddStream(aRemoteDataStream);
>
>     // signaling completes, and the data stream goes active on both sides
>
>     [local] onReadyToSend();
>
>     [remote] onReadyToSend();
>
>          // we start sending data on the data stream
>
>     var id = aLocalDataStream.send("foo");
>
>     // the message is delivered
>
>     [remote] onMessage("foo");
>
>     // the result is communicated back to the sender
>
>     [local] onSendResult(id, true);
>
>     // the data stream is discarded
>
>     local.removeDataStream(aLocalDataStream)
>
>     // new signaling is generated, resulting in onRemoveStream for the
>     remote
>
>     [remote] onRemoveStream(aRemoteDataStream);
>
>
>             5.4 Implementation notes
>
>     It is intended that this API map to the wire protocol and layering
>     being defined in the IETF RTCWEB WG for the data channel. One
>     current proposal for said protocol is
>
>     http://www.ietf.org/id/draft-jesup-rtcweb-data-00.txt, which is
>     believed to match the requirements of this API.
>
>

Received on Monday, 7 November 2011 13:04:06 UTC