Middleware Cloudflare : Preview Mode

Objet : Middleware Cloudflare Worker
Type : Worker
Slice : Slice 1 (Page d’accueil) + Slice 2 (Blog)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : DOC

---

1. Description et périmètre

1.1. Objectif

Le middleware Cloudflare Worker est un Worker indépendant qui gère le mode preview Sanity. Il valide le secret de preview, pose le cookie sanity-preview, et force le bypass du cache Edge.

1.2. Utilisation principale

• Validation du mode preview Sanity
• Gestion du cookie sanity-preview
• Bypass du cache Edge en mode preview
• Protection contre les open redirects

1.3. Périmètre concerné

• Type : Cloudflare Worker indépendant
• Isolation : Isolé d’Astro (conformément à l’ADR L3)
• Localisation : services/preview-middleware/
• Intégration : Placé en amont de la couche de présentation

---

2. Contrats d’entrée

2.1. Requête HTTP

Entrée : Requête HTTP avec paramètres de preview

Structure :

GET /api/preview?secret={SANITY_PREVIEW_SECRET}&slug={slug}

Règles :

• secret : obligatoire, secret de preview Sanity
• slug : obligatoire, slug de la page à prévisualiser
• Validation du secret côté middleware

2.2. Variables d’environnement

Entrée : Variables d’environnement Cloudflare

Structure :

{
  SANITY_PREVIEW_SECRET: string,
  SANITY_PROJECT_ID: string,
  SANITY_DATASET: string
}

Règles :

• SANITY_PREVIEW_SECRET : obligatoire, secret de validation
• SANITY_PROJECT_ID : obligatoire, ID du projet Sanity
• SANITY_DATASET : obligatoire, nom du dataset

---

3. Contrats de sortie

3.1. Cookie de preview

Sortie : Cookie sanity-preview posé

Comportement :

• Cookie sanity-preview = true
• path = /
• httpOnly = true
• secure = true
• sameSite = lax
• maxAge = 3600 (1 heure)

3.2. Redirect

Sortie : Redirect vers la page demandée

Comportement :

• Status HTTP 307 (Temporary Redirect)
• Redirect vers le slug validé
• Protection contre les open redirects

3.3. Bypass du cache Edge

Sortie : Bypass du cache Edge en mode preview

Comportement :

• cf.cacheEverything = false en mode preview
• Force le rendu à la demande
• Évite le cache statique

---

4. Side effects

4.1. Impact sur le cache

Effet : Le middleware bypass le cache Edge en mode preview

Impact :

• En mode preview : pas de cache, rendu à la demande
• En mode normal : cache Edge activé
• Nécessite de détecter le cookie sanity-preview

4.2. Impact sur la sécurité

Effet : Le middleware valide le secret de preview

Impact :

• Protection contre l’accès non autorisé aux drafts
• Protection contre les open redirects
• Cookie sécurisé (httpOnly, secure)

---

5. Erreurs et gestion

5.1. Erreurs potentielles

Erreur	Cause probable	Solution
Secret invalide	Secret incorrect ou manquant	Retourner HTTP 401
Slug invalide	Slug mal formaté	Sanitizer le slug (protection open redirect)
Cookie non posé	Erreur lors de la pose du cookie	Retourner HTTP 500
Variable manquante	Variable d’environnement manquante	Retourner HTTP 500

5.2. Codes HTTP

• 200 : Preview activé avec succès
• 307 : Redirect vers la page demandée
• 401 : Secret invalide ou manquant
• 500 : Erreur serveur

---

6. Checklist de validation

Avant de passer à l’étape SPEC, vérifier :

• La structure du middleware est documentée
• Les contrats d’entrée/sortie sont documentés
• Les side effects sont identifiés
• Les erreurs potentielles sont documentées

---

7. Approbation

Validation requise : Confirmer que la documentation du middleware preview peut passer à l’étape SPEC.

---

8. Historique des modifications

Date	Version	Description	Auteur
2026-09-16	1.0	Création initiale	Devin