XEP-0037: DSPS - Data Stream Proxy Service

3.1 Stream Creation/Relay {optional}¶

(optional) Creating or modifying stream is done like so:

<iq
  id='dsps1'
  type='get'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a44'>
  <query type='create'
    xmlns='jabber:iq:dsps'
    minthroughput='1.5KB'
    maxpublic='20'>
    <peer port='5290'>
      dsps.myjabber.net/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33
    </peer>
    <comment>public comment</comment>
  </query>
</iq>

• "to" with resource implies reconnection to previous relay stream with previously supplied credentials and authentication as per section "DSPS relay setup", otherwise implies creation of new stream where creator is granted "master" rights.
• "minthroughput" (optional) is minimum 16 second average throughput below which peers will be disconnected (but not dropped). Checked after every unit of outgoing transfer against the fourth value returned by "who" query for each peer. Legal only upon initial creation of stream. If omitted or negative, 0 is assumed.
• "maxpublic" (optional) is maximum number of peers that can join without invitation. If omitted or negative, 0 is assumed. If positive, DSPS generates globally unique id for public peers to acknowledge, reported within "stats" message. Said id remains constant for life of stream.
• <peer/> (optional) full JID of stream on another DSPS. Relay stream will be treated using "slave" rights. Legal only upon initial creation of stream. Multiple such blocks tried in series until successful connection. First successful (last if all failed) remembered by DSPS, all successive <peer/> ignored.. On connection, DSPS initiates handshake using peer's full JID and contents of block for destination's full JID to the relay destination as per section "Connecting to DSPS via default method". Authentication is done as per section "DSPS relay setup". Upon successful handshake, DSPS sends presence notification to peer as per section "Acknowledge of DSPS connection".
• "port" (optional) for connecting to destination DSPS. If omitted, default is assumed.
• <comment/> (optional) all such blocks reported in "stats" message. Multiple such blocks allowed. Block may contain a full XML stack of elements. No order implied for "stats" message.

Possible failure messages:

3.2 Connection waiting¶

DSPS creates "id" (empty string is legal), used in "who" replies and notifies client of waiting connection like so:

<iq
  id='dsps1'
  type='result'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'>
  <query type='create' xmlns='jabber:iq:dsps'
    wait='10'
    host='dsps.jabber.org'
    port='5290'
    minthroughput='1.5KB'
    protocol='0.5'>
    <feature type='http' version='1.1'/>
    <feature type='ssl' version='3.0'/>
  </query>
</iq>

• "from" full JID of DSPS, internally globally unique. Used in handshake and every subsequent communication with stream. May differ with the one specified in "invite" message.
• "wait" amount of time in milliseconds that DSPS will wait for client to initiate handshake. If timeout occurs, DSPS will totally forget prepared connection and act accordingly.
• "host" (optional) for handshake and data stream. If omitted default from the "from" is assumed. Intended for P2P connections to be able to report alternate hostname or IP for connection.
• "port" (optional) for handshake and data stream. If omitted default is assumed.
• "minthroughput" value from "create".
• "protocol" version this DSPS supports.
• <feature/> (optional) supported by this DSPS. Type and version are properties and additional data stored in body. HTTP stream will not follow HTTP protocol. SSL handshake performed encrypted. Both HTTP and SSL connections are only between client and DSPS.

3.3 Establishing prepared connection¶

Upon receipt of message as per section "Connection waiting", client can either ignore it and connection will timeout, or connect to the DSPS directly via any supported connection method or via relay. There may be a maximum of 1 (one) established connection to DSPS from any Client_full_JID + DSPS_full_JID pair, deviations are handles as per section "Connecting to DSPS via default method". DSPS will not discriminate method via which direct connection is made, even if prior to "disconnect" a different method was used. Any packet from an unauthorized connection is ignored without reporting an error.

<iq
  id='dsps1'
  type='get'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'>
  <query type='create' xmlns='jabber:iq:dsps'>acDgH63I27Gb1</query>
</iq>

<iq
  id='dsps1'
  type='result'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  <query type='create' xmlns='jabber:iq:dsps'>acDgH63I27Gb1</query>
</iq>

GET /DSPS/STREAM/ HTTP/1.0<CR>
Host: dsps.server<CR>
<CR>

HTTP/1.0 200 OK<CR>
Content-Type: application/octet-stream<CR>
<CR>

starttls<CR>

Client_full_JID DSPS_full_JID<CR>

rob@nauseum.org/dspsclient dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33

uGhhb74d21

