httpcl

package
v0.7.31 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 24, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package httpcl provides a minimal HTTP client with JSON defaults and retries. Inspired by backplane-go/httpcl but stripped to essentials, using hashicorp/go-retryablehttp for retry logic.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Body

func Body(v any) func(*Request)

Body sets a value that will be JSON-encoded as the request body.

func HasStatusCode

func HasStatusCode(err error, codes ...int) bool

HasStatusCode checks if err is an *HTTPError with any of the given status codes.

func Header(key, val string) func(*Request)

Header sets a single request header.

func JSONDecoder

func JSONDecoder(v any) func(*Request)

JSONDecoder decodes a 2xx response body as JSON into v.

func QueryParam

func QueryParam(key, val string) func(*Request)

QueryParam sets a single query parameter.

func RouteParams added in v0.7.29

func RouteParams(params ...any) func(*Request)

RouteParams fills route template placeholders (%s, %d, etc.) with the given values.

Types

type Client

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

Client is a simple HTTP client with JSON defaults and automatic retries.

func New

func New(cfg Config) *Client

New creates a Client from the given config.

func (*Client) Call

func (c *Client) Call(ctx context.Context, r Request) (int, error)

Call executes the request and returns the HTTP status code. Non-2xx responses return an *HTTPError. If a decoder is set and the response is 2xx, the response body is decoded.

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
}

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.

func (*HTTPError) Error

func (e *HTTPError) Error() string

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

func NewRequest(method, route string, opts ...func(*Request)) Request

NewRequest creates a request with functional options.

func (Request) URL added in v0.7.29

func (r Request) URL() string

URL returns the resolved URL (after RouteParams) or the raw route.

type StatusError added in v0.7.31

type StatusError struct {
	Op         string
	StatusCode int
}

StatusError is a structured HTTP error for use by API client packages. It records the operation name and HTTP status code without exposing HTTPError.

func (*StatusError) Error added in v0.7.31

func (e *StatusError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL