..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

=====================
pepsi-failure-bouncer
=====================

*Funnel failed/timeout messages to the bounce stage.*

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 (:doc:`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: :manpage:`pepsi-failure-bouncer(1)`.

Modes
=====

* **service** (the default, no ``--once``) — a long-lived process that
  ``LISTEN``\ s 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.

See also
========

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