70.1.26. pepsi-stage-if

branch a message on a test of its stored state value

Manual section:

1

70.1.26.1.1. Name

pepsi-stage-if - the conditional-branch stage of the Pepsi pipeline.

70.1.26.1.2. Synopsis

pepsi-stage-if [GLOBAL-OPTIONS] worker

70.1.26.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-if 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 tests one member of the message state JSON for equality against a configured value: if they are equal it advances the message to TRUE_STAGE, otherwise to FALSE_STAGE. It is a programmable fork — an operator can route on any verdict an earlier stage recorded (state.spam, state.auth.dkim, …) without writing code.

The stage only ever moves the stage column. It never rewrites the message, never pauses or fails it, and leaves state untouched, so state.dsn and every other verdict are preserved across the branch. The message body is never loaded.

70.1.26.1.4. Condition

STATE_PATH is a dot-separated path into the state JSON. Each segment indexes an object by key; a segment that parses as an integer indexes an array by position. For example spam selects the top-level spam flag, auth.dkim the dkim member of the auth object, and dsn.rcpt.0.notify the notify field of the first recipient entry.

The value found there is compared to VALUE by its natural textual form:

  • a string matches its own text (pass matches pass);

  • a boolean matches true or false;

  • a number matches its decimal rendering (3, 1.5);

  • JSON null matches the literal null.

A path that is absent — or that resolves to an array or object, which has no scalar form — is never equal, so it takes the FALSE_STAGE branch. VALUE is required and cannot be empty (an empty option reads as unset).

70.1.26.1.5. Configuration

Options live in the stage’s own [stage-<name>] section (PROGRAM = pepsi-stage-if): the STATE_PATH tested, the VALUE compared against, and the TRUE_STAGE/FALSE_STAGE branch targets. They are documented in pepsi.conf(5).

70.1.26.1.6. State

Inputs: the single member of state selected by STATE_PATH.

Outputs: none — the stage only advances the message and leaves state unchanged. The state layout is described in pepsi.state(7).

Transitions: advances to TRUE_STAGE when the member selected by STATE_PATH equals VALUE (compared by scalar text form), otherwise to FALSE_STAGE — a missing path or a non-scalar value takes the FALSE_STAGE branch. These two advances are the only transitions; the stage never pauses, fails, reroutes or finishes.

70.1.26.1.7. Commands

worker

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

70.1.26.1.8. 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.26.1.9. Exit Status

0

The message was processed (advanced to TRUE_STAGE or FALSE_STAGE).

1

An error occurred (message not found or not running, misconfigured stage — e.g. a missing STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE — or a database error). The reason is written to the log.

70.1.26.1.10. Examples

Evaluate and route message 42 (it must be running):

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

A pipeline section that sends mail an earlier stage flagged as spam (state.spam == true) to the bounce stage and everything else onward:

[stage-if]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = true
TRUE_STAGE = bounce
FALSE_STAGE = srs

70.1.26.1.11. See Also

pepsi-config(1), pepsi-stage-check-whitelist(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

70.1.26.1.12. Bugs

Report bugs to the Pepsi issue tracker.