Changeset 172:ea2774e1c71c for wokkel

Timestamp:

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

Author:

Ralph Meijer <ralphm@…>

Branch:

default

Message:

Clean up of RosterItem? and RosterClientProtocol?.

RosterItem:

• Renamed attributes jid and ask to entity and pendingOut respectively.
• Can represent roster items to be removed or that have been removed.
• Now has fromElement and toElement methods.

RosterRequest is a new class to represent roster request stanzas.

RosterClientProtocol:

• Roster returned from getRoster is now indexed by JIDs (instead of the unicode representation of the JID).
• Outgoing requests are now done using RosterRequest.
• onRosterSet and onRosterRemove are deprecated in favor of setReceived and removeReceived, respectively. These are called with a RosterRequest to have access to addressing and roster version information.

RosterPushIgnored can be raised to return a service-unavailable stanza
error for unwanted pushes.

This also fixes a problem with checking the sender address for roster pushes.

Author: ralphm.
Fixes: #71.

Location:

wokkel

Files:

• test/test_xmppim.py (modified) (5 diffs)
• xmppim.py (modified) (5 diffs)

wokkel/test/test_xmppim.py

@@ -8 +8 @@
 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
@@ -14 +15 @@
 from wokkel import xmppim
 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'
@@ -450 +451 @@
 
 
-class RosterClientProtocolTest(unittest.TestCase):
+class RosterItemTest(unittest.TestCase):
+    """
+    Tests for L{xmppim.RosterItem}.
+    """
+
+    def test_toElement(self):
+        """
+        A roster item has the correct namespace/name, lacks unset attributes.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        element = item.toElement()
+        self.assertEqual('item', element.name)
+        self.assertEqual(NS_ROSTER, element.uri)
+        self.assertFalse(element.hasAttribute('subscription'))
+        self.assertFalse(element.hasAttribute('ask'))
+        self.assertEqual(u"", element.getAttribute('name', u""))
+        self.assertFalse(element.hasAttribute('approved'))
+        self.assertEquals(0, len(list(element.elements())))
+
+
+    def test_toElementMinimal(self):
+        """
+        A bare roster item only has a jid attribute.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        element = item.toElement()
+        self.assertEqual(u'user@example.org', element.getAttribute('jid'))
+
+
+    def test_toElementSubscriptionNone(self):
+        """
+        A roster item with no subscription has no subscription attribute.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=False,
+                                 subscriptionFrom=False)
+        element = item.toElement()
+        self.assertIdentical(None, element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionTo(self):
+        """
+        A roster item with subscriptionTo set has subscription 'to'.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=True,
+                                 subscriptionFrom=False)
+        element = item.toElement()
+        self.assertEqual('to', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionFrom(self):
+        """
+        A roster item with subscriptionFrom set has subscription 'to'.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=False,
+                                 subscriptionFrom=True)
+        element = item.toElement()
+        self.assertEqual('from', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionBoth(self):
+        """
+        A roster item with mutual subscription has subscription 'both'.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'),
+                                 subscriptionTo=True,
+                                 subscriptionFrom=True)
+        element = item.toElement()
+        self.assertEqual('both', element.getAttribute('subscription'))
+
+
+    def test_toElementSubscriptionRemove(self):
+        """
+        A roster item with remove set has subscription 'remove'.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        item.remove = True
+        element = item.toElement()
+        self.assertEqual('remove', element.getAttribute('subscription'))
+
+
+    def test_toElementAsk(self):
+        """
+        A roster item with pendingOut set has subscription 'ask'.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        item.pendingOut = True
+        element = item.toElement()
+        self.assertEqual('subscribe', element.getAttribute('ask'))
+
+
+    def test_toElementName(self):
+        """
+        A roster item's name is rendered to the 'name' attribute.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'),
+                                 name='Joe User')
+        element = item.toElement()
+        self.assertEqual(u'Joe User', element.getAttribute('name'))
+
+
+    def test_toElementGroups(self):
+        """
+        A roster item's groups are rendered as 'group' child elements.
+        """
+        groups = set(['Friends', 'Jabber'])
+        item = xmppim.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 = xmppim.RosterItem(JID('user@example.org'))
+        item.approved = True
+        element = item.toElement()
+        self.assertEqual(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 = xmppim.RosterItem.fromElement(parseXml(xml))
+        self.assertEqual(JID(u"test@example.org"), item.entity)
+        self.assertEqual(u"", item.name)
+        self.assertFalse(item.subscriptionTo)
+        self.assertFalse(item.subscriptionFrom)
+        self.assertFalse(item.pendingOut)
+        self.assertFalse(item.approved)
+        self.assertEqual(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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.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 = xmppim.RosterItem.fromElement(parseXml(xml))
+        self.assertTrue(item.approved)
+
+
+    def test_jidDeprecationGet(self):
+        """
+        Getting the jid attribute works as entity and warns deprecation.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        entity = self.assertWarns(DeprecationWarning,
+                                  "wokkel.xmppim.RosterItem.jid is deprecated. "
+                                  "Use RosterItem.entity instead.",
+                                  xmppim.__file__,
+                                  getattr, item, 'jid')
+        self.assertIdentical(entity, item.entity)
+
+
+    def test_jidDeprecationSet(self):
+        """
+        Setting the jid attribute works as entity and warns deprecation.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        self.assertWarns(DeprecationWarning,
+                         "wokkel.xmppim.RosterItem.jid is deprecated. "
+                         "Use RosterItem.entity instead.",
+                         xmppim.__file__,
+                         setattr, item, 'jid',
+                         JID('other@example.org'))
+        self.assertEqual(JID('other@example.org'), item.entity)
+
+
+    def test_askDeprecationGet(self):
+        """
+        Getting the ask attribute works as entity and warns deprecation.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        item.pendingOut = True
+        ask = self.assertWarns(DeprecationWarning,
+                               "wokkel.xmppim.RosterItem.ask is deprecated. "
+                               "Use RosterItem.pendingOut instead.",
+                               xmppim.__file__,
+                               getattr, item, 'ask')
+        self.assertTrue(ask)
+
+
+    def test_askDeprecationSet(self):
+        """
+        Setting the ask attribute works as entity and warns deprecation.
+        """
+        item = xmppim.RosterItem(JID('user@example.org'))
+        self.assertWarns(DeprecationWarning,
+                         "wokkel.xmppim.RosterItem.ask is deprecated. "
+                         "Use RosterItem.pendingOut instead.",
+                         xmppim.__file__,
+                         setattr, item, 'ask',
+                         True)
+        self.assertTrue(item.pendingOut)
+
+
+
+class RosterRequestTest(unittest.TestCase):
+    """
+    Tests for L{xmppim.RosterRequest}.
+    """
+
+    def test_fromElement(self):
+        """
+        A bare roster request is parsed and missing information is None.
+        """
+        xml = """
+            <iq type='get' to='this@example.org/Home' from='this@example.org'>
+              <query xmlns='jabber:iq:roster'/>
+            </iq>
+        """
+
+        request = xmppim.RosterRequest.fromElement(parseXml(xml))
+        self.assertEqual('get', request.stanzaType)
+        self.assertEqual(JID('this@example.org/Home'), request.recipient)
+        self.assertEqual(JID('this@example.org'), request.sender)
+        self.assertEqual(None, request.item)
+
+
+    def test_fromElementItem(self):
+        """
+        If an item is present, parse it and put it in the request item.
+        """
+        xml = """
+            <iq type='set' to='this@example.org/Home' from='this@example.org'>
+              <query xmlns='jabber:iq:roster'>
+                <item jid='user@example.org'/>
+              </query>
+            </iq>
+        """
+
+        request = xmppim.RosterRequest.fromElement(parseXml(xml))
+        self.assertNotIdentical(None, request.item)
+        self.assertEqual(JID('user@example.org'), request.item.entity)
+
+
+    def test_toElement(self):
+        """
+        A roster request has a query element in the roster namespace.
+        """
+        request = xmppim.RosterRequest()
+        element = request.toElement()
+        children = element.elements()
+        child = children.next()
+        self.assertEqual(NS_ROSTER, child.uri)
+        self.assertEqual('query', child.name)
+
+
+    def test_toElementItem(self):
+        """
+        If an item is set, it is rendered as a child of the query.
+        """
+        request = xmppim.RosterRequest()
+        request.item = xmppim.RosterItem(JID('user@example.org'))
+        element = request.toElement()
+        children = element.query.elements()
+        child = children.next()
+        self.assertEqual(NS_ROSTER, child.uri)
+        self.assertEqual('item', child.name)
+
+
+
+class FakeClient(object):
+    """
+    Fake client stream manager for roster tests.
+    """
+
+    def __init__(self, xmlstream, jid):
+        self.xmlstream = xmlstream
+        self.jid = jid
+
+
+    def request(self, request):
+        element = request.toElement()
+        self.xmlstream.send(element)
+        return defer.Deferred()
+
+
+    def addHandler(self, handler):
+        handler.makeConnection(self.xmlstream)
+        handler.connectionInitialized()
+
+
+
+class RosterClientProtocolTest(unittest.TestCase, TestableRequestHandlerMixin):
     """
     Tests for L{xmppim.RosterClientProtocol}.
@@ -457 +912 @@
     def setUp(self):
         self.stub = XmlStreamStub()
-        self.protocol = xmppim.RosterClientProtocol()
-        self.protocol.xmlstream = self.stub.xmlstream
-        self.protocol.connectionInitialized()
+        self.client = FakeClient(self.stub.xmlstream, JID('this@example.org'))
+        self.service = xmppim.RosterClientProtocol()
+        self.service.setHandlerParent(self.client)
 
 
@@ -466 +921 @@
         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
 
         iq = self.stub.output[-1]
-        self.assertEquals('set', iq.getAttribute('type'))
+        self.assertEqual('set', iq.getAttribute('type'))
         self.assertNotIdentical(None, iq.query)
-        self.assertEquals(NS_ROSTER, iq.query.uri)
+        self.assertEqual(NS_ROSTER, iq.query.uri)
 
         children = list(domish.generateElementsQNamed(iq.query.children,
                                                       'item', NS_ROSTER))
-        self.assertEquals(1, len(children))
+        self.assertEqual(1, len(children))
         child = children[0]
-        self.assertEquals('test@example.org', child['jid'])
-        self.assertEquals('remove', child['subscription'])
+        self.assertEqual('test@example.org', child['jid'])
+        self.assertEqual('remove', child.getAttribute('subscription'))
 
         # Fake successful response
 
         response = toResponse(iq, 'result')
-        self.stub.send(response)
-        return d
+        d.callback(response)
+        return d
+
+
+    def test_getRoster(self):
+        """
+        A request for the roster is sent out and the response is parsed.
+        """
+        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.assertEqual('get', iq.getAttribute('type'))
+        self.assertNotIdentical(None, iq.query)
+        self.assertEqual(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'
+
+        d.callback(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.assertEqual(1, len(items))
+            self.assertEqual(JID('user@example.org'), items[0].entity)
+
+        self.service.onRosterSet = onRosterSet
+
+        d = self.assertWarns(DeprecationWarning,
+                             "wokkel.xmppim.RosterClientProtocol.onRosterSet "
+                             "is deprecated. "
+                             "Use RosterClientProtocol.setReceived instead.",
+                             xmppim.__file__,
+                             self.handleRequest, xml)
+        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.assertEqual([JID('user@example.org')], entities)
+
+        self.service.onRosterRemove = onRosterRemove
+
+        d = self.assertWarns(DeprecationWarning,
+                             "wokkel.xmppim.RosterClientProtocol.onRosterRemove "
+                             "is deprecated. "
+                             "Use RosterClientProtocol.removeReceived instead.",
+                             xmppim.__file__,
+                             self.handleRequest, xml)
+        d.addCallback(cb)
+        return d
+
+
+    def test_setReceived(self):
+        """
+        A roster set push causes setReceived.
+        """
+        xml = """
+          <iq type='set'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        requests = []
+
+        def setReceived(request):
+            requests.append(request)
+
+        def cb(result):
+            self.assertEqual(1, len(requests), "setReceived was not called")
+            self.assertEqual(JID('user@example.org'), requests[0].item.entity)
+
+        self.service.setReceived = setReceived
+
+        d = self.handleRequest(xml)
+        d.addCallback(cb)
+        return d
+
+
+    def test_setReceivedOtherSource(self):
+        """
+        Roster pushes can be sent from other entities, too, ignore them.
+        """
+        xml = """
+          <iq type='set' to='this@example.org/Home' from='other@example.org'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        def cb(result):
+            self.assertEquals('service-unavailable', result.condition)
+
+        d = self.handleRequest(xml)
+        self.assertFailure(d, error.StanzaError)
+        d.addCallback(cb)
+        return d
+
+
+    def test_setReceivedOtherSourceAllowed(self):
+        """
+        Roster pushes can be sent from other entities, allow them.
+        """
+        xml = """
+          <iq type='set' to='this@example.org/Home' from='other@example.org'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        self.service.allowAnySender = True
+        requests = []
+
+        def setReceived(request):
+            requests.append(request)
+
+        def cb(result):
+            self.assertEqual(1, len(requests), "setReceived was not called")
+
+        self.service.setReceived = setReceived
+
+        d = self.handleRequest(xml)
+        d.addCallback(cb)
+        return d
+
+
+    def test_setReceivedOtherSourceIgnored(self):
+        """
+        Roster pushes can be sent from other entities, allow them.
+        """
+        xml = """
+          <iq type='set' to='this@example.org/Home' from='bad@example.org'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org'/>
+            </query>
+          </iq>
+        """
+
+        self.service.allowAnySender = True
+
+        def setReceived(request):
+            if request.sender == JID('bad@example.org'):
+                raise xmppim.RosterPushIgnored()
+
+        def cb(result):
+            self.assertEquals('service-unavailable', result.condition)
+
+        self.service.setReceived = setReceived
+
+
+        d = self.handleRequest(xml)
+        self.assertFailure(d, error.StanzaError)
+        d.addCallback(cb)
+        return d
+
+
+    def test_removeReceived(self):
+        """
+        A roster remove push causes removeReceived.
+        """
+        xml = """
+          <iq type='set'>
+            <query xmlns='jabber:iq:roster'>
+              <item jid='user@example.org' subscription='remove'/>
+            </query>
+          </iq>
+        """
+
+        requests = []
+
+        def removeReceived(request):
+            requests.append(request)
+
+        def cb(result):
+            self.assertEqual(1, len(requests), "removeReceived was not called")
+            self.assertEqual(JID('user@example.org'), requests[0].item.entity)
+
+        self.service.removeReceived = removeReceived
+
+        d = self.handleRequest(xml)
+        d.addCallback(cb)
+        return d

