httpkit

http-kit

中文文档

A lightweight Go HTTP client library with TLS/mTLS support, automatic retry with exponential backoff, and OpenTelemetry tracing integration.

Features

• TLS/mTLS Support - Full TLS configuration including CA certificates, client certificates for mutual TLS authentication
• Automatic Retry - Configurable retry logic with exponential backoff for transient failures
• OpenTelemetry Integration - Built-in trace context propagation for distributed tracing
• Configurable Options - Flexible client configuration with sensible defaults
• Zero External Dependencies - Only depends on OpenTelemetry for tracing (optional)

Installation

go get github.com/soulteary/http-kit

Quick Start

Basic HTTP Client

import "github.com/soulteary/http-kit"

// Create a simple client
client, err := httpkit.NewClient(&httpkit.Options{
    BaseURL: "https://api.example.com",
    Timeout: 10 * time.Second,
})
if err != nil {
    log.Fatal(err)
}

// Make a request
req, _ := http.NewRequest("GET", client.GetBaseURL()+"/users", nil)
resp, err := client.Do(req)

Client with TLS/mTLS

// Client with server certificate verification
client, err := httpkit.NewClient(&httpkit.Options{
    BaseURL:       "https://secure-api.example.com",
    TLSCACertFile: "/path/to/ca.crt",
    TLSServerName: "secure-api.example.com",
})

// Client with mutual TLS (mTLS)
client, err := httpkit.NewClient(&httpkit.Options{
    BaseURL:       "https://mtls-api.example.com",
    TLSCACertFile: "/path/to/ca.crt",
    TLSClientCert: "/path/to/client.crt",
    TLSClientKey:  "/path/to/client.key",
})

Automatic Retry

import "github.com/soulteary/http-kit"

client, _ := httpkit.NewClient(&httpkit.Options{
    BaseURL: "https://api.example.com",
})

// Use default retry options (3 retries, exponential backoff)
req, _ := http.NewRequest("GET", client.GetBaseURL()+"/data", nil)
resp, err := client.DoRequestWithRetry(context.Background(), req, nil)

// Or customize retry behavior
retryOpts := &httpkit.RetryOptions{
    MaxRetries:        5,
    RetryDelay:        200 * time.Millisecond,
    MaxRetryDelay:     5 * time.Second,
    BackoffMultiplier: 2.0,
    RetryableStatusCodes: []int{
        http.StatusTooManyRequests,
        http.StatusServiceUnavailable,
        http.StatusGatewayTimeout,
    },
}
resp, err := client.DoRequestWithRetry(context.Background(), req, retryOpts)

OpenTelemetry Tracing

import (
    "github.com/soulteary/http-kit"
    "go.opentelemetry.io/otel"
)

client, _ := httpkit.NewClient(&httpkit.Options{
    BaseURL: "https://api.example.com",
})

// Create a span in your application
tracer := otel.Tracer("my-service")
ctx, span := tracer.Start(context.Background(), "api-call")
defer span.End()

// Inject trace context into request headers
req, _ := http.NewRequest("GET", client.GetBaseURL()+"/data", nil)
client.InjectTraceContext(ctx, req)

resp, err := client.Do(req)

API Reference

Client Options

Retry Options

Client Methods

Project Structure

http-kit/
├── client.go       # HTTP client with TLS/mTLS support
├── client_test.go  # Client tests
├── retry.go        # Retry logic with exponential backoff
├── retry_test.go   # Retry tests
├── go.mod          # Module definition
└── LICENSE         # Apache 2.0 license

Security Features

Test Coverage

Run tests with coverage:

go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Requirements

• Go 1.21 or later

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.