bhttp

type BHTTP interface {
	// Client returns the underlying *http.Client used by this instance.
	// Callers may use it to customize transport/timeouts or to perform advanced requests directly.
	Client() *http.Client

	// Do execute the HTTP request using default behavior.
	//
	// Defaults:
	//   - ExpectedStatusCodes: []int{http.StatusOK}
	//   - Retry: disabled (no retries)
	//   - RateLimiter: none
	//
	// Returns an error if the request fails or the response status code is not expected.
	Do(req *http.Request) error

	// DoWithOptions executes the HTTP request with the provided options.
	//
	// It validates the response status code against opts.ExpectedStatusCodes (default 200).
	// If opts.Retry is configured, it will retry when the response status code matches
	// opts.Retry.RetryStatusCodes, up to 1+opts.Retry.Attempts total tries.
	//
	// Returns an error if the request fails, retries are exhausted, or the final response status
	// code is not expected.
	DoWithOptions(req *http.Request, opts *Options) error

	// DoAndUnwrap executes the request using default behavior and unmarshal the JSON response body
	// into dest.
	//
	// Requirements:
	//   - dest must be a non-nil pointer.
	//
	// Defaults:
	//   - ExpectedStatusCodes: []int{http.StatusOK}
	//   - Retry: disabled (no retries)
	//   - RateLimiter: none
	//
	// Returns an error if the request fails, the response status code is not expected, or the
	// response body cannot be unmarshaled into dest.
	DoAndUnwrap(req *http.Request, dest any) error

	// DoAndUnwrapWithOptions executes the request with the provided options and unmarshal the JSON
	// response body into dest.
	//
	// Requirements:
	//   - dest must be a non-nil pointer.
	//
	// Behavior:
	//   - status code validation uses opts.ExpectedStatusCodes (default 200)
	//   - retry behavior uses opts.Retry.RetryStatusCodes and opts.Retry.Attempts (if provided)
	//   - rate limiting uses opts.RateLimiter (if provided)
	//
	// Returns an error if the request fails, retries are exhausted, the final response status
	// code is not expected, or the response body cannot be unmarshalled into dest.
	DoAndUnwrapWithOptions(req *http.Request, dest any, opts *Options) error
}

type Options struct {
	// ExpectedStatusCodes defines which HTTP status codes are considered successful.
	// If empty/nil, defaults to []int{http.StatusOK}.
	ExpectedStatusCodes []int

	// Retry configures retry behavior based on response status codes.
	// If nil, it is treated as &RetryConfig{} (no retries by default).
	Retry *RetryConfig

	// RateLimiter, if set, will wait before EACH attempt (including retries) using req.Context().
	// This is useful to cap outgoing QPS across calls.
	// If nil, no rate limiting is applied.
	RateLimiter *rate.Limiter
}

type RetryConfig struct {
	// Attempts is the number of retries AFTER the first attempt.
	// Total tries = 1 + Attempts.
	//
	// Example:
	//   Attempts = 0 => 1 try total (no retries)
	//   Attempts = 2 => up to 3 tries total
	Attempts int

	// RetryStatusCodes lists HTTP status codes that should trigger a retry.
	// Only response-status-based retries are supported by your current code
	// (network errors are returned immediately and are not retried).
	//
	// Example common retry codes: 429, 500, 502, 503, 504.
	RetryStatusCodes []int
}