internal

Documentation

Index

• Constants
• func SetErrorSource(head *http.Header, es ErrorSource)
• type CooldownFactory
  • func AsFastAsPossible() CooldownFactory
  • func Exponential(interval time.Duration, base int) CooldownFactory
  • func Fixed(delay time.Duration) CooldownFactory
  • func Max(limit int, factory CooldownFactory) CooldownFactory
• type CooldownFunc
• type Error
  • func (e Error) Error() string
• type ErrorSource
  • func GetErrorSource(head http.Header) ErrorSource
  • func NewErrorSource(es string) ErrorSource
  • func (e ErrorSource) String() string
• type Retrier
  • func (r Retrier) Do(ctx context.Context, run func() error) error
• type TemporaryError
• type ValidationError
  • func (v ValidationError) Error() string
  • func (v ValidationError) IsEmpty() bool
• type WireserverPluginQuery
  • func (w WireserverPluginQuery) String() string
• type WireserverResponse
  • func (w WireserverResponse) StatusCode() (int, error)
• type WireserverTransport
  • func (w *WireserverTransport) RoundTrip(inReq *http.Request) (*http.Response, error)

Examples

• Exponential
• Fixed
• Max

Constants

const (
	MimeJSON        = "application/json"
	MimeOctetStream = "application/octet-stream"
)

const (
	WirePluginPath string = "/machine/plugins"

	// DefaultBufferSize is the maximum number of bytes read from Wireserver in
	// the event that no Content-Length is provided. The responses are relatively
	// small, so the smallest page size should be sufficient
	DefaultBufferSize int64 = 4 * kilobyte

	// errors
	ErrNoStatusCode = Error("no httpStatusCode property returned in Wireserver response")
)

const (
	ErrMaxAttempts = Error("maximum attempts reached")
)

const (
	HeaderContentType = "Content-Type"
)

const (
	HeaderErrorSource = "X-Error-Source"
)

Functions

func SetErrorSource

func SetErrorSource(head *http.Header, es ErrorSource)

SetErrorSource sets the header value necessary for communicating the error source.

Types

type CooldownFactory

type CooldownFactory func() CooldownFunc

CooldownFactory is a function that returns CooldownFuncs. It helps CooldownFuncs dispose of any accumulated state so that they function correctly upon successive uses.

func AsFastAsPossible

func AsFastAsPossible() CooldownFactory

AsFastAsPossible is a Cooldown strategy that does not block, allowing retry logic to proceed as fast as possible. This is particularly useful in tests.

func Exponential

func Exponential(interval time.Duration, base int) CooldownFactory

Exponential provides an exponential increase the the base interval provided.

Example

// this example details the common case where the powers of 2 are desired
cooldown := Exponential(1*time.Millisecond, 2)()

for i := 0; i < 5; i++ {
	got, err := cooldown()
	if err != nil {
		fmt.Println("received error during cooldown: err:", err)
		return
	}

	fmt.Println(got)
}

Output:

1ms
2ms
4ms
8ms
16ms

func Fixed

func Fixed(delay time.Duration) CooldownFactory

Fixed produced the same delay value upon each invocation.

Example

cooldown := Fixed(10 * time.Millisecond)()

for i := 0; i < 5; i++ {
	got, err := cooldown()
	if err != nil {
		fmt.Println("unexpected error cooling down: err", err)
		return
	}
	fmt.Println(got)

	

Output:

10ms
10ms
10ms
10ms
10ms

func Max

func Max(limit int, factory CooldownFactory) CooldownFactory

Max provides a fixed limit for the number of times a subordinate cooldown function can be invoked.

Example

cooldown := Max(4, Fixed(10*time.Millisecond))()

for i := 0; i < 5; i++ {
	got, err := cooldown()
	if err != nil {
		fmt.Println("error cooling down:", err)
		break
	}
	fmt.Println(got)

	

Output:

10ms
10ms
10ms
10ms
error cooling down: maximum attempts reached

type CooldownFunc

type CooldownFunc func() (time.Duration, error)

CooldownFunc is a function that will block when called. It is intended for use with retry logic.

type Error

type Error string

Error represents an internal sentinal error which can be defined as a constant.

func (Error) Error

func (e Error) Error() string

type ErrorSource

type ErrorSource int

ErrorSource is an indicator used as a header value to indicate the source of non-2xx status codes.

const (
	ErrorSourceInvalid ErrorSource = iota
	ErrorSourceWireserver
	ErrorSourceNMAgent
)

func GetErrorSource

func GetErrorSource(head http.Header) ErrorSource

GetErrorSource retrieves the error source from the provided HTTP headers.

func NewErrorSource

func NewErrorSource(es string) ErrorSource

NewErrorSource produces an ErrorSource value from the provided string. Any unrecognized values will become the invalid type.

func (ErrorSource) String

func (e ErrorSource) String() string

String produces the string equivalent for the ErrorSource type.

type Retrier

type Retrier struct {
	Cooldown CooldownFactory
}

Retrier is a construct for attempting some operation multiple times with a configurable backoff strategy.

func (Retrier) Do

func (r Retrier) Do(ctx context.Context, run func() error) error

Do repeatedly invokes the provided run function while the context remains active. It waits in between invocations of the provided functions by delegating to the provided Cooldown function.

type TemporaryError

type TemporaryError interface {
	error
	Temporary() bool
}

TemporaryError is an error that can indicate whether it may be resolved with another attempt.

type ValidationError

type ValidationError struct {
	MissingFields []string
}

func (ValidationError) Error

func (v ValidationError) Error() string

func (ValidationError) IsEmpty

func (v ValidationError) IsEmpty() bool

type WireserverPluginQuery

type WireserverPluginQuery struct {
	Component string
	Type      string
}

WireserverPluginQuery is a construct for executing queries against plugins of Wireserver

func (WireserverPluginQuery) String

func (w WireserverPluginQuery) String() string

type WireserverResponse

type WireserverResponse map[string]json.RawMessage

WireserverResponse represents a raw response from Wireserver.

func (WireserverResponse) StatusCode

func (w WireserverResponse) StatusCode() (int, error)

StatusCode extracts the embedded HTTP status code from the response from Wireserver.

type WireserverTransport

type WireserverTransport struct {
	Transport http.RoundTripper
}

WireserverTransport is an http.RoundTripper that applies transformation rules to inbound requests necessary to make them compatible with Wireserver.

func (*WireserverTransport) RoundTrip

func (w *WireserverTransport) RoundTrip(inReq *http.Request) (*http.Response, error)

RoundTrip executes arbitrary HTTP requests against Wireserver while applying the necessary transformation rules to make such requests acceptable to Wireserver.