Aller au contenu principal

ADR-0155 : Plans du worker, operation_id des opérations longues et compensation des actions externes

Contexte​

La référence d'architecture demande des unités de déploiement audit-plane, soc-plane et telemetry-plane (A5.2) mises à l'échelle séparément (B6.2), un operation_id pour chaque opération longue afin de la suivre, d'en lire le résultat et d'éviter les doublons (B6.3), et des compensations pour les actions sur systèmes externes (B13.5). Le worker du Control Plane exécutait tous les jobs dans un seul déploiement, le Control Plane renvoyait l'identifiant de la ressource suivie et n'acceptait Idempotency-Key que sur les runs et les approbations, et une action externe validée puis annulée n'avait pas d'action inverse.

Décision​

  • python -m eai.worker --plane audit|soc|telemetry|core n'exécute que les jobs de ce plan (eai.worker.PLANES ; core prend les autres) sous son propre verrou consultatif (EAI_WORKER_LOCK_KEY + décalage du plan). Le chart Helm crée, avec worker.planes.enabled, un déploiement par plan avec ses ressources et ses réplicas ; les politiques réseau et le PodMonitor sélectionnent le label eai.io/workload-class: control-plane-worker, porté par chaque plan. Sans l'option, un seul worker exécute tout (comportement inchangé).
  • Le domaine eai.domains.operations enregistre chaque création longue (runs, runs d'évaluation et de red team, installations et mises à jour du marketplace, réindexation d'une base de connaissance, synchronisation d'un connecteur, génération vidéo) dans eai.operations (V188). La réponse porte Operation-Id et Operation-Location ; GET /v1/operations/{operation_id} rend la réponse acceptée, la ressource suivie et son état vivant, lu par la route de la ressource avec les identifiants de l'appelant. Avec Idempotency-Key, un nouvel essai du même principal avec le même corps rejoue la première réponse sans réexécuter ; un autre corps reçoit 409 idempotency_conflict, un essai pendant le traitement reçoit 409 operation_in_progress. Une requête refusée ne laisse aucune opération.
  • eai.domains.soc.transactions.compensate et compensate_run annulent une action externe validée par son action inverse enregistrée (payment.create vers payment.refund...), au plus une fois : clé compensation:<clé>:<essai>, intention durable (compensating, V185) avant l'appel, compensated après ; un résultat inconnu attend le rapprochement du SOC, jamais un nouvel essai aveugle.

Conséquences​

Chaque plan garde une seule réplique active (verrou consultatif) : les réplicas supplémentaires sont des secours. L'ingestion de télémétrie par l'API suit l'HPA du Control Plane. Activer les plans sur une installation existante ne change pas le sélecteur du worker principal.

Preuves​

services/control-plane/tests/test_worker_planes.py, services/control-plane/tests/test_operations.py, services/control-plane/tests/test_side_effect_compensation.py, et dans les SDK sdks/python/tests/test_operations.py, sdks/typescript/packages/sdk/test/operations.test.ts, sdks/go/operations_test.go, sdks/java/enterprise-ai-java/src/test/java/io/enterpriseai/OperationsClientTest.java.