els

Documentation

Overview

Package els provides support for communicating with the Elastic Licensing Service (ELS), including the acquisition of access keys and the signing of API calls using those access keys.

Index

• Constants
• Variables
• type APICaller
• type APIHandler
  • func NewAPIHandler(c *http.Client) *APIHandler
  • func (h *APIHandler) CreateAccessKey(ctx context.Context, emailAddress string, password string, pwPrehashed bool, ...) (a *AccessKey, statusCode int, err error)
• type APISigner
  • func NewAPISigner(k *AccessKey) (a *APISigner, err error)
  • func (s *APISigner) Sign(r *http.Request, now time.Time) error
• type APIUtils
• type AccessKey
  • func (a *AccessKey) CanSign() bool
  • func (a *AccessKey) ValidUntil(now time.Time, in time.Duration) bool
• type AccessKeyID
• type EDAPICaller
  • func NewEDAPICaller(c *http.Client, tp datetime.TimeProvider, timeout time.Duration, ...) (a *EDAPICaller)
  • func (a *EDAPICaller) Do(ctx context.Context, r *http.Request, s Signer, isELSAPI bool) (*http.Response, error)
  • func (a *EDAPICaller) Get(ctx context.Context, url string, s Signer, isELSAPI bool) (*http.Response, error)
  • func (a *EDAPICaller) LastTimeout() time.Time
• type SecretAccessKey
• type Signer

Constants

const (
	DefaultAPIScheme    = "https"
	DefaultAPIDomain    = "api.elasticlicensing.com"
	DefaultAPIVersion   = "1.0"
	RequiredContentType = "application/json;charset=utf-8"
)

Variables

var (
	ErrNoAccessKey       = errors.New("No Access Key")
	ErrNoRequest         = errors.New("No Request")
	ErrInvalidAccessKey  = errors.New("Invalid Access Key")
	ErrExpiredAccessKey  = errors.New("Expired Access Key")
	ErrRequestInvalidURL = errors.New("Invalid URL")
)

var (
	ErrUnexpectedStatusCode = errors.New("Unexpected Status Code")
)

Errors which may be expected to be returned from an APIHandler's methods.

Types

type APICaller

type APICaller interface {
	// embedding APIUtils confers the ability to request an access key
	// for a user.
	APIUtils

	// Do executes the request, optionally ELS-signing it (if a signer is passed
	// and optionally completing the URL if the request is an ELS API request
	// (i.e. isELSAPI is true). Pass nil as ctx to use a default context or pass
	// your own if you want explicit control over the timeout period. Set
	// isELSAPI to false and pass nil as s if making an API call to a third
	// party.
	// If the request times out, error will be set to ctx.Err().
	Do(ctx context.Context, r *http.Request, s Signer, isELSAPI bool) (*http.Response, error)

	// Get executes an HTTP GET request with the given url. Pass nil as ctx to
	// use a default context or pass your own if you want explicit control over
	// the timeout period. If the request times out, error will be set to
	// ctx.Err().
	Get(ctx context.Context, url string, s Signer, isELSAPI bool) (*http.Response, error)

	// LastTimeout returns the time when an API call last failed to connect. If
	// there have been no timeouts, it will return the zero time (time.Time{})
	LastTimeout() time.Time
}

APICaller identifies the methods that are used to access the ELS and other APIs.

type APIHandler

type APIHandler struct {
	// Scheme defines the http scheme to use - usually "https". In practise this
	// is only overriden during testing.
	Scheme string

	// Domain is the API domain, e.g. "api.elasticlicensing.com".
	Domain string

	// Version is the API version to use in requests. E.g. "1.0".
	Version string

	// Client is used to make all API calls.
	Client *http.Client
}

APIHandler implements APIUtils and provides convenience methods for interacting with the ELS API.

func NewAPIHandler

func NewAPIHandler(c *http.Client) *APIHandler

NewAPIHandler returns an APIHandler configured to use the given http.Client. Pass nil for the http client, to force use of http.DefaultClient instead.

func (*APIHandler) CreateAccessKey

func (h *APIHandler) CreateAccessKey(ctx context.Context, emailAddress string, password string, pwPrehashed bool, expiryDays uint) (a *AccessKey, statusCode int, err error)

CreateAccessKey returns a new temporary AccessKey generated by the ELS, using the credentials passed. An AccessKey is used by a Signer to sign all ELS API calls. The credentials must match that of an existing user in the ELS. expiryDays determines after how many days the newly-generated access key should expire. If 0, then the access key does not expire. If the context is cancelled or times out then ctx.Err() will be returned. If there is a response from the server but the http status code is not 201 (created), then an error will be returned and statusCode will indicate the statuscode received.

