httpserver

func DefaultCORSConfig ¶

func DefaultCORSConfig() CORSConfig

DefaultCORSConfig returns a permissive CORS configuration.

This is suitable for development. For production, customize the AllowedOrigins to your specific domains.

func DefaultConfig ¶

func DefaultConfig() Config

DefaultConfig returns a balanced configuration suitable for most use cases.

This configuration provides reasonable timeouts that protect against common attacks while being lenient enough for typical web applications.

Timeout values:

• ReadTimeout: 15s
• WriteTimeout: 15s
• IdleTimeout: 60s
• ShutdownTimeout: 10s

func DevelopmentConfig ¶

func DevelopmentConfig() Config

DevelopmentConfig returns a lenient configuration for local development.

Key differences from DefaultConfig:

• No read/write timeouts (allows debugging with breakpoints)
• Longer idle timeout (less connection churn during development)
• Very short shutdown timeout (fast restart during iteration)

Warning: Do not use this in production!

Timeout values:

• ReadTimeout: 0 (unlimited)
• WriteTimeout: 0 (unlimited)
• IdleTimeout: 120s
• ShutdownTimeout: 3s

func ProductionConfig ¶

func ProductionConfig() Config

ProductionConfig returns a hardened configuration optimized for production.

Designed for Kubernetes environments where the default terminationGracePeriodSeconds is 30s.

Rationale:

• ReadTimeout (10s): Most API requests complete in <1s; 10s catches slow clients while failing fast for genuinely stalled connections.
• WriteTimeout (10s): Matches read; responses should complete quickly.
• IdleTimeout (30s): Shorter than default to free resources faster; most HTTP/2 clients handle reconnection gracefully.
• ShutdownTimeout (25s): K8s sends SIGTERM, then waits terminationGracePeriodSeconds (30s) before SIGKILL. We use 25s to complete gracefully with 5s buffer. This allows in-flight requests to finish while ensuring we exit before K8s forcibly kills the pod.

Timeout values:

• ReadTimeout: 10s
• WriteTimeout: 10s
• IdleTimeout: 30s
• ShutdownTimeout: 25s (5s buffer before K8s SIGKILL at 30s)

func NewHealthHandler ¶

func NewHealthHandler(opts ...HealthOption) *HealthHandler

NewHealthHandler creates a new HealthHandler.

When using with httpserver, use WithHealth instead for automatic ServiceName.

Example (standalone):

health := httpserver.NewHealthHandler(
    httpserver.WithVersion("2.1.0"),
)

Example (with server - recommended):

var health *httpserver.HealthHandler
server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithHealth(&health, "2.1.0"),
)
// health is now usable with ServiceName auto-set

func WithVersion ¶

func WithVersion(version string) HealthOption

WithVersion sets the version for health responses.

func KeyFuncByClientID ¶

func KeyFuncByClientID() KeyFunc

KeyFuncByClientID returns a KeyFunc that uses the client_id from ServiceAuth.

Use Case ¶

Rate limit authenticated service clients. Use after ServiceAuth middleware.

Example ¶

// Each authenticated client gets 1000 req/sec across all endpoints
mux.Handle("/internal/", httpserver.Chain(
    httpserver.ServiceAuth(authConfig),
    httpserver.RateLimit(httpserver.RateLimitConfig{
        Limit:   1000,
        Burst:   2000,
        KeyFunc: httpserver.KeyFuncByClientID(),
    }),
)(handler))

Prerequisite ¶

Must be used after ServiceAuth middleware. Without authentication, returns empty string (all unauthenticated requests share one bucket).

func KeyFuncByClientIDAndPath ¶

func KeyFuncByClientIDAndPath() KeyFunc

KeyFuncByClientIDAndPath combines client_id and path.

Use Case ¶

Rate limit authenticated clients per endpoint. For example, a client might have different limits for read vs write operations.

Example ¶

