[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]
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]

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

[Nom du Worker]

1. 1. Vue d’ensemble (DOC)3
2. 1.1. Description4
3. 1.2. Objectif5
4. 1.3. Caractéristiques6
5. 2. Architecture et flux (DOC)7
6. 2.1. Diagramme de flux8
7. 2.2. Composants impliqués9
8. 3. Configuration (CODE)10
9. 3.1. Variables d’environnement11
10. 3.2. Bindings Cloudflare12
11. 3.3. Configuration Wrangler (wrangler.toml)13
12. 4. Implémentation (CODE)14
13. 4.1. Handler HTTP fetch15
14. 4.2. Handler Cron (si applicable)16
15. 4.3. Handler Queue (si applicable)17
16. 5. Contrats d’Entrée/Sortie (SPEC)18
17. 5.1. Inputs (Requête HTTP)19
18. 5.2. Outputs (Réponse HTTP)20
19. 5.3. Side effects21
20. 6. Tests attendus (TEST)22
21. 6.1. Tests unitaires23
22. 6.2. Tests d’intégration24
23. 6.3. Tests E2E25
24. 7. Intégration (INTÉG)26
25. 7.1. Intégration avec les composants27
26. 7.2. Points d’attention28
27. 7.3. Vérification de cohérence29
28. 8. Sécurité30
29. 8.1. Mécanismes de sécurité31
30. 8.2. Règles de sécurité32
31. 9. Performance et limites33
32. 9.1. Limites Cloudflare34
33. 9.2. Optimisations35
34. 10. Débogage et troubleshooting36
35. 10.1. Problèmes courants37
36. 10.2. Commandes de debug38
37. 11. Bonnes pratiques39
38. 11.1. Architecture40
39. 11.2. Code41
40. 11.3. Maintenance42
41. 12. Évolutions et roadmap43
42. 12.1. Améliorations planifiées44
43. 12.2. Limitations connues45
44. 13. Ressources liées46
45. 14. Historique des modifications47