Sessions (expérimental)

Type : boolean
Par défaut : false

Ajouté à la version : astro@5.1.0

Les sessions sont utilisées pour stocker l’état de l’utilisateur entre les demandes de pages rendues à la demande.

Cette fonctionnalité expérimentale vous permet de stocker et d’accéder à des éléments tels que le statut de connexion, le contenu du panier d’achat ou d’autres données spécifiques à l’utilisateur :

---
export const prerender = false; // Inutile avec la sortie `server`
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} articles</a>

Les sessions s’appuient sur un pilote de session configurable pour stocker les données sur l’objet session. Un cookie de session stocke un identifiant de session.

L’objet session vous permet d’interagir avec l’état de l’utilisateur stocké (par exemple, ajouter des articles à un panier d’achat) et l’identifiant de session (par exemple, supprimer le cookie d’identifiant de session lors de la déconnexion).

Activation des sessions expérimentales

Pour activer les sessions, définissez l’option experimental.session sur true. Les sessions ne fonctionnent que sur les pages avec un rendu à la demande, vous devez donc installer un adaptateur prenant en charge le rendu à la demande et vous assurer que toutes les pages qui utilisent des sessions sont définies avec prerender: false ou que output est défini sur server dans la configuration Astro.

  {
    adapter: node({
      mode: "standalone",
    }),
    experimental: {
      session: true,
    },
  }

Les sessions nécessitent un pilote de stockage pour stocker les données de session. Les adaptateurs Node et Netlify configurent automatiquement un pilote par défaut pour vous, mais d’autres adaptateurs nécessitent actuellement que vous spécifiiez un pilote manuellement. Vous pouvez utiliser n’importe quel pilote pris en charge par unstorage.

Configuration d’un pilote de session

Si vous utilisez un adaptateur qui n’a pas de pilote par défaut, ou si vous souhaitez choisir un autre pilote, vous pouvez le configurer en utilisant l’option de configuration session :

  {
    adapter: vercel(),
    session: {
      driver: "upstash",
    },
    experimental: {
      session: true,
    },
  }

Configurez session.driver avec le nom du driver Unstorage qui correspond à la fonctionnalité de stockage fournie par votre plateforme d’hébergement, comme le pilote Cloudflare KV ou le pilote Deno KV. Vous pouvez également utiliser un pilote multiplateforme tel que Upstash ou Redis.

Options du pilote

Vous pouvez également transmettre toutes les options disponibles au pilote unstorage dans un objet session.options distinct. Consultez la documentation du pilote que vous avez choisi pour connaître les options disponibles.

L’exemple suivant définit un préfixe dans base ("sessions") à utiliser pour toutes les clés dans Upstash :

  {
    adapter: vercel(),
    session: {
      driver: "upstash",
      options: {
        base: "sessions",
      },
    },
    experimental: {
      session: true,
    },
  }

Autres options de session

Vous pouvez configurer des options supplémentaires pour les sessions dans l’objet session.

`session.cookie`

Type : string | object
Par défaut : astro-session

Configure le cookie de session. Ce cookie est défini dans la réponse lorsqu’une session est générée. Aucune donnée utilisateur réelle n’est stockée dans le cookie - juste un identifiant utilisé pour identifier la session d’un utilisateur. L’option session.cookie peut être utilisée pour définir des options pour ce cookie. Vous pouvez soit fournir une chaîne de caractères, qui sera utilisée comme nom de cookie, soit un objet qui permet des options supplémentaires :

  {
    session: {
      // Si défini avec une chaîne de caractères, celle-ci sera utilisée comme nom de cookie
      // cookie: "mon-id-de-session",
      // Si défini avec un objet, cela permettra de définir des options avancées
      cookie: {
        name: "mon-id-de-session"
        sameSite: "Strict",
      },
    }
  }

`session.ttl`

Type : number
Par défaut : undefined

Une période d’expiration de durée de vie par défaut facultative pour les valeurs de session, en secondes.

Par défaut, les valeurs de session persistent jusqu’à ce qu’elles soient supprimées ou que la session soit détruite, et n’expirent pas automatiquement car un certain laps de temps s’est écoulé. Définissez session.ttl pour ajouter une période d’expiration par défaut pour vos valeurs de session. Passer une option ttl à session.set() remplacera la valeur globale par défaut pour cette entrée individuelle.

  {
    session: {
      ttl: 60 * 60, // 1 heure
    }
  }

Utilisation des sessions

Une fois que vous avez configuré un pilote, vous pouvez utiliser l’objet session pour interagir avec la session. Cet objet est accessible en tant que Astro.session dans vos composants et pages Astro et sur l’objet context dans les points de terminaison de l’API, le middleware et les actions. L’API est la même dans tous les cas.

La session est générée automatiquement lors de sa première utilisation et peut être régénérée à tout moment avec Astro.session.regenerate() ou détruite avec Astro.session.destroy().

Dans la plupart des cas, vous n’aurez besoin que d’utiliser Astro.session.get() et Astro.session.set(). Pour les autres méthodes disponibles, voir la section API.

Composants et pages Astro

Dans les composants et les pages .astro, vous pouvez accéder à l’objet session via l’objet global Astro. Par exemple, pour afficher le nombre d’articles dans un panier d’achat :

---
export const prerender = false; // Inutile avec la sortie `server`
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} articles</a>

Points d’accès à l’API

Dans les points de terminaison de l’API, l’objet de session est disponible dans l’objet context. Par exemple, pour ajouter un article à un panier d’achat :

import type { APIContext } from 'astro';

export async function POST(req: Request, context: APIContext) {
  const cart = await context.session.get('cart');
  cart.push(req.body.item);
  await context.session.set('cart', cart);
  return Response.json(cart);
}

Actions

Dans les actions, l’objet session est disponible dans l’objet context. Par exemple, pour ajouter un article à un panier d’achat :

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  addToCart: defineAction({
    input: z.object({ productId: z.string() }),
    handler: async (input, context) => {
      const cart = await context.session.get('cart');
      cart.push(input.productId);
      await context.session.set('cart', cart);
      return cart;
    },
  }),
};

Middleware

Dans le middleware, l’objet session est disponible sur l’objet context. Par exemple, pour définir l’heure de la dernière visite dans la session :

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  context.session.set('lastVisit', new Date());
  return next();
});

API Sessions

L’objet session est disponible dans tous les contextes Astro, y compris les composants, les actions et les points de terminaison API. Dans les composants, il est accessible via l’objet global Astro, et dans les actions et les points de terminaison d’API, il est disponible sur l’objet context. L’API est la même dans tous les cas.

Les valeurs sont sérialisées et désérialisées en utilisant devalue, qui est la même bibliothèque utilisée par la couche de contenu et les actions. Cela signifie que les types supportés sont les mêmes, et incluent les chaînes de caractères, les nombres, Date, Map, Set, URL, les tableaux et les objets simples.

`session.get()`

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

Renvoie la valeur de la clé donnée dans la session. Si la clé n’existe pas, il renvoie undefined.

`session.set()`

Type : (key: string, value: any, options?: { ttl: number }) => void

Définit la valeur de la clé donnée dans la session. La valeur peut être de n’importe quel type sérialisable. Cette méthode est synchrone et la valeur est immédiatement disponible pour la récupération, mais elle n’est pas enregistrée dans le backend avant la fin de la requête.

`session.regenerate()`

Type : () => void

Régénère l’identifiant de session. La meilleure pratique consiste à appeler cette fonction lorsqu’un utilisateur se connecte ou augmente ses privilèges, afin de prévenir les attaques par fixation de session.

`session.destroy()`

Type : () => void

Détruit la session, en supprimant le cookie et l’objet du backend. Elle doit être appelée lorsqu’un utilisateur se déconnecte ou que sa session est invalidée d’une autre manière.

Lecture complémentaire

Pour plus de détails et pour donner votre avis sur cette API expérimentale, consultez le RFC Sessions.

Contribuer Communauté Parrainer