Trunk merge

3 files changed, 195 insertions, 28 deletions

diff --git a/src/mailman/rest/docs/addresses.rst b/src/mailman/rest/docs/addresses.rst
index fd3520be9..f70b64a39 100644
--- a/src/mailman/rest/docs/addresses.rst
+++ b/src/mailman/rest/docs/addresses.rst
@@ -190,6 +190,7 @@ representation:
     created_on: 2005-08-01T07:49:23
     display_name: Cris X. Person
     http_etag: "..."
+    is_server_owner: False
     password: ...
     self_link: http://localhost:9001/3.0/users/1
     user_id: 1
diff --git a/src/mailman/rest/docs/domains.rst b/src/mailman/rest/docs/domains.rst
index a78dacd85..34e3b9a18 100644
--- a/src/mailman/rest/docs/domains.rst
+++ b/src/mailman/rest/docs/domains.rst
@@ -28,15 +28,12 @@ Once a domain is added, it is accessible through the API.
 
     >>> domain_manager.add(
     ...     'example.com', 'An example domain', 'http://lists.example.com')
-    <Domain example.com, An example domain,
-            base_url: http://lists.example.com,
-            contact_address: postmaster@example.com>
+    <Domain example.com, An example domain, base_url: http://lists.example.com>
     >>> transaction.commit()
 
     >>> dump_json('http://localhost:9001/3.0/domains')
     entry 0:
         base_url: http://lists.example.com
-        contact_address: postmaster@example.com
         description: An example domain
         http_etag: "..."
         mail_host: example.com
@@ -51,24 +48,18 @@ At the top level, all domains are returned as separate entries.
 
     >>> domain_manager.add(
     ...     'example.org',
-    ...     base_url='http://mail.example.org',
-    ...     contact_address='listmaster@example.org')
-    <Domain example.org, base_url: http://mail.example.org,
-            contact_address: listmaster@example.org>
+    ...     base_url='http://mail.example.org')
+    <Domain example.org, base_url: http://mail.example.org>
     >>> domain_manager.add(
     ...     'lists.example.net',
     ...     'Porkmasters',
-    ...     'http://example.net',
-    ...     'porkmaster@example.net')
-    <Domain lists.example.net, Porkmasters,
-            base_url: http://example.net,
-            contact_address: porkmaster@example.net>
+    ...     'http://example.net')
+    <Domain lists.example.net, Porkmasters, base_url: http://example.net>
     >>> transaction.commit()
 
     >>> dump_json('http://localhost:9001/3.0/domains')
     entry 0:
         base_url: http://lists.example.com
-        contact_address: postmaster@example.com
         description: An example domain
         http_etag: "..."
         mail_host: example.com
@@ -76,7 +67,6 @@ At the top level, all domains are returned as separate entries.
         url_host: lists.example.com
     entry 1:
         base_url: http://mail.example.org
-        contact_address: listmaster@example.org
         description: None
         http_etag: "..."
         mail_host: example.org
@@ -84,7 +74,6 @@ At the top level, all domains are returned as separate entries.
         url_host: mail.example.org
     entry 2:
         base_url: http://example.net
-        contact_address: porkmaster@example.net
         description: Porkmasters
         http_etag: "..."
         mail_host: lists.example.net
@@ -103,7 +92,6 @@ The information for a single domain is available by following one of the
 
     >>> dump_json('http://localhost:9001/3.0/domains/lists.example.net')
     base_url: http://example.net
-    contact_address: porkmaster@example.net
     description: Porkmasters
     http_etag: "..."
     mail_host: lists.example.net
@@ -165,7 +153,6 @@ Now the web service knows about our new domain.
 
     >>> dump_json('http://localhost:9001/3.0/domains/lists.example.com')
     base_url: http://lists.example.com
-    contact_address: postmaster@lists.example.com
     description: None
     http_etag: "..."
     mail_host: lists.example.com
@@ -176,9 +163,7 @@ And the new domain is in our database.
 ::
 
     >>> domain_manager['lists.example.com']
-    <Domain lists.example.com,
-            base_url: http://lists.example.com,
-            contact_address: postmaster@lists.example.com>
+    <Domain lists.example.com, base_url: http://lists.example.com>
 
     # Unlock the database.
     >>> transaction.abort()
@@ -190,8 +175,7 @@ address.
     >>> dump_json('http://localhost:9001/3.0/domains', {
     ...           'mail_host': 'my.example.com',
     ...           'description': 'My new domain',
-    ...           'base_url': 'http://allmy.example.com',
-    ...           'contact_address': 'helpme@example.com'
+    ...           'base_url': 'http://allmy.example.com'
     ...           })
     content-length: 0
     date: ...
@@ -200,7 +184,6 @@ address.
 
     >>> dump_json('http://localhost:9001/3.0/domains/my.example.com')
     base_url: http://allmy.example.com
-    contact_address: helpme@example.com
     description: My new domain
     http_etag: "..."
     mail_host: my.example.com
@@ -208,9 +191,7 @@ address.
     url_host: allmy.example.com
 
     >>> domain_manager['my.example.com']
