ADR: Endpoint /test-direct pour le développement local

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

1. Contexte et Problématique

Le Submission Processor Worker traite les soumissions de formulaire depuis la Cloudflare Queue et crée des documents Sanity. Pour le développement local, il est nécessaire de tester directement la création de documents Sanity sans passer par la Queue.

Problèmes :

Développement local : Il est difficile de tester la création de documents Sanity en local sans un environnement Cloudflare complet.
Debugging : Les erreurs de création de documents Sanity sont difficiles à déboguer via la Queue.
Isolation : Pour tester uniquement la logique de création de documents Sanity, il faut isoler du traitement de Queue.

2. Décision Architecturale

Nous décidons d’ajouter un endpoint /test-direct au Submission Processor Worker pour le développement local :

// POST /test-direct
POST http://localhost:8789/test-direct
Content-Type: application/json

{
  "id": "uuid",
  "name": "Test User",
  "email": "test@example.com",
  "message": "Test message",
  "submittedAt": "2026-09-16T12:00:00Z",
  "environment": "local"
}

Le endpoint /test-direct :

Bypass la Queue
Crée directement un document Sanity de type submission
Est disponible uniquement en développement local
Utilise les mêmes credentials Sanity que le traitement normal

3. Justification du choix

3.1. Pourquoi un endpoint de test ?

Développement local : Permet de tester la création de documents Sanity en local sans Cloudflare.
Debugging : Facilite le debugging des erreurs de création de documents Sanity.
Isolation : Permet de tester uniquement la logique de création de documents Sanity.
Rapidité : Permet de tester rapidement sans passer par la Queue.

3.2. Pourquoi pas utiliser la Queue en local ?

Complexité : Configurer Cloudflare Queue en local est complexe.
Lenteur : Le passage par la Queue ajoute de la latence.
Surcharge : Pour tester uniquement la création de documents Sanity, la Queue est inutile.

4. Conséquences de la décision

Effets Positifs (Avantages)

Développement local : Facilite le développement et le test en local.
Debugging : Permet de déboguer rapidement les erreurs de création de documents Sanity.
Isolation : Permet de tester uniquement la logique de création de documents Sanity.
Rapidité : Permet de tester rapidement sans passer par la Queue.

Effets Négatifs (Inconvénients & Risques)

Exposition accidentelle : Si l’endpoint est exposé en production, il pourrait être utilisé de manière abusive.
Consistance : Le endpoint /test-direct ne reproduit pas exactement le chemin de production (via Queue).
Maintenance : Il faut maintenir le endpoint /test-direct en plus du traitement normal.

5. Alternatives Exclues

Utiliser uniquement la Queue en local : Exclu car complexe et lent.
Créer un script de test séparé : Exclu car moins pratique qu’un endpoint HTTP.
Utiliser un mock de Queue : Exclu car ajoute de la complexité.

6. Recommandations

Sécurité : S’assurer que l’endpoint /test-direct n’est pas exposé en production.
Documentation : Documenter clairement l’utilisation de l’endpoint /test-direct pour le développement local.
Tests : Utiliser l’endpoint /test-direct pour les tests unitaires et d’intégration locaux.
Cleanup : Supprimer l’endpoint /test-direct s’il n’est plus nécessaire à l’avenir.