httputil

Documentation

Overview

Package httputil provides shared HTTP client creation and configuration. It integrates with the config system for centralized HTTP settings while providing sensible defaults for standalone usage.

Index

• Constants
• func InstrumentedHandler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler
• func InstrumentedMiddleware(operation string, opts ...otelhttp.Option) func(http.Handler) http.Handler
• func InstrumentedTransport(base http.RoundTripper, opts ...otelhttp.Option) http.RoundTripper
• func NewClient(timeout time.Duration) *http.Client
• func NewClientFromConfig(cfg ClientConfig) *http.Client
• func NewInstrumentedClient(timeout time.Duration) *http.Client
• func NewInstrumentedRetryableClient(timeout time.Duration) *http.Client
• func NewRetryableClient(timeout time.Duration) *http.Client
• func NewRetryableClientWithConfig(timeout time.Duration, retryMax int, retryWaitMin, retryWaitMax time.Duration) *http.Client
• func NewSafeClient(timeout time.Duration) *http.Client
• func NewSafeInstrumentedClient(timeout time.Duration) *http.Client
• func NewSafeInstrumentedRetryableClient(timeout time.Duration) *http.Client
• func NewSafeRetryableClient(timeout time.Duration) *http.Client
• func NewSafeTransport() *http.Transport
• func NewSafeTransportFromConfig(cfg ClientConfig) *http.Transport
• func NewSafeTransportWithOptions(opts ...network.Option) *http.Transport
• func NewTransport() *http.Transport
• func NewTransportFromConfig(cfg ClientConfig) *http.Transport
• type ClientConfig
  • func DefaultClientConfig() ClientConfig

Constants

const (
	// DefaultDialTimeout is the maximum time to establish a TCP connection.
	DefaultDialTimeout = 10 * time.Second

	// DefaultKeepAlive is the interval between TCP keep-alive probes.
	DefaultKeepAlive = 30 * time.Second

	// DefaultIdleConnTimeout is how long idle connections remain in the pool.
	DefaultIdleConnTimeout = 90 * time.Second

	// DefaultTLSHandshakeTimeout is the maximum time for TLS handshake.
	DefaultTLSHandshakeTimeout = 10 * time.Second

	// DefaultResponseHeaderTimeout is the maximum time to wait for response headers.
	DefaultResponseHeaderTimeout = 20 * time.Second

	// DefaultMaxIdleConns is the maximum number of idle connections in the pool.
	DefaultMaxIdleConns = 20

	// DefaultMaxIdleConnsPerHost is the maximum number of idle connections per host.
	// The default http.Transport value is 2, which limits connection reuse when
	// talking to a single upstream. We set this higher to improve throughput.
	DefaultMaxIdleConnsPerHost = 10
)

Common HTTP client timeout constants used across deputy subsystems. These values represent best practices for production HTTP clients.

const (
	// DefaultRetryMax is the maximum number of retries for transient failures.
	DefaultRetryMax = 3

	// DefaultRetryWaitMin is the minimum wait time between retries.
	DefaultRetryWaitMin = 500 * time.Millisecond

	// DefaultRetryWaitMax is the maximum wait time between retries.
	DefaultRetryWaitMax = 5 * time.Second
)

Retry configuration defaults for retryable HTTP clients.

Functions

func InstrumentedHandler

func InstrumentedHandler(handler http.Handler, operation string, opts ...otelhttp.Option) http.Handler

InstrumentedHandler wraps an http.Handler with OpenTelemetry tracing. Creates server spans for incoming HTTP requests.

func InstrumentedMiddleware

func InstrumentedMiddleware(operation string, opts ...otelhttp.Option) func(http.Handler) http.Handler

InstrumentedMiddleware returns middleware that wraps handlers with OTel tracing.

func InstrumentedTransport

func InstrumentedTransport(base http.RoundTripper, opts ...otelhttp.Option) http.RoundTripper

InstrumentedTransport wraps an http.RoundTripper with OpenTelemetry tracing. Creates client spans for outgoing HTTP requests with proper context propagation. If base is nil, uses http.DefaultTransport.

func NewClient

func NewClient(timeout time.Duration) *http.Client

NewClient returns an http.Client with the given timeout and a production transport.

func NewClientFromConfig

func NewClientFromConfig(cfg ClientConfig) *http.Client

NewClientFromConfig creates an http.Client configured from ClientConfig. If retry is enabled and RetryMax > 0, the client will automatically retry transient failures with exponential backoff.

func NewInstrumentedClient

func NewInstrumentedClient(timeout time.Duration) *http.Client

NewInstrumentedClient returns an http.Client with OTel tracing enabled. All outgoing requests will create spans and propagate trace context.

func NewInstrumentedRetryableClient

func NewInstrumentedRetryableClient(timeout time.Duration) *http.Client

NewInstrumentedRetryableClient returns a retryable http.Client with OTel tracing. Combines automatic retry support with distributed tracing.

