toclientlib

Documentation

Overview

Package toclientlib provides shared symbols for Traffic Ops Go clients.

Index

• Constants
• Variables
• func ErrIsNotImplemented(err error) bool
• func Login(url, user, pass string, opts ClientOpts, apiVersions []string) (*TOClient, ReqInf, error)
• type CacheHitStatus
  • func StringToCacheHitStatus(s string) CacheHitStatus
  • func (s CacheHitStatus) String() string
• type ClientOpts
• type HTTPError
  • func (e *HTTPError) Error() string
• type MidReqF
• type ReqF
• type ReqInf
• type TOClient
  • func LoginWithAgent(toURL string, toUser string, toPasswd string, insecure bool, userAgent string, ...) (*TOClient, net.Addr, error)
  • func LoginWithToken(toURL string, token string, insecure bool, userAgent string, ...) (*TOClient, net.Addr, error)
  • func LogoutWithAgent(toURL string, toUser string, toPasswd string, insecure bool, userAgent string, ...) (*TOClient, net.Addr, error)
  • func NewClient(user, password, url, userAgent string, client *http.Client, ...) *TOClient
  • func NewNoAuthClient(toURL string, insecure bool, userAgent string, requestTimeout time.Duration, ...) *TOClient
  • func (to *TOClient) APIBase() string
  • func (to *TOClient) APIVersion() string
  • func (to *TOClient) Close() error
  • func (to *TOClient) LatestAPIVersion() string
  • func (to *TOClient) RawRequest(method, path string, body []byte) (*http.Response, net.Addr, error)
  • func (to *TOClient) RawRequestWithHdr(method, path string, body []byte, header http.Header) (*http.Response, net.Addr, error)
  • func (to *TOClient) Req(method string, path string, body interface{}, header http.Header, ...) (ReqInf, error)

Constants

const CacheHitStatusExpired = CacheHitStatus("expired")

CacheHitStatusExpired is deprecated and will be removed in the next major version.

const CacheHitStatusHit = CacheHitStatus("hit")

CacheHitStatusHit is deprecated and will be removed in the next major version.

const CacheHitStatusInvalid = CacheHitStatus("")

CacheHitStatusInvalid is deprecated and will be removed in the next major version.

const CacheHitStatusMiss = CacheHitStatus("miss")

CacheHitStatusMiss is deprecated and will be removed in the next major version.

const DefaultAPIVersionCheckInterval = time.Second * 60

DefaultAPIVersionCheckInterval is the default minimum amount of time a TOClient will wait between checking for a newer API version from Traffic Ops.

const DefaultTimeout = time.Second * 30

DefaultTimeout is the default amount of time a TOClient instance will wait for a response to its requests before giving up.

Variables

var ErrNotImplemented = errors.New("Traffic Ops Server returned 'Not Implemented', this client is probably newer than Traffic Ops, and you probably need to either upgrade Traffic Ops, or use a client whose version matches your Traffic Ops version.")

ErrNotImplemented is returned when Traffic Ops returns a 501 Not Implemented Users should check ErrIsNotImplemented rather than comparing directly, in case context was added.

Functions

func ErrIsNotImplemented

func ErrIsNotImplemented(err error) bool

ErrIsNotImplemented checks that the given error stems from ErrNotImplemented. Caution: This method does not unwrap errors, and relies on the common behavior of concatenating error messages in cascading errors to detect the inheritance.

func Login

func Login(url, user, pass string, opts ClientOpts, apiVersions []string) (*TOClient, ReqInf, error)

Login authenticates with Traffic Ops and returns the client object.

Returns the logged in client, the remote address of Traffic Ops which was translated and used to log in, and any error. If the error is not nil, the remote address may or may not be nil, depending whether the error occurred before the login request.

apiVersions is the list of API versions to be supported. This should generally be provided by the specific client version wrapping this library.

See ClientOpts for details about options, which options are required, and how they behave.

Types

type CacheHitStatus

type CacheHitStatus string

CacheHitStatus is deprecated and will be removed in the next major version.

func StringToCacheHitStatus

func StringToCacheHitStatus(s string) CacheHitStatus

StringToCacheHitStatus is deprecated and will be removed in the next major version.

func (CacheHitStatus) String

func (s CacheHitStatus) String() string

String is deprecated and will be removed in the next major version.

type ClientOpts

