48. pepsi-stage-if

Branch the pipeline on a stored state value.

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

48.2. Features

  • Dotted state paths: STATE_PATH is a dot-separated path into state. Each segment indexes an object by key; a segment that parses as an integer indexes an array by 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).

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

48.4. State

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

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

48.5. See also

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