moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-15 13:55:03 -05:00
Code Issues Releases Wiki Activity

Merge change for XEP-0402

Browse Source
This commit is contained in:
Maxime “pep” Buquet 2019-10-15 18:13:20 +02:00
commit b89fbe6840
1 changed files with 114 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
xep-0402.xml
View File

@ -25,6 +25,19 @@
<discuss>standards</discuss>
&dcridland;
&jcbrand;
<revision>
<version>0.3.0</version>
<date>2019-09-28</date>
<initials>egp</initials>
<remark><ul>
<li>Fix examples.</li>
<li>Explain the expected workflow better.</li>
<li>Encourage clients to set pubsub#send_last_published_item to never and pubsub#max_items to some high value.</li>
<li>Add examples about notifications and +notify.</li>
<li>Request clients to add notify='1' on retraction requests, so they do trigger notifications (see <link url='https://xmpp.org/extensions/xep-0060.html#publisher-delete-success-notify'>XEP-0060 §7.2.2.1</link> for a rationale).</li>
<li>Announce a feature when the server supports compat between old &xep0048; (version 1.0) and this specification, and another between current &xep0048; (version 1.1) and this specification.</li>
</ul></remark>
</revision>
<revision>
<version>0.2.1</version>
<date>2018-07-22</date>
@ -107,15 +120,32 @@
]]></example>
<p>This bookmark would be displayed as 'Council of Oberon' and, if activated, would attempt to join the conference room 'council@conference.underhill.org' with nickname 'Puck'.</p>
<p>Note that a bookmark item MUST contain only one conference room.</p>
<p>Note also that a conference element has no truly mandatory attributes or child elements, though a name SHOULD be given. Thus the following is legal:</p>
<p>Note also that a conference element has no truly mandatory attributes or child elements, thus the following is legal:</p>
<example caption='Minimalist conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['/>
]]></example>
</section1>
<section1 topic='Examples' anchor='examples'>
<section1 topic='Workflow' anchor='workflow'>
<section2 topic='Registering to receive notifications' anchor='enable-updates'>
<p>A client interested in bookmarks SHOULD include the 'urn:xmpp:bookmarks:0+notify' feature in its &xep0115;, as per &xep0163;, so that it receives notifications for updates done by other clients of the user, and reacts accordingly. The actual notifications are explained in the <link url='#notifications'>Bookmark Notifications</link> section of this specification.</p>
<example caption='Client replies with +notify to a XEP-0030 query from its server'><![CDATA[
<iq from='juliet@capulet.lit/balcony' to='capulet.lit' type='result' id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='client' type='pc' name='poezio'/>
<feature var='http://jabber.org/protocol/disco#info'/>
<feature var='urn:xmpp:bookmarks:0+notify'/>
<!-- … -->
</query>
</iq>
]]></example>
</section2>
<section2 topic='Retrieving all bookmarks' anchor='retrieving-bookmarks'>
<p>Once connected, a client first retrieves the current list of bookmarks. It then SHOULD join every MUC identified by the items’ 'id' attribute that have an 'autojoin' attribute that is set to "true" or "1".</p>
<p>NOTE: A future version of this specification might refer to &xep0312; or a similar protocol to reduce the need for full synchronisation on each connection.</p>
<example caption='Client retrieves all bookmarks'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='get' id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
@ -130,14 +160,16 @@
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
<conference xmlns=']]>&namespace;<![CDATA['
name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
<item id='orchard@conference.shakespeare.lit'>
<conference name='The Orchard'
autojoin='true'>
<conference xmlns=']]>&namespace;<![CDATA['
name='The Orchard'
autojoin='1'>
<nick>JC</nick>
</conference>
</item>
@ -149,13 +181,15 @@
<section2 topic='Adding a bookmark' anchor='adding-a-bookmark'>
<p>Adding a bookmark means publishing a new item, with the bookmark JID as id, to the '&namespace;' node.</p>
<p>publish-options (as defined in <link url='https://xmpp.org/extensions/xep-0060.xml#publisher-publish-options'>XEP-0060</link>) MUST be supported by the server in order to check that the node is correctly configured before publishing a new conference. This is especially important to avoid leaking your bookmarks to your contacts for instance.</p>
<example caption='Client adds a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
<conference xmlns=']]>&namespace;<![CDATA['
name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
@ -169,6 +203,12 @@
<field var='pubsub#persist_items'>
<value>true</value>
</field>
<field var='pubsub#max_items'>
<value>10000</value>
</field>
<field var='pubsub#send_last_published_item'>
<value>never</value>
</field>
<field var='pubsub#access_model'>
<value>whitelist</value>
</field>
@ -185,11 +225,12 @@
<section2 topic='Removing a bookmark' anchor='removing-a-bookmark'>
<p>Removing a bookmark means retracting an existing item, identified by the bookmark's JID, form the '&namespace;' node.</p>
<p>This implies that server support for the "delete-items" pubsub feature is REQUIRED.</p>
<p>A 'notify' attribute SHOULD be included on the &lt;retract/&gt; element in order to inform other online clients of the deletion.</p>
<example caption='Client removes a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='remove-bookmark1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='urn:xmpp:bookmarks:0'>
<retract node='urn:xmpp:bookmarks:0' notify='true'>
<item id='theplay@conference.shakespeare.lit'/>
</retract>
</pubsub>
@ -203,8 +244,36 @@
</section1>
<section1 topic="Bookmark Notifications">
<p>When a client is sent an event from the Pubsub service for the '&namespace;' node, it MUST check the 'autojoin' attribute if present, and join the room immediately if the attribute is both present and true.</p>
<section1 topic="Bookmark Notifications" anchor='notifications'>
<p>When a client is sent an event from the Pubsub service for the '&namespace;' node, it SHOULD join the room immediately if the 'autojoin' attribute is both present and true.</p>
<example caption='Client receives a new bookmark notification'><![CDATA[
<message from='juliet@capulet.lit' to='juliet@capulet.lit/balcony' type='headline' id='new-room1'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference xmlns=']]>&namespace;<![CDATA['
name='The Play&apos;s the Thing'
autojoin='1'>
<nick>JC</nick>
</conference>
</item>
</items>
</event>
</iq>
]]></example>
<p>On the other hand, if the 'autojoin' attribute is absent or false, or when the event is a retract notification, the client SHOULD leave the room immediately.</p>
<example caption='Client receives a bookmark retraction notification'><![CDATA[
<message from='juliet@capulet.lit' to='juliet@capulet.lit/balcony' type='headline' id='removed-room1'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:bookmarks:0'>
<retract id='theplay@conference.shakespeare.lit'/>
</items>
</event>
</iq>
]]></example>
</section1>
<section1 topic="Implementation Notes">
@ -220,6 +289,9 @@
</section2>
<section2 topic="Compatibility">
<p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
<p>It is encouraged to at least support unification between Private XML Storage because as of 2019 this is still the storage backend that is implemented in the majority of clients.</p>
<p>A server that supports unifying bookmarks from &xep0049; and &xep0402; SHOULD announce the "urn:xmpp:bookmarks:0#compat" feature on the account. Clients may use that feature as an indication that it is safe to store bookmarks using only &xep0402; without losing backward compatibility to clients that are only using &xep0049;.</p>
<p>A server that supports unifying bookmarks between &xep0223; and &xep0402; SHOULD announce the "urn:xmpp:bookmarks:0#compat-pep" feature on the account.</p>
<section3 topic="Publishing via this specification">
<p>When a client publishes a new item, the server MAY collate all items, casting them into the 'storage:bookmarks' namespace and setting the jid attribute to the item id in each case. When contained within a storage element qualified by the 'storage:bookmarks' namespace, this will be the correct format for both current and previous variants of &xep0048;</p>
</section3>
@ -231,6 +303,8 @@
<section1 topic='Determining Support' anchor='support'>
<p>This specification relies fully on a number of others. Most particularly, support for this protocol is available if &xep0223; is supported.</p>
<p>Server side unification between &xep0049; bookmarks and Bookmarks 2 is announced with the feature "urn:xmpp:bookmarks:0#compat" on the account.</p>
<p>Server side unification between the current use of XEP-0048 bookmarks (PEP) is annouced with the feature "urn:xmpp:bookmarks:0#compat-pep" on the account.</p>
</section1>
<section1 topic="Acknowledgements">