85.1.30. pepsi-stage-block-language

route a message by its detected body language(s)

Section du manuel:

1

85.1.30.1.1. Nom

pepsi-stage-block-language - l’étape de politique de langue du pipeline Pepsi.

85.1.30.1.2. Synopsis

pepsi-stage-block-language [GLOBAL-OPTIONS] worker

85.1.30.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-block-language est un programme d’étape exécuté par pepsi-dispatch(1) comme un worker persistant lisant les identifiants de message sur l’entrée standard. Il charge cette ligne pepsi.workqueue (refusant d’agir sauf si son status est running), lit sa section [stage-<stage>], évalue la ou les langues humaines notées sous state.language (par pepsi-stage-detect-language(1)) par rapport à une liste blanche et une liste noire configurées, et achemine le message en conséquence : au-dessus du seuil de score, il avance vers NEXT_STAGE, sinon il est bloqué. Ce que fait le blocage relève de l’option ENFORCEMENT — un rebond, ou un indicateur sur un message remis malgré tout (voir Application ci-dessous). Le reste de state (state.dsn, l”origin d’ingress, …) est préservé, et cette étape ne lui ajoute jamais rien.

85.1.30.1.4. Calcul du score

state.language est une chaîne de style HTTP Accept-Language d’éléments code;q=quality, où chaque quality est la probabilité de détection de cette langue. L’étape la transforme en un seul nombre :

score = Σ q over languages listed in WHITELIST
      − Σ q over languages listed in BLACKLIST

Les langues qui ne figurent sur aucune des deux listes ne contribuent en rien. Par exemple, avec l’anglais en liste blanche et le français en liste noire, un message noté en;q=0.7, fr;q=0.3 obtient le score 0.7 − 0.3 = 0.4.

Une entrée de liste est une plage de langues, comparée à une étiquette détectée par le filtrage de base de la RFC 4647 §3.3.1 : la plage correspond lorsqu’elle est égale à l’étiquette, ou égale à un préfixe de celle-ci suivi de -. Ainsi un simple de correspond à un de-CH détecté, et un de-CH plus étroit — également accepté dans les listes — ne correspond qu’à un de-CH détecté, pas à un de nu.

Si aucune langue n’a été détectée (state.language est absent), le score est calculé par rapport à la pseudo-distribution none;q=1. Le pseudo-code littéral none peut lui-même apparaître dans WHITELIST ou BLACKLIST, de sorte qu’un opérateur décide du sort du courrier non détecté : mettre none en liste noire lui donne le score −1, en liste blanche +1, et ne le lister nulle part le laisse à 0.

Un message qui porte un verdict explicite state.spam = false — posé par une correspondance de liste blanche en amont (pepsi-stage-check-whitelist(1)) ou par l’ingress pour le courrier adressé uniquement à la boîte aux lettres réservée <Postmaster> (RFC 5321 §4.5.1) — contourne entièrement la politique de langue et avance vers NEXT_STAGE quelle que soit sa langue détectée.

Sinon, un message dont le score est strictement supérieur à THRESHOLD avance vers NEXT_STAGE ; un message à ce niveau ou en dessous est bloqué. Un message qui est déjà un rebond (l’expéditeur d’enveloppe nul) est exempté dans les deux modes d’application — il avance vers NEXT_STAGE quel que soit son score, car un rebond ne doit jamais rebondir, et un indicateur annoncerait alors un rebond qui n’allait de toute façon pas avoir lieu.

Note

Comme la comparaison est stricte et que les langues non listées contribuent 0, une politique « tout autoriser sauf une liste noire » nécessite un THRESHOLD négatif. Avec le THRESHOLD = 0.0 par défaut et seulement une BLACKLIST définie, chaque message de langue neutre obtient le score 0 — qui n’est pas supérieur à 0 — et est bloqué. pepsi-setup(1) avertit de cette erreur de configuration particulière (une BLACKLIST avec une WHITELIST vide et un THRESHOLD non négatif).

Cette étape ne met jamais un message en pause, et le corps du message n’est jamais chargé.

85.1.30.1.5. Application

ENFORCEMENT décide de ce qu’il advient d’un message bloqué. Les deux modes agissent sur exactement le même ensemble de messages : tout ce que hard fait rebondir, soft le marque.

