업스트림 프록시 시스템

업스트림 프록시는 CCR(Claude Code Remote) 컨테이너에서 실행되며, 클라이언트와 API 서버 사이의 WebSocket 트래픽을 중계합니다. 핵심 과제는 GKE(Google Kubernetes Engine) L7 로드 밸런서를 통해 WebSocket 연결을 안정적으로 유지하는 것입니다.

핵심 도전 과제:

• GKE L7 LB 제약: Envoy 기반 LB가 512KB 청크 크기 제한과 유휴 연결 타임아웃을 강제
• MITM 가능 설계: 프록시가 트래픽을 관찰하고 변환할 수 있는 투명한 중계 레이어
• 6단계 초기화: 프로세스 보안 설정부터 서버 바인딩까지의 시작 절차
• 킵얼라이브: 30초 핑과 50초 유휴 타임아웃으로 연결 활성 유지

GKE의 L7 로드 밸런서(Envoy 기반)는 HTTP/WebSocket 트래픽에 여러 제약을 부과합니다.

• 512KB 청크 캡: 단일 WebSocket 프레임이 512KB를 초과하면 Envoy가 연결을 끊습니다
• 유휴 타임아웃: 트래픽 없이 일정 시간이 지나면 LB가 연결을 종료합니다
• Upgrade 핸들링: HTTP → WebSocket 업그레이드 시 LB가 연결을 백엔드로 전달하는 과정에서 지연이 발생할 수 있습니다

// proxy/connection.ts — 512KB 청크 분할
const MAX_CHUNK_SIZE = 512 * 1024  // 512KB Envoy 캡

function splitIntoChunks(data: Buffer): Buffer[] {
  const chunks: Buffer[] = []
  for (let i = 0; i < data.length; i += MAX_CHUNK_SIZE) {
    chunks.push(data.subarray(i, Math.min(i + MAX_CHUNK_SIZE, data.length)))
  }
  return chunks
}

프록시 서버의 시작은 보안 설정부터 서버 바인딩까지 6단계로 구성됩니다.

1. prctl PR_SET_DUMPABLE(0): 코어 덤프를 비활성화하여 메모리에 있는 토큰이 덤프 파일로 유출되는 것을 방지
2. 환경 변수 로드: 8개의 환경 변수에서 포트, 타임아웃, 인증 정보 등을 읽음
3. Protobuf 스키마 초기화: 수작업으로 작성된 인코더/디코더 로드
4. 킵얼라이브 타이머 설정: 30초 핑 간격, 50초 유휴 타임아웃
5. HTTP 서버 생성: WebSocket 업그레이드 핸들러 등록
6. 포트 바인딩: 환경 변수에서 지정된 포트에 바인딩

// proxy/server.ts — 6단계 초기화
async function startProxy(): Promise<void> {
  // 1. 코어 덤프 비활성화
  if (process.platform === 'linux') {
    prctl(PR_SET_DUMPABLE, 0)
  }

  // 2. 환경 변수 로드
  const config = loadProxyConfig()

  // 3. Protobuf 초기화
  const codec = initProtobufCodec()

  // 4. 킵얼라이브 설정
  const keepalive = new KeepaliveManager(config.pingInterval, config.idleTimeout)

  // 5. HTTP 서버 + WebSocket 업그레이드
  const server = createServer()
  server.on('upgrade', (req, socket, head) => {
    handleUpgrade(req, socket, head, codec, keepalive)
  })

  // 6. 포트 바인딩
  server.listen(config.port, () => {
    console.log(`프록시 서버 시작: 포트 ${config.port}`)
  })
}

각 WebSocket 연결은 두 단계의 상태를 거칩니다.

Phase 1: Handshake

클라이언트의 첫 메시지에서 인증 토큰을 추출하고 검증합니다. 유효한 경우 업스트림 API 서버로의 WebSocket 연결을 수립합니다.

Phase 2: Relay

양방향 메시지 중계가 시작됩니다. 클라이언트 → 업스트림과 업스트림 → 클라이언트 방향의 메시지를 투명하게 전달하며, 필요 시 청크 분할과 Protobuf 변환을 적용합니다.

// proxy/connection.ts — 2단계 상태 머신
class ProxyConnection {
  private state: 'handshake' | 'relay' = 'handshake'

