API des fournisseurs de cache d'Astro

Ajouté à la version : astro@7.0.0 Nouveau

L’API des fournisseurs de cache d’Astro permet de configurer et de gérer le comportement de mise en cache des routes. Cette API inclut une prise en charge intégrée d’un fournisseur de cache en mémoire et la possibilité de créer des fournisseurs personnalisés pour diverses stratégies de mise en cache et environnements d’exécution.

Qu’est-ce qu’un fournisseur de cache ?

Le comportement du cache est déterminé par le fournisseur de cache configuré. Les fournisseurs se répartissent en deux catégories :

Fournisseurs pour CDN

Les fournisseurs pour CDN traduisent les directives de cache en en-têtes de réponse (par exemple, CDN-Cache-Control, Cache-Tag) et s’appuient sur un CDN ou un proxy inverse pour gérer la mise en cache. Ces en-têtes internes sont supprimés avant que la réponse n’atteigne le client.

Un fournisseur pour CDN implémente setHeaders() pour produire les en-têtes appropriés.

Fournisseurs pour l’environnement d’exécution

Les fournisseurs pour l’environnement d’exécution implémentent onRequest() afin d’intercepter les requêtes et de mettre en cache les réponses en mémoire. Ils ajoutent un en-tête de réponse X-Astro-Cache pour l’observabilité :

• HIT : réponse servie depuis le cache
• MISS : réponse actualisée et stockée dans le cache
• STALE : réponse périmée servie pendant la revalidation en arrière-plan

Fournisseur de cache en mémoire intégré

Astro inclut un fournisseur de cache LRU en mémoire intégré pour l’environnement d’exécution, adapté aux déploiements à instance unique. Importez memoryCache() depuis astro/config :

astro.config.mjs

import { defineConfig, memoryCache } from 'astro/config';

export default defineConfig({
  cache: {
    provider: memoryCache({ max: 500 }),
  },
});

Options de memoryCache()

Type : { max?: number; query?: object }
Par défaut : { max: 1000 }

Configure le fournisseur de cache en mémoire.

max

Type : number
Par défaut : 1000

Définit le nombre maximum d’entrées à conserver dans le cache. Lorsque le cache dépasse cette limite, l’entrée la moins récemment utilisée est supprimée.

query

Type : { sort?: boolean; include?: string[]; exclude?: string[]; }

Contrôle la manière dont les paramètres de requête sont gérés dans les clés de cache.

query.sort

Type : boolean
Par défaut : true

Détermine si les paramètres de requête doivent être triés par ordre alphabétique. Ceci est utile lorsque l’ordre des paramètres est important et pour garantir que leur ordre n’affecte pas la clé de cache.

Définissez l’option sur false pour désactiver le tri et mettre en cache les URL avec des ordres de paramètres de requête différents séparément.

query.exclude

Type : string[]
Par défaut : ['utm_*', 'fbclid', 'gclid', 'gbraid', 'wbraid', 'dclid', 'msclkid', 'twclid', 'li_fat_id', 'mc_cid', 'mc_eid', '_ga', '_gl', '_hsenc', '_hsmi', '_ke', 'oly_anon_id', 'oly_enc_id', 'rb_clickid', 's_cid', 'vero_id', 'wickedid', 'yclid', '__s', 'ref']

Liste les paramètres de requête à exclure de la clé de cache. Cela prend en charge les caractères génériques glob (par exemple "utm_*") et, par défaut, exclut les paramètres de suivi et de mesure d’audience courants.

Définissez sur [] pour inclure tous les paramètres de requête dans la clé de cache :

astro.config.mjs

memoryCache({
  query: { exclude: [] },
});

Une erreur est émise en cas d’utilisation conjointe avec include.

query.include

Type : string[]

Liste les noms des paramètres de requête à inclure dans la clé de cache. Lorsqu’elle est définie, tous les autres paramètres sont ignorés, y compris les exclusions de paramètres de suivi par défaut.

L’exemple suivant n’utilise que les paramètres page et sort dans la clé de cache, en ignorant tous les autres :

astro.config.mjs

memoryCache({
  query: { include: ['page', 'sort'] },
});

Une erreur est émise en cas d’utilisation conjointe avec exclude.

Comportement des clés de cache

Le fournisseur de mémoire normalise automatiquement les clés de cache pour de meilleurs taux de réussite :

