Documentation
¶
Overview ¶
Package httpclient provides an HTTP client with auth, retry, and pagination support.
Package httpclient provides an HTTP client with authentication, retry with exponential backoff, response pagination, and configurable redirect handling.
The client is built for a caller that drives every knob from the outside, which is why it is not a wrapper over azdext.ResilientClient: that type fixes its options at construction and cannot carry per-request headers, a TLS opt out, a redirect policy, a response size limit, or an explicit auth scope.
Pagination is likewise its own implementation rather than azdext.Pager, because Pager reads only nextLink. This package also follows Microsoft Graph's @odata.nextLink and the RFC 5988 Link header, and it merges the sibling fields of the first page into the combined result.
Requests are retried on network errors and on 408, 429, 500, 502, 503, and 504. A Retry-After header, in either its second or millisecond form, overrides the computed backoff, and the backoff itself is jittered so that clients throttled by one service do not retry in lockstep.
Redirect targets are chosen by the server rather than the caller, so they are validated with azdext.SSRFSafeRedirect on top of the caller's own follow and hop-count policy.
Index ¶
- Constants
- Variables
- func DetectContentType(body []byte, contentType string) bool
- func IsJSON(data []byte) bool
- func RedactSensitiveHeader(key, value string) string
- func RedactToken(token string) string
- func RedactURL(rawURL string) string
- func ShouldSkipAuth(url string, headers map[string]string, skipAuth bool) bool
- type Client
- type Formatter
- type MockTokenProvider
- type OutputFormat
- type RequestOptions
- type Response
- type TokenProvider
Constants ¶
const ( // DefaultMaxRedirects is the maximum number of HTTP redirects to follow. DefaultMaxRedirects = 10 // DefaultMaxRetries is the default number of retry attempts for failed requests. DefaultMaxRetries = 3 // DefaultMaxResponseSize is the maximum response body size in bytes (100 MB). DefaultMaxResponseSize = 100 * 1024 * 1024 // MaxBodySizeForRetry is the maximum request body size that will be buffered // in memory for retry attempts (10 MB). MaxBodySizeForRetry = 10 * 1024 * 1024 // DefaultMaxPaginationPages is the maximum number of pages to follow during pagination. DefaultMaxPaginationPages = 1000 // BinaryDetectionBytes is the number of leading bytes inspected when detecting binary content. BinaryDetectionBytes = 512 // MaxRetryAfterDuration caps how long a Retry-After header can delay a retry. // Without a cap, a misconfigured or hostile server could stall the client // indefinitely by returning 503 with Retry-After: 86400. MaxRetryAfterDuration = 120 * time.Second // MaxDrainBytes bounds how much of a retryable response body is read and // discarded before the next attempt. Draining lets the connection be reused; // the bound stops a large body from stalling the retry. MaxDrainBytes = 1 << 20 // 1 MiB // MaxRetryBackoff caps the computed exponential backoff delay. MaxRetryBackoff = 30 * time.Second )
const DefaultMaxPages = 1000
DefaultMaxPages is the default maximum number of pages to fetch during pagination.
const DefaultMaxPaginationSize int64 = 1 * 1024 * 1024 * 1024
DefaultMaxPaginationSize is the default aggregate size limit for all paginated responses (1GB). This prevents unbounded memory growth when APIs return many pages.
Variables ¶
var ErrPaginationPageLimitExceeded = fmt.Errorf("pagination page count limit exceeded")
ErrPaginationPageLimitExceeded is returned when the number of pages fetched exceeds the maximum page count.
var ErrPaginationSizeLimitExceeded = fmt.Errorf("pagination aggregate size limit exceeded")
ErrPaginationSizeLimitExceeded is returned when paginated responses exceed the aggregate size limit.
var UserAgent = ""
UserAgent is the default User-Agent header value. It can be overridden by the caller.
var Version = "0.0.0-dev"
Version is the version string used in the User-Agent header. It can be overridden at build time or by the caller.
Functions ¶
func DetectContentType ¶
DetectContentType attempts to determine if content is binary
func RedactSensitiveHeader ¶
RedactSensitiveHeader redacts sensitive header values
func RedactToken ¶
RedactToken redacts sensitive parts of an authorization token
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps HTTP client functionality
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter handles response formatting and output
func NewFormatter ¶
NewFormatter creates a new formatter
func (*Formatter) WriteOutput ¶
WriteOutput writes the formatted output to the appropriate destination
type MockTokenProvider ¶
MockTokenProvider is a mock implementation of TokenProvider for testing.
type OutputFormat ¶
type OutputFormat string
OutputFormat represents the output format type
const ( FormatAuto OutputFormat = "auto" FormatJSON OutputFormat = "json" FormatRaw OutputFormat = "raw" )
Output format values.
type RequestOptions ¶
type RequestOptions struct {
Method string
URL string
Body io.Reader
Headers map[string]string
Scope string
SkipAuth bool
Verbose bool
Timeout time.Duration
Insecure bool
FollowRedirects bool
MaxRedirects int
OutputFile string
Format string
TokenProvider TokenProvider
Binary bool
Retry int
MaxResponseSize int64
Paginate bool
// MaxPaginationSize is the maximum aggregate size in bytes for all paginated
// responses combined. Defaults to 1GB if unset or zero.
MaxPaginationSize int64
// MaxPages is the maximum number of pages to fetch during pagination.
// Defaults to 1000 if unset or zero.
MaxPages int
}
RequestOptions contains options for HTTP requests
Source Files