  onMessage(data: Buffer): void {
    if (this.state === 'handshake') {
      const token = this.extractToken(data)
      if (this.validateToken(token)) {
        this.connectUpstream(token)
        this.state = 'relay'
      } else {
        this.close(4001, '인증 실패')
      }
      return
    }

    // relay 상태: 메시지를 업스트림으로 전달
    const chunks = splitIntoChunks(data)
    for (const chunk of chunks) {
      this.upstream.send(chunk)
    }
  }
}

업스트림 프록시는 protobuf-js 같은 라이브러리를 사용하지 않고 인코더/디코더를 수작업으로 구현합니다. 이는 번들 크기를 줄이고, CCR 컨테이너의 제한된 환경에서 의존성 문제를 피하기 위함입니다.

// proxy/protobuf.ts — 수작업 varint 인코딩
function encodeVarint(value: number): Uint8Array {
  const bytes: number[] = []
  while (value > 0x7f) {
    bytes.push((value & 0x7f) | 0x80)
    value >>>= 7
  }
  bytes.push(value & 0x7f)
  return new Uint8Array(bytes)
}

function encodeMessage(fieldNumber: number, data: Uint8Array): Uint8Array {
  const tag = encodeVarint((fieldNumber << 3) | 2)  // wire type 2 = length-delimited
  const length = encodeVarint(data.length)
  return concat(tag, length, data)
}

업스트림 프록시는 Bun과 Node.js 두 런타임에서 모두 실행될 수 있도록 설계되었습니다. 런타임 감지 후 API 차이를 추상화합니다.

// proxy/server.ts — 런타임 감지 및 추상화
const isBun = typeof globalThis.Bun !== 'undefined'

const WebSocketServer = isBun
  ? Bun.serve   // Bun 내장 WebSocket 서버
  : require('ws').WebSocketServer  // Node.js용 ws 라이브러리

Bun은 WebSocket을 네이티브로 지원하여 ws 라이브러리가 불필요하고, 메모리 사용량이 더 적습니다. Node.js는 호환성이 더 넓고 디버깅 도구가 풍부합니다. CCR 환경에서는 기본적으로 Bun을 사용합니다.

프록시는 8개의 환경 변수에서 설정을 읽습니다.

1. PROXY_PORT — 프록시 서버 바인딩 포트
2. UPSTREAM_URL — API 서버 WebSocket URL
3. PING_INTERVAL_MS — 킵얼라이브 핑 간격 (기본 30,000ms)
4. IDLE_TIMEOUT_MS — 유휴 연결 타임아웃 (기본 50,000ms)
5. MAX_CHUNK_SIZE — 최대 청크 크기 (기본 524,288 = 512KB)
6. AUTH_TOKEN — 프록시 인증 토큰
7. TLS_CERT_PATH — TLS 인증서 경로 (선택적)
8. LOG_LEVEL — 로깅 수준 (debug/info/warn/error)

보안 모델

프록시는 여러 보안 계층을 적용합니다:

• 코어 덤프 비활성화: prctl PR_SET_DUMPABLE(0)으로 메모리 덤프 방지
• 토큰 검증: 모든 WebSocket 연결의 첫 메시지에서 인증 토큰 확인
• TLS 종단: 선택적 TLS로 프록시-클라이언트 구간 암호화
• 청크 크기 제한: 과도한 메모리 사용 방지

GKE LB의 유휴 타임아웃을 방지하기 위해 프록시는 30초마다 WebSocket 핑을 전송합니다. 50초 동안 어떤 트래픽도 없으면 연결을 종료합니다.

// proxy/keepalive.ts — 킵얼라이브 관리
class KeepaliveManager {
  private pingTimer: NodeJS.Timer
  private idleTimer: NodeJS.Timer

  constructor(
    private pingInterval = 30_000,   // 30초
    private idleTimeout = 50_000,    // 50초
  ) {}

  start(ws: WebSocket): void {
    this.pingTimer = setInterval(() => {
      ws.ping()  // WebSocket 핑 프레임 전송
    }, this.pingInterval)

    this.resetIdleTimer(ws)
  }

  onActivity(ws: WebSocket): void {
    this.resetIdleTimer(ws)  // 트래픽 시 유휴 타이머 리셋
  }

  private resetIdleTimer(ws: WebSocket): void {
    clearTimeout(this.idleTimer)
    this.idleTimer = setTimeout(() => {
      ws.close(1000, '유휴 타임아웃')
    }, this.idleTimeout)
  }
}