• Tri des paramètres de requête : Les paramètres sont triés par ordre alphabétique, donc /page?b=2&a=1 et /page?a=1&b=2 correspondent à la même entrée de cache.
• Exclusion des paramètres de suivi : Les paramètres de mesure d’audience et de suivi courants (par exemple, utm_source, fbclid, gclid) sont exclus de la clé de cache par défaut. Cela empêche la fragmentation du cache à partir des liens marketing sans affecter le contenu de votre page.
• Prise en charge de l’en-tête Vary : Lorsqu’une réponse inclut un en-tête Vary, le fournisseur de mémoire utilise les valeurs des en-têtes de requête spécifiés pour créer des entrées de cache distinctes pour chaque variante. Par exemple, une réponse avec Vary: Accept-Language mettra en cache différentes versions pour différentes langues.

Note

L’en-tête Cookie est toujours ignoré pour le système de clés de cache reposant sur Vary car sa cardinalité est extrêmement élevée (chaque utilisateur a généralement des cookies différents), ce qui le rend effectivement impossible à mettre en cache.

Création d’un fournisseur de cache personnalisé

Un fournisseur de cache se compose de deux parties :

1. Le module d’exécution — Un fichier qui exporte par défaut une fonction CacheProviderFactory. Ce module est intégré à votre sortie SSR, il doit donc être indépendant de l’environnement d’exécution : évitez les modules intégrés de Node.js (par exemple node:fs, node:path) sauf si votre environnement d’exécution cible les prend en charge.

2. L’assistant de configuration — Une fonction exportée que les utilisateurs peuvent appeler dans astro.config.mjs. Elle renvoie un objet CacheProviderConfig qui indique à Astro où trouver le module d’exécution et quelles options lui transmettre. Il s’agit du même modèle que celui utilisé par le fournisseur intégré memoryCache().

L’exemple suivant montre un assistant de configuration qui accepte des options typées et pointe vers un module d’exécution :

my-provider/config.ts

import type { CacheProviderConfig } from 'astro';

interface MyProviderOptions {
  apiKey: string;
  region?: string;
}

export function myCache(options: MyProviderOptions): CacheProviderConfig {
  return {
    entrypoint: 'my-provider/runtime', // résolu depuis la racine du projet
    config: options, // transmis à la fabrique lors de l'exécution
  };
}

L’assistant de configuration est ensuite appelé dans la configuration d’Astro :

astro.config.mjs

import { defineConfig } from 'astro/config';
import { myCache } from 'my-provider/config';

export default defineConfig({
  cache: {
    provider: myCache({ apiKey: '...' }),
  },
});

Le module d’exécution exporte par défaut une fabrique qui reçoit la config sérialisée et renvoie un CacheProvider :

my-provider/runtime.ts

import type { CacheProviderFactory } from 'astro';

const factory: CacheProviderFactory = (config) => {
  return {
    name: 'my-cache-provider',

    // Style CDN : traduire les options de cache en en-têtes de réponse
    setHeaders(options) {
      const headers = new Headers();
      if (options.maxAge !== undefined) {
        let value = `max-age=${options.maxAge}`;
        if (options.swr !== undefined) {
          value += `, stale-while-revalidate=${options.swr}`;
        }
        headers.set('CDN-Cache-Control', value);
      }
      if (options.tags?.length) {
        headers.set('Cache-Tag', options.tags.join(','));
      }
      return headers;
    },

    // Style environnement d'exécution : intercepter les requêtes (facultatif)
    async onRequest(context, next) {
      // Vérifier le cache, appeler next(), stocker la réponse...
      return next();
    },

    // Gérer les demandes d'invalidation
    async invalidate(options) {
      // Purger par étiquettes ou chemin...
    },
  };
};

export default factory;

Lors de la création d’un fournisseur CDN, Astro fournit des utilitaires partagés pour créer des en-têtes de contrôle de cache et des étiquettes d’invalidation reposant sur les chemins.

Utilitaires pour les fournisseurs de cache

Astro exporte des utilitaires partagés pour les auteurs de fournisseurs de CDN depuis astro/cache/provider-utils. Il s’agit des mêmes utilitaires que ceux utilisés par les fournisseurs officiels Netlify, Vercel et Cloudflare.

import {
  buildCacheControlDirectives,
  pathTag,
  setConditionalHeaders,
  collectInvalidationTags,
  normalizeTags,
} from 'astro/cache/provider-utils';

buildCacheControlDirectives()

Type : (options: CacheOptions, extraDirectives?: string[]) => string | undefined

Génère une chaîne de directives cache-control (p. ex. "public, max-age=300, stale-while-revalidate=60") à partir de CacheOptions, sans inclure le nom de l’en-tête, afin que chaque fournisseur puisse appliquer le sien (comme Netlify-CDN-Cache-Control ou Cloudflare-CDN-Cache-Control). Utilisez le paramètre extraDirectives pour ajouter en début de chaîne des directives spécifiques à la plateforme, telles que public ou durable. Renvoie undefined en l’absence de directives de mise en cache.

