internal

Documentation

Index

• Constants
• func EncodeURL(urlFormat string, args ...interface{}) string
• func ExtractExtraProperties(bytes []byte, value interface{}, exclude ...string) (map[string]interface{}, error)
• func HandleExplicitFields(marshaler interface{}, explicitFields *big.Int) interface{}
• func MarshalJSONWithExtraProperties(marshaler interface{}, extraProperties map[string]interface{}) ([]byte, error)
• func MarshalJSONWithExtraProperty(marshaler interface{}, key string, value interface{}) ([]byte, error)
• func MergeHeaders(left, right http.Header) http.Header
• func QueryValues(v interface{}) (url.Values, error)
• func QueryValuesWithDefaults(v interface{}, defaults map[string]interface{}) (url.Values, error)
• func ResolveBaseURL(values ...string) string
• func StringifyJSON(value interface{}) (string, error)
• type CallParams
• type CallResponse
• type Caller
  • func NewCaller(params *CallerParams) *Caller
  • func (c *Caller) Call(ctx context.Context, params *CallParams) (*CallResponse, error)
• type CallerParams
• type Date
  • func NewDate(t time.Time) *Date
  • func NewOptionalDate(t *time.Time) *Date
  • func (d *Date) MarshalJSON() ([]byte, error)
  • func (d *Date) Time() time.Time
  • func (d *Date) TimePtr() *time.Time
  • func (d *Date) UnmarshalJSON(data []byte) error
• type DateTime
  • func NewDateTime(t time.Time) *DateTime
  • func NewOptionalDateTime(t *time.Time) *DateTime
  • func (d *DateTime) MarshalJSON() ([]byte, error)
  • func (d *DateTime) Time() time.Time
  • func (d *DateTime) TimePtr() *time.Time
  • func (d *DateTime) UnmarshalJSON(data []byte) error
• type ErrorCodes
• type ErrorDecoder
  • func NewErrorDecoder(errorCodes ErrorCodes, errorCodesOverrides ...ErrorCodes) ErrorDecoder
• type HTTPClient
• type QueryEncoder
• type Retrier
  • func NewRetrier(opts ...RetryOption) *Retrier
  • func (r *Retrier) Run(fn RetryFunc, request *http.Request, errorDecoder ErrorDecoder, ...) (*http.Response, error)
• type RetryFunc
• type RetryOption
  • func WithDisableRetries() RetryOption
  • func WithMaxAttempts(attempts uint) RetryOption

Constants

const RFC3339Milli = "2006-01-02T15:04:05.000Z07:00"

RFC3339Milli is a time format string for RFC 3339 with millisecond precision. Go's time.RFC3339 omits fractional seconds and time.RFC3339Nano trims trailing zeros, so neither produces the fixed ".000" millisecond suffix that many APIs expect.

Functions

func EncodeURL

func EncodeURL(urlFormat string, args ...interface{}) string

EncodeURL encodes the given arguments into the URL, escaping values as needed. Pointer arguments are dereferenced before processing.

func ExtractExtraProperties

func ExtractExtraProperties(bytes []byte, value interface{}, exclude ...string) (map[string]interface{}, error)

ExtractExtraProperties extracts any extra properties from the given value.

func HandleExplicitFields

func HandleExplicitFields(marshaler interface{}, explicitFields *big.Int) interface{}

HandleExplicitFields processes a struct to remove `omitempty` from fields that have been explicitly set (as indicated by their corresponding bit in explicitFields). Note that `marshaler` should be an embedded struct to avoid infinite recursion. Returns an interface{} that can be passed to json.Marshal.

func MarshalJSONWithExtraProperties

func MarshalJSONWithExtraProperties(marshaler interface{}, extraProperties map[string]interface{}) ([]byte, error)

MarshalJSONWithExtraProperties marshals the given value to JSON, including any extra properties.

func MarshalJSONWithExtraProperty

func MarshalJSONWithExtraProperty(marshaler interface{}, key string, value interface{}) ([]byte, error)

MarshalJSONWithExtraProperty marshals the given value to JSON, including the extra property.

func MergeHeaders

func MergeHeaders(left, right http.Header) http.Header

MergeHeaders merges the given headers together, where the right takes precedence over the left.

func QueryValues

func QueryValues(v interface{}) (url.Values, error)

QueryValues encodes url.Values from request objects.

Note: This type is inspired by Google's query encoding library, but supports far less customization and is tailored to fit this SDK's use case.

Ref: https://github.com/google/go-querystring

func QueryValuesWithDefaults

func QueryValuesWithDefaults(v interface{}, defaults map[string]interface{}) (url.Values, error)

QueryValuesWithDefaults encodes url.Values from request objects and default values, merging the defaults into the request. It's expected that the values of defaults are wire names.

func ResolveBaseURL

func ResolveBaseURL(values ...string) string

ResolveBaseURL resolves the base URL from the given arguments, preferring the first non-empty value.

func StringifyJSON

func StringifyJSON(value interface{}) (string, error)

StringifyJSON returns a pretty JSON string representation of the given value.

Types

type CallParams

