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>, -owner and -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

-bounces

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.