moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2025-02-16 07:10:15 -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 <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 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 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 <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 UID of the first and last message of the (possibly limited) result set. This
allows clients to accurately page through messages.</p> allows clients to accurately page through messages.</p>
@ -160,19 +160,21 @@
<query xmlns='urn:xmpp:mam:0' queryid='f27' /> <query xmlns='urn:xmpp:mam:0' queryid='f27' />
</iq>]]></example> </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[ <example caption='Their server sends the matching messages'><![CDATA[
<message from="witch@shakespeare.lit" to="macbeth@shakespeare.lit"> <message id='aeb213' to='juliet@capulet.lit/chamber'>
<body>Hail to thee</body> <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> </message>]]></example>
<example caption='Server returns the message sentinel'><![CDATA[ <example caption='Server returns the result IQ to signal the end'><![CDATA[
<message> <iq type='result' id='juliet1'/>]]></example>
<fin xmlns='urn:xmpp:mam:0' queryid='f27' /> <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>
</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>
<p>When querying a pubsub node's archive, the 'node' attribute is added to the &lt;query&gt; element.</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[ <example caption="A user queries a pubsub node's archive for messages"><![CDATA[
<iq to='pubsub.shakespeare.lit' type='set' id='juliet1'> <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 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> 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[ <example caption='Server responds to client with limited results using RSM'><![CDATA[
<iq type='result' id='q29302'/>
<!-- result messages --> <!-- result messages -->
<message> <iq type='result' id='q29302'>
<fin xmlns='urn:xmpp:mam:0'> <fin xmlns='urn:xmpp:mam:0'>
<set xmlns='http://jabber.org/protocol/rsm'> <set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>28482-98726-73623</first> <first index='0'>28482-98726-73623</first>
@ -329,11 +330,10 @@
</iq> </iq>
]]></example> ]]></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>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[ <example caption='Server completes a result with the last page of messages'><![CDATA[
<iq type='result' id='u29303'/>
<!-- result messages --> <!-- result messages -->
<message> <iq type='result' id='u29303'>
<fin xmlns='urn:xmpp:mam:0' complete='true'> <fin xmlns='urn:xmpp:mam:0' complete='true'>
<set xmlns='http://jabber.org/protocol/rsm'> <set xmlns='http://jabber.org/protocol/rsm'>
<first index='0'>23452-4534-1</first> <first index='0'>23452-4534-1</first>
@ -341,9 +341,9 @@
<count>16</count> <count>16</count>
</set> </set>
</fin> </fin>
</message> </iq>
]]></example> ]]></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>
<section3 topic='Retrieving form fields' anchor='query-form'> <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> <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>