diff options
Diffstat (limited to 'src/mailman/rest')
| -rw-r--r-- | src/mailman/rest/adapters.py | 12 | ||||
| -rw-r--r-- | src/mailman/rest/docs/membership.txt | 2 | ||||
| -rw-r--r-- | src/mailman/rest/docs/users.txt | 213 | ||||
| -rw-r--r-- | src/mailman/rest/root.py | 10 | ||||
| -rw-r--r-- | src/mailman/rest/users.py | 160 |
5 files changed, 389 insertions, 8 deletions
diff --git a/src/mailman/rest/adapters.py b/src/mailman/rest/adapters.py index 30ce99f44..5cbb89bc1 100644 --- a/src/mailman/rest/adapters.py +++ b/src/mailman/rest/adapters.py @@ -36,6 +36,7 @@ from mailman.interfaces.address import InvalidEmailAddressError from mailman.interfaces.listmanager import IListManager, NoSuchListError from mailman.interfaces.member import DeliveryMode from mailman.interfaces.membership import ISubscriptionService +from mailman.utilities.passwords import make_user_friendly_password @@ -84,15 +85,12 @@ class SubscriptionService: raise InvalidEmailAddressError(address) # Because we want to keep the REST API simple, there is no password or # language given to us. We'll use the system's default language for - # the user's default language. We'll set the password to None. XXX - # Is that a good idea? Maybe we should set it to something else, - # except that once we encode the password (as we must do to avoid - # cleartext passwords in the database) we'll never be able to retrieve - # it. - # + # the user's default language. We'll set the password to a system + # default. This will have to get reset since it can't be retrieved. # Note that none of these are used unless the address is completely # new to us. - return add_member(mlist, address, real_name, None, mode, + password = make_user_friendly_password() + return add_member(mlist, address, real_name, password, mode, system_preferences.preferred_language) def leave(self, fqdn_listname, address): diff --git a/src/mailman/rest/docs/membership.txt b/src/mailman/rest/docs/membership.txt index 553f6fde9..1e4e0414e 100644 --- a/src/mailman/rest/docs/membership.txt +++ b/src/mailman/rest/docs/membership.txt @@ -229,7 +229,7 @@ Elly is now a member of the mailing list. >>> elly = user_manager.get_user('eperson@example.com') >>> elly - <User "Elly Person" at ...> + <User "Elly Person" (...) at ...> >>> set(member.mailing_list for member in elly.memberships.members) set([u'alpha@example.com']) diff --git a/src/mailman/rest/docs/users.txt b/src/mailman/rest/docs/users.txt new file mode 100644 index 000000000..adca53ea3 --- /dev/null +++ b/src/mailman/rest/docs/users.txt @@ -0,0 +1,213 @@ +===== +Users +===== + +The REST API can be used to add and remove users, add and remove user +addresses, and change their preferred address, passord, or name. Users are +different than members; the latter represents an email address subscribed to a +specific mailing list. Users are just people that Mailman knows about. + +There are no users yet. + + >>> dump_json('http://localhost:9001/3.0/users') + http_etag: "..." + start: 0 + total_size: 0 + +When there are users in the database, they can be retrieved as a collection. +:: + + >>> from zope.component import getUtility + >>> from mailman.interfaces.usermanager import IUserManager + >>> user_manager = getUtility(IUserManager) + + >>> anne = user_manager.create_user('anne@example.com', 'Anne Person') + >>> transaction.commit() + >>> dump_json('http://localhost:9001/3.0/users') + entry 0: + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: None + real_name: Anne Person + user_id: 1 + http_etag: "..." + start: 0 + total_size: 1 + +The user ids match. + + >>> json = call_http('http://localhost:9001/3.0/users') + >>> json['entries'][0]['user_id'] == anne.user_id + True + + +Creating users via the API +========================== + +New users can be created through the REST API. To do so requires the initial +email address for the user, and optionally the user's full name and password. +:: + + >>> transaction.abort() + >>> dump_json('http://localhost:9001/3.0/users', { + ... 'email': 'bart@example.com', + ... 'real_name': 'Bart Person', + ... 'password': 'bbb', + ... }) + content-length: 0 + date: ... + location: http://localhost:9001/3.0/users/2 + server: ... + status: 201 + +The user exists in the database. +:: + + >>> bart = user_manager.get_user('bart@example.com') + >>> bart + <User "Bart Person" (2) at ...> + +It is also available via the location given in the response. + + >>> dump_json('http://localhost:9001/3.0/users/2') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 + +Because email addresses just have an ``@`` sign in then, there's no confusing +them with user ids. Thus, a user can be retrieved via its email address. + + >>> dump_json('http://localhost:9001/3.0/users/bart@example.com') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 + +Users can be created without a password. A *user friendly* password will be +assigned to them automatically, but this password will be encrypted and +therefore cannot be retrieved. It can be reset though. +:: + + >>> transaction.abort() + >>> dump_json('http://localhost:9001/3.0/users', { + ... 'email': 'cris@example.com', + ... 'real_name': 'Cris Person', + ... }) + content-length: 0 + date: ... + location: http://localhost:9001/3.0/users/3 + server: ... + status: 201 + + >>> dump_json('http://localhost:9001/3.0/users/3') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}... + real_name: Cris Person + user_id: 3 + + +Missing users +============= + +It is of course an error to attempt to access a non-existent user, either by +user id... +:: + + >>> dump_json('http://localhost:9001/3.0/users/99') + Traceback (most recent call last): + ... + HTTPError: HTTP Error 404: 404 Not Found + +...or by email address. +:: + + >>> dump_json('http://localhost:9001/3.0/users/zed@example.org') + Traceback (most recent call last): + ... + HTTPError: HTTP Error 404: 404 Not Found + + +User addresses +============== + +Bart may have any number of email addresses associated with their user +account. We can find out all of these through the API. The addresses are +sorted in lexical order by original (i.e. case-preserved) email address. +:: + + >>> bart.register('bperson@example.com') + <Address: bperson@example.com [not verified] at ...> + >>> bart.register('bart.person@example.com') + <Address: bart.person@example.com [not verified] at ...> + >>> bart.register('Bart.Q.Person@example.com') + <Address: Bart.Q.Person@example.com [not verified] + key: bart.q.person@example.com at ...> + >>> transaction.commit() + + >>> dump_json('http://localhost:9001/3.0/users/2/addresses') + entry 0: + email: bart.q.person@example.com + http_etag: "..." + original_email: Bart.Q.Person@example.com + real_name: + registered_on: None + verified_on: None + entry 1: + email: bart.person@example.com + http_etag: "..." + original_email: bart.person@example.com + real_name: + registered_on: None + verified_on: None + entry 2: + email: bart@example.com + http_etag: "..." + original_email: bart@example.com + real_name: Bart Person + registered_on: None + verified_on: None + entry 3: + email: bperson@example.com + http_etag: "..." + original_email: bperson@example.com + real_name: + registered_on: None + verified_on: None + http_etag: "..." + start: 0 + total_size: 4 + +In fact, any of these addresses can be used to look up Bart's user record. +:: + + >>> dump_json('http://localhost:9001/3.0/users/bart@example.com') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 + + >>> dump_json('http://localhost:9001/3.0/users/bart.person@example.com') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 + + >>> dump_json('http://localhost:9001/3.0/users/bperson@example.com') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 + + >>> dump_json('http://localhost:9001/3.0/users/Bart.Q.Person@example.com') + created_on: 2005-08-01T07:49:23 + http_etag: "..." + password: {CLEARTEXT}bbb + real_name: Bart Person + user_id: 2 diff --git a/src/mailman/rest/root.py b/src/mailman/rest/root.py index 9d8c92428..3287a6be2 100644 --- a/src/mailman/rest/root.py +++ b/src/mailman/rest/root.py @@ -34,6 +34,7 @@ from mailman.rest.domains import ADomain, AllDomains from mailman.rest.helpers import etag, path_to from mailman.rest.lists import AList, AllLists from mailman.rest.members import AllMembers +from mailman.rest.users import AUser, AllUsers @@ -108,3 +109,12 @@ class TopLevel(resource.Resource): if len(segments) == 0: return AllMembers() return http.bad_request() + + @resource.child() + def users(self, request, segments): + """/<api>/users""" + if len(segments) == 0: + return AllUsers() + else: + user_id = segments.pop(0) + return AUser(user_id), segments diff --git a/src/mailman/rest/users.py b/src/mailman/rest/users.py new file mode 100644 index 000000000..54402096f --- /dev/null +++ b/src/mailman/rest/users.py @@ -0,0 +1,160 @@ +# Copyright (C) 2011 by the Free Software Foundation, Inc. +# +# This file is part of GNU Mailman. +# +# GNU Mailman is free software: you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your option) +# any later version. +# +# GNU Mailman is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +# more details. +# +# You should have received a copy of the GNU General Public License along with +# GNU Mailman. If not, see <http://www.gnu.org/licenses/>. + +"""REST for users.""" + +from __future__ import absolute_import, unicode_literals + +__metaclass__ = type +__all__ = [ + 'AUser', + 'AllUsers', + ] + + +from operator import attrgetter +from restish import http, resource +from zope.component import getUtility + +from mailman.interfaces.address import ExistingAddressError +from mailman.interfaces.usermanager import IUserManager +from mailman.rest.helpers import CollectionMixin, etag, path_to +from mailman.rest.validator import Validator +from mailman.utilities.passwords import ( + encrypt_password, make_user_friendly_password) + + + +class _UserBase(resource.Resource, CollectionMixin): + """Shared base class for user representations.""" + + def _resource_as_dict(self, user): + """See `CollectionMixin`.""" + # The canonical URL for a user is their preferred email address, + # although we can always look up a user based on any registered and + # validated email address associated with their account. + return dict( + real_name=user.real_name, + password=user.password, + user_id=user.user_id, + created_on=user.created_on, + ) + + def _get_collection(self, request): + """See `CollectionMixin`.""" + return list(getUtility(IUserManager).users) + + + +class AllUsers(_UserBase): + """The users.""" + + @resource.GET() + def collection(self, request): + """/users""" + resource = self._make_collection(request) + return http.ok([], etag(resource)) + + @resource.POST() + def create(self, request): + """Create a new user.""" + try: + validator = Validator(email=unicode, + real_name=unicode, + password=unicode, + _optional=('real_name', 'password')) + arguments = validator(request) + except ValueError as error: + return http.bad_request([], str(error)) + # 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: + return http.bad_request([], b'Address already exists {0}'.format( + error.email)) + if password is None: + # This will have to be reset since it cannot be retrieved. + password = make_user_friendly_password() + user.password = encrypt_password(password) + location = path_to('users/{0}'.format(user.user_id)) + return http.created(location, [], None) + + + +class AUser(_UserBase): + """A user.""" + + def __init__(self, user_identifier): + """Get a user by various type of identifiers. + + :param user_identifier: The identifier used to retrieve the user. The + identifier may either be an integer user-id, or an email address + controlled by the user. The type of identifier is auto-detected + by looking for an `@` symbol, in which case it's taken as an email + address, otherwise it's assumed to be an integer. + :type user_identifier: str + """ + user_manager = getUtility(IUserManager) + if '@' in user_identifier: + self._user = user_manager.get_user(user_identifier) + else: + self._user = user_manager.get_user_by_id(user_identifier) + + @resource.GET() + def user(self, request): + """Return a single user end-point.""" + if self._user is None: + return http.not_found() + return http.ok([], self._resource_as_json(self._user)) + + @resource.child() + def addresses(self, request, segments): + """/users/<uid>/addresses""" + return _AllUserAddresses(self._user) + + + +class _AllUserAddresses(resource.Resource, CollectionMixin): + """All addresses that a user controls.""" + + def __init__(self, user): + self._user = user + super(_AllUserAddresses, self).__init__() + + def _resource_as_dict(self, address): + """See `CollectionMixin`.""" + return dict( + email=address.email, + original_email=address.original_email, + real_name=address.real_name, + registered_on=address.registered_on, + verified_on=address.verified_on, + ) + + def _get_collection(self, request): + """See `CollectionMixin`.""" + return sorted(self._user.addresses, + key=attrgetter('original_email')) + + @resource.GET() + def collection(self, request): + """/addresses""" + resource = self._make_collection(request) + return http.ok([], etag(resource)) |