# Cloudflare Durable Objects + WebSocket 실시간 카운터

이 프로젝트는 SvelteKit, Cloudflare Durable Objects, WebSocket을 사용하여 실시간 카운터 및 접속자 수를 표시하는 예제 애플리케이션입니다.

## 주요 기능

- ✅ **Cloudflare Durable Objects**로 상태 관리
- ✅ **WebSocket Hibernation API**로 실시간 양방향 통신
- ✅ 카운트 버튼 클릭으로 증가
- ✅ 실시간 접속자 수 표시
- ✅ 모든 클라이언트에 실시간 동기화
- ✅ Durable Objects 영구 저장소에 상태 저장

## 기술 스택

- **SvelteKit 5** - 풀스택 웹 프레임워크
- **Cloudflare Durable Objects** - 상태 저장 및 관리
- **WebSocket Hibernation API** - 저비용 실시간 통신
- **Tailwind CSS 4** - 스타일링
- **TypeScript** - 타입 안전성

## 프로젝트 구조

```
├── src/
│   ├── durable-objects/
│   │   └── counter.ts              # Durable Object 구현
│   ├── routes/
│   │   ├── api/counter/
│   │   │   └── +server.ts          # WebSocket 엔드포인트
│   │   └── +page.svelte            # 메인 UI 컴포넌트
│   ├── app.d.ts                    # TypeScript 타입 정의
│   └── hooks.server.ts             # Durable Object export
├── wrangler.jsonc                  # Cloudflare Workers 설정
├── svelte.config.js                # SvelteKit 설정
└── package.json
```

## 개발 환경 설정

### 1. 의존성 설치

```bash
pnpm install
```

### 2. 로컬 개발 서버 실행

```bash
pnpm dev
```

개발 서버가 시작되면 `http://localhost:5173`에서 애플리케이션을 확인할 수 있습니다.

**참고**: 로컬 개발 환경에서는 Durable Objects가 에뮬레이션되므로, 실제 동작과 약간 다를 수 있습니다.

## Cloudflare에 배포하기

### 1. 프로젝트 빌드

```bash
pnpm build
```

### 2. Wrangler로 배포

Cloudflare 계정이 필요합니다. 아직 로그인하지 않았다면:

```bash
npx wrangler login
```

그런 다음 배포:

```bash
npx wrangler deploy
```

### 3. Durable Objects 설정 확인

배포 시 Cloudflare Dashboard에서 다음을 확인하세요:

1. **Workers & Pages** 섹션으로 이동
2. 배포된 Worker 선택
3. **Settings** > **Durable Objects** 확인
4. `CounterDurableObject` 바인딩이 올바르게 설정되었는지 확인

## 작동 원리

### Durable Objects

`CounterDurableObject` 클래스는 다음을 담당합니다:

1. **상태 관리**: 카운트 값과 연결된 WebSocket 세션 관리
2. **영구 저장**: 카운트를 Durable Objects Storage에 저장
3. **브로드캐스팅**: 모든 연결된 클라이언트에 상태 변경 알림

### WebSocket Hibernation

Cloudflare의 WebSocket Hibernation API를 사용하여:

- 메시지가 없을 때 Durable Object를 메모리에서 제거
- 비용 절감 (GB-초 단위 청구 방지)
- 클라이언트 연결 유지

### 실시간 동기화

1. 클라이언트가 `/api/counter`로 WebSocket 연결
2. Durable Object가 모든 클라이언트 세션 추적
3. 카운트 변경 시 모든 연결된 클라이언트에 브로드캐스트
4. 각 클라이언트가 실시간으로 UI 업데이트

## 환경 변수 및 설정

### wrangler.jsonc

```jsonc
{
  "name": "dd",
  "main": ".svelte-kit/cloudflare/_worker.js",
  "compatibility_date": "2025-01-15",
  "assets": {
    "binding": "ASSETS",
    "directory": ".svelte-kit/cloudflare"
  },
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",
        "class_name": "CounterDurableObject",
        "script_name": "dd"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["CounterDurableObject"]
    }
  ]
}
```

## 추가 기능 아이디어

- 여러 개의 독립적인 카운터 (룸 기반)
- 사용자 인증 및 권한 관리
- 카운트 히스토리 및 통계
- 더 복잡한 실시간 협업 기능

## 문제 해결

### WebSocket 연결 실패

- 브라우저 콘솔에서 오류 확인
- Cloudflare Dashboard에서 Durable Objects 바인딩 확인
- Worker 로그 확인 (`wrangler tail`)

### 로컬 개발 시 WebSocket 작동하지 않음

로컬 개발 환경에서는 Wrangler의 `--local` 모드를 사용하거나 `wrangler dev`를 실행할 수 있습니다:

```bash
pnpm build
npx wrangler dev
```

## 참고 자료

- [SvelteKit 문서](https://kit.svelte.dev/)
- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
- [WebSocket Hibernation API](https://developers.cloudflare.com/durable-objects/best-practices/websockets/)
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)

## 라이선스

MIT