API des pilotes de session d'Astro

Les sessions d’Astro vous permettent de partager des données entre les requêtes pour les pages rendues à la demande. Elles nécessitent un pilote de session Astro pour stocker les données de session.

Pilotes intégrés

Astro exporte des pilotes de session intégrés depuis astro/config :

import { sessionDrivers } from 'astro/config'

N’importe quel pilote unstorage peut être utilisé, par exemple :

astro.config.mjs

import { defineConfig, sessionDrivers } from 'astro/config'

export default defineConfig({
    session: {
        driver: sessionDrivers.redis({
            url: process.env.REDIS_URL
        }),
    }
})

Note

Certains pilotes peuvent nécessiter l’installation de paquets supplémentaires. D’autres peuvent également exiger la configuration de variables d’environnement ou d’identifiants. Consultez la documentation d’Unstorage pour plus d’informations.

Création d’un pilote de session

Un pilote de session est composé de deux parties :

• La configuration du pilote, qui indique à Astro quelle implémentation utiliser lors de l’exécution et quelle configuration transmettre
• L’implémentation du pilote, qui gère la logique de stockage à l’exécution

La configuration du pilote de session

Un SessionDriverConfig est un objet contenant un point d’entrée d’exécution (entrypoint) obligatoire et une config facultative. La méthode privilégiée pour l’implémenter consiste à exporter une fonction qui renvoie cet objet et prend la configuration comme paramètre optionnel.

L’exemple suivant définit une configuration de pilote de mémoire :

driver/config.ts

import type { SessionDriverConfig } from 'astro'

export interface Config {
    max?: number;
}

export function memoryDriver(config: Config = {}): SessionDriverConfig {
    return {
        entrypoint: new URL('./runtime.js', import.meta.url),
        config,
    }
}

Il est ensuite enregistré dans la configuration d’Astro :

astro.config.ts

import { defineConfig } from 'astro/config'
import { memoryDriver } from './driver/config'

export default defineConfig({
    session: {
        driver: memoryDriver({
            max: 500
        })
    }
})

entrypoint

Type : string | URL

Ajouté à la version : astro@6.0.0

Définit le point d’entrée pour l’implémentation du pilote.

config

Type : Record<string, any> | undefined

Ajouté à la version : astro@6.0.0

Définit la configuration sérialisable transmise à l’implémentation du pilote au moment de l’exécution.

L’implémentation du pilote de session

SessionDriver est un objet responsable du stockage, de la récupération et de la suppression des données lors de l’utilisation de sessions à l’exécution (par exemple context.session.set()). Vous pouvez l’implémenter dans votre module de pilote de session en exportant une fonction par défaut qui accepte la configuration du pilote en tant que paramètre.

L’exemple suivant implémente un pilote de mémoire :

driver/runtime.ts

import type { SessionDriver } from 'astro'
import type { Config } from './config'
import { LRUCache } from 'lru-cache'

export default function(config: Config): SessionDriver {
    const cache = new LRUCache({ max: config.max })
    return {
        setItem: async (key, value) => {
            cache.set(key, value)
        },
        getItem: async (key) => {
            return cache.get(key)
        },
        removeItem: async (key) => {
            cache.delete(key)
        },
    }
}

setItem()

Type : (key: string, value: any) => Promise<void>

Ajouté à la version : astro@6.0.0

Définit une fonction qui définit les données de session par nom de propriété.

getItem()

Type : (key: string) => Promise<any>

Ajouté à la version : astro@6.0.0

Définit une fonction qui récupère les données de session par nom de propriété.

removeItem()

Type : (key: string) => Promise<void>

Ajouté à la version : astro@6.0.0

Définit une fonction qui supprime les données de session par nom de propriété.

Compatibilité avec Unstorage

Les pilotes intégrés fournissent les mêmes pilotes qu’Unstorage. Lorsque vous avez besoin d’une personnalisation plus poussée, vous pouvez créer votre propre pilote reposant sur n’importe quel pilote Unstorage.

Installez le paquet unstorage et transmettez le spécificateur de pilote en tant que point d’entrée :

driver/config.ts

import type { SessionDriverConfig } from "astro";

export function configuredRedisDriver(): SessionDriverConfig {
  return {
    entrypoint: "unstorage/drivers/redis",
    config: {
      tls: true,
    },
  };
}

Vous pouvez également importer un pilote Unstorage et l’encapsuler dans votre propre implémentation. Cela peut être utile si vous souhaitez ajouter une logique supplémentaire au pilote ou remplacer la configuration au moment de l’exécution.

L’exemple suivant implémente un pilote Redis avec un ttl par défaut de 7 jours :

driver/runtime.ts

import type { SessionDriver } from "astro";
import redisDriver, { type RedisOptions } from "unstorage/drivers/redis";

export default function (config: RedisOptions): SessionDriver {
  const driver = redisDriver({
    ...config,
    ttl: config.ttl ?? 60 * 60 * 24 * 7, // par défaut à 7 jours
  });

  return {
    async getItem(key) {
      return await driver.getItem(key);
    },
    async setItem(key, value) {
      await driver.setItem?.(key, value, {});
    },
    async removeItem(key) {
      await driver.removeItem?.(key, {});
    },
  };
}