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

Remove message sentinel from MAM (XEP-0313)

Browse Source 
The MAM history already says "Switch the sentinel message back to the iq
result.", but this has never happened. This commit does the switch.
This commit is contained in:
Florian Schmaus 2015-07-18 11:25:15 +02:00
parent 44b8c2cd1f
commit f465e5d1f6
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>