1 files changed, 164 insertions, 2 deletions

diff --git a/src/mailman/interfaces/subscriptions.py b/src/mailman/interfaces/subscriptions.py
index 382a23ac0..e707cf706 100644
--- a/src/mailman/interfaces/subscriptions.py
+++ b/src/mailman/interfaces/subscriptions.py
@@ -15,7 +15,7 @@
 # You should have received a copy of the GNU General Public License along with
 # GNU Mailman.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Membership interface for REST."""
+"""Subscription management."""
 
 from collections import namedtuple
 from enum import Enum
@@ -78,8 +78,35 @@ class TokenOwner(Enum):
 
 
 @public
+class SubscriptionConfirmationNeededEvent:
+    """Triggered when a subscription needs confirmation.
+
+    Addresses must be verified before they can receive messages or post
+    to mailing list.  The confirmation message is sent to the user when
+    this event is triggered.
+    """
+    def __init__(self, mlist, token, email):
+        self.mlist = mlist
+        self.token = token
+        self.email = email
+
+
+@public
+class UnsubscriptionConfirmationNeededEvent:
+    """Triggered when an unsubscription request needs confirmation.
+
+    The confirmation message is sent to the user when this event is
+    triggered.
+    """
+    def __init__(self, mlist, token, email):
+        self.mlist = mlist
+        self.token = token
+        self.email = email
+
+
+@public
 class ISubscriptionService(Interface):
-    """General Subscription services."""
+    """General subscription services."""
 
     def get_members():
         """Return a sequence of all members of all mailing lists.
@@ -178,3 +205,138 @@ class ISubscriptionService(Interface):
         :rtype: 2-tuple of (set-of-strings, set-of-strings)
         :raises NoSuchListError: if the named mailing list does not exist.
         """
+
+
+@public
+class ISubscriptionManager(Interface):
+    """Handling subscription and unsubscription of addresses and users.
+
+    This is a higher level interface to user registration and
+    unregistration, email address confirmation, etc. than the
+    `IUserManager`.  The latter does no validation, syntax checking, or
+    confirmation, while this interface does.
+
+    To use this, adapt an ``IMailingList`` to this interface.
+    """
+    def register(subscriber=None, *,
+                 pre_verified=False, pre_confirmed=False, pre_approved=False):
+        """Subscribe an address or user according to subscription policies.
+
+        The mailing list's subscription policy is used to subscribe
+        `subscriber` to the given mailing list.  The subscriber can be
+        an ``IUser``, in which case the user must have a preferred
+        address, and that preferred address will be subscribed.  The
+        subscriber can also be an ``IAddress``, in which case the
+        address will be subscribed.
+
+        The workflow may pause (i.e. be serialized, saved, and
+        suspended) when some out-of-band confirmation step is required.
+        For example, if the user must confirm, or the moderator must
+        approve the subscription.  Use the ``confirm(token)`` method to
+        resume the workflow.
+
+        :param subscriber: The user or address to subscribe.
+        :type email: ``IUser`` or ``IAddress``
+        :param pre_verified: A flag indicating whether the subscriber's email
+            address should be considered pre-verified.  Normally a never
+            before seen email address must be verified by mail-back
+            confirmation.  Setting this flag to True automatically verifies
+            such addresses without the mail-back.  (A confirmation message may
+            still be sent under other conditions.)
+        :type pre_verified: bool
+        :param pre_confirmed: A flag indicating whether, when required by the
+            subscription policy, a subscription request should be considered
+            pre-confirmed.  Normally in such cases, a mail-back confirmation
+            message is sent to the subscriber, which must be positively
+            acknowledged by some manner.  Setting this flag to True
+            automatically confirms the subscription request.  (A confirmation
+            message may still be sent under other conditions.)
+        :type pre_confirmed: bool
+        :param pre_approved: A flag indicating whether, when required by the
+            subscription policy, a subscription request should be considered
+            pre-approved.  Normally in such cases, the list administrator is
+            notified that an approval is necessary, which must be positively
+            acknowledged in some manner.  Setting this flag to True
+            automatically approves the subscription request.
+        :type pre_approved: bool
+        :return: A 3-tuple is returned where the first element is the token
+            hash, the second element is a ``TokenOwner`, and the third element
+            is the subscribed member.  If the subscriber got subscribed
+            immediately, the token will be None and the member will be
+            an ``IMember``.  If the subscription got held, the token
+            will be a hash and the member will be None.
+        :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
+        :raises MembershipIsBannedError: when the address being subscribed
+            appears in the global or list-centric bans.
+        """
+
+    def unregister(subscriber=None, *,
+                   pre_confirmed=False, pre_approved=False):
+        """Unsubscribe an address or user according to subscription policies.
+
+        The mailing list's unsubscription policy is used to unsubscribe
+        `subscriber` from the given mailing list.  The subscriber can be
+        an ``IUser`` or an ``IAddress``, and must already be subscribed to the
+        mailing list.
+
+        The workflow may pause (i.e. be serialized, saved, and
+        suspended) when some out-of-band confirmation step is required.
+        For example, if the user must confirm, or the moderator must
+        approve the unsubscription.  Use the ``confirm(token)`` method to
+        resume the workflow.
+
+        :param subscriber: The user or address to unsubscribe.
+        :type email: ``IUser`` or ``IAddress``
+        :param pre_confirmed: A flag indicating whether, when required by the
+            unsubscription policy, an unsubscription request should be
+            considered pre-confirmed.  Normally in such cases, a mail-back
+            confirmation message is sent to the subscriber, which must be
+            positively acknowledged by some manner.  Setting this flag to True
+            automatically confirms the unsubscription request.  (A confirmation
+            message may still be sent under other conditions.)
+        :type pre_confirmed: bool
+        :param pre_approved: A flag indicating whether, when required by the
+            unsubscription policy, an unsubscription request should be
+            considered pre-approved.  Normally in such cases, the list
+            administrator is notified that an approval is necessary, which
+            must be positively acknowledged in some manner.  Setting this flag
+            to True automatically approves the unsubscription request.
+        :type pre_approved: bool
+        :return: A 3-tuple is returned where the first element is the token
+            hash, the second element is a ``TokenOwner`, and the third element
+            is the unsubscribing member.  If the subscriber got unsubscribed
+            immediately, the token will be None and the member will be
+            an ``IMember``.  If the unsubscription got held, the token
+            will be a hash and the member will be None.
+        :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
+        """
+
+    def confirm(token):
+        """Continue any paused workflow.
+
+        Confirmation may occur after the user confirms their
+        subscription request, or their email address must be verified,
+        or the moderator must approve the subscription request.
+
+        :param token: A token matching a workflow.
+        :type token: string
+        :return: A 3-tuple is returned where the first element is the token
+            hash, the second element is a ``TokenOwner`, and the third element
+            is the subscribed member.  If the subscriber got subscribed
+            immediately, the token will be None and the member will be
+            an ``IMember``.  If the subscription is still being held, the token
+            will be a hash and the member will be None.
+        :rtype: (str-or-None, ``TokenOwner``, ``IMember``-or-None)
+        :raises LookupError: when no workflow is associated with the token.
+        """
+
+    def discard(token):
+        """Discard the workflow matched to the given `token`.
+
+        :param token: A token matching a pending event with a type of
+            'registration'.
+        :raises LookupError: when no workflow is associated with the token.
+        """
+
+    def evict():
+        """Evict all saved workflows which have expired."""