mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 23:28:51 -05:00
XEP-0313: new revision 0.7
Plus (after ML discussion): - Clarify intention of 'with' field rule - Add 'ids' field for fetching specific messages - Add archive metadata query - relax language about inclusion of RSM count/index These were always optional, but the XEP encouraged their use. Implementation experience has shown that generating the count has significant performance cost, while most/all current clients ignore it anyway.
This commit is contained in:
Matthew Wild
Jonas Schäfer
parent
92000ad16d
commit
a3e6d10651
572
xep-0313.xml
572
xep-0313.xml
@ -10,7 +10,7 @@
|
||||
<abstract>This document defines a protocol to query and control an archive of messages stored on a server.</abstract>
|
||||
&LEGALNOTICE;
|
||||
<number>0313</number>
|
||||
<status>Deferred</status>
|
||||
<status>Experimental</status>
|
||||
<lastcall>2017-11-15</lastcall>
|
||||
<type>Standards Track</type>
|
||||
<sig>Standards</sig>
|
||||
@ -28,6 +28,16 @@
|
||||
</schemaloc>
|
||||
&mwild;
|
||||
&ksmith;
|
||||
<revision>
|
||||
<version>0.7.0</version>
|
||||
<date>2020-03-20</date>
|
||||
<initials>mw</initials>
|
||||
<remark>
|
||||
<p>Add 'before-id' and 'after-id' fields, flipped pages, single-item retrieval and a new mandatory disco feature</p>
|
||||
<p>Split preferences protocol into a separate document</p>
|
||||
<p>Split the details of pubsub archives into a separate document</p>
|
||||
</remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.6.3</version>
|
||||
<date>2018-07-16</date>
|
||||
@ -176,9 +186,9 @@
|
||||
<li>The remote JID that the stanza is to (for an outgoing message) or from (for an
|
||||
incoming message).</li>
|
||||
<li>A server-assigned UID that MUST be unpredictable and unique within the archive.</li>
|
||||
<li>The message stanza itself. The entire original stanza SHOULD be stored, but at a
|
||||
minimum only the &BODY; tag MUST be preserved (ie. the server might, at its
|
||||
discretion, strip certain extensions from messages before storage).</li>
|
||||
<li>The message stanza itself. The entire original stanza SHOULD be stored, but at a minimum only the &BODY; tag MUST
|
||||
be preserved (ie. the server might, at its discretion, strip certain extensions from messages before storage), in
|
||||
addition to all standard attributes of the stanza (e.g. to, from, type, id).</li>
|
||||
</ul>
|
||||
<p>Note that 'incoming' and 'outgoing' messages are viewed within the context of the archived JID, rather than the system as a whole. For example, if romeo@montegue.lit sent a message to juliet@capulet.lit, it would be an outgoing message in the context of archiving for Romeo, and an incoming message in the context of archiving for Juliet.</p>
|
||||
<section2 topic='Order of messages' anchor='archive_order'>
|
||||
@ -200,7 +210,7 @@
|
||||
or cache that clients may keep.</p>
|
||||
</section2>
|
||||
<section2 topic='Archiving entities' anchor='archiving_entities'>
|
||||
<p>There is no restriction on which services can expose archives, although only user, MUC and pubsub node archives are discussed here.</p>
|
||||
<p>There is no restriction on which services can expose archives, although only user and MUC archives are discussed here.</p>
|
||||
<section3 topic='User archives' anchor='archives_user'>
|
||||
<p>The most typical address is that of a user's own bare JID, within which those messages sent to or from that
|
||||
user's account would generally automatically be stored by the server. The collection
|
||||
@ -211,9 +221,6 @@
|
||||
<section3 topic='MUC archives' anchor='archives_muc'>
|
||||
<p>A MUC service allowing MAM queries for a room MUST expose the MAM archive on the room's bare JID</p>
|
||||
</section3>
|
||||
<section3 topic='Pubsub node archives' anchor='archives_pubsub'>
|
||||
<p>A pubsub service allowing MAM queries for a node's data MUST expose this for queries addressed to the pubsub service</p>
|
||||
</section3>
|
||||
</section2>
|
||||
<section2 topic='Querying Entities' anchor='entities'>
|
||||
<p>While this document talks about 'clients' and 'servers', as these are the common cases, the querying entity (referred to as a 'client') need not be an XMPP client as defined by RFC6120, but could potentially be any type of entity, and the queried entity (referred to as a 'server') need not be an XMPP server as defined by RFC6120, although access controls might prohibit any given entity from being able to access an archive.</p>
|
||||
@ -272,30 +279,36 @@
|
||||
</iq>]]></example>
|
||||
<p>To ensure that the client knows when the results are complete, the server MUST send the &IQ; result after last query result has been sent
|
||||
to the client. The client can optionally include a 'queryid' attribute in their query, which allows the client to match results to their initiating query.</p>
|
||||
<p>When querying a pubsub node's archive, the 'node' attribute is added to the <query> element.</p>
|
||||
<example caption="A user queries a pubsub node's archive for messages"><![CDATA[
|
||||
<example caption="A user queries an archive for messages"><![CDATA[
|
||||
<iq to='pubsub.shakespeare.lit' type='set' id='juliet1'>
|
||||
<query xmlns='urn:xmpp:mam:2' queryid='f28' node='fdp/submitted/capulet.lit/sonnets'/>
|
||||
<query xmlns='urn:xmpp:mam:2' queryid='f28' />
|
||||
</iq>
|
||||
]]></example>
|
||||
<section2 topic='Filtering results' anchor='filter'>
|
||||
<p>By default all messages match a query, and filters are used to request a subset of the archived
|
||||
messages. Filters are specified in a &xep0004; data form included with the query. The hidden FORM_TYPE field
|
||||
MUST be set to this protocol's namespace, 'urn:xmpp:mam:2'. Three further fields are defined by this
|
||||
MUST be set to this protocol's namespace, 'urn:xmpp:mam:2'. Six further fields are defined by this
|
||||
XEP and MUST be supported by servers, though all of them are optional for the client. These fields are:</p>
|
||||
<ul>
|
||||
<li>start</li>
|
||||
<li>end</li>
|
||||
<li>with</li>
|
||||
<li>before-id (*)</li>
|
||||
<li>after-id (*)</li>
|
||||
<li>ids (*)</li>
|
||||
</ul>
|
||||
|
||||
<p>Servers supporting fields marked with an asterisk (*) MUST advertise the disco feature 'urn:xmpp:mam:2#extended' and clients
|
||||
that depend on these fields MUST verify that the server advertises this feature before attempting to use them.</p>
|
||||
|
||||
<p>Other fields may be used, but are not defined in this document - the naming of new fields MUST be
|
||||
consistent with the format defined in &xep0068;. Servers MUST NOT mark any fields in the form as
|
||||
being required (i.e. with the data forms <required/> element), regardless of whether they are
|
||||
defined in this document or elsewhere.</p>
|
||||
<section3 topic='Filtering by JID' anchor='filter-jid'>
|
||||
<p>If a 'with' field is present in the form, it contains a JID against which to match messages. The
|
||||
server MUST only return messages if they match the supplied JID. A message in a user's archive matches if the JID matches either the to or from of the message. An item in a pubsub or MUC archive matches if the publisher of the item matches the JID; note that this should only be available to entities that would already have been allowed to know the publisher of the events (e.g. this could not be used by a visitor to a semi-anonymous MUC).</p>
|
||||
<p>If the 'with' field's value is the bare JID of the archive, the server must only return results where both the 'to' and 'from' match the bare JID (either as bare or by ignoring the resource), as otherwise every message in the archive would match</p>
|
||||
server MUST only return messages if they match the supplied JID. A message in a user's archive matches if the JID matches either the to or from of the message. An item in a MUC archive matches if the publisher of the item matches the JID; note that this should only be available to entities that would already have been allowed to know the publisher of the events (e.g. this could not be used by a visitor to a semi-anonymous MUC).</p>
|
||||
<p>To allow querying for messages the user sent to themselves, the client needs to set the 'with' attribute to the account JID. In that case, the server MUST only return results where both the 'to' and 'from' match the bare JID (either as bare or by ignoring the resource), as otherwise every message in the archive would match.</p>
|
||||
<p>If 'with' is omitted, the server MUST match all messages in the selected timespan with the query,
|
||||
regardless of the to/from addresses on each message.</p>
|
||||
<example caption='Querying for all messages to/from a particular JID'><![CDATA[
|
||||
@ -362,96 +375,73 @@
|
||||
</iq>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Limiting results' anchor='query-limit'>
|
||||
<p>Finally, in order for the client or server to limit the number of results transmitted at
|
||||
a time a server MUST support &xep0059; and MUST support the paging mechanism defined therein.
|
||||
A client MAY include a <set/> element in its query.</p>
|
||||
<p>For the purposes of this protocol, the UIDs used by RSM correspond with the UIDs of the
|
||||
stanzas stored in the archive.</p>
|
||||
<example caption='A query using Result Set Management'><![CDATA[
|
||||
<iq type='set' id='q29302'>
|
||||
<section3 topic='Limiting results by id' anchor='query-limit-id'>
|
||||
<p>If the client has already seen some messages, it may choose to restrict its query to
|
||||
before and/or after messages it already knows about. This may be done through the 'before-id'
|
||||
and 'after-id' fields.</p>
|
||||
<example caption='Querying the archive for all messages after a certain message'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'>
|
||||
<value>urn:xmpp:mam:2</value>
|
||||
</field>
|
||||
<field var='start'>
|
||||
<value>2010-08-07T00:00:00Z</value>
|
||||
<field var='after-id'>
|
||||
<value>09af3-cc343-b409f</value>
|
||||
</field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>To conserve resources, a server MAY place a reasonable limit on how many stanzas may be
|
||||
pushed to a client in one request. Whether or not the client query included a <set/> element, the server MAY simply return
|
||||
its limited results, modifying the <set/> element it returns appropriately.</p>
|
||||
<example caption='Server responds to client with limited results using RSM'><![CDATA[
|
||||
<!-- result messages -->
|
||||
<iq type='result' id='q29302'>
|
||||
<fin xmlns='urn:xmpp:mam:2'>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<first index='0'>28482-98726-73623</first>
|
||||
<last>09af3-cc343-b409f</last>
|
||||
<count>20</count>
|
||||
</set>
|
||||
</fin>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The <first> and <last> elements specify the UID of the first and last returned
|
||||
results (not necessarily of all the messages that matched the query, if the results have been limited).</p>
|
||||
|
||||
<p>The RSM <count> element and the 'index' attribute on the RSM <first> element are optional,
|
||||
but servers SHOULD include them. Please refer to the RSM specification for more information
|
||||
surrounding their meaning and use.</p>
|
||||
</section3>
|
||||
<section3 topic='Paging through results' anchor='query-paging'>
|
||||
<p>Having previously made a query that returned results limited by the server (as described above), a client
|
||||
can re-send the same request and receive the next 'page' of results. It does this by including a <set>
|
||||
element with its request, containing an <after/> with the UID of the last message it received
|
||||
from the previous query.</p>
|
||||
<example caption='A page query using Result Set Management'><![CDATA[
|
||||
<iq type='set' id='q29303'>
|
||||
<example caption='Querying the archive for all messages between two known messages'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:2</value></field>
|
||||
<field var='start'><value>2010-08-07T00:00:00Z</value></field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
<after>09af3-cc343-b409f</after>
|
||||
</set>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'>
|
||||
<value>urn:xmpp:mam:2</value>
|
||||
</field>
|
||||
<field var='after-id'>
|
||||
<value>28482-98726-73623</value>
|
||||
</field>
|
||||
<field var='before-id'>
|
||||
<value>09af3-cc343-b409f</value>
|
||||
</field>
|
||||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.</p>
|
||||
<p>If the UID contained within an <after> or <before> element is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
|
||||
<p>When the results returned by the server are complete (that is: when they have not been limited by the maximum size of the result page (either as specified or enforced by the server)), the server MUST include a 'complete' attribute on the <fin> element, with a value of 'true'; this informs the client that it doesn't need to perform further paging to retreive the requested data. If it is not the last page of the result set, the server MUST either omit the 'complete' attribute, or give it a value of 'false'.</p>
|
||||
<example caption='Server completes a result with the last page of messages'><![CDATA[
|
||||
<!-- result messages -->
|
||||
<iq type='result' id='u29303'>
|
||||
<fin xmlns='urn:xmpp:mam:2' complete='true'>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<first index='0'>23452-4534-1</first>
|
||||
<last>390-2342-22</last>
|
||||
<count>16</count>
|
||||
</set>
|
||||
</fin>
|
||||
|
||||
<p>If the client already knows the UID of one or more messages it wants to fetch, it can use
|
||||
the 'ids' field:</p>
|
||||
|
||||
<example caption='Fetching a specific message from the archive'><![CDATA[
|
||||
<iq type='set' id='juliet1'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'>
|
||||
<value>urn:xmpp:mam:2</value>
|
||||
</field>
|
||||
<field var='ids'>
|
||||
<value>28482-98726-73623</value>
|
||||
</field>
|
||||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Sometimes (e.g. due to network or storage partitioning, or other transient errors) the server might return results to a client that are unstable (e.g. they might later change in sequence or content). In such a situation the server MUST stamp the <fin> element with a 'stable' attribute with a value of 'false'. If the server knows that the data it's serving are stable it MUST either stamp a 'stable' attribute with a value of 'true', or no such attribute. An example of when unstable might legitimately be returned is if the MAM service uses a clustered data store and a query covers a time period for which the data store has not yet converged; it the server could return best-guess results and tell the client that they may be unstable. A client SHOULD NOT cache unstable results long-term without later confirming (by reissuing appropriate queries) that they have become stable.</p>
|
||||
|
||||
<p>If any UID requested by the client in any of the 'before-id', 'after-id' or 'ids' form fields, the server MUST return an item-not-found error in response to the query.</p>
|
||||
|
||||
</section3>
|
||||
<section3 topic='Retrieving form fields' anchor='query-form'>
|
||||
<p>In order for the client find out about additional fields the server might support, it can send an iq stanza of type 'get' addressed to the archive like this:</p>
|
||||
<example caption="Client requests supported query fields"><![CDATA[
|
||||
<section3 topic='Retrieving form fields' anchor='query-form'>
|
||||
<p>In order for the client find out about additional fields the server might support, it can send an iq stanza of type 'get' addressed to the archive like this:</p>
|
||||
<example caption="Client requests supported query fields"><![CDATA[
|
||||
<iq type='get' id='form1'>
|
||||
<query xmlns='urn:xmpp:mam:2'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The server replies with all the form fields it supports in queries, which MUST include the mandatory fields specified in this document.</p>
|
||||
<example caption="Server returns supported fields"><![CDATA[
|
||||
<p>The server replies with all the form fields it supports in queries, which MUST include the mandatory fields specified in this document.</p>
|
||||
<example caption="Server returns supported fields"><![CDATA[
|
||||
<iq type='result' id='form1'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='form'>
|
||||
@ -461,14 +451,23 @@
|
||||
<field type='jid-single' var='with'/>
|
||||
<field type='text-single' var='start'/>
|
||||
<field type='text-single' var='end'/>
|
||||
<field type='text-single' var='urn:example:xmpp:free-text-search'/>
|
||||
<field type='text-single' var='urn:example:xmpp:stanza-content'/>
|
||||
<field type='text-single' var='before-id'/>
|
||||
<field type='text-single' var='after-id'/>
|
||||
<field type='list-multi' var='ids'>
|
||||
<validate xmlns="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||||
<open/>
|
||||
</validate>
|
||||
</field>
|
||||
<field type='text-single' var='{http://example.com/}free-text-search'/>
|
||||
<field type='text-single' var='{http://example.com/}stanza-content'/>
|
||||
</x>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>If the client understands any of the additional fields it MAY proceed to include any of them in subsequent queries. It is not required to include any or all of the supported fields in queries.</p>
|
||||
<example caption="Client uses two discovered query fields in a query"><![CDATA[
|
||||
<p>If the client understands any of the additional fields it MAY proceed to include any of them in subsequent queries. It is not required to include any or all of the supported fields in queries.</p>
|
||||
<p>A special note about the 'ids' field: this field is of type 'list-multi' which typically is used to allow the client to select from a provided list of options. In this case the list of all possible ids MUST NOT be provided by the server, as it is likely to be extremely large. Instead the server MUST include a &xep0122; <validate/> element that signals the list is open to arbitrary values provided by the client.</p>
|
||||
<p>As specified in &xep0068;, names of custom fields SHOULD use Clark notation to avoid conflicts with other extensions.</p>
|
||||
<example caption="Client uses two discovered query fields in a query"><![CDATA[
|
||||
<iq type='set' id='query4'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
@ -485,9 +484,11 @@
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note that as the 'with', 'start' and 'end' fields MUST be implemented by servers, clients are able to submit forms using combinations of only these fields without needing to first fetch the form from the server and the types of these fields MUST be 'jid-single', 'text-single' and 'text-single' respectively. A server MUST NOT rely on a client having first requested the form before submitting queries</p>
|
||||
</section3>
|
||||
<p>Note that as the 'with', 'start' and 'end' fields MUST be implemented by servers, clients are able to submit forms using combinations of only these fields without needing to first fetch the form from the server and the types of these fields MUST be 'jid-single', 'text-single' and 'text-single' respectively. A server MUST NOT rely on a client having first requested the form before submitting queries</p>
|
||||
<p>If a client includes a form field that the server does not recognise, the server MUST respond with a 'feature-not-implemented' error.</p>
|
||||
</section3>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Query results' anchor='results'>
|
||||
<p>The server responds to the archive query by transmitting to the client all the messages
|
||||
that match the criteria the client requested, subject to implementation limits. The results are sent as individual stanzas,
|
||||
@ -534,6 +535,167 @@
|
||||
</message>
|
||||
]]></example>
|
||||
</section2>
|
||||
|
||||
<section2 topic='Paging through results' anchor='query-paging'>
|
||||
<section3 topic='Page limits' anchor='query-paging-limit'>
|
||||
<p>A client or server will typically want to limit the number of results transmitted at
|
||||
a time, thereby breaking the result stream into smaller 'pages'. For this purpose a
|
||||
server MUST support &xep0059; and MUST support the paging mechanism defined therein.
|
||||
A client MAY include a <set/> element in its query.</p>
|
||||
<p>For the purposes of this protocol, the UIDs used by RSM correspond with the UIDs of the
|
||||
stanzas stored in the archive.</p>
|
||||
<example caption='A query using Result Set Management'><![CDATA[
|
||||
<iq type='set' id='q29302'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'>
|
||||
<value>urn:xmpp:mam:2</value>
|
||||
</field>
|
||||
<field var='start'>
|
||||
<value>2010-08-07T00:00:00Z</value>
|
||||
</field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>To conserve resources, a server MAY place a reasonable limit on how many stanzas may be
|
||||
pushed to a client in one request. Whether or not the client query included a <set/> element, the server MAY simply return
|
||||
its limited results, modifying the <set/> element it returns appropriately.</p>
|
||||
<example caption='Server responds to client with limited results using RSM'><![CDATA[
|
||||
<!-- result messages -->
|
||||
<iq type='result' id='q29302'>
|
||||
<fin xmlns='urn:xmpp:mam:2'>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<first index='0'>28482-98726-73623</first>
|
||||
<last>09af3-cc343-b409f</last>
|
||||
<count>20</count>
|
||||
</set>
|
||||
</fin>
|
||||
</iq>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic='Requesting pages' anchor='query-paging-request'>
|
||||
<p>The <first> and <last> elements specify the UID of the first and last returned
|
||||
results (not necessarily of all the messages that matched the query, if the results have been limited).</p>
|
||||
|
||||
<p>The RSM <count> element and the 'index' attribute on the RSM <first> element are optional,
|
||||
a server MAY include them, but a client MUST NOT depend on them being present. Please refer to the RSM
|
||||
specification for more information surrounding their meaning and use.</p>
|
||||
<p>Having previously made a query that returned results limited by the server (as described above), a client
|
||||
can re-send the same request and receive the next 'page' of results. It does this by including a <set>
|
||||
element with its request, containing an <after/> with the UID of the last message it received
|
||||
from the previous query.</p>
|
||||
<example caption='A page query using Result Set Management'><![CDATA[
|
||||
<iq type='set' id='q29303'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:2</value></field>
|
||||
<field var='start'><value>2010-08-07T00:00:00Z</value></field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
<after>09af3-cc343-b409f</after>
|
||||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Note: There is no concept of an "open query", and servers MUST be prepared to receive arbitrary page requests at any time.</p>
|
||||
<p>RSM does not define the behaviour of including both <before> and <after> in the same request. To retrieve a range of items between two known ids, use before-id and after-id in the query form instead.</p>
|
||||
<p>If the UID contained within an <after> or <before> element is not present in the archive, the server MUST return an item-not-found error in response to the query.</p>
|
||||
<example caption='Message id not found in archive'><![CDATA[
|
||||
<iq type='error' id='q29303'>
|
||||
<error type='cancel'>
|
||||
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
||||
</error>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>When the results returned by the server are complete (that is: when they have not been limited by the maximum size of the result page (either as specified or enforced by the server)), the server MUST include a 'complete' attribute on the <fin> element, with a value of 'true'; this informs the client that it doesn't need to perform further paging to retreive the requested data. If it is not the last page of the result set, the server MUST either omit the 'complete' attribute, or give it a value of 'false'.</p>
|
||||
<example caption='Server completes a result with the last page of messages'><![CDATA[
|
||||
<!-- result messages -->
|
||||
<iq type='result' id='u29303'>
|
||||
<fin xmlns='urn:xmpp:mam:2' complete='true'>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<first index='0'>23452-4534-1</first>
|
||||
<last>390-2342-22</last>
|
||||
<count>16</count>
|
||||
</set>
|
||||
</fin>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Sometimes (e.g. due to network or storage partitioning, or other transient errors) the server might return results to a client that are unstable (e.g. they might later change in sequence or content). In such a situation the server MUST stamp the <fin> element with a 'stable' attribute with a value of 'false'. If the server knows that the data it's serving are stable it MUST either stamp a 'stable' attribute with a value of 'true', or no such attribute. An example of when unstable might legitimately be returned is if the MAM service uses a clustered data store and a query covers a time period for which the data store has not yet converged; it the server could return best-guess results and tell the client that they may be unstable. A client SHOULD NOT cache unstable results long-term without later confirming (by reissuing appropriate queries) that they have become stable.</p>
|
||||
</section3>
|
||||
<section3 topic='Requesting the last page'>
|
||||
<p>To request the page at the end of the archive (i.e. the most recent messages), include just an empty <before/> element in the RSM part of the query. As defined by RSM, this will return the last page of the archive.</p>
|
||||
<example caption='A request for the last page in an archive'><![CDATA[
|
||||
<iq type='set' id='q29303'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:2</value></field>
|
||||
<field var='start'><value>2010-08-07T00:00:00Z</value></field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
<before/>
|
||||
</set>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>Within the returned page, all results are still in chronological order, that is, the first result you receive will be the oldest item in the page, and the last result you receive will be the last item in the archive.</p>
|
||||
</section3>
|
||||
<section3 topic='Flipped pages' anchor='query-paging-flip'>
|
||||
<p>When fetching a page, the client may prefer for the server to send the results within that page in reverse order.
|
||||
For example, if a client implements a user interface that automatically fetches older messages as a user scrolls backward,
|
||||
it may want to receive and display the newest messages first, instead of waiting for the whole page to be received.</p>
|
||||
<p>A client wishing for a reversed page should include the <flip-page/> element in its query, like so:</p>
|
||||
<example caption='Requesting a page that is flipped'><![CDATA[
|
||||
<iq type='set' id='q29309'>
|
||||
<query xmlns='urn:xmpp:mam:2'>
|
||||
<x xmlns='jabber:x:data' type='submit'>
|
||||
<field var='FORM_TYPE' type='hidden'><value>urn:xmpp:mam:2</value></field>
|
||||
<field var='start'><value>2010-08-07T00:00:00Z</value></field>
|
||||
</x>
|
||||
<set xmlns='http://jabber.org/protocol/rsm'>
|
||||
<max>10</max>
|
||||
<after>09af3-cc343-b409f</after>
|
||||
</set>
|
||||
<flip-page/>
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>It is important to note that flipping a page does not affect what results are returned in response to the query. It only affects the
|
||||
order in which they are transmitted from the server to the client.</p>
|
||||
<p>A client that wishes to use flipped pages MUST ensure that the server advertises the 'urn:xmpp:mam:2#extended' feature.</p>
|
||||
</section3>
|
||||
</section2>
|
||||
|
||||
</section1>
|
||||
|
||||
<section1 topic='Archive metadata' anchor='archive-metadata'>
|
||||
<p>When planning a query, a client may wish to learn the current state of the archive. This includes information about the first/last entries in the archive.</p>
|
||||
|
||||
<p>When the archive advertises support for 'urn:xmpp:mam:2#extended' then the archive supports queries for this metadata via an iq of type 'get' to the
|
||||
archive's address, with a <metadata/> payload in the 'urn:xmpp:mam:2' namespace.</p>
|
||||
|
||||
<example caption='Requesting archive metadata'><![CDATA[
|
||||
<iq type='get' id='jui8921rr9'>
|
||||
<metadata xmlns='urn:xmpp:mam:2'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<example caption='Server returns archive metadata'><![CDATA[
|
||||
<iq type='result' id='jui8921rr9'>
|
||||
<metadata xmlns='urn:xmpp:mam:2'>
|
||||
<start id='YWxwaGEg' timestamp='2008-08-22T21:09:04Z' />
|
||||
<end id='b21lZ2Eg' timestamp='2020-04-20T14:34:21Z' />
|
||||
</metadata>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>The server response includes a <metadata/> element containing information about the archive. This element MUST include <start/> and <end/>
|
||||
elements, which each have an 'id' and XEP-0082 formatted 'timestamp of the first and last messages in the archive respectively.</p>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Business Rules' anchor='business_rules'>
|
||||
@ -592,42 +754,11 @@
|
||||
</result>
|
||||
</message>
|
||||
]]></example>
|
||||
</section3>
|
||||
<section3 topic="Pubsub Archives" anchor='business-storeret-pubsub-archives'>
|
||||
<p>A PubSub service offering MAM SHOULD store each of the items published to each node. When responding to MAM requests it MUST construct the message stanza within the <forwarded> element in the same manner as the notifications sent to subscribers for the item, except that specifying the 'from' 'to' and 'id' attributes are OPTIONAL. Pubsub items must be returned one per message stanza (i.e. there MUST NOT be multiple <item> elements within the <items> element).</p>
|
||||
<example caption='Server returns a pubsub messages'><![CDATA[
|
||||
<message id='iasd208' to='juliet@capulet.lit/chamber'>
|
||||
<result xmlns='urn:xmpp:mam:2' queryid='g28' id='28482-20987-73623'>
|
||||
<forwarded xmlns='urn:xmpp:forward:0'>
|
||||
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
|
||||
<message xmlns="jabber:client">
|
||||
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||
<items node='princely_musings'>
|
||||
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
|
||||
<entry xmlns='http://www.w3.org/2005/Atom'>
|
||||
<title>Soliloquy</title>
|
||||
<summary>
|
||||
To be, or not to be: that is the question:
|
||||
Whether 'tis nobler in the mind to suffer
|
||||
The slings and arrows of outrageous fortune,
|
||||
Or to take arms against a sea of troubles,
|
||||
And by opposing end them?
|
||||
</summary>
|
||||
<link rel='alternate' type='text/html'
|
||||
href='http://denmark.lit/2003/12/13/atom03'/>
|
||||
<id>tag:denmark.lit,2003:entry-32397</id>
|
||||
<published>2003-12-13T18:30:02Z</published>
|
||||
<updated>2003-12-13T18:30:02Z</updated>
|
||||
</entry>
|
||||
</item>
|
||||
</items>
|
||||
</event>
|
||||
</message>
|
||||
</forwarded>
|
||||
</result>
|
||||
</message>]]></example>
|
||||
</section3>
|
||||
|
||||
<section3 topic='Pubsub archives' anchor='business-storeret-pubsub-archives'>
|
||||
<p>This specification reserves the 'node' attribute of the <query> element for use with pubsub archives. Full details of using
|
||||
this protocol to query pubsub node archives are documented in [FIXME: number to be assigned to xep-pubsub-mam].</p>
|
||||
</section3>
|
||||
</section2>
|
||||
<section2 topic='IDs' anchor='business-ids'>
|
||||
<p>The IDs used within an archive MUST be unique per item stored and MUST NOT be reused, even if the original item with a given ID has since been removed from the archive. If a server provides multiple archives (e.g. many user archives, or many MUC archives), the IDs do not need to be unique across all of these archives unless the server also allows a single query to be run across multiple archives (e.g. searching of all MUC rooms), discussion of which is beyond the scope of this document. These IDs are strings that servers may construct in any manner, and clients must treat as opaque strings (e.g. there is no requirement for them to be numeric, sequenced or GUIDs).</p>
|
||||
@ -640,160 +771,10 @@
|
||||
</section2>
|
||||
</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>
|
||||
<section2 topic='Processing Hints' anchor='hints'>
|
||||
<p>Clients can use &xep0334; for signaling that they do not wish some messages to be stored in the archive.</p>
|
||||
<example><![CDATA[
|
||||
<message from='romeo@montague.lit/laptop' to='juliet@capulet.lit/laptop'>
|
||||
<body>V unir avtug'f pybnx gb uvqr zr sebz gurve fvtug</body>
|
||||
<no-store xmlns='urn:xmpp:hints'/>
|
||||
</message>
|
||||
]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
|
||||
<section1 topic='Determining support' anchor='support'>
|
||||
<p>If a server or other entity hosts archives and supports MAM queries, it MUST advertise
|
||||
the 'urn:xmpp:mam:2' feature in response to &xep0030; requests made to archiving JIDs
|
||||
(i.e. JIDs hosting an archive, such as users' bare JIDs):
|
||||
the 'urn:xmpp:mam:2' and 'urn:xmpp:mam:2#extended' features in response to &xep0030; requests
|
||||
made to archiving JIDs (i.e. JIDs hosting an archive, such as users' bare JIDs):
|
||||
</p>
|
||||
<example caption='Client queries for server features'><![CDATA[
|
||||
<iq type='get' id='disco1' to='juliet@capulet.lit' from='juliet@capulet.lit/balcony'>
|
||||
@ -806,10 +787,49 @@
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||||
...
|
||||
<feature var='urn:xmpp:mam:2'/>
|
||||
<feature var='urn:xmpp:mam:2#extended'/>
|
||||
...
|
||||
</query>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>Servers advertising the 'urn:xmpp:mam:2#extended' feature MUST implement the 'before-id' and 'after-id' fields, as well as support for
|
||||
flipped pages and single-item retrieval. The 'urn:xmpp:mam:2#extended' feature MUST NOT be advertised by a server without also advertising
|
||||
'urn:xmpp:mam:2'.</p>
|
||||
|
||||
<table caption='Extended namespace feature comparison'>
|
||||
<tr>
|
||||
<th>Feature</th>
|
||||
<th>urn:xmpp:mam:2</th>
|
||||
<th>urn:xmpp:mam:2#extended</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Queries using 'with', 'start' and 'end'</td>
|
||||
<td>Required</td>
|
||||
<td>Required</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Error responses for missing UIDs</td>
|
||||
<td>Required</td>
|
||||
<td>Required</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Queries using 'before-id', 'after-id' or 'ids'</td>
|
||||
<td>-</td>
|
||||
<td>Required</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Page flipping</td>
|
||||
<td>-</td>
|
||||
<td>Required</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Archive metadata query</td>
|
||||
<td>-</td>
|
||||
<td>Required</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</section1>
|
||||
|
||||
<section1 topic='Security Considerations' anchor='security'>
|
||||
@ -843,7 +863,7 @@
|
||||
|
||||
<section1 topic='Acknowledgements' anchor='acks'>
|
||||
<p>Many thanks to Dave Cridland, Kim Alvefur, Yann Leboulanger, Evgeny Khramtsov, Florian Schmaus, Lance Stout,
|
||||
Waqas Hussain and Daniel Gultsch for their input and feedback on this specification.</p>
|
||||
Waqas Hussain, Daniel Gultsch, Philipp Hörist, Jonas Schäfer and Georg Lukas for their input and feedback on this specification.</p>
|
||||
</section1>
|
||||
|
||||
</xep>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user