[Telepathy] The XMPP implementation of Tubes

[Simon McVittie]

As part of the review process for the telepathy-gabble-tubes branch,
I've been looking at the XMPP protocol we use to implement Telepathy
Tubes. I think it needs documenting, and it also needs some changes - at
the moment it's a bit of an abuse of IBB.

To start with, I'll just document the current protocol. I'll reply to this
mail with criticisms and proposed changes.

===============================================================================
                            The Tubes protocol
===============================================================================

The draft of the Tubes specification that's implemented in the -tubes
branch can be found at
<http://projects.collabora.co.uk/~smcv/gabble-tubes-as-of-20070813.html>.

In this document, NS_SI_TUBES, NS_SI_TUBES_OLD and NS_TUBES mean
"http://telepathy.freedesktop.org/xmpp/si/profile/tubes",
"http://jabber.org/protocol/si/profile/tubes" and
"http://telepathy.freedesktop.org/xmpp/tubes" respectively.
The use of NS_SI_TUBES_OLD was a mistake (it's not in a namespace we
control, so we shouldn't use it) - wherever this is used, we need
to change it to NS_SI_TUBES.

Tubes can be used in a 1-1 context (for CONTACT tubes channels) or in a MUC
context (for ROOM tubes channels).

Usage in 1-1 context
====================

Opening the channel
-------------------

A 1-1 Tubes channel is opened by request, or when a Stream Initiation
request with profile NS_SI_TUBES or NS_SI_TUBES_OLD is received.

Offering a tube
---------------

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.

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.

We currently support only IBB as a transport.

Accepting a tube
----------------

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.

Sending and receiving data
--------------------------

The messages are sent as specified by IBB.

In the case of D-Bus tubes, each <message> contains (a) an entire
D-Bus message, and (b) no more than one D-Bus message.

In the case of stream tubes, <message> boundaries are arbitrary.

Usage in MUCs
=============

The <tubes> element with namespace NS_TUBES may be added to MUC presence.
Its children are <tube> elements representing those tubes which, in
the Telepathy Tubes spec, are in state Tube_State_Open. This is everyone's
tubes, not just ones we initiated.

Opening a channel
-----------------

A Tubes channel is opened on request, or when a <tubes> is seen in MUC
presence.

Offering a tube
---------------

Put it in your presence.

I still need to investigate how stream tubes work here.

Accepting a tube
----------------

No D-Bus tubes are remote-pending or local-pending at any time - the tube is
considered to be already open as soon as it appears in someone's presence,
so no accepting is ever needed.

I still need to investigate how stream tubes work here.

Sending data
------------

The messages are sent in <message>s as specified by IBB (XEP-0047_), except
that the sequence number @seq is meaningless on output, must be ignored
on input, and no <open> or <close> ever occurs.

The <tube> element
==================

Example::

    <tube stream-id="stream1" type="dbus" initiator="room at conf.example.com/me"
          service="com.example.TextEditor" offering="true" id="1343"
          dbus-name=":0.fhsIUH">
        <parameters>
            <parameter name="filename" type="str">README.txt</parameter>
        </parameters>
    </tube>

: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.
    type : "stream" or "dbus"
        Required. The type of tube.
    initiator : MUC member JID (MUC) / bare JID (SI)
        Required. The initiator of the tube.
    service : D-Bus well-known name
        Required. The D-Bus service name.
    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...

        In MUC context, omitted.
    id : decimal in range 0 to (2**31)-1
        The per-channel stream ID. Generated randomly in an attempt to
        avoid collisions.
    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.

:Children:
    parameters
        Tube parameters. Children are named "parameter" and have attributes
        "name" (user-specified) and "type" ("str", "bytes", "int" or "uint").
        Character content is UTF-8 (str), Base64 (bytes), ASCII decimal
        (int, uint).

        .. Note:: FIXME
            This encoding can't support ASCII control codes in UTF-8
            strings, because XML can't. Do we care?

        .. Note:: Proposed change:
            Children are either named after either basic D-Bus types, or 'ay'.
            For example::

                <parameters>
                    <s name="foo">Hello, world!</s>
                    <ay name="icon">Base64Base64Base64</ay>
                    <d name="quality">1.0</d>
                </parameters>

        .. Note:: Alternative:
            The <parameters> element has character content, which is the
            D-Bus serialization of the a{sv} in Base64. The encoding can be
            obtained with libdbus by marshalling a dummy message containing
            the a{sv}, then taking the body part of the message by doing
            trivial parsing.

.. _XEP-0047: http://www.xmpp.org/extensions/xep-0047.html
.. _XEP-0095: http://www.xmpp.org/extensions/xep-0095.html

.. vim:set sw=4 sts=4 et ft=rst: