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. 의존성 설치

pnpm install

2. 로컬 개발 서버 실행

pnpm dev

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

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

Cloudflare에 배포하기

1. 프로젝트 빌드

pnpm build

2. Wrangler로 배포

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

npx wrangler login

그런 다음 배포:

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

{
  "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를 실행할 수 있습니다:

pnpm build
npx wrangler dev

참고 자료

• SvelteKit 문서
• Cloudflare Durable Objects
• WebSocket Hibernation API
• Cloudflare Workers

라이선스

MIT