Claude Code CLI를 Go 기반 REST API 게이트웨이로 래핑해 비동기 작업 큐, SSE 스트리밍, 웹훅 콜백을 갖춘 단일 정적 바이너리 구현

Context

Claude Code는 강력한 CLI 도구이지만 stdin/stdout 기반의 블랙박스로, CI 파이프라인이나 백엔드 서비스에 통합할 HTTP 인터페이스, 작업 큐, 상태 폴링, 스트리밍 엔드포인트가 없어 자동화된 워크플로우에 사용할 수 없었다.

Technical Solution

• 게이트웨이 패턴으로 Claude Code 프로세스 래핑: stdin/stdout 기반 CLI를 REST API로 변환하고 HTTP 엔드포인트 제공
• 버퍼링된 채널 기반 비동기 작업 큐 구현: 단순한 chan string으로 buffered 채널을 사용해 작업 ID만 전달하고 비블로킹 백프레셔 구현
• SQLite 기반 상태 지속성: modernc.org/sqlite(순수 Go, CGO 불필요)를 사용해 작업 메타데이터 저장 및 충돌 복구
• Server-Sent Events(SSE) 팬아웃 방식 스트리밍: 워커가 64 크기의 버퍼링된 채널로 여러 구독자에게 청크 브로드캐스트하고 느린 클라이언트의 이벤트 자동 드롭
• 지능형 웹훅 전달 모듈: 지수 백오프 재시도(3회, 1s→2s→4s), RFC 1918/루프백/링크로컬 IP 차단(SSRF 보호), 모든 콜백에 일관된 페이로드 형식
• 작업 취소 메커니즘: 워커가 작업 ID 기반 context.CancelFunc를 등록하고 HTTP 핸들러가 exec.CommandContext로 서브프로세스를 정리된 상태로 종료
• Go 1.22 정수 범위 순회로 워커 풀 시작: for range q.cfg.Concurrency { go q.runWorker(ctx) } 패턴으로 인덱스 변수 없이 동시 워커 생성
• 임베드된 웹 플레이드라운드: //go:embed로 HTML UI를 컴파일 타임에 포함해 별도 의존성 없이 작업 제출 및 히스토리 조회 가능

Key Takeaway

게이트웨이 패턴의 강력함은 개별 기술 선택(큐, SSE, 웹훅)이 아니라 이들의 조합에 있으며, 특히 ID 기반 채널로 취소 안전성을 확보하고 매 웹훅 전달 시 SSRF 검증을 수행하는 등 프로덕션 환경의 세부 디자인이 신뢰성을 결정한다.