아키텍처

요청 흐름

AI CLI (claude-code, claude-cli, ...)
  │
  │  HTTP to 127.0.0.1:3817
  ▼
┌──────────────────────────────────────────────┐
│ sotatek-proxy (Gin engine, loopback bind)    │
│                                              │
│  recoveryLogger    panic recovery            │
│  requestLogger     scrub Authorization,      │
│                    x-api-key, drop query     │
│  MiddlewareGitRemote                         │
│       │                                      │
│       ├─ extract peer port from RemoteAddr   │
│       ├─ inspect.GetPidByPeerPort  → PID     │
│       ├─ inspect.GetCwdByPid       → CWD     │
│       ├─ walk parents (≤3) for .git          │
│       ├─ cache.Get(pid) [verify CWD]         │
│       ├─ git.GetRemoteRaw(cwd)  (2s timeout) │
│       └─ inject X-Git-Remote (base64)        │
│                                              │
│  ReverseProxy (NoRoute)                      │
│       ├─ stamp User-Agent: sotatek-proxy/X   │
│       ├─ preserve original in                │
│       │  X-Forwarded-User-Agent              │
│       └─ FlushInterval=-1 (SSE-safe)         │
└────────────────────┬─────────────────────────┘
                     │  HTTP/2 (ForceAttemptHTTP2)
                     ▼
       https://bifrost.sotatek.works/anthropic/v1/*

미들웨어 체인

순서가 중요합니다. 각 레이어는 요청 시 이 순서로 실행되며, 응답 시 역순으로 실행됩니다.

#	미들웨어	목적
1	`recoveryLogger`	패닉 복구; 요청 헤더를 절대 출력하지 않습니다.
2	`requestLogger`	요청별 간결한 구조화 로그: 메서드, 경로, 상태, 지연 시간, `client_ip`, `has_auth`/`has_api_key` 불리언, `has_query` 플래그. Authorization 값은 절대 기록되지 않습니다.
3	`MiddlewareGitRemote`	호출 PID와 CWD를 확인하고, `git remote -v`를 실행하며, 결과를 base64로 인코딩하여 `X-Git-Remote`를 설정합니다. 클라이언트가 제공한 `X-Git-Remote`는 먼저 제거됩니다.
4	`ReverseProxy` (NoRoute)	업스트림으로 1:1 전달, `User-Agent` 스탬프, SSE를 버퍼링 없이 스트리밍합니다.

프로세스 검사 (PID → CWD → git)

프록시는 클라이언트의 TCP 피어 포트 (CLI가 연결에 사용한 포트)를 PID로, 그다음 CWD로 역추적한 후 .git을 찾아 최대 3개의 상위 디렉토리를 탐색합니다.

OS	구현 방식
macOS	`lsof -iTCP:<port> -sTCP:ESTABLISHED -F pn` (PID), `lsof -p <pid> -d cwd -F n` (CWD). 2초 실행 타임아웃.
Linux	`/proc/net/tcp[6]`을 읽어 포트 → 아이노드를 매핑하고, `/proc/*/fd/`에서 일치하는 소켓을 스캔한 후 `/proc/<pid>/cwd`를 읽습니다. 동일 사용자에게만 적용됩니다.
Windows	IPv4/IPv6 연결 테이블을 위한 `GetExtendedTcpTable`; CWD를 위한 `NtQueryInformationProcess`를 통한 PEB 탐색. 64비트 전용.

상위 탐색은 일반적인 대화형 셸 (bash, zsh, fish, sh, dash, ksh, tcsh, csh)에서 중지되므로 프록시가 셸의 CWD를 가로채지 않습니다.

캐시

PID → {cwd, git-remote} 캐시는 TTL(기본 60초)이 있는 sync.Map을 사용합니다. Get 호출 시마다 현재 CWD를 다시 읽으며, CWD가 일치하지 않으면 캐시 항목이 제거됩니다 — 이는 PID 재사용에 대한 방어 메커니즘입니다.

백그라운드 정리 작업이 5분마다 만료된 항목과 PID가 더 이상 살아있지 않은 항목(kill -0)을 제거합니다.

git remote -v 셸 실행에는 2초의 하드 타임아웃이 있습니다. 타임아웃이 발생하거나 리모트가 없는 경우 요청은 X-Git-Remote 헤더 없이 전달됩니다 — 차단되지 않습니다.

스트리밍

프록시는 FlushInterval=-1을 사용하는 httputil.ReverseProxy를 사용하며, 이는 쓰기마다 강제 플러시를 수행합니다. SSE / 청크 응답은 업스트림이 전송하는 즉시 클라이언트에 도달합니다 — 본문 버퍼링 없음. 클라이언트 연결 해제 시 업스트림 컨텍스트가 취소됩니다.

헬스 엔드포인트

GET /_proxy/healthz

버전, 커밋, 업타임, (연결된 경우) 캐시 통계를 반환합니다.

{
  "status": "ok",
  "version": "v0.1.0",
  "commit": "abc1234",
  "uptime": "1h23m",
  "cache": { "entries": 12, "hits": 480, "misses": 64, "hit_rate": 0.882 }
}