type APISigner

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

APISigner implements the Signer interface and is used to modify an http.Request to be 'ELS-signed' by an Access Key (which is bound to an ELS user). ELS API calls must be ELS-signed or they will be immediately rejected. Note that even once ELS-Signed, a request may return an unauthorised response if the user whose AccessKey was used to sign the request is not authorised to make the request.

func NewAPISigner

func NewAPISigner(k *AccessKey) (a *APISigner, err error)

func (*APISigner) Sign

func (s *APISigner) Sign(r *http.Request, now time.Time) error

Sign signs the given request using the given access key. It is assumed that the request being signed will be sent immediately.

type APIUtils

type APIUtils interface {
	CreateAccessKey(ctx context.Context, emailAddress string, password string, pwPrehashed bool, expiryDays uint) (*AccessKey, int, error)
}

APIUtils defines the methods which Api Handlers are expected to implement.

type AccessKey

type AccessKey struct {
	// Id is the public part of the access key which appears in the header of a
	// signed request. This field is mandatory.
	ID AccessKeyID `json:"accessKeyId,omitempty"`

	// SecretAccessKey is the private part of the access key, known only by the
	// holder of the Key and the ELS, and whose value is used in the signing
	// process. This field is mandatory.
	SecretAccessKey SecretAccessKey `json:"secretAccessKey,omitempty"`

	// ExpiryDate is an optional time which, if set to the non-zero time,  is
	// used to prevent use of the AccessKey to sign requests if it is known to
	// have expired.
	ExpiryDate time.Time `json:"expiryDt"`

	// Email is the email address of the user to whom this access key belongs.
	Email string `json:"emailAddress,omitempty"`
}

AccessKey represents an access key that is used to sign ELS API Requests on behalf of a user identified by email address. An acesss key has a public 'accessKeyId' and a private 'secretAccessKey'.

func (*AccessKey) CanSign

func (a *AccessKey) CanSign() bool

CanSign returns true if the AccessKey is able to sign an API Request.

func (*AccessKey) ValidUntil

func (a *AccessKey) ValidUntil(now time.Time, in time.Duration) bool

ValidUntil returns true if the access key has not expired and will not do so within the given duration from now. Note that if ExpiryDate is the zero value time, this signifies "never expires".

type AccessKeyID

type AccessKeyID string

AccessKeyID represents the public part of an ELS access Key.

type EDAPICaller

type EDAPICaller struct {
	sync.RWMutex

	// APIHandler is used to request Access Keys.
	APIHandler
	// contains filtered or unexported fields
}

EDAPICaller implements interface APICaller is used to make API calls to the ELS.

func NewEDAPICaller

func NewEDAPICaller(c *http.Client, tp datetime.TimeProvider, timeout time.Duration, apiVersion string) (a *EDAPICaller)

NewEDAPICaller returns an EDAPICaller which will sign http.Requests and send them using the given client and signer.. Pass nil for c to use http.DefaultClient. Leave apiVersion blank to use the current version of the API. If you need to use multiple versions of the API, then create multiple EDAPICallers.

func (*EDAPICaller) Do

func (a *EDAPICaller) Do(ctx context.Context, r *http.Request, s Signer, isELSAPI bool) (*http.Response, error)

Do completes the url of the request, signs the request and executes it. If the context has a deadline which expires, then context.DeadlineExceeded will be returned. Pass nil as ctx if you want a default context which times-out after the default ELS-signed API call timeout. Pass nil as s if you don't want the API call to be ELS-signed. Pass false as isELSAPI if the request is a call to a third-party API.

func (*EDAPICaller) Get

func (a *EDAPICaller) Get(ctx context.Context, url string, s Signer, isELSAPI bool) (*http.Response, error)

Get creates a signed GET request with a completed version of the url and executes it. Pass nil as ctx if you want a default context which times-out after the default ELS-signed API call timeout. Pass nill as s if you don't want the API call to be ELS-signed. Pass false as isELSAPI if the request is a call to a third-party API.

func (*EDAPICaller) LastTimeout

func (a *EDAPICaller) LastTimeout() time.Time

LastTimeout returns the last time a timeout was encountered by the EDAPICaller.

type SecretAccessKey

type SecretAccessKey string

SecretAccessKey represents the private part of an ELS access Key.

type Signer

type Signer interface {
	Sign(r *http.Request, now time.Time) error
}

Signer defines the methods that must be implemented by a class that implements ELS API request signing.