hard (la valeur par défaut)

Le message est acheminé vers BOUNCE_STAGE avec un state de DSN d’échec permanent, de sorte que pepsi-stage-bounce(1) n’émet un rebond que si le NOTIFY de l’expéditeur demande FAILURE (la valeur par défaut en son absence). Dans les deux cas, le message n’est pas remis. Rien du message lui-même n’est réécrit. pepsi-setup(1) refuse une étape hard dépourvue de BOUNCE_STAGE, et son worker refuse de démarrer sur une telle section, puisqu’elle ferait autrement échouer chaque message que la politique rejette.

Un message comportant plusieurs destinataires d’enveloppe est d’abord scindé afin que chaque destinataire soit bloqué sur sa propre ligne, et que chacun obtienne donc son propre groupe par destinataire dans le DSN (RFC 3464 §2.3.1) et soit jugé selon son propre NOTIFY. Sans cette scission, le rapport nommerait une seule adresse et laisserait l’expéditeur croire que les autres avaient été remises.

soft

Le message est remis malgré tout, marqué, et avance vers NEXT_STAGE :

  • SUBJECT_FLAG_LABEL (par défaut [!LANG]) est ajouté à son Subject:, dans le bloc d’en-têtes et dans la colonne subject de la ligne, de sorte que la marque soit visible à la fois pour le destinataire et pour pepsi-queue(1). Elle n’est ajoutée que si le sujet ne la contient pas déjà, sans tenir compte de la casse, de sorte qu’une réponse qui la renvoie à travers cette étape n’en accumule pas une seconde. Un message arrivé sans champ Subject: n’en gagne aucun — l’étape n’invente pas d’en-tête — mais sa colonne est tout de même marquée.

  • Un en-tête X-Pepsi-Detected-Languages est ajouté, portant la détection dans la même forme code;q=value qu’un en-tête HTTP Accept-Language. Il est re-rendu depuis la distribution qui a réellement été évaluée — de sorte que le champ et la décision ne peuvent pas diverger, chaque qualité étant arrondie à deux décimales — et pour le courrier non détecté il porte la pseudo-distribution none;q=1 qui a été évaluée. Toute copie de ce champ déjà présente sur le message est retirée au préalable : il n’est pas dans l’espace de noms X-Pepsi-* que pepsi-stage-decrypt(1) supprime en bloc, de sorte qu’un message entrant peut en porter un falsifié, et le champ dont hérite un message remis doit être la réponse de ce serveur plutôt que celle de l’expéditeur.

  • BOUNCE_STAGE n’est pas consultée, et aucun DSN n’est généré.

C’est le mode par lequel commencer. Les indicateurs qui s’accumulent dans de vraies boîtes aux lettres sont un aperçu fidèle de ce que l’application refuserait, de sorte que WHITELIST, BLACKLIST et THRESHOLD peuvent être réglés sur du trafic authentique avant que le courrier d’un correspondant ne soit jeté. Étant une option d’étape ordinaire, ENFORCEMENT est redéfinissable par adresse (pepsi-settings(1)) — un compte peut rester en apprentissage pendant que le reste du déploiement applique la règle.

Avertissement

Réécrire le Subject: casse la signature DKIM de l’expéditeur et l”AMS ARC propre à ce serveur : les deux sur-signent Subject. C’est le même compromis que fait pepsi-stage-vacation(1) pour son VACATION_TAG, et il est gratuit sur une branche qui se termine par une remise locale et pas gratuit sur une branche qui relaie le message plus loin. Mettez ENFORCEMENT = soft sur la première. hard ne réécrit aucun en-tête.

85.1.30.1.6. Configuration

Les options résident dans la propre section [stage-<name>] de l’étape (PROGRAM = pepsi-stage-block-language) : NEXT_STAGE, BOUNCE_STAGE, les listes de langues WHITELIST/BLACKLIST, le THRESHOLD, et le couple ENFORCEMENT/SUBJECT_FLAG_LABEL ci-dessus. Elles sont documentées dans pepsi.conf(5).

85.1.30.1.7. État

Entrées : state.language (la chaîne de style Accept-Language écrite par pepsi-stage-detect-language(1) ; traitée comme none;q=1 en son absence) et, pour un message rebondi, state.dsn et le destinataire d’enveloppe.

