Go 기반 HTTP API Gateway입니다. 경로별 로드밸런싱, API 키 인증, 요청 제한에 더해 파일 기반 라우팅 갱신과 업스트림 장애 격리를 제공합니다.
로컬 데모는 Go 1.25.6 이상에서 실행합니다.
go run ./cmd/server
curl -H 'X-API-Key: secret-key-123' http://127.0.0.1:8080/api/v1
curl http://127.0.0.1:9090/readyz데모는 알려진 테스트 키를 사용하며 8081~8083번 포트의 업스트림을 전제로 합니다. 실제 업스트림 주소와 환경 변수 기반 키를 쓰려면 examples/gateway.yaml로 실행합니다. 먼저 examples/routes.yaml에 접근 가능한 업스트림 주소를 등록합니다.
export GATEWAY_SIGNING_KEY="$(openssl rand -hex 32)"
export GATEWAY_CLIENT_KEY="$(openssl rand -hex 24)"
go run ./cmd/server -check-config -config examples/gateway.yaml
go run ./cmd/server -config examples/gateway.yaml-check-config는 환경 변수, 게이트웨이 설정, 초기 라우팅 파일을 함께 검증하고 포트를 열지 않고 종료합니다.
다른 셸에서 요청할 때는 동일한 GATEWAY_CLIENT_KEY 값을 사용합니다. 공개 트래픽은 TLS를 종료하는 프록시를 통해 연결하고, 게이트웨이에 직접 접근할 수 있는 네트워크를 제한합니다.
- 경로 세그먼트를 기준으로 가장 긴 prefix를 선택합니다. 경로와 쿼리는 기본적으로 유지됩니다.
allowed_methods를 지정하면 해당 메서드만 업스트림에 전달합니다.GET은HEAD도 허용하며, 거부 응답은405와Allow헤더를 반환합니다.strip_prefix: true는 매칭된 경로 앞부분을 제거하고 업스트림의 기본 경로와 합칩니다. 예제의GET /catalog/items?tag=a는 업스트림에GET /api/v1/items?tag=a로 전달됩니다.route_file은 게이트웨이 설정 파일의 경로를 기준으로 찾습니다. 저장할 때 임시 파일을 작성한 뒤 이름을 바꾸면 쓰는 중간 상태를 노출하지 않습니다.- 스냅샷의 모든 라우트가 유효하면 한 번에 교체합니다. 잘못된 새 설정이 들어오면 직전 정상 테이블로 계속 요청을 처리합니다. 명시적인
routes: []는 라우트를 비웁니다. - 파일 라우트의 응답 헤더 타임아웃 기본값은 5초입니다. 같은 타임아웃을 가진 라우트는 업스트림 연결 풀을 공유하며, 파일 모드에서는 업스트림에 직접 연결합니다.
- 서킷 브레이커가 설정되면 연결 오류와 업스트림 5xx를 실패로 집계합니다. 임계치에 도달한 업스트림을 피하고, 대기 시간이 지나면 요청 하나로 회복을 확인합니다. 이미 전달한 요청은 재전송하지 않습니다. 파일을 갱신할 때 설정이 같은 라우트는 서킷 상태를 유지하고, 변경된 라우트는 새 상태로 시작합니다.
- 파일 예제는 API 키와 HS256 서명 키를 환경 변수에서 읽습니다. 업스트림은
gateway발급자의 서명, 만료, 사용자 및 역할을 검증합니다. 클라이언트 키는 내부 토큰으로 교체됩니다. - 직접 접속한 클라이언트가 보내는 전달 IP 헤더는 무시합니다. 신뢰하는 프록시만
server.trusted_proxies에 등록하고 프록시가 연결 주소를 전달 체인에 추가하고X-Forwarded-Proto를 실제 외부 연결 스킴으로 덮어쓰도록 설정합니다. - 속도 제한은 게이트웨이 프로세스별 IP 버킷을 사용합니다. 각 샤드의 클라이언트 수에는 상한이 있습니다.
- 관리자 주소는 루프백에서만 열립니다.
/livez는 프로세스 상태,/readyz는 라우팅 테이블과 종료 상태,/metrics는 요청 수와 처리 시간 및 처리 중인 요청을 제공합니다. 준비 상태는 업스트림에 대한 별도 능동 프로브를 실행하지 않습니다. GET /routes는 관리자 포트에서 라우트별 닫힘·열림·복구 대기 서킷 수를 반환합니다. 업스트림 주소는 응답에 포함되지 않습니다.- 서킷 브레이커와 속도 제한 상태는 프로세스 안에 저장됩니다.
go test -race ./...
go vet ./...
GOMAXPROCS=8 go test -run '^$' -bench '^BenchmarkGatewayLoad$' ./internal/server