95.1.20. pepsi-stage-list¶
route mail addressed to a mailing list
- Manual section:
1
95.1.20.1.1. Name¶
pepsi-stage-list - the mailing-list router of the Pepsi pipeline.
95.1.20.1.2. Synopsis¶
pepsi-stage-list [GLOBAL-OPTIONS] worker
95.1.20.1.3. Description¶
pepsi-stage-list is a stage program run by pepsi-dispatch(1). It
looks at each envelope recipient, decides whether it names a mailing list on
this server, and routes the message accordingly. It is the only one of the
five list stages that runs on every message, so it is cheap by design: it
loads the envelope and state and never the headers or the body.
Pepsi’s mailing-list subsystem is a reimplementation of GNU Mailman 3. The
address vocabulary that this stage recognises (the posting address and the eight
role sub-addresses) is upstream’s, copyright the Free Software Foundation and
its contributors, so that a site migrating from Mailman keeps every address that
its subscribers already use. Files in Pepsi that came from GNU Mailman remain under
the GNU General Public License; see pepsi-list(1) for the fuller
statement and vendor/PEPSI-VENDORING.md for the list.
A server that hosts no lists is unaffected by it. With no lists configured the routing table is empty and every message advances to NEXT_STAGE, which is what makes dropping the section into an existing pipeline harmless.
95.1.20.1.4. Addresses recognised¶
For each recipient the stage matches, in this order:
the posting address
<list>@<host>;then the eight role sub-addresses
-request,-join,-subscribe,-leave,-unsubscribe,-confirm+<token>,-ownerand-bounces(optionally carrying VERP detail,-bounces+alice=example.net=<code>).
Posting addresses are matched before the suffixes, and the suffixes are
tried longest-first. Both orders matter. A list may legitimately be called
foo-request; matching suffixes first would make it unreachable the moment
somebody created a list called foo, and the symptom would be mail to a real
list silently entering the command path. Longest-first is why -unsubscribe
is not read as -subscribe with a stem ending in -un.
Warning
Setting [pepsi] RECIPIENT_DELIMITER to - breaks list
sub-addressing entirely. Every sub-address is <list>-<role>, so with
- as the delimiter the base of announce-owner@ is announce, which
is the posting address, and mail meant for the owners is posted to the list
instead. The same option is the delimiter that the fan-out writes into each VERP
envelope sender and the -confirm+token address, so the router always
splits what the lists wrote.
95.1.20.1.5. Routing¶
A recipient that names a list is routed to one of three stages by role:
Role |
Stage option |
|---|---|
the posting address |
POST_STAGE |
|
BOUNCE_STAGE |
every other role |
COMMAND_STAGE |
-owner goes to the command stage even though it carries no command: it is
the stage that knows how to look up a list’s owners and how to suppress an
auto-reply loop, and giving it a fourth stage of its own would duplicate both.
A message addressed to a list and to an ordinary mailbox, or to two lists,
is split, one row per destination, each carrying its own recipients and its own
slice of state.dsn.rcpt. The not-a-list group, when there is one, stays on
the original row.
Warning
BOUNCE_STAGE here means the opposite of what it means on every other stage in pepsi.conf(5). On this stage it is where somebody else’s inbound bounce is consumed; everywhere else it is where Pepsi generates a DSN. Pointing it at pepsi-stage-bounce(1) answers a bounce with a bounce, which makes a mail loop rather than a misrouted message; pepsi-setup refuses that configuration.
95.1.20.1.6. Freshness¶
The routing table is loaded once per worker. When the database announces a
change on the pepsi_list_changed channel, the dispatcher retires the
stage’s workers, and their successors load a fresh table. A list created while the dispatcher is running
therefore starts receiving mail with no restart and no staleness window. The
stage itself holds no listener: a stage worker’s connection pool is exactly one
connection, and a listener inside the worker would hold it forever.
95.1.20.1.7. Fusion¶
A fusion successor may run in-process only if its Load is satisfied by what
the predecessor already loaded. This stage loads metadata only. It can
therefore fuse its own advance to NEXT_STAGE, which is the not-a-list path
that runs on every message, but it cannot fuse into
pepsi-stage-list-post(1), which needs the body. Routing an actual list post costs one ordinary stage
transition.
95.1.20.1.8. Configuration¶
The stage’s own [stage-<name>] section holds NEXT_STAGE,
POST_STAGE, COMMAND_STAGE and BOUNCE_STAGE; all four are required.
Per-list
configuration is in the database, not here; see pepsi-list(1).
95.1.20.1.9. State¶
Inputs: the envelope rcpt_to.
Outputs: a state.list descriptor on each routed row, with the list’s
id, the role, the address that the message arrived at, and whatever detail the
sub-address carried. That detail is a -confirm token, or a -bounces
VERP detail copied verbatim; the bounce stage, which holds the key, decodes and
verifies it. The descriptor is deliberately small: the worker stage reads
everything else that it needs from the database, which it is about to do
anyway.
Transitions: advances (to NEXT_STAGE or to a role’s stage), and fans out when the recipients split.
95.1.20.1.10. Commands¶
- worker
Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.
95.1.20.1.11. Global Options¶
The usual set: -c/–config, -L/–log, -v/–verbose, -h/–help and -V/–version, which behave as they do for every Pepsi program; see pepsi-config(1).
95.1.20.1.12. Exit Status¶
The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.
- 0
The worker ran until its standard input was closed.
- 1
A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.
- 78
The worker refused to start: a
[stage-*]section it serves, or[pepsi]RECIPIENT_DELIMITER, does not parse (e.g. a missing POST_STAGE). The dispatcher requeues what it handed over and retries the stage later.
95.1.20.1.13. Examples¶
[stage-list]
PROGRAM = pepsi-stage-list
NEXT_STAGE = aliases
POST_STAGE = list-post
COMMAND_STAGE = list-command
BOUNCE_STAGE = list-bounce
95.1.20.1.14. See Also¶
pepsi-list(1), pepsi-stage-list-post(1), pepsi-stage-list-deliver(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.20.1.15. Bugs¶
Report bugs to the Pepsi issue tracker.