type CallParams struct {
	URL                string
	Method             string
	MaxAttempts        uint
	DisableRetries     bool
	Headers            http.Header
	BodyProperties     map[string]interface{}
	QueryParameters    url.Values
	Client             core.HTTPClient
	Request            interface{}
	Response           interface{}
	ResponseIsOptional bool
	ErrorDecoder       ErrorDecoder
}

CallParams represents the parameters used to issue an API call.

type CallResponse

type CallResponse struct {
	StatusCode int
	Header     http.Header
}

CallResponse is a parsed HTTP response from an API call.

type Caller

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

Caller calls APIs and deserializes their response, if any.

func NewCaller

func NewCaller(params *CallerParams) *Caller

NewCaller returns a new *Caller backed by the given parameters.

func (*Caller) Call

func (c *Caller) Call(ctx context.Context, params *CallParams) (*CallResponse, error)

Call issues an API call according to the given call parameters.

type CallerParams

type CallerParams struct {
	Client         core.HTTPClient
	MaxAttempts    uint
	DisableRetries bool
}

CallerParams represents the parameters used to constrcut a new *Caller.

type Date

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

DateTime wraps time.Time and adapts its JSON representation to conform to a RFC3339 date (e.g. 2006-01-02).

Ref: https://ijmacd.github.io/rfc3339-iso8601

func NewDate

func NewDate(t time.Time) *Date

NewDate returns a new *Date. If the given time.Time is nil, nil will be returned.

func NewOptionalDate

func NewOptionalDate(t *time.Time) *Date

NewOptionalDate returns a new *Date. If the given time.Time is nil, nil will be returned.

func (*Date) MarshalJSON

func (d *Date) MarshalJSON() ([]byte, error)

func (*Date) Time

func (d *Date) Time() time.Time

Time returns the Date's underlying time, if any. If the date is nil, the zero value is returned.

func (*Date) TimePtr

func (d *Date) TimePtr() *time.Time

TimePtr returns a pointer to the Date's underlying time.Time, if any.

func (*Date) UnmarshalJSON

func (d *Date) UnmarshalJSON(data []byte) error

type DateTime

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

DateTime wraps time.Time and adapts its JSON representation to conform to a RFC3339 date-time (e.g. 2017-07-21T17:32:28Z).

Ref: https://ijmacd.github.io/rfc3339-iso8601

func NewDateTime

func NewDateTime(t time.Time) *DateTime

NewDateTime returns a new *DateTime.

func NewOptionalDateTime

func NewOptionalDateTime(t *time.Time) *DateTime

NewOptionalDateTime returns a new *DateTime. If the given time.Time is nil, nil will be returned.

func (*DateTime) MarshalJSON

func (d *DateTime) MarshalJSON() ([]byte, error)

func (*DateTime) Time

func (d *DateTime) Time() time.Time

Time returns the DateTime's underlying time, if any. If the date-time is nil, the zero value is returned.

func (*DateTime) TimePtr

func (d *DateTime) TimePtr() *time.Time

TimePtr returns a pointer to the DateTime's underlying time.Time, if any.

func (*DateTime) UnmarshalJSON

func (d *DateTime) UnmarshalJSON(data []byte) error

type ErrorCodes

type ErrorCodes map[int]func(*core.APIError) error

ErrorCodes maps HTTP status codes to error constructors.

type ErrorDecoder

type ErrorDecoder func(statusCode int, header http.Header, body io.Reader) error

ErrorDecoder decodes *http.Response errors and returns a typed API error (e.g. *core.APIError).

func NewErrorDecoder

func NewErrorDecoder(errorCodes ErrorCodes, errorCodesOverrides ...ErrorCodes) ErrorDecoder

NewErrorDecoder returns a new ErrorDecoder backed by the given error codes. errorCodesOverrides is optional and will be merged with the default error codes, with overrides taking precedence.

type HTTPClient

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

HTTPClient is an interface for a subset of the *http.Client.

type QueryEncoder

type QueryEncoder interface {
	EncodeQueryValues(key string, v *url.Values) error
}

QueryEncoder is an interface implemented by any type that wishes to encode itself into URL values in a non-standard way.

type Retrier

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

Retrier retries failed requests a configurable number of times with an exponential back-off between each retry.

func NewRetrier

func NewRetrier(opts ...RetryOption) *Retrier

NewRetrier constructs a new *Retrier with the given options, if any.

func (*Retrier) Run

func (r *Retrier) Run(
	fn RetryFunc,
	request *http.Request,
	errorDecoder ErrorDecoder,
	opts ...RetryOption,
) (*http.Response, error)

Run issues the request and, upon failure, retries the request if possible.

The request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit.

type RetryFunc

type RetryFunc func(*http.Request) (*http.Response, error)

RetryFunc is a retryable HTTP function call (i.e. *http.Client.Do).

type RetryOption

type RetryOption func(*retryOptions)

RetryOption adapts the behavior the *Retrier.

func WithDisableRetries

func WithDisableRetries() RetryOption

WithDisableRetries disables retry attempts entirely. The request is issued exactly once. Distinct from WithMaxAttempts(0), which falls through to the default.

func WithMaxAttempts

func WithMaxAttempts(attempts uint) RetryOption

WithMaxAttempts configures the maximum number of attempts of the *Retrier.