La mise en cache pour tout cadriciel, tout CMS.

1. Activez la mise en cache

Dans Paramètres → Cache de votre projet, activez Mise en cache des réponses. Cela place le cache de Canner devant votre application. Rien n’est mis en cache tant que vos réponses ne le demandent pas — voir l’étape 2.

2. Marquez les réponses comme cachables et étiquetez-les

Sur les routes à mettre en cache, posez un en-tête Cache-Control avecs-maxage, et étiquetez la réponse avec un Surrogate-Key par entité présente sur la page. Ajoutez stale-while-revalidate pour continuer de servir instantanément pendant qu’une copie fraîche est récupérée en arrière-plan. Les étiquettes sont automatiquement limitées à votre projet, alors utilisez des noms clairs et lisibles :

---
// src/pages/blog/[slug].astro  (output: 'server')
const post = await getPost(Astro.params.slug);

// Cache on Canner for an hour; keep serving up to a day past that while a
// fresh copy is fetched in the background (stale-while-revalidate).
Astro.response.headers.set(
  "Cache-Control",
  "public, s-maxage=3600, stale-while-revalidate=86400"
);
Astro.response.headers.set(
  "Surrogate-Key",
  [`post-${post.id}`, "blog-listing"].join(" ")
);
---

Une même entité peut apparaître sur plusieurs routes (page de l’article, liste, page d’accueil). En étiquetant chaque réponse avec la clé de l’entité, une seule purge les vide toutes d’un coup. Après une purge, le prochain visiteur d’une route vidée déclenche un seul rendu frais, qui est ensuite remis en cache.

---
import { cache } from '@canner-ca/astro-cache';
const post = await getPost(Astro.params.slug);
cache(Astro.response, { ttl: 3600, swr: 86400, tags: [post.id, 'blog-listing'] });
---

Astro 7 : utilisez Canner comme fournisseur de cache

Sur Astro 7+, Canner s’intègre à la mise en cache des routes intégrée d’Astro comme fournisseur de première classe — la même API que sur Netlify, Vercel ou Cloudflare, dirigée vers Canner. Configurez-le une fois :

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import { cacheCanner } from '@canner-ca/astro-cache';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  cache: {
    provider: cacheCanner({
      slug: 'my-project',
      token: process.env.CANNER_CACHE_TOKEN, // only needed for invalidate()
    }),
  },
});

Contrôlez ensuite la mise en cache par route avec Astro.cache.set() (oucontext.cache.set() dans les points de terminaison et le middleware). Canner traduit les directives en en-têtes de cache et gère les purges par étiquette et par URL avec le même jeton :

---
// src/pages/blog/[slug].astro
const post = await getPost(Astro.params.slug);
Astro.cache.set({ maxAge: 3600, swr: 86400, tags: [post.id, 'blog-listing'] });
---

Le fournisseur met en cache au niveau du proxy de Canner — devant votre application, partagé entre les instances — sans jamais dépenser la mémoire de votre application pour un cache interne. Purgez par étiquette ou par URL depuis votre CMS, ou laissez la fonction invalidate() du fournisseur s’en charger.

Brouillon et aperçu : contourner le cache

Pour prévisualiser du contenu non publié sur sa vraie URL — sans vider ce que voient les autres — une requête peut contourner le cache. Le public continue de recevoir la page en cache; une requête portant le secret de contournement de votre projet est rendue à neuf depuis l’origine. C’est la même forme que le mode brouillon de Vercel. Trois façons de transporter le secret :

• un témoin __canner_bypass (pour une session de brouillon — posé depuis une route que vous avez autorisée),
• un paramètre ?__canner_bypass=<secret> (pour un lien d’aperçu partageable),
• un en-tête X-Canner-Bypass: <secret> (pour un usage programmatique).

Les utilitaires de cadriciel vous donnent une route de brouillon clé en main. Trouvez votre secret dans Paramètres → Cache (ou GET /projects/<slug>/cache/bypass-secret); faites-le pivoter là pour invalider tous les liens d’un coup :

