Documentation
¶
Overview ¶
Package httpcl provides a minimal HTTP client with JSON defaults and retries. Copied from github.com/CircleCI-Public/chunk-cli/internal/httpcl. TODO: extract to a shared module.
Index ¶
- func Body(v any) func(*Request)
- func BytesDecoder(resp *[]byte) func(*Request)
- func CaptureHeader(h *http.Header) func(*Request)
- func CopyDecoder(w io.Writer) func(*Request)
- func HasStatusCode(err error, codes ...int) bool
- func Header(key, val string) func(*Request)
- func JSONDecoder(v any) func(*Request)
- func JSONLDecoder[T any](fn func(T)) func(*Request)
- func NoTimeout() func(*Request)
- func OptionalQueryParam(key, val string) func(*Request)
- func QueryParam(key, val string) func(*Request)
- func RawBody(body []byte, contentType string) func(*Request)
- func RouteParams(v ...any) func(*Request)
- func StringDecoder(s *string) func(*Request)
- func UserAgent(goos, goarch, version, agent string) string
- type Client
- type Config
- type HTTPError
- type Request
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BytesDecoder ¶
BytesDecoder decodes a 2xx response body as JSON into v.
func CaptureHeader ¶
CaptureHeader stores the response headers into h on a 2xx response, so callers can read values the typed decoders don't expose (e.g. a streaming endpoint's X-Terminal marker).
func CopyDecoder ¶
func HasStatusCode ¶
HasStatusCode checks if err is an *HTTPError with any of the given status codes.
func JSONDecoder ¶
JSONDecoder decodes a 2xx response body as JSON into v.
func JSONLDecoder ¶
JSONLDecoder decodes a 2xx response body as newline-delimited JSON (JSONL), invoking fn once per decoded record as it is read off the wire so callers can consume records as a stream rather than buffering them. Blank lines and surrounding whitespace between records are tolerated. Decoding runs to EOF; a malformed record returns the decode error.
func NoTimeout ¶ added in v1.5.0
func NoTimeout() func(*Request)
NoTimeout exempts the request from the client's overall timeout, which bounds the whole request including reading the body. Use it for downloads, which take as long as the connection needs; the caller's context still cancels them.
func OptionalQueryParam ¶
func QueryParam ¶
QueryParam sets a single query parameter.
func RawBody ¶
RawBody sets a pre-encoded request body sent verbatim with the given Content-Type, bypassing JSON marshaling (e.g. multipart/form-data uploads). Takes precedence over Body.
func RouteParams ¶
func StringDecoder ¶
StringDecoder decodes a 2xx response body as JSON into v.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a simple HTTP client with JSON defaults and automatic retries.
type Config ¶
type Config struct {
// BaseURL is prepended to every request route.
BaseURL string
// AuthToken is sent as a Bearer token unless AuthHeader is set.
AuthToken string
// AuthHeader overrides the header name for AuthToken (e.g. "Circle-Token", "x-api-key").
// When set, the token is sent as the raw header value (not "Bearer ...").
AuthHeader string
// UserAgent sets the User-Agent header on every request.
UserAgent string
// Timeout is the per-request timeout. Defaults to 30s.
Timeout time.Duration
// DisableRetries disables automatic retries. By default requests are
// retried up to 3 times with exponential backoff.
DisableRetries bool
// Transport overrides the HTTP transport (useful for testing).
Transport http.RoundTripper
// OnWarn, when non-nil, is called with a plain-text warning message when the
// server signals endpoint removal via Deprecation or Sunset response headers.
// The caller controls formatting (prefix, newline, colour).
OnWarn func(msg string)
}
Config configures a Client.
type HTTPError ¶
type HTTPError struct {
Method string
Route string
StatusCode int
Body []byte // raw response body
}
HTTPError represents a non-2xx HTTP response.
type Request ¶
type Request struct {
// contains filtered or unexported fields
}
Request is an individual HTTP request to be executed by Client.Call. Use NewRequest to create one.
func NewRequest ¶
NewRequest creates a request with functional options.
Source Files