SOP Fan-In : Vue d’ensemble
Un fan-in est une source d’événements externe qui lance les exécutions de SOP. Chaque source transmet des événements au moteur SOP via dispatch_sop_event, qui associe chaque événement aux déclencheurs de chaque SOP chargé et lance les exécutions pour celles qui correspondent.
Une instance ZeroClaw peut lier plusieurs fan-ins à la fois : un topic MQTT, un chemin de système de fichiers et une clé de routage AMQP peuvent tous alimenter le même moteur sans processus séparés. Chaque source dispose d’un guide dédié ci-dessous.
Comment fonctionne le dispatch
- Un seul chemin de matcher : un seul matcher évalue chaque type de trigger, de sorte que la correspondance se comporte de la même manière quelle que soit la source.
- Audit de début d’exécution : les exécutions démarrées sont persistées via
SopAuditLogger. - Sécurité en mode headless : dans les contextes hors boucle d’agent,
process_headless_resultsjournalise les actionsExecuteStepcomme en attente au lieu de les exécuter silencieusement. - Entrée non fiable : le texte du sujet et du payload sont limités, normalisés, filtrés par prompt-guard et encadrés avant d’atteindre le contexte du modèle.
Sources
Chaque type de déclencheur SOP, ses champs et son statut de dispatch, projetés directement depuis le registre SopTrigger :
| Type | Champs | Notes |
|---|---|---|
mqtt | topic, condition optionnel | Arrivée du message MQTT. En direct : transmis par l’écouteur MQTT. |
webhook | path | Requête HTTP entrante. En production : routes de passerelle /sop/* et routes /webhook donnant la priorité au SOP. |
cron | expression | Déclenchement basé sur le temps. En direct : distribué par le tick de maintenance SOP (chemins daemon / démarrage de canal). |
peripheral | board, signal, condition optionnelle | Signal matériel. Défini et apparié, mais aucun écouteur périphérique ne l’alimente. |
filesystem | path, optionnel condition, optionnel events | Filesystem modification. Live : fourni par le surveillant de système de fichiers. |
calendar | calendar_source, optionnel calendar_ids, optionnel condition | État de l’événement de calendrier. Défini et correspondant, mais aucun poller ne l’alimente en temps réel. |
channel | channel, optionnel alias, optionnel condition | Message entrant ou événement forge/platform sur un canal configuré (telegram, discord, slack, git, …). Live : diffusé par l’orchestrateur de canal lorsque le dispatch SOP du canal est activé. Le producteur forge Git définit un sujet d’événement sous la forme <channel>.<alias>:<event_type> et place event_type dans la charge utile, afin qu’une condition définie filtre les événements forge par type sans nécessiter de seconde forme de déclencheur. |
manual | aucun | Exécution initiée par l’agent via l’outil sop_execute. Pas un fan-in externe. |
amqp | routing_key, optionnel condition | Livraison AMQP. En direct : livrée par le consommateur AMQP dans un mode de dispatch SOP. |
Chaque source dispose d’un guide dédié dans la barre latérale. Les sources en direct (transmises par un écouteur en cours d’exécution ou une requête authentifiée via la passerelle) lancent des exécutions à mesure que les événements arrivent ; les déclencheurs cron sont distribués par le cycle périodique de maintenance SOP du daemon ; les exécutions initiées par un agent démarrent depuis l’intérieur d’un tour d’agent via sop_execute ; les autres sources définies mais non connectées (périphérique et calendrier) sont validées et mises en correspondance, mais aucune source d’événements en direct ne les achemine encore vers le répartiteur.
Valeurs par défaut de sécurité
| Inquiétude | Mécanisme |
|---|---|
| Authentification des webhooks | Authentification bearer de pairing du Gateway, avec gateway.webhook_secret/X-Webhook-Secret facultatifs ; /sop/* et /webhook utilisent le même limiteur de débit. Au moins un contrôle doit être configuré pour la distribution SOP, et tous les contrôles configurés doivent réussir. Les secrets d’alias distincts de [channels.webhook] n’autorisent jamais ces routes. |
| Protection contre le rejeu des webhooks | Clé X-Idempotency-Key facultative, avec un espace de noms par chemin SOP ainsi que des espaces de noms distincts pour /sop/* et /webhook. Les clés sont réservées avant le déclenchement et signifient qu’il y aura au plus une tentative, sans prouver qu’une exécution précédente a commencé |
| Transport MQTT | mqtts:// avec use_tls = true pour le transport TLS |
| Filesystem racines | Racines étendues (/, /home, /etc, /var, /proc, /sys, /dev, /tmp) refusées lors de la validation de la configuration à moins que allow_broad_roots ; les globs d’inclusion/exclusion définissent la portée des événements |
| Filesystem liens symboliques | Les chemins d’événements de liens symboliques sont rejetés avant toute lecture de métadonnées, de hachage ou de contenu par défaut ; follow_symlinks = true active l’option mais exige toujours que la cible canonique se résolve à l’intérieur d’une racine surveillée |
| Entrée du déclencheur non fiable | Les textes de topic et de payload sont plafonnés, normalisés, filtrés par le prompt-guard et encadrés avant le contexte du modèle |
| Bloc déclencheur non sécurisé | untrusted_input_guard = "block" refuse les événements non fiables non sécurisés avec BlockedUnsafe ; par défaut warn audite et autorise |
| Validation de Cron | Les expressions cron invalides échouent de manière sécurisée lors de l’analyse et de la construction du cache. |
| Répartition headless | Les appelants headless journalisent la progression de l’exécution au lieu d’exécuter automatiquement ExecuteStep |
Dépannage
| Symptôme | Cause probable | Corriger |
|---|---|---|
| SOP ne démarre jamais à partir d’une source en direct | non-correspondance du motif de déclenchement ou une condition en échec | Vérifier que le motif de déclenchement correspond à l’événement livré ; vérifier la condition par rapport à la charge utile |
| SOP démarré mais une étape ne s’est pas exécutée | déclencheur headless sans boucle d’agent active | Exécutez une boucle d’agent pour ExecuteStep, ou concevez l’exécution pour qu’elle se mette en pause sur les approbations |
| Le déclencheur de webhook ne se déclenche jamais | incompatibilité du chemin de déclenchement exact, sous-système SOP indisponible ou authentification refusée | Exécutez zeroclaw daemon avec sop.sops_dir configuré, faites correspondre exactement le chemin complet de la requête et fournissez les en-têtes bearer/secret configurés |
| Le déclencheur du périphérique ou du calendrier ne se déclenche jamais | source d’événements non raccordée au répartiteur | Utilisez une source en direct (Webhook, MQTT, Filesystem, AMQP) ou démarrez l’exécution avec sop_execute |
| Le déclencheur Cron ne se déclenche jamais | cycle de maintenance non exécuté (ni zeroclaw daemon ni zeroclaw channel start ; le lancement autonome de gateway start ne l’exécute pas), sops_dir non défini/vide, ou maintenance_interval_secs = 0 | Exécutez zeroclaw daemon (ou zeroclaw channel start) avec sop.sops_dir défini sur une valeur non vide (non défini par défaut ; la valeur documentée est shared/sops) et sop.maintenance_interval_secs différent de zéro (valeur par défaut : 60) |
Voir aussi
- Syntaxe : le format complet de
SOP.tomletSOP.md - Comment les SOP s’exécutent
- Canaux : Vue d’ensemble: le côté transport de MQTT, du système de fichiers et d’AMQP