pathTag()

Type : (path: string) => string

Génère une étiquette de cache pour un chemin donné (astro-path:{path}). Utilisé pour prendre en charge invalidate({ path }) sur les plateformes qui n’offrent que la purge reposant sur les étiquettes.

setConditionalHeaders()

Type : (headers: Headers, options: CacheOptions) => void

Définit les en-têtes Last-Modified et ETag dans un objet Headers à partir des valeurs correspondantes de CacheOptions.

collectInvalidationTags()

Type : (options: InvalidateOptions) => string[]

Collecte toutes les étiquettes nécessaires pour invalider les options données, y compris l’étiquette de chemin lorsque options.path est défini. Utilisé par les fournisseurs qui implémentent l’invalidation par chemin via des étiquettes plutôt que par purge native de chemin.

normalizeTags()

Type : (tags: string | string[] | undefined) => string[]

Normalise la valeur d’une étiquette en un tableau de chaînes de caractères plat.

Référence des types de fournisseurs de cache

Les types suivants peuvent être importés depuis le module astro :

import type {
  CacheOptions,
  CacheProvider,
  CacheProviderConfig,
  CacheProviderFactory,
  InvalidateOptions,
} from "astro";

CacheOptions

Décrit les options transmises à un fournisseur de cache.

Découvrez comment utiliser les options de cache pour contrôler le comportement de mise en cache.

CacheOptions.maxAge

Type : number

Définit le temps en secondes pendant lequel la réponse est considérée comme fraîche.

CacheOptions.swr

Type : number

Spécifie la durée de la fenêtre « stale-while-revalidate » en secondes. Un contenu périmé est servi pendant qu’une réponse actualisée est générée en arrière-plan.

CacheOptions.tags

Type : string[]

Une liste d’étiquettes de cache pour une invalidation ciblée. Les étiquettes s’accumulent au fil des appels successifs à cache.set().

CacheOptions.lastModified

Type : Date

Indique la date de dernière modification. Lorsque plusieurs appels à cache.set() fournissent lastModified, l’appel le plus récent prévaut.

CacheOptions.etag

Type : string

Indique l’étiquette d’entité pour les requêtes conditionnelles.

CacheProvider

Décrit un fournisseur utilisé pour la mise en cache. Cela nécessite les propriétés name et invalidate() et accepte des propriétés optionnelles.

CacheProvider.name

Type : string

Un nom unique pour le fournisseur, utilisé dans les journaux et pour l’identification.

CacheProvider.setHeaders()

Type : (options: CacheOptions, request: Request) => Headers

Convertit les options de mise en cache en en-têtes de réponse. Cette fonction est appelée après le rendu de la réponse, mais avant son envoi au client. Ces en-têtes sont retirés de la réponse finale.

La requête (request) entrante est transmise en tant que second argument, ce qui permet au fournisseur de lire l’URL ou les en-têtes de la requête. Cela peut s’avérer utile pour étiqueter automatiquement les réponses avec leur chemin d’accès en vue d’une invalidation reposant sur le chemin.

CacheProvider.onRequest()

Type : (context: { request: Request; url: URL; waitUntil?: (promise: Promise<unknown>) => void }, next: MiddlewareNext) => Promise<Response>

Intercepte les requêtes pour mettre en œuvre la mise en cache à l’exécution. L’objet context inclut une fonction waitUntil() (lorsqu’elle est disponible dans l’environnement d’exécution) pour les tâches en arrière-plan, telles que la stratégie « stale-while-revalidate ».

CacheProvider.invalidate()

Type : (options: InvalidateOptions) => Promise<void>

Gère les demandes de purge par étiquette ou par chemin.

CacheProviderConfig

Type : { entrypoint: string | URL; config?: Record<string, any> }

L’objet de configuration transmis à cache.provider. Utilisez une fonction d’assistance (par exemple, memoryCache()) pour une configuration garantissant la sûreté du typage.

CacheProviderFactory

Type : (config: Record<string, any> | undefined) => CacheProvider

Le type de fonction de fabrique. Reçoit l’objet de configuration sérialisable du fournisseur issu de la configuration d’Astro.

InvalidateOptions

Décrit les options transmises à la méthode invalidate() du fournisseur.

InvalidateOptions.path

Type : string

Chemin exact à invalider. Pas de prise en charge des motifs glob ou des caractères génériques.

InvalidateOptions.tags

Type : string | string[]

Étiquette ou étiquettes à invalider. Toutes les entrées avec des étiquettes correspondantes sont purgées.