source: ralphm-patches/roster_item.patch @ 49:537d1413b661

wokkel/im.py

@@ -7 +7 @@
 XMPP IM protocol support.
 
 This module provides generic implementations for the protocols defined in
-U{RFC 3921<http://www.xmpp.org/rfcs/rfc3921.html>} (XMPP IM).
-
-All of it should eventually move to Twisted.
+U{RFC 6121<http://www.xmpp.org/rfcs/rfc6121.html>} (XMPP IM).
 """
 
+import warnings
+
+from twisted.internet import defer
 from twisted.words.protocols.jabber.jid import JID, internJID
+from twisted.words.protocols.jabber import error
 from twisted.words.xish import domish
 
 from wokkel.compat import IQ
 from wokkel.generic import ErrorStanza, Stanza
-from wokkel.subprotocols import XMPPHandler
+from wokkel.subprotocols import IQHandlerMixin, XMPPHandler
 
 NS_XML = 'http://www.w3.org/XML/1998/namespace'
 NS_ROSTER = 'jabber:iq:roster'
 
+XPATH_ROSTER_SET = "/iq[@type='set']/query[@xmlns='%s']" % NS_ROSTER
+
+
+
 class BasePresence(Stanza):
     """
     Stanza of kind presence.
@@ -349 +355 @@
 
     This represents one contact from an XMPP contact list known as roster.
 
-    @ivar jid: The JID of the contact.
-    @type jid: L{JID}
+    @ivar entity: The JID of the contact.
+    @type entity: L{JID}
     @ivar name: The optional associated nickname for this contact.
     @type name: C{unicode}
     @ivar subscriptionTo: Subscription state to contact's presence. If C{True},
@@ -360 +366 @@
     @ivar subscriptionFrom: Contact's subscription state. If C{True}, the
                             contact is subscribed to the presence information
                             of the roster owner.
-    @type subscriptionTo: C{bool}
-    @ivar ask: Whether subscription is pending.
-    @type ask: C{bool}
+    @type subscriptionFrom: C{bool}
+    @ivar pendingOut: Whether the subscription request to this contact is
+        pending.
+    @type pendingOut: C{bool}
     @ivar groups: Set of groups this contact is categorized in. Groups are
                   represented by an opaque identifier of type C{unicode}.
     @type groups: C{set}
     """
 
-    def __init__(self, jid):
-        self.jid = jid
-        self.name = None
-        self.subscriptionTo = False
-        self.subscriptionFrom = False
-        self.ask = None
-        self.groups = set()
+    __subscriptionStates = {(False, False): None,
+                            (True, False): 'to',
+                            (False, True): 'from',
+                            (True, True): 'both'}
 
+    def __init__(self, entity, subscriptionTo=False, subscriptionFrom=False,
+                       name=None, groups=None):
+        self.entity = entity
+        self.subscriptionTo = subscriptionTo
+        self.subscriptionFrom = subscriptionFrom
+        self.name = name
+        self.groups = groups or set()
 
+        self.pendingOut = False
+        self.approved = False
+        self.remove = False
 
-class RosterClientProtocol(XMPPHandler):
+
+    def __getJID(self):
+        warnings.warn("Use RosterItem.entity instead.", DeprecationWarning)
+        return self.entity
+
+
+    def __setJID(self, value):
+        warnings.warn("Use RosterItem.entity instead.", DeprecationWarning)
+        self.entity = value
+
+
+    jid = property(__getJID, __setJID, doc="""
+            JID of the contact. Deprecated in favour of C{entity}.""")
+
+
+    def __getAsk(self):
+        warnings.warn("Use RosterItem.pendingOut instead.", DeprecationWarning)
+        return self.pendingOut
+
+
+    def __setAsk(self, value):
+        warnings.warn("Use RosterItem.pendingOut instead.", DeprecationWarning)
+        self.pendingOut = value
+
+
+    ask = property(__getAsk, __setAsk, doc="""
+            Pending out subscription. Deprecated in favour of C{pendingOut}.""")
+
+
+    def toElement(self):
+        element = domish.Element((NS_ROSTER, 'item'))
+        element['jid'] = self.entity.full()
+
+        if self.remove:
+            subscription = 'remove'
+        else:
+            subscription = self.__subscriptionStates[self.subscriptionTo,
+                                                     self.subscriptionFrom]
+
+            if self.pendingOut:
+                element['ask'] = u'subscribe'
+
+            if self.name:
+                element['name'] = self.name
+
+            if self.approved:
+                element['approved'] = u'true'
+
+            if self.groups:
+                for group in self.groups:
+                    element.addElement('group', content=group)
+
+        if subscription:
+            element['subscription'] = subscription
+
+        return element
+
+
+    @classmethod
+    def fromElement(Class, element):
+        entity = internJID(element['jid'])
+        item = Class(entity)
+        subscription = element.getAttribute('subscription')
+        if subscription == 'remove':
+            item.remove = True
+        else:
+            item.name = element.getAttribute('name')
+            item.subscriptionTo = subscription in ('to', 'both')
+            item.subscriptionFrom = subscription in ('from', 'both')
+            item.pendingOut = element.getAttribute('ask') == 'subscribe'
+            item.approved = element.getAttribute('approved') in ('true', '1')
+            for subElement in domish.generateElementsQNamed(element.children,
+                                                            'group', NS_ROSTER):
+                item.groups.add(unicode(subElement))
+        return item
+
+
+
+class RosterPushIgnored(Exception):
+    """
+    Raised when this entity doesn't want to accept/trust a roster push.
+    """
+
+
+
+class RosterClientProtocol(XMPPHandler, IQHandlerMixin):
     """
     Client side XMPP roster protocol.
     """
 
+    iqHandlers = {XPATH_ROSTER_SET: "_onRosterSet"}
+
     def connectionInitialized(self):
-        ROSTER_SET = "/iq[@type='set']/query[@xmlns='%s']" % NS_ROSTER
-        self.xmlstream.addObserver(ROSTER_SET, self._onRosterSet)
-
-
-    def _parseRosterItem(self, element):
-        jid = internJID(element['jid'])
-        item = RosterItem(jid)
-        item.name = element.getAttribute('name')
-        subscription = element.getAttribute('subscription')
-        item.subscriptionTo = subscription in ('to', 'both')
-        item.subscriptionFrom = subscription in ('from', 'both')
-        item.ask = element.getAttribute('ask') == 'subscribe'
-        for subElement in domish.generateElementsQNamed(element.children,
-                                                        'group', NS_ROSTER):
-            item.groups.add(unicode(subElement))
-
-        return item
+        self.xmlstream.addObserver(XPATH_ROSTER_SET, self.handleRequest)
 
 
     def getRoster(self):
@@ -415 +500 @@
             roster = {}
             for element in domish.generateElementsQNamed(result.query.children,
                                                          'item', NS_ROSTER):
-                item = self._parseRosterItem(element)
-                roster[item.jid.userhost()] = item
+                item = RosterItem.fromElement(element)
+                roster[item.entity] = item
 
             return roster
 
@@ -437 +522 @@
         """
         iq = IQ(self.xmlstream, 'set')
         iq.addElement((NS_ROSTER, 'query'))
-        item = iq.query.addElement('item')
-        item['jid'] = entity.full()
-        item['subscription'] = 'remove'
+        item = RosterItem(entity)
+        item.remove = True
+        iq.query.addChild(item.toElement())
         return iq.send()
 
 
     def _onRosterSet(self, iq):
-        if iq.handled or \
-           iq.hasAttribute('from') and iq['from'] != self.xmlstream:
-            return
-
-        iq.handled = True
+        def eb(failure):
+            failure.trap(RosterPushIgnored)
+            raise error.StanzaError('service-unavailable')
 
         itemElement = iq.query.item
+        item = RosterItem.fromElement(iq.query.item)
 
-        if unicode(itemElement['subscription']) == 'remove':
-            self.onRosterRemove(internJID(itemElement['jid']))
+        if item.remove:
+            d = defer.maybeDeferred(self.onRosterRemove, item.entity)
         else:
-            item = self._parseRosterItem(iq.query.item)
-            self.onRosterSet(item)
+            d = defer.maybeDeferred(self.onRosterSet, item)
+
+        d.addErrback(eb)
+        return d
 
 
     def onRosterSet(self, item):
         """
         Called when a roster push for a new or update item was received.
 
+        Raise L{RosterPushIgnored} when not accepting this roster push
+        (directly or via Deferred). This will result in a
+        L{'service-unavailable'} error being sent in return.
+
         @param item: The pushed roster item.
         @type item: L{RosterItem}
         """
@@ -472 +562 @@
         """
         Called when a roster push for the removal of an item was received.
 
+        Raise L{RosterPushIgnored} when not accepting this roster push
+        (directly or via Deferred). This will result in a
+        L{'service-unavailable'} error being sent in return.
+
         @param entity: The entity for which the roster item has been removed.
         @type entity: L{JID}
         """

wokkel/test/test_im.py

@@ -7 +7 @@
 
 from twisted.internet import defer
 from twisted.trial import unittest
+from twisted.words.protocols.jabber import error
 from twisted.words.protocols.jabber.jid import JID
 from twisted.words.protocols.jabber.xmlstream import toResponse
 from twisted.words.xish import domish, utility
 
 from wokkel import im
 from wokkel.generic import ErrorStanza, parseXml
-from wokkel.test.helpers import XmlStreamStub
+from wokkel.test.helpers import TestableRequestHandlerMixin, XmlStreamStub
 
 NS_XML = 'http://www.w3.org/XML/1998/namespace'
 NS_ROSTER = 'jabber:iq:roster'
@@ -389 +390 @@
 
 
 
-class RosterClientProtocolTest(unittest.TestCase):
+class RosterItemTest(unittest.TestCase):
+    """
+    Tests for L{im.RosterItem}.
+    """
+
+    def test_jidDeprecationGet(self):
+        """
+        Getting the jid attribute works as entity and warns deprecation.
+        """
+        item = im.RosterItem(JID('user@example.org'))
+        entity = self.assertWarns(DeprecationWarning,
+                                  "Use RosterItem.entity instead.",
+                                  im.__file__,
+                                  getattr, item, 'jid')
+        self.assertIdentical(entity, item.entity)
+
+
+    def test_jidDeprecationSet(self):
+        """
+        Setting the jid attribute works as entity and warns deprecation.
+        """
+        item = im.RosterItem(JID('user@example.org'))
+        entity = self.assertWarns(DeprecationWarning,
+                                  "Use RosterItem.entity instead.",
+                                  im.__file__,
+                                  setattr, item, 'jid',
+                                  JID('other@example.org'))
+        self.assertEquals(JID('other@example.org'), item.entity)
+
+
+    def test_askDeprecationGet(self):
+        """
+        Getting the ask attribute works as entity and warns deprecation.
+        """
+        item = im.RosterItem(JID('user@example.org'))
+        item.pendingOut = True
+        ask = self.assertWarns(DeprecationWarning,
+                               "Use RosterItem.pendingOut instead.",
+                               im.__file__,
+                               getattr, item, 'ask')
+        self.assertTrue(ask)
+
+
+    def test_askDeprecationSet(self):
+        """
+        Setting the ask attribute works as entity and warns deprecation.
+        """
+        item = im.RosterItem(JID('user@example.org'))
+        entity = self.assertWarns(DeprecationWarning,
+                                  "Use RosterItem.pendingOut instead.",
+                                  im.__file__,
+                                  setattr, item, 'ask',
+                                  True)
+        self.assertTrue(item.pendingOut)
+
+
+    def test_toElement(self):
+        item = im.RosterItem(JID('user@example.org'))
+        element = item.toElement()
+        self.assertEquals('item', element.name)
+        self.assertEquals(NS_ROSTER, element.uri)
+        self.assertFalse(element.hasAttribute('subscription'))
+        self.assertFalse(element.hasAttribute('ask'))
+        self.assertFalse(element.hasAttribute('name'))
+        self.assertFalse(element.hasAttribute('approved'))
+        self.assertEquals(0, len(list(element.elements())))
+
+
+    def test_toElementMinimal(self):
+        item = im.RosterItem(JID('user@example.org'))
+        element = item.toElement()
+        self.assertEquals(u'user@example.org', element.getAttribute('jid'))
+
+
+    def test_toElementSubscriptionNone(self):
+        item = im.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=False,
+                                 subscriptionFrom=False)
+        element = item.toElement()
+        self.assertIdentical(None, element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionTo(self):
+        item = im.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=True,
+                                 subscriptionFrom=False)
+        element = item.toElement()
+        self.assertEquals('to', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionFrom(self):
+        item = im.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=False,
+                                 subscriptionFrom=True)
+        element = item.toElement()
+        self.assertEquals('from', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionBoth(self):
+        item = im.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=True,
+                                 subscriptionFrom=True)
+        element = item.toElement()
+        self.assertEquals('both', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionRemove(self):
+        item = im.RosterItem(JID('user@example.org'))
+        item.remove = True
+        element = item.toElement()
+        self.assertEquals('remove', element.getAttribute('subscription'))
+
+
+    def test_toElementAsk(self):
+        item = im.RosterItem(JID('user@example.org'))
+        item.pendingOut = True
+        element = item.toElement()
+        self.assertEquals('subscribe', element.getAttribute('ask'))
+
+
+    def test_toElementName(self):
+        item = im.RosterItem(JID('user@example.org'),
+                                 name='Joe User')
+        element = item.toElement()
+        self.assertEquals(u'Joe User', element.getAttribute('name'))
+
+
+    def test_toElementGroups(self):
+        groups = set(['Friends', 'Jabber'])
+        item = im.RosterItem(JID('user@example.org'),
+                                 groups=groups)
+
+        element = item.toElement()
+        foundGroups = set()
+        for child in element.elements():
+            if child.uri == NS_ROSTER and child.name == 'group':
+                foundGroups.add(unicode(child))
+
+        self.assertEqual(groups, foundGroups)
+
+
+    def test_toElementApproved(self):
+        """
+        A pre-approved subscription for a roster item has an 'approved' flag.
+        """
+        item = im.RosterItem(JID('user@example.org'))
+        item.approved = True
+        element = item.toElement()
+        self.assertEquals(u'true', element.getAttribute('approved'))
+
+
+    def test_fromElementMinimal(self):
+        """
+        A minimal roster item has a reference to the JID of the contact.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertEqual(JID(u"test@example.org"), item.entity)
+        self.assertIdentical(None, item.name)
+        self.assertFalse(item.subscriptionTo)
+        self.assertFalse(item.subscriptionFrom)
+        self.assertFalse(item.pendingOut)
+        self.assertFalse(item.approved)
+        self.assertEquals(set(), item.groups)
+
+
+    def test_fromElementName(self):
+        """
+        A roster item may have an optional name.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  name="Test User"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertEqual(u"Test User", item.name)
+
+
+    def test_fromElementGroups(self):
+        """
+        A roster item may have one or more groups.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org">
+              <group>Friends</group>
+              <group>Twisted</group>
+            </item>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertIn(u"Twisted", item.groups)
+        self.assertIn(u"Friends", item.groups)
+
+
+    def test_fromElementSubscriptionNone(self):
+        """
+        Subscription 'none' sets both attributes to False.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  subscription="none"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertFalse(item.remove)
+        self.assertFalse(item.subscriptionTo)
+        self.assertFalse(item.subscriptionFrom)
+
+
+    def test_fromElementSubscriptionTo(self):
+        """
+        Subscription 'to' sets the corresponding attribute to True.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  subscription="to"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertFalse(item.remove)
+        self.assertTrue(item.subscriptionTo)
+        self.assertFalse(item.subscriptionFrom)
+
+
+    def test_fromElementSubscriptionFrom(self):
+        """
+        Subscription 'from' sets the corresponding attribute to True.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  subscription="from"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertFalse(item.remove)
+        self.assertFalse(item.subscriptionTo)
+        self.assertTrue(item.subscriptionFrom)
+
+
+    def test_fromElementSubscriptionBoth(self):
+        """
+        Subscription 'both' sets both attributes to True.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  subscription="both"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertFalse(item.remove)
+        self.assertTrue(item.subscriptionTo)
+        self.assertTrue(item.subscriptionFrom)
+
+
+    def test_fromElementSubscriptionRemove(self):
+        """
+        Subscription 'remove' sets the remove attribute.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  subscription="remove"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertTrue(item.remove)
+
+
+    def test_fromElementPendingOut(self):
+        """
+        The ask attribute, if set to 'subscription', means pending out.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  ask="subscribe"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertTrue(item.pendingOut)
+
+
+    def test_fromElementApprovedTrue(self):
+        """
+        The approved attribute (true) signals a pre-approved subscription.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  approved="true"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertTrue(item.approved)
+
+
+    def test_fromElementApproved1(self):
+        """
+        The approved attribute (1) signals a pre-approved subscription.
+        """
+
+        xml = """
+            <item xmlns="jabber:iq:roster"
+                  jid="test@example.org"
+                  approved="1"/>
+        """
+
+        item = im.RosterItem.fromElement(parseXml(xml))
+        self.assertTrue(item.approved)
+
+
+
+class RosterClientProtocolTest(unittest.TestCase, TestableRequestHandlerMixin):
     """
     Tests for L{im.RosterClientProtocol}.
     """
 
     def setUp(self):
         self.stub = XmlStreamStub()
-        self.protocol = im.RosterClientProtocol()
-        self.protocol.xmlstream = self.stub.xmlstream
-        self.protocol.connectionInitialized()
+        self.service = im.RosterClientProtocol()
+        self.service.makeConnection(self.stub.xmlstream)
+        self.service.connectionInitialized()
 
 
     def test_removeItem(self):
         """
         Removing a roster item is setting an item with subscription C{remove}.
         """
-        d = self.protocol.removeItem(JID('test@example.org'))
+        d = self.service.removeItem(JID('test@example.org'))
 
         # Inspect outgoing iq request
 
@@ -419 +753 @@
         self.assertEquals(1, len(children))
         child = children[0]
         self.assertEquals('test@example.org', child['jid'])
-        self.assertEquals('remove', child['subscription'])
+        self.assertEquals('remove', child.getAttribute('subscription'))
 
         # Fake successful response
 
         response = toResponse(iq, 'result')
         self.stub.send(response)
         return d
+
+
+    def test_getRoster(self):
+        def cb(roster):
+            self.assertIn(JID('user@example.org'), roster)
+
+
+        d = self.service.getRoster()
+        d.addCallback(cb)
+
+        # Inspect outgoing iq request
+
+        iq = self.stub.output[-1]
+        self.assertEquals('get', iq.getAttribute('type'))
+        self.assertNotIdentical(None, iq.query)
+        self.assertEquals(NS_ROSTER, iq.query.uri)
+
+        # Fake successful response
+        response = toResponse(iq, 'result')
+        query = response.addElement((NS_ROSTER, 'query'))
+        item = query.addElement('item')
+        item['jid'] = 'user@example.org'
+
+        self.stub.send(response)
+        return d
+
+
+    def test_onRosterSet(self):
+        """
+        A roster push causes onRosterSet to be called with the parsed item.
+        """
+        xml = """
+          <iq type='set'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        items = []
+
+        def onRosterSet(item):
+            items.append(item)
+
+        def cb(result):
+            self.assertEquals(1, len(items))
+            self.assertEquals(JID('user@example.org'), items[0].entity)
+
+        self.service.onRosterSet = onRosterSet
+
+        d = self.handleRequest(xml)
+        d.addCallback(cb)
+        return d
+
+
+    def test_onRosterSetUntrusted(self):
+        """
+        Roster pushes from untrusted sources will be not be handled.
+        """
+        xml = """
+          <iq type='set' from='bad@example.org'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        def onRosterSet(item):
+            raise im.RosterPushIgnored()
+
+        def cb(result):
+            self.assertEquals('service-unavailable', result.condition)
+
+        self.service.onRosterSet = onRosterSet
+
+        d = self.handleRequest(xml)
+        self.assertFailure(d, error.StanzaError)
+        d.addCallback(cb)
+        return d
+
+
+    def test_onRosterRemove(self):
+        """
+        A roster push causes onRosterSet to be called with the parsed item.
+        """
+        xml = """
+          <iq type='set'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org' subscription='remove'/>
+            </query>
+          </iq>
+        """
+
+        entities = []
+
+        def onRosterRemove(entity):
+            entities.append(entity)
+
+        def cb(result):
+            self.assertEquals([JID('user@example.org')], entities)
+
+        self.service.onRosterRemove = onRosterRemove
+
+        d = self.handleRequest(xml)
+        d.addCallback(cb)
+        return d
+