Documentation
¶
Overview ¶
Package http provides a small, composable HTTP client with request/response interceptors, default headers, basic auth, and a retry mechanism with exponential backoff and jitter.
Retries
- Controlled via Builder.WithRetries(maxRetries, retryDelay).
- Retries occur on:
- Transport errors (network failures)
- Timeouts (context deadline exceeded or net.Error timeout)
- HTTP 5xx responses
- 4xx responses are not retried.
Backoff Strategy
- Exponential backoff based on retryDelay: delay = retryDelay * 2^attempt
- Full jitter is applied: actual sleep is random in [0, delay).
- Delay is capped at 30 seconds to avoid excessive waits.
Notes
- Request bodies are re-sent by rebuilding the http.Request on each attempt.
- Interceptor errors are not retried and are surfaced immediately.
Index ¶
- Constants
- func IsErrorType(err error, errorType ErrorType) bool
- func IsHTTPStatusError(err error, statusCode int) bool
- func IsSuccessStatus(statusCode int) bool
- type BasicAuth
- type Builder
- func (b *Builder) Build() Client
- func (b *Builder) WithBasicAuth(username, password string) *Builder
- func (b *Builder) WithDefaultHeader(key, value string) *Builder
- func (b *Builder) WithRequestInterceptor(interceptor RequestInterceptor) *Builder
- func (b *Builder) WithResponseInterceptor(interceptor ResponseInterceptor) *Builder
- func (b *Builder) WithRetries(maxRetries int, retryDelay time.Duration) *Builder
- func (b *Builder) WithTimeout(timeout time.Duration) *Builder
- type Client
- type ClientError
- func NewHTTPError(message string, statusCode int, body []byte) ClientError
- func NewInterceptorError(message, stage string, wrapped error) ClientError
- func NewNetworkError(message string, wrapped error) ClientError
- func NewTimeoutError(message string, timeout time.Duration) ClientError
- func NewValidationError(message, field string) ClientError
- type Config
- type ErrorType
- type Request
- type RequestInterceptor
- type Response
- type ResponseInterceptor
- type Stats
Constants ¶
const ( // DefaultTimeout is the default request timeout duration DefaultTimeout = 30 * time.Second // DefaultMaxRetries is the default maximum number of retries for failed requests DefaultMaxRetries = 0 // DefaultRetryDelay is the default delay between retries DefaultRetryDelay = 1 * time.Second )
Variables ¶
This section is empty.
Functions ¶
func IsErrorType ¶
IsErrorType checks if an error is of a specific type
func IsHTTPStatusError ¶
IsHTTPStatusError checks if an error is an HTTP error with a specific status code
func IsSuccessStatus ¶
IsSuccessStatus checks if a status code represents success (2xx)
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder provides a fluent interface for configuring the REST client
func NewBuilder ¶
NewBuilder creates a new client builder
func (*Builder) WithBasicAuth ¶
WithBasicAuth sets basic authentication credentials
func (*Builder) WithDefaultHeader ¶
WithDefaultHeader adds a default header that will be sent with all requests
func (*Builder) WithRequestInterceptor ¶
func (b *Builder) WithRequestInterceptor(interceptor RequestInterceptor) *Builder
WithRequestInterceptor adds a request interceptor
func (*Builder) WithResponseInterceptor ¶
func (b *Builder) WithResponseInterceptor(interceptor ResponseInterceptor) *Builder
WithResponseInterceptor adds a response interceptor
func (*Builder) WithRetries ¶
WithRetries sets the retry configuration
type Client ¶
type Client interface {
Get(ctx context.Context, req *Request) (*Response, error)
Post(ctx context.Context, req *Request) (*Response, error)
Put(ctx context.Context, req *Request) (*Response, error)
Patch(ctx context.Context, req *Request) (*Response, error)
Delete(ctx context.Context, req *Request) (*Response, error)
Do(ctx context.Context, method string, req *Request) (*Response, error)
}
Client defines the REST client interface for making HTTP requests
type ClientError ¶
ClientError represents different types of REST client errors
func NewHTTPError ¶
func NewHTTPError(message string, statusCode int, body []byte) ClientError
NewHTTPError creates a new HTTP error
func NewInterceptorError ¶
func NewInterceptorError(message, stage string, wrapped error) ClientError
NewInterceptorError creates a new interceptor error
func NewNetworkError ¶
func NewNetworkError(message string, wrapped error) ClientError
NewNetworkError creates a new network error
func NewTimeoutError ¶
func NewTimeoutError(message string, timeout time.Duration) ClientError
NewTimeoutError creates a new timeout error
func NewValidationError ¶
func NewValidationError(message, field string) ClientError
NewValidationError creates a new validation error
type Config ¶
type Config struct {
Timeout time.Duration
MaxRetries int
RetryDelay time.Duration
RequestInterceptors []RequestInterceptor
ResponseInterceptors []ResponseInterceptor
BasicAuth *BasicAuth
DefaultHeaders map[string]string
// LogPayloads enables debug-level logging of headers and body payloads
LogPayloads bool
// MaxPayloadLogBytes caps the number of body bytes logged when LogPayloads is enabled
MaxPayloadLogBytes int
}
Config holds the REST client configuration
type RequestInterceptor ¶
RequestInterceptor is called before sending the request
Source Files