httpc

type AppConfig struct {
	// Timeout is the HTTP request timeout as a duration string (e.g. "30s").
	Timeout string `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	// RetryMax is the maximum number of retries.
	RetryMax int `json:"retryMax,omitempty" yaml:"retryMax,omitempty"`
	// RetryWaitMin is the minimum wait time between retries as a duration string.
	RetryWaitMin string `json:"retryWaitMin,omitempty" yaml:"retryWaitMin,omitempty"`
	// RetryWaitMax is the maximum wait time between retries as a duration string.
	RetryWaitMax string `json:"retryWaitMax,omitempty" yaml:"retryWaitMax,omitempty"`
	// EnableCache enables HTTP response caching.
	EnableCache *bool `json:"enableCache,omitempty" yaml:"enableCache,omitempty"`
	// CacheType is the cache type: "memory" or "filesystem".
	CacheType string `json:"cacheType,omitempty" yaml:"cacheType,omitempty"`
	// CacheDir is the directory for filesystem cache.
	CacheDir string `json:"cacheDir,omitempty" yaml:"cacheDir,omitempty"`
	// CacheTTL is the time-to-live for cached responses as a duration string.
	CacheTTL string `json:"cacheTTL,omitempty" yaml:"cacheTTL,omitempty"`
	// CacheKeyPrefix is the prefix for cache keys.
	CacheKeyPrefix string `json:"cacheKeyPrefix,omitempty" yaml:"cacheKeyPrefix,omitempty"`
	// MaxCacheFileSize is the maximum size for a single cached file in bytes.
	MaxCacheFileSize int64 `json:"maxCacheFileSize,omitempty" yaml:"maxCacheFileSize,omitempty"`
	// MemoryCacheSize is the maximum number of entries in memory cache.
	MemoryCacheSize int `json:"memoryCacheSize,omitempty" yaml:"memoryCacheSize,omitempty"`
	// EnableCircuitBreaker enables the circuit breaker pattern.
	EnableCircuitBreaker *bool `json:"enableCircuitBreaker,omitempty" yaml:"enableCircuitBreaker,omitempty"`
	// CircuitBreakerMaxFailures is the number of failures before opening the circuit.
	CircuitBreakerMaxFailures int `json:"circuitBreakerMaxFailures,omitempty" yaml:"circuitBreakerMaxFailures,omitempty"`
	// CircuitBreakerOpenTimeout is the wait time before half-open state as a duration string.
	CircuitBreakerOpenTimeout string `json:"circuitBreakerOpenTimeout,omitempty" yaml:"circuitBreakerOpenTimeout,omitempty"`
	// CircuitBreakerHalfOpenMaxRequests is the number of successful requests in half-open before closing.
	CircuitBreakerHalfOpenMaxRequests int `json:"circuitBreakerHalfOpenMaxRequests,omitempty" yaml:"circuitBreakerHalfOpenMaxRequests,omitempty"`
	// EnableCompression enables automatic gzip compression.
	EnableCompression *bool `json:"enableCompression,omitempty" yaml:"enableCompression,omitempty"`
	// AllowPrivateIPs allows HTTP requests to private/loopback/link-local IP literals.
	AllowPrivateIPs *bool `json:"allowPrivateIPs,omitempty" yaml:"allowPrivateIPs,omitempty"`
	// MaxResponseBodySize is the maximum HTTP response body size in bytes.
	MaxResponseBodySize int64 `json:"maxResponseBodySize,omitempty" yaml:"maxResponseBodySize,omitempty"`
}

type CacheStats struct {
	Hits    uint64
	Misses  uint64
	HitRate float64 // Computed as Hits / (Hits + Misses)
}

type CacheType string

type CircuitBreakerConfig struct {
	// MaxFailures is the number of consecutive failures before opening the circuit
	MaxFailures int
	// OpenTimeout is how long to wait before transitioning from Open to HalfOpen
	OpenTimeout time.Duration
	// HalfOpenMaxRequests is the number of successful requests in HalfOpen before closing
	HalfOpenMaxRequests int
}

type CircuitBreakerState int

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

type ClientConfig struct {
	// Timeout is the maximum time to wait for a request to complete
	Timeout time.Duration
	// RetryMax is the maximum number of retries
	RetryMax int
	// RetryWaitMin is the minimum time to wait between retries
	RetryWaitMin time.Duration
	// RetryWaitMax is the maximum time to wait between retries
	RetryWaitMax time.Duration
	// EnableCache enables HTTP caching
	EnableCache bool
	// CacheType specifies the type of cache to use (memory or filesystem)
	CacheType CacheType
	// CacheDir is the directory to use for filesystem cache (only used when CacheType is filesystem)
	CacheDir string
	// CacheTTL is the time-to-live for cached responses
	CacheTTL time.Duration
	// CacheKeyPrefix is a prefix added to all cache keys to prevent collisions
	CacheKeyPrefix string
	// MaxCacheFileSize is the maximum size in bytes for a single cached file (0 = no limit)
	// Only applies to filesystem cache
	MaxCacheFileSize int64
	// MemoryCacheSize is the maximum number of entries in the memory cache (default: 1000)
	MemoryCacheSize int
	// Logger is the logger to use for the client
	Logger logr.Logger
	// CheckRetry is a custom retry policy function
	CheckRetry retryablehttp.CheckRetry
	// Backoff is a custom backoff policy function
	Backoff retryablehttp.Backoff
	// ErrorHandler is called if retries are exhausted
	ErrorHandler retryablehttp.ErrorHandler
	// RequestHooks are functions called before each request
	RequestHooks []RequestHook
	// ResponseHooks are functions called after each response
	ResponseHooks []ResponseHook
	// OnUnauthorized is called when a 401 Unauthorized response is received.
	// Return the new full Authorization header value (e.g. "Bearer <new-token>") to
	// inject a single transparent retry with the refreshed token.
	// Return an empty string (or an error) to pass the 401 response through as-is.
	OnUnauthorized func(ctx context.Context) (authorizationHeader string, err error)
	// EnableCircuitBreaker enables circuit breaker pattern
	EnableCircuitBreaker bool
	// CircuitBreakerConfig holds circuit breaker configuration
	CircuitBreakerConfig *CircuitBreakerConfig
	// EnableCompression enables automatic gzip compression for requests/responses
	EnableCompression bool
	// Metrics is the metrics collector for the HTTP client.
	// Defaults to NoopMetrics{} if not set.
	Metrics Metrics
	// AllowPrivateIPs allows HTTP requests to private/loopback/link-local IP literals.
	// Defaults to false (deny), enforcing secure-by-default behaviour.
	AllowPrivateIPs bool
	// MaxRedirects is the maximum number of HTTP redirects to follow.
	// Defaults to DefaultMaxRedirects (10).
	MaxRedirects int
	// MaxResponseBodySize is the maximum HTTP response body size in bytes.
	// Defaults to DefaultMaxResponseBodySize (100 MB).
	MaxResponseBodySize int64
}

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

type FileCacheConfig struct {
	// Dir is the directory to use for cache storage
	Dir string
	// TTL is the time-to-live for cached entries
	TTL time.Duration
	// KeyPrefix is a prefix added to all cache keys to prevent collisions
	KeyPrefix string
	// MaxSize is the maximum size in bytes for a single cached file (0 = no limit)
	MaxSize int64
	// FileIOTimeout is the best-effort maximum time for file I/O operations (default: 5s).
	// Context is checked before and after I/O syscalls, but cannot interrupt them mid-call.
	FileIOTimeout time.Duration
	// Logger is used for logging cache operations
	Logger logr.Logger
	// Metrics is the metrics collector for cache operations
	Metrics Metrics
}

type Metrics interface {
	// RecordRequestDuration records the duration of an HTTP request.
	RecordRequestDuration(ctx context.Context, method, host, pathTemplate string, statusCode int, duration time.Duration)

	// IncrementRequestsTotal increments the total request counter.
	IncrementRequestsTotal(ctx context.Context, method, host, pathTemplate string, statusCode int)

	// IncrementErrorsTotal increments the error counter with the given error type.
	IncrementErrorsTotal(ctx context.Context, method, host, pathTemplate, errorType string)

	// IncrementRetries increments the retry counter.
	IncrementRetries(ctx context.Context, method, host, pathTemplate string)

	// IncrementCacheHits increments the cache hit counter.
	IncrementCacheHits(ctx context.Context)

	// IncrementCacheMisses increments the cache miss counter.
	IncrementCacheMisses(ctx context.Context)

	// SetCacheSizeBytes reports the total cache size in bytes.
	SetCacheSizeBytes(bytes int64)

	// SetCircuitBreakerState reports the circuit breaker state for a host.
	// State values: 0=closed, 1=open, 2=half-open.
	SetCircuitBreakerState(host string, state float64)

	// IncrementConcurrentRequests increments the in-flight request counter.
	IncrementConcurrentRequests(ctx context.Context)

	// DecrementConcurrentRequests decrements the in-flight request counter.
	DecrementConcurrentRequests(ctx context.Context)

	// RecordRequestSize records the size of an HTTP request body in bytes.
	RecordRequestSize(ctx context.Context, method, host, pathTemplate string, bytes float64)

	// RecordResponseSize records the size of an HTTP response body in bytes.
	RecordResponseSize(ctx context.Context, method, host, pathTemplate string, bytes float64)
}

type NoopMetrics struct{}

type RequestHook func(*http.Request) error

type ResponseHook func(*http.Response) error