Configuration Wrangler Globale

Configuration Wrangler Globale

Documentation technique

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

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

Configuration Wrangler Globale

1. 1. Vue d’ensemble2
2. 1.1. Description3
3. 1.2. Objectif4
4. 1.3. Périmètre concerné5
5. 2. Architecture du Monorepo6
6. 2.1. Structure du dépôt7
7. 2.2. Composants impliqués8
8. 3. Configuration par service9
9. 3.1. Worker form-handler (Traitement des Formulaires)10
10. 3.2. Worker submission-processor (Traitement des Soumissions)11
11. 3.3. Services non implémentés12
12. 4. Gestion des secrets13
13. 4.1. Matrice des secrets par service14
14. 4.2. Commandes d’injection15
15. 4.3. Règles de sécurité16
16. 4.4. Vérification des secrets17
17. 5. Scripts npm du monorepo18
18. 5.1. Scripts de déploiement19
19. 5.2. Scripts de gestion des secrets20
20. 6. Configuration des environnements21
21. 6.1. Matrice des environnements22
22. 6.2. Variables d’environnement par environnement23
23. 6.3. Règles de déploiement24
24. 7. Bindings Cloudflare25
25. 7.1. Matrice des bindings par service26
26. 7.2. Création des ressources27
27. 7.3. Lifecycle Rules R228
28. 8. CI/CD et déploiement29
29. 8.1. Pipeline de déploiement30
30. 8.2. Rollback31
31. 8.3. Tests manuels32
32. 9. Monitoring et observabilité33
33. 9.1. Logs en temps réel34
34. 9.2. Métriques clés35
35. 9.3. Cloudflare Logpush36
36. 10. Débogage et troubleshooting37
37. 10.1. Problèmes courants38
38. 10.2. Commandes de debug39
39. 11. Bonnes pratiques40
40. 11.1. Architecture41
41. 11.2. Sécurité42
42. 11.3. Performance43
43. 11.4. Maintenance44
44. 12. Évolutions et roadmap45
45. 12.1. Améliorations planifiées46
46. 12.2. Limitations connues47
47. 13. Ressources liées48
48. 14. Historique des modifications49