Merge pull request #1275 from Ppjet6/0060-node-full

XEP-0060: Add pubsub#publish_node_full
2024-11-21 16:55:07 -05:00 · 2023-05-04 14:29:52 +01:00 · 2023-05-04 14:29:52 +01:00 · b9ec6c12ac
commit b9ec6c12ac
parent 642260ef6b 9067d145e1
1 changed files with 74 additions and 5 deletions
--- a/xep-0060.xml
+++ b/xep-0060.xml
@ -16,6 +16,7 @@
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
+  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0004</spec>
@ -49,6 +50,19 @@
  &pgmillard;
  &stpeter;
  &ralphm;
+  <revision>
+    <version>1.25.0</version>
+    <date>2023-03-22</date>
+    <initials>mw, pep</initials>
+    <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>Clarify behaviour and current usage of the 'pubsub#itemreply' option.</p></li>
+        <li><p>Fix spec approver</p></li>
+      </ul>
+    </remark>
+  </revision>
  <revision>
    <version>1.24.1</version>
    <date>2022-01-21</date>
@ -2794,7 +2808,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[
@ -2932,7 +2945,7 @@ And by opposing end them?
 ]]></example>
      </section4>
      <section4 topic='Item Publisher' anchor='publisher-publish-success-publisher'>
-        <p>If configured to do so, the service can include the publisher of the item when it generates event notifications.</p>
+        <p>If configured to do so (see <link url='#impl-association'>Associating Events and Payloads with the Generating Entity</link>), the service can include the publisher of the item when it generates event notifications.</p>
    <example caption='Service Notifies Subscribers'><![CDATA[
 <message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
@ -2981,6 +2994,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 or reject the new item.</p>
+        <p>The behaviour of the service is determined by the "pubsub#publish_node_full" option which may take one of the following 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>
@ -2988,6 +3009,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>
@ -3031,6 +3053,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, and the pubsub#publish_full_node configuration value is set to "reject", then the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of &lt;node-full/&gt;.</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>
@ -5341,6 +5377,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>
@ -5412,7 +5454,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>
@ -5447,6 +5489,13 @@ And by opposing end them?
 </section1>

 <section1 topic='Implementation Notes' anchor='impl'>
+  <section2 topic='Data Model' anchor='data-model'>
+    <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>

  <section2 topic='Notification Triggers' anchor='impl-notify'>
    <p>There are many possible triggers for sending an event notification to an entity for the currently published item or the last published item, as summarized below:</p>
@ -5626,13 +5675,15 @@ And by opposing end them?
      <li>In the context of a group weblog, different users might publish to the weblog and replies might go to the publisher of an entry rather than to the weblog owner.</li>
      <li>In the context of an integrated pubsub and multi-user chat system, the node owner might be the room owner but all replies need to be sent to the room rather than to the owner.</li>
    </ul>
-    <p>Therefore we define the "itemreply" node configuration option, with two possible values:</p>
+    <p>Therefore we define the "itemreply" node configuration option, with three possible values:</p>
    <ul>
      <li>"owner" (i.e., the node owner or an alias for the node owners)</li>
      <li>"publisher" (i.e., the item publisher)</li>
+      <li>"none"</li>
    </ul>
    <p>A node owner MUST NOT define more than one of these options.</p>
-    <p>An example is shown below.</p>
+    <p>Interoperability note: As of March 2023, the value of "owner" is not widely supported in generic implementations, and clients may choose to avoid it. In contrast, the value of "none" was not specified in previous versions of this document but has been added retrospectively due to implementation support. Therefore, the primary use of the 'pubsub#itemreply' option is to allow node owners to determine whether the server will <link url='#publisher-publish-success-publisher'>include a 'publisher' attribute in items or not</link>.</p>
+    <p>The JID associated with an item is conveyed via the 'publisher' attribute on the &lt;item/&gt; element, as demonstrated in the below example:</p>
    <example caption='Event notification with publisher JID'><![CDATA[
 <message from='pubsub.shakespeare.lit'
         to='bassanio@merchantofvenice.lit'>
@ -6251,6 +6302,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>
@ -6609,6 +6665,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'/>