httpclientx

Documentation

Overview

Package httpclientx contains extensions to more easily invoke HTTP APIs.

Index

• Constants
• Variables
• func GetJSON[Output any](ctx context.Context, epnt *Endpoint, config *Config) (Output, error)
• func GetRaw(ctx context.Context, epnt *Endpoint, config *Config) ([]byte, error)
• func GetXML[Output any](ctx context.Context, epnt *Endpoint, config *Config) (Output, error)
• func NilSafetyAvoidNilBytesSlice(input []byte) []byte
• func NilSafetyErrorIfNil[Type any](value Type) (Type, error)
• func OverlappedIgnoreIndex[Output any](value Output, _ int, err error) (Output, error)
• func OverlappedReduce[Output any](results []*OverlappedErrorOr[Output]) (Output, int, error)
• func PostJSON[Input, Output any](ctx context.Context, epnt *Endpoint, input Input, config *Config) (Output, error)
• type Config
• type Endpoint
  • func NewEndpoint(URL string) *Endpoint
  • func NewEndpointFromModelOOAPIServices(svcs ...model.OOAPIService) (epnts []*Endpoint)
  • func (e *Endpoint) WithHostOverride(host string) *Endpoint
• type ErrRequestFailed
  • func (err *ErrRequestFailed) Error() string
• type Overlapped
  • func NewOverlappedGetJSON[Output any](config *Config) *Overlapped[Output]
  • func NewOverlappedGetRaw(config *Config) *Overlapped[[]byte]
  • func NewOverlappedGetXML[Output any](config *Config) *Overlapped[Output]
  • func NewOverlappedPostJSON[Input, Output any](input Input, config *Config) *Overlapped[Output]
  • func (ovx *Overlapped[Output]) Map(ctx context.Context, epnts ...*Endpoint) []*OverlappedErrorOr[Output]
  • func (ovx *Overlapped[Output]) Run(ctx context.Context, epnts ...*Endpoint) (Output, int, error)
• type OverlappedErrorOr

Constants

const DefaultMaxResponseBodySize = 1 << 24

DefaultMaxResponseBodySize is the default maximum response body size.

const OverlappedDefaultScheduleInterval = 15 * time.Second

OverlappedDefaultScheduleInterval is the default schedule interval. After this interval has elapsed for a URL without seeing a success, we will schedule the next URL.

const OverlappedDefaultWatchdogTimeout = 5 * time.Minute

OverlappedDefaultWatchdogTimeout is the timeout after which we assume all the API calls have gone rogue and forcibly interrupt all of them.

Variables

var ErrGenericOverlappedFailure = errors.New("overlapped: generic failure")

ErrGenericOverlappedFailure indicates that a generic *Overlapped failure occurred.

var ErrIsNil = errors.New("nil map, pointer, or slice")

ErrIsNil indicates that NilSafetyErrorIfNil was passed a nil value.

var ErrTruncated = errors.New("httpapi: truncated response body")

ErrTruncated indicates we truncated the response body.

Note: we SHOULD NOT change the error string because this error string was previously used by the httpapi package and it's better to keep the same strings.

Functions

func GetJSON

func GetJSON[Output any](ctx context.Context, epnt *Endpoint, config *Config) (Output, error)

GetJSON sends a GET request and reads a JSON response.

Arguments:

- ctx is the cancellable context;

- epnt is the HTTP *Endpoint to use;

- config contains the config.

This function either returns an error or a valid Output.

func GetRaw

func GetRaw(ctx context.Context, epnt *Endpoint, config *Config) ([]byte, error)

GetRaw sends a GET request and reads a raw response.

Arguments:

- ctx is the cancellable context;

- epnt is the HTTP *Endpoint to use;

- config is the config to use.

This function either returns an error or a valid Output.

func GetXML

func GetXML[Output any](ctx context.Context, epnt *Endpoint, config *Config) (Output, error)

GetXML sends a GET request and reads an XML response.

Arguments:

- ctx is the cancellable context;

- epnt is the HTTP *Endpoint to use;

- config is the config to use.

This function either returns an error or a valid Output.

func NilSafetyAvoidNilBytesSlice

func NilSafetyAvoidNilBytesSlice(input []byte) []byte

NilSafetyAvoidNilBytesSlice replaces a nil bytes slice with an empty slice.

func NilSafetyErrorIfNil

func NilSafetyErrorIfNil[Type any](value Type) (Type, error)

NilSafetyErrorIfNil returns ErrIsNil iff input is a nil map, struct, or slice.

This mechanism prevents us from mistakenly sending to a server a literal JSON "null" and protects us from attempting to process a literal JSON "null" from a server.

func OverlappedIgnoreIndex

func OverlappedIgnoreIndex[Output any](value Output, _ int, err error) (Output, error)

OverlappedIgnoreIndex is a filter that removes the index from *Overlapped.Run results.

func OverlappedReduce

func OverlappedReduce[Output any](results []*OverlappedErrorOr[Output]) (Output, int, error)

OverlappedReduce takes the results of *Overlapped.Map and returns either an Output or an error.

Note that you SHOULD use *Overlapped.Run unless you want to observe the result of each operation, which is mostly useful when running unit tests.

The return value is (output, index, nil) on success and (zero, zero, error) on failure.

func PostJSON

func PostJSON[Input, Output any](ctx context.Context, epnt *Endpoint, input Input, config *Config) (Output, error)

PostJSON sends a POST request with a JSON body and reads a JSON response.

Arguments:

- ctx is the cancellable context;

- epnt is the HTTP *Endpoint to use;

- input is the input structure to JSON serialize as the request body;

- config is the config to use.

This function either returns an error or a valid Output.

Types

type Config

