xeps/xep-0437.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Room Activity Indicators</title>
  <abstract>This specification describes a lightweight mechanism for activity notifications in MUCs</abstract>
  &LEGALNOTICE;
  <number>0437</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  &mwild;
  <revision>
    <version>0.2.0</version>
    <date>2020-05-05</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Assign urn:xmpp namespace instead of xmpp:prosody.im namespace (this was missed during acceptance)</remark>
  </revision>
  <revision>
    <version>0.1.0</version>
    <date>2020-05-05</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Accepted by vote of Council on 2020-04-15.</remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2020-04-13</date>
    <initials>mw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>Sometimes it is desirable for a client to indicate to a user that
activity has occurred in a MUC, without the overhead of immediately
joining every MUC that the user has an interest in.</p>

  <p>A MUC may already send out-of-band notifications to users who are not
currently joined if e.g. they are mentioned using &xep0372;. However a MUC
typically won't forward other kinds of messages unless the user is joined.</p>

  <p>This protocol describes a lightweight mechanism for the client to display
an indication to the user that there are new messages in a room since the
last time the user was joined there. This can, for example, be used to provide
a UI hint that a room the user is interested in has new unread activity.</p>
</section1>

<section1 topic='Requirements' anchor='reqs'>
  <ul>
    <li>A client must be able to receive an indication that activity has occurred in a room without joining it</li>
    <li>The protocol must scale to a large number of rooms, while remaining simple to implement on the client and server</li>
  </ul>

  <p>This protocol explicitly does not attempt to define:</p>

  <ul>
    <li>Usage with &xep0369; (MIX architecture is fundamentally different to MUC)</li>
    <li>A means for the client/server to agree on which rooms the client should be subscribed to (it is assumed the server can
        determine a suitable strategy itself, and that this strategy may be deployment-specific).</li>
  </ul>
</section1>

<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Client subscribes to activity indicators'>
    <p>To inform the MUC service that you are interested in receiving
       activity indicators, send a presence to the service including the
       &lt;rai&gt; element:</p>

      <example caption='Client subscribes to activity indicators'><![CDATA[
<presence to="conference.example.com" id="dwZ3vL">
  <rai xmlns="urn:xmpp:rai:0"/>
</presence>
]]></example>

    <p>After sending this presence, the service may send you activity
       indicator updates at any time, each one containing one or more
       JIDs of MUC rooms that have new messages:</p>

      <example caption='Server notifies client of room activity'><![CDATA[
<message from="conference.example.com">
  <rai xmlns="urn:xmpp:rai:0">
    <activity>room1@conference.example.com</activity>
    <activity>room3@conference.example.com</activity>
  </rai>
</message>
]]></example>

    <p>Note that the service will **only** send notifications for rooms
       where the client's session is not currently joined. If the client
       is joined to a room, it already receives live events from the room directly.</p>

  </section2>

  <section2 topic='Client unsubscribes from activity indicators'>
    <p>A client may unsubscribe from activity indicators by sending an unavailable presence
    to the MUC service. This will typically be sent by the user's server automatically when
    they go offline.</p>
  </section2>
</section1>

<section1 topic='Business Rules' anchor='rules'>
  <p>Upon receiving a presence stanza addressed to the service JID that includes
     a &lt;rai xmlns="urn:xmpp:rai:0"&gt; element, the service should
     build a list of rooms where activity has occurred since the client was
     last in the room, and send them in a single notification.</p>

  <p>When activity happens in a room, a service should send an activity notification
     to room members who have subscribed to notifications and who have not already
     received a notification for that room in their current subscription's lifetime.</p>

  <p>A server SHOULD only send a single notification for each room where activity
     has occured since the last time a given affiliated user was joined to a room.
     Each room may only be notified once, even if many events occur while the client
     is not present in the room. Therefore the client MUST NOT attempt to count activity
     events. A single activity notification for a room means some unspecified number
     of events have happened, receiving another activity notification for the same
     room adds no further information.</p>
  <p>A server MUST NOT send activity notifications to a user from a room that the user
     would not be allowed to join. This potentially includes hidden rooms where the user
     has no affiliation.</p>
</section1>

<section1 topic='Implementation Notes' anchor='impl'>
  <section2 topic='Determining the list of rooms'>
    <p>This specification does not dictate how a server determines which rooms a client
       should receive notifications for. The list may be large and varying.</p>
    <p>For example, this information is available to the server through some other means,
       or a server may simply subscribe a user to all rooms on the MUC service, or only to
       rooms where a user has an affiliation.</p>
  </section2>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>This specification is not expected to introduce any security concerns.</p>
  <p>From a privacy perspective, a user's availability is exposed to the MUC service, but not
     beyond what would be exposed if the user simply joined a room as normal.</p>
  <p>Servers may place restrictions on who may subscribe to room activity notifications, e.g.
     by only serving local users, or only permitting a sensible number of active subscriptions.</p>
  <p>Servers must be careful not to leak room activity indicators to users who would not otherwise
     have permission to view the content in the room.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>This document requires no interaction with &REGISTRAR;.</p>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <p>REQUIRED for protocol specifications.</p>
</section1>
</xep>