Configuration Wrangler Globale

Type de ressource : Configuration Wrangler (Monorepo / Services Cloudflare)
Fichier source : wrangler.toml (racine) et services/[worker-name]/wrangler.toml
Statut : Actif

1. Vue d’ensemble

1.1. Description

Configuration centralisée des ressources Cloudflare partagées (R2, KV, Queues) pour le monorepo. Ce fichier à la racine n’est pas un Worker à déployer directement, mais sert de référence pour les identifiants de ressources partagées.

1.2. Objectif

• Centraliser les identifiants des ressources Cloudflare partagées
• Fournir une référence unique pour les R2 buckets, Queues et KV namespaces
• Documenter l’architecture de déploiement du monorepo

1.3. Périmètre concerné

• Services couverts : form-handler, submission-processor
• Environnements : Development, Production
• Type de configuration : Wrangler.toml (référence), Bindings (R2, KV, Queue)

2. Architecture du Monorepo

2.1. Structure du dépôt

├── apps/
│   ├── web/                     # Projet Front-End Astro (Couche 02)
│   │   └── wrangler.toml
│   └── studio/                  # Sanity Studio SPA (Couche 01)
│       └── wrangler.toml
├── services/
│   ├── form-handler/            # Microservice formulaires
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── wrangler.toml
│   │   └── package.json
│   └── submission-processor/   # Microservice traitement soumissions
│       ├── src/
│       │   └── index.ts
│       ├── wrangler.toml
│       └── package.json
├── package.json                 # Scripts monorepo (Taskfile.yaml)
├── wrangler.toml                # Configuration racine (référence)
└── README.md

2.2. Composants impliqués

