client

Documentation

Overview

Package client provides a client for interacting with the anxcloud API.

Index

• Constants
• Variables
• type Client
  • func New(options ...Option) (Client, error)
  • func NewTestClient(c Client, handler http.Handler) (Client, *httptest.Server)
• type Metric
• type MetricLabel
• type MetricReceiver
• type Option
  • func AuthFromEnv(unset bool) Option
  • func BaseURL(baseURL string) Option
  • func HTTPClient(c *http.Client) Option
  • func IgnoreMissingToken() Option
  • func LogWriter(w io.Writer) Option
  • func Logger(l logr.Logger) Option
  • func ParseEngineErrors(parseEngineErrors bool) Option
  • func TokenFromEnv(unset bool) Option
  • func TokenFromString(token string) Option
  • func UserAgent(userAgent string) Option
  • func WithClient(hc *http.Client) Option
  • func WithMetricReceiver(r MetricReceiver) Option
• type ResponseError
  • func (r ResponseError) Error() string

Constants

const (
	// TokenEnvName is the name of the environment variable that should contain the API token.
	TokenEnvName = "ANEXIA_TOKEN" //nolint:gosec // This is a name, not a secret.
	// VsphereLocationEnvName is the name of the environment variable that should contain a test location for paths that need a provisioning location.
	VsphereLocationEnvName = "ANEXIA_VSPHERE_LOCATION_ID"
	// CoreLocationEnvName is the name of the environment variable that should contain a test location for paths that need a core location.
	CoreLocationEnvName = "ANEXIA_CORE_LOCATION_ID"
	// VLANEnvName is the name of the environment variable that should contain the VLAN of VMs to manage.
	VLANEnvName = "ANEXIA_VLAN_ID"
	// IntegrationTestEnvName is the name of the environment variable that enables integration tests if present.
	IntegrationTestEnvName = "ANEXIA_INTEGRATION_TESTS_ON"
	// DefaultRequestTimeout is a suggested timeout for API calls.
	DefaultRequestTimeout = 10 * time.Second
)

const (
	// LogVerbosityRequests is the verbosity level for requests and responses.
	LogVerbosityRequests = 3

	// LogNameTrace is the name of the logger used for logging requests and responses.
	LogNameTrace = "trace"
)

Variables

var ErrConfiguration = errors.New("could not configure client")

ErrConfiguration is raised when the given configuration is insufficient or erroneous.

var ErrEnvMissing = errors.New("environment variable missing")

ErrEnvMissing indicates an environment variable is missing.

Types

type Client

type Client interface {
	// Do fires a given http.Request against the API.
	// This method behaves as http.Client.Do, but signs the request prior to sending it out
	// and returns an error is the response status is not OK.
	Do(req *http.Request) (*http.Response, error)
	BaseURL() string
}

Client interacts with the anxcloud API.

func New

func New(options ...Option) (Client, error)

New creates a new client with the given options.

The options need to contain a method of authentication with the API. If you are unsure what to use pass AuthFromEnv.

func NewTestClient

func NewTestClient(c Client, handler http.Handler) (Client, *httptest.Server)

NewTestClient creates a new client for testing.

c may be used to specify an other client implementation that needs to be tested or may be nil. handler is a http.Handler that mocks parts of the API functionality that shall be tested.

Returned will be a client.Client that can be passed to the method under test and the used httptest.Server that should be closed after test completion.

type Metric

type Metric string

Metric is a named ... metric. We have them named in prometheus format, but using this type and the given constants, non-prometheus users don't have to care about the actual name.

const (
	// MetricRequestDuration is the time in seconds it took to send the request until a response was received.
	MetricRequestDuration Metric = "http_request_duration_seconds"

	// MetricRequestCount is the number of requests sent for the given labels. It is a counter, delivered
	// as 1 for increment and -1 for decrement.
	MetricRequestCount Metric = "http_request_total"

	// MetricRequestInflight is the number of requests currently waiting for a response. It is a counter,
	// delivered as 1 for increment and -1 for decrement.
	MetricRequestInflight Metric = "http_requests_in_flight"
)

type MetricLabel

type MetricLabel string

MetricLabel is the key for the labels-map we give when passing metrics to the receiver. It again is just a prometheus-like label name but non-prometheus users don't have to care about the actual name this way.

const (
	// MetricLabelResource contains the name of the resource the given metric is about - this might be a
	// request URI, the name of a type or something similar. It will be the same for all requests for
	// the same resource-kind.
	MetricLabelResource MetricLabel = "resource"

	// MetricLabelMethod contains the HTTP verb used in the request.
	MetricLabelMethod MetricLabel = "method"

	// MetricLabelStatus contains the status code we received for the request.
	MetricLabelStatus MetricLabel = "status"
)

type MetricReceiver

type MetricReceiver func(metrics map[Metric]float64, labels map[MetricLabel]string)

MetricReceiver receives a bunch of metrics with the same labels. Counter metrics will be delivered as 1 for increment and -1 for decrement.

type Option

type Option func(o *clientOptions) error

Option is a optional parameter for the New method.

func AuthFromEnv

func AuthFromEnv(unset bool) Option

AuthFromEnv uses any known environment variables to create a client.

func BaseURL

func BaseURL(baseURL string) Option

BaseURL configures the base URL for the client to use. Defaults to the production engine, but changing this can be useful for testing.

func HTTPClient

func HTTPClient(c *http.Client) Option

HTTPClient lets the client use the given http.Client.

func IgnoreMissingToken

func IgnoreMissingToken() Option

IgnoreMissingToken makes New() not return an error when no token is supplied.

func LogWriter

func LogWriter(w io.Writer) Option

LogWriter configures the debug writer for logging requests and responses. Deprecated, use Logger instead.

func Logger

func Logger(l logr.Logger) Option

Logger configures where the client logs. Requests and responses are logged with verbosity LogVerbosityRequests on a logger derived from the one passed here with name LogNameTrace, replacing the previous LogWriter option.

func ParseEngineErrors

func ParseEngineErrors(parseEngineErrors bool) Option

ParseEngineErrors is an option to chose if the client is supposed to parse http error responses into go errors or not.

func TokenFromEnv

func TokenFromEnv(unset bool) Option

TokenFromEnv fetches the API auth token from environment variables.

func TokenFromString

func TokenFromString(token string) Option

TokenFromString uses the given API auth token.

func UserAgent

func UserAgent(userAgent string) Option

UserAgent configures the user agent string to send with every HTTP request.

func WithClient

func WithClient(hc *http.Client) Option

WithClient can be used to use another underlying http.Client.

func WithMetricReceiver

func WithMetricReceiver(r MetricReceiver) Option

WithMetricReceiver can be used to configure a receiver for client metrics (timing, request/response sizes, .. that kind of metrics).

type ResponseError

type ResponseError struct {
	Request   *http.Request  `json:"-"`
	Response  *http.Response `json:"-"`
	ErrorData struct {
		Code       int               `json:"code"`
		Message    string            `json:"message"`
		Validation map[string]string `json:"validation"`
	} `json:"error"`
	Debug struct {
		Source string `json:"source"`
	} `json:"debug"`
}

ResponseError is a response from the API that indicates an error.

func (ResponseError) Error

func (r ResponseError) Error() string