Changeset 173:6b0eb01b5744

Timestamp:

May 9, 2012, 2:24:28 PM (9 years ago)

Author:

Ralph Meijer <ralphm@…>

Branch:

default

Message:

Add support for roster versioning.

Files:

• doc/listings/xmppim/roster_client_versioning.py (added)
• doc/xmppim.rst (modified) (1 diff)
• wokkel/test/test_xmppim.py (modified) (6 diffs)
• wokkel/xmppim.py (modified) (6 diffs)

doc/xmppim.rst

@@ -32 +32 @@
    :language: python
    :linenos:
+
+Roster versioning
+^^^^^^^^^^^^^^^^^
+
+Some XMPP servers support roster versioning. A client can keep a cache of the
+roster by requesting it and applying changes as roster pushes come in. Each
+version of the roster is marked with a version identifier. This can be used
+to request the roster upon reconnect. The server can then choose to send the
+difference between the requested and current version as roster pushed,
+instead of returning the complete roster.
+
+When no roster was cached by the client, yet, a client passes the empty
+string (``''``) to ``getRoster`` to bootstrap the process.
+
+This example will force a reconnect 15 seconds after authentication.
+
+.. literalinclude:: listings/xmppim/roster_client_versioning.py
+   :language: python
+   :linenos:

wokkel/test/test_xmppim.py

@@ -838 +838 @@
         self.assertEqual(JID('this@example.org'), request.sender)
         self.assertEqual(None, request.item)
+        self.assertEqual(None, request.version)
 
 
@@ -855 +856 @@
         self.assertNotIdentical(None, request.item)
         self.assertEqual(JID('user@example.org'), request.item.entity)
+
+
+    def test_fromElementVersion(self):
+        """
+        If a ver attribute is present, put it in the request version.
+        """
+        xml = """
+            <iq type='set' to='this@example.org/Home' from='this@example.org'>
+              <query xmlns='jabber:iq:roster' ver='ver72'>
+                <item jid='user@example.org'/>
+              </query>
+            </iq>
+        """
+        request = xmppim.RosterRequest.fromElement(parseXml(xml))
+        self.assertEqual('ver72', request.version)
+
+
+    def test_fromElementVersionEmpty(self):
+        """
+        The ver attribute may be empty.
+        """
+        xml = """
+            <iq type='get' to='this@example.org/Home' from='this@example.org'>
+              <query xmlns='jabber:iq:roster' ver=''/>
+            </iq>
+        """
+        request = xmppim.RosterRequest.fromElement(parseXml(xml))
+        self.assertEqual('', request.version)
 
 
@@ -904 +933 @@
 
 
+    def test_toElementVersion(self):
+        """
+        If the roster version is set, a 'ver' attribute is added.
+        """
+        request = xmppim.RosterRequest()
+        request.version = 'ver72'
+        element = request.toElement()
+        self.assertEqual('ver72', element.query.getAttribute('ver'))
+
+
+    def test_toElementVersionEmpty(self):
+        """
+        If the roster version is the empty string, it should add 'ver', too.
+        """
+        request = xmppim.RosterRequest()
+        request.version = ''
+        element = request.toElement()
+        self.assertEqual('', element.query.getAttribute('ver'))
+
+
 
 class RosterClientProtocolTest(unittest.TestCase, TestableRequestHandlerMixin):
@@ -950 +999 @@
         def cb(roster):
             self.assertIn(JID('user@example.org'), roster)
+            self.assertIdentical(None, getattr(roster, 'version'))
 
         d = self.service.getRoster()
@@ -960 +1010 @@
         self.assertNotIdentical(None, iq.query)
         self.assertEqual(NS_ROSTER, iq.query.uri)
+        self.assertFalse(iq.query.hasAttribute('ver'))
 
         # Fake successful response
@@ -967 +1018 @@
         item['jid'] = 'user@example.org'
 