func NewRetryableClient

func NewRetryableClient(timeout time.Duration) *http.Client

NewRetryableClient returns an http.Client with automatic retry support for transient failures (5xx errors, connection errors, etc.). This is ideal for external API calls to services like GitHub, OSV, or package registries.

The client uses exponential backoff with jitter and respects Retry-After headers. Logging is disabled by default to avoid noisy output.

func NewRetryableClientWithConfig

func NewRetryableClientWithConfig(timeout time.Duration, retryMax int, retryWaitMin, retryWaitMax time.Duration) *http.Client

NewRetryableClientWithConfig returns a retryable HTTP client with custom retry settings. Use this when you need different retry behavior than the defaults.

func NewSafeClient

func NewSafeClient(timeout time.Duration) *http.Client

NewSafeClient returns an http.Client with SSRF protection using network.SafeDialer. It blocks connections to private networks, loopback addresses, link-local addresses, and common cloud metadata endpoints. Use this for any HTTP requests to user-controlled URLs.

func NewSafeInstrumentedClient

func NewSafeInstrumentedClient(timeout time.Duration) *http.Client

NewSafeInstrumentedClient returns an http.Client with both SSRF protection and OTel tracing. Combines SafeDialer protection with distributed tracing for user-controlled URLs.

func NewSafeInstrumentedRetryableClient

func NewSafeInstrumentedRetryableClient(timeout time.Duration) *http.Client

NewSafeInstrumentedRetryableClient returns a retryable http.Client with SSRF protection and OTel tracing. Combines SafeDialer protection, automatic retry support, and distributed tracing. Use this for external API calls to user-controlled URLs that need both retry and observability.

func NewSafeRetryableClient

func NewSafeRetryableClient(timeout time.Duration) *http.Client

NewSafeRetryableClient returns an http.Client with automatic retry support and SSRF protection. It combines exponential backoff for transient failures with SafeDialer to block connections to private networks, loopback addresses, link-local addresses, and cloud metadata endpoints.

Use this for external API calls to user-controlled URLs that need retry support.

func NewSafeTransport

func NewSafeTransport() *http.Transport

NewSafeTransport returns an http.Transport with SSRF protection using network.SafeDialer. It blocks connections to private networks, loopback addresses, link-local addresses, and common cloud metadata endpoints. Use this for any HTTP requests to user-controlled URLs.

The transport uses the same production-friendly defaults as NewTransport.

func NewSafeTransportFromConfig

func NewSafeTransportFromConfig(cfg ClientConfig) *http.Transport

NewSafeTransportFromConfig creates an http.Transport with SSRF protection from the provided configuration. This is a convenience function equivalent to setting EnableSSRFProtection=true in the config.

func NewSafeTransportWithOptions

func NewSafeTransportWithOptions(opts ...network.Option) *http.Transport

NewSafeTransportWithOptions returns an http.Transport with SSRF protection and custom SafeDialer options. Use this when you need to customize the SafeDialer behavior (e.g., allow private networks).

Example:

transport := NewSafeTransportWithOptions(network.WithAllowPrivate())

func NewTransport

func NewTransport() *http.Transport

NewTransport returns an http.Transport configured with production-friendly defaults. The transport uses sensible timeouts for dialing, TLS, and connection pooling.

func NewTransportFromConfig

func NewTransportFromConfig(cfg ClientConfig) *http.Transport

NewTransportFromConfig creates an http.Transport from the provided configuration. If EnableSSRFProtection is true, the transport uses SafeDialer for SSRF protection.

Types

type ClientConfig

type ClientConfig struct {
	// Connection timeouts
	Timeout               time.Duration
	DialTimeout           time.Duration
	TLSHandshakeTimeout   time.Duration
	ResponseHeaderTimeout time.Duration
	KeepAlive             time.Duration
	IdleConnTimeout       time.Duration

	// Connection pool settings
	MaxIdleConns        int
	MaxIdleConnsPerHost int

	// Retry settings
	RetryEnabled bool
	RetryMax     int
	RetryWaitMin time.Duration
	RetryWaitMax time.Duration

	// Instrumentation
	EnableOTel bool

	// Security
	// EnableSSRFProtection enables SafeDialer to block connections to private networks,
	// loopback addresses, link-local addresses, and cloud metadata endpoints.
	// Use this for clients that make requests to user-controlled URLs.
	EnableSSRFProtection bool

	// SafeDialerOptions allows customizing SafeDialer behavior when EnableSSRFProtection is true.
	// For example, use network.WithAllowPrivate() to allow internal network access.
	SafeDialerOptions []network.Option
}

ClientConfig contains all settings needed to create an HTTP client. This mirrors config.HTTPConfig but avoids a circular dependency.

func DefaultClientConfig

func DefaultClientConfig() ClientConfig

DefaultClientConfig returns a ClientConfig with production-ready defaults.