Quotas à compartiments à jetons (token-bucket) à portée de l’appelant avec classes distinctes 429 et 503, Retry-After en cas de limitation, fenêtres de rafale versus soutenue, et partage équitable entre locataires sans jamais divulguer l’identité d’un voisin.
Statut du package : contexte de référence prêt pour revue humaine. Le contrat et les scénarios de test sont complets, mais aucune affirmation n’est faite qu’une implémentation adoptante les ait validés.
Décision
Les API HTTP publiques et partenaires n’admettent une requête qu’après qu’un compartiment à jetons à portée de l’appelant ait accordé un jeton. Le trafic authentifié est indexé par principal et locataire. Les routes publiques non authentifiées utilisent une classe anonyme documentée issue d’une plage réseau hachée plus la classe de route, jamais un identifiant de locataire voisin. Le rafraîchissement en rafale et soutenu sont des valeurs de profil indépendantes. L’épuisement du quota personnel est une limitation client ; l’épuisement de l’admission partagée ou la défaillance du magasin de limiteurs est une classe de service. L’identité du voisin et le budget restant n’apparaissent jamais dans les en-têtes, corps ou journaux visibles par l’appelant.
Portée
- Admission pour les classes de route public-apis et partner-apis dans le profil d’adoption.
- Identité du quota, rafraîchissement du compartiment à jetons, Retry-After, équité des fragments, et clés de limiteur pouvant divulguer un autre locataire.
Hors de ce bloc
- Ouverture de circuit pour une dépendance en échec (package de disjoncteur associé).
- Arithmétique de délai restant (package de propagation de délai associé).
Contrat
- L’identité du limiteur est le principal et locataire authentifiés, ou une classe anonyme documentée, jamais un identifiant brut de locataire voisin.
- Les jetons de rafale et le rafraîchissement soutenu sont évalués indépendamment ; la rafale est autorisée uniquement tant que cette identité dispose encore de crédit de rafraîchissement.
- L’épuisement du quota personnel retourne HTTP 429 avec un code catalogue et un Retry-After calculé à partir du compartiment de cet appelant.
- L’épuisement de la capacité partagée ou la défaillance du magasin de limiteurs retourne HTTP 503 avec un code catalogue différent.
- Sur un fragment partagé, aucun locataire ne peut occuper plus que la part de profil des créneaux d’admission partagée dans une fenêtre.
- Les réponses et journaux visibles par l’appelant omettent les identifiants des autres locataires, les quotas restants, et les statistiques de route des voisins.
Guide d’implémentation
- Indexer les compartiments par principal et classe de route ; ne pas indexer le trafic authentifié uniquement par IP. Décrémenter atomiquement pour éviter que des mises à jour perdues accordent une rafale supplémentaire.
- Lorsque le magasin de limiteurs est inaccessible, échouer fermé vers la classe d’erreur de capacité plutôt que d’admettre un trafic illimité.
Gestion des échecs et protections
- Les clients doivent distinguer la limitation personnelle de la capacité du fournisseur. Si Retry-After ne peut être calculé pour cet appelant, omettre l’en-tête plutôt que de copier un délai d’un voisin.
- Le rafraîchissement du compartiment utilise l’heure du magasin de limiteurs, pas l’en-tête Date du client.
Vérification et exploitation
- Faire fonctionner deux locataires sur un même fragment et prouver que l’un ne peut pas affamer l’autre au-delà de la part de profil, et que les corps 429 n’incluent jamais l’identifiant de l’autre locataire.
- Alerter lorsque les rejets de la classe capacité dépassent le budget d’erreur du profil.
Les exemples à exécution apparente dans ce package sont des fixtures et contrats d’acceptation. Exécutez
python tools/validate.py depuis la racine de la collection pour vérifier la structure et les métadonnées du package ; puis
implémentez et exécutez les scénarios dans le dépôt cible.
Hypothèses d’adoption
- Les noms et valeurs numériques dans
example.yamlsont un profil d’adoption, pas des valeurs par défaut universelles. - L’équipe adoptante doit mapper les acteurs, classes de données, vocabulaire d’erreur, et propriété à son système.