85.1.15. pepsi-stage-discard

discard a message (a sink stage for staging)

Manual section:

1

85.1.15.1.1. Name

pepsi-stage-discard - the discard (sink) stage of the Pepsi pipeline.

85.1.15.1.2. Synopsis

pepsi-stage-discard [GLOBAL-OPTIONS] worker

85.1.15.1.3. Description

This stage defaults to FUSION = yes: when stage fusion is enabled ([pepsi] ALLOW_FUSION, the default) and this stage is folded into the unified pepsi binary, a predecessor may run it in its own worker process instead of dispatching it separately. See pepsi-dispatch(1) and pepsi.conf(5).

pepsi-stage-discard is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. It loads that pepsi.workqueue row (refusing to act unless its status is running), reads its [stage-<stage>] section, and then discards the message: the row is deleted and reported to the dispatcher as a success. Nothing is relayed anywhere. This is intended for staging and test deployments — for example a pipeline that exercises ingress, authentication and the stages without putting mail onto the network.

The discard is deliberately terminal: it ignores NEXT_STAGE. Two options shape what — if anything — the discard reports back to the sender.

DISPOSITION chooses the simulated outcome: success (the default) treats the message as delivered, failure treats it as a permanent delivery failure.

BOUNCE (default no) chooses whether the discard may emit a delivery-status notification (DSN) at all. When it may, the sender’s DSN preferences are always honoured, and they are honoured per recipient: NOTIFY is given one RCPT at a time, so it is answered one recipient at a time. In either case the row itself is always deleted; a report is a sibling message spawned alongside that deletion, one per reportable recipient, in the same single database call (its token is the original’s with a -discard<N> suffix, so the spawn is at-most-once):

• failure + BOUNCE = yes: one sibling per recipient whose NOTIFY requests FAILURE (the default when absent) is routed to the stage’s BOUNCE_STAGE, which generates the failure bounce; NOTIFY=NEVER drops silently.

• success + BOUNCE = yes: a positive (Action: delivered) report is spawned the same way, but only when the global [pepsi] ORIGINATE_SUCCESS_DSN is enabled and that recipient’s NOTIFY requests SUCCESS (success has no implicit default).

• A message that is already a bounce (the null sender) is never bounced again, and never draws a success report either.

In every case where no DSN is warranted — BOUNCE = no, NOTIFY not requesting the relevant report, a null-sender message, or no BOUNCE_STAGE wired — the row is simply deleted with nothing spawned.

85.1.15.1.4. Configuration

Options live in the stage’s own [stage-<name>] section (PROGRAM = pepsi-stage-discard): DISPOSITION (success/failure), BOUNCE (yes/no) and the BOUNCE_STAGE a reportable discard’s sibling reports are routed to. Both stage options are optional — a discard with no BOUNCE_STAGE simply deletes the row. NEXT_STAGE is ignored (a discard is terminal) and the success path consults the shared [pepsi] ORIGINATE_SUCCESS_DSN flag. All are documented in pepsi.conf(5).

85.1.15.1.5. State

Inputs: state.dsn — each recipient’s notify/orcpt and the message-level envid/ret, used to decide whether (and how) to notify the sender, recipient by recipient.

Outputs: none on the message itself, which is always deleted. On a reportable discard each reportable recipient gets a sibling message at BOUNCE_STAGE carrying a state.bounce object (kind = permanent for a failure, or success for a positive report, plus diagnostic and the failed_recipient it reports on) for pepsi-stage-bounce(1). The state layout is described in pepsi.state(7).

Transitions (driven by DISPOSITION, BOUNCE, each recipient’s NOTIFY and [pepsi] ORIGINATE_SUCCESS_DSN):

• a reportable outcome — a failure (DISPOSITION = failure, BOUNCE = yes, NOTIFY wanting failure) or a positive report (DISPOSITION = success, BOUNCE = yes, with ORIGINATE_SUCCESS_DSN and NOTIFY=SUCCESS) — finishes the row and spawns one sibling per such recipient at BOUNCE_STAGE;

• otherwise → finish (the row is deleted, nothing spawned).

NEXT_STAGE is ignored (a discard is always terminal); a null-sender bounce is never re-bounced. The stage never advances, pauses or fails.

85.1.15.1.6. Commands

worker

Run as a persistent pepsi-dispatch(1) worker, reading message ids on standard input.

85.1.15.1.7. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (default info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

85.1.15.1.8. 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.

85.1.15.1.9. Examples

Discard message 42 through a one-off worker (it must be running):

echo 42 | pepsi-stage-discard -c /etc/pepsi/pepsi.conf worker

A staging [stage-*] section that quietly drops everything as delivered:

[stage-sink]
PROGRAM = pepsi-stage-discard
DISPOSITION = success

A section that simulates permanent failure and bounces (honouring NOTIFY):

[stage-sink]
PROGRAM = pepsi-stage-discard
DISPOSITION = failure
BOUNCE = yes
BOUNCE_STAGE = bounce

85.1.15.1.10. See Also

pepsi-config(1), pepsi-stage-bounce(1), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

85.1.15.1.11. Bugs

Report bugs to the Pepsi issue tracker.