..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  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-queue
===========

*Inspect and repair the message workqueue.*

Role
====

``pepsi-queue`` is the operator's diagnostic and repair tool for the
``pepsi.workqueue`` table. It connects through the shared ``[pepsi-postgres]``
section and has no configuration of its own. Started as ``root`` it continues as
the ``pepsi`` service account before connecting, so no ``sudo -u pepsi`` is
needed. Reference: :manpage:`pepsi-queue(1)`.

Features
========

* **list** — list queued messages ordered by ``workqueue_id``, optionally as
  ``--json`` (``workqueue_id``, ``stage``, ``status``, ``mail_from``, ``subject``,
  ``received_at``, ``state``), with ``--limit`` (100 by default), ``--stage`` and
  ``--status`` filters, an optional *WORKQUEUE_ID* positional that restricts the
  output to one message, and ``--state-only`` to print each matching message's
  full, un-abbreviated JSON ``state`` instead of the row summary. ``list`` is the
  default action, so its positional and options are also accepted bare
  (``pepsi-queue 5``, ``pepsi-queue --state-only 5``).
* **delete** *WORKQUEUE_ID* — permanently remove a message.
* **set-stage** *WORKQUEUE_ID STAGE* — re-assign a message to a given stage and
  reset its ``status`` to ``pending`` (its ``state`` is left unchanged) so the new
  stage picks it up.
* **clear-all** — bulk "unstick": reset every ``running``/``paused`` message back
  to ``pending`` (``failed``/``timeout`` are left untouched) — the recovery used
  after a crash or a stalled stage.
* **gc** — garbage-collect the proof-of-origin nonce table
  (``pepsi.origin_nonce``), deleting entries whose expiration has passed, and
  the MX address cache (``pepsi.dns_address``), deleting rows whose DNS TTL has
  passed. Meant for a timer; the Debian package wires an hourly one.

The mutating subcommands act immediately and are not reversible. ``set-stage``
and ``clear-all`` also wake the dispatcher (``pepsi.workqueue`` carries no
notifying trigger, and these run outside the dispatcher's own loop, so nothing
else would). **Run ``clear-all`` only while ``pepsi-dispatch`` is stopped**: the
``running`` half names rows a live worker may still be holding, and resetting
them means the same message is claimed and handled twice.

Relationship to the dispatcher
==============================

``pepsi-queue`` manipulates the same ``stage``/``status``/``state`` columns the
dispatcher acts on; ``clear-all`` complements the dispatcher's own start-up reset
of orphaned ``running`` rows. It does not start stage programs.

See also
========

:doc:`pepsi-dispatch`, :doc:`../architecture`, :manpage:`pepsi-queue(1)`,
:manpage:`pepsi.conf(5)`.