실험적 세션

타입: boolean
기본값: false

Added in: astro@5.1.0

세션은 요청 시 렌더링되는 페이지에 대한 요청 사이에 사용자 상태를 저장하는 데 사용됩니다.

이 실험적 기능을 사용하면 로그인 상태, 장바구니 내용 또는 기타 사용자별 데이터와 같은 항목을 저장하고 액세스할 수 있습니다:

---
export const prerender = false; // 'server' 출력에는 필요하지 않습니다.
const cart = await Astro.session.get('cart');
---

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

세션은 session 객체에 데이터를 저장하기 위해 구성 가능한 세션 driver에 의존합니다. 세션 쿠키는 식별 세션 ID를 저장합니다.

session 객체를 사용하면 저장된 사용자 상태(예: 장바구니에 항목 추가) 및 세션 ID(예: 로그아웃 시 세션 ID 쿠키 삭제)와 상호 작용할 수 있습니다.

실험적 세션 활성화

세션을 활성화하려면 experimental.session 플래그를 true로 설정하세요. 세션은 온디맨드 렌더링 페이지에서만 작동하므로 온디맨드 렌더링을 지원하는 어댑터를 설치하고 세션을 사용하는 모든 페이지가 prerender: false로 설정되었는지 또는 Astro 구성에서 output이 server로 설정되었는지 확인해야 합니다.

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

세션을 사용하기 위해서는 세션 데이터를 저장하기 위한 스토리지 드라이버가 필요합니다. Node 및 Netlify 어댑터는 자동으로 기본 드라이버를 구성하지만 현재 다른 어댑터는 드라이버를 수동으로 지정해야 합니다. unstorage의 지원되는 드라이버를 사용할 수 있습니다.

세션 드라이버 구성

기본 드라이버가 없는 어댑터를 사용하거나 다른 드라이버를 선택하려면 session 구성 옵션을 사용하여 드라이버를 구성할 수 있습니다.

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

session.driver를 호스팅 플랫폼에서 제공하는 스토리지 기능에 해당하는 unstorage driver 이름(예: Cloudflare KV 드라이버 또는 Deno KV 드라이버로 구성합니다. Upstash 또는 Redis와 같은 크로스 플랫폼 드라이버를 사용할 수도 있습니다.

드라이버 옵션

session.options 객체를 통해 unstorage 드라이버에 사용 가능한 모든 옵션을 전달할 수도 있습니다. 사용 가능한 옵션은 선택한 드라이버의 문서를 참조하세요.

다음 예제는 Upstash의 모든 키에 사용할 "sessions" 접두사를 base로 설정합니다.

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

기타 세션 옵션

session 객체에서 세션에 대한 추가 옵션을 구성할 수 있습니다.

`session.cookie`

타입: string | object
기본값: astro-session

세션 쿠키를 구성합니다. 이 쿠키는 세션이 생성될 때 응답에 설정됩니다. 실제 사용자 데이터는 쿠키에 저장되지 않고, 사용자 세션을 식별하는 데 사용되는 ID만 저장됩니다. session.cookie 옵션을 사용하여 이 쿠키에 대한 옵션을 설정할 수 있습니다. 쿠키 이름으로 사용될 string을 제공하거나 추가 옵션을 허용하는 객체를 제공할 수 있습니다.

  {
    session: {
      // 문자열로 설정하면 쿠키 이름으로 사용됩니다.
      // cookie: "my-session-id",
      // 객체로 설정하면 고급 옵션을 설정할 수 있습니다.
      cookie: {
        name: "my-session-id"
        sameSite: "Strict",
      },
    }
  }

`session.ttl`

타입: number
기본값: undefined

세션 값에 대한 선택적 기본 수명(TTL, time-to-live) 만료 기간(초 단위)입니다.

기본적으로 세션 값은 삭제되거나 세션이 파괴될 때까지 유지되며 특정 시간 경과로 인해 자동으로 만료되지 않습니다. session.ttl을 설정하여 세션 값에 대한 기본 만료 기간을 추가합니다. session.set()에 ttl 옵션을 전달하면 해당 개별 항목에 대한 전역 기본값을 재정의합니다.

  {
    session: {
      ttl: 60 * 60, // 1 시간
    }
  }

세션 사용

드라이버를 구성하면 session 객체를 사용하여 세션과 상호 작용할 수 있습니다. 객체는 Astro 컴포넌트와 페이지에서는 Astro.session으로, API 엔드포인트, 미들웨어 및 액션의 context 객체에서 접근할 수 있습니다. API는 모든 경우에 동일합니다.

세션은 처음 사용될 때 자동으로 생성되며 Astro.session.regenerate()를 사용하여 언제든지 재생성하거나 Astro.session.destroy()를 사용하여 파괴할 수 있습니다.

대부분의 경우 Astro.session.get()과 Astro.session.set()만 사용하면 됩니다. 사용 가능한 다른 메서드는 API 섹션을 참조하세요.

Astro 컴포넌트 및 페이지

.astro 컴포넌트와 페이지에서는 전역 Astro 객체를 통해 세션 객체에 접근할 수 있습니다. 예를 들어, 장바구니의 항목 수를 표시하는 방법은 다음과 같습니다:

---
export const prerender = false; // 'server' 출력에는 필요하지 않습니다.
const cart = await Astro.session.get('cart');
---

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

API 엔드포인트

API 엔드포인트에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:

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);
}

액션

액션에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:

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;
    },
  }),
};

미들웨어

미들웨어에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 세션에서 마지막 방문 시간을 설정하는 방법은 다음과 같습니다:

import { defineMiddleware } from 'astro:middleware';

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

세션 API

세션은 처음 액세스할 때 자동으로 생성됩니다. 세션 객체는 컴포넌트, 액션 및 API 엔드포인트를 포함한 모든 Astro 컨텍스트에서 사용할 수 있습니다. 컴포넌트에서는 전역 Astro 객체를 통해 액세스하고, 액션 및 API 엔드포인트에서는 context 객체에서 사용할 수 있습니다. API는 모든 경우에 동일합니다.

값은 콘텐츠 컬렉션 및 액션에 사용되는 것과 동일한 라이브러리인 devalue를 사용하여 직렬화 및 역직렬화됩니다. 즉, 지원되는 타입은 동일하며 문자열, 숫자, Date, Map, Set, URL, 배열 및 일반 객체를 포함합니다.

`session.get()`

타입: (key: string) => Promise<any>

세션에서 주어진 키의 값을 반환합니다. 키가 존재하지 않으면 undefined를 반환합니다.

`session.set()`

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

세션에서 주어진 키의 값을 설정합니다. 값은 직렬화 가능한 모든 타입이 될 수 있습니다. 이 메서드는 동기적이며 값을 즉시 검색할 수 있지만, 요청이 끝날 때까지 백엔드에 저장되지 않습니다.

`session.regenerate()`

타입: () => void

세션 ID를 재생성합니다. 세션 고정 공격을 방지하기 위해 사용자가 로그인하거나 권한을 높일 때 호출하는 것이 가장 좋습니다.

`session.destroy()`

타입: () => void

세션을 파괴하고 쿠키와 객체를 백엔드에서 삭제합니다. 사용자가 로그아웃하거나 세션이 무효화될 때 호출해야 합니다.

더 알아보기

이 실험적 API에 대한 자세한 내용과 피드백을 제공하려면 세션 RFC를 참조하세요.

기여하기 커뮤니티 후원하기