XEP-0363: specificy purpos/buckets when requesting slots

Author: iNPUTmice

xep-0363.xml

@@ -290,6 +290,91 @@
     <get url='https://download.montague.tld/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67/tr%C3%A8s%20cool.jpg' />
   </slot>
 </iq>]]></example>
+</section1>
+<section1 topic='Upload purpose' anchor='purpose'>
+
+  <p>Retention policy is out of scope for this document. However, common retention strategies include enforcing user quotas that trigger the deletion of the oldest files when exceeded, and automatically deleting files older than a specified timeframe. This retention policy works well for message attachments, which are downloaded once per recipient device, but it may not be suitable for files requiring longer availability, like user avatars or microblog post images. To alleviate this problem, the requesting entity MAY specify a purpose when requesting an upload slot. This allows the upload service to sort files into different 'buckets' and apply different retention periods to those buckets. If no purpose is specified, the service MUST assume 'message' as the default purpose.</p>
+
+<section2 topic='Message' anchor='purpose-message'>
+  <p>An entity advertises support for the 'message' purpose by including "urn:xmpp:http:upload:purpose:0#message" in its service discovery features.</p>
+  <p>The requesting entity indicates that the upload slot is meant to be used for messaging purposes by including an element 'message' qualified by the 'urn:xmpp:http:upload:purpose:0' namespace.</p>
+  <p class="note">Note: As the 'message' purpose is the default, explicitly announcing the feature and including this purpose in the slot request is technically redundant and is done solely for the sake of completeness.</p>
+  <example caption='Client requests a slot for the purpose of sending it as a message'><![CDATA[
+<iq from='[email protected]/garden'
+    id='step_03'
+    to='upload.montague.tld'
+    type='get'>
+  <request xmlns='urn:xmpp:http:upload:0'
+           filename='hi.jpg'
+           size='23425'
+           content-type='image/jpeg'>
+    <message xmlns="urn:xmpp:http:upload:purpose:0" />
+  </request>
+</iq>]]></example>
+
+</section2>
+
+<section2 topic='Profile' anchor='purpose-profile'>
+  <p>An entity advertises support for the 'profile' purpose by including "urn:xmpp:http:upload:purpose:0#profile" in its service discovery features.</p>
+
+  <p>The requesting entity indicates that the upload slot is meant to be used for profile purposes by including a 'profile' element, qualified by the urn:xmpp:http:upload:purpose:0 namespace. This purpose is for files, such as avatars (&xep0084;) or cover photos, that require longer retention, are smaller in size, and need a significantly lower overall quota.</p>
+
+  <example caption='Client requests an HTTP upload slot for the purpose of uploading an avatar'><![CDATA[
+<iq from='[email protected]/garden'
+    id='step_03'
+    to='upload.montague.tld'
+    type='get'>
+  <request xmlns='urn:xmpp:http:upload:0'
+           filename='avatar.jpg'
+           size='100'
+           content-type='image/jpeg'>
+    <profile xmlns="urn:xmpp:http:upload:purpose:0"/>
+  </request>
+</iq>]]></example>
+
+</section2>
+
+<section2 topic='Ephemeral' anchor='purpose-ephemeral'>
+  <p>An entity advertises support for the ephemeral purpose by including "urn:xmpp:http:upload:purpose:0#ephemeral" in its service discovery features.</p>
+  
+    <p>The requesting entity indicates that the upload slot is meant to be used for ephemeral purposes by including an 'ephemeral' element, qualified by the urn:xmpp:http:upload:purpose:0 namespace. The element MUST have an attribute called 'expire-before' that contains a DateTime as specified in &xep0082;. This purpose is similar to the default 'message' purpose but imposes an upper limit on the retention period, as specified by the requesting entity. The upload service MAY delete the file earlier based on its own retention policies, but MUST NOT make the file available after the time specified in the expire-before attribute.<br/>Example use cases for this purpose include, but are not limited to &xep0466; or 'Stories' that expire after 24 hours.</p>
+
+  <example caption='Client requests a slot with a limited lifetime'><![CDATA[
+<iq from='[email protected]/garden'
+    id='step_03'
+    to='upload.montague.tld'
+    type='get'>
+  <request xmlns='urn:xmpp:http:upload:0'
+           filename='eiffel-tower-status-picture.jpg'
+           size='100'
+           content-type='image/jpeg'>
+    <ephemeral xmlns="urn:xmpp:http:upload:purpose:0"
+               expire-before="2025-09-10T23:08:25Z" />
+  </request>
+</iq>]]></example>
+
+</section2>
+
+<section2 topic='Permanent' anchor='purpose-permanent'>
+  <p>An entity advertises support for the permanent purpose by including "urn:xmpp:http:upload:purpose:0#permanent" in its service discovery features.</p>
+  
+  <p>The requesting entity indicates that the upload slot is meant for long term storage by including a 'permanent' element, qualified by the urn:xmpp:http:upload:purpose:0 namespace.<br/>Example use cases for this purpose include, but are not limited to &xep0277; and &xep0472;.<br/>Support for this purpose - like any other specific purpose - is OPTIONAL.</p>
+
+  <example caption='Client requests a slot for permanent storage'><![CDATA[
+<iq from='[email protected]/garden'
+    id='step_03'
+    to='upload.montague.tld'
+    type='get'>
+  <request xmlns='urn:xmpp:http:upload:0'
+           filename='pubsub-blog-picture.jpg'
+           size='42000'
+           content-type='image/jpeg'>
+    <permanent xmlns="urn:xmpp:http:upload:purpose:0" />
+  </request>
+</iq>]]></example>
+
+</section2>
+
 </section1>
 <section1 topic='Error conditions' anchor='errors'>
   <p>Instead of providing the client with a slot the service MAY respond with an error if the requested file size is too large. In addition the entity MAY inform the requester about the maximum file size.</p>