[Nom de la Ressource de Stockage Cloudflare]

Type de ressource : Bucket Cloudflare R2 / Bibliothèque Cloudflare Stream
Fichier source : services/[worker-name]/wrangler.toml ou configuration associée
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 cette ressource de stockage dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. stocker les images du blog et du portfolio]
• [Bénéfice pour l’architecture : ex. découplage des médias du CMS Sanity]

1.3. Périmètre concerné

Type de médias	Statut
Images	[✅/❌]
Vidéos	[✅/❌]
Documents	[✅/❌]
Backups	[✅/❌]

Accès	Statut
Public	[✅/❌]
Privé	[✅/❌]
URLs signées	[✅/❌]

Consommateur	Statut
Sanity	[✅/❌]
Astro	[✅/❌]
Workers L3	[✅/❌]

---

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Sanity Studio]
     │  (upload via Worker L3)
     ▼
[Worker media-upload (L3)]
     │  • Génération URL présignée R2
     ▼
[Cloudflare R2]
     │  • Stockage structuré
     ▼
[Sanity]
     │  • Stocke uniquement URL + métadonnées
     ▼
[Astro / Site]
     │  • Consomme les URLs R2
     ▼
[Utilisateur final]

2.2. Composants impliqués

Composant	Rôle	Couche
Bucket R2	Stockage des médias	Infrastructure
Worker media-upload	Génération d’URLs présignées	L3
Worker media-cleanup	Nettoyage des orphelins	L3
Worker sanity-backup	Backups vers R2	L3
Sanity	Stockage des métadonnées + URLs	L1
Astro	Consommation des URLs	L2

---

3. Configuration du bucket (CODE)

3.1. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
R2_ACCOUNT_ID	ID du compte Cloudflare	✅	-
R2_BUCKET_NAME	Nom du bucket	✅	-
R2_ACCESS_KEY_ID	Clé d’accès API R2	✅	-
R2_SECRET_ACCESS_KEY	Clé secrète API R2	✅	-
R2_PUBLIC_DOMAIN	Domaine public	✅	-

3.2. Configuration Wrangler (wrangler.toml)

services/media-upload/wrangler.toml

name = "media-upload"
main = "src/index.ts"
compatibility_date = "2026-09-01"

[[r2_buckets]]
binding = "R2_BUCKET"
bucket_name = "pub-medias"
preview_bucket_name = "pub-medias-staging"

[vars]
R2_ACCOUNT_ID = "your-account-id"
R2_BUCKET_NAME = "pub-medias"
R2_PUBLIC_DOMAIN = "pub-medias.votredomaine.com"

3.3. Injection des secrets

wrangler secret put R2_ACCESS_KEY_ID --env production
wrangler secret put R2_SECRET_ACCESS_KEY --env production

---

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

4.1. Inputs (Upload)

Paramètre	Type	Validation
file	File	Type MIME valide
filename	string	Extension valide

4.2. Outputs (URL)

Élément	Type	Description
url	string	URL publique du fichier

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Upload	Fichier valide	URL générée
Download	URL valide	Fichier retourné

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux upload	Worker + R2	Upload → Stockage	Fichier stocké

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Sanity	L1	Stockage métadonnées	URL stockée dans schéma
Astro	L2	Consommation	URL utilisée dans <img>
Workers	L3	Gestion	R2 binding

6.2. Points d’attention

• Les credentials ne doivent jamais être exposés
• Les URLs doivent être accessibles publiquement
• Le bucket doit être configuré avec le bon domaine

6.3. Vérification de cohérence

• Le bucket est créé
• Les credentials sont valides
• Les uploads fonctionnent
• Les téléchargements fonctionnent

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Credentials injectés via secrets
• ✅ HTTPS forcé
• ✅ CORS configuré

7.2. Règles de sécurité

• ✅ Ne jamais exposer les credentials
• ✅ Valider les types MIME
• ✅ Configurer les permissions correctement

---

8. Performance et limites

8.1. Limites R2

Limite	Valeur
Taille max fichier	5 TB
Requêtes par seconde	Illimité (facturé)

8.2. Optimisations

• ✅ CDN Cloudflare
• ✅ Compression automatique
• ✅ Cache Edge

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Upload échoue	Credentials invalides	Vérifier les secrets
403 Forbidden	Permissions incorrectes	Configurer les permissions

9.2. Commandes de debug

# Lister les buckets
wrangler r2 bucket list

# Télécharger un fichier
wrangler r2 object get bucket-name key

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Organisation hiérarchique des fichiers
• ✅ Noms de fichiers cohérents
• ✅ Lifecycle rules

10.2. Maintenance

• ✅ Surveiller l’utilisation
• ✅ Nettoyer les fichiers orphelins
• ✅ Configurer les lifecycle rules

---

11. Évolutions et roadmap

11.1. Améliorations planifiées

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

11.2. Limitations connues

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

---

12. Ressources liées

• Documentation Cloudflare : R2

---

13. Historique des modifications

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