-    <Domain my.example.com, My new domain,
-            base_url: http://allmy.example.com,
-            contact_address: helpme@example.com>
+    <Domain my.example.com, My new domain, base_url: http://allmy.example.com>
 
     # Unlock the database.
     >>> transaction.abort()
@@ -229,4 +210,92 @@ Domains can also be deleted via the API.
     status: 204
 
 
+Domain owners
+=============
+
+Domains can have owners.  By posting some addresses to the owners resource,
+you can add some domain owners.  Currently our domain has no owners:
+
+    >>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
+    http_etag: ...
+    start: 0
+    total_size: 0
+
+Anne and Bart volunteer to be a domain owners.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners', (
+    ...     ('owner', 'anne@example.com'), ('owner', 'bart@example.com')
+    ...     ))
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+    >>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
+    entry 0:
+        created_on: 2005-08-01T07:49:23
+        http_etag: ...
+        is_server_owner: False
+        self_link: http://localhost:9001/3.0/users/1
+        user_id: 1
+    entry 1:
+        created_on: 2005-08-01T07:49:23
+        http_etag: ...
+        is_server_owner: False
+        self_link: http://localhost:9001/3.0/users/2
+        user_id: 2
+    http_etag: ...
+    start: 0
+    total_size: 2
+
+We can delete all the domain owners.
+
+    >>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners',
+    ...           method='DELETE')
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+Now there are no owners.
+
+    >>> dump_json('http://localhost:9001/3.0/domains/my.example.com/owners')
+    http_etag: ...
+    start: 0
+    total_size: 0
+
+New domains can be created with owners.
+
+    >>> dump_json('http://localhost:9001/3.0/domains', (
+    ...           ('mail_host', 'your.example.com'),
+    ...           ('owner', 'anne@example.com'),
+    ...           ('owner', 'bart@example.com'),
+    ...           ))
+    content-length: 0
+    date: ...
+    location: http://localhost:9001/3.0/domains/your.example.com
+    server: ...
+    status: 201
+
+The new domain has the expected owners.
+
+    >>> dump_json('http://localhost:9001/3.0/domains/your.example.com/owners')
+    entry 0:
+        created_on: 2005-08-01T07:49:23
+        http_etag: ...
+        is_server_owner: False
+        self_link: http://localhost:9001/3.0/users/1
+        user_id: 1
+    entry 1:
+        created_on: 2005-08-01T07:49:23
+        http_etag: ...
+        is_server_owner: False
+        self_link: http://localhost:9001/3.0/users/2
+        user_id: 2
+    http_etag: ...
+    start: 0
+    total_size: 2
+
+
 .. _Domains: ../../model/docs/domains.html
diff --git a/src/mailman/rest/docs/users.rst b/src/mailman/rest/docs/users.rst
index 824492333..13390a00f 100644
--- a/src/mailman/rest/docs/users.rst
+++ b/src/mailman/rest/docs/users.rst
@@ -34,6 +34,7 @@ Anne's user record is returned as an entry into the collection of all users.
         created_on: 2005-08-01T07:49:23
         display_name: Anne Person
         http_etag: "..."
+        is_server_owner: False
         self_link: http://localhost:9001/3.0/users/1
         user_id: 1
     http_etag: "..."
@@ -50,11 +51,13 @@ returned in the REST API.
         created_on: 2005-08-01T07:49:23
         display_name: Anne Person
         http_etag: "..."
+        is_server_owner: False
         self_link: http://localhost:9001/3.0/users/1
         user_id: 1
     entry 1:
         created_on: 2005-08-01T07:49:23
         http_etag: "..."
+        is_server_owner: False
         self_link: http://localhost:9001/3.0/users/2
         user_id: 2
     http_etag: "..."
@@ -76,6 +79,7 @@ page.
         created_on: 2005-08-01T07:49:23
         display_name: Anne Person
         http_etag: "..."
+        is_server_owner: False
         self_link: http://localhost:9001/3.0/users/1
         user_id: 1
     http_etag: "..."
@@ -86,6 +90,7 @@ page.
     entry 0:
         created_on: 2005-08-01T07:49:23
         http_etag: "..."
+        is_server_owner: False
         self_link: http://localhost:9001/3.0/users/2
         user_id: 2
     http_etag: "..."
@@ -120,6 +125,7 @@ one was assigned to her.
     >>> dump_json('http://localhost:9001/3.0/users/3')
     created_on: 2005-08-01T07:49:23
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}...
     self_link: http://localhost:9001/3.0/users/3
     user_id: 3
@@ -131,6 +137,7 @@ address.
     >>> dump_json('http://localhost:9001/3.0/users/cris@example.com')
     created_on: 2005-08-01T07:49:23
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}...
     self_link: http://localhost:9001/3.0/users/3
     user_id: 3
@@ -158,6 +165,7 @@ Dave's user record includes his display name.
     created_on: 2005-08-01T07:49:23
     display_name: Dave Person
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}...
     self_link: http://localhost:9001/3.0/users/4
     user_id: 4
