httpclient

Documentation

Overview

Package httpclient provides base-URL-scoped, context-owned outbound HTTP clients with bounded typed JSON helpers.

Index

• Constants
• type Client
  • func New(options Options) (*Client, error)
  • func (client *Client) BaseURL() string
  • func (client *Client) Do(request *http.Request) (*http.Response, error)
  • func (client *Client) NewRequest(ctx context.Context, method string, reference string, body io.Reader) (*http.Request, error)
• type JSONResponse
  • func DoJSON[Value any](ctx context.Context, client *Client, method string, reference string, ...) (JSONResponse[Value], error)
• type Options
• type ResponseError
  • func (responseErr *ResponseError) Error() string
  • func (responseErr *ResponseError) RemoteProblem() (web.Problem, bool)

Constants

const (
	// DefaultTimeout bounds requests when a caller does not supply an HTTP
	// client.
	DefaultTimeout = 30 * time.Second
	// DefaultMaxResponseBodyBytes bounds typed response and remote error bodies.
	DefaultMaxResponseBodyBytes int64 = 4 << 20
	// MaxResponseBodyBytes is the largest typed response bound accepted by New.
	// Larger payloads should use the raw streaming API.
	MaxResponseBodyBytes int64 = 64 << 20
)

Types

type Client

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

Client is one immutable base-URL-scoped outbound HTTP client.

func New

func New(options Options) (*Client, error)

New validates and copies an outbound client configuration. A nil HTTPClient selects a standard client with DefaultTimeout.

func (*Client) BaseURL

func (client *Client) BaseURL() string

BaseURL returns the canonical configured base URL.

func (*Client) Do

func (client *Client) Do(request *http.Request) (*http.Response, error)

Do sends one raw request and returns a caller-owned response body. The request URL must remain within the configured base URL.

func (*Client) NewRequest

func (client *Client) NewRequest(
	ctx context.Context,
	method string,
	reference string,
	body io.Reader,
) (*http.Request, error)

NewRequest creates a scoped request without sending it. Reference must be relative to the configured base path and contain no dot segments or fragment.

type JSONResponse

type JSONResponse[Value any] struct {
	Status int
	Header http.Header
	Value  Value
}

JSONResponse is one successful typed outbound response.

func DoJSON

func DoJSON[Value any](
	ctx context.Context,
	client *Client,
	method string,
	reference string,
	requestBody any,
) (JSONResponse[Value], error)

DoJSON sends an optional JSON body and decodes one bounded JSON response. Empty and 204 success bodies return the zero Value.

type Options

type Options struct {
	BaseURL                       string
	HTTPClient                    *http.Client
	DefaultHeaders                http.Header
	UserAgent                     string
	MaxResponseBodyBytes          int64
	DisallowUnknownResponseFields bool
}

Options configures one isolated outbound client.

type ResponseError

type ResponseError struct {
	Status int
	// contains filtered or unexported fields
}

ResponseError reports a non-2xx remote response without retaining its raw body or rendering remote details in Error().

func (*ResponseError) Error

func (responseErr *ResponseError) Error() string

Error returns stable status context without remote response detail.

func (*ResponseError) RemoteProblem

func (responseErr *ResponseError) RemoteProblem() (web.Problem, bool)

RemoteProblem returns a validated copy of a remote RFC 9457 response.