Skip to content
AMN Docs

Middleware Cloudflare : Preview Mode

Middleware Cloudflare : Preview Mode

Documentation technique

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’environnement1/2

Entrée : Variables d’environnement Cloudflare

Structure :

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

2.2. Variables d’environnement2/2

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

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
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare