[Nom du Worker]

[Nom du Worker]

Documentation technique

Type de ressource : Cloudflare Worker (Microservice FaaS / Middleware)
Fichier source : services/[worker-name]/src/index.ts
Statut : [Actif / Déprécié / En développement]

1. Vue d’ensemble

1.1. Description

[Description concise du rôle de ce Worker dans l’architecture L3]

1.2. Objectif

• [Objectif principal : ex. intercepter toutes les requêtes HTTP pour appliquer les politiques de sécurité]
• [Bénéfice pour l’architecture : ex. découplage de la logique Edge du framework Astro]

1.3. Caractéristiques

Propriété	Valeur
Type	[Middleware HTTP / Microservice métier / Cron Trigger / Pages Function]
Trigger	[HTTP fetch / Cron / Queue consumer / Les deux]
Route publique	https://[worker-name].[subdomain].workers.dev ou sous-domaine dédié
Environnements	[Production / Staging / Preview]
Consommateurs	[Astro / Sanity / Navigateur / Autres Workers]

2. Architecture et flux

2.1. Diagramme de flux

[Entrée : Client / Astro / Sanity / Cron]
     │
     ▼
[Cloudflare Worker]
     │  • Validation des entrées
     │  • Logique métier
     │  • Interaction avec les bindings (KV, R2, Queue)
     ▼
[Services tiers / Storage]
     │  • Sanity API / CRM / R2 / KV
     ▼
[Réponse / Action]

2.2. Positionnement dans la chaîne Edge

[Client]
     │
     ▼
[Middleware Global] ← (ce Worker, si applicable)
     │
     ▼
[Pages Functions / Autres Workers]
     │
     ▼
[Services tiers]

2.3. Composants impliqués

Composant	Rôle	Type
[Nom]	[Description]	[Binding / Service tiers / Client]

3. Configuration

3.1. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
[Variable]	[Description]	[✅/❌]	[Valeur]

3.2. Bindings Cloudflare

Binding	Type	Nom	Description
[Nom]	[KV / R2 / Queue / Service / Secret]	[Binding name]	[Description]

3.3. Configuration Wrangler (wrangler.toml)

services/[worker-name]/wrangler.toml

name = "[worker-name]"
main = "src/index.ts"
compatibility_date = "2026-09-01"

[vars]
# Variables non-sensibles
[VAR_NAME] = "value"

# Bindings
[[kv_namespaces]]
binding = "KV_BINDING"
id = "your-kv-namespace-id"

[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "bucket-name"

[[queues.producers]]
queue = "queue-name"
binding = "QUEUE_BINDING"

[triggers]
crons = ["0 2 * * *"]  # Si Cron Trigger

[env.production]
vars = { [VAR_NAME] = "prod-value" }

[env.staging]
vars = { [VAR_NAME] = "staging-value" }

3.4. Injection des secrets

# Injection des secrets via Wrangler CLI
wrangler secret put [SECRET_NAME] --env production
wrangler secret put [SECRET_NAME] --env staging

4. Implémentation

4.1. Code de production (src/index.ts)

export interface Env {
  // Définition des bindings et variables d'environnement
  [BINDING_NAME]: [Type];
}

export default {
  // Handler HTTP (si applicable)
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Logique du Worker
    return new Response('OK', { status: 200 });
  },

  // Handler Cron (si applicable)
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
    // Logique du Cron
  },

  // Handler Queue (si applicable)
  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void> {
    // Logique du Queue consumer
  },
};

4.2. Interfaces et types

// Types spécifiques au Worker
interface [TypeName] {
  // ...
}

5. Sécurité

5.1. Mécanismes de sécurité

Mécanisme	Implémentation	Rationale
[Mécanisme]	[Implémentation]	[Rationale]

5.2. Validation des entrées

• ✅ [Règle de validation 1]
• ✅ [Règle de validation 2]
• ✅ [Règle de validation 3]

5.3. Gestion des secrets

• ✅ Les secrets ne sont jamais dans le code source
• ✅ Injection via wrangler secret put
• ✅ Rotation régulière des secrets (tous les 90 jours recommandé)

6. Résilience et gestion des erreurs

6.1. Stratégie de retry

Scénario	Stratégie	Rationale
[Scénario]	[Retry / Fallback / Queue]	[Rationale]

6.2. Safety Locks (si applicable)

Lock	Condition	Action
[Nom]	[Condition]	[Action]

6.3. Gestion des timeouts

• ✅ Timeout global : [X] secondes
• ✅ Timeout par service tiers : [X] secondes
• ✅ Fallback en cas de timeout : [Description]

7. Performance et limites

7.1. Limites Cloudflare Workers

Limite	Valeur	Stratégie d’optimisation
Mémoire RAM	128 MB	[Stratégie : streaming, URLs présignées]
CPU time	30s (Free) / 50s (Paid)	[Stratégie]
Nombre de sous-requêtes	50	[Stratégie]
Taille requête/réponse	100 MB	[Stratégie]

7.2. Optimisations appliquées

• ✅ [Optimisation 1 : ex. streaming HTTP pour éviter OOM]
• ✅ [Optimisation 2 : ex. URLs présignées pour déporter l’upload]
• ✅ [Optimisation 3 : ex. debouncing KV pour limiter les exécutions]

8. Monitoring et observabilité

8.1. Logs structurés

// Format de log recommandé
console.log(JSON.stringify({
  worker: '[worker-name]',
  action: '[action]',
  status: '[success/error]',
  duration: 123,
  metadata: { /* ... */ }
}));

