moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

Merge pull request #22 from Flowdalic/mam-wo-sentinel

Browse Source 
Remove message sentinel from MAM (XEP-0313)
This commit is contained in:
Peter Saint-Andre 2015-08-18 09:10:36 -06:00
commit 687b1b9a73
1 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
xep-0313.xml
View File

@ -151,7 +151,7 @@
<p>A query consists of an &IQ; stanza of type='set' 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
a &MESSAGE; with a &lt;fin/&gt; tag to indicate that the query is completed.</p>
the &IQ; result to indicate that the query is completed.</p>
<p>The final &MESSAGE; response MUST include an RSM &lt;set/&gt; element indicating the
UID of the first and last message of the (possibly limited) result set. This
allows clients to accurately page through messages.</p>
@ -160,19 +160,21 @@
<query xmlns='urn:xmpp:mam:0' queryid='f27' />
</iq>]]></example>
<example caption='Their server accepts the query'><![CDATA[
<iq type='result' id='juliet1'/>]]></example>
<example caption='Their server sends the matching messages'><![CDATA[
<message from="witch@shakespeare.lit" to="macbeth@shakespeare.lit">
<body>Hail to thee</body>
<message id='aeb213' to='juliet@capulet.lit/chamber'>
<result xmlns='urn:xmpp:mam:0' queryid='f27' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message from="witch@shakespeare.lit" to="macbeth@shakespeare.lit">
<body>Hail to thee</body>
</message>
</forwarded>
</result>
</message>]]></example>
<example caption='Server returns the message sentinel'><![CDATA[
<message>
<fin xmlns='urn:xmpp:mam:0' queryid='f27' />
</message>]]></example>
<p>To ensure that the client knows when the results are complete, the server MUST send a &lt;fin&gt; message. The client can optionally include a 'queryid' attribute in their query, which allows the client to match results to their initiating query, and if present in the client's query the server MUST include it in the &lt;fin&gt; response.</p>
<example caption='Server returns the result IQ to signal the end'><![CDATA[
<iq type='result' id='juliet1'/>]]></example>
<p>To ensure that the client knows when the results are complete, the server MUST send the &IQ; result after the last message retrieved from the archive. 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 &lt;query&gt; element.</p>
<example caption="A user queries a pubsub node's archive for messages"><![CDATA[
<iq to='pubsub.shakespeare.lit' type='set' id='juliet1'>
@ -290,9 +292,8 @@
pushed to a client in one request. Whether or not the client query included a &lt;set/&gt; element, the server MAY simply return
its limited results, modifying the &lt;set/&gt; element it returns appropriately.</p>
<example caption='Server responds to client with limited results using RSM'><![CDATA[
<iq type='result' id='q29302'/>
<!-- result messages -->
<message>
<iq type='result' id='q29302'>
<fin xmlns='urn:xmpp:mam:0'>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>28482-98726-73623</first>
@ -329,11 +330,10 @@
</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>When the results returned by the server are complete (that is: when they are the last page of the result set), the server MUST include a 'complete' attribute on the &lt;fin&gt; element, with a value of 'true'. 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>
<p>When the results returned by the server are complete (that is: when they are the last page of the result set), the server MUST include a 'complete' attribute in the &IQ; result, with a value of 'true'. 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[
<iq type='result' id='u29303'/>
<!-- result messages -->
<message>
<iq type='result' id='u29303'>
<fin xmlns='urn:xmpp:mam:0' complete='true'>
<set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>23452-4534-1</first>
@ -341,9 +341,9 @@
<count>16</count>
</set>
</fin>
</message>
</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 &lt;fin&gt; 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>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 &IQ; result 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='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>