[Telepathy] The XMPP implementation of Tubes
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Thu Aug 16 02:22:10 PDT 2007
Le lundi 13 août 2007 à 17:49 +0100, Simon McVittie a écrit :
> 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.
>
Great idea. Thanks for that.
> 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.
>
http://projects.collabora.co.uk/~monkey/telepathy-salut-private-tubes/
implements OOB as transport now. Of course SI choose this one if it's
available and use IBB if it's not.
> 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.
There is some extra negotiation steps to initiate the IBB bytestream
before we consider the tube to be open.
See 3.1 section on http://www.xmpp.org/extensions/xep-0047.html
> 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.
Same as D-Bus tube. Set a stream tubes in our muc presence make it
available for all muc members.
>
> 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.
>
No. When you see a new tube in a MUC presence, this tube is
local-pending while you don't accept/close it.
> 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.
>
right.
> 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...
>
It's used for stream tubes. Let's say Alice offers a stream tube to Bob.
Alice send a SI request containing tubes info and offering=true. Bob
accept it and a bytestream X is created.
Now Bob connects 2 applications to his local socket. For each
connection, the CM needs to establish a new bytestream that will be used
to transfer data for this socket connection. So it send 2 SI requests
with offering=false.
(Currently the bytestream X is not used. Maybe it should be for the
first connection and so avoid an extra SI. There is a XXX in the code
about that IIRC).
So the job of the offering attribute is to make the difference between a
SI creating a new tube and a SI to establish a new bytestream for an
existing tube.
Maybe we could solve that using another SI profile. I don't remember if
I investigated this solution when I added the offering attribute.
> 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.
>
For private tubes, this dbus-name is in the SI reply.
> :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.
>
I'm definitely not against a change, but what are the problems of the
current format?
Be aware that this code is also use by the OLPC extensions to define
activities properties.
G.
More information about the Telepathy
mailing list