rhttp

Documentation

Index

• Variables
• func ClassifyError(response *http.Response, err error) error
• type Client
  • func NewClient(pipeline Pipeline) (*Client, error)
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
• type Handler
  • func HttpHandler(c *http.Client) Handler
• type Middleware
  • func NewBreakerMiddleware(cb *breaker.CircuitBreaker) Middleware
  • func NewClassifierMiddleware() Middleware
  • func NewHedgeMiddleware(delay time.Duration, maxAttempts int) Middleware
  • func NewLimiterMiddleware(l *limiter.Limiter) Middleware
  • func NewRetryMiddleware(policy *retry.RetryPolicy[*http.Response]) Middleware
  • func NewTimeoutMiddleware(d time.Duration) Middleware
• type Pipeline
• type Request

Variables

var (
	ErrRateLimited = errors.New("rate limit")    // 429 Too Many Requests.
	ErrClientError = errors.New("client error")  // 408 Request Timeout, 425 Too Early.
	ErrServerError = errors.New("server error")  // 5xx server errors.
	ErrUnknown     = errors.New("unknown error") // Nil response or unclassified error.
)

var ErrClientCreation = errors.New("client creation failed: requires an http.Client or a custom Handler")

var ShouldRetryDefault = func(response *http.Response, err error) bool {
	if err != nil {
		return true
	}

	if response == nil {
		return true
	}

	switch response.StatusCode {
	case http.StatusRequestTimeout,
		http.StatusTooEarly,
		http.StatusTooManyRequests,
		http.StatusInternalServerError,
		http.StatusBadGateway,
		http.StatusServiceUnavailable,
		http.StatusGatewayTimeout:
		return true
	}

	return false
}

ShouldRetryDefault returns a strategy that retries on network errors (err != nil) or server-side HTTP errors (status >= 500), except for common rate-limiting signals.

Functions

func ClassifyError

func ClassifyError(response *http.Response, err error) error

ClassifyError converts an HTTP response into a classification error. Returns the original error if present; otherwise classifies by status code. Used by the circuit breaker and retry middlewares to determine failure classification.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the primary entry point for the resilience library. It holds the compiled middleware chain.

func NewClient

func NewClient(pipeline Pipeline) (*Client, error)

NewClient assembles a resilience pipeline into a functional Client. It chains middlewares in the correct order to ensure optimal protection and performance.

func (*Client) Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do executes the given http.Request through the pre-configured resilience pipeline. It initializes the Request context, including the initial timestamp (Now).

type Handler

type Handler func(Request) (*http.Response, error)

Handler is the functional interface for executing a Request. Middlewares wrap these handlers to inject resilience logic.

func HttpHandler

func HttpHandler(c *http.Client) Handler

HttPHandler wraps a standard http.Client.Do call into the resilience Handler interface.

type Middleware

type Middleware func(Handler) Handler

Middleware is a higher-order function that takes a Handler and returns a decorated Handler.

func NewBreakerMiddleware

func NewBreakerMiddleware(cb *breaker.CircuitBreaker) Middleware

NewBreakerMiddleware creates a middleware that protects the handler using a circuit breaker. It tracks failure rates and opens the circuit if a threshold is reached, preventing further requests from reaching failing downstream services.

func NewClassifierMiddleware

func NewClassifierMiddleware() Middleware

NewClassifierMiddleware classifies HTTP responses and converts status codes into errors. This enables the circuit breaker to track failures and the retry middleware to make decisions based on status codes rather than transport-level errors alone.

func NewHedgeMiddleware

func NewHedgeMiddleware(delay time.Duration, maxAttempts int) Middleware

NewHedgeMiddleware creates a middleware that implements the Hedged Requests pattern. If the primary request is slow (takes longer than 'delay'), additional parallel attempts are fired. The first successful response (or the last failure) is returned.

func NewLimiterMiddleware

func NewLimiterMiddleware(l *limiter.Limiter) Middleware

NewLimiterMiddleware creates a middleware that enforces concurrency limits using a Limiter instance. It integrates with the resilience pipeline to provide adaptive backpressure.

func NewRetryMiddleware

func NewRetryMiddleware(policy *retry.RetryPolicy[*http.Response]) Middleware

NewRetryMiddleware creates a middleware that implements sequential retries. It uses a provided RetryPolicy to manage backoff, budgets, and per-try deadlines.

func NewTimeoutMiddleware

func NewTimeoutMiddleware(d time.Duration) Middleware

NewTimeoutMiddleware creates a middleware that enforces a global timeout for the entire request pipeline. It sets the RequestDeadline field in the Request struct and checks it both before and after calling the next handler in the chain.

type Pipeline

type Pipeline struct {
	HttpClient     *http.Client // The underlying HTTP client to use.
	HttpHandler    Handler      // An optional custom handler (useful for testing or non-HTTP protocols).
	Timeout        Middleware   // Global timeout enforcement.
	Retry          Middleware   // Sequential retry logic with backoff.
	Hedge          Middleware   // Parallel hedging strategy.
	Limiter        Middleware   // Rate limiting or concurrency control.
	CircuitBreaker Middleware   // Fault tolerance and failure isolation.
	Classifier     Middleware
}

Pipeline defines the configuration for building a resilience chain. The order of execution follows: Limiter -> CircuitBreaker -> Timeout -> Retry -> Hedge -> Handler.

type Request

type Request struct {
	Req             *http.Request // The original HTTP request to be executed.
	RequestDeadline int64         // Absolute Unix Nano timestamp for the global request deadline.
	TryDeadline     int64         // Absolute Unix Nano timestamp for a single attempt deadline.
	Now             int64         // Cached Unix Nano timestamp to avoid redundant time.Now() calls.
}

Request represents a single logical execution within the resilience pipeline. It carries the original http.Request along with deadlines and cached timestamps to minimize system calls and facilitate cross-middleware coordination.