63. pepsi-failure-bouncer

Funnel failed/timeout messages to the bounce stage.

63.1. Role

A message in the post-ingress pipeline ends up failed (a stage gave a permanent error, or its worker crashed) or timeout (a worker exceeded [pepsi-dispatch] MAX_RUNTIME) when its stage gives up. The dispatcher never re-queues such a row, so without operator action the message is stuck in pepsi.ingress and the sender is never notified.

pepsi-failure-bouncer moves each stuck message to the configured [pepsi-failure-bouncer] BOUNCE_STAGE and resets it to pending, so the dispatcher runs the bounce stage (pepsi-stage-bounce), which — per the sender’s RFC 3461 NOTIFY — emits a delivery-status notification. A message already at the bounce stage is left alone, so a bounce failing at that stage does not loop; one failing downstream (an unrelayable null-sender DSN) is moved back and simply dropped (a bounce is never re-bounced).

It connects through [pepsi-postgres] and is configured by [pepsi-failure-bouncer]. It is not a stage. Started as root it continues as the pepsi service account — the role that owns the queue — before connecting. Reference: pepsi-failure-bouncer(1).

63.2. Modes

• service (the default, no --once) — a long-lived process that LISTENs on the ingress_failed channel (fired by the ingress_failed_notify trigger whenever a row becomes failed/timeout) and bounces each message as it arrives. It sweeps all already-stuck messages on start-up and on every reconnect, so nothing is missed, and runs until SIGINT/SIGTERM.

• –once — sweep the currently-stuck messages a single time and exit (a manual operator run or a cron job).

--failed-only / --timeout-only restrict either mode to one of the two terminal states.

63.3. See also

pepsi-dispatch, pepsi-stage-bounce, pepsi-queue, pepsi-status, pepsi-failure-bouncer(1), pepsi.conf(5).