8.2. Métriques clés

Métrique	Seuil d’alerte	Canal
Taux d’erreur 5xx	> 1% sur 5 min	[PagerDuty / Slack / Email]
Latence p95	> [X]ms	[Canal]
[Autre métrique]	[Seuil]	[Canal]

8.3. Commandes de debug

# Logs en temps réel
wrangler tail [worker-name] --env production

# Vérification des bindings
wrangler deployments list

# Inspection des variables d'environnement
wrangler secret list --env production

9. Déploiement

9.1. Pipeline de déploiement

# Build
npm run build --workspace=services/[worker-name]

# Déploiement staging
wrangler deploy --env staging

# Déploiement production
wrangler deploy --env production

9.2. Rollback

# Liste des déploiements
wrangler deployments list

# Rollback vers une version précédente
wrangler deployments rollback --deployment-id=[id]

9.3. Tests manuels

# Test HTTP
curl -X POST "https://[worker-url]" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Test Cron (trigger manuel)
wrangler dev --test-scheduled

# Test Queue
wrangler queues tail [queue-name]

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
[Symptôme]	[Cause]	[Solution]

10.2. Erreurs fréquentes

Code HTTP / Erreur	Signification	Action
[Code]	[Signification]	[Action]

11. Bonnes pratiques

11.1. Architecture

• ✅ Respecter le principe de responsabilité unique (un Worker = une mission)
• ✅ Découpler la logique Edge du framework Astro
• ✅ Utiliser les bindings Cloudflare plutôt que des appels HTTP internes
• ✅ Préférer le streaming HTTP au chargement en mémoire

11.2. Code

• ✅ Typer strictement les bindings et les réponses
• ✅ Valider toutes les entrées (Zod, schémas custom)
• ✅ Gérer explicitement les erreurs (try/catch)
• ✅ Logger de manière structurée (JSON)

11.3. Sécurité

• ✅ Ne jamais exposer les secrets côté client
• ✅ Valider cryptographiquement les webhooks (HMAC)
• ✅ Utiliser des comparaisons à temps constant pour les secrets
• ✅ Appliquer une CSP stricte (pour le Middleware)

11.4. Performance

• ✅ Minimiser le nombre de sous-requêtes
• ✅ Utiliser le cache KV pour les données fréquemment lues
• ✅ Déporter les uploads lourds via URLs présignées
• ✅ Utiliser le streaming pour les gros volumes

12. Évolutions et roadmap

12.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]
• [Évolution 3]

12.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

13. Ressources liées1/2

• Documentation Cloudflare Workers : Getting Started
• Documentation Wrangler : CLI Reference
• DAT L3 : §[X] - [Section pertinente]
• Workers associés :
  • [Liste des Workers liés ou dépendants]

13. Ressources liées2/2

• Fichiers concernés :
  • services/[worker-name]/src/index.ts
  • services/[worker-name]/wrangler.toml
  • services/[worker-name]/package.json

14. Historique des modifications1/2

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]
YYYY-MM-DD	1.1	[Modification]	[Nom]

14. Historique des modifications2/2

---

**Points clés de ce template :**
- Couvre les trois types de handlers (HTTP fetch, Cron, Queue consumer)
- Détaille la configuration Wrangler complète (bindings, secrets, environnements)
- Inclut les safety locks et mécanismes de résilience (critiques pour les Workers métier)
- Documente les limites Cloudflare et les stratégies d'optimisation
- Fournit les commandes de debug et de rollback
- Sépare clairement les bonnes pratiques par catégorie (architecture, code, sécurité, performance)
- S'adapte à tous les Workers du projet (Middleware, form-handler, cms-webhook-receiver, media-upload, media-cleanup, sanity-backup)

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

[Nom du Worker]

1. 1. Vue d’ensemble2
2. 1.1. Description3
3. 1.2. Objectif4
4. 1.3. Caractéristiques5
5. 2. Architecture et flux6
6. 2.1. Diagramme de flux7
7. 2.2. Positionnement dans la chaîne Edge8
8. 2.3. Composants impliqués9
9. 3. Configuration10
10. 3.1. Variables d’environnement11
11. 3.2. Bindings Cloudflare12
12. 3.3. Configuration Wrangler (wrangler.toml)13
13. 3.4. Injection des secrets14
14. 4. Implémentation15
15. 4.1. Code de production (src/index.ts)16
16. 4.2. Interfaces et types17
17. 5. Sécurité18
18. 5.1. Mécanismes de sécurité19
19. 5.2. Validation des entrées20
20. 5.3. Gestion des secrets21
21. 6. Résilience et gestion des erreurs22
22. 6.1. Stratégie de retry23
23. 6.2. Safety Locks (si applicable)24
24. 6.3. Gestion des timeouts25
25. 7. Performance et limites26
26. 7.1. Limites Cloudflare Workers27
27. 7.2. Optimisations appliquées28
28. 8. Monitoring et observabilité29
29. 8.1. Logs structurés30
30. 8.2. Métriques clés31
31. 8.3. Commandes de debug32
32. 9. Déploiement33
33. 9.1. Pipeline de déploiement34
34. 9.2. Rollback35
35. 9.3. Tests manuels36
36. 10. Débogage et troubleshooting37
37. 10.1. Problèmes courants38
38. 10.2. Erreurs fréquentes39
39. 11. Bonnes pratiques40
40. 11.1. Architecture41
41. 11.2. Code42
42. 11.3. Sécurité43
43. 11.4. Performance44
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 modifications50