// src/pages/api/draft.ts
import { enableDraft } from '@canner-ca/astro-cache';

export const GET = ({ url, cookies, redirect }) => {
  // You gate this yourself — e.g. a secret in the CMS preview URL.
  if (url.searchParams.get('secret') !== import.meta.env.PREVIEW_SECRET) {
    return new Response('Unauthorized', { status: 401 });
  }
  enableDraft(cookies, import.meta.env.CANNER_BYPASS_SECRET);
  return redirect(url.searchParams.get('to') ?? '/');
};

Une réponse contournée n’est jamais stockée et n’évince jamais l’entrée publiée, donc le contenu brouillon ne peut pas fuir dans le cache public. En mode strict (par défaut), le secret doit correspondre; le mode cookie-name optionnel contourne à la simple présence du témoin, pour les applications qui gèrent leur propre session de brouillon.

3. Invalidez depuis votre CMS

Dans Paramètres → Cache, générez un jeton de purge (affiché une seule fois). Dans votre CMS (n’importe lequel — la charge utile native de DatoCMS est comprise automatiquement), ajoutez un webhook déclenché à la publication/dépublication qui envoie :

• URL : https://api.canner.ca/projects/<votre-slug>/cache/purge
• Méthode : POST
• En-tête : Authorization: Bearer <votre jeton de purge>

Envoyez les étiquettes que votre application a émises dans Surrogate-Key, ou des chemins exacts à vider. Canner vide toutes les réponses en cache portant l’une de ces étiquettes — le tout limité à votre projet, donc vos étiquettes ne peuvent jamais toucher un autre site même si les noms coïncident :

curl -X POST https://api.canner.ca/projects/<your-slug>/cache/purge \
  -H "Authorization: Bearer <your purge token>" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["post-123", "blog-listing"]}'

Invalidez par URL au lieu des étiquettes (ou en plus) avec {"paths": [...]} — un chemin sans requête vide toutes ses variantes. C’est ce qu’appelle la fonction invalidate({ path }) du fournisseur Astro :

curl -X POST https://api.canner.ca/projects/<your-slug>/cache/purge \
  -H "Authorization: Bearer <your purge token>" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/blog/my-post"]}'

Tout vider

Besoin de repartir à zéro ? Le bouton Tout vider dans Paramètres → Cache vide tout le cache du projet. Pratique après un redéploiement qui a modifié la mise en page ou des composants partagés — même si les déploiements purgent déjà automatiquement.

Sites statiques : reconstruire au lieu de vider

Si votre site est entièrement statique (sans adaptateur serveur), il n’y a aucun cache par requête à vider — les pages ont été rendues au moment de la compilation. Dans ce cas, dirigez plutôt le webhook de votre CMS vers le point de terminaison rebuild, avec le même jeton de purge. Il redéploie votre projet depuis le dépôt GitHub connecté :

curl -X POST https://api.canner.ca/projects/<your-slug>/cache/rebuild \
  -H "Authorization: Bearer <your purge token>"

La reconstruction nécessite un projet connecté à GitHub (elle compile à partir du HEAD de votre dépôt). Les sites SSR devraient utiliser /cache/purge ci-dessus — c’est instantané et ça ne coûte pas une compilation.

Bon à savoir

• Seules les réponses avec Cache-Control: public et un s-maxage positif sont mises en cache. Les réponses authentifiées ou avec Set-Cookie ne le sont jamais.
• Avec stale-while-revalidate, le premier visiteur après l’expiration reçoit la copie périmée instantanément pendant que Canner la rafraîchit une fois en arrière-plan — personne n’attend un rendu à froid.
• Les purges sont limitées à votre projet — vous ne pouvez jamais toucher le cache d’un autre locataire, et personne ne peut vider le vôtre sans votre jeton.
• Les entrées expirent aussi d’elles-mêmes une fois le s-maxage (plus toute fenêtre SWR) écoulé; la purge n’est que le chemin rapide quand le contenu change plus tôt.
• Un déploiement de production réussi purge votre cache automatiquement, de sorte que le nouveau code est actif immédiatement.