85.1.34. pepsi-stage-if

branch a message on a test of its stored state value

Section du manuel:

1

85.1.34.1.1. Nom

pepsi-stage-if - l’étape de branchement conditionnel du pipeline Pepsi.

85.1.34.1.2. Synopsis

pepsi-stage-if [GLOBAL-OPTIONS] worker

85.1.34.1.3. Description

Cette étape a FUSION = yes par défaut : lorsque la fusion d’étapes est activée ([pepsi] ALLOW_FUSION, la valeur par défaut) et que cette étape est pliée dans le binaire pepsi unifié, un prédécesseur peut l’exécuter dans son propre processus worker plutôt que de la dispatcher séparément. Voir pepsi-dispatch(1) et pepsi.conf(5).

pepsi-stage-if est un programme d’étape exécuté par pepsi-dispatch(1) comme worker persistant lisant les identifiants de message sur l’entrée standard. Il charge cette ligne pepsi.workqueue (refusant d’agir si son status n’est pas running), lit sa section [stage-<stage>], et teste l’égalité d’un membre du JSON state du message avec une valeur configurée : s’ils sont égaux, il fait avancer le message vers TRUE_STAGE, sinon vers FALSE_STAGE. C’est un branchement programmable — un opérateur peut acheminer selon n’importe quel verdict qu’une étape antérieure a noté (state.spam, state.auth.dkim, …) sans écrire de code.

L’étape ne fait jamais que déplacer la colonne stage. Elle ne réécrit jamais le message, ne le met jamais en pause ni ne le fait échouer, et laisse state intact, de sorte que state.dsn et chaque autre verdict sont préservés à travers la branche. Le corps du message n’est jamais chargé.

85.1.34.1.4. Condition

STATE_PATH est un chemin séparé par des points dans le JSON state. Chaque segment indexe un objet par clé ; un segment qui s’analyse comme un entier indexe un tableau par position. Par exemple spam sélectionne l’indicateur spam de premier niveau, auth.dkim le membre dkim de l’objet auth, et dsn.rcpt.0.notify le champ notify de la première entrée de destinataire.

La valeur trouvée là est comparée à VALUE par sa forme textuelle naturelle :

  • une chaîne correspond à son propre texte (pass correspond à pass) ;

  • un booléen correspond à true ou false ;

  • un nombre correspond à son rendu décimal (3, 1.5) ;

  • le null JSON correspond au littéral null.

Un chemin qui est absent — ou qui se résout en un tableau ou objet, qui n’a pas de forme scalaire — n’est jamais égal, il prend donc la branche FALSE_STAGE. VALUE est obligatoire et ne peut pas être vide (une option vide est lue comme non définie).

85.1.34.1.5. Configuration

Les options résident dans la section [stage-<name>] propre à l’étape (PROGRAM = pepsi-stage-if) : le STATE_PATH testé, le VALUE auquel comparer, et les cibles de branche TRUE_STAGE/FALSE_STAGE. Toutes quatre sont obligatoires, et pepsi-setup vérifie en outre que les deux cibles de branche nomment des étapes existantes. L’étape n’a pas de NEXT_STAGE (les deux destinations sont nommées explicitement). Elles sont documentées dans pepsi.conf(5).

85.1.34.1.6. État

Entrées : l’unique membre de state sélectionné par STATE_PATH.

Sorties : aucune — l’étape ne fait qu’avancer le message et laisse state inchangé. La disposition de l’état est décrite dans pepsi.state(7).

Transitions : avance vers TRUE_STAGE lorsque le membre sélectionné par STATE_PATH est égal à VALUE (comparé par sa forme textuelle scalaire), sinon vers FALSE_STAGE — un chemin manquant ou une valeur non scalaire prend la branche FALSE_STAGE. Ces deux avancées sont les seules transitions ; l’étape ne met jamais en pause, ne fait jamais échouer, ne réachemine ni ne termine.

85.1.34.1.7. Commandes

worker

Exécuté comme un worker persistant de pepsi-dispatch(1), lisant les identifiants de message sur l’entrée standard.

85.1.34.1.8. Options globales

-c FILE, –config FILE

Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.

-L LOGLEVEL, –log LOGLEVEL

Règle la verbosité de journalisation (par défaut info).

-v, –verbose

Affiche les messages de journal de toutes les sources.

-h, –help ; -V, –version

Affiche un résumé d’utilisation / la version et quitte.

85.1.34.1.9. Code de sortie

0

Le message a été traité (avancé vers TRUE_STAGE ou FALSE_STAGE).

1

Une erreur s’est produite (message introuvable ou pas en running, étape mal configurée — par exemple un STATE_PATH/VALUE/TRUE_STAGE/FALSE_STAGE manquant — ou une erreur de base de données). La raison est écrite dans le journal.

85.1.34.1.10. Exemples

Retraiter le message 42 avec un worker ponctuel (il doit être running)

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

Une section de pipeline qui envoie le courrier qu’une étape antérieure a marqué comme spam (state.spam == true) vers l’étape de rebond et tout le reste plus loin

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

85.1.34.1.11. Voir aussi

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. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.