// client-1 gets 100 req/sec to /api/read
// client-1 gets separate 10 req/sec to /api/write
mux.Handle("/api/", httpserver.Chain(
    httpserver.ServiceAuth(authConfig),
    httpserver.RateLimit(httpserver.RateLimitConfig{
        Limit:   100,
        Burst:   200,
        KeyFunc: httpserver.KeyFuncByClientIDAndPath(),
    }),
)(handler))

func KeyFuncByHeader ¶

func KeyFuncByHeader(header string) KeyFunc

KeyFuncByHeader returns a KeyFunc that extracts a value from a header.

Use Case ¶

Rate limit by a custom header, such as tenant ID or API key.

Example ¶

// Each tenant gets 100 req/sec
mux.Handle("/api/", httpserver.RateLimit(httpserver.RateLimitConfig{
    Limit:   100,
    Burst:   200,
    KeyFunc: httpserver.KeyFuncByHeader("X-Tenant-ID"),
})(handler))

func KeyFuncByIP ¶

func KeyFuncByIP() KeyFunc

KeyFuncByIP returns a KeyFunc that extracts the client IP.

Uses X-Forwarded-For header if present (for reverse proxy setups), otherwise falls back to RemoteAddr.

Use Case ¶

Rate limit each client IP independently. For example, 100 req/sec per IP means one abusive client doesn't affect other clients.

Example ¶

// Each IP can make 100 requests per second
mux.Handle("/api/", httpserver.RateLimit(httpserver.RateLimitConfig{
    Limit:   100,
    Burst:   200,
    KeyFunc: httpserver.KeyFuncByIP(),
})(handler))

func KeyFuncByIPAndPath ¶

func KeyFuncByIPAndPath() KeyFunc

KeyFuncByIPAndPath returns a KeyFunc that combines client IP and path.

Use Case ¶

Most granular rate limiting for public APIs. Each client IP gets its own rate limit bucket per endpoint.

Example ¶

// IP 1.2.3.4 gets 100 req/sec to /api/users
// IP 1.2.3.4 gets separate 100 req/sec to /api/orders
// IP 5.6.7.8 gets its own 100 req/sec to /api/users
mux.Handle("/api/", httpserver.RateLimit(httpserver.RateLimitConfig{
    Limit:   100,
    Burst:   200,
    KeyFunc: httpserver.KeyFuncByIPAndPath(),
})(handler))

func KeyFuncByPath ¶

func KeyFuncByPath() KeyFunc

KeyFuncByPath returns a KeyFunc that uses the URL path.

Use Case ¶

Rate limit each endpoint independently. For example, /api/search might have a lower limit than /api/users because it's more expensive.

Example ¶

// All requests to /api/search share 10 req/sec
// All requests to /api/users share separate 100 req/sec
mux.Handle("/api/", httpserver.RateLimit(httpserver.RateLimitConfig{
    Limit:   100,
    Burst:   200,
    KeyFunc: httpserver.KeyFuncByPath(),
})(handler))

Note ¶

This limits ALL clients combined per endpoint. For per-client per-endpoint, use KeyFuncByIPAndPath or KeyFuncByClientIDAndPath.

func NewMemoryCredentialValidator ¶

func NewMemoryCredentialValidator(clients map[string]string) *MemoryCredentialValidator

NewMemoryCredentialValidator creates a validator from a map of client_id -> passkey.

Example:

validator := httpserver.NewMemoryCredentialValidator(map[string]string{
    os.Getenv("SERVICE_CLIENT_ID"): os.Getenv("SERVICE_PASS_KEY"),
})

func NewMetrics ¶

func NewMetrics(cfg MetricsConfig) (*Metrics, error)

NewMetrics creates a new Metrics instance.

func DefaultMetricsConfig ¶

func DefaultMetricsConfig() MetricsConfig

DefaultMetricsConfig returns a default metrics configuration.

func CORS ¶

func CORS(cfg CORSConfig) Middleware

CORS returns middleware that handles Cross-Origin Resource Sharing.

Example:

