Middleware Cache

Le middleware Cache utilise l’API Cache des standards du Web.

Le middleware Cache prend actuellement en charge les projets Cloudflare Workers utilisant des domaines personnalisés et les projets Deno utilisant Deno 1.26 ou version ultérieure. Il est également disponible avec Deno Deploy.

Cloudflare Workers respecte l’en-tête Cache-Control et renvoie les réponses mises en cache. Pour plus de détails, consultez la documentation du cache de Cloudflare. Deno ne respecte pas les en-têtes ; si vous devez mettre à jour le cache, vous devez donc implémenter votre propre mécanisme.

Consultez la section Utilisation ci-dessous pour les instructions propres à chaque plateforme.

Importation

import { Hono } from 'hono'
import { cache } from 'hono/cache'

Utilisation

Cloudflare Workers

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
  })
)

Deno

// Must use `wait: true` for the Deno runtime
app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    wait: true,
  })
)

Mise en cache des requêtes QUERY

Le middleware Cache met également en cache les réponses aux requêtes QUERY. Comme l’exige la RFC 10008, la clé de cache d’une requête QUERY intègre une empreinte du contenu de la requête et de ses métadonnées de représentation ; les requêtes dont le corps diffère sont donc mises en cache séparément.

Les requêtes QUERY dont le corps dépasse maxQueryBodySize (64 Kio par défaut) contournent le cache.

Information

Pour permettre cela, les entrées mises en cache sont stockées sous une clé interne de la forme /.hono/cache?__hono_cache_key=..., plutôt que sous l’URL de la requête elle-même. Si vous purgez directement les entrées avec l’API Cache, par exemple en appelant caches.delete() avec l’URL d’origine de la requête, vous devrez adapter cette logique. Cela s’applique à toutes les méthodes, y compris GET.

Options

obligatoire cacheName: string | (c: Context) => string | Promise<string>

Le nom du cache. Il peut servir à stocker plusieurs caches avec des identifiants différents.

facultatif wait: boolean

Un booléen indiquant si Hono doit attendre la résolution de la Promise de la fonction cache.put avant de poursuivre la requête. Doit être défini sur true dans l’environnement Deno. La valeur par défaut est false.

facultatif cacheControl: string

Une chaîne de directives pour l’en-tête Cache-Control. Consultez la documentation MDN pour plus d’informations. Si cette option n’est pas fournie, aucun en-tête Cache-Control n’est ajouté aux requêtes.

facultatif vary: string | string[]

Définit l’en-tête Vary de la réponse. Si la réponse d’origine contient déjà un en-tête Vary, les valeurs sont fusionnées et les doublons supprimés. Définir cette option sur * provoque une erreur. Pour en savoir plus sur l’en-tête Vary et ses conséquences sur les stratégies de cache, consultez la documentation MDN.

facultatif keyGenerator: (c: Context) => string | Promise<string>

Génère les clés de chaque requête dans le cache cacheName. Cela permet de mettre en cache les données en fonction des paramètres de requête ou de contexte. La valeur par défaut est c.req.url. Pour les requêtes QUERY, la clé inclut également une empreinte du contenu de la requête et de ses métadonnées de représentation.

facultatif maxQueryBodySize: number

La taille maximale, en octets, du corps d’une requête QUERY pouvant être mise en cache. Les requêtes QUERY dont le corps est plus volumineux contournent le cache. La valeur par défaut est 65536 (64 Kio).

facultatif cacheableStatusCodes: number[]

Un tableau des codes de statut à mettre en cache. La valeur par défaut est [200]. Utilisez cette option pour mettre en cache des réponses ayant des codes de statut précis.

app.get(
  '*',
  cache({
    cacheName: 'my-app',
    cacheControl: 'max-age=3600',
    cacheableStatusCodes: [200, 404, 412],
  })
)

facultatif onCacheNotAvailable: ((reason: string) => void | Promise<void>) | false

Une fonction de rappel ou false contrôlant le comportement lorsque l’API Cache n’est pas disponible dans la portée globale, ou lorsque la mise en cache de QUERY ne peut pas utiliser Web Crypto. La fonction de rappel reçoit la raison. Par défaut, cette raison est journalisée avec console.log. Vous pouvez fournir une fonction personnalisée pour adapter le comportement, ou définir l’option sur false pour supprimer complètement le journal.

// Custom logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: () => {
      console.log('Custom log: Cache API is not available.')
    },
  })
)

// Suppress logging
app.use(
  cache({
    cacheName: 'my-app-v1',
    onCacheNotAvailable: false,
  })
)