<iq
  id='dsps1'
  type='get'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'>
  <query type='auth' xmlns='jabber:iq:dsps'>uGhhb74d21</query>
</iq>

<iq
  id='dsps1'
  type='result'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'
  <query type='auth' xmlns='jabber:iq:dsps'>qgqB42Ij784</query>
</iq>

  <iq
  id='dsps2'
  type='set'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='foo@bar.com/resource'>
  <query type='presence' xmlns='jabber:iq:dsps'>
  <peer status='connect'>JID</peer>
  </query>
</iq>

3.4 Stream administration¶

DSPS protocol allows multiple peers to use the same stream. Manipulation of the authorized peer list is done through admin functionality described in next several subsections. DSPS protocol allows for three types of peer connections: "master", "slave", and "relay". "master" peers get full control of the stream, "slave" peers get limited control of the stream, and "relay" are treated similar to "slave" except in reporting of JIDs where the resource must be omitted.

"master" peers are allowed to invite any other user to the stream and drop any peer registered with the stream, including themselves. "slave" peers are only allowed to drop themselves from the stream. Any administrative changes coming from a "slave" peer that are not for the peer's own connection are ignored. Dropping one's own connection is the preferred way of permanently disconnecting from the stream.

Any data received from a "master" gets copied to every other peer on the stream. Any data received from a "slave" peer gets copied to all "master" peers on the stream only.

Stream administration request looks like so:

<iq
  id='dsps3'
  type='set'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'>
  <query type='admin' xmlns='jabber:iq:dsps' expire='20' wait='10'>
    <comment>welcome to the stream</comment>
    <peer type='master'>someone@somewhere.net</peer>
  </query>
</iq>

• "admin" denotes administrative functions are to follow. Any properties within this block apply to this block alone. Multiple such blocks are allowed.
• "expire" time DSPS should wait for the "acknowledge" message from any invited peer within block. An "expire" of 0 denotes no time limit. Actual value sent to peer as "expire" is minimum of this value and default value preset for DSPS. If value unparseable or not present, default is used.
• "wait" time DSPS should wait for invited peer to connect to DSPS after "acknowledge" is received and message from section "Connection waiting". is sent. A "wait" of 0 denotes no time limit. Actual value sent to peer as "wait" is minimum of this value and default value preset for DSPS. If the value unparseable or not present, default is used.
• <comment/> (optional) block sent to each of the peers. Multiple such blocks are allowed. Block may contain a full XML stack of elements. All such blocks are sent to each of the invited peers as is. No guarantee is made on their order in the <invite/> message.
• <peer/> JID to execute action upon. If invitation then body will not necessarily be same full JID as one that would respond. Multiple such blocks allowed.
• "type" type of action to do. "master" denotes invitation, granting master rights. "slave" denotes invitation, granting slave rights. "drop" denotes request to drop peer from stream. "relay" peers may not be invited but may be dropped using this method.

Possible optional errors include the following:

<iq
  id='dsps3'
  type='result'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='user@server.org/resource'>
  <query type='admin' xmlns='jabber:iq:dsps'>
    <peer acknowledge='expire'>abc@company.com/net</peer>
    <peer acknowledge='reject'>friend@someplace.com/home</peer>
    <peer acknowledge='timeout'>abd@company.com/net</peer>
    <peer acknowledge='missing'>who@knows.org/winjab</peer>
  </query>
</iq>

• "admin" denotes admin response, sent to sender of "admin" request for every peer in block. Peers may be combined from multiple "admin" requests or peers from single "admin" request may be split over multiple "admin" replies.
• <peer/> peer in question. For "expire" JID is one from invite request. For "reject" JID is one from which reject received. For "timeout" JID is one from invite request. For "missing" is one from drop request. After this DSPS will totally forget about this peer.
• "acknowledge" reason for failure. "expire" denotes "expire" timeout sent, has ended. "reject" denotes peer rejected invite. "timeout" denotes "wait" timeout sent, has ended. "missing" denotes peer marked for drop not found registered on tis stream.

Possible failure messages:

<iq
  id='dsps4'
  type='get'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='foo@bar.com/resource'>
  <query type='acknowledge'
    xmlns='jabber:iq:dsps'
    status='master'
    expire='20'>
    <peer>rob@nauseum.org/dspsclient</peer>
    <comment>some long comment block or structure</comment>
  </query>
</iq>

<iq
  id='dsps5'
  type='set'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='foo@bar.com/resource'>
  <query type='acknowledge' xmlns='jabber:iq:dsps' status='drop'>
    <comment>some long comment block or structure</comment>
  </query>
