The long-awaited rewrite of the bounce processing system. We've

(hopefully) managed to make this both more understandable and much
simpler.  Simpler even than recent mailman-developer threads (and yet,
I still believe this will work :).  The algorithm is explained in the
Mailman/Gui/Bounce.py, i.e. admin/bounce category, help string.

Specifically here,

GetConfigInfo(): Explain the new bounce scoring algorithm, and provide
for configuration attributes bounce_processing,
bounce_score_threshold, bounce_info_stale_after,
bounce_you_are_disabled_warnings, and
bounce_you_are_disabled_warnings_interval.  Get rid of the old bounce
configuration attributes.

HandleForm(), GetValue(): Handle the setting and getting of the gui
configuration variables, specifically the conversion from
float-seconds to days.  The former type is used internally, while the
latter is presented to the user.

1 files changed, 101 insertions, 21 deletions

diff --git a/Mailman/Gui/Bounce.py b/Mailman/Gui/Bounce.py
index 3562d0ddb..72e177b26 100644
--- a/Mailman/Gui/Bounce.py
+++ b/Mailman/Gui/Bounce.py
@@ -16,6 +16,7 @@
 
 from Mailman import mm_cfg
 from Mailman.i18n import _
+from Mailman.mm_cfg import days
 
 
 
@@ -27,30 +28,109 @@ class Bounce:
         if category <> 'bounce':
             return None
         return [
-            _('''Policies regarding systematic processing of bounce messages,
-            to help automate recognition and handling of defunct
-            addresses.'''),
-            
+            _("""These policies control the automatic bounce processing system
+            in Mailman.  Here's an overview of how it works.
+
+            <p>When a bounce is received, Mailman tries to extract two pieces
+            of information from the message: the address of the member the
+            message was intended for, and the severity of the problem causing
+            the bounce.  The severity can be either <em>hard</em> or
+            <em>soft</em> meaning either a fatal error occurred, or a
+            transient error occurred.  When in doubt, a hard severity is used.
+
+            <p>If no member address can be extracted from the bounce, then the
+            bounce is usually discarded.  Otherwise, each member is assigned a
+            <em>bounce score</em> and every time we encounter a bounce from
+            this member we increment the score.  Hard bounces increment by 1
+            while soft bounces increment by 0.5.  We only increment the bounce
+            score once per day, so even if we receive ten hard bounces from a
+            member per day, their score will increase by only 1 for that day.
+
+            <p>When a member's bounce score is greater than the
+            <a href="?VARHELP=bounce/bounce_score_threshold">bounce score
+            threshold</a>, the subscription is disabled.  Once disabled, the
+            member will not receive any postings from the list until their
+            membership is explicitly re-enabled (either by the list
+            administrator or the user).  However, they will receive occasional
+            reminders that their membership has been disabled, and these
+            reminders will include information about how to re-enable their
+            membership.
+
+            <p>You can control both the
+            <a href="?VARHELP=bounce/bounce_you_are_disabled_warnings">number
+            of reminders</a> the member will receive and the
+            <a href="?VARHELP=bounce/bounce_you_are_disabled_warnings_interval"
+            >frequency</a> with which these reminders are sent.
+
+            <p>There is one other important configuration variable; after a
+            certain period of time -- during which no bounces from the member
+            are received -- the bounce information is
+            <a href="?VARHELP=bounce/bounce_info_stale_after">considered
+            stale</a> and discarded.  Thus by adjusting this value, and the
+            score threshold, you can control how quickly bouncing members are
+            disabled.  You should tune both of these to the frequency and
+            traffic volume of your list."""),
+
             ('bounce_processing', mm_cfg.Toggle, (_('No'), _('Yes')), 0,
-             _('Try to figure out error messages automatically?')),
+             _('Should Mailman perform automatic bounce processing?'),
+             _("""By setting this value to <em>No</em>, you disable all
+             automatic bounce processing for this list, however bounce
+             messages will still be discarded so that the list administrator
+             isn't inundated with them.""")),
 
-            ('minimum_removal_date', mm_cfg.Number, 3, 0,
-             _('''Minimum number of days an address has been non-fatally bad
-             before we take action''')),
+            ('bounce_score_threshold', mm_cfg.Number, 5, 0,
+             _("""The maximum member bounce score before the member's
+             subscription is disabled.  This value can be a floating point
+             number.""")),
 
-            ('minimum_post_count_before_bounce_action', mm_cfg.Number, 3, 0,
-             _('''Minimum number of posts to the list since members first
-             bounce before we consider removing them from the list''')),
+            ('bounce_info_stale_after', mm_cfg.Number, 5, 0,
+             _("""The number of days after which a member's bounce information
+             is discarded, if no new bounces have been received in the
+             interim.  This value must be an integer.""")),
 
-            ('max_posts_between_bounces', mm_cfg.Number, 3, 0,
-             _('''Maximum number of messages your list gets in an hour. (Yes,
-             bounce detection finds this info useful)''')),
+            ('bounce_you_are_disabled_warnings', mm_cfg.Number, 5, 0,
+             _("""How many <em>Your Membership Is Disabled</em> warnings a
+             disabled member should get before their address is removed from
+             the mailing list.  Set to 0 to immediately remove an address from
+             the list once their bounce score exceeds the threshold.  This
+             value must be an integer.""")),
 
-            ('automatic_bounce_action', mm_cfg.Radio,
-             (_("Do nothing"),
-              _("Disable and notify me"),
-              _("Disable and DON'T notify me"),
-              _("Remove and notify me")),
-             0,
-             _("Action when critical or excessive bounces are detected."))
+            ('bounce_you_are_disabled_warnings_interval', mm_cfg.Number, 5, 0,
+             _("""The number of days between sending the <em>Your Membership
+             Is Disabled</em> warnings.  This value must be an integer.""")),
             ]
+
+    def __convert(self, mlist, cgidata, varname, doc, func):
+        # BAW: This should really be an attribute on the doc object
+        from Mailman.Cgi.admin import add_error_message
+        def error(doc, varname, value):
+            text = _("""Bad value for <a href="?VARHELP=bounce/%(varname)s"
+            >%(varname)s</a>: %(value)s""")
+            add_error_message(doc, text, _('Error: '))
+
+        value = cgidata.getvalue(varname)
+        if value:
+            try:
+                setattr(mlist, varname, func(value))
+            except ValueError:
+                error(doc, varname, value)
+
+    def HandleForm(self, mlist, cgidata, doc):
+        def convert(varname, func, mlist=mlist, cgidata=cgidata, doc=doc):
+            self.__convert(mlist, cgidata, varname, doc, func)
+
+        def to_days(value):
+            return days(int(value))
+        # Do our own form processing so the admin.py script doesn't have to
+        # contain all the logic for converting from seconds to days.
+        convert('bounce_processing', int)
+        convert('bounce_score_threshold', float)
+        convert('bounce_info_stale_after', to_days)
+        convert('bounce_you_are_disabled_warnings', int)
+        convert('bounce_you_are_disabled_warnings_interval', to_days)
+
+    def GetValue(self, mlist, kind, varname, params):
+        if varname not in ('bounce_info_stale_after',
+                           'bounce_you_are_disabled_warnings_interval'):
+            return None
+        return int(getattr(mlist, varname) / days(1))