# Rapport d'Analyse Technique : Idempotence du Regent SDK
**Statut :** Analyse Critique d'Architecture
**Écosystème :** Rust (Gestion de Configuration & Automatisation)
**Date :** Août 2026
---
## Introduction
Ce rapport évalue les garanties d'**idempotence** fournies par le framework `regent-sdk`. L'idempotence (la propriété d'une opération à produire le même état final qu'elle soit exécutée une ou plusieurs fois) est indispensable pour la stabilité des infrastructures.
L'analyse de la séparation entre l'inventaire (`Inventory`) et l'état attendu (`ExpectedState`) met en évidence plusieurs lacunes structurelles face aux effets de bord des systèmes d'exploitation réels.
---
## 1. Module de Gestion des Secrets (Secrets Management)
Le SDK prend en charge la récupération dynamique de données sensibles via des backends externes (AWS Secrets Manager, HashiCorp Vault, variables d'environnement).
* **Lacune identifiée :** Absence de verrouillage temporel ou de versioning strict par défaut lors de la phase de remédiation.
* **Mécanisme de défaillance :**
1. Le moteur exécute l'évaluation de conformité (`ComplianceAssessment`).
2. Une rotation automatique du secret survient sur le coffre-fort externe juste après la vérification.
3. L'étape d'application (`apply_remediation`) injecte alors une valeur obsolète ou hybride.
* **Impact sur l'idempotence :** Rejouer la tâche produit un état système différent et imprévisible selon le timing de la rotation.
---
## 2. Attribut de Présence de Fichier (`!FilePresent`)
Cet attribut valide et impose la présence d'un fichier sur une machine cible.
* **Lacune identifiée :** Absence de mutation atomique des fichiers et vulnérabilité lors de la résolution des liens symboliques.
* **Mécanisme de défaillance :**
* Si le chemin cible (ex: `/etc/myapp/config.toml`) est malicieusement ou accidentellement remplacé par un lien symbolique pointant vers un fichier système critique entre deux exécutions, la remédiation va écraser le fichier pointé au lieu de recréer l'élément attendu.
* Si une panne réseau ou une panique de thread Rust survient au milieu de l'écriture du fichier, le fichier reste tronqué.
* **Impact sur l'idempotence :** Une exécution ultérieure détectera un fichier "présent" (le fichier existe sur le disque) mais structurellement invalide, car le moteur ne recalcule pas systématiquement l'empreinte cryptographique (SHA-256) du contenu complet à chaque passage.
---
## 3. Attributs de Permissions Globaux (`EnsureCorrectPermissions`)
Ce module gère l'application des droits d'accès (`chmod`/`chown`) sur les fichiers et dossiers.
* **Lacune identifiée :** Utilisation de masques de permissions relatifs et absence de gestion déterministe des permissions héritées.
* **Mécanisme de défaillance :** Modifier des droits de manière idempotente exige des valeurs absolues (ex: `0644`). Si le moteur applique des masques relatifs (ex: `g+w`) ou s'il traite récursivement des répertoires contenant des points de montage réseau dynamiques ou virtuels (NFS, FUSE), l'environnement sous-jacent modifie les métadonnées de manière asynchrone.
* **Impact sur l'idempotence :** L'opération réapplique des modifications et altère l'état du système à chaque passage, sans jamais converger vers un état fixe.
---
## 4. Moteur de Concurrence Asynchrone (`tokio` + `StreamExt`)
Le framework permet de distribuer des vagues de tâches d'automatisation en parallèle pour gérer de grands volumes d'hôtes.
* **Lacune identifiée :** Situations de compétition (Race Conditions) sur les ressources partagées d'un même hôte en raison de l'absence de verrous distribués.
* **Mécanisme de défaillance :** Si deux tâches distinctes s'exécutant dans des threads asynchrones différents ciblent simultanément le même nœud pour modifier le même service ou fichier, il n'existe aucun mécanisme de verrouillage exclusif (Locking) sur l'agent distant. Les deux workers constatent le défaut de conformité en même temps et tentent d'écraser la configuration simultanément.
* **Impact sur l'idempotence :** L'état final de la machine dépend uniquement de l'ordonnancement réseau (non-déterminisme total).
---
## 5. Sérialisation et Exécution Distante (`RegentTask`)
Le SDK sérialise des objets de tâche (via `serde`) pour les envoyer à travers des bus de messages (gRPC, RabbitMQ).
* **Lacune identifiée :** Absence d'une clé d'idempotence applicative (Idempotency Key) persistante dans la structure du protocole.
* **Mécanisme de défaillance :** En informatique distribuée, les pannes réseau provoquent fréquemment le rejeu de messages par le broker (duplication "at-least-once"). Si un worker reçoit deux fois la même `RegentTask` parce que l'acquittement (ACK) a échoué, il réexécute l'action. Si l'action consiste à "ajouter une ligne de configuration à la fin d'un fichier" (au lieu de remplacer le fichier entier), l'action dupliquée insère la ligne deux fois.
* **Impact sur l'idempotence :** Le rejeu d'un message réseau valide corrompt la configuration cible.
---
## Recommandations pour le SDK
Pour immuniser le framework contre ces défaillances et garantir une idempotence mathématique, trois axes doivent être implémentés :
1. **Validation par Approche d'État (State-driven) :** Remplacer les vérifications de présence superficielles par un contrôle systématique des empreintes numériques (Hashes de contenu).
2. **Mécanisme de Lock Exclusif :** Instaurer un système de verrouillage sur la ressource cible pour interdire à deux workers parallèles de modifier le même composant simultanément.
3. **Jetons d'Idempotence (UUID) :** Forcer l'inclusion d'un identifiant de transaction unique lors de la sérialisation des `RegentTask` pour permettre aux nœuds d'exécution de rejeter instantanément les requêtes dupliquées.
