diff --git a/inbox/xep-mam-prefs.xml b/inbox/xep-mam-prefs.xml new file mode 100644 index 00000000..c89a9b17 --- /dev/null +++ b/inbox/xep-mam-prefs.xml @@ -0,0 +1,186 @@ + + +%ents; +]> + + +
+ Message Archive Management Preferences + This document defines a protocol to control a user's archiving preferences. + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + + XMPP Core + XEP-0030 + XEP-0313 + + + + mamprefs + &mwild; + &ksmith; + + 0.1 + 2020-04-03 + mw + +

Split from XEP-0313, no protocol changes

+ + +
+ + +

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;.

+ +

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.

+ + + +

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.

+ +

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:

+
    +
  • A list of JIDs that should always have messages to/from archived in the user's store.
    • +
  • A list of JIDs that should never have messages to/from archived in the user's store.
    • +
  • The default archiving behaviour (for JIDs in neither of the above lists).
    • +
+ + + +]]> + +

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.

+ + + + + + + +]]> + +

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;.

+ + + + + + +]]> + +

To update the preferences, the client can simply send an iq stanza with a type of 'set':

+ + + + + romeo@montague.lit + + + montague@montague.lit + + + +]]> +

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):

+ + + + romeo@montague.lit + + + montague@montague.lit + + + +]]> + +

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).

+ + +

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. +

+

The 'default' attribute of the 'prefs' element MUST be one of the following values:

+
    +
  • 'always' - all messages are archived by default.
    • +
  • 'never' - messages are never archived by default.
    • +
  • 'roster' - messages are archived only if the contact's bare JID is in the user's roster.
    • +
+ + +

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'). +

+

If missing from the preferences, <always/> SHOULD be assumed by the server to be an + empty list. +

+ + +

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'). +

+

If missing from the preferences, <never/> SHOULD be assumed by the server to be an + empty list. +

+ + + +

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.

+

If supported, such a configuration command SHOULD be presented on the well-defined + command node of "urn:xmpp:mam#configure".

+ + + +

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). +

+

For matching against entries in either the 'allow' or 'never' lists, for each listed + JID: +

+
    +
  • If the listed JID contains a resource, compare against the target JID as-is.
    • +
  • If the listed JID has no resource (it is a bare JID) then first strip any resource + from the target JID prior to comparison. +
    • +
+ + +

For outgoing messages, the server MUST use the value of the 'to' attribute as the target JID. +

+ + +

For incoming messages, the server MUST use the value of the 'from' attribute as the target JID. +

+ + + +