La Sessions API de Astro: estado del lado del servidor

HTTP no recuerda. Cada petición aterriza huérfana, sin memoria de la anterior, y esa amnesia es un rasgo de diseño del protocolo, no un defecto. Pero una aplicación real necesita hilar: saber que esta visita es la misma persona que inició sesión hace tres pantallas. Una cookie podría cargar el dato, pero es pequeña, pública y manipulable. La sesión invierte el reparto: guarda el estado en el servidor y entrega al navegador únicamente un identificador opaco. Astro.session es la API oficial de Astro para ese patrón —estable desde la 5.7 y, en Astro 7, la forma canónica de sostener estado por usuario sin arrastrar un framework al cliente—.

HTTP no recuerda: el problema que la sesión resuelve

El protocolo web trata cada petición como un suceso aislado. El servidor responde y olvida; la siguiente petición del mismo navegador llega sin ninguna marca que la ligue a la anterior. Esa ausencia de estado es lo que hace a HTTP escalable —cualquier máquina puede atender cualquier petición—, pero deja un vacío: ¿cómo sabe la aplicación que quien pide el carrito es quien acaba de añadir un producto?

La respuesta clásica es una cookie: un dato que el navegador reenvía en cada petición. El error tentador es meter el estado entero en ella —el carrito, el usuario, sus permisos—. Una cookie viaja al cliente, así que es visible para quien abra las herramientas del navegador, manipulable por quien quiera falsearla, y está limitada a unos cuatro kilobytes. Guardar ahí datos sensibles o voluminosos es pedir problemas. La sesión resuelve el dilema con una indirección: en la cookie va solo un identificador —un token aleatorio e ininteligible—, y el dato real vive en un almacén del servidor, indexado por ese id. El navegador presenta el token; el servidor lo cambia por los datos.

Astro.session: get, set, regenerate, destroy

Dentro de una página o componente .astro, la sesión se alcanza por el objeto global Astro. Fuera —en endpoints, middleware y actions— llega dentro del contexto, como context.session. La API es la misma en ambos sitios y se reduce a un puñado de métodos deliberadamente pequeños.

---
export const prerender = false; // innecesario si output es 'server'
const carrito = await Astro.session?.get('carrito');
---
<a href="/checkout">🛒 {carrito?.length ?? 0} artículos</a>

La escritura es igual de directa, pero esconde una asimetría que conviene interiorizar. Astro.session.get es asíncrono —devuelve una promesa— porque puede tener que ir al almacén de fondo, leer los bytes y deserializarlos. Astro.session.set, en cambio, es síncrono: escribe en el objeto de sesión que vive en memoria durante la petición y devuelve al instante; el volcado al backend ocurre una sola vez, al final de la petición. De ahí que se espere el get con await y el set no lo necesite.

import type { APIContext } from 'astro';

export async function POST({ session, request }: APIContext) {
  const carrito = (await session?.get('carrito')) ?? [];
  const item = await request.json();
  carrito.push(item);
  session?.set('carrito', carrito); // sincrono; se persiste al cerrar la peticion
  return Response.json({ carrito });
}

Los otros dos métodos gobiernan el ciclo de vida del identificador. Astro.session.regenerate cambia el id de sesión conservando los datos —la defensa contra la fijación de sesión, que veremos a fondo—. Astro.session.destroy aniquila la sesión: borra la cookie y el objeto del almacén, el gesto exacto del cierre de sesión. Hay además un Astro.session.load para cargar una sesión por id cuando gestionas el token por tu cuenta y no por cookie.

Un matiz que ahorra sustos: leer, modificar y volver a escribir una clave de sesión no es una operación atómica. Si dos peticiones del mismo usuario cargan el carrito a la vez, le añaden un artículo y lo guardan, la segunda escritura puede pisar a la primera y perder un ítem. Para estado que se actualiza en paralelo, evita el ciclo leer-antes-de-escribir cuando puedas —o serializa esas escrituras— en lugar de confiar en que nunca coincidan dos peticiones.

Los dos requisitos: un adapter y un driver

La Sessions API no funciona en el vacío. Necesita dos piezas que ya conoces a medias. La primera es un adapter: las sesiones solo tienen sentido en rutas renderizadas bajo demanda, porque una página horneada en el build no tiene una petición viva a la que asociar un usuario. Sin adapter no hay render en servidor, y sin render en servidor Astro.session es undefined. La segunda es un driver de almacenamiento: el lugar físico donde se guardan los datos indexados por id. Astro apoya el almacenamiento en unstorage, y ofrece un catálogo de drivers —memoria, filesystem, KV, Redis— que estudiaremos en la próxima lección.

// astro.config.mjs
import { defineConfig, sessionDrivers } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
  session: {
    driver: sessionDrivers.redis({ url: process.env.REDIS_URL }),
  },
});

Hay un atajo cómodo: los adapters de Node, Cloudflare y Netlify configuran un driver por defecto por ti —filesystem, Workers KV y Blobs respectivamente—, así que en esos destinos las sesiones funcionan casi sin tocar la configuración. Los demás adapters exigen que nombres un driver a mano. En todos los casos, la cookie que Astro planta guarda solo el identificador; su forma por defecto es { name: "astro-session", sameSite: "lax", httpOnly: true, secure: true }, unas opciones que ya delatan una intención de seguridad.

Tipar la sesión con App.SessionData

Por defecto la sesión no tiene forma declarada: Astro.session.get devuelve any, sin autocompletado ni red de seguridad del compilador. Igual que App.Locals tipa el maletín del middleware, existe App.SessionData para tipar el almacén de sesión. Se declara una sola vez en src/env.d.ts, y Astro la aplica en páginas, endpoints, middleware y actions por igual.

// src/env.d.ts
declare namespace App {
  interface SessionData {
    carrito: string[];
    userId: string;
  }
}

Con esa declaración, await Astro.session?.get('carrito') se estrecha a string[] | undefined, y un Astro.session?.set('userId', 42) se rechaza en compilación porque un número no encaja con la forma prometida. Bajo el capó, Astro serializa y deserializa los valores con devalue —la misma biblioteca que usan las content collections y las actions—, de modo que no te limitas a cadenas y números: puedes guardar Date, Map, Set, URL, arrays y objetos planos, y recuperarlos con su tipo intacto, sin el aplanamiento que impondría un JSON.stringify a secas.

flowchart LR
B[navegador con cookie de id] --> S[servidor lee el identificador]
S --> DR[el driver busca por id]
DR --> D[datos de la sesion en el almacen]
D --> R[respuesta personalizada]
style S fill:#89b4fa,color:#11111b
style D fill:#a6e3a1,color:#11111b