mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-14 13:25:23 -05:00
194 lines
8.1 KiB
XML
194 lines
8.1 KiB
XML
<?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>
|
|
<approver>Council</approver>
|
|
<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>
|