Politique d'importation pilotée par quota
Billet #143 : Politique d'importation pilotée par quota avec retry ciblé
Type : Fonctionnalité / Fiabilité / Contrôle des coûts
Composants concernés : code_source_simule/pipeline.py, tests/test_pipeline.py, config.ini, README.md
1. Contexte
Le pipeline ETL enrichit les données du portefeuille en appelant l'API Marketstack pour chaque ticker. Avec une limite mensuelle de 10 000 requêtes, il n'existait aucun mécanisme pour empêcher le pipeline de consommer son quota sans contrôle, ni protection contre les boucles de retry inutiles lorsque les prix étaient déjà disponibles.
De plus, l'endpoint Marketstack /v1/account pour retourner l'usage de quota en temps réel est inexistant.
2. Objectif
Implanter une politique d'importation pilotée par quota qui :
- Classifie chaque run du pipeline selon l'un de quatre modes selon l'usage du quota :
normal,eco,protectionoublocked - Bloque complètement l'enrichissement API lorsque le quota est critiquement bas
- Limite le retry à un seul passage, ciblant uniquement les tickers sans prix
- Bascule gracieusement lorsque l'endpoint de quota API est indisponible
- Permet d'ajuster les seuils sans redéploiement
3. Implémentation
3.1 — Classification du mode quota
Une classe QuotaMode classifie les runs selon trois seuils configurables (défauts : 65 / 80 / 95 %) :
| Usage | Mode | Comportement |
|---|---|---|
| < 65 % | normal |
Enrichissement complet + retry activé |
| 65–79 % | eco |
Enrichissement activé, retry désactivé |
| 80–94 % | protection |
Enrichissement activé, retry désactivé, alerte opérateur |
| ≥ 95 % | blocked |
Enrichissement annulé entièrement |
3.2 — Nouvelle tentative ciblée
En mode normal uniquement, un seul passage de nouvelle tentative enrichit les tickers sans prix après la première passe — sans jamais re-soumettre un ticker déjà enrichi.
3.3 — Compteur local de quota (repli)
Comme /v1/account n'existe pas, le pipeline maintient un compteur JSON local dans logs/marketstack_quota_usage.json. Ce compteur :
- se réinitialise automatiquement au premier appel de chaque mois
- s'incrémente à chaque appel API effectué lors de l'enrichissement
- est utilisé comme source de quota lorsque l'endpoint API est indisponible
3.4 — Seuils configurables
Tous les seuils et le chemin de log sont lus depuis config.ini. Les valeurs manquantes ou invalides retombent sur les défauts sûrs (65 / 80 / 95, logs/pipeline.log) avec un avertissement journalisé.
3.5 — Observabilité structurée
Chaque décision de quota, transition de mode, alerte opérateur et blocage d'enrichissement est écrit comme un événement JSON structuré dans logs/pipeline.log.
3.6 — Renforcements complémentaires livrés
- Passage des appels Marketstack en HTTPS pour les endpoints quota et EOD
- Confirmation de
MARKETSTACK_API_KEYcomme source unique autorisée de clé API (aucun secret de secours) - Mise à jour en parité de la documentation
README.md,docs/tests/pipeline.mdetdocs/fr/tests/pipeline.md - Validation finale des scénarios (
normal,protection,blocked) et exécution non-régressive
4. Couverture de tests
- 11 nouveaux cas de test ajoutés (tc-pipe-quota01 à tc-pipe-quota11)
- Couverture du module pipeline : 60 % → 83 %
- 49 tests passent (24 pipeline + 3 config + 22 autres)
5. Rapports d'exécution régénérés
report.xmlrégénéré depuis l'exécution complète (49 passés)report.jsonlrégénéré sur la même exécution pour la traçabilité détaillée
6. Résultat
Le pipeline opère maintenant automatiquement dans les limites de son enveloppe de quota mensuel. Les opérateurs peuvent ajuster les seuils dans config.ini sans toucher au code. Le compteur local de remplacement assure la protection même si l'endpoint de compte Marketstack est inexistant.