@@ -190,6 +198,7 @@ because it has the hash algorithm prefix (i.e. the *{plaintext}* marker).
     created_on: 2005-08-01T07:49:23
     display_name: Elly Person
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}supersekrit
     self_link: http://localhost:9001/3.0/users/5
     user_id: 5
@@ -214,6 +223,7 @@ Dave's display name has been updated.
     created_on: 2005-08-01T07:49:23
     display_name: David Person
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}...
     self_link: http://localhost:9001/3.0/users/4
     user_id: 4
@@ -238,6 +248,7 @@ addition of the algorithm prefix.
     created_on: 2005-08-01T07:49:23
     display_name: David Person
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}clockwork angels
     self_link: http://localhost:9001/3.0/users/4
     user_id: 4
@@ -246,8 +257,9 @@ You can change both the display name and the password by PUTing the full
 resource.
 
     >>> dump_json('http://localhost:9001/3.0/users/4', {
-    ...           'display_name': 'David Personhood',
     ...           'cleartext_password': 'the garden',
+    ...           'display_name': 'David Personhood',
+    ...           'is_server_owner': False,
     ...           }, method='PUT')
     content-length: 0
     date: ...
@@ -260,6 +272,7 @@ Dave's user record has been updated.
     created_on: 2005-08-01T07:49:23
     display_name: David Personhood
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}the garden
     self_link: http://localhost:9001/3.0/users/4
     user_id: 4
@@ -343,6 +356,7 @@ addresses can be used to look up Fred's user record.
     created_on: 2005-08-01T07:49:23
     display_name: Fred Person
     http_etag: "..."
+    is_server_owner: False
     self_link: http://localhost:9001/3.0/users/6
     user_id: 6
 
@@ -350,6 +364,7 @@ addresses can be used to look up Fred's user record.
     created_on: 2005-08-01T07:49:23
     display_name: Fred Person
     http_etag: "..."
+    is_server_owner: False
     self_link: http://localhost:9001/3.0/users/6
     user_id: 6
 
@@ -357,6 +372,7 @@ addresses can be used to look up Fred's user record.
     created_on: 2005-08-01T07:49:23
     display_name: Fred Person
     http_etag: "..."
+    is_server_owner: False
     self_link: http://localhost:9001/3.0/users/6
     user_id: 6
 
@@ -364,6 +380,7 @@ addresses can be used to look up Fred's user record.
     created_on: 2005-08-01T07:49:23
     display_name: Fred Person
     http_etag: "..."
+    is_server_owner: False
     self_link: http://localhost:9001/3.0/users/6
     user_id: 6
 
@@ -382,6 +399,7 @@ password is hashed and getting her user record returns the hashed password.
     created_on: 2005-08-01T07:49:23
     display_name: Elly Person
     http_etag: "..."
+    is_server_owner: False
     password: {plaintext}supersekrit
     self_link: http://localhost:9001/3.0/users/5
     user_id: 5
@@ -399,3 +417,82 @@ This time, Elly successfully logs into Mailman.
     date: ...
     server: ...
     status: 204
+
+
+Server owners
+=============
+
+Users can be designated as server owners.  Elly is not currently a server
+owner.
+
+    >>> dump_json('http://localhost:9001/3.0/users/5')
+    created_on: 2005-08-01T07:49:23
+    display_name: Elly Person
+    http_etag: "..."
+    is_server_owner: False
+    password: {plaintext}supersekrit
+    self_link: http://localhost:9001/3.0/users/5
+    user_id: 5
+
+Let's make her a server owner.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/users/5', {
+    ...           'is_server_owner': True,
+    ...           }, method='PATCH')
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+    >>> dump_json('http://localhost:9001/3.0/users/5')
+    created_on: 2005-08-01T07:49:23
+    display_name: Elly Person
+    http_etag: "..."
+    is_server_owner: True
+    password: {plaintext}supersekrit
+    self_link: http://localhost:9001/3.0/users/5
+    user_id: 5
+
+Elly later retires as server owner.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/users/5', {
+    ...           'is_server_owner': False,
+    ...           }, method='PATCH')
+    content-length: 0
+    date: ...
+    server: ...
+    status: 204
+
+    >>> dump_json('http://localhost:9001/3.0/users/5')
+    created_on: 2005-08-01T07:49:23
+    display_name: Elly Person
+    http_etag: "..."
+    is_server_owner: False
+    password: {plaintext}...
+    self_link: http://localhost:9001/3.0/users/5
+    user_id: 5
+
+Gwen, a new users, takes over as a server owner.
+::
+
+    >>> dump_json('http://localhost:9001/3.0/users', {
+    ...           'display_name': 'Gwen Person',
+    ...           'email': 'gwen@example.com',
+    ...           'is_server_owner': True,
+    ...           })
+    content-length: 0
+    date: ...
+    location: http://localhost:9001/3.0/users/7
+    server: ...
+    status: 201
+
+    >>> dump_json('http://localhost:9001/3.0/users/7')
+    created_on: 2005-08-01T07:49:23
+    display_name: Gwen Person
+    http_etag: "..."
+    is_server_owner: True
+    password: {plaintext}...
+    self_link: http://localhost:9001/3.0/users/7
+    user_id: 7