+        d.callback(response)
+        return d
+
+
+    def test_getRosterVer(self):
+        """
+        A request for the roster with version passes the version on.
+        """
+        def cb(roster):
+            self.assertEqual('ver96', getattr(roster, 'version'))
+
+        d = self.service.getRoster(version='ver72')
+        d.addCallback(cb)
+
+        # Inspect outgoing iq request
+
+        iq = self.stub.output[-1]
+        self.assertEqual('ver72', iq.query.getAttribute('ver'))
+
+        # Fake successful response
+        response = toResponse(iq, 'result')
+        query = response.addElement((NS_ROSTER, 'query'))
+        query['ver'] = 'ver96'
+        item = query.addElement('item')
+        item['jid'] = 'user@example.org'
+
+        d.callback(response)
+        return d
+
+
+    def test_getRosterVerEmptyResult(self):
+        """
+        An empty response is returned as None.
+        """
+        def cb(response):
+            self.assertIdentical(None, response)
+
+        d = self.service.getRoster(version='ver72')
+        d.addCallback(cb)
+
+        # Inspect outgoing iq request
+
+        iq = self.stub.output[-1]
+
+        # Fake successful response
+        response = toResponse(iq, 'result')
         d.callback(response)
         return d

wokkel/xmppim.py

@@ -749 +749 @@
     @ivar item: Roster item to be set or pushed.
     @type item: L{RosterItem}.
+
+    @ivar version: Roster version identifier for roster pushes and
+        retrieving the roster as a delta from a known cached version. This
+        should only be set if the recipient is known to support roster
+        versioning.
+    @type version: C{unicode}
     """
     item = None
+    version = None
 
     def parseRequest(self, element):
+        self.version = element.getAttribute('ver')
+
         for child in element.elements(NS_ROSTER, 'item'):
             self.item = RosterItem.fromElement(child)
@@ -761 +770 @@
         element = Request.toElement(self)
         query = element.addElement((NS_ROSTER, 'query'))
+        if self.version is not None:
+            query['ver'] = self.version
         if self.item:
             query.addChild(self.item.toElement())
@@ -775 +786 @@
     result in a C{'service-unavailable'} error being sent in return.
     """
+
+
+
+class Roster(dict):
+    """
+    In-memory roster container.
+
+    This provides a roster as a mapping from L{JID} to L{RosterItem}. If
+    roster versioning is used, the C{version} attribute holds the version
+    identifier for this version of the roster.
+
+    @ivar version: Roster version identifier.
+    @type version: C{unicode}.
+    """
+
+    version = None
 
 
@@ -797 +824 @@
     pushes from untrusted senders.
 
+    If roster versioning is supported by the server, the roster and
+    subsequent pushes are annotated with a version identifier. This can be
+    used to cache the roster on the client side. Upon reconnect, the client
+    can request the roster with the version identifier of the cached version.
+    The server may then choose to only send roster pushes for the changes
+    since that version, instead of a complete roster.
+
     @cvar allowAnySender: Flag to allow roster pushes from any sender.
         C{False} by default.
@@ -810 +844 @@
 
 
-    def getRoster(self):
+    def getRoster(self, version=None):
         """
         Retrieve contact list.
+
+        The returned deferred fires with the result of the roster request as
+        L{Roster}, a mapping from contact JID to L{RosterItem}.
+
+        If roster versioning is supported, the recipient responds with either
+        a the complete roster or with an empty result. In case of complete
+        roster, the L{Roster} is annotated with a C{version} attribute that
+        holds the version identifier for this version of the roster. This
+        identifier should be used for caching.
+
+        If the recipient responds with an empty result, the returned deferred
+        fires with C{None}. This indicates that any roster modifications
+        since C{version} will be sent as roster pushes.
+
+        Note that the empty result (C{None}) is different from an empty
+        roster (L{Roster} with no items).
+
+        @param version: Optional version identifier of the last cashed
+            version of the roster. This shall only be set if the recipient is
+            known to support roster versioning. If there is no (valid) cached
+            version of the roster, but roster versioning is desired,
+            C{version} should be set to the empty string (C{u''}).
+        @type version: C{unicode}
 
         @return: Roster as a mapping from L{JID} to L{RosterItem}.
@@ -819 +876 @@
 
         def processRoster(result):
-            roster = {}
-            for element in domish.generateElementsQNamed(result.query.children,
-                                                         'item', NS_ROSTER):
-                item = RosterItem.fromElement(element)
-                roster[item.entity] = item
-
-            return roster
+            if result.query is not None:
+                roster = Roster()
+                roster.version = result.query.getAttribute('ver')
+                for element in result.query.elements(NS_ROSTER, 'item'):
+                    item = RosterItem.fromElement(element)
+                    roster[item.entity] = item
+                return roster
+            else:
+                return None
 
         request = RosterRequest(stanzaType='get')
+        request.version = version
         d = self.request(request)
         d.addCallback(processRoster)