XMPP Component Protocol

From OLPC
Jump to navigation Jump to search

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='activity-id'
     room='myroom@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='myroom@conference.jabber.laptop.org'>
   <x xmlns="http://jabber.org/protocol/muc#user">
     <invite to="index.jabber.laptop.org"/>
   </x>
 </message>
 <message type='normal'
   from='myroom@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='myroom@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?
  • Design buddy/activity search TP API
  • Activity properties protocol