Limitation de concurrence

Certaines méthodes exposées via @frappe.whitelist() peuvent monopoliser un worker Gunicorn pendant toute leur durée d'exécution (génération de rapports complexes, requêtes analytiques lourdes, exports volumineux…). Une rafale de requêtes simultanées peut épuiser tous les workers disponibles et rendre le site complètement inaccessible.

Le décorateur @frappe.concurrent_limit() résout ce problème en limitant le nombre d'exécutions simultanées d'une méthode donnée.

Principe de fonctionnement

      
sequenceDiagram
    participant Client
    participant Gunicorn
    participant Redis
    participant Fonction

    

Techniquement, un pool de jetons est stocké dans une liste Redis. Chaque slot de concurrence autorisé correspond à un jeton dans cette liste :

• Au démarrage d'une requête, un jeton est extrait de la liste (BLPOP).
• À la fin de l'exécution (succès ou erreur), le jeton est restitué (LPUSH).
• Si aucun jeton n'est disponible avant l'expiration du délai wait_timeout, la requête reçoit une réponse 503 avec un en-tête Retry-After.

Auto-guérison après crash

En cas de crash d'un worker (le jeton n'est jamais restitué), le pool se reconstruit automatiquement grâce à une TTL d'une heure sur la clé de capacité Redis. Le site se rétablit sans intervention manuelle.

Usage

Décoration d'une méthode exposée

import frappe

@frappe.whitelist()
@frappe.concurrent_limit(limit=3)
def endpoint_couteux(*args, **kwargs):
    # traitement long...
    pass

Paramètres

Exemple avec délai d'attente personnalisé

@frappe.whitelist()
@frappe.concurrent_limit(limit=5, wait_timeout=30)
def export_rapport_annuel(annee: int):
    """Export pouvant prendre jusqu'à 20 secondes — on tolère une attente de 30 s."""
    ...

Comportement hors requête HTTP

Le décorateur est un no-op dans les contextes suivants :

• Jobs en arrière-plan (workers)
• Commandes CLI (bench execute, scripts)
• Tests automatisés

Cela évite tout blocage involontaire lors des opérations de maintenance ou de développement.

Réponse 503 et en-tête Retry-After

Lorsque le délai d'attente est dépassé, le framework renvoie automatiquement :

HTTP/1.1 503 Service Unavailable
Retry-After: 10
Content-Type: application/json

{"exc_type": "TooManyConcurrentRequests", "exception": "...", ...}

Les clients (applications front-end, intégrations tierces) peuvent lire cet en-tête pour planifier une nouvelle tentative.

Introspection : obtenir les statistiques de concurrence

Une fonction utilitaire get_stats permet de consulter l'état courant du pool pour une fonction donnée :

from frappe.concurrency_limiter import get_stats

stats = get_stats("mon_app.api.endpoint_couteux")
# Exemple de retour :
# {"capacity": 3, "available": 1, "in_use": 2}

Cela peut être utile pour des tableaux de bord de supervision ou des alertes opérationnelles.

Cas d'usage recommandés

Points d'attention

Référence technique

• Module principal : frappe/concurrency_limiter.py
• Sémaphore Redis : frappe/utils/redis_semaphore.py
• Exception levée : frappe.exceptions.TooManyConcurrentRequests
• Tests : frappe/tests/test_concurrency_limiter.py