maigo

README

MaiGo

Se você procura um cliente HTTP simples, rápido e confiável para Go, o MaiGo é a escolha ideal. Inspirado na Mai Sakurajima, o pacote segue a filosofia de aparecer discretamente e resolver seu problema sem alarde.

Description

MaiGo oferece uma API baseada em builders, permitindo configurações de cabeçalhos, cookies, tentativas de retry e balanceamento de carga de forma fluida. Seu foco é produtividade sem deixar de lado a elegância – e alguns easter eggs para os fãs da Mai.

Requirements

• Go 1.25 ou superior (não faça downgrade abaixo desta versão)
• GolangCI-Lint 2.7+ para validações locais
• Não faça downgrade do linter wsl_v5 na configuração do GolangCI-Lint
• Módulos listados em go.mod
• Antes de abrir um PR, execute make lint garantindo o uso das versões mínimas de Go (1.25+) e GolangCI-Lint (2.7+)

Usage

Um exemplo de requisição básica pode ser encontrado em examples/base_get_request:

client := maigo.DefaultClient("https://api.example.com")
resp, err := client.GET("/users").Send()
if err != nil {
    // Tratamento de erro
}

var users []User
if err := resp.Body().AsJSON(&users); err != nil {
    // Erro ao ler a resposta
}

Outros exemplos estão disponíveis na pasta examples, incluindo chamadas com cabeçalhos customizados, balanceamento de carga, tracing com OpenTelemetry e coleta de métricas com Prometheus. E não se surpreenda se surgir uma nova referência à Mai no meio dos logs.

Compatibilidade com http.Client

Precisa interoperar com a biblioteca padrão? Use o builder do MaiGo e extraia os valores compatíveis:

// Obtém um *http.Client com as configurações aplicadas no builder
clientBuilder := maigo.NewClient(baseURL)
clientBuilder.Config().SetTimeout(5 * time.Second)
httpClient := clientBuilder.Build().(contracts.ClientCompat).Unwrap()

// Cria um *http.Request pronto para ser enviado com o http.Client padrão
reqBuilder := maigo.NewClient(baseURL)
reqBuilder.Header().Add(header.UserAgent, "mai-go")
req, err := reqBuilder.Build().
        GET("/users").
        Unwrap()
if err != nil {
        // Trate o erro de construção da requisição
}

resp, err := httpClient.Do(req)

Métricas de cliente HTTP

O MaiGo inclui um RoundTripper que registra métricas de duração e contagem por método e status usando Prometheus. Basta encadear o metrics.MetricsRoundTripper ao transporte do cliente:

registry := prometheus.NewRegistry()

transport := httpx.Compose(
        http.DefaultTransport,
        metrics.MetricsRoundTripper(metrics.RoundTripperOptions{
                Registerer: registry,
                Namespace:  "maigo",
                Subsystem:  "client",
        }),
)

client := maigo.NewClient(baseURL).
        Config().
        SetCustomTransport(transport).
        Build()

Um exemplo completo pode ser encontrado em examples/metrics_round_tripper, incluindo a exportação das métricas registradas.

Tracing com OpenTelemetry

Para gerar spans de saída e propagar o contexto em cabeçalhos HTTP, use o tracing.WithTracing() ao compor o transporte do cliente. É necessário configurar um TracerProvider e um TextMapPropagator do OpenTelemetry antes de enviar as requisições:

// Configuração global de tracing
tp := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})

transport := httpx.Compose(
        http.DefaultTransport,
        tracing.WithTracing(),
)

client := maigo.NewClient(baseURL).
        Config().
        SetCustomTransport(transport).
        Build()

Um exemplo funcional está disponível em examples/request_with_tracing, mostrando a criação de spans e a propagação automática do contexto ao longo das chamadas HTTP.

Configuração de TLS do client

Quando precisar confiar em um certificado específico ou ajustar o handshake TLS, aplique um *tls.Config diretamente no builder. O exemplo abaixo adiciona o certificado do servidor a um pool de confiança e o reaproveita no cliente:

server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "secure ok")
}))
defer server.Close()

certPool := x509.NewCertPool()
certPool.AddCert(server.Certificate())

tlsConfig := &tls.Config{RootCAs: certPool}

client := maigo.NewClient(server.URL).
        Config().
        SetTLSConfig(tlsConfig).
        Build()

resp, err := client.GET("/").Send()

Um programa completo pode ser encontrado em examples/tls_client_config mostrando a configuração do pool de certificados e o consumo do endpoint HTTPS.

Releases

As releases são geradas automaticamente ao mesclar alterações no branch main. O workflow release.yml usa GoReleaser para criar tags, gerar changelog e publicar pacotes utilizando o GITHUB_TOKEN com permissões de contents: write e packages: write.

Contributing

Contribuições são muito bem-vindas! Para colaborar:

1. Fork este repositório.
2. Crie um branch com sua funcionalidade.
3. Envie um pull request detalhando as alterações.

Se tiver dúvidas, abra uma issue. Enquanto isso, curta a presença da Mai neste projeto!