handler := httpserver.CORS(httpserver.CORSConfig{
    AllowedOrigins:   []string{"https://example.com"},
    AllowCredentials: true,
})(myHandler)

func Chain ¶

func Chain(middlewares ...Middleware) Middleware

Chain composes multiple middleware into a single middleware.

Middleware are applied in the order provided. The first middleware is the outermost (runs first on request, last on response).

Example:

handler := httpserver.Chain(
    httpserver.Tracing(tp),
    httpserver.Recovery(),
    httpserver.Logger(logger),
)(myHandler)

Request flow:

Tracing -> Recovery -> Logger -> myHandler -> Logger -> Recovery -> Tracing

func DefaultMiddleware ¶

func DefaultMiddleware(opts ...MiddlewareOption) Middleware

DefaultMiddleware returns a production-ready middleware stack.

The stack includes (in order):

1. Recovery - Panic recovery
2. RequestID - X-Request-ID generation/forwarding
3. Logger - Request/response logging (if logger provided)

For full observability, add Tracing() middleware manually with your TracerProvider.

Example:

handler := httpserver.Tracing(tp)(
    httpserver.DefaultMiddleware(logger)(myHandler),
)

func Logger ¶

func Logger(cfg LoggerConfig) Middleware

Logger returns middleware that logs HTTP requests.

Logs include:

• Method, path, status code
• Request duration
• Request ID (if present)
• Client IP
• Request/Response bodies (if enabled)

Example:

handler := httpserver.Logger(httpserver.LoggerConfig{
    Logger:    logger,
    SkipPaths: []string{"/livez", "/readyz", "/ping"},
})(myHandler)

func RateLimit ¶

func RateLimit(cfg RateLimitConfig) Middleware

RateLimit returns middleware that limits request rate using token bucket algorithm.

func RateLimitByIP ¶

func RateLimitByIP(limit rate.Limit, burst int) Middleware

RateLimitByIP returns rate limiting middleware keyed by client IP.

func RateLimitByIPRedis ¶

func RateLimitByIPRedis(rdb redis.UniversalClient, limit rate.Limit, burst int) Middleware

RateLimitByIPRedis returns distributed rate limiting middleware keyed by client IP.

func Recovery ¶

func Recovery(logger zerolog.Logger) Middleware

Recovery returns middleware that recovers from panics.

When a panic occurs:

• The panic is recovered
• A 500 Internal Server Error is returned
• The stack trace is logged (if logger provided)
• The request continues to the next middleware

Example:

handler := httpserver.Recovery(logger)(myHandler)

func RequestID ¶

func RequestID() Middleware

RequestID returns middleware that generates or forwards request IDs.

Behavior:

• If X-Request-ID header exists, use it
• Otherwise, generate a new UUID v4
• Add the ID to the response header
• Store the ID in the request context

Example:

handler := httpserver.RequestID()(myHandler)

// Access in handler:
func myHandler(w http.ResponseWriter, r *http.Request) {
    id := httpserver.RequestIDFromContext(r.Context())
    log.Printf("Request ID: %s", id)
}

func ServiceAuth ¶

func ServiceAuth(cfg ServiceAuthConfig) Middleware

ServiceAuth returns middleware that validates service-to-service credentials.

Requires both Client-ID and Pass-Key headers to be present and valid. On failure, returns 401 Unauthorized with a generic error message.

Example with in-memory validator:

validator := httpserver.NewMemoryCredentialValidator(map[string]string{
    os.Getenv("CLIENT_ID"): os.Getenv("PASS_KEY"),
})

mux.Handle("/internal/", httpserver.ServiceAuth(httpserver.ServiceAuthConfig{
    Validator: validator,
})(internalHandler))

Example with database validator:

validator := httpserver.NewSQLCredentialValidator(db,
    "SELECT passkey FROM service_credentials WHERE client_id = $1 AND is_active = true",
)

mux.Handle("/internal/", httpserver.ServiceAuth(httpserver.ServiceAuthConfig{
    Validator: validator,
})(internalHandler))

func Timeout ¶

