mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-23 16:18:51 -05:00
204 lines
11 KiB
XML
204 lines
11 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
<!ENTITY ns "urn:xmpp:mamfc:0">
|
|
<!ENTITY nsx "urn:example:">
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>MAM Fastening Collation</title>
|
|
<abstract>This specification proposes a mechanism by which MAM results containing fastenings can be collated effectively.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>XXXX</number>
|
|
<status>ProtoXEP</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0422</spec>
|
|
<spec>XEP-0313</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>mamfc</shortname>
|
|
&dcridland;
|
|
&ksmithisode;
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2019-12-19</date>
|
|
<initials>dwd</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Initial Revision</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>In XMPP, all messages are not equal. Some are semantically actual human messages; these are referred to in this
|
|
document as "instant messages". Others are ancillary messages - reactions, receipts, and so on - that are useful
|
|
and important, but do not conform to the concept of an instant message in the sense that a user might reasonably
|
|
expect.</p>
|
|
<p>Fastenings, &xep0422;, provides a generic mechanism for a sending entity to indicate that a particular message is
|
|
associated closely to an instant message. But in doing so, this presents the problem that if many messages are not in fact
|
|
actual human messages, an archive query might end up downloading dozens or even hundreds of messages in order to
|
|
present just a handful of actual instant messages to the user. Much of the information downloaded is not required.</p>
|
|
<p>For example, to display a message, a client may need to download all the "likes" for it - whereas a simply number of
|
|
likes might be sufficient for most users' needs.</p>
|
|
<p>This specification tackles the problem by allowing these to be filtered, collated, or presented in full depending
|
|
on the needs of the client. The client now downloads just the instant messages from the archive, and any likes,
|
|
reactions, or receipts are simply summarized.</p>
|
|
<section2 topic="Terminology">
|
|
<p>Because this document defines mechanisms for dealing generically with potential types of fastenings, it does not
|
|
offer any real examples of actual fastenings that might be used.</p>
|
|
<p>Instead, example fastenings are used within an XML namespace prefixed by <tt>&nsx;</tt></p>
|
|
<p>Pseudo-fastenings are messages that are semantically equivalent to fastenings, but use a different syntax,
|
|
see <link url="#pseudo">Pseudo Fastenings</link>.</p>
|
|
<p>Nomenclature used for instant messages versus ancillary messages will need to be adjusted to make it consistent
|
|
with &xep0422; et al.</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Overview' anchor="overview">
|
|
<section2 topic="Discovering Support" anchor="feature">
|
|
<p>Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature
|
|
of <tt>&ns;</tt>.</p>
|
|
</section2>
|
|
<section2 topic="Summarizing">
|
|
<p>This specification provides for four types of summary listing.</p>
|
|
<p>The first form, "<tt>simplified</tt>", is the default, and essentially represents the status quo. MAM queries
|
|
behave as if the archive contains only traditional IM traffic. No summary is provided.</p>
|
|
<p>The second form, "<tt>full</tt>", presents every message stanza in the results, including all fastenings,
|
|
errors, and so on.</p>
|
|
<p>The third form, "<tt>collate</tt>", presents each traditional IM message, as "<tt>simplified</tt>", but within
|
|
the result includes summary information about the fastenings (and pseudo-fastenings) encountered.</p>
|
|
<p>Finally a fourth form, "<tt>fastenings</tt>", returns only the fastenings for a particular message.</p>
|
|
<p>The "collate" form is the bulk of the specification presented herein.</p>
|
|
<section3 topic="Summary Information">
|
|
<p>The <apply-to/> element of &xep0422; contains a number of fastening elements. These in turn consist of a
|
|
qualified element, with a number of attributes, and potentially some content within the element.</p>
|
|
<p>This specification refers to the qualified name (the tuple of XML namespace and local-name) as the "fastening
|
|
type" (represented as an XML element herein), and the top-level element (including attributes and their
|
|
values), as the "fastening summary".</p>
|
|
<p>For example, a hypothetical edit fastening type might be <tt><edit xmlns="&nsx;edit:0"/></tt>, and that would
|
|
be the fastening summary as well. The full fastening would include any children (text or further XML elements)
|
|
of the top-level element. But a hypothetical reaction fastening type might be
|
|
<tt><reaction xmlns="&nsx;reaction:0"/></tt>, but the fastening summary could be
|
|
<tt><reaction xmlns="&nsx;reaction:0" emoji="Ὁ"/></tt></p>
|
|
<p>The summary information against each parent message consists of, for each fastening summary:</p>
|
|
<ul>
|
|
<li>The fastening summary itself.</li>
|
|
<li>A count of the number of fastenings with this summary fastened to the parent message.</li>
|
|
<li>The full fastening for the last fastening received for the parent message.</li>
|
|
</ul>
|
|
</section3>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic="Protocol Elements">
|
|
<section2 topic="Querying">
|
|
<p>This specification adds an additional field to the form defined in &xep0313; with the field name
|
|
"<tt>{&ns;}summary</tt>". This may have only the following values (unless of course further values are advertised
|
|
by a future specification):</p>
|
|
<ul>
|
|
<li>simplified</li>
|
|
<li>full</li>
|
|
<li>collate</li>
|
|
<li>fastenings</li>
|
|
</ul>
|
|
</section2>
|
|
<section2 topic="Results">
|
|
<p>The <tt><result/></tt> element defined in &xep0313; is extended by adding zero or more additional elements with
|
|
a local name of "<tt>applied</tt>", qualified by the "<tt>&ns;</tt>" namespace.</p>
|
|
<p>Each <tt><applied/></tt> element is associated with precisely one fastening summary.</p>
|
|
<p>This element contains, as its first child element, the full fastening for the last fastening received by the
|
|
server for the parent message. This is not included for "<tt>shell</tt>" fastenings, which are untyped.</p>
|
|
<p>There is a "<tt>count</tt>" attribute, consisting of an integral count of the fastenings with the same summary
|
|
as the first child element (or the count of shell fastenings when this is not included). This count, if absent,
|
|
defaults to 1. For "<tt>shell</tt>" fastenings, the attribute "<tt>shell</tt>" is set to true (or another value
|
|
with the same semantics for an XML boolean).</p>
|
|
<p>The <tt><applied/></tt> elements are only included in the <tt><result/></tt> element when the requested
|
|
summary type is "<tt>collate</tt>".</p>
|
|
</section2>
|
|
<section2 topic="Latest Archive ID">
|
|
<p>The latest archive id can usually be deduced either from the last message stanza received (and its stanza-id,
|
|
see &xep0359;) or by the id attribute of the last <tt><result/></tt> element from a query extending to the
|
|
latest message.</p>
|
|
<p>Since this specification can cause the latest message to be only in a summarized form when presented in the
|
|
archive, it also adds an additional element to the <tt><fin/></tt> element which terminates the query, to
|
|
indicate the latest id held in the archive (which may be that of a fastening).</p>
|
|
<p>This element, qualified by the "<tt>&ns;</tt>", has the local name of "<tt>latest</tt>" and a single attribute,
|
|
"<tt>id</tt>", containing the latest archive id.</p>
|
|
</section2>
|
|
<section2 topic="Incremental queries">
|
|
<p>A MAM query where the MAM summary type is "<tt>collate</tt>", and where "<tt>start</tt>" and "<tt>end</tt>" (or
|
|
the RSM <tt><after/></tt> element) would exclude the parent message but include the fastening, then the MAM
|
|
result is sent with the <tt><forwarded/></tt> element omitted but the summary present (including all
|
|
fastenings, not just those that have changed).</p>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic="Pseudo-Fastenings" anchor="pseudo">
|
|
<p>A number of previous specifications exist that - if they were rewritten today - might use fastenings.</p>
|
|
<p>For the purposes of this specification, it is convenient to treat these as pseudo-fastenings, behaving as if they
|
|
were a fastening for the purposes of the "collate" and "fastenings" summary types.</p>
|
|
<p>This specification defines two such types. Both MUST be supported by servers:</p>
|
|
<ul>
|
|
<li>Message Delivery Receipts: &xep0184; "ack messages" - those containing a <tt><received/></tt> element - are
|
|
considered to be equivalent to a fastening containing just the <received/> element, applying to the message
|
|
given by the "<tt>id</tt>" attribute.</li>
|
|
<li>Chat Markers: &xep0333; A Chat Marker is similarly equivalent to a fastening containing the Chat Marker, but
|
|
applying to all previous messages (since previous messages can be assumed to have been read and or displayed,
|
|
etc).</li>
|
|
</ul>
|
|
<p>In both cases, the fastening summary SHOULD omit the <tt>id</tt> attribute.</p>
|
|
</section1>
|
|
|
|
<section1 topic="Examples">
|
|
<p>A firm TODO; contributions are welcome - and a good test of whether I've written the rest right!</p>
|
|
</section1>
|
|
|
|
<section1 topic="Schema">
|
|
<code>
|
|
<![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="]]>&ns;<![CDATA[" xmlns:xs="http://www.w3.org/2001/XMLSchema">
|
|
<xs:element name="applied" type="mamfc:appliedType" xmlns:mamfc="]]>&ns;<![CDATA["/>
|
|
<xs:complexType name="appliedType">
|
|
<xs:sequence>
|
|
<xs:any minOccurs="0" maxOccurs="1"/>
|
|
<!-- Fastening summary, absent when shell is true -->
|
|
</xs:sequence>
|
|
<xs:attribute type="xs:positiveInteger" name="count" default="1"/>
|
|
<xs:attribute type="xs:boolean" name="shell" default="false"/>
|
|
</xs:complexType>
|
|
<xs:element name="latest" type="mamfc:latestType" xmlns:mamfc="]]>&ns;<![CDATA["/>
|
|
<xs:complexType name="latestType">
|
|
<xs:attribute type="xs:string"/>
|
|
</xs:complexType>
|
|
</xs:schema>
|
|
]]>
|
|
</code>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>This specification imposes substantial workload for servers.</p>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This XEP requires no interaction with &IANA;. </p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<p>None.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>The authors wish to share any credit with many members of the community, including Marvin Wissfield.</p>
|
|
</section1>
|
|
|
|
</xep>
|