Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-006 title: Faire des plugins d’exécution la cible des canaux optionnels date: 2026-07-18 status: proposed relates-to:

  • ADR-002
  • ADR-009
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8850
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • wit/v0/channel.wit
  • crates/zeroclaw-plugins/src/wasm_channel.rs

ADR-006 : Faire des plugins d’exécution la cible pour les canaux optionnels

Contexte

ZeroClaw compile actuellement de nombreuses intégrations de messagerie derrière des feature flags Cargo. Cela permet d’exclure le code des canaux inutilisés des builds sélectionnés, mais l’ajout ou la mise à jour d’une intégration optionnelle nécessite toujours de recompiler l’application. Cela maintient également les dépendances spécifiques aux fournisseurs et le rythme de publication couplés au binaire principal.

Le modèle de composant WIT définit désormais un monde channel-plugin, et l’adaptateur hôte implémente le trait Channel partagé pour un composant WASM. La découverte et l’adaptateur côté hôte existent, mais un démon en cours d’exécution ne construit pas encore les plugins de canal découverts ni ne fournit tous les écouteurs par fournisseur dont ils ont besoin. Les plugins d’exécution décrivent donc une cible réelle avec un chemin opérationnel incomplet, et non le modèle de packaging actuel.

Les alternatives sont de conserver un hybride compilé/exécution permanent, d’exiger une migration immédiate tous canaux, ou de faire des plugins d’exécution la cible par défaut tout en autorisant des exceptions natives explicites pour les capacités que la frontière de plugin ne peut pas encore prendre en charge.

Décision

Nous ferons des plugins installables à l’exécution le modèle cible d’empaquetage et d’exécution pour les canaux optionnels.

Un canal optionnel devrait migrer d’une fonctionnalité compilée vers un plugin d’exécution lorsque la frontière hôte WIT/WASI peut fournir ses capacités requises en matière de réseau, d’ingress par webhook ou par sondage, de configuration, de secrets, de médias, d’interaction et de cycle de vie, sans affaiblir le modèle de sécurité de l’exécution.

Les implémentations natives ne peuvent rester pendant la transition qu’en tant qu’exceptions explicites fondées sur les capacités. Une exception doit identifier la capacité hôte manquante ou la contrainte opérationnelle, le chemin de code natif qui en dépend, ainsi que la condition permettant la migration. L’identité du fournisseur, les indicateurs de fonctionnalité existants ou l’ancienneté de l’implémentation ne constituent pas à eux seuls des motifs d’exception permanente.

Le runtime est responsable de la découverte des plugins, de l’application des permissions, de la distribution de la configuration, de la supervision des listeners, du reporting de santé et de l’adaptation au contrat Channel partagé. Un plugin de canal est responsable du comportement protocolaire spécifique à la plateforme et de la traduction des messages. L’entrée hébergée par la passerelle peut router du trafic HTTP générique, mais elle ne doit pas devenir le propriétaire permanent de la logique de canal spécifique au fournisseur.

Le ticket #8850 gère le séquencement de la migration, le suivi des lacunes de capacités et la limite de retrait des canaux optionnels compilés. Cet ADR ne détermine pas quel canal migre en premier ni n’exige la suppression d’une implémentation native fonctionnelle avant que son remplacement d’exécution ne dispose d’un support opérationnel équivalent.

Cet ADR reste proposé jusqu’à ce que toutes ces conditions soient remplies :

  • les plugins de canaux découverts peuvent être configurés et enregistrés par un démon en cours d’exécution ;
  • une distribution prise en charge peut installer, configurer et exécuter un plugin de canal sans reconstruction personnalisée ;
  • le trafic du listener entrant ou du webhook peut atteindre le plugin sous la propriété d’un runtime supervisé ;
  • au moins un canal compilé optionnel existant a été migré de bout en bout ; et
  • le processus d’exception et de compatibilité est documenté pour les canaux qui ne peuvent pas encore migrer.

Conséquences

Conséquences positives :

  • Les utilisateurs peuvent ajouter et mettre à jour des intégrations optionnelles sans recompiler ZeroClaw.
  • Les dépendances des fournisseurs et le rythme de publication peuvent être dissociés du binaire principal.
  • Les implémentations de canaux partagent une frontière d’exécution soumise à permissions et un contrat de trait visible par l’appelant.
  • Les exceptions natives restent examinables, car elles sont liées à des lacunes de fonctionnalités explicitement identifiées plutôt que de devenir un second modèle permanent et indéfini.

Conséquences négatives :

  • L’hôte doit superviser les écouteurs à longue durée de vie et préserver la santé des canaux, l’interaction, les médias et le comportement de configuration au-delà de la limite du composant.
  • Certaines plateformes peuvent rester natives pendant que les capacités WIT/WASI arrivent à maturité, de sorte que la transition comporte toujours deux chemins de packaging.
  • La distribution, la compatibilité, la signature et la révocation des plugins font partie intégrante du cycle de vie opérationnel du canal.
  • La migration nécessite une preuve de parité ; la simple compilation d’un composant de canal ne suffit pas à retirer son implémentation native.

Références