mirror of https://github.com/moparisthebest/xeps
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
192 lines
8.0 KiB
192 lines
8.0 KiB
<?xml version='1.0' encoding='UTF-8'?> |
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [ |
|
<!ENTITY % ents SYSTEM 'xep.ent'> |
|
%ents; |
|
]> |
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?> |
|
<xep> |
|
<header> |
|
<title>Message Archive Management Preferences</title> |
|
<abstract>This document defines a protocol to control a user's archiving preferences.</abstract> |
|
&LEGALNOTICE; |
|
<number>0441</number> |
|
<status>Experimental</status> |
|
<type>Standards Track</type> |
|
<sig>Standards</sig> |
|
<dependencies> |
|
<spec>XMPP Core</spec> |
|
<spec>XEP-0030</spec> |
|
<spec>XEP-0313</spec> |
|
</dependencies> |
|
<supersedes/> |
|
<supersededby/> |
|
<shortname>mamprefs</shortname> |
|
&mwild; |
|
&ksmith; |
|
<revision> |
|
<version>0.2.0</version> |
|
<date>2020-08-25</date> |
|
<initials>XEP Editor (jsc)</initials> |
|
<remark>Accepted by vote of Council on 2020-08-19.</remark> |
|
</revision> |
|
<revision> |
|
<version>0.1</version> |
|
<date>2020-04-03</date> |
|
<initials>mw</initials> |
|
<remark> |
|
<p>Split from XEP-0313, no protocol changes</p> |
|
</remark> |
|
</revision> |
|
</header> |
|
|
|
<section1 topic='Introduction' anchor='intro'> |
|
<p>This specification describes a protocol for a server to allow a client to configure a user's |
|
message archiving preferences. It is intended to be used in conjunction with &xep0313;.</p> |
|
|
|
<p>After observing XEP-0313 usage in the wild, it became apparent that preferences were not often |
|
used, and can interfere with clients that use the archive for synchronization of messages received |
|
by the user while disconnected. Therefore it is not actively encouraged for an implementation/deployment |
|
to offer this functionality.</p> |
|
</section1> |
|
|
|
<section1 topic='Archiving Preferences' anchor='prefs'> |
|
<p>Depending on implementation and deployment policies, a server MAY allow the user to have control |
|
over the server's archiving behaviour. This specification defines a basic protocol for this, and |
|
also allows a server to offer more advanced configuration to a user.</p> |
|
<section2 topic='Simple configuration' anchor='config'> |
|
<p>If the server supports and allows configuration of the preferences described below then it SHOULD implement the protocol defined |
|
in this section. This allows the user to retrieve and configure the following preferences:</p> |
|
<ul> |
|
<li>A list of JIDs that should always have messages to/from archived in the user's store.</li> |
|
<li>A list of JIDs that should never have messages to/from archived in the user's store.</li> |
|
<li>The default archiving behaviour (for JIDs in neither of the above lists).</li> |
|
</ul> |
|
<example caption='Retrieving archiving preferences'><![CDATA[ |
|
<iq type='get' id='juliet2'> |
|
<prefs xmlns='urn:xmpp:mam:2'/> |
|
</iq> |
|
]]></example> |
|
|
|
<p>The server replies with the user's current archiving preferences. The <prefs> element |
|
MUST be present and contain the current default archiving policy. The <always> and <never> |
|
MUST also be present (even if empty), and contain a list of JIDs enclosed in <jid> elements.</p> |
|
|
|
<example caption='Server responds with current preferences'><![CDATA[ |
|
<iq type='result' id='juliet2'> |
|
<prefs xmlns='urn:xmpp:mam:2' default='roster'> |
|
<always/> |
|
<never/> |
|
</prefs> |
|
</iq> |
|
]]></example> |
|
|
|
<p>It is also possible that the server may respond with a stanza error, for example the standard |
|
'feature-not-implemented' (server does not support MAM configuration) defined in &rfc6120;.</p> |
|
|
|
<example caption='Server does not support archive configuration'><![CDATA[ |
|
<iq type='error' id='juliet2'> |
|
<error type='cancel'> |
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> |
|
</error> |
|
</iq> |
|
]]></example> |
|
|
|
<p>To update the preferences, the client can simply send an iq stanza with a type of 'set':</p> |
|
|
|
<example caption='Updating archiving preferences'><![CDATA[ |
|
<iq type='set' id='juliet3'> |
|
<prefs xmlns='urn:xmpp:mam:2' default='roster'> |
|
<always> |
|
<jid>romeo@montague.lit</jid> |
|
</always> |
|
<never> |
|
<jid>montague@montague.lit</jid> |
|
</never> |
|
</prefs> |
|
</iq> |
|
]]></example> |
|
<p>The server then replies with the applied preferences (note that due to server policies these |
|
MAY be different to the preferences sent by the client):</p> |
|
<example caption='Server responds with updated preferences'><![CDATA[ |
|
<iq type='result' id='juliet3'> |
|
<prefs xmlns='urn:xmpp:mam:2' default='roster'> |
|
<always> |
|
<jid>romeo@montague.lit</jid> |
|
</always> |
|
<never> |
|
<jid>montague@montague.lit</jid> |
|
</never> |
|
</prefs> |
|
</iq> |
|
]]></example> |
|
|
|
<p>It is also possible for the server to respond with an error, for example (but not limited to) |
|
the standard 'feature-not-implemented' (the server does not support configuration of preferences), |
|
'forbidden' (the user is not authorized to change their preferences) or 'not-allowed' (the server |
|
generally does not allow changing of configuration preferences).</p> |
|
|
|
<section3 topic='Default behaviour' anchor='config-default'> |
|
<p>If a JID is in neither the 'always archive' nor the 'never archive' list then whether it |
|
is archived depends on this setting, the default. |
|
</p> |
|
<p>The 'default' attribute of the 'prefs' element MUST be one of the following values:</p> |
|
<ul> |
|
<li>'always' - all messages are archived by default.</li> |
|
<li>'never' - messages are never archived by default.</li> |
|
<li>'roster' - messages are archived only if the contact's bare JID is in the user's roster.</li> |
|
</ul> |
|
</section3> |
|
<section3 topic='Always archive' anchor='config-always'> |
|
<p>The <prefs/> element MAY contain an <always/> child element. If present, it |
|
contains a list of <jid/> elements, each containing a single JID. The server SHOULD |
|
archive any messages to/from this JID (see 'JID matching'). |
|
</p> |
|
<p>If missing from the preferences, <always/> SHOULD be assumed by the server to be an |
|
empty list. |
|
</p> |
|
</section3> |
|
<section3 topic='Never archive' anchor='config-never'> |
|
<p>The <prefs/> element MAY contain an <never/> child element. If present, it |
|
contains a list of <jid/> elements, each containing a single JID. The server SHOULD |
|
NOT archive any messages to/from this JID (see 'JID matching'). |
|
</p> |
|
<p>If missing from the preferences, <never/> SHOULD be assumed by the server to be an |
|
empty list. |
|
</p> |
|
</section3> |
|
</section2> |
|
<section2 topic='Advanced configuration' anchor='advanced-config'> |
|
<p>In addition to this protocol, a server MAY offer more advanced configuration to the user |
|
through &xep0050;. Such an interface might, for example, allow the user to configure what |
|
types of messages to store, or set a limit on how long messages should remain in the |
|
archive.</p> |
|
<p>If supported, such a configuration command SHOULD be presented on the well-defined |
|
command node of "urn:xmpp:mam#configure".</p> |
|
</section2> |
|
<section2 topic='JID matching' anchor='match'> |
|
<section3 topic='General rules' anchor='match-rules'> |
|
<p>When comparing the message target JID against the user's roster (ie. when the user has |
|
set default='roster') the comparison MUST use the bare target JID (that is, stripped of |
|
any resource). |
|
</p> |
|
<p>For matching against entries in either the 'allow' or 'never' lists, for each listed |
|
JID: |
|
</p> |
|
<ul> |
|
<li>If the listed JID contains a resource, compare against the target JID as-is.</li> |
|
<li>If the listed JID has no resource (it is a bare JID) then first strip any resource |
|
from the target JID prior to comparison. |
|
</li> |
|
</ul> |
|
</section3> |
|
<section3 topic='Outgoing messages' anchor='match-out'> |
|
<p>For outgoing messages, the server MUST use the value of the 'to' attribute as the target JID. |
|
</p> |
|
</section3> |
|
<section3 topic='Incoming messages' anchor='match-in'> |
|
<p>For incoming messages, the server MUST use the value of the 'from' attribute as the target JID. |
|
</p> |
|
</section3> |
|
</section2> |
|
</section1> |
|
</xep>
|
|
|