XMPP Component Protocol

Information about the protocol for the OLPC-specific XMPP server component.

See also the current protocol

Data Acquisition

Currently buddy properties and activity properties and are implemented using PEP nodes. It's intended that the buddy properties continue using PEP nodes, and that activity properties are changed to be propagated within a MUC using a simple MUC <presence> based protocol.

This server component shall appear as a JID which can be found using service discovery, which when subscribed to, will subscribe to your presence (and hence PEP notifications), and therefore be privy to your buddy properties and make them available for others to search and be notified of changes. If this is undesirable for privacy reasons, the component JID should simply be removed from the roster.

The component JID can also be invited into activities in order to be made aware of the activity's existence, properties and current membership (by observing the <presence> stanzas of the MUC members). This information is then made available for others to search and be notified of changes.

Laptops still receive information about their buddies' current activity (FIXME: maybe?) and properties directly from them using PEP notifications.

Protocol Overview

Laptops query the server component about activities and buddies. For both kinds of query, there is at most one result set active at any given time. Result sets are managed using the Result Set Management (RSM) XMPP extension, as described in XEP-0059.

The component sends notifications to clients based on their currently visible result sets.

Activity Protocol

Namespace: http://laptop.org/xmpp/activity

Query

Return all activities matching the properties given.

Example: XO searches for all instances of the "Connect" activity.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity>
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
     </activity>
   </query>
 </iq>

Example: XO searches for an activity by muc jid.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity room="abcde123@conference.example.org" />
   </query>
 </iq>

Example: XO can search for a union of activities matching different search criteria (to be subscribed to changes of multiple activities)

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity>
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
     </activity>
     <activity room="abcde123@conference.example.org" />
   </query>
 </iq>

Search results contain information about the matching activities, including their properties and their current members.

Example: component replies to query:

 <iq type="result" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity room="connect4@conference.jabber.laptop.org">
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
       <buddy jid="alice@jabber.laptop.org" />
       <buddy jid="bob@jabber.laptop.org" />
       ...
     </activity>
     <activity room="abcde123@conference.example.org">
       <properties xmlns="...">
         ...
       </properties>
       ...
     </activity>
     ...
   </query>
 </iq>

Any buddies who are known by the component, and not currently visible in the XO's buddy result set, will have their properties included in full.

Example: component replies to query with supplemental buddy information.

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <activity room="...">
       <properties xmlns="...">
         <property type="str" name="type">org.laptop.Connect</property>
       </properties>
       <buddy jid="alice@jabber.laptop.org" />
       <buddy jid="bob@jabber.laptop.org">
         <properties xmlns="...">
           <property type="str" name="color">#005FE4,#00A0FF</property>
           ...
         </properties>
       </buddy>
       ...
     </activity>
     ...
   </query>
 </iq>

Change announcement

Example: component notifies client about change in activity properties:

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <change xmlns="...">
     <properties xmlns="..." activity="abcde123">
       <property type="str" name="tags">news, france</property>
     </properties>
   </change>
 </message>

Join announcement

Component tells XO that somebody has joined an activity.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <joined jid="bob@jabber.laptop.org" />
   </activity>
 </message>

Departure announcement

Component tells XO that someone has departed an actvitiy.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <left jid="bob@jabber.laptop.org" />
   </activity>
 </message>

Closed

Component tells XO that all participants have departed an activity.

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <activity xmlns="..." activity="abcde123"">
     <closed/>
   </activity>
 </message>

Share

To share an activity, one of its participant have to invite the indexer following the same protocol as when inviting a buddy

 <message
   from='joe@jabber.laptop.org'
   to='index.jabber.laptop.org'>
   <properties xmlns='http://laptop.org/xmpp/activity-properties'
     activity='abcde123'
     room='abcde123@conference.jabber.laptop.org'>
     <property type='str' name='type'>org.laptop.Connect</property>
     <property type='str' name='name'>Connect Activity</property>
     <property type='str' name='tags'/>
     <property type='str' name='color'>#0d1c38,#49bce4</property>
   </properties>
 </message>

 <message
   to='abcde123@conference.jabber.laptop.org'>
   <x xmlns="http://jabber.org/protocol/muc#user">
     <invite to="index.jabber.laptop.org"/>
   </x>
 </message>

 <message type='normal'
   from='abcde123@conference.jabber.laptop.org'
   to='indexer.jabber.laptop.org'>
   <x xmlns='http://jabber.org/protocol/muc#user'>
     <invite from='joe@jabber.laptop.org'>
       <reason/>
     </invite>
   </x>
   <x xmlns='jabber:x:conference'
     jid='abcde123@conference.jabber.laptop.org'/>
 </message>

Buddy Protocol

Namespace: http://laptop.org/xmpp/buddy

Query

Fetch information about buddies. Similar to activity querying.

By JID:

 <iq type="get" from="joe@jabber.laptop.org" to="index.jabber.laptop.org">
   <query xmlns="...">
     <buddy jid="bob@jabber.laptop.org" />
   </query>
 </iq>

Changed

 <message type="notice" from="index.jabber.laptop.org" to="joe@jabber.laptop.org">
   <change xmlns="..." jid="bob@jabber.laptop.org">
     <properties xmlns="...">
       <property type="str" name="color">#005FE4,#00A0FF</property>
     </properties>
   </change>
 </message>

Unresolved issues and TODO

• Do we need to continue to expose activity ID's to the network?
• Activity properties protocol. Why should we use muc <presence>? The current <message> based protocol could do the job
• Are we still using PEP for buddy activities? I'd say yes because if not we can't know when a friend create/join an activity
• Buddy current activity. We still use PEP (as for Buddy properties) so our friend know when we switch activity. Composant should also notify us when a buddy in our current search frame change his current activity.
• Are we still using PEP for activity properties? If not, we'll have to search for activities each time a friend create/join an activity to fetch its properties before be able to display it in the GUI. That implies more D-Bus and networks round-trips. Basically we are always interested about friends activities so PS will have to manually handle them to be sure they are always in our "activity search frame" to be sure to receive activity properties change notification.
• If we keep PEP for buddy-properties/buddy-current-activity/buddy-activities/activity-properties maybe it would be worth for the component to use PEP notification protocol for it's own notify changes. So we won't have to manage 2 type of notifications in Gabble ?

• Design buddy/activity search TP API