6 files changed, 329 insertions, 22 deletions

diff --git a/src/mailman/docs/NEWS.rst b/src/mailman/docs/NEWS.rst
index 0a4b2fb51..daa0e8bfe 100644
--- a/src/mailman/docs/NEWS.rst
+++ b/src/mailman/docs/NEWS.rst
@@ -63,6 +63,12 @@ REST
    internal change only.
  * The JSON representation `http_etag` key uses an algorithm that is
    insensitive to Python's dictionary sort order.
+ * The address resource now has an additional '/user' sub-resource which can
+   be used to GET the address's linked user if there is one.  This
+   sub-resource also supports POST to link an unlinked address (with an
+   optional 'auto_create' flag), and PUT to link the address to a different
+   user.  It also supports DELETE to unlink the address.  (LP: #1312884)
+   Given by Aurélien Bompard based on work by nicolask.
 
 
 3.0 beta 4 -- "Time and Motion"
diff --git a/src/mailman/rest/addresses.py b/src/mailman/rest/addresses.py
index fa3d099b6..f8516bc37 100644
--- a/src/mailman/rest/addresses.py
+++ b/src/mailman/rest/addresses.py
@@ -62,6 +62,9 @@ class _AddressBase(CollectionMixin):
             representation['display_name'] = address.display_name
         if address.verified_on:
             representation['verified_on'] = address.verified_on
+        if address.user:
+            representation['user'] = path_to(
+                'users/{0}'.format(address.user.user_id.int))
         return representation
 
     def _get_collection(self, request):
@@ -156,6 +159,14 @@ class AnAddress(_AddressBase):
         child = _VerifyResource(self._address, 'unverify')
         return child, []
 
+    @child()
+    def user(self, request, segments):
+        """/addresses/<email>/user"""
+        if self._address is None:
+            return NotFound(), []
+        # Avoid circular imports.
+        from mailman.rest.users import AddressUser
+        return AddressUser(self._address)
 
 
 class UserAddresses(_AddressBase):
diff --git a/src/mailman/rest/docs/addresses.rst b/src/mailman/rest/docs/addresses.rst
index fec0c194b..8d7ca6835 100644
--- a/src/mailman/rest/docs/addresses.rst
+++ b/src/mailman/rest/docs/addresses.rst
@@ -161,6 +161,7 @@ addresses live in the /addresses namespace.
         original_email: dave@example.com
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/dave@example.com
+        user: http://localhost:9001/3.0/users/1
     http_etag: "..."
     start: 0
     total_size: 1
@@ -172,6 +173,7 @@ addresses live in the /addresses namespace.
     original_email: dave@example.com
     registered_on: 2005-08-01T07:49:23
     self_link: http://localhost:9001/3.0/addresses/dave@example.com
+    user: http://localhost:9001/3.0/users/1
 
 A user can be associated with multiple email addresses.  You can add new
 addresses to an existing user.
@@ -208,6 +210,7 @@ The user controls these new addresses.
         original_email: dave.person@example.org
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/dave.person@example.org
+        user: http://localhost:9001/3.0/users/1
     entry 1:
         display_name: Dave Person
         email: dave@example.com
@@ -215,6 +218,7 @@ The user controls these new addresses.
         original_email: dave@example.com
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/dave@example.com
+        user: http://localhost:9001/3.0/users/1
     entry 2:
         display_name: Davie P
         email: dp@example.org
@@ -222,6 +226,7 @@ The user controls these new addresses.
         original_email: dp@example.org
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/dp@example.org
+        user: http://localhost:9001/3.0/users/1
     http_etag: "..."
     start: 0
     total_size: 3
diff --git a/src/mailman/rest/docs/users.rst b/src/mailman/rest/docs/users.rst
index 04533f578..b2adcaccb 100644
--- a/src/mailman/rest/docs/users.rst
+++ b/src/mailman/rest/docs/users.rst
@@ -329,18 +329,21 @@ order by original (i.e. case-preserved) email address.
         registered_on: 2005-08-01T07:49:23
         self_link:
             http://localhost:9001/3.0/addresses/fred.q.person@example.com
+        user: http://localhost:9001/3.0/users/6
     entry 1:
         email: fperson@example.com
         http_etag: "..."
         original_email: fperson@example.com
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/fperson@example.com
+        user: http://localhost:9001/3.0/users/6
     entry 2:
         email: fred.person@example.com
         http_etag: "..."
         original_email: fred.person@example.com
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/fred.person@example.com
+        user: http://localhost:9001/3.0/users/6
     entry 3:
         display_name: Fred Person
         email: fred@example.com
@@ -348,6 +351,7 @@ order by original (i.e. case-preserved) email address.
         original_email: fred@example.com
         registered_on: 2005-08-01T07:49:23
         self_link: http://localhost:9001/3.0/addresses/fred@example.com
+        user: http://localhost:9001/3.0/users/6
     http_etag: "..."
     start: 0
     total_size: 4
diff --git a/src/mailman/rest/tests/test_addresses.py b/src/mailman/rest/tests/test_addresses.py
index f4aeb3013..bbdd7d763 100644
--- a/src/mailman/rest/tests/test_addresses.py
+++ b/src/mailman/rest/tests/test_addresses.py
@@ -206,3 +206,177 @@ class TestAddresses(unittest.TestCase):
                     'email': 'anne.person@example.org',
                     })
         self.assertEqual(cm.exception.code, 404)