func Timeout(timeout time.Duration) Middleware

Timeout returns middleware that limits request processing time.

If the handler takes longer than the timeout, the request context is cancelled and a 503 Service Unavailable response is returned.

Note: The handler must respect context cancellation for this to work effectively.

Example:

handler := httpserver.Timeout(30 * time.Second)(myHandler)

func Tracing ¶

func Tracing(cfg TracingConfig) Middleware

Tracing returns middleware that adds OpenTelemetry tracing to requests.

Features:

• Extracts trace context from incoming requests (W3C TraceContext)
• Creates server spans with standard HTTP attributes
• Records errors on 5xx responses
• Propagates span context to downstream handlers

Example:

handler := httpserver.Tracing(httpserver.TracingConfig{
    TracerProvider: tp,
    ServiceName:    "api-gateway",
})(myHandler)

func WithDefaultLogger ¶

func WithDefaultLogger(cfg LoggerConfig) MiddlewareOption

WithDefaultLogger adds logging middleware to DefaultMiddleware.

func WithConfig ¶

func WithConfig(cfg Config) Option

WithConfig applies all settings from a Config struct.

This is the recommended way to configure the server. Use one of the preset configurations (DefaultConfig, ProductionConfig, DevelopmentConfig) as a starting point, then override specific fields as needed.

Example:

cfg := httpserver.ProductionConfig()
cfg.Addr = ":9090"
cfg.ShutdownTimeout = 30 * time.Second

server := httpserver.New(
    httpserver.WithConfig(cfg),
    httpserver.WithServiceName("my-api"),
    httpserver.WithHandler(mux),
)

func WithHandler ¶

func WithHandler(h http.Handler) Option

WithHandler sets the HTTP handler for the server.

This is required. The handler will be wrapped with any configured middleware in the order they are specified.

Example:

mux := http.NewServeMux()
mux.HandleFunc("/", homeHandler)

server := httpserver.New(
    httpserver.WithHandler(mux),
)

func WithHealth ¶

func WithHealth(handler **HealthHandler, version string) Option

WithHealth enables health check endpoints with auto-configured ServiceName.

This creates a HealthHandler with the server's ServiceName and version, and returns it for adding checks and registering routes.

Example:

var health *httpserver.HealthHandler
server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithHealth(&health, "1.0.0"),
    httpserver.WithHandler(mux),
)

health.AddReadinessCheck("database", dbPingCheck)
mux.Handle("/ping", health.PingHandler())
mux.Handle("/livez", health.LiveHandler())
mux.Handle("/readyz", health.ReadyHandler())

func WithLogger ¶

func WithLogger(l zerolog.Logger) Option

WithLogger sets the server logger for lifecycle events only.

This logger is used for:

• Server startup messages
• Graceful shutdown logging
• Internal errors

For REQUEST logging (each HTTP request/response), use WithLogging instead. You can use both: WithLogger for server events, WithLogging for requests.

Example:

logger := zerolog.New(os.Stdout).With().Timestamp().Logger()
server := httpserver.New(
    httpserver.WithLogger(logger),  // Server events
    httpserver.WithLogging(httpserver.LoggerConfig{Logger: logger}),  // Requests
    httpserver.WithHandler(mux),
)

func WithLogging ¶

func WithLogging(cfg LoggerConfig) Option

WithLogging enables request logging middleware.

The server's ServiceName is automatically included in all log entries. You don't need to set ServiceName in LoggerConfig.

Example:

logger := zerolog.New(os.Stdout).With().Timestamp().Logger()
server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithLogging(httpserver.LoggerConfig{
        Logger:    logger,
        SkipPaths: []string{"/livez", "/readyz", "/ping"},
    }),
    httpserver.WithHandler(mux),
)

func WithMetrics ¶

func WithMetrics(cfg MetricsConfig) Option

WithMetrics enables OpenTelemetry metrics middleware.

The server's ServiceName is automatically applied to all metrics. You don't need to set ServiceName in MetricsConfig.

Example:

