Submissions Queue

Type de ressource : Binding Cloudflare (Queue)
Fichier source : services/form-handler/wrangler.toml, services/submission-processor/wrangler.toml
Statut : Actif

1. Vue d’ensemble

1.1. Description

Queue Cloudflare pour le traitement asynchrone des soumissions de formulaire. Le Worker form-handler (producer) envoie les soumissions validées dans la Queue, et le Worker submission-processor (consumer) traite les messages et crée des documents dans Sanity.

1.2. Objectif

• Découpler la validation du traitement asynchrone
• Fournir une résilience asynchrone sans bloquer l’utilisateur
• Permettre le retry exponentiel en cas d’erreur Sanity
• Optimiser les performances via le traitement par batch

1.3. Caractéristiques

Propriété	Valeur
Type de binding	Queue
Nom du binding	SUBMISSIONS_QUEUE
Nom de la ressource	submissions-queue-dev (dev), submissions-queue-prod (production)
Environnements	Development, Production
Workers consommateurs	form-handler (producer), submission-processor (consumer)

2. Architecture et flux

[Form Handler Worker]
     │  • Envoi de la soumission validée
     ▼
[Queue Cloudflare (submissions-queue)]
     │  • File d'attente asynchrone
     ▼
[Submission-processor Worker]
     │  • Consommation par batch (max 10)
     ▼
[Sanity CMS]
     │  • Création du document submission

2.2. Composants impliqués

Composant	Rôle	Type
form-handler	Producer (envoie les soumissions)	Worker L3
SUBMISSIONS_QUEUE	File d’attente asynchrone	Cloudflare Service
submission-processor	Consumer (traite les soumissions)	Worker L3
Sanity API	Stockage des soumissions	Service tiers

3. Configuration

3.1. Configuration Wrangler (wrangler.toml)

# services/form-handler/wrangler.toml (Producer)
[[queues.producers]]
queue = "submissions-queue-dev"
binding = "SUBMISSIONS_QUEUE"

[env.dev]
[[env.dev.queues.producers]]
queue = "submissions-queue-dev"
binding = "SUBMISSIONS_QUEUE"

[env.production]
[[env.production.queues.producers]]
queue = "submissions-queue-prod"
binding = "SUBMISSIONS_QUEUE"

# services/submission-processor/wrangler.toml (Consumer)
[[env.dev.queues.consumers]]
queue = "submissions-queue-dev"
max_batch_size = 10
max_batch_timeout = 30

[[env.production.queues.consumers]]
queue = "submissions-queue-prod"
max_batch_size = 10
max_batch_timeout = 30

3.2. Création de la ressource

# Création des Queues
wrangler queues create submissions-queue-dev
wrangler queues create submissions-queue-prod

3.3. Variables d’environnement associées

Variable	Description	Obligatoire	Valeur par défaut
ENVIRONMENT	Environnement (dev/production)	✅	dev

4. Implémentation

4.1. Interface TypeScript du binding

// Interface Env du Worker producer (form-handler)
export interface Env {
  SUBMISSIONS_QUEUE: Queue;
  ENVIRONMENT: string;
}

// Interface Env du Worker consumer (submission-processor)
export interface Env {
  SUBMISSIONS_QUEUE: Queue;
  ENVIRONMENT: string;
  SANITY_PROJECT_ID: string;
  SANITY_DATASET: string;
  SANITY_API_WRITE_TOKEN?: string;
}

4.2. Utilisation dans un Worker producteur (form-handler)

// Envoi dans la Queue
const submission = {
  name: validatedData.name,
  email: validatedData.email,
  message: validatedData.message,
  submittedAt: new Date().toISOString(),
  id: crypto.randomUUID(),
  environment: env.ENVIRONMENT,
};

await env.SUBMISSIONS_QUEUE.send(submission);

4.3. Utilisation dans un Worker consommateur (submission-processor)

export default {
  async queue(batch: MessageBatch<SubmissionMessage>, env: Env): Promise<void> {
    console.log(`Processing batch of ${batch.messages.length} submissions`);

    const sanityClient = createClient({
      projectId: env.SANITY_PROJECT_ID,
      dataset: env.SANITY_DATASET,
      apiVersion: '2024-01-01',
      token: env.SANITY_API_WRITE_TOKEN,
      useCdn: false,
    });

    for (const message of batch.messages) {
      try {
        const submission = message.body as SubmissionMessage;
        console.log(`Processing submission ${submission.id} from ${submission.email}`);

        // Create document in Sanity
        const result = await sanityClient.create({
          _type: 'submission',
          name: submission.name,
          email: submission.email,
          message: submission.message,
          status: 'pending',
          submittedAt: submission.submittedAt,
          processedAt: new Date().toISOString(),
        });

        console.log(`Successfully stored submission ${submission.id} in Sanity with ID: ${result._id}`);

        // Acknowledge message
        message.ack();

      } catch (error) {
        console.error(`Failed to process submission:`, error);

        // Retry with exponential backoff
        message.retry({
          delaySeconds: Math.min(60, Math.pow(2, batch.messages.indexOf(message))),
        });
      }
    }
  },
};