</iq>

<iq
  id='dsps6'
  type='set'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='foo@bar.com/resource'>
  <query type='presence' xmlns='jabber:iq:dsps'>
    <peer status='drop'>JID</peer>
  </query>
</iq>

3.5 Invitation reply¶

An invited peer has the option to accept or reject an invitation to a stream.

<iq
  id='dsps4'
  type='result'
  from='foo@bar.com/moredsps'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33>
  <query type='acknowledge' xmlns='jabber:iq:dsps' status='connect'/>
</iq>

<iq
  id='dsps4'
  type='result'
  from='foo@bar.com/moredsps'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33>
  <query type='acknowledge' xmlns='jabber:iq:dsps' status='drop'/>
</iq>

3.6 Disconnection handling¶

If a peer ever disconnects without first dropping themselves, the following policy applies:

The peer may reconnect within the "wait" timeout provided in the "create" reply in section "Connection waiting". The peer may choose any supported mode of reconnection supplied in "create" reply, regardless of mode previously used. The "wait" timeout is not cumulative over multiple disconnects. After reconnect, peer will not receive any data that exists on the stream while it was disconnected.

Upon such disconnection DSPS notifies all other members of the stream, following the rules stated for the "presence" message, and takes the form of:

<iq
  id='dsps7'
  type='set'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='foo@bar.com/resource'>
  <query type='presence' xmlns='jabber:iq:dsps'>
    <peer status='waiting'>JID</peer>
  </query>
</iq>

• "from" is the DSPS JID/resource pair which DSPS has associated with the connection of the recipient of the message.
• "presence" denotes presence change. Body may contain multiple <peer/> blocks where same JID peers must be placed in chronological order relative to each other from start to end of message.
• <peer/> body is full JID of the disconnected peer registered on the stream, unless peer is of type "relay", in which case the resource is not reported.
• "status" is new status of peer.

Upon reaching "wait" timeout the procedure is the same if the peer dropped its own connection.

3.7 Ending a connection¶

Permanent termination of connection can be done in two ways: peer may disconnect from the stream and let the "wait" timeout expire, or more preferably the peer will drop itself from the stream via an "admin" message. The "admin" is still allowed to contain multiple "peer" blocks.

3.8 Stream use¶

The use policy for the stream follows the standard rules described in this document. Type and structure of the data must be negotiated by the peers separately (presumably via the normal XML message stream or within <comment/> blocks). The DSPS stream operates at the speed of the slowest connection (or slower if it is so configured in its internal configuration).

Data read from peer in a unit of transfer (decided by DSPS) is sent to other peers in a format like so:

0<size><CR><id><CR><data>

• "0" at beginning for checking start of block.
• <size> length in bytes including id and its trailing CR in form of [1-9][0-9]*[0-9A-Z], where last character is base 36 numerical equivalent power of 1024.
• <id> id of the sender as per "who" query.
• <data> data sent.
• <CR> regular carriage return, commonly referred to as the newline character.

For example, the appropriate string for the above block would be:

0340<CR>
010<CR>
this is the data in ASCII form

First block received after connection will always be full block. If discrepancy occurs, receiving peer should disconnect and reconnect back to stream.

3.9 Stream information¶

Two mechanisms exists to gain information about the stream configuration and its members. They are described within next few subsections.

<iq
  id='dsps8'
  type='get'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'>
  <query type='who' xmlns='jabber:iq:dsps'/>
</iq>

<iq
  id='dsps8'
  type='result'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'>
  <query type='who' xmlns='jabber:iq:dsps'>
    <peer
      type='master'
      id='0'
      status='connect'
      throughput='1KB////4.8KB//3KB'>
      rob@nauseum.org/dspsclient
    </peer>
  </query>
</iq>

<iq
  id='dsps9'
  type='get'
  from='rob@nauseum.org/dspsclient'
  to='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'>
  <query type='stats' xmlns='jabber:iq:dsps'/>
</iq>

<iq
  id='dsps9'
  type='result'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'>
  <query type='stats' xmlns='jabber:iq:dsps'
    init='00000000000000'
    protocol='0.5'
    port='5290'
    minthroughput='1.5KB'
    expiredefault='150'
    waitdefault='100'
    wait='10'
    public='5'
    maxpublic='25'
    mastercount='20'
    slavecount='40'
    relaycount='0'>
    <feature type='http' version='1.1'/>
    <feature type='ssl' version='3.0'/>
    <peer>mydsps@jabber.org/8xd67f56df4f546fdgsfdg65f6g58f</peer>
    <comment>some server comment</comment>
  </query>
