95.1.16. pepsi-stage-discard

discard a message (a sink stage for staging)

Manual section:

1

95.1.16.1.1. Name

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

95.1.16.1.2. Synopsis

pepsi-stage-discard [GLOBAL-OPTIONS] worker

95.1.16.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 the message’s 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 decide what the discard reports back to the sender, if anything.

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.

The row is simply deleted, with nothing spawned, 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.

95.1.16.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 that receives the sibling reports of a reportable discard. Both stage options are optional, and 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).

95.1.16.1.5. State

Inputs: state.dsn, that is, 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 whose state is the original’s (without list and the retry/failure bookkeeping) plus 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 finishes the row and spawns one sibling per such recipient at BOUNCE_STAGE. It is either a failure (DISPOSITION = failure, BOUNCE = yes, NOTIFY wanting failure) or a positive report (DISPOSITION = success, BOUNCE = yes, with ORIGINATE_SUCCESS_DSN and NOTIFY=SUCCESS);

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

95.1.16.1.6. Commands

worker

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

95.1.16.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 [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

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

78

The stage’s section does not parse (e.g. an unknown DISPOSITION): the worker refuses to start, and pepsi-dispatch(1) holds the stage’s messages until the configuration is fixed.

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

95.1.16.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)

95.1.16.1.11. Bugs

Report bugs to the Pepsi issue tracker.