XEP-xxxx: Jingle HTTP File Transfer

This document describes a content type used for transferring files with Jingle, using the Hypertext Transfer Protocol.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2007-02-05
Approving Body: XMPP Council
Dependencies: XMPP Core, XMPP IM, XEP-166
Supersedes: None
Superseded By: None
Short Name: Not yet assigned

Author Information

Brian McBarron

Email: bpm@google.com
JID: bpm@google.com

Sean Egan

Email: seanegan@google.com
JID: seanegan@google.com

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy (<http://www.xmpp.org/extensions/ipr-policy.shtml>). This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Table of Contents

1. Introduction
2. Requirements
3. Content Description
3.1. The File Manifest
3.2. The HTTP description
4. HTTP Implementation
4.1. Preview
4.2. Transfer
5. description-info Messages
6. Implementation Notes
7. Security Considerations
8. IANA Considerations
9. XMPP Registrar Considerations
10. XML Schema
Notes
Revision History


1. Introduction

The Jingle protocols, originally designed to enable XMPP clients to create voice sessions, has proven to be a suitable protocol for managing state in peer-to-peer sessions of any type. This document describes a filesharing content type that uses HTTP (see RFC 2068 [1]) to transfer files from one host to another.

2. Requirements

Currently, File Transfer [2] is the preferred method of transfering files between two XMPP client using Stream Initiation [3]. However, this protocol has some limitations addressed in the following design requirements for this protocol:

3. Content Description

A Jingle HTTP File Transfer content description describes what files are being offered, and how to request them over HTTP. The <description/> element, qualified by the 'http://www.xmpp.org/extensions/xep-XXXX.html#ns' namespace, MUST contain two elements: <manifest/> which describes the files being offered, and <http/> which describes the paths hosted by the sender's HTTP server implementation.

Example 1. An HTTP file transfer description

 <description xmlns='http://www.xmpp.org/extensions/xep-XXXX.html#ns'>
   <manifest>
    
     <file size='341'>
       <name>file.txt</name>
     </file>
     
     <file size='51321'>
      <name>picture.jpg</name>
      <image width='480' height='320'/>
     </file>
     
     <folder>
       <name>directory</name>
     </folder>

   </manifest>

   <http>
     <url name='source-path'>/source/23A53F01/</url>
     <url name='preview-path'>/preview/90266EA1/</url>
   </http>

 </description>

3.1 The File Manifest

The <manifest/> element contains any number of <file/> and <folder/> elements, describing the files and directories being offered. Both the <file/> and <folder> elements SHOULD possess a 'size' attribute, whose value is the size of the file (or total size of all files within a directory) in bytes. If calculating the size of all the files within a directory is too resource-intensive, this attribute MAY be omitted.

Both the <file/> and <folder/> elements MUST contain a <name/> element, whose character data is the filename of the file or directory.

An image file SHOULD contain an <image/> child containing additional metadata about the file. The <image/> element SHOULD possess 'width' and 'height' attributes, describing the dimensions of the image in pixels.

3.2 The HTTP description

The <http/> element describes the paths that HTTP requests should be made to. An <http/> element MUST contain an <url/> element with a 'name' attribute of 'source-path' that describes the base path of the offered files. It SHOULD also send an <url/> element with a 'name' attribute of 'preview-path' that describes the base path for previews of the files being offered, that the recipient may requet before accepting the session.

4. HTTP Implementation

An initiating client acts as an HTTP server, hosting files from the paths specified by 'preview-path' and 'source-path'. A receiving client acts as an HTTP client requesting files as needed. A client may create as many components as it desires, over which it can make an HTTP request. A receiver creates the components as negotiated by the transport type, listens for HTTP requests on them, and responds with the appropriate HTTP response.

4.1 Preview

Before the session is accepted by a 'session-accept' message, but after the content and transport are accepted, the initiating client should respect requests to the preview path, as the receiving client may wish to preview the offered files before accepting the transfer.

This preview SHOULD be done for image files, but MAY be done for any file. In either case, the initiating client MUST respond with an image file. The receiving client MAY request that the preview be a certain size by adding width and height queries to the requested URL. The initiating client SHOULD honor the requested size, but MAY send a preview of any size.

If the client cannot offer a preview image it MUST return an HTTP 404 error

Example 2. Receiving client requests a 50x50 preview of picture.jpg

GET /preview/90266EA1/picture.jpg?width=50&height=50 HTTP/1.1

Example 3. Initiating client responds with an image scaled to 50x50

HTTP/1.1 200
Content-Type: image/jpg
Content-length: 4582

[image data]

4.2 Transfer

Once the session has been accepted, by sending a 'session-accept' message, the receiver SHOULD preform HTTP GET requests on the the files in 'source-path.'

Example 4. Receiving client requests file.txt

GET /source/23A53F01/file.txt HTTP/1.1

The initator MUST respond with the requested file, or with with the appropriate HTTP error, when applicable

Example 5. Initiating client sends requested file

HTTP/1.1 200
Content-Type: text/plain
Content-length: 341

[file data]

If the URL requested represents a folder, rather than a file, the client responds with a document of content type 'application/x-tar', which contains the contents of the directory in tar file format

Example 6. Receiving client requests a directory

GET /source/23A53F01/directory HTTP/1.1

Example 7. Initiating client responds by sending a tar document

HTTP/1.1 200
Content-Type: application/x-tar
Content-length: 98121

[tar data]

5. description-info Messages

The initiating client SHOULD send a <complete/> description-info message, qualified by the 'http://www.xmpp.org/extensions/xep-XXXX#ns' namespace when the recipient has finished receiving all the offered files.

Example 8. Initiator notifies recipient that it has received all files.

<iq to='romeo@montegue.net/Filereceive'
    id='jingle-ft' 
    type='set'>
    <jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
     action='description-info'
     sid='5341736A17'>
      <complete xmlns='http://www.xmpp.org/extensions/xep-XXXX.html#ns'/>
    </jingle>
</iq>

6. Implementation Notes

To support resuming of interrupted transfers, clients SHOULD support Range as defiend in section 14.36 of RFC 2616 [4].

7. Security Considerations

As with all applications that allow files to be downloaded, clients must take care to protect file recipients from potentially harmful files.

8. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [5].

9. XMPP Registrar Considerations

The XMPP Registrar [6] includes 'http://xmpp.org/extensions/xep-XXXX.html#ns' in its registry of protocol namespaces.

10. XML Schema

TODO


Notes

1. RFC 2068: Hypertext Transport Protocol -- HTTP/1.1 <http://tools.ietf.org/html/rfc2068>.

2. XEP-0096: File Transfer <http://www.xmpp.org/extensions/xep-0096.html>.

3. XEP-0095: Stream Initiation <http://www.xmpp.org/extensions/xep-0095.html>.

4. RFC 2616: Hypertext Transport Protocol -- HTTP/1.1 <http://tools.ietf.org/html/rfc2616>.

5. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

6. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.


Revision History

Version 0.0.1 (2007-02-05)

First draft.

(bpm/sme)


END