type ClientOpts struct {
	// ForceLatestAPI will cause Login to return an error if the latest minor API in the client
	// is not supported by the Traffic Ops Server.
	//
	// Note this was the behavior of all Traffic Ops client functions prior to the Login function.
	//
	// If this is false or unset, login will determine the latest minor version supported, and use that for all requests.
	//
	// Be aware, this means client fields unknown to the server will always be default-initialized.
	// For example, suppose the field Foo was added in API 3.1, the client code is 3.1, and the server is 3.0.
	// Then, the field Foo will always be nil or the default value.
	// Client applications must understand this, and code processing the new feature Foo must be able to
	// process default or nil values, understanding they may indicate a server version before the feature was added.
	//
	ForceLatestAPI bool

	// Insecure is whether to ignore HTTPS certificate errors with Traffic Ops.
	// Setting this on production systems is strongly discouraged.
	Insecure bool

	// RequestTimeout is the HTTP timeout for Traffic Ops requests.
	// If 0 or not explicitly set, DefaultTimeout will be used.
	RequestTimeout time.Duration

	// UserAgent is the HTTP User Agent to use set when communicating with Traffic Ops.
	// This field is required, and Login will fail if it is unset or the empty string.
	UserAgent string

	// APIVersionCheckInterval is how often to try a newer Traffic Ops API Version.
	// This allows clients to get new Traffic Ops features after Traffic Ops is upgraded
	// without requiring a restart or new client.
	//
	// If 0 or not explicitly set, DefaultAPIVersionCheckInterval will be used.
	// To disable, set to a very high value (like 100 years).
	//
	// This has no effect if ForceLatestAPI is true.
	APIVersionCheckInterval time.Duration
}

ClientOpts is the options to configure the creation of the Client.

This exists to allow adding new features without a breaking change to the Login function. Users should understand this, and understand that upgrading their library may result in new options that their application doesn't know to use. New fields should always behave as-before if their value is the default.

type HTTPError

type HTTPError struct {
	HTTPStatusCode int
	HTTPStatus     string
	URL            string
	Body           string
}

HTTPError is returned on Update Client failure.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements the error interface for our customer error type.

type MidReqF

type MidReqF func(ReqF) ReqF

A MidReqF is a middleware that operates on a ReqF to return a ReqF with some additional behavior added.

type ReqF

type ReqF func(to *TOClient, method string, path string, body interface{}, header http.Header, response interface{}, raw bool) (ReqInf, error)

A ReqF is a function that can produce a ReqInf and any occurring error from a TOClient, a request method and path, an optional request bod, an HTTP header, and optionally decode the response into a provided reference.

type ReqInf

type ReqInf struct {
	// CacheHitStatus is deprecated and will be removed in the next major version.
	CacheHitStatus CacheHitStatus
	RemoteAddr     net.Addr
	StatusCode     int
	RespHeaders    http.Header
}

ReqInf contains information about a request - specifically it is primarily regarding the outcome of making the request.

type TOClient

type TOClient struct {
	UserName     string
	Password     string
	URL          string
	Client       *http.Client
	UserAgentStr string
	// contains filtered or unexported fields
}

TOClient is a Traffic Ops client, with generic functions to be used by any specific client.

func LoginWithAgent

func LoginWithAgent(
	toURL string,
	toUser string,
	toPasswd string,
	insecure bool,
	userAgent string,
	requestTimeout time.Duration,
	apiVersions []string,
) (*TOClient, net.Addr, error)

LoginWithAgent returns an authenticated TOClient.

Start with

toURL := "https://trafficops.example"
apiVers := []string{"3.0", "3.1"}
to := LoginWithAgent(toURL, "user", "passwd", true, "myapp/1.0", DefaultTimeout, apiVers)

subsequent calls like to.GetData("datadeliveryservice") will be authenticated.

Returns the logged in client, the remote IP address of Traffic Ops to which the given URL was resolved and used to authenticate, and any error that occurred. If the error is not nil, the remote address may or may not be nil, depending whether the error occurred before the login request.

apiVersions is the list of API versions supported in this client. This should generally be provided by the client package wrapping this package.

func LoginWithToken

func LoginWithToken(
	toURL string,
	token string,
	insecure bool,
	userAgent string,
	requestTimeout time.Duration,
	apiVersions []string,
) (*TOClient, net.Addr, error)

