Documentation
¶
Overview ¶
Package client provides an HTTP client with retry logic for registry APIs.
Index ¶
- Variables
- func BuildURLs(urls URLBuilder, name, version string) map[string]string
- type BaseURLs
- type Client
- func (c *Client) GetBody(ctx context.Context, url string) ([]byte, error)
- func (c *Client) GetJSON(ctx context.Context, url string, v any) error
- func (c *Client) GetText(ctx context.Context, url string) (string, error)
- func (c *Client) Head(ctx context.Context, url string) (int, error)
- func (c *Client) WithRateLimiter(rl RateLimiter) *Client
- func (c *Client) WithUserAgent(ua string) *Client
- type HTTPError
- type HeldError
- type HoldEvent
- type NotFoundError
- type Option
- type RateLimitError
- type RateLimitGate
- type RateLimiter
- type URLBuilder
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("not found")
ErrNotFound is returned when a package or version is not found.
var ErrUpstreamHeld = errors.New("upstream requests are held by rate limiting")
ErrUpstreamHeld marks a request refused locally during a rate-limit hold.
Functions ¶
Types ¶
type BaseURLs ¶
type BaseURLs struct {
RegistryFn func(name, version string) string
DownloadFn func(name, version string) string
DocumentationFn func(name, version string) string
PURLFn func(name, version string) string
}
BaseURLs provides a default URLBuilder implementation.
func (*BaseURLs) Documentation ¶
type Client ¶
type Client struct {
HTTPClient *http.Client
UserAgent string
MaxRetries int
BaseDelay time.Duration
RateLimiter RateLimiter
}
Client is an HTTP client with retry logic for registry APIs.
func DefaultClient ¶
func DefaultClient() *Client
DefaultClient returns a client with sensible defaults.
func (*Client) WithRateLimiter ¶
func (c *Client) WithRateLimiter(rl RateLimiter) *Client
WithRateLimiter returns a copy of the client with the given rate limiter.
func (*Client) WithUserAgent ¶
WithUserAgent returns a copy of the client with the given user agent.
type HTTPError ¶
HTTPError represents an HTTP error response.
func (*HTTPError) IsNotFound ¶
IsNotFound returns true if the error represents a 404 response.
type HeldError ¶ added in v0.10.0
HeldError is returned in place of a response while a host is held.
type HoldEvent ¶ added in v0.10.0
HoldEvent describes a rate-limit response, including any longer active hold.
type NotFoundError ¶
NotFoundError wraps ErrNotFound with additional context.
func (*NotFoundError) Error ¶
func (e *NotFoundError) Error() string
func (*NotFoundError) Unwrap ¶
func (e *NotFoundError) Unwrap() error
type Option ¶
type Option func(*Client)
Option configures a Client.
func WithHTTPClient ¶
WithHTTPClient swaps in a caller-supplied *http.Client. Use this when the application has its own connection pool, mTLS config, or auth-injecting transport that other Options like WithTimeout can't express. The supplied client's Timeout, Jar, and Transport are preserved as-is.
func WithMaxRetries ¶
WithMaxRetries sets the maximum number of retries.
func WithSafeHTTP ¶
func WithSafeHTTP() Option
WithSafeHTTP wraps the client's underlying *http.Client with the safehttp transport: dial-time IP gate (rejects loopback, RFC1918, CGNAT, link-local, multicast, unspecified), redirect chain capped at 10, non-http(s) schemes rejected on redirect. DNS is resolved at dial time and the connection dials the resolved IP directly so a rebind between resolve and connect cannot escape the gate. Suitable for any code path that fetches from URLs an attacker might control (a malicious registry response, a manifest-supplied URL, a redirect target).
func WithTimeout ¶
WithTimeout sets the HTTP client timeout.
func WithTransport ¶
func WithTransport(rt http.RoundTripper) Option
WithTransport replaces the underlying http.RoundTripper without touching the Client's other settings (timeout, jar, etc.). Useful for wrapping the transport in middleware (auth, logging, retry, rate-limit) while keeping the rest of the configured shape intact.
type RateLimitError ¶
type RateLimitError struct {
RetryAfter int // seconds
}
RateLimitError is returned when the registry rate limits requests.
func (*RateLimitError) Error ¶
func (e *RateLimitError) Error() string
type RateLimitGate ¶ added in v0.10.0
type RateLimitGate struct {
// Set callbacks before use. They run outside the lock and may run concurrently.
OnHold func(HoldEvent)
OnRelease func(host string)
// contains filtered or unexported fields
}
RateLimitGate holds a host after a 429 or a 503 with Retry-After. Limited responses pass through; requests during a hold return HeldError. The first non-limited response after expiry releases the hold.
func NewRateLimitGate ¶ added in v0.10.0
func NewRateLimitGate(base http.RoundTripper) *RateLimitGate
NewRateLimitGate wraps base. A nil base uses http.DefaultTransport.
func (*RateLimitGate) Held ¶ added in v0.10.0
func (g *RateLimitGate) Held(rawURL string) error
Held returns a *HeldError when requests to rawURL's host are being held, and nil otherwise. It is safe to call on a nil gate.
type RateLimiter ¶
RateLimiter controls request pacing.
Source Files