
Go용 사용자 정의 가능한 HTTP/HTTPS 프록시 라이브러리로, 일반 포워딩, CONNECT 터널링, MITM TLS 가로채기 및 프로그래밍 방식의 요청/응답 수정을 지원합니다.
# GoProxy

[](https://pkg.go.dev/github.com/elazarl/goproxy)
[](https://goreportcard.com/report/github.com/elazarl/goproxy)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://makeapullrequest.com)
[](https://github.com/avelino/awesome-go?tab=readme-ov-file#networking)
GoProxy는 Go(일명 Golang)를 사용하여 `맞춤형` HTTP/HTTPS `프록시 서버`를 만들 수 있는 라이브러리로, 여러 가지 구성 가능한 설정을 제공합니다.
이 프로젝트의 목표는 합리적인 트래픽 양에서 사용할 수 있는 `최적화된` 프록시 서버를 제공하면서도 `사용자 정의`가 가능하고 `프로그래밍 가능`하게 하는 것입니다.
프록시 자체는 단순히 `net/http` 핸들러이므로 그 위에 여러 미들웨어(패닉 복구, 로깅, 압축 등)를 추가할 수 있습니다. 다른 HTTP 네트워크 라이브러리와도 쉽게 통합할 수 있습니다.
goproxy를 사용하려면 브라우저(또는 다른 클라이언트)가 HTTP 프록시로 goproxy를 사용하도록 설정해야 합니다.
[Chrome](https://www.wikihow.com/Connect-to-a-Proxy-Server)과 [Firefox](http://www.wikihow.com/Enter-Proxy-Settings-in-Firefox)에서 설정하는 방법은 다음과 같습니다.
`base` 예제로 시작하기로 결정했다면 프록시로 사용할 URL은 `localhost:8080`이며, 이는 예제의 기본값입니다.
또한 클라이언트에서 인증서 문제가 발생하지 않도록 프록시 CA 인증서를 [신뢰](https://github.com/elazarl/goproxy/blob/master/examples/customca/README.md)해야 합니다.
> [✈️ 텔레그램 그룹](https://telegram.me/goproxygroup)
>
> [🎁 스폰서 되기](https://opencollective.com/goproxy)
## 기능
- 단일 동등 비교 또는 정규식 평가를 통해 `특정 호스트`에서만 특정 작업을 수행합니다
- 브라우저로 보내기 전에 `요청` 및 `응답`을 조작합니다
- 대상 서버에 요청을 수행하기 위해 `사용자 정의 http.Transport`를 사용합니다
- `MITM 인증서 캐시`를 지정하여 동일한 호스트에 대한 이후 요청에 재사용함으로써 CPU를 절약할 수 있습니다. 기본적으로 활성화되어 있지 않지만 프로덕션 환경에서는 사용해야 합니다!
- 대상이 `상대 경로`(예: `/ping`)인 경우 일반 HTTP 트래픽을 `사용자 정의 핸들러`로 리디렉션합니다
- `Logger` 인터페이스를 구현하여 사용할 로거를 선택할 수 있습니다
- `PreventCanonicalization`을 true로 설정하여 HTTP 요청 헤더 `정규화`를 `비활성화`할 수 있습니다
## 프록시 모드
1. 일반 HTTP 프록시
2. CONNECT를 통한 HTTPS
3. HTTPS MITM("중간자") 프록시 서버. 서버가 TLS 인증서를 생성하여 요청/응답 데이터를 구문 분석하고 그에 대한 작업을 수행합니다
4. "하이재킹된" 프록시 연결. 구성된 핸들러가 원시 net.Conn 데이터에 접근할 수 있습니다
## 스폰서
귀사의 회사에서 GoProxy를 사용하고 있나요? 프로젝트가 계속 유지 관리되고 건강하게 유지되도록 도와주세요!
GoProxy를 후원하면 버그 수정과 새로운 기능에 더 많은 시간을 할애할 수 있습니다.
그 대가로 Gold Supporter 또는 Enterprise 플랜을 선택하시면 귀사의 로고를 이곳에 자랑스럽게 게시해 드립니다.
> [스폰서 되기](https://opencollective.com/goproxy)
[](https://opencollective.com/goproxy)
[](https://opencollective.com/goproxy)
## 관리자
- [Elazar Leibovich](https://github.com/elazarl): 프로젝트 창시자, 소프트웨어 엔지니어
- [Erik Pellizzon](https://github.com/ErikPelli): 관리자, 프리랜서(협업 환영!)
GoProxy를 프로젝트에 통합해야 하거나 포크에서 유지 관리할 맞춤 기능이 필요한 경우 이메일로 [Erik](mailto:[email protected])(현재 관리자)에게 연락할 수 있으며, 유료 독립 컨설턴트로서 그가 어떻게 도울 수 있는지 함께 논의할 수 있습니다.
## 기여
문제가 있거나 제안 사항이 있거나 버그를 발견한 경우 GitHub `issue`를 열어 언제든지 연락해 주세요.
이 프로젝트는 자원봉사자들이 관리하는 `오픈 소스` 프로젝트이며, 개선할 수 있는 모든 것에 대해 기꺼이 논의합니다.
문제를 더 쉽게 이해할 수 있도록 문제의 배경과 변경하려는 내용을 포함한 모든 것을 설명해 주세요.
작은 코드 변경이라면 `Pull Request`를 직접 열 수도 있지만 설명에 모든 것을 설명해야 합니다.
`5,000`줄을 변경한 `refactoring`이라는 이름의 풀 리퀘스트를 열면 병합하지 않을 것입니다... `:D`
이 프로젝트의 코드는 `BSD 3-Clause` 라이선스로 배포되므로 `상업적` 용도로도 유용합니다.
### 사례 연구 제출
GoProxy를 개인 프로젝트나 재직 중인 회사의 프로젝트에 도입하고 통합했다면.
이 라이브러리로 만들어진 새로운 `창의적인 솔루션`을 알게 되어 기쁩니다. 이 프로젝트가 필요에 왜 유용하다고 생각했는지 설명하려면 위에 나열된 관리자에게 이메일로 `연락`해 주세요.
회사와 `비밀 유지 계약(NDA)`을 체결한 경우 공식 웹사이트에 이 주제에 대한 `블로그 게시물`을 작성하도록 제안할 수 있습니다. 그러면 해당 정보는 회사의 선택에 따라 공개되며, 블로그 게시물의 `링크를 공유`해 주세요 :)
사례 연구의 목적은 이 프로젝트의 모든 `기여자`가 그들의 도움으로 세상을 `개선`하고 있으며 사람들이 이를 사용하여 무엇을 구축하고 있는지 `커뮤니티`와 공유하는 것입니다.
### Linter
코드베이스는 Pull Request 코드에 대해 자동 린트 검사를 수행합니다.
Pull Request를 열기 전에 로컬 머신에서 린터를 실행하여 변경 사항이 이를 준수하는지 확인해야 예상치 못한 일이 없을 것입니다.
린터를 설치하려면:
```sh
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
그러면 `$GOPATH/bin` 폴더에 실행 파일이 생성됩니다
(`$GOPATH`는 환경 변수이며, 일반적으로 그 값은 `~/go`와 같습니다. 확실하지 않다면 자신의 머신에서 값을 확인하세요).
`golangci-lint run` 명령을 바로 사용할 수 있도록 셸의 경로에 bin 폴더를 포함해야 합니다.
## GoProxy 맛보기
`goproxy`의 맛을 보려면 데이터를 대상에 그대로 전달하는 기본 HTTP/HTTPS 프록시가 여기 있습니다:
```go
package main
import (
"log"
"net/http"
"github.com/elazarl/goproxy"
)
func main() {
proxy := goproxy.NewProxyHttpServer()
proxy.Verbose = true
log.Fatal(http.ListenAndServe(":8080", proxy))
}
```
### 요청 핸들러
이 줄은 대상으로 보내기 전에 프록시를 통해 전송되는 모든 요청에 `X-GoProxy: yxorPoG-X` 헤더를 추가합니다:
```go
proxy.OnRequest().DoFunc(
func(r *http.Request,ctx *goproxy.ProxyCtx)(*http.Request,*http.Response) {
r.Header.Set("X-GoProxy","yxorPoG-X")
return r,nil
})
```
`OnRequest()` 입력이 비어 있으면 `DoFunc`에 지정된 함수가 프록시로 들어오는 모든 요청을 처리합니다. 이 경우 요청에 헤더를 추가하고 호출자에게 반환합니다.
프록시는 수정된 요청을 대상으로 보냅니다.
타입에 지정된 인터페이스를 구현한다면 `DoFunc` 대신 `Do`를 사용할 수도 있습니다.
> ⚠️ 참고: 응답으로 nil 값을 반환했습니다.
> 반환된 응답이 nil이 아니면 goproxy는 요청을 폐기하고 지정된 응답을 클라이언트로 보냅니다.
### 조건부 요청 핸들러
서버 로컬 시간대 기준 8시에서 17시 사이에 www.reddit.com으로의 연결을 거부합니다:
```go
proxy.OnRequest(goproxy.DstHostIs("www.reddit.com")).DoFunc(
func(req *http.Request,ctx *goproxy.ProxyCtx)(*http.Request,*http.Response) {
if h,_,_ := time.Now().Clock(); h >= 8 && h <= 17 {
resp := goproxy.NewResponse(req, goproxy.ContentTypeText, http.StatusForbidden, "Don't waste your time!")
return req, resp
}
return req, nil
})
```
`DstHostIs`는 `*http.Request`를 받아 요청이 조건을 충족하는지(그리고 처리될 것인지) 확인하는 부울 값을 반환하는 함수인 `ReqCondition`을 반환합니다.
`DstHostIs("www.reddit.com")`은 요청이 "www.reddit.com"으로 향할 때 true를 반환하는 `ReqCondition`을 반환합니다.
호스트 동등성 검사는 DNS 리졸버의 동작을 반영하여 `대소문자를 구분하지 않으므로` 사용자가 "www.rEdDit.com"을 입력해도 비교는 조건을 충족합니다.
시간이 오전 8:00에서 오후 5:59 사이이면 `DoFunc()`에서 직접 응답을 반환하므로 원격 대상은 요청을 받지 못하고 클라이언트는 `"Don't waste your time!"` 응답을 받게 됩니다.
### 시작하기
```go
import "github.com/elazarl/goproxy"
```
`examples` 폴더에 가장 일반적인 경우를 다루는 몇 가지 프록시 사용 예제가 있습니다. 살펴보시고 행운을 빕니다!
## 요청 및 응답 조작
다음과 같이 프록시의 동작을 조작하기 위한 3가지 유형의 핸들러가 있습니다:
```go
// handler called after receiving HTTP CONNECT from the client, and
// before proxy establishes connection with the destination host
httpsHandlers []HttpsHandler
// handler called before proxy sends HTTP request to destination host
reqHandlers []ReqHandler
// handler called after proxy receives HTTP Response from destination host,
// and before proxy forwards the Response to the client
respHandlers []RespHandler
```
무엇을 조작하고 싶은지에 따라 이전 목록 각각에 핸들러를 추가하는 방법은 다음과 같습니다:
```go
// Add handlers to httpsHandlers
proxy.OnRequest(some ReqConditions).HandleConnect(YourHandlerFunc())
// Add handlers to reqHandlers
proxy.OnRequest(some ReqConditions).Do(YourReqHandlerFunc())
// Add handlers to respHandlers
proxy.OnResponse(some RespConditions).Do(YourRespHandlerFunc())
```
예시:
```go
// This rejects the HTTPS request to *.reddit.com during HTTP CONNECT phase.
// Reddit URL check is case-insensitive because of (?i), so the block will work also if the user types something like rEdDit.com.
proxy.OnRequest(goproxy.ReqHostMatches(regexp.MustCompile("(?i)reddit.*:443$"))).HandleConnect(goproxy.AlwaysReject)
// Be careful about this example! It shows you a common error that you
// need to avoid.
// This will NOT reject the HTTPS request with URL ending with .gif because,
// if the scheme is HTTPS, the proxy will receive only URL.Hostname
// and URL.Port during the HTTP CONNECT phase.
proxy.OnRequest(goproxy.UrlMatches(regexp.MustCompile(`.*gif$`))).HandleConnect(goproxy.AlwaysReject)
// To fix the previous example, here there is the correct way to manipulate
// an HTTP request using URL.Path (target path) as a condition.
proxy.OnRequest(goproxy.UrlMatches(regexp.MustCompile(`.*gif$`))).Do(YourReqHandlerFunc())
```
## 오류 처리
### 일반 오류
프록시를 통해 요청을 처리하는 동안 오류가 발생하면 기본적으로 프록시는 `오류 메시지`를 `본문` 내용으로 하여 HTTP 오류 `500`(내부 서버 오류)을 반환합니다.
이 동작을 재정의하려면 오류 응답을 변경하는 고유한 `RespHandler`를 정의할 수 있습니다.
컨텍스트 매개변수 중 `ctx.Error`는 발생한 `오류`가 있으면 해당 오류를 포함하고, 오류가 없으면 `nil` 값을 포함합니다.
원하는 대로 처리할 수 있으며, 사용자 정의 JSON을 본문으로 반환할 수도 있습니다.
오류 핸들러의 예:
```
proxy.OnResponse().DoFunc(func(resp *http.Response, ctx *goproxy.ProxyCtx) *http.Response {
var dnsError *net.DNSError
if errors.As(ctx.Error, &dnsError) {
// Do not leak our DNS server's address
dnsError.Server = "<server-redacted>"
return goproxy.NewResponse(ctx.Req, goproxy.ContentTypeText, http.StatusBadGateway, dnsError.Error())
}
return resp
})
```
### 연결 오류
대상 원격 서버(또는 프록시 클라이언트)로 데이터를 보내는 동안 오류가 발생하면 `proxy.ConnectionErrHandler`가 호출되어 오류를 처리합니다(정의된 경우). 그렇지 않으면 `기본 핸들러`가 사용됩니다.
오류는 프록시 컨텍스트 내부가 아닌 `함수 매개변수`로 전달되므로 이 핸들러에서 ctx.Error 필드를 확인할 필요가 없습니다.
이 핸들러에서는 프록시 클라이언트와의 원시 연결(`io.Writer`)에 접근할 수 있으므로 필요한 경우 오류 데이터를 포함한 모든 HTTP 데이터를 그 위로 보낼 수 있습니다.
연결이 이미 닫히지 않았다는 보장은 없으므로 `Write()`가 오류를 반환할 수 있습니다.
오류 핸들러 호출 후 `연결`은 프록시 라이브러리에 의해 `자동으로 닫히므로` 걱정할 필요가 없습니다.
## 프로젝트 상태
이 프로젝트는 `10년` 전에 만들어졌으며 `성숙` 단계에 도달했습니다. `프로덕션` 환경에서 안전하게 사용할 수 있으며 이미 많은 프로젝트가 그렇게 하고 있습니다.
향후 `호환성이 깨지는 변경`이 있다면 Go 모듈의 `새 버전`이 출시될 것입니다(예: v2).
## 직접 종속성으로 신뢰받는 곳:
<p align="left">
<a href="https://github.com/stripe/goproxy" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/64d9d4a11b59a2883beada1d0e2d5e574327f693a7b84f0905510f865248f63e/649c74ea103584e65478fd86f61a32c4651855d53efb8b8d9b9011b42e39c4ee-display-v1.webp" alt="Stripe" title="Stripe" /> </a>
<a href="https://github.com/dependabot/goproxy" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/537c51643f1d6066d041dba12f4bcae952c41490dcf6e6a1143a2e2b15d82199/ec116e30794b65255c125251a815dc4dd376fbdd76a6919fe1d2decae4c8429d-display-v1.webp" alt="Dependabot" title="Dependabot" /> </a>
<a href="https://github.com/go-git/go-git" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/141e8059d0f465d80548bbe9af30697989ed963c30581830b97bc57ef15da0d5/fd51665ff118904f4eefb78cfd2774c195fdf100cffaa6c03e4b8467584c42bd-display-v1.webp" alt="Go Git" title="Go Git" /> </a>
<a href="https://github.com/google/oss-rebuild" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/3cdb183f5b49d7315445abe5fd1e1dac0665db8ad88ef05062eea726ae908031/1957e79f54e85ce7afc6febabb41556f30f81b172a0c63688094ca62515817a1-display-v1.webp" alt="Google" title="Google" /> </a>
<a href="https://github.com/grafana/grafana-plugin-sdk-go" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/801cf1f9b90012f77d2cdbac224be8b5d7def3b5b97483bedaeca069dad28790/c68471eb91d68e700faf0b225cb7f5eb55b88e520068ede25e660bfcca0f7681-display-v1.webp" alt="Grafana" title="Grafana" /> </a>
<a href="https://github.com/superfly/tokenizer" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/fc6176b4a42fa9a431e616d58461b2b6d9fcc84ac214f1f1d321527a6445ee12/b10213639c5ce30276ff67a0f4609737b8c6a65b76b2d99d23805892a99e79d6-display-v1.webp" alt="Fly.io" title="Fly.io" /> </a>
<a href="https://github.com/kubernetes/minikube" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/3ea12262ac6217219b5cffb4fbc2b06d415dcee86a86e9ff620fa3369a64ae36/0ef3dfd53535365fca209291742bdd27099f430199526b20ba59f56c180fcc7e-display-v1.webp" alt="Kubernetes / Minikube" title="Kubernetes / Minikube" /> </a>
<a href="https://github.com/newrelic/newrelic-client-go" target="_blank" rel="noreferrer"> <img src="https://assets.kitploit.com/production/public/readmes/50732/e3060fc9e303c90a833c7a6e01c4977d237a503215c5d6da66817881de9298c3/36b33aedf9fdd68f8e3ff5e8e9274cad40fb63d874187000c2dd29edc533d02f-display-v1.webp" alt="New Relic" title="New Relic" /> </a>
</p>