Submissions Queue

Documentation technique

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`)1/2

# 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"

3.1. Configuration Wrangler (`wrangler.toml`)2/2

# 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)1/2

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

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 formulaires1/2

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

5.1. Queue : Fallback asynchrone pour formulaires2/2

Flux :

User soumet le formulaire via Astro
Astro envoie vers /api/submit
/api/submit délègue à form-handler
form-handler valide via Zod
form-handler envoie dans la Queue
submission-processor consomme la Queue
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

Submissions Queue

Submissions Queue

1. Vue d’ensemble

1.1. Description

1.2. Objectif

1.3. Caractéristiques

2. Architecture et flux

2.2. Composants impliqués

3. Configuration

3.1. Configuration Wrangler (wrangler.toml)1/2

3.1. Configuration Wrangler (wrangler.toml)2/2

3.2. Création de la ressource

3.3. Variables d’environnement associées

4. Implémentation

4.1. Interface TypeScript du binding

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

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

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

5. Cas d’usage spécifiques

5.1. Queue : Fallback asynchrone pour formulaires1/2

5.1. Queue : Fallback asynchrone pour formulaires2/2

6. Sécurité et accès

6.1. Contrôle d’accès

6.2. Règles de sécurité

6.3. Rotation des secrets

7. Performance et limites

7.1. Limites par type de binding

7.2. Optimisations appliquées

7.3. Coûts

8. Monitoring et observabilité

8.1. Métriques clés

8.2. Commandes de debug

9. Débogage et troubleshooting

9.1. Problèmes courants

9.2. Tests manuels

10. Bonnes pratiques

10.1. Architecture

10.2. Code

10.3. Performance

10.4. Sécurité

11. Évolutions et roadmap

11.1. Améliorations planifiées

11.2. Limitations connues

12. Ressources liées

13. Historique des modifications

3.1. Configuration Wrangler (`wrangler.toml`)1/2

3.1. Configuration Wrangler (`wrangler.toml`)2/2