+
+    def test_address_with_user(self):
+        # An address which is already linked to a user has a 'user' key in the
+        # JSON representation.
+        with transaction():
+            getUtility(IUserManager).create_user('anne@example.com')
+        json, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com')
+        self.assertEqual(headers['status'], '200')
+        self.assertEqual(json['user'], 'http://localhost:9001/3.0/users/1')
+
+    def test_address_without_user(self):
+        # The 'user' key is missing from the JSON representation of an address
+        # with no linked user.
+        with transaction():
+            getUtility(IUserManager).create_address('anne@example.com')
+        json, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com')
+        self.assertEqual(headers['status'], '200')
+        self.assertNotIn('user', json)
+
+    def test_user_subresource_on_unlinked_address(self):
+        # Trying to access the 'user' subresource on an address that is not
+        # linked to a user will return a 404 error.
+        with transaction():
+            getUtility(IUserManager).create_address('anne@example.com')
+        with self.assertRaises(HTTPError) as cm:
+            call_api(
+                'http://localhost:9001/3.0/addresses/anne@example.com/user')
+        self.assertEqual(cm.exception.code, 404)
+
+    def test_user_subresource(self):
+        # For an address which is linked to a user, accessing the user
+        # subresource of the address path returns the user JSON representation.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            user_manager.create_user('anne@example.com', 'Anne')
+        json, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user')
+        self.assertEqual(headers['status'], '200')
+        self.assertEqual(json['user_id'], 1)
+        self.assertEqual(json['display_name'], 'Anne')
+        user_resource = json['self_link']
+        self.assertEqual(user_resource, 'http://localhost:9001/3.0/users/1')
+        # The self_link points to the correct user.
+        json, headers = call_api(user_resource)
+        self.assertEqual(json['user_id'], 1)
+        self.assertEqual(json['display_name'], 'Anne')
+        self.assertEqual(json['self_link'], user_resource)
+
+    def test_user_subresource_post(self):
+        # If the address is not yet linked to a user, POSTing a user id to the
+        # 'user' subresource links the address to the given user.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            anne = user_manager.create_user('anne.person@example.org', 'Anne')
+            anne_addr = user_manager.create_address('anne@example.com')
+        response, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                'user_id': anne.user_id.int,
+                })
+        self.assertEqual(headers['status'], '200')
+        self.assertEqual(anne_addr.user, anne)
+        self.assertEqual(sorted([a.email for a in anne.addresses]),
+                         ['anne.person@example.org', 'anne@example.com'])
+
+    def test_user_subresource_post_new_user(self):
+        # If the address is not yet linked to a user, POSTing to the 'user'
+        # subresources creates a new user object and links it to the address.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            anne_addr = user_manager.create_address('anne@example.com')
+        response, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                'display_name': 'Anne',
+                })
+        self.assertEqual(headers['status'], '201')
+        anne = user_manager.get_user('anne@example.com')
+        self.assertIsNotNone(anne)
+        self.assertEqual(anne.display_name, 'Anne')
+        self.assertEqual([a.email for a in anne.addresses],
+                         ['anne@example.com'])
+        self.assertEqual(anne_addr.user, anne)
+        self.assertEqual(headers['location'],
+                         'http://localhost:9001/3.0/users/1')
+
+    def test_user_subresource_post_conflict(self):
+        # If the address is already linked to a user, trying to link it to
+        # another user produces a 409 Conflict error.
+        with transaction():
+            getUtility(IUserManager).create_user('anne@example.com')
+        with self.assertRaises(HTTPError) as cm:
+            call_api(
+                'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                    'email': 'anne.person@example.org',
+                })
+        self.assertEqual(cm.exception.code, 409)
+
+    def test_user_subresource_post_new_user_no_auto_create(self):
+        # By default, POSTing to the 'user' resource of an unlinked address
+        # will automatically create the user.  By setting a boolean
+        # 'auto_create' flag to false, you can prevent this.
+        with transaction():
+            getUtility(IUserManager).create_address('anne@example.com')
+        with self.assertRaises(HTTPError) as cm:
+            json, headers = call_api(
+                'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                    'display_name': 'Anne',
+                    'auto_create': 0,
+                })
+        self.assertEqual(cm.exception.code, 403)
+
+    def test_user_subresource_unlink(self):
+        # By DELETEing the usr subresource, you can unlink a user from an
+        # address.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            user_manager.create_user('anne@example.com')
+        response, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user',
+            method='DELETE')
+        self.assertEqual(headers['status'], '204')
+        anne_addr = user_manager.get_address('anne@example.com')
+        self.assertIsNone(anne_addr.user, 'The address is still linked')
+        self.assertIsNone(user_manager.get_user('anne@example.com'))
+
+    def test_user_subresource_unlink_unlinked(self):
+        # If you try to unlink an unlinked address, you get a 404 error.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            user_manager.create_address('anne@example.com')
+        with self.assertRaises(HTTPError) as cm:
+            response, headers = call_api(
+                'http://localhost:9001/3.0/addresses/anne@example.com/user',
+                method='DELETE')
+        self.assertEqual(cm.exception.code, 404)
+
+    def test_user_subresource_put(self):
+        # By PUTing to the 'user' resource, you can change the user that an
+        # address is linked to.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            anne = user_manager.create_user('anne@example.com', 'Anne')
+            bart = user_manager.create_user(display_name='Bart')
+        response, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                'user_id': bart.user_id.int,
+                }, method='PUT')
+        self.assertEqual(headers['status'], '200')
+        self.assertEqual(anne.addresses, [])
+        self.assertEqual([address.email for address in bart.addresses],
+                         ['anne@example.com'])
+        self.assertEqual(bart,
+                         user_manager.get_address('anne@example.com').user)
+
+    def test_user_subresource_put_create(self):
+        # PUTing to the 'user' resource creates the user, just like with POST.
+        user_manager = getUtility(IUserManager)
+        with transaction():
+            anne = user_manager.create_user('anne@example.com', 'Anne')
+        response, headers = call_api(
+            'http://localhost:9001/3.0/addresses/anne@example.com/user', {
+                'email': 'anne.person@example.org',
+                }, method='PUT')
+        self.assertEqual(headers['status'], '201')
+        self.assertEqual(anne.addresses, [])
+        anne_person = user_manager.get_user('anne.person@example.org')
+        self.assertIsNotNone(anne_person)
+        self.assertEqual(
+            sorted([address.email for address in anne_person.addresses]),
+            ['anne.person@example.org', 'anne@example.com'])
+        anne_addr = user_manager.get_address('anne@example.com')
+        self.assertIsNotNone(anne_addr)
+        self.assertEqual(anne_addr.user, anne_person)
diff --git a/src/mailman/rest/users.py b/src/mailman/rest/users.py
index cfea36cfa..7ab1d6818 100644
--- a/src/mailman/rest/users.py
+++ b/src/mailman/rest/users.py
@@ -27,6 +27,7 @@ __all__ = [
     ]
 
 
