XEP-0060: Add pubsub#publish_node_full

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

xep-0060.xml

@@ -57,6 +57,7 @@
     <remark>
       <ul>
         <li><p>Add data model informational text in Implementation Notes.</p></li>
+        <li><p>Provide a way for a PubSub service to tell a client when a node is full.</p></li>
         <li><p>Fix spec approver</p></li>
       </ul>
     </remark>
@@ -2806,7 +2807,6 @@ And by opposing end them?
       <p>Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST overwrite the old item with the new item and then proceed as follows.</p>
       <p>The pubsub service MUST then send one event notification to each entity that meets the criteria for receiving an event notification (typically to each approved subscriber, although there are other contexts in which an entity may receive an event notification as summarized under <link url='#impl-notify'>Notification Triggers</link>). Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the <link url='#impl-bounce'>Handling Notification-Related Errors</link> section of this document). Depending on the node configuration, the event notification either will or will not contain the payload, as shown below.</p>
       <p>Note: In order to facilitate authorization for item removal as described in the <link url='#publisher-delete'>Delete an Item from a Node</link> section of this document, implementations that support persistent items SHOULD store the item (if the node is so configured) and maintain a record of the publisher.</p>
-      <p>Note: If the service or node is configured so that there is a maximum number of items cached at the node and the maximum is reached when an item is published, the service MUST delete one of the existing items. It is RECOMMENDED for the service to follow the "first in, first out" rule and delete the oldest item. Depending on node configuration, deletion of an existing item MAY result in sending of a delete notification to the subscribers.</p>
       <section4 topic='Notification With Payload' anchor='publisher-publish-success-withpayload'>
         <p>If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.</p>
         <example caption='Subscribers receive event notifications with payloads'><![CDATA[
@@ -2993,6 +2993,14 @@ And by opposing end them?
 </message>
 ]]></example>
       </section4>
+      <section4 topic='Node is full' anchor='publisher-publish-success-nodefull'>
+        <p>If the service or node is configured so that there is a maximum number of items cached at the node and the maximum is reached when an item is published, the service MUST delete one of the existing items.</p>
+        <p>The behaviour of the service is reflected through the "pubsub#publish_node_full" option which may take multiple values: "retract-oldest", "discard-oldest", or "reject".</p>
+        <p>The "retract-oldest" option is the default one and SHOULD be implemented even if this configuration isn't supported.</p>
+        <p>It is RECOMMENDED for the service to follow the "first in, first out" rule and retract the oldest item. Depending on node configuration, deletion of an existing item MAY result in sending of a retract notification to the subscribers.</p>
+        <p>When configured as "discard-oldest", a service MUST discard the oldest item.</p>
+        <p>The "reject" option for this configuration is described in <link url="publisher-publish-error-nodefull">Node is full</link> publishing errors.</p>
+      </section4>
     </section3>
     <section3 topic='Error Cases' anchor='publisher-publish-error'>
       <p>There are several reasons why the publish request might fail:</p>
@@ -3000,6 +3008,7 @@ And by opposing end them?
         <li>The requesting entity does not have sufficient privileges to publish.</li>
         <li>The node does not support item publication.</li>
         <li>The node does not exist.</li>
+        <li>The node is full (max_items exceeded).</li>
         <li>The payload size exceeds a service-defined limit.</li>
         <li>The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node.</li>
         <li>The request does not match the node configuration.</li>
@@ -3043,6 +3052,20 @@ And by opposing end them?
   <error type='cancel'>
     <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
   </error>
+</iq>
+]]></example>
+      </section4>
+      <section4 topic='Node is full' anchor='publisher-publish-error-nodefull'>
+        <p>If the requesting entity attempts to publish an item to a node that has reached its maximum number of items, visible via pubsub#max_items, the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of &lt;node-full/&gt;, if pubsub#publish_node_full exists and is set to "reject".</p>
+        <example caption='Entity attempts to publish to a node with max_items reached'><![CDATA[
+<iq type='error'
+    from='pubsub.shakespeare.lit'
+    to='hamlet@denmark.lit/elsinore'
+    id='publish1'>
+  <error type='cancel'
+    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
+    <node-full xmlns='http://jabber.org/protocol/pubsub#errors'/>
+  </error>
 </iq>
         ]]></example>
       </section4>
@@ -5353,6 +5376,12 @@ And by opposing end them?
       <td>RECOMMENDED</td>
       <td><link url='#affiliations'>Affiliations</link></td>
     </tr>
+    <tr>
+      <td>publish-node-full</td>
+      <td>Specified behaviour may happen when publishing on a full node.</td>
+      <td>OPTIONAL</td>
+      <td><link url='#publisher-publish-success-nodefull'>Retracting an item</link> and <link url='#publisher-publish-error-nodefull'>Rejecting an item</link>.</td>
+    </tr>
     <tr>
       <td>purge-nodes</td>
       <td>Purging of nodes is supported.</td>
@@ -5424,7 +5453,7 @@ And by opposing end them?
     </tr>
     <tr>
       <td>&conflict;</td>
-      <td>The node already exists.</td>
+      <td>The node already exists, or is full. See <link url='#publish_node_full'>pubsub#publish_node_full</link>.</td>
     </tr>
     <tr>
       <td>&feature;</td>
@@ -5463,6 +5492,7 @@ And by opposing end them?
     <p>When implementing this protocol, it is often helpful to consider the data model behind it. Note that this section describes such a conceptual model for informational purposes only and does not define any requirements about how, where or in what format an implementation actually stores data.</p>
 <p>A persistent pubsub node may be viewed as an ordered key-value store, where the ItemIDs are the keys, and the item payloads are the values.</p>
     <p>The order of items is publication order, such that the most recently published is the “newest”. This holds true even if publishing with an ItemID that already exists on the node: the older item is dropped to preserve uniqueness of keys. This is sometimes referred to as “overwriting” in this document.</p>
+    <p>The order is of most importance when the max_items option is used to limit the number of items on the node. When the limit is reached, the oldest item may be dropped from the node according to the configured policy (see the <link url="#publisher-publish-nodefull">publish_node_full</link> option).</p>
     <p>If published ItemIDs are always unique, a persistent node may also be viewed as a kind of “first in, first out” (FIFO) queue.</p>
   </section2>
 
@@ -6269,6 +6299,11 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings;item=ae
   <desc>The publisher affiliation is supported.</desc>
   <doc>XEP-0060</doc>
 </var>
+<var>
+  <name>http://jabber.org/protocol/pubsub#publish-node-full</name>
+  <desc>Specified behaviour may happen when publishing on a full node.</desc>
+  <doc>XEP-0060</doc>
+</var>
 <var>
   <name>http://jabber.org/protocol/pubsub#purge-nodes</name>
   <desc>Purging of nodes is supported.</desc>
@@ -6627,6 +6662,19 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings;item=ae
       <value>open</value>
     </option>
   </field>
+  <field var='pubsub#publish_node_full'
+         type='list-single'
+         label='Action to be performed by the service when publishing on a full node.'>
+    <option label='Retract the oldest item alongside publishing the new item.'>
+      <value>retract-oldest</value>
+    </option>
+    <option label='Discard the oldest item alongside publishing the new item.'>
+      <value>discard-oldest</value>
+    </option>
+    <option label='Reject publication of the new item.'>
+      <value>reject</value>
+    </option>
+  </field>
   <field var='pubsub#purge_offline'
          type='boolean'
          label='Whether to purge all items when the relevant publisher goes offline'/>