70.1.15. pepsi-stage-discard

discard a message (a sink stage for staging)

Manual section:

1

70.1.15.1.1. Name

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

70.1.15.1.2. Synopsis

pepsi-stage-discard [GLOBAL-OPTIONS] worker

70.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.ingress row (refusing to act unless its status is running), reads its [stage-<stage>] section, and then discards the message: the row is deleted and the program exits successfully. 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:

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

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

  • A message that is already a bounce (the null sender) is never bounced again.

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.

70.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 is routed to. 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).

70.1.15.1.5. State

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

Outputs: on a reportable discard the stage reroutes to BOUNCE_STAGE, writing a state.bounce object (kind = permanent for a failure, or success for a positive report) merged into the existing state for pepsi-stage-bounce(1). Otherwise the row (and its state) is deleted. The state layout is described in pepsi.state(7).

Transitions (driven by DISPOSITION, BOUNCE, the 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 with ORIGINATE_SUCCESS_DSN and NOTIFY=SUCCESS) — → reroute to BOUNCE_STAGE with a state.bounce object;

  • otherwise → finish (the row is deleted).

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

70.1.15.1.6. Commands

worker

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

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

70.1.15.1.8. Exit Status

0

The message was processed (discarded, or rerouted to generate a DSN).

1

An error occurred (message not found or not running, misconfigured stage, or a database error). The reason is written to the log.

70.1.15.1.9. Examples

Discard message 42 (it must be running):

pepsi-stage-discard -c /etc/pepsi/pepsi.conf 42

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

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

70.1.15.1.11. Bugs

Report bugs to the Pepsi issue tracker.