Sorties : sur le chemin de passage, l’étape avance et laisse state intact. Sous ENFORCEMENT = hard, un message bloqué est réacheminé vers BOUNCE_STAGE, fusionnant les clés de DSN d’échec que pepsi-stage-bounce(1) consomme (state.bounce). Sous soft, l’étape n’écrit aucun state : la marque est dans le message, non dans les métadonnées de la ligne. La disposition de l’état est décrite dans pepsi.state(7).

Transitions (le score est calculé à partir de WHITELIST/BLACKLIST, la pseudo-langue none servant à évaluer le courrier non détecté) :

  • state.spam = false → avancer vers NEXT_STAGE, sans être évalué ;

  • score au-dessus de THRESHOLD → avancer vers NEXT_STAGE ;

  • score égal ou inférieur à THRESHOLD, le message est un rebond (expéditeur nul) → avancer vers NEXT_STAGE, non marqué, dans les deux modes ;

  • score à ou en dessous du THRESHOLD, ENFORCEMENT = hard, plus d’un destinataire d’enveloppe → la ligne est scindée en une ligne par destinataire, chacune laissée pending à cette même étape, et chacune jugée de nouveau à sa propre passe suivante ;

  • score égal ou inférieur à THRESHOLD, ENFORCEMENT = hard → réacheminer vers BOUNCE_STAGE en portant state.bounce (un DSN d’échec) ;

  • score égal ou inférieur à THRESHOLD, ENFORCEMENT = soft → réécrire les en-têtes Subject:/X-Pepsi-Detected-Languages et avancer vers NEXT_STAGE.

L’étape ne se met jamais en pause. Elle ne fait échouer un message que lorsqu’un paramètre par adresse active ENFORCEMENT = hard pour une étape sans BOUNCE_STAGE et que la politique le bloque.

85.1.30.1.8. Commandes

worker

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

85.1.30.1.9. 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.30.1.10. Code de sortie

0

Le message a été traité (avancé ou acheminé vers l’étape de rebond).

1

Une erreur s’est produite (message introuvable ou non running, ou un paramètre par adresse qui casse la section de l’étape — un code de langue invalide, WHITELIST et BLACKLIST toutes deux vides, un chevauchement entre elles, ou un blocage sans BOUNCE_STAGE). La raison est écrite dans le journal.

Une défaillance de l’hôte (la base de données, un modèle ou un helper inutilisable) n’est pas signalée comme un échec : le message est mis en pause et réessayé, comme le décrit Erreurs d’étape dans pepsi-dispatch(1). Une section qui ne s’analyse pas fait refuser au worker de démarrer (statut 78) au lieu de faire échouer chaque message tour à tour.

85.1.30.1.11. Exemples

Évaluer et acheminer le message 42 (il doit être running)

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

Une section de pipeline qui accepte le courrier en anglais, rejette le courrier d’apparence française, et laisse passer le courrier non détecté (0 dépasse le seuil -0.1)

[stage-block-language]
PROGRAM = pepsi-stage-block-language
NEXT_STAGE = srs
BOUNCE_STAGE = bounce
WHITELIST = en
BLACKLIST = fr
THRESHOLD = -0.1

La même politique en mode apprentissage : rien n’est refusé, et le courrier qui aurait été refusé arrive avec un sujet marqué et un en-tête qui dit pourquoi

[stage-block-language]
PROGRAM = pepsi-stage-block-language
NEXT_STAGE = local
BOUNCE_STAGE = bounce
WHITELIST = en
BLACKLIST = fr
THRESHOLD = -0.1
ENFORCEMENT = soft

Un message d’allure française parvient alors au destinataire ainsi

X-Pepsi-Detected-Languages: fr;q=0.87, en;q=0.09
Subject: Bonjour [!LANG]

Garder un utilisateur en apprentissage pendant que la règle s’applique à tous les autres (pepsi-settings(1))

pepsi-settings set alice@example.org block-language ENFORCEMENT soft

85.1.30.1.12. Voir aussi

pepsi-config(1), pepsi-stage-detect-language(1), pepsi-stage-bounce(1), pepsi-dispatch(1), pepsi-settings(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

85.1.30.1.13. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.