type Config struct {
	// Authorization contains the OPTIONAL Authorization header value to use.
	Authorization string

	// Client is the MANDATORY [model.HTTPClient] to use.
	Client model.HTTPClient

	// Logger is the MANDATORY [model.Logger] to use.
	Logger model.Logger

	// MaxResponseBodySize OPTIONALLY limits the maximum body size. If not set, we
	// use the [DefaultMaxResponseBodySize] value.
	MaxResponseBodySize int64

	// UserAgent is the MANDATORY User-Agent header value to use.
	UserAgent string
}

Config contains configuration shared by GetJSON, GetXML, GetRaw, and PostJSON.

The zero value is invalid; initialize the MANDATORY fields.

type Endpoint

type Endpoint struct {
	// URL is the MANDATORY endpoint URL.
	URL string

	// Host is the OPTIONAL host header to use for cloudfronting.
	Host string
}

Endpoint is an HTTP endpoint.

The zero value is invalid; construct using NewEndpoint.

func NewEndpoint

func NewEndpoint(URL string) *Endpoint

NewEndpoint constructs a new *Endpoint instance using the given URL.

func NewEndpointFromModelOOAPIServices

func NewEndpointFromModelOOAPIServices(svcs ...model.OOAPIService) (epnts []*Endpoint)

NewEndpointFromModelOOAPIServices constructs new *Endpoint instances from the given model.OOAPIService instances, assigning the host header if "cloudfront", and skipping all the entries that are neither "https" not "cloudfront".

func (*Endpoint) WithHostOverride

func (e *Endpoint) WithHostOverride(host string) *Endpoint

WithHostOverride returns a copy of the *Endpoint using the given host header override.

type ErrRequestFailed

type ErrRequestFailed struct {
	StatusCode int
}

ErrRequestFailed indicates that an HTTP request status indicates failure.

func (*ErrRequestFailed) Error

func (err *ErrRequestFailed) Error() string

Error returns the error as a string.

The string returned by this error starts with the httpx prefix for backwards compatibility with the legacy httpx package.

type Overlapped

type Overlapped[Output any] struct {
	// RunFunc is the MANDATORY function that fetches the given [*Endpoint].
	//
	// This field is typically initialized by [NewOverlappedGetJSON], [NewOverlappedGetRaw],
	// [NewOverlappedGetXML], or [NewOverlappedPostJSON] to be the proper function that
	// makes sense for the operation that you requested with the constructor.
	//
	// If you set it manually, you MUST modify it before calling [*Overlapped.Run].
	RunFunc func(ctx context.Context, epnt *Endpoint) (Output, error)

	// ScheduleInterval is the MANDATORY scheduling interval.
	//
	// This field is typically initialized by [NewOverlappedGetJSON], [NewOverlappedGetRaw],
	// [NewOverlappedGetXML], or [NewOverlappedPostJSON] to be [OverlappedDefaultScheduleInterval].
	//
	// If you set it manually, you MUST modify it before calling [*Overlapped.Run].
	ScheduleInterval time.Duration

	// WatchdogTimeout is the MANDATORY timeout after which the code assumes
	// that all API calls must be aborted and give up.
	//
	// This field is typically initialized by [NewOverlappedGetJSON], [NewOverlappedGetRaw],
	// [NewOverlappedGetXML], or [NewOverlappedPostJSON] to be [OverlappedDefaultWatchdogTimeout].
	//
	// If you set it manually, you MUST modify it before calling [*Overlapped.Run].
	WatchdogTimeout time.Duration
}

Overlapped represents the possibility of overlapping HTTP calls for a set of functionally equivalent URLs, such that we start a new call if the previous one has failed to produce a result within the configured ScheduleInterval.

Limitations

Under very bad networking conditions, *Overlapped would cause a new network call to start while the previous one is still in progress and very slowly downloading a response. A future implementation MIGHT want to account for this possibility.

func NewOverlappedGetJSON

func NewOverlappedGetJSON[Output any](config *Config) *Overlapped[Output]

NewOverlappedGetJSON constructs a *Overlapped for calling GetJSON with multiple URLs.

func NewOverlappedGetRaw

func NewOverlappedGetRaw(config *Config) *Overlapped[[]byte]

NewOverlappedGetRaw constructs a *Overlapped for calling GetRaw with multiple URLs.

func NewOverlappedGetXML

func NewOverlappedGetXML[Output any](config *Config) *Overlapped[Output]

NewOverlappedGetXML constructs a *Overlapped for calling GetXML with multiple URLs.

func NewOverlappedPostJSON

func NewOverlappedPostJSON[Input, Output any](input Input, config *Config) *Overlapped[Output]

NewOverlappedPostJSON constructs a *Overlapped for calling PostJSON with multiple URLs.

func (*Overlapped[Output]) Map

func (ovx *Overlapped[Output]) Map(ctx context.Context, epnts ...*Endpoint) []*OverlappedErrorOr[Output]

Map applies the [*Overlapped.RunFunc] function to each epnts entry, thus producing a result for each entry. This function will cancel subsequent operations until there is a success: subsequent results will be context.Canceled errors.

Note that you SHOULD use *Overlapped.Run unless you want to observe the result of each operation, which is mostly useful when running unit tests.

Note that this function will return a zero length slice if epnts lenth is also zero.

func (*Overlapped[Output]) Run

func (ovx *Overlapped[Output]) Run(ctx context.Context, epnts ...*Endpoint) (Output, int, error)

Run runs the overlapped operations, returning the result of the first operation that succeeds and its endpoint index, or the error that occurred.

type OverlappedErrorOr

type OverlappedErrorOr[Output any] struct {
	// Err is the error or nil.
	Err error

	// Index is the endpoint index.
	Index int

	// Value is the result.
	Value Output
}

OverlappedErrorOr combines error information, result information and the endpoint index.