diff --git a/xep-0313.xml b/xep-0313.xml new file mode 100644 index 00000000..46be8916 --- /dev/null +++ b/xep-0313.xml @@ -0,0 +1,380 @@ + + +%ents; +]> + + +
+ Message Archive Management + This document defines a protocol to query and control and archive of messages stored on a server. + &LEGALNOTICE; + 0313 + Experimental + Standards Track + Standards + + XMPP Core + XEP-0030 + XEP-0059 + XEP-0297 + + + + mam + + http://www.xmpp.org/schemas/archive-management.xsd + + + Matthew + Wild + me@matthewwild.co.uk + me@matthewwild.co.uk + + + 0.1 + 2010-07-01 + mw +

Initial version, to much rejoicing.

 + +
+ + +

It is a common desire for a user using XMPP for IM to want to store their messages in a central archive + on their server. This feature allows them to record conversations that take place on clients that do not + support local history storage, and also to synchronise their conversation history seamlessly between + multiple clients.

+ + + +

As this extension aims to make things easy for client developers, some research was made into the + way clients handle history today. The resulting protocol was designed to allow for the following primary + usage scenarios:

+ +

Another extension for archiving already exists in XMPP, &xep0136;). However implementation experience has + shown that the protocol defined therein supports rather more functionality than is typically needed for the + above uses, and is significantly more effort to implement.

+

This specification aims to define a much simpler and modular protocol for working with a server-side + message store. Through this it is hoped to boost implementation and deployment of archiving in XMPP. It + should be noted that (although not required) a server is free to implement XEP-0136 alongside this + protocol if it so chooses, though a mapping between both protocols is beyond the scope of this specification.

+

Notable functionality in XEP-0136 that is intentionally not defined by this specification for simplicity:

+ + + + +

An archive is a collection of messages stored on a user's server. Messages sent to or from a + user's account are generally automatically added to a user's archive by the server. The collection + is ordered chronologically by the time each message was sent/received.

+

Exactly which messages a server archives is left up to implementation and deployment policy, + but as a minimum servers SHOULD NOT archive messages that do not have a <body/> child tag.

+

At a minimum, a stored message consists of the following pieces of information:

+ +

A server MAY impose limits on the size of a user's archive. For example a server might begin + to discard old messages once the archive reaches a certain size, or only keep messages until they + reach a certain age. The UIDs of deleted messages MUST NOT be reused for new messages.

+

Finally, there is no restriction on where an archive may be hosted. Servers that archive + messages on behalf of local users SHOULD expose archives to the user on their bare JID, while a + MUC service might allow MAM queries to be sent to the room's bare JID.

+ + + +

A client is able to query the archive for all messages within a certain timespan, optionally + restricting results to those to/from a particular JID. To allow limiting the results or paging + through them a client may use &xep0059;, which MUST be supported by servers.

+

A query consists of an <iq/> stanza addressed to the account or server entity hosting + the archive, with a 'query' payload. On receiving the query, the server pushes to the client a + series of messages from the archive that match the client's given criteria, and finally returns + the <iq/> result.

+ + + + +[... server sends matching messages ...] + + + ]]> +

To ensure that the client knows when the results are complete, the server MUST delay the result + <iq/> until after it has pushed all the results to the client. An optional 'queryid' attribute + allows the client to match results to a certain query.

+ +

The query can contain any combination of three filtering tags - <with/>, <start/> + and <end/>. By default all messages match a query, the filters are used to request a subset + of the archived messages.

+ +

If a <with/> element is present in the <query/>, it contains a JID against which + to match messages. The server MUST only return messages if they match the supplied JID.

+

If <with/> is omitted, the server SHOULD return all messages in the selected timespan, + regardless of the to/from addresses on each message.

+ + + juliet@capulet.com + + + ]]> +

If (and only if) the supplied JID is a bare JID (i.e. no resource is present), then + the server SHOULD return messages if their bare to/from address would match it. For example, + if the client supplies with='juliet@capulet.com' this filter would also match messages to + or from "juliet@capulet.com/balcony" and "juliet@capulet.com/chamber".

+ + +

The <start/> and <end/> elements, if provided, MUST contain timestamps + formatted according to the DateTime profile defined in &xep0082;

+

The <start/> element is used to filter out messages before a certain date/time. + If specified, a server MUST only return messages whose timestamp is equal to or later + than the given timestamp.

+

If omitted, the server SHOULD assume the value of <start/> to be equal to the + date/time of the earliest message stored in the archive.

+

Conversely, the <end/> element is used to exclude from the results messages + after a certain point in time. If specified, a server MUST only return messages whose + timestamp is equal to or earlier than the timestamp given in the <end/> element.

+

If omitted, the server SHOULD assume the value of <end/> to be equal to the + date/time of the most recent message stored in the archive.

+ + + 2010-06-07T00:00:00Z + 2010-07-07T13:23:54Z + + + ]]> + + + 2010-08-07T00:00:00Z + + + ]]> + + +

Finally, in order for the client or server to limit the number of results transmitted at + a time a server MUST support &xep0059; and SHOULD support the paging mechanism defined therein. + A client MAY include a <set/> element in its query.

+

For the purposes of this protocol, the UIDs used by RSM correspond with the UIDs of the + stanzas stored in the archive.

+ + + 2010-08-07T00:00:00Z + + 10 + + + + ]]> +

To conserve resources, a server MAY place a reasonable limit on how many stanzas may be + pushed to a client in one request. If a query returns a number of stanzas greater than this + limit and either the client did not specify a limit using RSM then the server should return + a policy-violation error to the client. If the query did include a <set/> element then + the server SHOULD simply return its limited results and adjust the <before/> and <after/> + in its reply to allow the client to page through them by timestamp.

+ + + + Too many results + + + ]]> + + + +

The server responds to the archive query by transmitting to the client all the messages + that match the criteria the client requested. The results are sent as individual stanzas, + with the original message encapsulated in a <forwarded/> element as described in &xep0297;. +

+

The result messages MUST contain a <result/> element with an 'id' attribute that gives + the current message's UID. If the client gave a 'queryid' attribute in its initial query, the + server MUST also include that in this result element.

+

The <forwarded/> element SHOULD contain the original message as it was received, and + SHOULD also contain a <delay/> element qualified by the 'urn:xmpp:delay' namespace + specified in &xep0203;. The value of the 'stamp' attribute MUST be the time the message was + originally received by the forwarding entity. +

+ + + + + + Call me but love, and I'll be new baptized; Henceforth I never will be Romeo. + + + + + + + + + + What man art thou that thus bescreen'd in night so stumblest on my counsel? + + + + ]]> + + + + +

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 then it SHOULD implement the protocol defined + in this section. This allows the user to 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).
    • +
+ + + + romeo@montague.net + + + montague@montague.net + + + +]]> +

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.net + + + montague@montague.net + + + + ]]> + +

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

+ + + + + +

If a server or other entity hosts archives and supports MAM queries, it MUST advertise that fact + by including the feature "urn:xmpp:mam:tmp" in response to a &xep0030; request:

+ + + +]]> + + + + ... + + ... + + +]]> + + +