
Uma biblioteca de proxy HTTP/HTTPS personalizável para Go, com suporte a encaminhamento regular, tunelamento CONNECT, interceptação TLS MITM e modificação programática de requisições/respostas.
# 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 é uma biblioteca para criar um `servidor proxy` HTTP/HTTPS `personalizado` usando
Go (também conhecido como Golang), com várias configurações disponíveis.
O objetivo deste projeto é oferecer um servidor proxy `otimizado`, utilizável com
uma quantidade razoável de tráfego, mas também `personalizável` e `programável`.
O proxy em si é simplesmente um handler `net/http`, então você pode adicionar vários
middlewares (panic recover, logging, compressão, etc.) sobre ele. Ele pode ser
facilmente integrado com qualquer outra biblioteca de rede HTTP.
Para usar o goproxy, você deve configurar seu navegador (ou qualquer outro cliente)
para usar o goproxy como um proxy HTTP.
Veja como fazer isso no [Chrome](https://www.wikihow.com/Connect-to-a-Proxy-Server)
e no [Firefox](http://www.wikihow.com/Enter-Proxy-Settings-in-Firefox).
Se você decidir começar com o exemplo `base`, a URL que você deve usar como
proxy é `localhost:8080`, que é a padrão no nosso exemplo.
Você também precisa [confiar](https://github.com/elazarl/goproxy/blob/master/examples/customca/README.md)
no certificado CA do proxy, para evitar qualquer problema de certificado nos clientes.
> [✈️ Grupo no Telegram](https://telegram.me/goproxygroup)
>
> [🎁 Torne-se um Patrocinador](https://opencollective.com/goproxy)
## Funcionalidades
- Executar certas ações apenas em `hosts específicos`, com uma única comparação de igualdade ou com avaliação de regex
- Manipular `requests` e `responses` antes de enviá-los ao navegador
- Usar um `http.Transport` personalizado para realizar requisições ao servidor de destino
- Você pode especificar um `cache de certificados MITM`, para reutilizá-los posteriormente em outras requisições ao mesmo host, economizando CPU. Não habilitado por padrão, mas você deve usá-lo em produção!
- Redirecionar o tráfego HTTP normal para um `handler personalizado`, quando o destino for um `caminho relativo` (ex.: `/ping`)
- Você pode escolher o logger a ser usado, implementando a interface `Logger`
- Você pode `desabilitar` a `canonicalização` dos cabeçalhos das requisições HTTP, definindo `PreventCanonicalization` como true
## Modos de proxy
1. Proxy HTTP regular
2. HTTPS via CONNECT
3. Servidor proxy HTTPS MITM ("Man in the Middle"), no qual o servidor gera certificados TLS para analisar os dados de requisição/resposta e executar ações sobre eles
4. Conexão de proxy "sequestrada" (hijacked), onde o handler configurado pode acessar os dados brutos de net.Conn
## Patrocinadores
Sua empresa usa o GoProxy? Ajude-nos a manter o projeto ativo e saudável!
Apoiar o GoProxy nos permite dedicar mais tempo a correções de bugs e novos recursos.
Em troca, se você escolher um plano Gold Supporter ou Enterprise, exibiremos orgulhosamente o logotipo da sua empresa aqui.
> [Torne-se um Patrocinador](https://opencollective.com/goproxy)
[](https://opencollective.com/goproxy)
[](https://opencollective.com/goproxy)
## Mantenedores
- [Elazar Leibovich](https://github.com/elazarl): Criador do projeto, Engenheiro de Software
- [Erik Pellizzon](https://github.com/ErikPelli): Mantenedor, Freelancer (aberto a colaborações!)
Se você precisar integrar o GoProxy ao seu projeto, ou precisar de alguns
recursos personalizados para manter no seu fork, você pode entrar em contato com [Erik](mailto:[email protected])
(o mantenedor atual) por e-mail, e vocês podem discutir juntos como ele
pode ajudar você como consultor independente remunerado.
## Contribuições
Se você tiver algum problema, sugestão, ou se encontrar um bug, sinta-se à vontade
para entrar em contato abrindo uma `issue` no GitHub.
Este é um projeto `open source` gerenciado por voluntários, e ficamos felizes
em discutir qualquer coisa que possa melhorá-lo.
Certifique-se de explicar tudo, incluindo o motivo por trás da issue
e o que você deseja alterar, para tornar o problema mais fácil de entender.
Você também pode abrir diretamente um `Pull Request`, se for uma pequena alteração de código, mas
você precisa explicar tudo na descrição.
Se você abrir um pull request chamado `refactoring` com `5.000` linhas alteradas,
não vamos mesclá-lo... `:D`
O código deste projeto é distribuído sob a licença `BSD 3-Clause`,
tornando-o útil também para usos `comerciais`.
### Envie seu estudo de caso
Então, você introduziu e integrou o GoProxy em um dos seus projetos pessoais
ou em um projeto dentro da empresa em que você trabalha.
Ficamos felizes em conhecer novas `soluções criativas` feitas com esta biblioteca,
então sinta-se à vontade para `entrar em contato` com o mantenedor listado acima por e-mail,
explicando por que você achou este projeto útil para suas necessidades.
Se você assinou um `Acordo de Confidencialidade` (Non Disclosure Agreement) com a empresa, você
pode propor a eles que escrevam um `post de blog` no site oficial deles sobre
este tópico, assim essa informação será pública por escolha deles, e você pode
`compartilhar o link` do post do blog conosco :)
O objetivo dos estudos de caso é compartilhar com a `comunidade` por que todos os
`contribuidores` deste projeto estão `melhorando` o mundo com a ajuda deles e
o que as pessoas estão construindo usando-o.
### Linter
O codebase usa uma verificação automática de lint no código do seu Pull Request.
Antes de abri-lo, você deve verificar se suas alterações o respeitam, executando
o linter na sua máquina local, para que você não tenha nenhuma surpresa.
Para instalar o linter:
```sh
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```
Isso criará um executável na sua pasta `$GOPATH/bin`
(`$GOPATH` é uma variável de ambiente, geralmente
seu valor é equivalente a `~/go`, verifique o valor na sua máquina se você
não tiver certeza sobre isso).
Certifique-se de incluir a pasta bin no path do seu shell, para poder
usar diretamente o comando `golangci-lint run`.
## Um gostinho do GoProxy
Para ter um gostinho do `goproxy`, aqui está um proxy HTTP/HTTPS básico
que apenas encaminha dados para o destino:
```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))
}
```
### Handler de requisições
Esta linha adicionará o cabeçalho `X-GoProxy: yxorPoG-X` a todas as requisições enviadas através do proxy,
antes de enviá-las ao destino:
```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
})
```
Quando a entrada de `OnRequest()` estiver vazia, a função especificada em `DoFunc`
processará todas as requisições recebidas pelo proxy. Nesse caso, ela adicionará
um cabeçalho à requisição e a retornará ao chamador.
O proxy enviará a requisição modificada ao destino.
Você também pode usar `Do` em vez de `DoFunc`, se você implementar a interface
especificada no seu tipo.
> ⚠️ Observe que retornamos um valor nil como resposta.
> Se a resposta retornada não for nil, o goproxy descartará a requisição
> e enviará a resposta especificada ao cliente.
### Handler de requisições condicional
Recuse conexões com www.reddit.com entre 8 e 17 no fuso horário local
do servidor:
```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` retorna uma `ReqCondition`, que é uma função que recebe um `*http.Request`
e retorna um booleano que verifica se a requisição satisfaz a condição (e que será processada).
`DstHostIs("www.reddit.com")` retornará uma `ReqCondition` que retorna true
quando a requisição for direcionada a "www.reddit.com".
A verificação de igualdade do host é `case-insensitive` (não diferencia maiúsculas de minúsculas),
para refletir o comportamento dos resolvedores de DNS, então mesmo que o usuário digite "www.rEdDit.com", a comparação
satisfará a condição.
Quando a hora estiver entre 8:00 e 17:59, retornamos diretamente
uma resposta em `DoFunc()`, então o destino remoto não receberá a
requisição e o cliente receberá a resposta `"Don't waste your time!"`.
### Vamos começar
```go
import "github.com/elazarl/goproxy"
```
Há alguns exemplos de uso do proxy na pasta `examples`, que
cobrem os casos mais comuns. Dê uma olhada neles e boa sorte!
## Manipulação de requisições e respostas
Existem 3 tipos diferentes de handlers para manipular o comportamento do proxy, conforme abaixo:
```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
```
Dependendo do que você deseja manipular, as formas de adicionar handlers a cada uma das listas anteriores são:
```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())
```
Exemplo:
```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())
```
## Tratamento de erros
### Erro genérico
Se ocorrer um erro ao manipular uma requisição através do proxy, por padrão
o proxy retorna o erro HTTP `500` (Internal Server Error) com a `mensagem
de erro` como conteúdo do `body`.
Se você quiser substituir esse comportamento, você pode definir seu próprio
`RespHandler` que altera a resposta de erro.
Entre os parâmetros de contexto, `ctx.Error` contém o `error` ocorrido,
se houver, ou o valor `nil`, se nenhum erro aconteceu.
Você pode tratá-lo como desejar, inclusive retornando um JSON personalizado como body.
Exemplo de um handler de erro:
```
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
})
```
### Erro de conexão
Se ocorrer um erro ao enviar dados para o servidor remoto de destino (ou para
o cliente do proxy), o `proxy.ConnectionErrHandler` é chamado para tratar o
erro, se presente; caso contrário, um `handler padrão` será usado.
O erro é passado como `parâmetro de função` e não dentro do contexto do proxy,
então você não precisa verificar o campo ctx.Error neste handler.
Neste handler você tem acesso à conexão bruta com o cliente do proxy
(como um `io.Writer`), então você pode enviar qualquer dado HTTP por ela,
se necessário, contendo os dados do erro.
Não há garantia de que a conexão já não foi fechada, então
o `Write()` pode retornar um erro.
A `conexão` será `fechada automaticamente` pela biblioteca do proxy após a
chamada do handler de erro, então você não precisa se preocupar com isso.
## Status do Projeto
Este projeto foi criado há `10 anos` e alcançou um estágio de
`maturidade`. Ele pode ser usado com segurança em `produção`, e muitos projetos
já o fazem.
Se houver alguma `mudança que quebre a compatibilidade` no futuro, uma `nova versão` do
módulo Go será lançada (ex.: v2).
## Confiável, como dependência direta, por:
<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>