+from lazr.config import as_boolean
 from passlib.utils import generate_password as generate
 from uuid import UUID
 from zope.component import getUtility
@@ -39,7 +40,8 @@ from mailman.interfaces.usermanager import IUserManager
 from mailman.rest.addresses import UserAddresses
 from mailman.rest.helpers import (
     BadRequest, CollectionMixin, GetterSetter, NotFound, bad_request, child,
-    created, etag, forbidden, no_content, not_found, okay, paginate, path_to)
+    conflict, created, etag, forbidden, no_content, not_found, okay, paginate,
+    path_to)
 from mailman.rest.preferences import Preferences
 from mailman.rest.validator import PatchValidator, Validator
 
@@ -63,6 +65,35 @@ ATTRIBUTES = dict(
     )
 
 
+CREATION_FIELDS = dict(
+    email=unicode,
+    display_name=unicode,
+    password=unicode,
+    _optional=('display_name', 'password'),
+    )
+
+
+def create_user(arguments, response):
+    """Create a new user."""
+    # We can't pass the 'password' argument to the user creation method, so
+    # strip that out (if it exists), then create the user, adding the password
+    # after the fact if successful.
+    password = arguments.pop('password', None)
+    try:
+        user = getUtility(IUserManager).create_user(**arguments)
+    except ExistingAddressError as error:
+        bad_request(
+            response, b'Address already exists: {}'.format(error.address))
+        return None
+    if password is None:
+        # This will have to be reset since it cannot be retrieved.
+        password = generate(int(config.passwords.password_length))
+    user.password = config.password_context.encrypt(password)
+    location = path_to('users/{}'.format(user.user_id.int))
+    created(response, location)
+    return user
+
+
 
 class _UserBase(CollectionMixin):
     """Shared base class for user representations."""
