diff --git a/xep-0214.xml b/xep-0214.xml index 67b70298..9491058c 100644 --- a/xep-0214.xml +++ b/xep-0214.xml @@ -7,10 +7,10 @@
File Repository and Sharing - While a protocol has been described for initiating a file transfer from one user to another, there is not yet a way for users to designate a set of files as available for retrieval by other users of their choosing. This extension fills that functionality, with additional features such as file versioning, multiple download mirrors across several internet protocols, collaborative modification of the file listing, and all the other benefits of Pubsub. - 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/). + While a protocol has been described for initiating a file transfer from one user to another, there is not yet a defined way for users to designate a set of files as available for retrieval by other users of their choosing. This extension defines a common syntax for this purpose which is based on PubSub Collections. + &LEGALNOTICE; 0214 - Deferred + Experimental Standards Track Standards JIG Council @@ -20,16 +20,23 @@ XEP-0060 XEP-0082 XEP-0137 + XEP-0248 - Not yet assigned + NOT_YET_ASSIGNED Nicholas Parker nickbp@gmail.com nickp@jabber.org + + 0.2 + 2009-01-05 + nbp +

Non-functional rewording and refactoring. Now reflects the move of PubSub Collections into a separate extension.

 + 0.1 2007-04-20 @@ -56,31 +63,46 @@
-

Describes how a Jabber user may find and retrieve files which other Jabber users have published. The listing of files is done through a Pubsub (XEP-0060) server, allowing multiple users to manage the same listing. Other features include file metadata, revisions, and download mirrors.

-

Retrieval of the files provided in the listing MAY be performed through any relevant protocol for transferring data (http, ftp, etc), but this protocol emphasizes the use of Stream Initiation (XEP-0137) to establish the connection.

+

This document defines a common format which allows a Jabber user to submit, find, and retrieve files within XMPP. The file listing itself is stored on a &xep0060; server, allowing multiple users to manage the same listing. Other features specified by this extension include file metadata, revisions, and download mirrors.

+

Retrieval of files provided in a listing MAY be performed through any relevant protocol for transferring data (http, ftp, etc). This protocol standardizes the use of &xep0137; to establish the file transfer, but also allows for usage of outside protocols such as http or ftp.

The protocol defined herein provides the following functionality:

    -
  1. Publication of a list of available files to a Pubsub server, with tree structure, file metadata, user permissions, and file versioning.
    2. +
  2. Publication of a list of available files to a PubSub server, with support for hierarchical listings, file metadata, user privileges, and file versioning.
  3. Request that a file be sent from a Jabber contact directly to oneself using Stream Initiation.
 - - - - - + + + + + + + + + + + + + + + + + + + +
File ListingTop-level Pubsub Collection Node, containing information about files and/or subsections which a user or group of users have published.
SubsectionNon-Root Collection Node which containts files and/or other subsections.
FilePubsub Node, stored within a File Listing, which describes all revisions of a given file. The filename and (optionally) description are provided here.
RevisionPubsub Item which describes a given file revision. Other metadata which can vary between revisions is provided here (file size, checksum, available mirrors, etc).
MirrorA location which has a given Revision available for download. Additional information about a given Mirror MAY be provided for protocols that require it. A list of available protocols is provided below.
File ListingA Root-level Pubsub Collection Node, containing information about files and/or subsections which a user or group of users have published.
SubsectionA Non-Root Collection Node which contains files and/or other subsections.
FileA Pubsub Node, stored within a File Listing, which describes all revisions of a given file. The filename and (optional) description are provided here.
RevisionA Pubsub Item which describes a given file revision. Other metadata which can vary between revisions, such as filesize, checksum, or available mirrors, is provided here.
MirrorA location which has a given Revision available for download. Additional information about a Mirror MAY be specified in instances where the protocol requires it. A list of example file transfer protocols is provided below, but others may also be deployed.
 + +

The following use cases describe tasks which are already covered by &xep0060; in a more generic context. These tasks are again being provided here in order to demonstrate the functionality provided by this protocol and convey the structure and syntax of the file listing. As a result of this close relationship, many details of PubSub are omitted here for brevity. Consult &xep0060; and &xep0248; for the full specification of node and user management commands as well as their server responses.

-

