[Telepathy] The XMPP implementation of Tubes

[Simon McVittie]

Terminology: define the "initiator" to be the contact who offered the
tube, and the "non-initiator(s)" to be the other contact(s) in the tubes
channel, who have the opportunity to accept the tube.

On Mon, 13 Aug 2007 at 17:49:46 +0100, Simon McVittie wrote:
> To offer a tube, send a Stream Initiation request with profile
> NS_SI_TUBES or NS_SI_TUBES_OLD (currently, the latter is sent). As per
> XEP-0095_, the SI request must be sent to a full-JID. The resource
> chosen is one that has NS_SI_TUBES or NS_SI_TUBES_OLD advertised as a
> capability in its presence.

Note that the stream set up by this SI request will never be used for
stream tubes, only for D-Bus tubes. For stream tubes, the non-initiator
makes SI requests back to the initiator. Each of these "additional streams"
represents a client connecting to the socket the CM has opened. In response,
the initiator's CM opens parallel connections to the service being offered,
one per additional stream. This is weird.

Guillaume calls this dummy stream, whose SI request establishes the tube
offer, the "default bytestream".

I'm tempted to specify that for D-Bus tubes, the initiator makes one SI
request per D-Bus tube; but that for stream tubes, the initiator sends a
<message> containing a <tube>, and the non-initiator responds with SI
requests.

> It's somewhat vague whether we support opening a 1-1 tubes channel with
> a MUC contact - there is code to support it, but I don't think we put
> capabilities in MUC presence. We should probably rule that it's
> unsupported.

Applying that ruling would also simplify the code for
stream-tubes-in-a-MUC, for what it's worth...

> Responding to a tube offer is as usual for SI. Once the other end has
> agreed to do IBB, we consider the tube to be open.

Possibly we shouldn't consider the tube to be open until the IBB <open>
has been sent.

> Offering a tube
> ---------------
> 
> Put it in your presence.
> 
> I still need to investigate how stream tubes work here.

Putting a D-Bus tube in your MUC presence causes it to spring into
existence. Everyone can immediately send pseudo-IBB <data> marked with
its stream-id, and it is considered to be open.

Putting a stream tube in your MUC presence is equivalent to doing the
"default bytestream" SI request in the 1-1 case - the non-initiators open
individual SI requests back to the initiator, as in the 1-1 case, but using
MUC JIDs instead of individual JIDs. They then push all data through these
1-1 SI streams.

The initiator immediately considers the stream to be open.
Each non-initiator considers the stream to be local-pending, until they
accept the stream, at which point it becomes open.

> :Attributes:
>     stream-id : string
>         In SI tubes, the stream ID that will be used when the IBB
>         stream is eventually opened. In MUC tubes, an arbitrary string
>         which is repeated on the pseudo-IBB messages.

Having written some tubes regression tests, I can now revise this to:

* In MUC D-Bus tubes, the string which will be used as the "sid" on the
  pseudo-IBB messages

* In MUC stream tubes, absent

* In 1-1 D-Bus tubes, a copy of the SI stream ID (which could safely
  disappear, because the <tube> is in the same message as the <si>)

* In 1-1 stream tubes, absent, but there is an "id" attribute (?!) which
  is the same as the SI stream ID; I think it could safely disappear

I propose to remove this attribute, and use the tube ID as an attribute
on the pseudo-IBBs in MUC D-Bus tubes, instead of a session ID.

>     offering : "true" or "false"
>         In SI context, OfferTube maps to offering="true". I'm not quite
>         sure how it can ever have offering="false" or why this is
>         necessary...

This is used to distinguish between the "default bytestream", which has
offering="true", and the additional bytestreams, which have
offering="false". We could use a simpler mechanism, I'm sure, even if we
keep the default/additional thing. For instance, the default bytestream
could be the only one containing a <tube> element, and the additional
bytestreams could be linked to the offer in a lightweight way by having a
tubes:tube-id attribute (where the tubes: prefix has namespace NS_TUBES).

>     dbus-name : D-Bus unique name
>         Required for D-Bus tubes. The unique name the contact whose
>         announcement this is will use in the tube.

That reminds me: I noticed while constructing the test case that
DBusNamesChanged doesn't seem to be emitted for 1-1 tubes. I think
that's a bug.

	Simon