+
+
+
+**Type :** `{ max?: number; query?: object }`
+**Par défaut :** `{ max: 1000 }`
+
+
+**Type :** `number`
+**Par défaut :** `1000`
+
+
+**Type :** `{ sort?: boolean; include?: string[]; exclude?: string[]; }`
+
+
+**Type :** `boolean`
+**Par défaut :** `true`
+
+
+**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']`
+
+ +**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 : + +```js title="astro.config.mjs" +memoryCache({ + query: { include: ['page', 'sort'] }, +}); +``` + +Une erreur est émise en cas d'utilisation conjointe avec [`exclude`](#queryexclude). + +### 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`](https://developer.mozilla.org/fr/docs/Web/HTTP/Reference/Headers/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`](#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()`](#fournisseur-de-cache-en-mémoire-intégré). + +L'exemple suivant montre un assistant de configuration qui accepte des options typées et pointe vers un module d'exécution : + +```ts title="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 : + +```js title="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`](#cacheprovider) : + +```ts title="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](#utilitaires-pour-les-fournisseurs-de-cache) 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. + +```ts +import { + buildCacheControlDirectives, + pathTag, + setConditionalHeaders, + collectInvalidationTags, + normalizeTags, +} from 'astro/cache/provider-utils'; +``` + +### `buildCacheControlDirectives()` + +
+
+**Type :** (options: CacheOptions, extraDirectives?: string[]) => string | undefined
+
+ +**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 })`](/fr/reference/api-reference/#cacheinvalidate) sur les plateformes qui n'offrent que la purge reposant sur les étiquettes. + +### `setConditionalHeaders()` + +
+
+**Type :** (headers: Headers, options: CacheOptions) => void
+
+
+**Type :** (options: InvalidateOptions) => string[]
+
+ +**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` : + +```ts +import type { + CacheOptions, + CacheProvider, + CacheProviderConfig, + CacheProviderFactory, + InvalidateOptions, +} from "astro"; +``` + +### `CacheOptions` + +Décrit les options transmises à un fournisseur de cache. + ++ +**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()`](/fr/reference/api-reference/#cacheset). + +#### `CacheOptions.lastModified` + ++ +**Type :** `Date` +
+ +Indique la date de dernière modification. Lorsque plusieurs appels à [`cache.set()`](/fr/reference/api-reference/#cacheset) 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
+
+
+**Type :** (context: \{ request: Request; url: URL; waitUntil?: (promise: Promise\
+
+
+**Type :** (options: InvalidateOptions) => Promise\
+
+
+**Type :** `{ entrypoint: string | URL; config?: Record
+
+**Type :** (config: Record\
+
+ +**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. diff --git a/src/content/docs/fr/reference/modules/astro-config.mdx b/src/content/docs/fr/reference/modules/astro-config.mdx index 4c3b0abc29deb..41eb9d5a2b386 100644 --- a/src/content/docs/fr/reference/modules/astro-config.mdx +++ b/src/content/docs/fr/reference/modules/astro-config.mdx @@ -312,10 +312,10 @@ Récupère la configuration de Vite à utiliser en fusionnant un objet de config ### `memoryCache()`
-**Type :** (config?: MemoryCacheProviderOptions) => CacheProviderConfig\
+**Type :** (config?: MemoryCacheProviderOptions) => CacheProviderConfig\