The following use cases describe tasks which are already covered by XEP-0060 in a more generic context. These tasks are explicitly described in order to demonstrate the wide range of capabilities afforded by this system and convey the data structure of the file listing itself. Consult XEP-0060 for the full range of node and user management commands as well as their server responses.

-

Juliet wishes to make her sonnets available for retrieval by the public. She creates a Root Pubsub Collection Node which will contain her file listing:

@@ -106,7 +128,7 @@ from='juliet@capulet.com/balcony' to='pubsub.shakespeare.lit' id='config2'> - + @@ -120,7 +142,7 @@ ]]> -

Juliet also wishes to add a subsection for her sonnets about Romeo. She creates another Pubsub Collection Node under the Root Node:

+

Juliet also wishes to add a subsection for her sonnets about Romeo. She creates another PubSub Collection Node under the Root Node:

-

Juliet has just finished a new sonnet and wishes to announce its availability on her File Listing. She adds the sonnet as a new Pubsub Node stored in her Collection Node, then inserts a first revision of her sonnet as an Item within that Node:

+

Juliet has just finished a new sonnet and wishes to announce its availability on her File Listing. She adds the sonnet as a new PubSub Node stored in her Collection Node, then inserts a first revision of her sonnet as an Item within that Node:

The Item ID is set to 1, signifying the first revision for this file. Subsequent revisions/items will have incremented ID values, like one would see in a versioning system such as CVS or SVN. Implementations MAY follow this convention, but are not required to do so. For example, a given implementation may instead mark revisions using version numbers ("Beta 1", "6.2", etc) or use other arbitrary strings. However, no two revisions of a given file may share the same ID.

+

Node IDs MAY take the form of "path/to/file.ext", rather than the randomized string "a6190c5d38e22452041d1c5798eff3f5" provided in the above use case. For example, Juliet's sonnet MAY instead use a Node ID of "juliets_sonnets/sonnet.txt", as long as this ID is unique within the PubSub server. Randomized strings are used in this document to illustrate that Node IDs SHOULD NOT be used for providing information about files.

Here is a listing of the possible metadata in a file revision (Item), each field is OPTIONAL:

- + @@ -353,42 +376,42 @@ ]]> -

The above examples give a listing of available mirror protocols in probable configurations. As described in the Implementation Notes, only the sipub mirror type is REQUIRED, the others are only given as examples for common protocols which are not already compatible with SI. Here is a full listing of those protocols and their available settings:

+

The above examples give a listing of several possible file transfer protocols in example configurations. Only the sipub mirror type is REQUIRED; the other types are OPTIONAL. Here is a full listing of those protocols and their available settings:

-
SizeThe size, in bytes, of the file.
ModifiedThe last modified time of the revision. Follows the format described in XEP-0082. If a publisher prefers to only make a single revision available to clients, the publisher MAY instead update this value (and others, such as size and/or checksum) to announce that a new version of the file is available.
ModifiedThe last modified time of the revision. Follows the format described in &xep0082;. If a publisher prefers to only make a single revision available to clients, the publisher MAY instead update this value (and others, such as size and/or checksum) to announce that a new version of the file is available.
ChecksumA checksum of the revision, using the specified hash algorithm. Acceptable types are "sha512", "sha1", "md5", and "crc32".
MimeThe file's MIME type.
DescriptionDescription text for the revision. As an example, could contain release notes.
+
- - - - - + + + + + - + - + - + - - + +
Protocol DescriptionRef AddressPort (default) UserPass
sipubOPTIONAL
http
sipub (REQUIRED)OPTIONALN/AN/AN/AN/AN/A
http (OPTIONAL) OPTIONALREQUIRED REQUIREDOPTIONAL (80) OPTIONALOPTIONAL
https
https (OPTIONAL) OPTIONALREQUIRED REQUIREDOPTIONAL (443) OPTIONALOPTIONAL
ftp
ftp (OPTIONAL) OPTIONALREQUIRED REQUIREDOPTIONAL (21) OPTIONALOPTIONAL
sftp
sftp (OPTIONAL) OPTIONALREQUIRED REQUIREDOPTIONAL (22) OPTIONALOPTIONAL
smbOPTIONALREQUIRED (Incl. Share name)
smb (OPTIONAL)OPTIONALREQUIRED REQUIREDOPTIONAL (445) OPTIONALOPTIONAL