wokkel/xmppim.py

@@ -8 +8 @@
 
 This module provides generic implementations for the protocols defined in
-U{RFC 3921<http://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 import error
 from twisted.words.protocols.jabber.jid import JID
 from twisted.words.xish import domish
 
-from wokkel.compat import IQ
-from wokkel.generic import ErrorStanza, Stanza
+from wokkel.generic import ErrorStanza, Stanza, Request
+from wokkel.subprotocols import IQHandlerMixin
 from wokkel.subprotocols import 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 Presence(domish.Element):
@@ -606 +612 @@
     This represents one contact from an XMPP contact list known as roster.
 
-    @ivar jid: The JID of the contact.
-    @type jid: L{JID}
-    @ivar name: The optional associated nickname for this contact.
+    @ivar entity: The JID of the contact.
+    @type entity: L{JID}
+    @ivar name: The associated nickname for this contact.
     @type name: C{unicode}
     @ivar subscriptionTo: Subscription state to contact's presence. If C{True},
@@ -617 +623 @@
                             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()
-
-
-class RosterClientProtocol(XMPPHandler):
+    @ivar approved: Signals pre-approved subscription.
+    @type approved: C{bool}
+    @ivar remove: Signals roster item removal.
+    @type remove: C{bool}
+    """
+
+    __subscriptionStates = {(False, False): None,
+                            (True, False): 'to',
+                            (False, True): 'from',
+                            (True, True): 'both'}
+
+    def __init__(self, entity, subscriptionTo=False, subscriptionFrom=False,
+                       name=u'', 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
+
+
+    def __getJID(self):
+        warnings.warn(
+            "wokkel.xmppim.RosterItem.jid is deprecated. "
+            "Use RosterItem.entity instead.",
+            DeprecationWarning)
+        return self.entity
+
+
+    def __setJID(self, value):
+        warnings.warn(
+            "wokkel.xmppim.RosterItem.jid is deprecated. "
+            "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(
+            "wokkel.xmppim.RosterItem.ask is deprecated. "
+            "Use RosterItem.pendingOut instead.",
+            DeprecationWarning)
+        return self.pendingOut
+
+
+    def __setAsk(self, value):
+        warnings.warn(
+            "wokkel.xmppim.RosterItem.ask is deprecated. "
+            "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 = JID(element['jid'])
+        item = Class(entity)
+        subscription = element.getAttribute('subscription')
+        if subscription == 'remove':
+            item.remove = True
+        else:
+            item.name = element.getAttribute('name', u'')
+            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 RosterRequest(Request):
+    """
+    Roster request.
+
+    @ivar item: Roster item to be set or pushed.
+    @type item: L{RosterItem}.
+    """
+    item = None
+
+    def parseRequest(self, element):
+        for child in element.elements(NS_ROSTER, 'item'):
+            self.item = RosterItem.fromElement(child)
+            break
+
+
+    def toElement(self):
+        element = Request.toElement(self)
+        query = element.addElement((NS_ROSTER, 'query'))
+        if self.item:
+            query.addChild(self.item.toElement())
+        return element
+
+
+
+class RosterPushIgnored(Exception):
+    """
+    Raised when this entity doesn't want to accept/trust a roster push.
+
+    To avert presence leaks, a handler can raise L{RosterPushIgnored} when
+    not accepting a roster push (directly or via Deferred). This will
+    result in a C{'service-unavailable'} error being sent in return.
+    """
+
+
+
+class RosterClientProtocol(XMPPHandler, IQHandlerMixin):
     """
     Client side XMPP roster protocol.
-    """
+
+    The roster can be retrieved using L{getRoster}. Subsequent changes to the
+    roster will be pushed, resulting in calls to L{setReceived} or
+    L{removeReceived}. These methods should be overridden to handle the
+    roster pushes.
+
+    RFC 6121 specifically allows entities other than a user's server to
+    hold a roster for that user. However, how a client should deal with
+    that is currently not yet specfied.
+
+    By default roster pushes from other source. I.e. when C{request.sender}
+    is set but the sender's bare JID is different from the user's bare JID.
+    Set L{allowAnySender} to allow roster pushes from any sender. To
+    avert presence leaks, L{RosterPushIgnored} should then be raised for
+    pushes from untrusted senders.
+
+    @cvar allowAnySender: Flag to allow roster pushes from any sender.
+        C{False} by default.
+    @type allowAnySender: C{boolean}
+    """
+
+    allowAnySender = False
+    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 = JID(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):
@@ -669 +822 @@
             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
 
-        iq = IQ(self.xmlstream, 'get')
-        iq.addElement((NS_ROSTER, 'query'))
-        d = iq.send()
+        request = RosterRequest(stanzaType='get')
+        d = self.request(request)
         d.addCallback(processRoster)
         return d
@@ -689 +841 @@
         @rtype: L{twisted.internet.defer.Deferred}
         """
-        iq = IQ(self.xmlstream, 'set')
-        iq.addElement((NS_ROSTER, 'query'))
-        item = iq.query.addElement('item')
-        item['jid'] = entity.full()
-        item['subscription'] = 'remove'
-        return iq.send()
+        request = RosterRequest(stanzaType='set')
+        request.item = RosterItem(entity)
+        request.item.remove = True
+        return self.request(request)
 
 
     def _onRosterSet(self, iq):
-        if iq.handled or \
-           iq.hasAttribute('from') and iq['from'] != self.xmlstream:
-            return
-
-        iq.handled = True
-
-        itemElement = iq.query.item
-
-        if unicode(itemElement['subscription']) == 'remove':
-            self.onRosterRemove(JID(itemElement['jid']))
+        def trapIgnored(failure):
+            failure.trap(RosterPushIgnored)
+            raise error.StanzaError('service-unavailable')
+
+        request = RosterRequest.fromElement(iq)
+
+        if (not self.allowAnySender and
+                request.sender and
+                request.sender.userhostJID() !=
+                self.parent.jid.userhostJID()):
+            d = defer.fail(RosterPushIgnored())
+        elif request.item.remove:
+            d = defer.maybeDeferred(self.removeReceived, request)
         else:
-            item = self._parseRosterItem(iq.query.item)
-            self.onRosterSet(item)
-
-    def onRosterSet(self, item):
+            d = defer.maybeDeferred(self.setReceived, request)
+        d.addErrback(trapIgnored)
+        return d
+
+
+    def setReceived(self, request):
         """
         Called when a roster push for a new or update item was received.
 
-        @param item: The pushed roster item.
-        @type item: L{RosterItem}
-        """
-
-    def onRosterRemove(self, entity):
+        @param request: The push request.
+        @type request: L{RosterRequest}
+        """
+        if hasattr(self, 'onRosterSet'):
+            warnings.warn(
+                "wokkel.xmppim.RosterClientProtocol.onRosterSet "
+                "is deprecated. "
+                "Use RosterClientProtocol.setReceived instead.",
+                DeprecationWarning)
+            return defer.maybeDeferred(self.onRosterSet, request.item)
+
+
+    def removeReceived(self, request):
         """
         Called when a roster push for the removal of an item was received.
 
-        @param entity: The entity for which the roster item has been removed.
-        @type entity: L{JID}
-        """
+        @param request: The push request.
+        @type request: L{RosterRequest}
+        """
+        if hasattr(self, 'onRosterRemove'):
+            warnings.warn(
+                "wokkel.xmppim.RosterClientProtocol.onRosterRemove "
+                "is deprecated. "
+                "Use RosterClientProtocol.removeReceived instead.",
+                DeprecationWarning)
+            return defer.maybeDeferred(self.onRosterRemove,
+                                       request.item.entity)