moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 15:18:51 -05:00
Code Issues Releases Wiki Activity

HTTP Upload: Slight syntax changes and added ability to provide additional HTTP header fields on slot assignment

Browse Source
This commit is contained in:
Daniel Gultsch 2017-02-01 15:53:23 +01:00 committed by Sam Whited
parent 14ce97424c
commit 3849f03db4
1 changed files with 45 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
xep-0363.xml
View File

@ -28,12 +28,18 @@
<email>daniel@gultsch.de</email>
<jid>daniel@gultsch.de</jid>
</author>
<revision>
<version>0.3.0</version>
<date>2017-02-01</date>
<initials>dg</initials>
<remark><p>Slight syntax changes and added ability to provide additional HTTP header fields on slot assignment.</p></remark>
</revision>
<revision>
<version>0.2.5</version>
<date>2017-01-08</date>
<initials>XEP Editor: ssw</initials>
<remark><p>Merge typo fixes suggested by an unnamed user.</p></remark>
</revision>
</revision>
<revision>
<version>0.2.4</version>
<date>2016-10-28</date>
@ -97,13 +103,13 @@
<section1 topic='Requirements' anchor='reqs'>
<ul>
<li>Be as easy to implement as possible. This is grounded on the idea that most programming languages already have HTTP libraries available.</li>
<li>Be agnostic toward the distribution of the actual URL. Users can choose to send the URL in the body of a message stanza, utilize &xep0066;, or even use it as their avatar in &xep0084;.</li>
<li>Do not provide any kind of access control or security beyond Transport Layer Security in form of HTTPS and long random paths that are impossible to guess. That means everyone who knows the URL SHOULD be able to access it.</li>
<li>Be agnostic toward the distribution of the actual URL. Users can choose to send the URL in the body of a message stanza, utilize &xep0066;, &xep0370;, or even use it as their avatar in &xep0084;</li>
<li>Do not provide any kind of access control or security for file retrieval beyond Transport Layer Security in form of HTTPS and long random paths that are impossible to guess. That means everyone who knows the URL SHOULD be able to access it.</li>
</ul>
</section1>
<section1 topic='Discovering Support' anchor='disco'>
<p>An entity advertises support for this protocol by including the "urn:xmpp:http:upload" in its service discovery information features as specified in &xep0030; or section 6.3 of &xep0115;. To avoid unnecessary round trips an entity SHOULD also include the maximum file size as specified in &xep0128; if such a limitation exists. The field name MUST be "max-file-size" and the value MUST be in bytes.</p>
<p>A user's server SHOULD include any known entities that provide such services into its service discovery items.</p>
<p>An entity advertises support for this protocol by including the "urn:xmpp:http:upload:0" in its service discovery information features as specified in &xep0030; or section 6.3 of &xep0115;. To avoid unnecessary round trips an entity SHOULD also include the maximum file size as specified in &xep0128; if such a limitation exists. The field name MUST be "max-file-size" and the value MUST be in bytes.</p>
<p>A user’s server SHOULD include any known entities that provide such services into its service discovery items.</p>
<example caption='Client sends service discovery request to server'><![CDATA[
<iq from='romeo@montague.tld/garden'
id='step_01'
@ -137,10 +143,10 @@
<identity category='store'
type='file'
name='HTTP File Upload' />
<feature var='urn:xmpp:http:upload' />
<feature var='urn:xmpp:http:upload:0' />
<x type='result' xmlns='jabber:x:data'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:http:upload</value>
<value>urn:xmpp:http:upload:0</value>
</field>
<field var='max-file-size'>
<value>5242880</value>
@ -150,28 +156,32 @@
</iq>]]></example>
</section1>
<section1 topic='Requesting a slot' anchor='request'>
<p>A client requests a new upload slot by sending an IQ-get to the upload service containing a &lt;request&gt; child element qualified by the urn:xmpp:http:upload namespace. This element MUST include elements &lt;filename&gt; and &lt;size&gt; containing the file name and size respectively.</p>
<p>An additional element &lt;content-type&gt; containing the Content-Type is OPTIONAL.</p>
<p>A client requests a new upload slot by sending an IQ-get to the upload service containing a &lt;request&gt; child element qualified by the urn:xmpp:http:upload:0 namespace. This element MUST include the attributes filename and size containing the file name and size respectively.</p>
<p>An additional attribute content-type containing the Content-Type is OPTIONAL.</p>
<example caption='Client requests a slot on the upload service'><![CDATA[
<iq from='romeo@montague.tld/garden'
id='step_03'
to='upload.montague.tld'
type='get'>
<request xmlns='urn:xmpp:http:upload'>
<filename>my_juliet.png</filename>
<size>23456</size>
<content-type>image/jpeg</content-type>
<request xmlns='urn:xmpp:http:upload:0'
filename='my-juliet.jpg'
size='23456'
content-type='image/jpeg' />
</request>
</iq>]]></example>
<p>The upload service responds with both a PUT and a GET URL wrapped by a &lt;slot&gt; element. The service SHOULD keep the file name and especially the file ending intact. Using the same hostname for PUT and GET is OPTIONAL. The host SHOULD provide Transport Layer Security (&rfc5246;).</p>
<p>The upload service responds with both a PUT and a GET URL wrapped by a &lt;slot&gt; element. The service SHOULD keep the file name and especially the file ending intact. Using the same hostname for PUT and GET is OPTIONAL. The host MUST provide Transport Layer Security (&rfc5246;).</p>
<p>The &lt;put&gt; element MAY also contain an unlimited number of &lt;header&gt; elements which correspond to HTTP header fields. Each &lt;header&gt; element MUST have a name-attribute and a content with the value of the header.</p>
<example caption='The upload service responds with a slot'><![CDATA[
<iq from='upload.montague.tld'
id='step_03'
to='romeo@montague.tld/garden'
type='result'>
<slot xmlns='urn:xmpp:http:upload'>
<put>https://upload.montague.tld/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/my_juliet.png</put>
<get>https://download.montague.tld/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/my_juliet.png</get>
<slot xmlns='urn:xmpp:http:upload:0'>
<put url='https://upload.montague.tld/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/my-juliet.jpg'>
<header name='Authorization'>Basic Base64String==</header>
<header name='Host'>montague.tld</header>
</put>
<get url='https://download.montague.tld/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/my-juliet.jpg' />
</slot>
</iq>]]></example>
</section1>
@ -182,14 +192,14 @@
id='step_03'
to='romeo@montague.tld/garden'
type='error'>
<request xmlns='urn:xmpp:http:upload'>
<filename>my_juliet.png</filename>
<size>23456</size>
</request>
<request xmlns='urn:xmpp:http:upload:0'
filename='my-juliet.jpg'
size='23456'
content-type='image/jpeg' />
<error type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' />
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas>File too large. The maximum file size is 20000 bytes</text>
<file-too-large xmlns='urn:xmpp:http:upload'>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>File too large. The maximum file size is 20000 bytes</text>
<file-too-large xmlns='urn:xmpp:http:upload:0'>
<max-file-size>20000</max-file-size>
</file-too-large>
</error>
@ -200,13 +210,13 @@
id='step_03'
to='romeo@montague.tld/garden'
type='error'>
<request xmlns='urn:xmpp:http:upload'>
<filename>my_juliet.png</filename>
<size>23456</size>
</request>
<request xmlns='urn:xmpp:http:upload:0'
filename='my-juliet.jpg'
size='23456'
content-type='image/jpeg' />
<error type='wait'>
<resource-constraint xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' />
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas>Quota reached. You can only upload 5 files in 5 minutes</text>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>Quota reached. You can only upload 5 files in 5 minutes</text>
</error>
</iq>]]></example>
<example caption='Alternative response by the upload service to indicate a permanent error to a client that is not allowed to upload files'><![CDATA[
@ -214,18 +224,19 @@
id='step_03'
to='romeo@montague.tld/garden'
type='error'>
<request xmlns='urn:xmpp:http:upload'>
<filename>my_juliet.png</filename>
<size>23456</size>
</request>
<request xmlns='urn:xmpp:http:upload:0'
filename='my-juliet.jpg'
size='23456'
content-type='image/jpeg' />
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' />
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas>Only premium members are allowed to upload files</text>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>Only premium members are allowed to upload files</text>
</error>
</iq>]]></example>
</section1>
<section1 topic='Upload' anchor='upload'>
<p>The actual upload of the file happens via HTTP-PUT and is out of scope of this document. The upload service MUST reject the file upload if the Content-Length does not match the size of the slot request. The service SHOULD reject the file if the Content-Type has been specified beforehand and does not match. The service MAY assume application/octet-stream as a Content-Type if it the client did not specify a Content-Type at all.</p>
<p>In addition to the Content-Length and Content-Type header the client MUST also include all additional headers that came with the slot assignment.</p>
<p>There is no further XMPP communication required between the upload service and the client. A HTTP status Code of 201 means that the server is now ready to serve the file via the provided GET URL. If the upload fails for whatever reasons the client MAY request a new slot.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
@ -246,7 +257,7 @@
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:http:upload</li>
<li>urn:xmpp:http:upload:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>