Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id : ADR-007 titre : Extraire la passerelle dans un processus optionnel distinct date : 2026-07-18 statut : proposé concerne :

  • ADR-002
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • crates/zeroclaw-gateway
  • crates/zeroclaw-runtime/src/rpc

ADR-007 : extraire la passerelle en tant que processus facultatif distinct

Contexte

La surface HTTP, WebSocket, webhook et tableau de bord de ZeroClaw dispose déjà d’une crate dédiée zeroclaw-gateway. L’application principale lie et démarre toujours cette crate en cours de processus derrière la fonctionnalité gateway. La frontière de crate améliore la propriété du code, mais elle ne fournit pas d’isolation de processus et ne permet pas à un opérateur d’exécuter, de redémarrer, de mettre à niveau ou d’omettre la surface web indépendamment du runtime de l’agent.

Le runtime dispose également d’une surface JSON-RPC, mais le contrat local stable complet, le transport, le modèle d’authentification, la politique de compatibilité et la supervision de processus nécessaires à une passerelle externe n’ont pas été livrés en tant que frontière prise en charge unique. Les coutures de crate et RPC actuelles constituent donc des étapes de migration utiles plutôt que la preuve que l’extraction de processus est terminée.

Les alternatives consistent soit à considérer la crate à fonctionnalités contrôlées et exécutée en interne comme l’architecture finale, soit à faire de la passerelle un processus optionnel distinct, connecté au runtime via un contrat IPC local explicite.

Décision

Nous ferons de la passerelle un processus zeroclaw-gw optionnel distinct.

Le runtime de l’agent demeure l’autorité en matière d’exécution des agents, de sessions, de mémoire, de configuration, d’outils, de politique de sécurité et d’autres états de domaine. La passerelle est responsable des protocoles HTTP externes et de streaming, de la livraison du tableau de bord, du couplage et des préoccupations liées au transport, ainsi que de l’ingestion générique de webhooks. Elle doit solliciter les opérations du runtime via le contrat IPC pris en charge, plutôt que d’accéder directement à l’état du runtime local au processus.

La limite IPC entre le runtime et la passerelle doit être authentifiée, versionnée et documentée. Le choix du transport peut varier selon la plateforme, mais la connexion par défaut doit rester locale et ne doit pas exposer silencieusement la surface de contrôle du runtime sur une interface publique.

La crate zeroclaw-gateway actuelle, en cours d’exécution et protégée par feature flag, constitue une jointure intermédiaire. Elle peut rester disponible pendant la mise en place de la parité IPC et de la prise en charge du cycle de vie des processus, mais la nouvelle architecture ne doit pas faire de l’accès direct aux composants internes du runtime une exigence permanente de la gateway.

Les opérateurs doivent pouvoir exécuter l’agent sans zeroclaw-gw. Une défaillance ou un redémarrage de la passerelle ne doit pas interrompre l’exécution d’un agent par ailleurs sain.

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

  • un binaire zeroclaw-gw pris en charge communique avec le runtime via le contrat IPC local documenté ;
  • la limite IPC couvre les capacités de passerelle requises pour l’expérience de tableau de bord et d’API prise en charge sans accès direct à l’état local du processus ;
  • L’authentification, la négociation de version, la reconnexion, l’état de santé, le démarrage et le comportement d’arrêt sont implémentés et documentés ; et
  • une distribution d’exécution prise en charge peut fonctionner sans lier ni démarrer le serveur de passerelle.

Conséquences

Conséquences positives :

  • Les déploiements sans interface et contraints peuvent se passer complètement de l’interface web.
  • Les pannes, redémarrages et mises à jour de la passerelle sont isolés de l’exécution des agents.
  • Le contrat IPC offre aux applications de bureau et autres clients locaux de confiance une limite d’intégration définie.
  • La propriété du runtime et de la passerelle devient plus facile à tester et à comprendre, car les accès inter-frontières sont explicites.

Conséquences négatives :

  • L’installation, le démarrage, l’authentification, la journalisation et le diagnostic multiprocessus sont plus complexes qu’un appel de fonction dans le même processus.
  • Le streaming et les charges utiles volumineuses doivent franchir une frontière sérialisée.
  • Une politique de compatibilité est requise dès lors que les versions du runtime et de la passerelle peuvent différer.
  • Jusqu’à ce que la parité soit atteinte, les mainteneurs doivent prendre en charge à la fois la jonction en cours de processus actuelle et la limite de processus cible.

Références