[RTW] peer-to-peer connection API thoughts

[Matthew Kaufman]

On 1/7/2011 5:03 AM, Harald Alvestrand wrote:
>
>
> For very simple applications, this might be a sufficient API. But even 
> if the object is magical, I think its API has to be quite a bit richer 
> - in particular, when the state of the connection changes (failover to 
> new connections, data doesn't flow any more, data suddenly flows a 
> great deal faster than before) the changes have to be signalled back 
> (using callbacks?) to the client Javascript so that appropriate user 
> interface events can happen.
>
> When I yank out my network cable, and don't have wireless, I expect an 
> error message saying "connection lost"; I don't expect things to just 
> freeze.

Agreed. I had left out all the status events and adjustment knobs... 
trying to just get connection establishment happening.

> So the extended API for establishing a connection would be something like
>
>   var connection = new PeerConnection(destinationSpecifier, 
> changeCallback, deathCallback, ....)
>

In JavaScript you'd just have the destinationSpecifier and then assign 
event handlers to the "connection" instance of the PeerConnection 
object. So:

connection.onDeath = doSomething;

(or in the new way, connection.addEventListener('death', doSomething, 
false); )

>>
>> B. A single connection object which does most of the magic, but with 
>> the low-bandwidth signaling made external though events
>>
>> In this case, the API is the same as above, but rather than providing 
>> in the destiniationSpecifier some sort of server address for the "low 
>> bandwidth signaling" the connection object would instead fire events 
>> containing (essentially opaque to the channel, but in an agreed 
>> format) the data which needed to be transported to the other side. A 
>> corresponding API on the far end's "listening" connection object 
>> would allow for the data to be injected at the far end. The script 
>> implementer would simply need to wire the event up to an existing 
>> transport mechanism (HTTP, WebSockets).
> I'm not familiar enough with this form of API to interpret that - what 
> are these events, where would the events go, and who would handle 
> them? Or are "events" Javascript terminology for what I'm used to 
> calling "callbacks"?

Pretty much, yes. See above.

So you'd have something like:

function sendMessageToOtherEnd(message) {
     ... use an existing WebSocket to your signaling server to send the 
message ...
}

connection.onMessageToOtherEnd = sendMessageToOtherEnd;


>>
>> C. A connection object which does most of the magic, but with a 
>> parent object that is the connection to the signaling mechanism
>>
>> This is the approach Flash Player has taken. The NetConnection is 
>> opened to the rendezvous-handling server (which can also act as a 
>> media relay), NetStreams are then opened either to that relaying 
>> server or directly to other peers. These peer-to-peer NetStreams use 
>> the open NetConnection for the peer setup signaling (determining the 
>> far IP addresses, requesting NAT hole-punching, etc.)
> Interesting - does this mean that one has an overarching object that 
> can relate to multiple streams? Are there multiple streams active at 
> the same time, and if so, what state do they share, and how are they 
> different?

Yes. There's a "NetConnection" which represents the connection to the 
server, and then zero or more NetStreams, each of which is a 
unidirectional flow of media. Some of the NetStreams may represent 
peer-to-peer streams, so either "published locally for consumption by 
peer" or "played from <remote peer-ID>".

>
> Pointers to specs would be welcome!

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/NetConnection.html

and

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/NetStream.html

(The same API is also used by "RTMFP Groups", which is a p2p overlay 
that includes application-level multicast, so you can also publish/play 
NetStreams over the multicast overlay.)


> No more comments on these - good starting thoughts!
>

I'm glad to see that we're starting to make progress on multiple fronts 
here. Shouldn't be long before we can put together some draft specs and 
start refining the details.

Matthew Kaufman