..
  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-stage-discard
===================

*A sink stage for staging and test deployments.*

Role
====

``pepsi-stage-discard`` deletes the message instead of relaying it, optionally
*simulating* a delivery outcome and the DSN it would produce. It lets a staging
pipeline exercise ingress, authentication and the stages without putting mail on
the network. Reference: :manpage:`pepsi-stage-discard(1)`.

Features
========

* **Terminal sink:** deletes the row and exits successfully; **ignores
  ``NEXT_STAGE``**.
* **Simulated disposition:** ``DISPOSITION = success`` (default) treats the
  message as delivered; ``failure`` treats it as a permanent delivery failure.
* **Optional DSN simulation** (``BOUNCE = yes``), honouring the sender's DSN
  preferences exactly as a real delivery stage would:

  * ``failure`` → routes to ``BOUNCE_STAGE`` for a failure bounce, but only if
    ``NOTIFY`` requests ``FAILURE`` (default when absent); ``NOTIFY=NEVER`` drops.
  * ``success`` → a positive (``Action: delivered``) report only when the global
    ``ORIGINATE_SUCCESS_DSN`` is on **and** ``NOTIFY=SUCCESS`` was requested.
* **Never bounces a bounce:** a null-sender message is simply deleted.
* When no DSN is warranted, the row is just deleted.

Configuration
=============

``[stage-<name>]``: ``PROGRAM = pepsi-stage-discard``, ``DISPOSITION``
(``success``/``failure``), ``BOUNCE`` (``yes``/``no``) and ``BOUNCE_STAGE`` (the
DSN-generation stage). Consults the shared ``[pepsi] ORIGINATE_SUCCESS_DSN`` for
the success path. See :manpage:`pepsi-stage-discard(1)`.

State
=====

* **Inputs:** ``state.dsn`` — the first recipient's ``notify``/``orcpt`` and the
  message-level ``envid``.
* **Outputs:** on a reportable discard, a ``state.bounce`` object
  (``permanent``/``success``) for the bounce stage; otherwise the row (and its
  ``state``) is deleted.

See also
========

:doc:`pepsi-stage-bounce`, :doc:`pepsi-stage-relay-to-internet`,
:doc:`../features`, :manpage:`pepsi-stage-discard(1)`.