i18n(ko-KR): create session.mdx

src/content/docs/ko/reference/experimental-flags/sessions.mdx

@@ -0,0 +1,237 @@
+---
+title: 실험적 세션
+sidebar:
+  label: 세션
+i18nReady: true
+---
+
+import Since from '~/components/Since.astro';
+import ReadMore from '~/components/ReadMore.astro';
+
+<p>
+
+**타입:** `SessionConfig`<br />
+**기본값:** `undefined`<br />
+
+<Since v="5.1.0" />
+</p>
+
+세션은 [요청 시 렌더링되는 페이지](/ko/guides/on-demand-rendering/)에 대한 요청 사이에 사용자 상태를 저장하는 데 사용됩니다.
+
+이 실험적 기능을 사용하면 로그인 상태, 장바구니 내용 또는 기타 사용자별 데이터와 같은 항목을 저장하고 액세스할 수 있습니다:
+
+```astro title="src/components/CartButton.astro" {3}
+---
+export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.
+const cart = await Astro.session.get('cart');
+---
+
+<a href="/checkout">🛒 {cart?.length ?? 0} items</a>
+```
+
+세션은 `session` 객체에 데이터를 저장하기 위해 [구성 가능한 세션 `driver`](#실험적-세션-활성화)에 의존합니다. [세션 쿠키](#쿠키)는 식별 세션 ID를 저장합니다.
+
+[`session` 객체](#세션-api)를 사용하면 저장된 사용자 상태(예: 장바구니에 항목 추가) 및 세션 ID(예: 로그아웃 시 세션 ID 쿠키 삭제)와 상호 작용할 수 있습니다.
+
+## 실험적 세션 활성화
+
+현재 `experimental.sessions`의 초기 릴리스에서는 Astro의 공식 서버 어댑터가 아직 플랫폼의 기본 스토리지 기능을 기반으로 하는 기본 세션 드라이버를 제공하도록 업데이트되지 않았습니다. 이러한 기능이 내장될 때까지 [어댑터를 추가하는 것](/ko/guides/on-demand-rendering/#어댑터-추가) 외에도 `experimental.sessions` 구성 객체에서 직접 `driver`를 지정해야 합니다.
+
+다음 섹션에서는 각 어댑터에 대해 권장되는 드라이버를 보여줍니다. (이 기능의 안정적인 릴리스에서는 자동으로 구성됩니다.) 또는 [unstorage의 지원되는 드라이버](https://unstorage.unjs.io/drivers/) 중 하나를 지정할 수 있습니다.
+
+### Node 어댑터로 세션 구성
+
+Node 어댑터는 [파일시스템 드라이버](https://unstorage.unjs.io/drivers/fs)와 호환됩니다. 공유 파일시스템이 없는 서버리스 환경에서는 사용할 수 없습니다.
+
+```js title="astro.config.mjs" ins={6}
+	{
+    adapter: node({ mode: 'standalone' }),
+		experimental: {
+      session: {
+        // 필수: unstorage 드라이버의 이름
+        driver: "fs",
+      },
+    },
+	}
+```
+
+### 다른 어댑터의 세션 드라이버 구성
+
+[Netlify Blobs 드라이버(`netlify-blobs`)](https://unstorage.unjs.io/drivers/netlify), [Cloudflare KV 드라이버(`cloudflare-kv-binding`)](https://unstorage.unjs.io/drivers/cloudflare) 또는 [Deno KV 드라이버(`deno-kv`)](https://unstorage.unjs.io/drivers/deno)와 같이 호스팅 플랫폼에서 제공하는 스토리지 기능에 해당하는 [unstorage `driver` 이름](https://unstorage.unjs.io/drivers/)을 선택하세요. [Upstash](https://unstorage.unjs.io/drivers/upstash)나 [Redis](https://unstorage.unjs.io/drivers/redis)와 같은 크로스 플랫폼 드라이버를 사용할 수도 있습니다.
+
+:::note
+일부 드라이버는 추가 패키지를 설치해야 할 수 있습니다. 예를 들어, `netlify-blobs` 드라이버는 `@netlify/blobs` 패키지가 필요하고, Upstash는 `@upstash/redis` 패키지가 필요합니다. 일부 드라이버는 환경 변수나 인증 정보를 설정해야 할 수도 있습니다.
+
+<ReadMore>[unstorage 드라이버 문서](https://unstorage.unjs.io/drivers)에서 자세한 정보를 확인하세요.</ReadMore>
+:::
+
+### 드라이버 옵션
+
+unstorage 드라이버에 사용 가능한 모든 옵션을 별도의 `session.options` 객체로 전달할 수도 있습니다. 다음 예제는 [Netlify Blobs](https://unstorage.unjs.io/drivers/netlify) 드라이버를 구성하면서 `name`을 제공하고 `consistency` 모드를 지정합니다:
+
+```js title="astro.config.mjs" ins={7-11}
+  {
+    adapter: netlify(),
+    experimental: {
+      session: {
+        // unstorage 드라이버의 이름은 kebab-case 형식으로 지정합니다.
+        driver: "netlify-blobs",
+        options: {
+          name: 'astro-sessions',
+          // 세션을 사용하기 위해 consistency를 strong으로 지정합니다.
+          consistency: 'strong',
+        }
+      },
+    },
+  }
+```
+
+## 세션 사용
+
+드라이버를 구성하면 `session` 객체를 사용하여 세션과 상호 작용할 수 있습니다. 이 객체는 Astro 컴포넌트와 페이지에서는 `Astro.session`으로, API 엔드포인트, 미들웨어 및 액션의 `context` 객체에서 접근할 수 있습니다. API는 모든 경우에 동일합니다.
+
+대부분의 경우 [`Astro.session.get()`](#sessionget)과 [`Astro.session.set()`](#sessionset)만 사용하면 됩니다. 다른 사용 가능한 메서드는 [API 섹션](#세션-api)을 참조하세요.
+
+### Astro 컴포넌트 및 페이지
+
+`.astro` 컴포넌트와 페이지에서는 전역 `Astro` 객체를 통해 세션 객체에 접근할 수 있습니다. 예를 들어, 장바구니의 항목 수를 표시하는 방법은 다음과 같습니다:
+
+```astro title="src/components/CartButton.astro" "Astro.session"
+---
+export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.
+const cart = await Astro.session.get('cart');
+---
+
+<a href="/checkout">🛒 {cart?.length ?? 0} items</a>
+```
+
+### API 엔드포인트
+
+API 엔드포인트에서는 `context` 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:
+
+```ts title="src/pages/api/addToCart.ts" "context.session"
+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` 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:
+
+```ts title="src/actions/addToCart.ts" "context.session"
+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;
+    },
+  }),
+};
+```
+
+### 미들웨어
+
+:::note
+현재 엣지 미들웨어에서는 세션이 지원되지 않습니다.
+:::
+
+미들웨어에서는 `context` 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 세션에서 마지막 방문 시간을 설정하는 방법은 다음과 같습니다:
+
+```ts title="src/middleware.ts" "context.session"
+import { defineMiddleware } from 'astro:middleware';
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  context.session.set('lastVisit', new Date());
+  return next();
+});
+```
+
+## 쿠키
+
+세션은 처음 접근할 때 생성되며 응답에 세션 ID 쿠키가 설정됩니다. 쿠키에는 실제 사용자 데이터가 저장되지 않고 사용자의 세션을 식별하는 데 사용되는 ID만 저장됩니다. 세션은 [`Astro.session.regenerate()`](#sessionregenerate)를 사용하여 언제든지 재생성할 수 있으며, [`Astro.session.destroy()`](#sessiondestroy)를 사용하여 삭제할 수 있습니다.
+
+### `session.cookie`
+
+<p>
+
+**타입:** `string` | `object`<br />
+**기본값:** `undefined`<br />
+
+</p>
+
+쿠키 옵션을 설정하기 위한 선택적 속성입니다. `cookie.name` 속성은 문자열을 제공하여 자동으로 설정할 수 있습니다. 추가 옵션을 구성하려면 객체를 제공하세요.
+
+```js title="astro.config.mjs" {5} ins={7-10}
+  {
+    experimental: {
+      session: {
+        // 문자열로 설정하면 쿠키 이름으로 사용됩니다
+        // cookie: "my-session-id",
+        // 객체로 설정하면 고급 옵션을 설정할 수 있습니다
+        cookie: {
+          name: "my-session-id"
+          sameSite: "Strict",
+        },
+      }
+    }
+  }
+```
+
+## 세션 API
+
+세션 객체는 컴포넌트, 액션 및 API 엔드포인트를 포함한 모든 Astro 컨텍스트에서 사용할 수 있습니다. 컴포넌트에서는 전역 `Astro` 객체를 통해 접근하고, 액션과 API 엔드포인트에서는 `context` 객체에서 사용할 수 있습니다. API는 모든 경우에 동일합니다.
+
+값은 콘텐츠 레이어와 액션에서 사용되는 것과 같은 라이브러리인 [devalue](https://github.com/Rich-Harris/devalue)를 사용하여 직렬화 및 역직렬화됩니다. 이는 지원되는 타입이 동일하며, 문자열, 숫자, `Date`, `Map`, `Set`, `URL`, 배열 및 일반 객체를 포함한다는 의미입니다.
+
+
+### `session.get()` 
+
+<p>
+
+**타입**: `(key: string) => Promise<any>`
+</p>
+
+세션에서 주어진 키의 값을 반환합니다. 키가 존재하지 않으면 `undefined`를 반환합니다.
+
+### `session.set()`
+
+<p>
+
+**타입**: `(key: string, value: any, options?: { ttl: number }) => void`
+</p>
+
+세션에서 주어진 키의 값을 설정합니다. 값은 직렬화 가능한 모든 타입이 될 수 있습니다.
+
+### `session.regenerate()`
+
+<p>
+
+**타입**: `() => void`
+</p>
+
+세션 ID를 재생성합니다. 세션 고정 공격을 방지하기 위해 사용자가 로그인하거나 권한을 높일 때 호출하는 것이 가장 좋습니다.
+
+### `session.destroy()`
+
+<p>
+
+**타입**: `() => void`
+</p>
+
+세션을 파괴하고 쿠키와 객체를 백엔드에서 삭제합니다. 사용자가 로그아웃하거나 세션이 무효화될 때 호출해야 합니다.
+
+## 더 알아보기
+
+이 실험적 API에 대한 자세한 내용과 피드백을 제공하려면 [세션 RFC](https://github.com/withastro/roadmap/blob/sessions/proposals/0054-sessions.md)를 참조하세요.

src/content/docs/ko/tutorial/3-components/1.mdx

@@ -153,4 +153,4 @@ HTML을 생성하지만 웹 사이트의 새 페이지가 되지 않는 `.astro`
 
 - [Astro 컴포넌트 개요](/ko/basics/astro-components/)
 
-- [리팩터링](https://refactoring.com/) <Badge class="neutral-badge" text="외부 링크" />
+- [리팩터링](https://refactoring.com/) <Badge class="neutral-badge" text="외부 링크" />