← Back to branch summary

~barry/mailman/events-and-web

« back to all changes in this revision

Viewing changes to Mailman/rules/docs/header-matching.txt

  • Committer: Barry Warsaw
  • Date: 2008-02-03 04:03:19 UTC
  • mfrom: (6581.1.27 rules)
  • Revision ID: barry@python.org-20080203040319-mnb1sar9bumaih01
Merge the 'rules' branch.

Give the first alpha a code name.

This branch mostly gets rid of all the approval oriented handlers in favor of
a chain-of-rules based approach.  This will be much more powerful and
extensible, allowing rule definition by plugin and chain creation via web
page.

When a message is processed by the incoming queue, it gets sent through a
chain of rules.  The starting chain is defined on the mailing list object, and
there is a built-in default starting chain, called 'built-in'.  Each chain is
made up of links, which describe a rule and an action, along with possibly
some other information.  Actions allow processing to take a detour through
another chain, jump to another chain, stop processing, run a function, etc.

The built-in chain essentially implements the original early part of the
handler pipeline.  If a message makes it through the built-in chain, it gets
sent to the prep queue, where the message is decorated and such before sending
out to the list membership.  The 'accept' chain is what moves the message into
the prep queue.

There are also 'hold', 'discard', and 'reject' chains, which do what you would
expect them to.  There are lots of built-in rules, implementing everything
from the old emergency handler to new handlers such as one not allowing empty
subject headers.

IMember grows an is_moderated attribute.

The 'adminapproved' metadata key is renamed 'moderator_approved'.

Fix some bogus uses of noreply_address to no_reply_address.

Stash an 'original_size' attribute on the message after parsing its plain
text.  This can be used later to ensure the original message does not exceed a
specified size without have to flatten the message again.

The KNOWN_SPAMMERS global variable is replaced with HEADER_MATCHES.  The
mailing list's header_filter_rules variable is replaced with header_matches
which has the same semantics as HEADER_MATCHES, but is list-specific.

DEFAULT_MAIL_COMMANDS_MAX_LINES -> EMAIL_COMMANDS_MAX_LINES.

Update smtplistener.py to be much better, to use maildir format instead of
mbox format, to respond to RSET commands by clearing the maildir, and by
silencing annoying asyncore error messages.

Extend the doctest runner so that it will run .txt files in any docs
subdirectory in the code tree.

Add plugable keys 'mailman.mta' and 'mailman.rules'.  The latter may have only
one setting while the former is extensible.

There are lots of doctests which should give all the gory details.

Mailman/Post.py -> Mailman/inject.py and the command line usage of this module
is removed.

SQLALCHEMY_ECHO, which was unused, is removed.

Backport the ability to specify additional footer interpolation variables by
the message metadata 'decoration-data' key.

can_acknowledge() defines whether a message can be responded to by the email
robot.

Simplify the implementation of _reset() based on Storm fixes.  Be able to
handle lists in Storm values.

Do some reorganization.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Mailman/rules/docs/header-matching.txt
 
1
Header matching
 
2
===============
 
3
 
 
4
Mailman can do pattern based header matching during its normal rule
 
5
processing.  There is a set of site-wide default header matchines specified in
 
6
the configuaration file under the HEADER_MATCHES variable.
 
7
 
 
8
    >>> from Mailman.app.lifecycle import create_list
 
9
    >>> mlist = create_list(u'_xtest@example.com')
 
10
 
 
11
Because the default HEADER_MATCHES variable is empty when the configuration
 
12
file is read, we'll just extend the current header matching chain with a
 
13
pattern that matches 4 or more stars, discarding the message if it hits.
 
14
 
 
15
    >>> from Mailman.configuration import config
 
16
    >>> chain = config.chains['header-match']
 
17
    >>> chain.extend('x-spam-score', '[*]{4,}', 'discard')
 
18
 
 
19
First, if the message has no X-Spam-Score header, the message passes through
 
20
the chain untouched (i.e. no disposition).
 
21
 
 
22
    >>> msg = message_from_string("""\
 
23
    ... From: aperson@example.com
 
24
    ... To: _xtest@example.com
 
25
    ... Subject: Not spam
 
26
    ... Message-ID: <one>
 
27
    ...
 
28
    ... This is a message.
 
29
    ... """)
 
30
 
 
31
    >>> from Mailman.app.chains import process
 
32
 
 
33
Pass through is seen as nothing being in the log file after processing.
 
34
 
 
35
    # XXX This checks the vette log file because there is no other evidence
 
36
    # that this chain has done anything.
 
37
    >>> import os
 
38
    >>> fp = open(os.path.join(config.LOG_DIR, 'vette'))
 
39
    >>> fp.seek(0, 2)
 
40
    >>> file_pos = fp.tell()
 
41
    >>> process(mlist, msg, {}, 'header-match')
 
