[Nom de la Configuration Cloudflare Stream]

Type de ressource : Configuration Cloudflare Stream (Direct Upload / Lecture / Métadonnées)
Fichier source : services/media-upload/src/index.ts 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 configuration Stream dans l’architecture du site]

1.2. Objectif

• [Objectif principal : ex. héberger les vidéos du portfolio avec transcoding automatique]
• [Bénéfice pour l’architecture : ex. adaptive bitrate sans gestion serveur]

1.3. Périmètre concerné

Type de contenu	Statut
Portfolio	[✅/❌]
Blog	[✅/❌]
Pages vitrine	[✅/❌]

Format source	Statut
MP4	[✅/❌]
MOV	[✅/❌]
WebM	[✅/❌]

Accès	Statut
Public	[✅/❌]
Privé	[✅/❌]
Signé	[✅/❌]

---

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Sanity Studio]
     │  (demande d'upload vidéo)
     ▼
[Worker media-upload (L3)]
     │  • Génération Direct Upload Token
     ▼
[Sanity Studio]
     │  • Upload direct vers Cloudflare Stream
     │  • Stocke l'uid dans le document
     ▼
[Cloudflare Stream]
     │  • Transcoding automatique
     │  • Génération des thumbnails
     ▼
[Astro / Site]
     │  • Iframe ou SDK Stream
     ▼
[Utilisateur final]

2.2. Composants impliqués

Composant	Rôle	Couche
Bibliothèque Stream	Stockage + transcoding	Infrastructure
Worker media-upload	Génération de tokens	L3
Sanity	Stockage de l’UID Stream	L1
Astro	Intégration du player	L2

---

3. Configuration (CODE)

3.1. Variables d’environnement

Variable	Description	Obligatoire	Valeur par défaut
CLOUDFLARE_ACCOUNT_ID	ID du compte Cloudflare	✅	-
CLOUDFLARE_STREAM_API_TOKEN	Token API Stream	✅	-
STREAM_PUBLIC_DOMAIN	Domaine public	❌	iframe.videodelivery.net

3.2. Configuration du token API

Dans le Dashboard Cloudflare :

1. My Profile → API Tokens → Create Token
2. Template : “Create Custom Token”
3. Permissions : Account → Cloudflare Stream → Edit

wrangler secret put CLOUDFLARE_STREAM_API_TOKEN --env production

3.3. Génération du Direct Upload Token

services/media-upload/src/index.ts

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await fetch(
      `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/stream/direct_upload`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${env.CLOUDFLARE_STREAM_API_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          maxDurationSeconds: 3600,
          requiredSignedURLs: false,
        }),
      }
    );

    const data = await response.json();
    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' },
    });
  },
};

---

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

4.1. Inputs (Demande de token)

Paramètre	Type	Validation
maxDurationSeconds	number	≤ 3600

4.2. Outputs (Token + URL)

Élément	Type	Description
uploadURL	string	URL d’upload
uid	string	UID de la vidéo

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Génération token	Requête valide	Token généré
Upload vidéo	Token valide	Vidéo uploadée

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux upload	Worker + Stream	Token → Upload	Vidéo stockée

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Sanity	L1	Stockage UID	Champ videoUid
Astro	L2	Player	Iframe ou SDK

6.2. Points d’attention

• Le token doit être généré côté serveur
• L’UID doit être stocké dans Sanity
• Le player doit être configuré correctement

6.3. Vérification de cohérence

• Le token est généré
• L’upload fonctionne
• Le transcoding est automatique
• Le player affiche la vidéo

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Token API injecté via secret
• ✅ HTTPS forcé
• ✅ Validation des durées

7.2. Règles de sécurité

• ✅ Ne jamais exposer le token API
• ✅ Limiter la durée des vidéos
• ✅ Configurer les permissions correctement

---

8. Performance et limites

8.1. Limites Stream

Limite	Valeur
Durée max vidéo	3600s (1h)
Taille max fichier	10 GB
Vidéos par compte	Illimité (facturé)

8.2. Optimisations

• ✅ Transcoding automatique
• ✅ Adaptive bitrate
• ✅ CDN global

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Token invalide	Token expiré	Régénérer le token
Upload échoue	Format non supporté	Vérifier le format

9.2. Commandes de debug

# Lister les vidéos
wrangler stream list

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Utiliser le Direct Upload Token
• ✅ Stocker l’UID dans Sanity
• ✅ Utiliser le player iframe ou SDK

10.2. Maintenance

• ✅ Surveiller l’utilisation
• ✅ Nettoyer les vidéos obsolètes

---

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 : Stream

---

13. Historique des modifications

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