60. pepsi-stage-if

Branch the pipeline on a stored state value.

60.1. Role

pepsi-stage-if is a programmable fork: it tests one member of the message state JSON for equality against a configured value and advances the message to TRUE_STAGE when they are equal, otherwise to FALSE_STAGE. It lets an operator route on any verdict that an earlier stage recorded — state.spam, state.auth.dkim, state.local_origin, … — without writing code. It only moves the stage column; it never rewrites, pauses or fails a message, and leaves state untouched. Reference: pepsi-stage-if(1).

60.2. Features

  • Dotted state paths: STATE_PATH is a dot-separated path into state. A segment selects an object’s member by name, or an array’s element by a non-negative integer position — e.g. spam, auth.dkim, dsn.rcpt.0.notify.

  • Scalar text comparison: the value found is compared to VALUE by its natural textual form — a string matches its text, a boolean true/false, a number its decimal rendering, JSON null the literal null.

  • False on absent or non-scalar: a path that is missing, or that resolves to an array or object (which has no scalar form), is never equal and so takes the FALSE_STAGE branch. VALUE is required and may not be empty.

  • Non-destructive: the body is never loaded and state (including state.dsn) is preserved across the branch, so the stage can be placed anywhere in the graph.

A common use is to split the pipeline by direction: pepsi-ingress records state.local_origin = true for an authenticated submission, so a STATE_PATH = local_origin / VALUE = true test sends outbound mail down a signing/relay path and inbound mail down the filtering/delivery path (see Getting started on a cheap VPS).

Another is to hold encrypted mail from strangers that no key here can open, which would otherwise pass every content filter as ciphertext: after pepsi-stage-check-whitelist, one if passes whitelisted senders (spam = false) on and a second sends crypto.in.failure = no-decryption-key to a quarantine or discard stage (pepsi-stage-if(1) has the sections). It must branch on “no key here” alone, never on a failed decryption, and must never lead to a bounce: a route that depends on whether a modified AES-CBC ciphertext decrypts is a padding oracle (CBC padding and format oracles against unauthenticated S/MIME, Encrypted unsolicited mail evades content filters).

60.3. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-if, STATE_PATH (the dotted path to test), VALUE (required, the value compared against), and the TRUE_STAGE/FALSE_STAGE branch targets. pepsi-setup checks that both branch targets resolve to real stages, like NEXT_STAGE. See pepsi-stage-if(1).

All four options are subject to per-address settings: if the stage is listed in an edit-settings stage’s EDITABLE_STAGES, a correspondent can redirect their own mail to either branch or anywhere else. Never list an if stage that guards a security decision (see Per-address settings are a trust boundary).

60.4. State

  • Inputs: the single member of state selected by STATE_PATH.

  • Outputs: none — the stage only advances the message and leaves state unchanged.

60.5. See also

pepsi-stage-check-whitelist, pepsi-stage-bounce, Supported Features, Getting started on a cheap VPS, pepsi-stage-if(1).