ADR: Utilisation de Cloudflare Queue pour le traitement asynchrone des formulaires

Documentation technique

Statut : Accepté
Date : 2026-09-16
Auteur : Devin

1. Contexte et Problématique1/2

Le formulaire de contact du site doit être capable de traiter les soumissions de manière fiable et performante. L’architecture de la couche L3 (Backend) repose sur Cloudflare Workers, qui ont des limites de ressources (RAM, CPU time) et ne peuvent pas bloquer l’utilisateur pendant des traitements potentiellement longs (ex: envoi vers un CRM, création de documents Sanity).

1. Contexte et Problématique2/2

Les exigences sont :

Réponse immédiate à l’utilisateur (pas de timeout)
Résilience en cas de panne de services tiers (Sanity, CRM)
Scalabilité pour gérer les pics de soumissions
Traitement asynchrone sans bloquer le frontend

2. Décision Architecturale

Nous décidons d’utiliser Cloudflare Queue pour découpler la validation des soumissions de leur traitement asynchrone.

L’architecture adoptée est la suivante :

Worker form-handler (Producer) : Valide les données via Zod, crée un objet de soumission avec métadonnées, et l’envoie dans la Queue.
Queue Cloudflare (submissions-queue) : Stocke les soumissions en file d’attente asynchrone.
Worker submission-processor (Consumer) : Consomme les messages de la Queue par batch (max 10), crée les documents dans Sanity, et gère les erreurs avec retry exponentiel.

3. Justification du choix

3.1. Pourquoi Cloudflare Queue ?1/2

Découplage des responsabilités : La validation (form-handler) est séparée du traitement (submission-processor), permettant une maintenance facilitée.
Résilience asynchrone : En cas de panne de Sanity ou du CRM, les soumissions restent dans la Queue et seront réessayées automatiquement.

3.1. Pourquoi Cloudflare Queue ?2/2

Performance utilisateur : L’utilisateur reçoit une réponse immédiate (success/400) sans attendre le traitement complet.
Scalabilité : Cloudflare Queue absorbe les pics de trafic sans saturation, avec un traitement par batch optimisé.
Retry exponentiel : Le système de retry intégré permet de gérer les erreurs temporaires sans code complexe.

3.2. Pourquoi pas d’autres approches ?

Traitement synchrone : Exclu car bloquerait l’utilisateur et pourrait timeout les Workers.
Worker direct vers Sanity : Exclu car aucune résilience en cas de panne Sanity.
Base de données intermédiaire : Exclu car Cloudflare Queue est plus adapté au pattern message-based et évite la gestion d’une DB supplémentaire.

4. Conséquences de la décision

Effets Positifs (Avantages)

Réponse immédiate : L’utilisateur reçoit une confirmation en < 100ms, améliorant l’UX.
Résilience automatique : Les erreurs Sanity sont gérées par retry exponentiel (max 60s).
Traitement par batch : Le consommateur traite jusqu’à 10 messages par batch, optimisant les coûts et performances.
Observabilité : Chaque soumission a un ID unique pour le traçage.

Effets Négatifs (Inconvénients & Risques)

Complexité additionnelle : Nécessite de gérer deux Workers (producer et consumer) au lieu d’un seul.
Pas de Dead Letter Queue (DLQ) : Les messages qui échouent définitivement ne sont pas déplacés vers une DLQ (à implémenter si nécessaire).
Délai de traitement : Le traitement n’est pas instantané (quelques secondes selon la charge de la Queue).
Observabilité limitée : Pas de monitoring configuré pour surveiller la profondeur de la Queue.

5. Alternatives Exclues

Traitement synchrone dans form-handler : Exclu car bloquerait l’utilisateur et pourrait timeout.
Worker direct vers Sanity sans Queue : Exclu car aucune résilience en cas de panne.
Base de données intermédiaire (D1) : Exclu car Cloudflare Queue est plus adapté au pattern message-based et évite la gestion d’une DB supplémentaire.
Webhook vers service tiers : Exclu car ajouterait une dépendance externe et une complexité inutile.