5. Cas d’usage spécifiques

5.1. Queue : Fallback asynchrone pour formulaires

Contexte : Le Worker form-handler utilise une Queue pour traiter les soumissions de formulaire de manière asynchrone.

Configuration :

• Nom de la Queue : submissions-queue-dev (dev), submissions-queue-prod (production)
• Binding : SUBMISSIONS_QUEUE
• Batch size : 10 messages
• Batch timeout : 30 secondes
• Rationale : Résilience asynchrone sans bloquer l’utilisateur

Flux :

1. User soumet le formulaire via Astro
2. Astro envoie vers /api/submit
3. /api/submit délègue à form-handler
4. form-handler valide via Zod
5. form-handler envoie dans la Queue
6. submission-processor consomme la Queue
7. submission-processor crée le document Sanity

6. Sécurité et accès

6.1. Contrôle d’accès

Binding	Accès	Rationale
SUBMISSIONS_QUEUE	Workers uniquement	Pas d’accès direct depuis le client

6.2. Règles de sécurité

• ✅ Les bindings sont accessibles uniquement depuis les Workers (pas depuis le navigateur)
• ✅ Les Queues ne sont pas accessibles publiquement (Workers uniquement)

6.3. Rotation des secrets

Non applicable - aucun secret n’est utilisé dans ce binding.

7. Performance et limites

7.1. Limites par type de binding

Binding	Limite	Rationale
Queue	5 000 messages/s, 10 MB max par message	Quota Cloudflare

7.2. Optimisations appliquées

• ✅ Utiliser les Queues pour le traitement asynchrone (évite les timeouts)
• ✅ Traitement par batch (max 10 messages)
• ✅ Retry exponentiel pour les erreurs (max 60s)

7.3. Coûts

Binding	Modèle de coût	Estimation mensuelle
Queue	$0.40/1M messages	~$1-2

8. Monitoring et observabilité

8.1. Métriques clés

Non implémenté - aucune métrique ou alerte n’est configurée.

8.2. Commandes de debug

# Inspection Queue
wrangler queues info submissions-queue-dev

# Logs en temps réel
wrangler tail form-handler
wrangler tail submission-processor

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
“Binding not found”	Binding mal configuré dans wrangler.toml	Vérifier la configuration et redéployer
“Queue full”	Consommateur trop lent	Augmenter max_batch_size ou ajouter des consommateurs
Messages non consommés	Consumer non déployé	Vérifier le déploiement de submission-processor

9.2. Tests manuels

# Test Queue (envoi manuel via curl)
curl -X POST http://localhost:8789/test-direct \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@example.com","message":"Test message"}'

10. Bonnes pratiques

10.1. Architecture

• ✅ Utiliser les Queues pour le traitement asynchrone (formulaires, webhooks)
• ✅ Séparer les queues par environnement (production, staging)
• ✅ Documenter les bindings dans ce fichier

10.2. Code

• ✅ Typer strictement les bindings dans l’interface Env
• ✅ Gérer les erreurs de manière explicite (try/catch)
• ✅ Logger les opérations critiques pour l’audit
• ✅ Utiliser le retry exponentiel pour les erreurs temporaires

10.3. Performance

• ✅ Utiliser les Queues pour éviter les timeouts
• ✅ Traitement par batch pour optimiser les performances
• ✅ Surveiller les métriques de performance (latence, débit)

10.4. Sécurité

• ✅ Ne jamais exposer les bindings côté client
• ✅ Les Queues ne sont pas accessibles publiquement

11. Évolutions et roadmap

11.1. Améliorations planifiées

• Configuration de monitoring (métriques, alertes)
• Ajout d’une Dead Letter Queue (DLQ) pour les messages échoués
• Ajout de métriques de profondeur de queue

11.2. Limitations connues

• ❌ Les Queues ont une limite de 10 MB par message
• ❌ Pas de Dead Letter Queue (DLQ) configurée
• ❌ Pas de monitoring configuré

12. Ressources liées

• Documentation Cloudflare Queues : Getting Started
• Workers consommateurs :
  • services/form-handler/
  • services/submission-processor/
• Fichiers concernés :
  • services/form-handler/wrangler.toml
  • services/submission-processor/wrangler.toml
  • Configuration Dashboard Cloudflare → Queues

13. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale	Devin