42
    >>> fp.seek(file_pos)
 
43
    >>> print 'LOG:', fp.read()
 
44
    LOG:
 
45
    <BLANKLINE>
 
46
 
 
47
Now, if the header exists but does not match, then it also passes through
 
48
untouched.
 
49
 
 
50
    >>> msg['X-Spam-Score'] = '***'
 
51
    >>> del msg['subject']
 
52
    >>> msg['Subject'] = 'This is almost spam'
 
53
    >>> del msg['message-id']
 
54
    >>> msg['Message-ID'] = '<two>'
 
55
    >>> file_pos = fp.tell()
 
56
    >>> process(mlist, msg, {}, 'header-match')
 
57
    >>> fp.seek(file_pos)
 
58
    >>> print 'LOG:', fp.read()
 
59
    LOG:
 
60
    <BLANKLINE>
 
61
 
 
62
But now if the header matches, then the message gets discarded.
 
63
 
 
64
    >>> del msg['x-spam-score']
 
65
    >>> msg['X-Spam-Score'] = '****'
 
66
    >>> del msg['subject']
 
67
    >>> msg['Subject'] = 'This is spam, but barely'
 
68
    >>> del msg['message-id']
 
69
    >>> msg['Message-ID'] = '<three>'
 
70
    >>> file_pos = fp.tell()
 
71
    >>> process(mlist, msg, {}, 'header-match')
 
72
    >>> fp.seek(file_pos)
 
73
    >>> print 'LOG:', fp.read()
 
74
    LOG: ... DISCARD: <three>
 
75
    <BLANKLINE>
 
76
 
 
77
For kicks, let's show a message that's really spammy.
 
78
 
 
79
    >>> del msg['x-spam-score']
 
80
    >>> msg['X-Spam-Score'] = '**********'
 
81
    >>> del msg['subject']
 
82
    >>> msg['Subject'] = 'This is really spammy'
 
83
    >>> del msg['message-id']
 
84
    >>> msg['Message-ID'] = '<four>'
 
85
    >>> file_pos = fp.tell()
 
86
    >>> process(mlist, msg, {}, 'header-match')
 
87
    >>> fp.seek(file_pos)
 
88
    >>> print 'LOG:', fp.read()
 
89
    LOG: ... DISCARD: <four>
 
90
    <BLANKLINE>
 
91
 
 
92
Flush out the extended header matching rules.
 
93
 
 
94
    >>> chain.flush()
 
95
 
 
96
 
 
97
List-specific header matching
 
98
-----------------------------
 
99
 
 
100
Each mailing list can also be configured with a set of header matching regular
 
101
expression rules.  These are used to impose list-specific header filtering
 
102
with the same semantics as the global `HEADER_MATCHES` variable.
 
103
 
 
104
The list administrator wants to match not on four stars, but on three plus
 
105
signs, but only for the current mailing list.
 
106
 
 
107
    >>> mlist.header_matches = [('x-spam-score', '[+]{3,}', 'discard')]
 
108
 
 
109
A message with a spam score of two pluses does not match.
 
110
 
 
111
    >>> del msg['x-spam-score']
 
112
    >>> msg['X-Spam-Score'] = '++'
 
113
    >>> del msg['message-id']
 
114
    >>> msg['Message-ID'] = '<five>'
 
115
    >>> file_pos = fp.tell()
 
116
    >>> process(mlist, msg, {}, 'header-match')
 
117
    >>> fp.seek(file_pos)
 
118
    >>> print 'LOG:', fp.read()
 
119
    LOG:
 
120
 
 
121
A message with a spam score of three pluses does match.
 
122
 
 
123
    >>> del msg['x-spam-score']
 
124
    >>> msg['X-Spam-Score'] = '+++'
 
125
    >>> del msg['message-id']
 
126
    >>> msg['Message-ID'] = '<six>'
 
127
    >>> file_pos = fp.tell()
 
128
    >>> process(mlist, msg, {}, 'header-match')
 
129
    >>> fp.seek(file_pos)
 
130
    >>> print 'LOG:', fp.read()
 
131
    LOG: ... DISCARD: <six>
 
132
    <BLANKLINE>
 
133
 
 
134
As does a message with a spam score of four pluses.
 
135
 
 
136
    >>> del msg['x-spam-score']
 
137
    >>> msg['X-Spam-Score'] = '+++'
 
138
    >>> del msg['message-id']
 
139
    >>> msg['Message-ID'] = '<seven>'
 
140
    >>> file_pos = fp.tell()
 
141
    >>> process(mlist, msg, {}, 'header-match')
 
142
    >>> fp.seek(file_pos)
 
143
    >>> print 'LOG:', fp.read()
 
144
    LOG: ... DISCARD: <seven>
 
145
    <BLANKLINE>