[Nom du Worker]

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ées

• 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]
• Fichiers concernés :
  • services/[worker-name]/src/index.ts
  • services/[worker-name]/wrangler.toml
  • services/[worker-name]/package.json

14. Historique des modifications

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

---

**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)