server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithMetrics(httpserver.MetricsConfig{
        SkipPaths: []string{"/livez", "/readyz", "/ping"},
    }),
    httpserver.WithHandler(mux),
)

func WithMiddleware ¶

func WithMiddleware(ms ...Middleware) Option

WithMiddleware adds middleware to wrap the handler.

Middleware is applied in order (first middleware wraps outermost). Use this for custom middleware or when you need fine-grained control.

For built-in middleware (tracing, metrics, logging), prefer the dedicated options (WithTracing, WithMetrics, WithLogging) which automatically inject the server's ServiceName.

Example:

server := httpserver.New(
    httpserver.WithHandler(mux),
    httpserver.WithMiddleware(
        httpserver.Recovery(logger),
        httpserver.RequestID(),
        httpserver.CORS(corsConfig),
    ),
)

func WithRateLimit ¶

func WithRateLimit(cfg RateLimitConfig) Option

WithRateLimit enables global rate limiting for all requests.

For per-endpoint rate limiting, use the RateLimit middleware directly on specific routes instead.

Example (global rate limit):

server := httpserver.New(
    httpserver.WithRateLimit(httpserver.RateLimitConfig{
        Limit: 100,  // 100 requests per second
        Burst: 200,  // Allow bursts up to 200
    }),
    httpserver.WithHandler(mux),
)

Example (per-endpoint rate limit - add middleware to specific routes):

// Apply stricter limit to sensitive endpoint
mux.Handle("/api/login", httpserver.RateLimitByIP(10, 20)(loginHandler))

// Apply different limit to API endpoints
mux.Handle("/api/", httpserver.RateLimit(httpserver.RateLimitConfig{
    Limit: 50,
    Burst: 100,
})(apiHandler))

func WithServiceName ¶

func WithServiceName(name string) Option

WithServiceName sets the service name for the entire server.

This is the SINGLE source of truth for service identity. The server automatically passes this value to all components that need it:

• Tracing spans (service.name attribute)
• Metrics (service.name label)
• Request logs (service field)
• Health check responses (service field)

Example:

server := httpserver.New(
    httpserver.WithServiceName("payment-api"),
    httpserver.WithHandler(mux),
)

func WithTracing ¶

func WithTracing(cfg TracingConfig) Option

WithTracing enables OpenTelemetry tracing middleware.

The server's ServiceName is automatically applied to all spans. You don't need to set ServiceName in TracingConfig.

Example:

server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithTracing(httpserver.TracingConfig{
        SkipPaths: []string{"/livez", "/readyz", "/ping"},
    }),
    httpserver.WithHandler(mux),
)

func DefaultPprofConfig ¶

func DefaultPprofConfig() PprofConfig

DefaultPprofConfig returns default pprof configuration.

func DefaultRateLimitConfig ¶

func DefaultRateLimitConfig() RateLimitConfig

DefaultRateLimitConfig returns a default rate limit configuration.

func NewSQLCredentialValidator ¶

func NewSQLCredentialValidator(db *sql.DB, query string) *SQLCredentialValidator

NewSQLCredentialValidator creates a validator that queries a database.

The query should return the passkey for a given client_id. Example query: "SELECT passkey FROM service_credentials WHERE client_id = $1 AND is_active = true"

Example:

validator := httpserver.NewSQLCredentialValidator(
    db,
    "SELECT passkey FROM service_credentials WHERE client_id = $1",
)

func New ¶

func New(opts ...Option) *Server

New creates a new Server with the provided options.

At minimum, you must provide a handler using WithHandler(). If no config is provided, DefaultConfig() is used.

Example:

server := httpserver.New(
    httpserver.WithServiceName("my-api"),
    httpserver.WithHandler(mux),
    httpserver.WithMiddleware(
        httpserver.Recovery(logger),
        httpserver.RequestID(),
    ),
)

func DefaultTracingConfig ¶

func DefaultTracingConfig() TracingConfig

DefaultTracingConfig returns a default tracing configuration.