Hello Kafka

Apache Kafka의 핵심 동작 원리를 학습하기 위해 Python으로 직접 구현하는 미니 Kafka 프로젝트입니다.

🎯 프로젝트 진행 상태

📋 작업 목록 (9개)

• 작업 1-2: 프로젝트 구조 설정 및 프로토콜 정의 (완료)
• 작업 3-4: 스토리지 엔진 및 브로커 서버 구현 (완료)
• 작업 5: AdminClient 구현 (토픽 생성/조회)
• 작업 6: KafkaProducer 구현 (메시지 발행)
• 작업 7: KafkaConsumer 구현 (메시지 소비)
• 작업 8: 통합 테스트 및 E2E 검증
• 작업 9: 예제 애플리케이션 및 문서화

🔥 현재 상태

• 진행률: 40% (4/9개 작업 완료)
• 현재 작업: AdminClient 구현 → Producer/Consumer 구현
• 다음 목표: KafkaProducer 구현 → 메시지 발행 기능 추가

🏷️ 작업 관리

모든 작업이 GitHub Issues #3-11로 관리되며, 우선순위와 의존성이 라벨로 표시됩니다.

🛠️ 실행 방법

요구사항

• Python 3.13+

브로커 시작

# 1. 저장소 클론
https://github.com/joowankim/hello-kafka.git
cd hello-kafka

# 2. 브로커 실행
chmod +x run-broker.sh
./run-broker.sh

브로커가 127.0.0.1:8000에서 클라이언트 연결을 대기합니다.

📚 시스템 개요

핵심 기능

• 토픽 관리: 토픽 생성 및 목록 조회
• 메시지 발행: Producer를 통한 메시지 발송
• 메시지 소비: Consumer를 통한 메시지 수신 및 오프셋 관리
• 영속성: 파일 시스템 기반 메시지 저장

아키텍처

통신 프로토콜

[Correlation ID: 4바이트] + [API Key: 2바이트] + [Payload 길이: 4바이트] + [JSON Payload]

스토리지 구조

데이터/
├── {토픽}-{파티션}/
│   ├── 00000000000000000000.log    # 레코드 데이터
│   ├── 00000000000000000000.index  # 오프셋 인덱스
│   └── ...
└── consumer_offsets.chk            # 컨슈머 오프셋 정보

레코드 저장 형식

[길이: 4바이트] + [JSON 레코드 데이터]

🎯 구현 목표

성공 기준

1. 토픽 생성: createTopics() → 파일 시스템에 토픽 디렉토리 생성
2. 메시지 발행: send() → 브로커에 저장 후 RecordMetadata 반환
3. 메시지 소비: poll() → 브로커에서 ConsumerRecord 목록 수신
4. 오프셋 관리: commitSync() → 소비 위치 저장 및 재시작 시 복원

비기능적 요구사항

• 성능: 초당 1,000개 메시지 처리
• 내구성: 브로커 재시작 후 데이터 보존
• 언어: Python + asyncio

제외 사항

• 클러스터링 및 복제
• 컨슈머 그룹 관리
• 보안 기능
• 고급 API