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, buddies activities and current activity continue using PEP nodes. Activity properties are changed to drop PEP and just use the current <message> based protocol inside the muc.

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?
  • RM: Don't know; what are the pros and cons? I'd like it if we could dissociate the JID from any magical meaning conferred by the PS, so you can turn a normal MUC room on an arbitrary server into an activity by interacting with the indexer. Also, if rooms span servers, the local part of the room name is no longer unique.

• 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
  • RM: Yes, either this or for current activity.

• Buddy current activity. We still use PEP (as for Buddy properties) so our friend know when we switch activity. Component should also notify us when a buddy in our current search frame change his current activity.
  • RM: Can we check where in the UI that current activity is used versus just knowing which buddy is in which activity? Daf seemed to think it wasn't really used. I'd like the indexer to not get involved with this ideally. The impression I got from Eben was that the point of the mesh view was more about showing you activities rather than buddies. So it's more important to just show activities with the relevant people around them, rather than one-activity-per-buddy.

• 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 notifications.
  • RM: No, I'd rather do this by making the indexer push the relevant information to us somehow. I don't want to have to publish activity properties redundantly in PEP any more, and publishing activity data per buddy is wrong. A better alternative should be sought... I'd like to know what the intention of the friends view is - do we want to show activities floating around buddies, or is there some way to see "the" activity per buddy? Also, when you search for buddies, do we need to care about showing activities at all?

• 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 ?
  • RM: Seems a little odd to me, they're coming from a different JID, and we're in some cases "patching" an existing XML result node (activity properties/joined/left don't replace the entire <activity> node and nor should they).

• What about buddy search using not OLPC specific keys (alias, name, mail, ...)? Could be cool to have a UserSearch interface but maybe not very convenient to have to deal with 2 search API's
  • RM: I spoke to Eben about this... currently the UI doesn't have a lot in the way of other search keys anyway. If the OLPC UI adds more user info then we can add them to the OLPC properties. The benefit of storing this information in the OLPC component is that we can place a clear privacy policy on it - if you subscribe to the indexer, people can search whatever info is in the OLPC properties. Arguably we could also just use XEP-0154: User Profile and make the indexer spy on/seach those, but it seems to just make life more complicated at the moment. I don't think we want to try and use two search APIs on the server though, because then we get into awkward "unioning" of search results.

• Design buddy/activity search TP API
• We need a way to specify the matching type (substring, equality, case insensitive?) in the <property> things we specify in a search request.
• We need a way to remove the indexer from the room when the activity goes private. Or should it just leave when it sees the private flag?