Middleware Astro : Preview

Objet : Middleware Astro
Type : Middleware
Slice : Slice 1 (Page d’accueil)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : DOC

---

1. Description et périmètre

1.1. Objectif

Le middleware Astro détecte le mode preview (cookie sanity-preview) et injecte une bannière d’information dans les pages prerendered et SSR. Il permet aux collaborateurs de savoir qu’ils sont en mode preview et de quitter ce mode facilement.

1.2. Utilisation principale

• Détection du cookie sanity-preview
• Injection de bannière preview dans le HTML
• Gestion de la route /api/exit-preview pour quitter le mode

1.3. Périmètre concerné

• Type : Middleware Astro côté serveur
• Routes : Toutes les pages (prerendered et SSR)
• Cookie : sanity-preview=true
• Contrainte : Doit fonctionner avec les pages prerendered (SSG)

---

2. Contrats d’entrée

2.1. Détection du cookie preview

Entrée : Cookie sanity-preview dans la requête

Structure :

Cookie: sanity-preview=true

Règles :

• Le middleware détecte la présence du cookie
• La valeur doit être true pour activer le mode preview
• Si absent ou différent, pas de bannière

2.2. Routes spécifiques

Entrée : Chemin de la requête

Routes traitées :

• /api/exit-preview : Suppression du cookie et redirect
• /* : Injection de bannière si cookie présent

Règles :

• Middleware s’exécute sur toutes les routes
• Comportement spécial pour /api/exit-preview

---

3. Contrats de sortie

3.1. Injection de bannière preview

Sortie : HTML modifié avec bannière

Comportement :

• Si cookie sanity-preview=true : injecter bannière après <body>
• Si cookie absent : ne rien modifier
• Bannière contient : message d’avertissement + lien exit-preview

3.2. Gestion de route exit-preview

Sortie : Redirect avec suppression de cookie

Comportement :

• Supprimer le cookie sanity-preview
• Redirect vers /
• Code HTTP 307

---

4. Side effects

4.1. Impact sur le rendu

Effet : Le middleware modifie le HTML en sortie

Impact :

• Aucun impact sur la logique des composants
• Modification purement visuelle (bannière)
• Performance minimale (detection cookie + injection)

4.2. Impact sur le cache

Effet : Pages avec bannière preview ne devraient pas être mises en cache

Impact :

• Nécessite de désactiver le cache pour les requêtes avec cookie preview
• Cache normal pour les requêtes sans cookie

---

5. Erreurs et gestion

5.1. Erreurs potentielles

Erreur	Cause probable	Solution
Cookie non détecté	Middleware ne lit pas les cookies	Vérifier configuration middleware
Bannière non injectée	HTML invalide ou structure incorrecte	Vérifier le pattern d’injection
Exit-preview non fonctionnel	Route non interceptée	Vérifier le middleware s’exécute sur /api/exit-preview

5.2. Fallbacks

Gestion des erreurs :

• Si middleware échoue : page s’affiche normalement sans bannière
• Si route exit-preview échoue : l’utilisateur peut supprimer le cookie manuellement

---

6. Architecture

6.1. Position dans le pipeline

Requête HTTP → Middleware Astro → Page Astro → Réponse HTML
                            ↓
                    Détection cookie
                            ↓
                    Injection bannière

6.2. Interaction avec les pages

Pages prerendered (SSG) :

• Middleware peut détecter le cookie (contrairement aux composants)
• Injection de bannière dans le HTML statique
• Respecte l’ADR-SSR-Pur.md

Pages SSR :

• Détection du cookie dans le composant (déjà implémenté)
• Middleware injecte aussi la bannière pour cohérence
• Double détection possible (non problématique)

---

7. Sécurité

7.1. Validation du cookie

Règles :

• Ne faire confiance qu’au cookie sanity-preview=true
• Ne pas injecter de bannière pour d’autres cookies
• Le cookie est posé par le middleware Cloudflare (validation secret)

7.2. Protection contre abus

Règles :

• La bannière ne contient que du HTML statique
• Pas de script ou contenu dynamique dans la bannière
• Le lien exit-preview pointe vers /api/exit-preview (route middleware)

---

8. Checklist de validation

Avant de considérer le middleware comme terminé :

• Détection du cookie sanity-preview fonctionnelle
• Injection de bannière dans les pages prerendered
• Injection de bannière dans les pages SSR
• Route /api/exit-preview fonctionnelle
• Suppression correcte du cookie
• Redirect vers / après exit
• Performance acceptable (overhead minimal)
• Aucun conflit avec le middleware Cloudflare

---

9. Approbation

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

---

10. Historique des modifications

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