85.1.34. pepsi-stage-if

branch a message on a test of its stored state value

Handbuchabschnitt:

1

85.1.34.1.1. Name

pepsi-stage-if - die Bedingte-Verzweigungs-Stage der Pepsi-Pipeline.

85.1.34.1.2. Übersicht

pepsi-stage-if [GLOBAL-OPTIONS] worker

85.1.34.1.3. Beschreibung

Diese Stage hat den Standardwert FUSION = yes: Wenn Stage-Fusion aktiviert ist ([pepsi] ALLOW_FUSION, der Standardwert) und diese Stage in das vereinheitlichte pepsi-Binärprogramm eingefaltet ist, kann ein Vorgänger sie in seinem eigenen Worker-Prozess ausführen, statt sie separat zu dispatchen. Siehe pepsi-dispatch(1) und pepsi.conf(5).

pepsi-stage-if ist ein Stage-Programm, das von pepsi-dispatch(1) als persistenter Worker ausgeführt wird, der Nachrichten-IDs von der Standardeingabe liest. Es lädt diesen pepsi.workqueue-Datensatz (und weigert sich zu handeln, sofern sein status nicht running ist), liest seinen [stage-<stage>]-Abschnitt und testet ein Mitglied des state-JSON der Nachricht auf Gleichheit gegen einen konfigurierten Wert: Sind sie gleich, schaltet es die Nachricht zu TRUE_STAGE weiter, andernfalls zu FALSE_STAGE. Es ist eine programmierbare Verzweigung — ein Operator kann nach jedem Urteil routen, das eine frühere Stage festgehalten hat (state.spam, state.auth.dkim, …), ohne Code zu schreiben.

Die Stage verschiebt immer nur die stage-Spalte. Sie schreibt die Nachricht nie um, pausiert oder lässt sie nie fehlschlagen und lässt state unberührt, sodass state.dsn und jedes andere Urteil über die Verzweigung hinweg erhalten bleiben. Der Nachrichtentext wird nie geladen.

85.1.34.1.4. Bedingung

STATE_PATH ist ein punktgetrennter Pfad in das state-JSON. Jedes Segment indiziert ein Objekt nach Schlüssel; ein Segment, das als Ganzzahl geparst wird, indiziert ein Array nach Position. Zum Beispiel wählt spam das oberste spam-Flag, auth.dkim das dkim-Mitglied des auth-Objekts und dsn.rcpt.0.notify das notify-Feld des ersten Empfängereintrags.

Der dort gefundene Wert wird mit VALUE in seiner natürlichen Textform verglichen:

  • eine Zeichenkette passt auf ihren eigenen Text (pass passt auf pass);

  • ein Boolean passt auf true oder false;

  • eine Zahl passt auf ihre Dezimaldarstellung (3, 1.5);

  • JSON-null passt auf das literale null.

Ein Pfad, der fehlt — oder der auf ein Array oder Objekt auflöst, das keine Skalarform hat — ist nie gleich, sodass er den FALSE_STAGE-Zweig nimmt. VALUE ist erforderlich und kann nicht leer sein (eine leere Option gilt als nicht gesetzt).

85.1.34.1.5. Konfiguration

Die Optionen liegen im eigenen [stage-<name>]-Abschnitt der Stage (PROGRAM = pepsi-stage-if): das getestete STATE_PATH, der verglichene VALUE und die Verzweigungsziele TRUE_STAGE/FALSE_STAGE. Alle vier sind erforderlich, und pepsi-setup prüft zusätzlich, dass beide Verzweigungsziele bestehende Stages benennen. Die Stage hat kein NEXT_STAGE (beide Ziele werden ausdrücklich benannt). Sie sind in pepsi.conf(5) dokumentiert.

85.1.34.1.6. State

Eingaben: das einzelne von STATE_PATH ausgewählte Mitglied von state.

Ausgaben: keine — die Stage schaltet die Nachricht nur weiter und lässt state unverändert. Das State-Layout wird in pepsi.state(7) beschrieben.

Übergänge: schaltet zu TRUE_STAGE weiter, wenn das von STATE_PATH ausgewählte Mitglied gleich VALUE ist (nach Skalar-Textform verglichen), andernfalls zu FALSE_STAGE — ein fehlender Pfad oder ein nicht-skalarer Wert nimmt den FALSE_STAGE-Zweig. Diese beiden Weiterschaltungen sind die einzigen Übergänge; die Stage pausiert, schlägt fehl, leitet um oder schließt nie ab.

85.1.34.1.7. Befehle

worker

Läuft als persistenter pepsi-dispatch(1)-Worker, der Nachrichten-IDs von der Standardeingabe liest.

85.1.34.1.8. Globale Optionen

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit (Standardwert info).

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen.

-h, –help; -V, –version

Gibt eine Verwendungsübersicht / die Version aus und beendet sich.

85.1.34.1.9. Exit-Status

0

Die Nachricht wurde verarbeitet (zu TRUE_STAGE oder FALSE_STAGE weitergeschaltet).

1

Ein Fehler ist aufgetreten (Nachricht nicht gefunden oder nicht running, fehlkonfigurierte Stage — z. B. ein fehlendes STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE — oder ein Datenbankfehler). Der Grund wird in das Journal geschrieben.

85.1.34.1.10. Beispiele

Nachricht 42 über einen einmaligen Worker erneut verarbeiten (sie muss running sein):

echo 42 | pepsi-stage-if -c /etc/pepsi/pepsi.conf worker

Ein Pipeline-Abschnitt, der Mail, die eine frühere Stage als Spam markiert hat (state.spam == true), zur Bounce-Stage sendet und alles andere weiter:

[stage-if]
PROGRAM = pepsi-stage-if
STATE_PATH = spam
VALUE = true
TRUE_STAGE = bounce
FALSE_STAGE = srs

85.1.34.1.11. Siehe auch

pepsi-config(1), pepsi-stage-check-whitelist(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

85.1.34.1.12. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.