httpx

httpx: Minimalist HTTP Extensions for Go

中文 | English

httpx is a set of HTTP extension tools based on Go 1.18+ generics. It is not a heavy web framework, but a powerful enhancement for the standard library net/http.

It aims to eliminate repetitive JSON decoding, parameter validation, and response encapsulation code in http.Handler through Generics, while maintaining full compatibility with the standard library.

Core Concepts

1. Type Safety: Leveraging generics to transform func(w, r) into strongly typed func(ctx, *Req) (*Res, error).
2. Modern Conventions: Uses String Codes (e.g., "OK", "INVALID_ARGUMENT") for business logic, distinct from HTTP Status Codes.
3. Performance at Scale: Provides a SelfValidatable interface to bypass reflection validation; integrates httpsnoop for zero-overhead metric capture.
4. Production Ready: Built-in protection against large bodies, memory limits for uploads, and graceful shutdown for long-lived connections.

Installation

go get github.com/oy3o/httpx

Quick Start

1. Define Request & Response

Use json, form, or path tags to define the structure.

type LoginReq struct {
    // Supports Go 1.22+ PathValue
    TenantID string `path:"tenant_id"` 
    Username string `json:"username" validate:"required,min=3"`
    Password string `json:"password" validate:"required"`
}

type LoginRes struct {
    Token string `json:"token"`
}

2. Write Business Logic

No need to manipulate http.ResponseWriter and *http.Request.

import "github.com/oy3o/httpx"

func LoginHandler(ctx context.Context, req *LoginReq) (*LoginRes, error) {
    if req.Username == "admin" && req.Password == "123456" {
        return &LoginRes{Token: "abc-123"}, nil
    }
    
    // Return an error. httpx automatically maps HTTP Status to a Business Code.
    // E.g., 401 -> "UNAUTHORIZED"
    return nil, httpx.ErrUnauthorized
}

3. Register Routes

Use httpx.NewHandler to convert business functions into standard http.Handlers. Use httpx.NewStreamHandler to convert streamable business functions into standard http.Handlers.

func main() {
    mux := http.NewServeMux()

    // Register Handler with Options (Safety limits)
    mux.Handle("POST /login/{tenant_id}", httpx.NewHandler(LoginHandler, 
        httpx.WithMaxBodySize(2<<20), // Limit body to 2MB
    ))

    // Add middleware chain
    handler := httpx.Chain(mux, 
        httpx.Recovery(nil),
        httpx.Logger(nil),
        httpx.SecurityHeaders(), // Security hardening
        httpx.DefaultCORS(),
    )

    http.ListenAndServe(":8080", handler)
}

Core Features

1. Cooperative Binding

httpx.Bind automatically aggregates data from multiple sources:

• Path: Go 1.22 r.PathValue (Tag: path).
• Query: URL Query parameters (Tag: form).
• Body: JSON or Form/Multipart based on Content-Type.
• Priority: Path > Body > Query.

2. Hybrid Validation (High Performance)

• Reflection Mode: Use struct tags (validate:"required"). fast for development.
• Interface Mode: Implement SelfValidatable. Zero reflection overhead, ideal for hot paths.

// Fast Validation: httpx calls this method first, skipping reflection
func (r *LoginReq) Validate(ctx context.Context) error {
    if len(r.Username) < 3 {
        return errors.New("username too short")
    }
    return nil
}

3. Semantic Error Handling & Trace Injection

Separates HTTP Status from Business Code. Automatically injects X-Trace-ID into headers and the response body if a Trace provider is configured.

{
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials",
    "trace_id": "a1b2c3d4"
}

4. Safety & Protection

• WithMaxBodySize(bytes): Limits the request body size. Returns 413 Entity Too Large if exceeded.
• WithMultipartLimit(bytes): Limits memory usage during file uploads. Excess data spills to disk.

Middleware Ecosystem

Advanced: Graceful Shutdown for Long Connections

Standard http.Server.Shutdown does not terminate hijacked connections (like WebSockets) immediately. httpx.ShutdownManager solves this.

// 1. Create Manager
mgr := httpx.NewShutdownManager()

// 2. Wrap Handler
mux.Handle("/ws", mgr.Middleware(websocketHandler))

// 3. Inside Handler
func websocketHandler(w http.ResponseWriter, r *http.Request) {
    // Register cleanup callback
    httpx.RegisterOnShutdown(r.Context(), func() {
        conn.WriteMessage(websocket.CloseMessage, ...)
        conn.Close()
    })
    // ... loop ...
}

// 4. On Server Shutdown
mgr.Shutdown(ctx) // Triggers all registered callbacks