LoginWithToken returns an authenticated TOClient, using a token for said authentication.

Start with

toURL := "https://trafficops.example"
apiVers := []string{"3.0", "3.1"}
to := LoginWithToken(toURL, "token", true, "myapp/1.0", DefaultTimeout, apiVers)

subsequent calls like to.GetData("datadeliveryservice") will be authenticated.

Returns the logged in client, the remote IP address of Traffic Ops to which the given URL was resolved and used to authenticate, and any error that occurred. If the error is not nil, the remote address may or may not be nil, depending whether the error occurred before the login request.

apiVersions is the list of API versions supported in this client. This should generally be provided by the client package wrapping this package.

func LogoutWithAgent

func LogoutWithAgent(
	toURL string,
	toUser string,
	toPasswd string,
	insecure bool,
	userAgent string,
	requestTimeout time.Duration,
	apiVersions []string,
) (*TOClient, net.Addr, error)

LogoutWithAgent creates a new TOClient, authenticates that client with Traffic Ops, then immediately logs out before returning the TOClient. As a result, the returned TOClient is *not* authenticated, but it is verified that authentication can be performed with the given information.

apiVersions is the list of API versions supported in this client. This should generally be provided by the client package wrapping this package.

func NewClient

func NewClient(user, password, url, userAgent string, client *http.Client, apiVersions []string) *TOClient

NewClient returns a reference to a TOClient instance with the given settings. This instance is not authenticated with Traffic Ops; external callers should generally use Login, LoginWithToken, or LoginWithAgent instead.

func NewNoAuthClient

func NewNoAuthClient(
	toURL string,
	insecure bool,
	userAgent string,
	requestTimeout time.Duration,
	apiVersions []string,
) *TOClient

NewNoAuthClient returns a new Client without logging in this can be used for querying unauthenticated endpoints without requiring a login The apiVersions is the list of API versions supported in this client. This should generally be provided by the client package wrapping this package.

func (*TOClient) APIBase

func (to *TOClient) APIBase() string

APIBase returns the base API string for HTTP requests, such as /api/3.1.

func (*TOClient) APIVersion

func (to *TOClient) APIVersion() string

APIVersion is the version of the Traffic Ops API this client will use for requests. If the client was created with any function except Login, or with UseLatestSupportedAPI false, this will be LatestAPIVersion(). Otherwise, it will be the version dynamically determined to be the latest the Traffic Ops Server supports.

func (*TOClient) Close

func (to *TOClient) Close() error

Close closes all idle "kept-alive" connections in the client's connection pool. Note that connections in use are unaffected by this call, so it's not necessarily true that calling this method will leave the client with no open connections.

This will always return a nil error, the signature is just meant to conform to io.Closer.

func (*TOClient) LatestAPIVersion

func (to *TOClient) LatestAPIVersion() string

LatestAPIVersion returns the latest Traffic Ops API version this client supports.

func (*TOClient) RawRequest

func (to *TOClient) RawRequest(method, path string, body []byte) (*http.Response, net.Addr, error)

RawRequest performs the actual HTTP request to Traffic Ops, simply, without trying to refresh the cookie if an Unauthorized code is returned. Returns the response, the remote address of the Traffic Ops instance used, and any error. The returned net.Addr is guaranteed to be either nil or valid, even if the returned error is not nil. Callers are encouraged to check and use the net.Addr if an error is returned, and use the remote address in their own error messages. This violates the Go idiom that a non-nil error implies all other values are undefined, but it's more straightforward than alternatives like typecasting. Deprecated: RawRequest will be removed in 6.0. Use RawRequestWithHdr.

func (*TOClient) RawRequestWithHdr

func (to *TOClient) RawRequestWithHdr(method, path string, body []byte, header http.Header) (*http.Response, net.Addr, error)

RawRequestWithHdr makes an HTTP request to Traffic Ops. This differs from the Req method in a few ways: it returns a reference to an http.Response instead of doing any decoding for the caller, it does not do any automatic encoding of request bodies for the caller, and it includes no middleware, meaning that authentication is not retried and API version fallback is not done.

func (*TOClient) Req

func (to *TOClient) Req(method string, path string, body interface{}, header http.Header, response interface{}) (ReqInf, error)

Req makes a request using the given HTTP request method, request path (which should include any needed query string), optionally a request body, any additional HTTP headers to send, and optionally a reference into which to place a decoded response.