HTTP Library

A comprehensive Go HTTP utilities library providing robust server and client functionality with extensive middleware capabilities, graceful shutdown support, and production-ready features.

Features

🚀 HTTP Server

Graceful shutdown with context cancellation
TLS support with automatic certificate handling
Background request processing for long-running operations
JSON response handlers with automatic content-type headers
Error handling middleware with structured error responses
Profiling endpoints (CPU, memory, pprof) for debugging
File serving capabilities

🔧 HTTP Client & RoundTrippers

Retry logic with configurable delays and skip conditions
Rate limiting to prevent API abuse
Authentication (Basic Auth, Header-based)
Request/response logging with configurable verbosity
Metrics collection (Prometheus compatible)
Header manipulation and path prefix removal
Request building utilities

🛡️ Proxy & Middleware

Reverse proxy with error handling
Sentry integration for error reporting
Background handlers for async processing
Content type utilities
Request validation and response checking

Installation

go get github.com/bborbe/http

Quick Start

Basic HTTP Server

package main

import (
    "context"
    "net/http"
    
    bhttp "github.com/bborbe/http"
    "github.com/bborbe/run"
    "github.com/gorilla/mux"
)

func main() {
    router := mux.NewRouter()
    router.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        w.Write([]byte("OK"))
    })
    
    server := bhttp.NewServerWithPort(8080, router)
    run.CancelOnInterrupt(context.Background(), server)
}

JSON Handler

type Response struct {
    Message string `json:"message"`
    Status  string `json:"status"`
}

func healthHandler(ctx context.Context, req *http.Request) (interface{}, error) {
    return Response{
        Message: "Service is healthy",
        Status:  "OK",
    }, nil
}

func main() {
    router := mux.NewRouter()
    
    // JSON handler automatically sets Content-Type and marshals response
    jsonHandler := bhttp.NewJsonHandler(bhttp.JsonHandlerFunc(healthHandler))
    errorHandler := bhttp.NewErrorHandler(jsonHandler)
    
    router.Handle("/api/health", errorHandler)
    
    server := bhttp.NewServerWithPort(8080, router)
    run.CancelOnInterrupt(context.Background(), server)
}

HTTP Client with Retry

package main

import (
    "context"
    "net/http"
    "time"
    
    bhttp "github.com/bborbe/http"
)

func main() {
    // Create HTTP client with retry logic
    transport := bhttp.NewRoundTripperRetry(
        http.DefaultTransport,
        3,                    // retry limit
        time.Second * 2,      // retry delay
    )
    
    client := &http.Client{
        Transport: transport,
        Timeout:   time.Second * 30,
    }
    
    // Make request - automatically retries on failure
    resp, err := client.Get("https://api.example.com/data")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
}

Background Request Handler

func longRunningTask(ctx context.Context, req *http.Request) error {
    // Simulate long-running task
    time.Sleep(10 * time.Second)
    
    // Your background processing logic here
    return nil
}

func main() {
    router := mux.NewRouter()
    
    // Background handler processes requests asynchronously
    bgHandler := bhttp.NewBackgroundRequestHandler(
        bhttp.BackgroundRequestHandlerFunc(longRunningTask),
    )
    errorHandler := bhttp.NewErrorHandler(bgHandler)
    
    router.Handle("/api/process", errorHandler)
    
    server := bhttp.NewServerWithPort(8080, router)
    run.CancelOnInterrupt(context.Background(), server)
}

HTTP Proxy

func main() {
    targetURL, _ := url.Parse("https://api.backend.com")
    
    // Create proxy with error handling
    errorHandler := bhttp.NewProxyErrorHandler()
    transport := http.DefaultTransport
    
    proxy := bhttp.NewProxy(transport, targetURL, errorHandler)
    
    server := bhttp.NewServerWithPort(8080, proxy)
    run.CancelOnInterrupt(context.Background(), server)
}

Advanced Client with Middleware Stack

func main() {
    // Build client with multiple middleware layers
    transport := http.DefaultTransport
    
    // Add retry logic
    transport = bhttp.NewRoundTripperRetry(transport, 3, time.Second*2)
    
    // Add authentication
    transport = bhttp.NewRoundTripperBasicAuth(transport, "username", "password")
    
    // Add logging
    transport = bhttp.NewRoundTripperLog(transport)
    
    // Add rate limiting
    transport = bhttp.NewRoundTripperRateLimit(transport, 10) // 10 req/sec
    
    client := &http.Client{
        Transport: transport,
        Timeout:   time.Second * 30,
    }
    
    // Client now has retry, auth, logging, and rate limiting
    resp, err := client.Get("https://api.example.com/protected")
    // Handle response...
}

Testing

The library includes comprehensive test coverage and mock generation using Counterfeiter:

# Run tests
make test

# Run all quality checks (format, test, lint, etc.)
make precommit

# Generate mocks for testing
make generate

Pre-generated Mocks

The library provides pre-generated mocks in the mocks/ package for easy testing:

import "github.com/bborbe/http/mocks"

// Available mocks:
// - HttpHandler
// - HttpJsonHandler  
// - HttpJsonHandlerTx
// - HttpProxyErrorHandler
// - HttpRoundtripper
// - HttpRoundtripperMetrics
// - HttpWithError

Example usage in tests:

func TestMyService(t *testing.T) {
    mockHandler := &mocks.HttpJsonHandler{}
    mockHandler.ServeHTTPReturns(map[string]string{"status": "ok"}, nil)
    
    // Use mock in your test...
}

Advanced Features

Profiling Support

Built-in handlers for performance profiling:

CPU profiling: /debug/pprof/profile
Memory profiling: /debug/pprof/heap
Goroutine profiling: /debug/pprof/goroutine

Metrics Integration

Prometheus-compatible metrics collection for monitoring request performance, error rates, and more.

Error Handling

Structured error handling with context preservation and optional Sentry integration for production error tracking.

Graceful Shutdown

All server components support graceful shutdown with proper resource cleanup when receiving termination signals.

API Documentation

Complete API documentation is available on pkg.go.dev.

View the documentation locally with:

go doc -all github.com/bborbe/http

Dependencies

This library uses minimal external dependencies:

Standard net/http package
github.com/bborbe/errors for enhanced error handling
github.com/bborbe/run for graceful lifecycle management
Optional Prometheus metrics support
Optional Sentry error reporting

License

BSD-style license. See LICENSE file for details.

# Packages

# README