Documentation
¶
Overview ¶
Package httpclient provides an HTTP client with retry, backoff, and rate limit handling.
Features:
- Automatic retry with exponential backoff
- Rate limit header parsing (Anthropic, OpenAI)
- Smart retry based on status codes
- Configurable retry strategies
Index ¶
- func ConfigureTLS(config *TLSConfig) (*http.Transport, error)
- type Client
- type HeaderParser
- type Option
- func WithBaseDelay(delay time.Duration) Option
- func WithHTTPClient(client *http.Client) Option
- func WithHeaderParser(parser HeaderParser) Option
- func WithMaxDelay(delay time.Duration) Option
- func WithMaxRetries(max int) Option
- func WithRetryStrategy(strategyFunc StrategyFunc) Option
- func WithTLSConfig(config *TLSConfig) Option
- type RateLimitInfo
- type RetryStrategy
- type RetryableError
- type StrategyFunc
- type TLSConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps http.Client with retry and backoff capabilities.
type HeaderParser ¶
type HeaderParser func(http.Header) RateLimitInfo
HeaderParser extracts rate limit info from response headers.
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithBaseDelay ¶
WithBaseDelay sets the base delay for exponential backoff.
func WithHTTPClient ¶
WithHTTPClient sets a custom http.Client.
IMPORTANT: Order matters when using with WithTLSConfig:
✅ CORRECT: Call WithHTTPClient FIRST, then WithTLSConfig Example: httpclient.New( httpclient.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}), httpclient.WithTLSConfig(&httpclient.TLSConfig{CACertificate: "/path/to/ca.pem"}), )
❌ WRONG: Calling WithTLSConfig before WithHTTPClient will lose TLS configuration
✅ BEST: For custom transport settings, configure TLS on the transport first: Example: tlsTransport, _ := httpclient.ConfigureTLS(&httpclient.TLSConfig{CACertificate: "/path/to/ca.pem"}) tlsTransport.MaxIdleConns = 100 // Custom settings httpclient.New( httpclient.WithHTTPClient(&http.Client{Transport: tlsTransport, Timeout: 30 * time.Second}), )
func WithHeaderParser ¶
func WithHeaderParser(parser HeaderParser) Option
WithHeaderParser sets a custom rate limit header parser.
func WithMaxDelay ¶
WithMaxDelay sets the maximum delay between retries.
func WithMaxRetries ¶
WithMaxRetries sets the maximum number of retries.
func WithRetryStrategy ¶
func WithRetryStrategy(strategyFunc StrategyFunc) Option
WithRetryStrategy sets a custom retry strategy function.
func WithTLSConfig ¶
WithTLSConfig sets TLS configuration for the HTTP client. This is useful for:
- Corporate networks with custom CA certificates
- Internal services with self-signed certificates
- Development/testing environments (with InsecureSkipVerify)
NOTE: Call WithTLSConfig AFTER WithHTTPClient if both are used. If called before WithHTTPClient, the TLS transport will be overwritten.
type RateLimitInfo ¶
type RateLimitInfo struct {
RetryAfter time.Duration
ResetTime int64
RequestsRemaining int
InputTokensRemaining int
OutputTokensRemaining int
TokensRemaining int
}
RateLimitInfo contains rate limit information from response headers.
func ParseAnthropicHeaders ¶
func ParseAnthropicHeaders(headers http.Header) RateLimitInfo
ParseAnthropicHeaders extracts rate limit info from Anthropic API headers.
func ParseGeminiHeaders ¶
func ParseGeminiHeaders(headers http.Header) RateLimitInfo
ParseGeminiHeaders extracts rate limit info from Google Gemini API headers.
func ParseOpenAIHeaders ¶
func ParseOpenAIHeaders(headers http.Header) RateLimitInfo
ParseOpenAIHeaders extracts rate limit info from OpenAI API headers.
type RetryStrategy ¶
type RetryStrategy int
RetryStrategy defines how to handle retries.
const ( // NoRetry indicates no retry should be attempted. NoRetry RetryStrategy = iota // ConservativeRetry attempts up to 2 retries with fixed delays. ConservativeRetry // SmartRetry uses rate limit headers and exponential backoff. SmartRetry )
func DefaultStrategy ¶
func DefaultStrategy(statusCode int) RetryStrategy
DefaultStrategy returns the default retry strategy for a status code.
type RetryableError ¶
RetryableError represents an error that may be retried.
func (*RetryableError) Error ¶
func (e *RetryableError) Error() string
func (*RetryableError) IsRetryable ¶
func (e *RetryableError) IsRetryable() bool
IsRetryable returns true.
func (*RetryableError) Unwrap ¶
func (e *RetryableError) Unwrap() error
type StrategyFunc ¶
type StrategyFunc func(int) RetryStrategy
StrategyFunc determines the retry strategy based on status code.
type TLSConfig ¶
type TLSConfig struct {
// InsecureSkipVerify disables TLS certificate verification.
// WARNING: Only use for development/testing. Never use in production.
InsecureSkipVerify bool
// CACertificate is the path to a custom CA certificate file.
// Use this for corporate proxies or internal services with custom certificates.
CACertificate string
}
TLSConfig holds TLS configuration options for outbound HTTP requests. This is useful for corporate networks with custom CA certificates or development environments with self-signed certificates.
Source Files