</iq>

3.10 Stream shutdown¶

Stream exists from its "create"ion time to the time when there are no more "master" peers registered with the stream.

When last "master" peer is dropped from the stream, DSPS will make sure that all the data sent by all the "master" peers was actually copied to all the "slave" peers still present. For every remaining "slave" peer DSPS will initiate a drop event. Once stream is void of any peers it will be totally forgotten by the DSPS and all associated data is released.

3.11 Error message format¶

Error messages look like so:

<iq
  id='dsps9'
  type='error'
  from='dsps.jabber.org/0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33'
  to='rob@nauseum.org/dspsclient'>
  <error code='405'>Method Not Allowed</error>
</iq>

• <error/> denotes error block where body is text description.
• "code" denotes error code.

4.1 File transfer¶

File transfer can be easily accomplished over DSPS. Where one user invites another user to a DSPS stream. File details can be transfered in the invitation comment as such: <meta type='file' name='myfile.txt' size='500K' crc32='12345' sha1='23451' mime='application/octet-stream' timestamp='12345' date='20020412T00:00:00'/>. Where the "size" would be in bytes. All properties should reflect their appropriate values for this instance. Once the second peer has accepted, it can simply put a CR on the stream stating that transfer can begin. then the first party simply dumps the contents of file on the stream, closes the stream and "drop"s itself from the stream. DSPS will make sure the second party gets everything that the first party sent before closing the connection. If multiple recipients of the file are required, the sending client can save a lot of bandwidth and transmit only one copy if the file to the DSPS which in term will transmit the data over to all the other connected clients.

4.2 VoIP¶

Same idea as the file transfer. However if more then two parties are involved, every party must have a "master" connection.

4.3 Multicast¶

A server has a JID which it registers with a stream. Any client wishing to join the multicast sends an XML message to the server, which then invites the client with a "slave" connection. Thus everything the server sends is received by every client on the stream. If there are multiple back-up servers, they can be invited with a "master" connection, thus if one of them goes down, the others can take over.

4.4 File Storage¶

It has long been discussed in many Jabber places that a file storage facility is desired. The communication with such a facility can be easily accommodated with DSPS, as such a facility would merely appear as a user to DSPS which can either be "invite"ed or "invite" other users onto personal streams to transfer files as described in 6.1.

5.1 Ports¶

PASS requires the use of a large number of individual ports, which on a heavily loaded server can lead to the number of spare ports dropping to zero, causing connections to be refused.

This is also problematic if PASS is situated behind a firewall. Firewall administrators are typically loathe to allow incoming connections to a large range of ports.

DSPS only uses one port, and so resolves the first problem, while making the second almost a non-issue.

5.2 Knowledge of IP¶

PASS requires the client to have some knowledge of IP, which immediately forces the assumption that the XML stream's underlying protocol is in fact, IP. While at the time of writing this is always the case, it may not always be this way.

DSPS uses the Jabber ID to do its routing, and so avoids these problems. And while DSPS does use the concept of a TCP connection and an IP port, this information is never actually used anywhere on the XML stream, making the actual connection to the DSPS implementation-defined.

5.3 IP Addresses¶

PASS makes the IP address of the remote client available to the local client. While it is rare that this is an actual problem, many users and administrators prefer that IP address information is never actually revealed.

DSPS never transmits IP address information across the XML stream, and so does not have this problem.

5.4 Intuitiveness¶

PASS requires a client to initiate a connection by opening a (proxied) listening socket, and then soliciting connections. However, TCP works by having the client connect to a remote resource directly. This difference can make the operation of PASS difficult to understand. Also, it is left to the client to distribute the information about this listening socket, which places an additional burden on the client.

DSPS, while it uses listening sockets to do its work, does all the work of setting up the connection after a client initiates it. All the initiating client has to do is request a connection, connect to the DSPS, and wait - everything else is handled automatically.

5.5 Scalability¶

Due to the master/slave design, DSPS is already able to handle multicasts of streams or such, whilst PASS was only designed for simple p2p stream connections. This will becoming increasingly more important as more emphasis is made on streaming capabilities, for technologies such as audio and video conferencing.

Due to DSPS generality, the protocol can be easily used for either P2P or P2S2P needs. This eliminates the need for a separate protocol for each of the tasks.

Copyright

This document has been placed in the public domain.

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.