[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]
Slice : [Numéro de la tranche verticale]
Version : 1.0

---

1. Vue d’ensemble (DOC)

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 (DOC)

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. Composants impliqués

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

---

3. Configuration (CODE)

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 * * * *"] # Toutes les heures

---

4. Implémentation (CODE)

4.1. Handler HTTP fetch

services/[worker-name]/src/index.ts

export interface Env {
  KV_BINDING: KVNamespace;
  R2_BUCKET: R2Bucket;
  QUEUE_BINDING: Queue;
  [SECRET_NAME]: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    // Logique métier
    if (url.pathname === '/api/endpoint') {
      return handleEndpoint(request, env);
    }

    return new Response('Not Found', { status: 404 });
  },
};

4.2. Handler Cron (si applicable)

export default {
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
    // Logique cron
    console.log('Cron triggered', { cron: event.cron });
  },
};

4.3. Handler Queue (si applicable)

export default {
  async queue(batch: MessageBatch<unknown>, env: Env): Promise<void> {
    for (const message of batch.messages) {
      await processMessage(message, env);
      message.ack();
    }
  },
};

---

5. Contrats d’Entrée/Sortie (SPEC)

5.1. Inputs (Requête HTTP)

Paramètre	Type	Source	Validation
body	object	Request body	Validation Zod
headers	Headers	Request headers	Validation des en-têtes

5.2. Outputs (Réponse HTTP)

Code HTTP	Condition	Description
200	Succès	Opération réussie
400	Erreur client	Requête invalide
500	Erreur serveur	Erreur interne

5.3. Side effects

Effet	Description	Fréquence
[Écriture KV]	[Description]	[À chaque appel / Conditionnel]

---

6. Tests attendus (TEST)

6.1. Tests unitaires

Scénario	Description	Résultat attendu
Handler fetch	Requête HTTP valide	Réponse 200
Validation des entrées	Données invalides	Erreur 400

6.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux complet	Bindings + Services tiers	Opération end-to-end	Succès

6.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Déploiement	Build → Deploy	Déploiement sur Cloudflare	Worker fonctionnel

---

7. Intégration (INTÉG)

7.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Astro	L2	Consommateur	HTTP fetch
Sanity	L1	Producteur	Webhook
Autres Workers	L3	Communication	Service binding

7.2. Points d’attention

• Les bindings doivent être configurés dans wrangler.toml
• Les secrets doivent être injectés via wrangler secret put
• Les handlers doivent être correctement exportés

7.3. Vérification de cohérence

• Le Worker se déploie correctement
• Les bindings sont accessibles
• Les tests unitaires passent
• Les tests E2E passent

---

8. Sécurité

8.1. Mécanismes de sécurité

• ✅ Validation des entrées
• ✅ Secrets injectés via wrangler secret put
• ✅ HTTPS forcé

8.2. Règles de sécurité

• ✅ Ne jamais logger les secrets
• ✅ Valider toutes les entrées
• ✅ Utiliser les permissions minimales

---

9. Performance et limites

9.1. Limites Cloudflare

Limite	Valeur	Stratégie d’optimisation
CPU time	10 ms (free) / 50 ms (paid)	Optimiser le code
Memory	128 MB	Éviter les gros objets
Requests	100 000 (free) / 10M (paid)	Cache Edge

9.2. Optimisations

• ✅ Utiliser le cache Edge
• ✅ Minimiser les allocations mémoire
• ✅ Utiliser des opérations asynchrones

---

10. Débogage et troubleshooting

10.1. Problèmes courants

Symptôme	Cause probable	Solution
Worker échoue	Binding manquant	Vérifier wrangler.toml
Secret inaccessible	Secret non injecté	wrangler secret put
Timeout	CPU time dépassé	Optimiser le code

10.2. Commandes de debug

# Déploiement local
wrangler dev

# Déploiement production
wrangler deploy --env production

# Logs en temps réel
wrangler tail

---

11. Bonnes pratiques

11.1. Architecture

• ✅ Handlers séparés par type (fetch, cron, queue)
• ✅ Validation des entrées
• ✅ Gestion des erreurs

11.2. Code

• ✅ TypeScript strict
• ✅ Logs structurés
• ✅ Documentation des fonctions

11.3. Maintenance

• ✅ Mettre à jour les dépendances régulièrement
• ✅ Documenter les changements dans ce fichier

---

12. Évolutions et roadmap

12.1. Améliorations planifiées

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

12.2. Limitations connues

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

---

13. Ressources liées

• Documentation Cloudflare : Workers
• DAT L3 : §5 - Workers Cloudflare

---

14. Historique des modifications

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