@@ -77,7 +108,7 @@ class _UserBase(CollectionMixin):
         resource = dict(
             user_id=user_id,
             created_on=user.created_on,
-            self_link=path_to('users/{0}'.format(user_id)),
+            self_link=path_to('users/{}'.format(user_id)),
             )
         # Add the password attribute, only if the user has a password.  Same
         # with the real name.  These could be None or the empty string.
@@ -105,30 +136,12 @@ class AllUsers(_UserBase):
     def on_post(self, request, response):
         """Create a new user."""
         try:
-            validator = Validator(email=unicode,
-                                  display_name=unicode,
-                                  password=unicode,
-                                  _optional=('display_name', 'password'))
+            validator = Validator(**CREATION_FIELDS)
             arguments = validator(request)
         except ValueError as error:
             bad_request(response, str(error))
             return
-        # We can't pass the 'password' argument to the user creation method,
-        # so strip that out (if it exists), then create the user, adding the
-        # password after the fact if successful.
-        password = arguments.pop('password', None)
-        try:
-            user = getUtility(IUserManager).create_user(**arguments)
-        except ExistingAddressError as error:
-            bad_request(
-                response, b'Address already exists: {0}'.format(error.address))
-            return
-        if password is None:
-            # This will have to be reset since it cannot be retrieved.
-            password = generate(int(config.passwords.password_length))
-        user.password = config.password_context.encrypt(password)
-        location = path_to('users/{0}'.format(user.user_id.int))
-        created(response, location)
+        create_user(arguments, response)
 
 
 
@@ -242,6 +255,100 @@ class AUser(_UserBase):
 
 
 
+class AddressUser(_UserBase):
+    """The user linked to an address."""
+
+    def __init__(self, address):
+        self._address = address
+        self._user = address.user
+
+    def on_get(self, request, response):
+        """Return a single user end-point."""
+        if self._user is None:
+            not_found(response)
+        else:
+            okay(response, self._resource_as_json(self._user))
+
+    def on_delete(self, request, response):
+        """Delete the named user, all her memberships, and addresses."""
+        if self._user is None:
+            not_found(response)
+            return
+        self._user.unlink(self._address)
+        no_content(response)
+
+    def on_post(self, request, response):
+        """Link a user to the address, and create it if needed."""
+        if self._user:
+            conflict(response)
+            return
+        # When creating a linked user by POSTing, the user either must already
+        # exist, or it can be automatically created, if the auto_create flag
+        # is given and true (if missing, it defaults to true).  However, in
+        # this case we do not accept 'email' as a POST field.
+        fields = CREATION_FIELDS.copy()
+        del fields['email']
+        fields['user_id'] = int
+        fields['auto_create'] = as_boolean
+        fields['_optional'] = fields['_optional'] + ('user_id', 'auto_create')
+        try:
+            validator = Validator(**fields)
+            arguments = validator(request)
+        except ValueError as error:
+            bad_request(response, str(error))
+            return
+        user_manager = getUtility(IUserManager)
+        if 'user_id' in arguments:
+            raw_uid = arguments['user_id']
+            user_id = UUID(int=raw_uid)
+            user = user_manager.get_user_by_id(user_id)
+            if user is None:
+                not_found(response, b'No user with ID {}'.format(raw_uid))
+                return
+            okay(response)
+        else:
+            auto_create = arguments.pop('auto_create', True)
+            if auto_create:
+                # This sets the 201 or 400 status.
+                user = create_user(arguments, response)
+                if user is None:
+                    return
+            else:
+                forbidden(response)
+                return
+        user.link(self._address)
+
+    def on_put(self, request, response):
+        """Set or replace the addresses's user."""
+        if self._user:
+            self._user.unlink(self._address)
+        # Process post data and check for an existing user.
+        fields = CREATION_FIELDS.copy()
+        fields['user_id'] = int
+        fields['_optional'] = fields['_optional'] + ('user_id', 'email')
+        try:
+            validator = Validator(**fields)
+            arguments = validator(request)
+        except ValueError as error:
+            bad_request(response, str(error))
+            return
+        user_manager = getUtility(IUserManager)
+        if 'user_id' in arguments:
+            raw_uid = arguments['user_id']
+            user_id = UUID(int=raw_uid)
+            user = user_manager.get_user_by_id(user_id)
+            if user is None:
+                not_found(response, b'No user with ID {}'.format(raw_uid))
+                return
+            okay(response)
+        else:
+            user = create_user(arguments, response)
+            if user is None:
+                return
+        user.link(self._address)
+
+
+
 class Login:
     """<api>/users/<uid>/login"""