Composant	Rôle	Type
wrangler.toml (racine)	Configuration globale (référence)	Config
services/*/wrangler.toml	Configuration par service	Config
Cloudflare Resources	R2, KV, Queues	Infrastructure
Taskfile.yaml	Scripts de déploiement	Automation

3. Configuration par service

3.1. Worker form-handler (Traitement des Formulaires)

services/form-handler/wrangler.toml

name = "amn-form-handler"
main = "src/index.ts"
compatibility_date = "2025-07-18"
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "dev"

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

[env.dev]
name = "amn-form-handler-dev"
vars = { ENVIRONMENT = "dev" }

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

[env.production]
name = "amn-form-handler-prod"
vars = { ENVIRONMENT = "production" }

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

3.2. Worker submission-processor (Traitement des Soumissions)

services/submission-processor/wrangler.toml

name = "amn-submission-processor"
main = "src/index.ts"
compatibility_date = "2025-07-18"
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "dev"

[env.dev]
name = "amn-submission-processor-dev"
vars = { ENVIRONMENT = "dev" }

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

[env.production]
name = "amn-submission-processor-prod"
vars = { ENVIRONMENT = "production" }

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

3.3. Services non implémentés

Les services suivants du template ne sont pas implémentés dans le projet actuel :

• middleware (Middleware Global)
• cms-webhook-receiver (Récepteur Webhooks)
• media-upload (Upload Présigné)
• media-cleanup (Nettoyage Cron)
• sanity-backup (Backup Cron)

4. Gestion des secrets

4.1. Matrice des secrets par service

Service	Secret	Description	Rotation
form-handler	Aucun secret configuré	-	-
submission-processor	SANITY_PROJECT_ID	ID du projet Sanity	90 jours
submission-processor	SANITY_DATASET	Nom du dataset	90 jours
submission-processor	SANITY_API_WRITE_TOKEN	Token d’écriture Sanity	90 jours

4.2. Commandes d’injection

# Injection des secrets pour le service submission-processor
wrangler secret put SANITY_PROJECT_ID --env production --config services/submission-processor/wrangler.toml
wrangler secret put SANITY_DATASET --env production --config services/submission-processor/wrangler.toml
wrangler secret put SANITY_API_WRITE_TOKEN --env production --config services/submission-processor/wrangler.toml

4.3. Règles de sécurité

• ✅ Les secrets ne sont jamais commités dans Git
• ✅ Les secrets sont injectés via wrangler secret put (chiffrés par Cloudflare)
• ✅ Rotation recommandée tous les 90 jours
• ✅ Les secrets sont spécifiques à chaque environnement (production/development)
• ✅ Les secrets ne sont jamais loggés dans les Workers

4.4. Vérification des secrets

# Liste des secrets d'un service
wrangler secret list --config services/submission-processor/wrangler.toml --env production

# Suppression d'un secret
wrangler secret delete SECRET_NAME --config services/submission-processor/wrangler.toml --env production

5. Scripts npm du monorepo

5.1. Scripts de déploiement

# Taskfile.yaml (utilisé à la place de package.json)
tasks:
  dev:services:
    # Démarre tous les services
  build:
    # Build l'application web
  typecheck:services:
    # Typecheck les services

5.2. Scripts de gestion des secrets

Non implémenté - utilisez wrangler secret put directement.

6. Configuration des environnements

6.1. Matrice des environnements

Environnement	Usage	Déclenchement
dev	Développement local	task dev:services
production	Production publique	Merge sur main (via GitHub Actions)

6.2. Variables d’environnement par environnement

Variable	Dev	Production
ENVIRONMENT	dev	production
Queue	submissions-queue-dev	submissions-queue-prod

6.3. Règles de déploiement

• ✅ La branche main déclenche le déploiement en production via GitHub Actions
• ✅ Les secrets sont spécifiques à chaque environnement
• ✅ Les bindings (Queue) sont partagés ou isolés selon l’environnement

7. Bindings Cloudflare

7.1. Matrice des bindings par service

Service	KV	R2	Queue	Service
form-handler	-	-	SUBMISSIONS_QUEUE	-
submission-processor	-	-	SUBMISSIONS_QUEUE	-

7.2. Création des ressources

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

7.3. Lifecycle Rules R2

Non implémenté - aucun bucket R2 n’est configuré dans les services actuels.

8. CI/CD et déploiement

8.1. Pipeline de déploiement

Non documenté - le déploiement est automatique via GitHub Actions (selon règles globales).

8.2. Rollback

# Liste des déploiements
wrangler deployments list --config services/form-handler/wrangler.toml

# Rollback vers une version précédente
wrangler deployments rollback --deployment-id=[id] --config services/form-handler/wrangler.toml

8.3. Tests manuels

# Test local d'un service
task dev:form-handler

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

9. Monitoring et observabilité

9.1. Logs en temps réel

# Logs d'un service spécifique
wrangler tail form-handler

# Logs avec filtre
wrangler tail submission-processor --format pretty

9.2. Métriques clés

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

9.3. Cloudflare Logpush

Non implémenté - Logpush n’est pas configuré.

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
“Binding not found”	Binding mal configuré	Vérifier le wrangler.toml et redéployer
“Secret not found”	Secret non injecté	Exécuter wrangler secret put
“Service unavailable”	Worker non déployé	Vérifier le déploiement avec wrangler deployments list
Erreur de compatibilité	compatibility_date trop ancien	Mettre à jour vers 2025-07-18

10.2. Commandes de debug

# Vérification de la configuration
wrangler deploy --dry-run --config services/form-handler/wrangler.toml

# Inspection des bindings
wrangler queues list

11. Bonnes pratiques

11.1. Architecture

• ✅ Séparer la configuration par service (un wrangler.toml par Worker)
• ✅ Utiliser des environnements distincts (dev/production)
• ✅ Documenter les bindings et secrets dans ce fichier
• ✅ Versionner les wrangler.toml dans Git (sauf les secrets)

11.2. Sécurité

• ✅ Ne jamais commiter les secrets dans Git
• ✅ Utiliser wrangler secret put pour injecter les secrets
• ✅ Rotation régulière des secrets (tous les 90 jours)
• ✅ Valider les permissions des tokens API (principe du moindre privilège)

11.3. Performance

• ✅ Utiliser compatibility_date récent pour bénéficier des optimisations
• ✅ Minimiser le nombre de bindings par Worker

11.4. Maintenance

• ✅ Documenter les changements de configuration dans ce fichier
• ✅ Surveiller les métriques après chaque déploiement

12. Évolutions et roadmap

12.1. Améliorations planifiées

• Ajout du service middleware (Middleware Global)
• Ajout du service cms-webhook-receiver (Webhooks Sanity)
• Ajout du service media-upload (Upload présigné)
• Ajout du service media-cleanup (Nettoyage Cron)
• Ajout du service sanity-backup (Backup Cron)
• Configuration de Logpush vers un SIEM

12.2. Limitations connues

• ❌ Les secrets ne peuvent pas être versionnés dans Git
• ❌ Pas de monitoring configuré
• ❌ Pas de Logpush configuré
• ❌ Pas de bucket R2 configuré

13. Ressources liées

• Documentation Cloudflare : Wrangler Configuration
• Documentation Cloudflare : Queues
• Fichiers concernés :
  • wrangler.toml (racine)
  • services/form-handler/wrangler.toml
  • services/submission-processor/wrangler.toml
  • apps/web/wrangler.toml
  • apps/studio/wrangler.toml

14. Historique des modifications

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