The Description field is where an arbitrary description of the mirror MAY be placed. For example, if a File Listing is advertising mirrors which are located in different geographic locations, then this field may be used to specify those locations.

-

The Ref field is a unique identifier which is used to request the file from the mirror server. In the above examples, it is used as a path to the file.

-

The address and port fields describe where the file may be retrieved using the specified protocol. If a port is not provided, the default value (specified in parentheses) is assumed.

+

The Ref field is a unique address or identifier for retrieving the file from the mirror server. In the above examples, it is used as a path to the file.

+

The address and port fields describe the server where the file may be retrieved using the specified protocol. If a port is not provided, the default value (specified in parentheses) MAY be assumed.

The User and Pass fields are for providing credentials which, if given by the File Listing, SHOULD be used when requesting the file. For example, an sftp mirror MAY require that the user log in using specified credentials before the file may be retrieved.

 @@ -509,14 +532,14 @@ ]]> -

Other deletion, modification, and user management operations are available as described in XEP-0060. These examples are provided here to explicitly illustrate the capabilities offered by this system.

+

Other deletion, modification, and user management operations are available as described in &xep0060; and &xep0248;.

 -

Romeo is interested in seeing what files Juliet has made available. To do this, Romeo sends Juliet a request for repositories which she is associated with:

+

Romeo is interested in seeing what files Juliet has made available. To do this, Romeo sends a request to Juliet for repositories which she is associated with:

]]> -

Juliet responds with a list of Pubsub nodes where she has published files or which she believes would be interesting to Romeo. If no such locations exist, Juliet SHOULD respond with an empty list.

+

Juliet responds with a list of PubSub nodes where she has published files or which she believes would be interesting to Romeo. If no such locations exist, Juliet SHOULD respond with an empty list.

]]> -

After browsing Juliet's repository, Romeo has chosen to download her sonnet. The most recent revision of this file contains a listing of available mirrors, and one of them is an SI stream. Romeo sends an SI request to that mirror:

+

After browsing Juliet's repository, Romeo has chosen to download her sonnet. The most recent revision of this file contains a listing of available mirrors, and Romeo sees that one of them is an SI stream. Romeo sends an SI request to that mirror:

]]> -

The rest of the negotiation and transfer occurs as described in XEP-0137.

+

The rest of the negotiation and file transfer occurs as described in &xep0137;.

 -

Since Pubsub is used for the File Listing, the access models described in XEP-0060 MUST be followed. Users MUST NOT be able to view or control information in the File Listing to which they do not have access.

- -

Node IDs MAY take the form of "path/to/file.ext", rather than the randomized strings provided in the above use cases. For example, Juliet's sonnet MAY use a Node ID of "juliets_sonnets/sonnet.txt" rather than "a6190c5d38e22452041d1c5798eff3f5", as long as this ID is unique to the PubSub server. Randomized strings were used in order to explicitly illustrate that Node IDs SHOULD NOT be depended upon for storing information about files.

- -

The "sipub" mirror type MUST be implemented by the client, while the other mirror types are entirely OPTIONAL, and are provided only as examples for custom client implementations which desire use of common protocols which are currently incompatible with SI requests.

+

Since PubSub is used for the File Listing, the access models described in &xep0060; and &xep0248; MUST be followed. Users MUST NOT be able to view or control information in the File Listing to which they do not have access.

-

If user access to files is restricted, the mirror servers and the File Listing server MUST be able to synchronize these restrictions between them. See Security Considerations.

+

If user access to files is restricted, the Mirror servers and the PubSub server MUST be able to synchronize these restrictions between them. See Security Considerations.

 -

When restricted files are being distributed, mirrors need to know which users have permission to access which files. If mirrors are not provided this information by the File Listing (or some other entity), unauthorized users could request files from mirrors directly, thus bypassing any such restrictions.

+

When restricted files are being distributed, mirrors need to know which users have sufficient privileges to access which files. If mirrors are not kept up to date on user privileges, unauthorized users could access files directly from those mirrors, thus bypassing any restrictions being set on the PubSub server.

No interaction with the Internet Assigned Numbers Authority (IANA) is required as a result of this XEP.