client

README

Boskos Client Library

Boskos client is a go client library interfaces boskos server.

Users of boskos need to use boskos client to communicate with the deployed boskos service.

Initialize

A boskos client instance is initialized with the URL of target boskos server accompanied with owner of the client.

The client object looks like:

type Client struct {
	// RetryCount is the number of times an HTTP request issued by this client
	// is retried when the initial request fails due an inaccessible endpoint.
	RetryCount uint

	// RetryDuration is the interval to wait before retrying an HTTP operation
	// that failed due to an inaccessible endpoint.
	RetryWait time.Duration

	url       string
	resources []string
	owner     string
}

To create a boskos client, use NewClient and specify the Boskos endpoint URL and resource owner. The NewClient function also sets the client's RetryCount to 3 and RetryWait interval to 10s.

func NewClient(url string, owner string) *Client

API Reference

// Acquire asks boskos for a resource of certain type in certain state, and set the resource to dest state.
func (c *Client) Acquire(rtype string, state string, dest string) (string, error)

// AcquireWait blocks until Acquire returns the specified resource or the
// provided context is cancelled or its deadline exceeded.
func (c *Client) AcquireWait(rtype string, state string, dest string) (string, error)

// AcquireByState asks boskos for a resources of certain type, and set the resource to dest state.
// Returns a list of resources on success.
func (c *Client) AcquireByState(state, dest string, names []string) ([]common.Resource, error)

// AcquireByStateWait blocks until AcquireByState returns the specified
// resource(s) or the provided context is cancelled or its deadline exceeded.
func (c *Client) AcquireByStateWait(ctx context.Context, state, dest string, names []string) ([]common.Resource, error)

// ReleaseAll returns all resources hold by the client back to boskos and set them to dest state.
func (c *Client) ReleaseAll(dest string) error

// ReleaseOne returns one of owned resources back to boskos and set it to dest state.
func (c *Client) ReleaseOne(name string, dest string) error

// UpdateAll signals update for all resources hold by the client.
func (c *Client) UpdateAll(state string) error

// UpdateOne signals update for one of the resources hold by the client.
func (c *Client) UpdateOne(name string, state string) error

// Reset will scan all boskos resources of type, in state, last updated before expire, and set them to dest state.
// Returns a map of {resourceName:owner} for further actions.
func (c *Client) Reset(rtype string, state string, expire time.Duration, dest string) (map[string]string, error)

Documentation

Index

• Variables
• type Client
  • func NewClient(owner string, urlString, username, passwordFile string) (*Client, error)
  • func NewClientWithPasswordGetter(owner string, urlString, username string, passwordGetter func() []byte) (*Client, error)
  • func (c *Client) Acquire(rtype, state, dest string) (*common.Resource, error)
  • func (c *Client) AcquireByState(state, dest string, names []string) ([]common.Resource, error)
  • func (c *Client) AcquireByStateWait(ctx context.Context, state, dest string, names []string) ([]common.Resource, error)
  • func (c *Client) AcquireWait(ctx context.Context, rtype, state, dest string) (*common.Resource, error)
  • func (c *Client) AcquireWaitWithPriority(ctx context.Context, rtype, state, dest, requestID string) (*common.Resource, error)
  • func (c *Client) AcquireWithPriority(rtype, state, dest, requestID string) (*common.Resource, error)
  • func (c *Client) HasResource() bool
  • func (c *Client) Metric(rtype string) (common.Metric, error)
  • func (c *Client) Release(name, dest string) error
  • func (c *Client) ReleaseAll(dest string) error
  • func (c *Client) ReleaseOne(name, dest string) error
  • func (c *Client) Reset(rtype, state string, expire time.Duration, dest string) (map[string]string, error)
  • func (c *Client) SyncAll() error
  • func (c *Client) Update(name, state string, userData *common.UserData) error
  • func (c *Client) UpdateAll(state string) error
  • func (c *Client) UpdateOne(name, state string, userData *common.UserData) error
• type DialerWithRetry
  • func (d *DialerWithRetry) Dial(network, address string) (net.Conn, error)
  • func (d *DialerWithRetry) DialContext(ctx context.Context, network, address string) (net.Conn, error)

Variables

var (
	// ErrNotFound is returned by Acquire() when no resources are available.
	ErrNotFound = errors.New("resources not found")
	// ErrAlreadyInUse is returned by Acquire when resources are already being requested.
	ErrAlreadyInUse = errors.New("resources already used by another user")
	// ErrContextRequired is returned by AcquireWait and AcquireByStateWait when
	// they are invoked with a nil context.
	ErrContextRequired = errors.New("context required")
	// ErrTypeNotFound is returned when the requested resource type (rtype) does not exist.
	// For this error to be returned, you must set DistinguishNotFoundVsTypeNotFound to true.
	ErrTypeNotFound = errors.New("resource type not found")
)

var SleepFunc = time.Sleep

SleepFunc is called when requests are retried. This may be replaced in tests.

Types

type Client

type Client struct {
	// Dialer is the net.Dialer used to establish connections to the remote
	// boskos endpoint.
	Dialer DialerWithRetry
	// DistinguishNotFoundVsTypeNotFound, if set, will make it possible to distinguish between
	// ErrNotFound and ErrTypeNotFound. For backwards-compatibility, this flag is off by
	// default.
	DistinguishNotFoundVsTypeNotFound bool
	// contains filtered or unexported fields
}

Client defines the public Boskos client object

func NewClient

func NewClient(owner string, urlString, username, passwordFile string) (*Client, error)

NewClient creates a Boskos client for the specified URL and resource owner.

Clients created with this function default to retrying failed connection attempts three times with a ten second pause between each attempt.

func NewClientWithPasswordGetter

func NewClientWithPasswordGetter(owner string, urlString, username string, passwordGetter func() []byte) (*Client, error)

NewClientWithPasswordGetter creates a Boskos client for the specified URL and resource owner.

Clients created with this function default to retrying failed connection attempts three times with a ten second pause between each attempt.

func (*Client) Acquire

func (c *Client) Acquire(rtype, state, dest string) (*common.Resource, error)

Acquire asks boskos for a resource of certain type in certain state, and set the resource to dest state. Returns the resource on success.

func (*Client) AcquireByState

func (c *Client) AcquireByState(state, dest string, names []string) ([]common.Resource, error)

AcquireByState asks boskos for a resources of certain type, and set the resource to dest state. Returns a list of resources on success.

func (*Client) AcquireByStateWait

func (c *Client) AcquireByStateWait(ctx context.Context, state, dest string, names []string) ([]common.Resource, error)

AcquireByStateWait blocks until AcquireByState returns the specified resource(s) or the provided context is cancelled or its deadline exceeded.

func (*Client) AcquireWait

func (c *Client) AcquireWait(ctx context.Context, rtype, state, dest string) (*common.Resource, error)

AcquireWait blocks until Acquire returns the specified resource or the provided context is cancelled or its deadline exceeded.

func (*Client) AcquireWaitWithPriority

func (c *Client) AcquireWaitWithPriority(ctx context.Context, rtype, state, dest, requestID string) (*common.Resource, error)

AcquireWaitWithPriority blocks until Acquire returns the specified resource or the provided context is cancelled or its deadline exceeded. This allows you to pass in a request priority. Boskos Priority are FIFO.

func (*Client) AcquireWithPriority

func (c *Client) AcquireWithPriority(rtype, state, dest, requestID string) (*common.Resource, error)

AcquireWithPriority asks boskos for a resource of certain type in certain state, and set the resource to dest state. Returns the resource on success. Boskos Priority are FIFO.

func (*Client) HasResource

func (c *Client) HasResource() bool

HasResource tells if current client holds any resources

func (*Client) Metric

func (c *Client) Metric(rtype string) (common.Metric, error)

Metric will query current metric for target resource type. Return a common.Metric object on success.

func (*Client) Release

func (c *Client) Release(name, dest string) error

Release a lease for a resource and set its state to the destination state

func (*Client) ReleaseAll

func (c *Client) ReleaseAll(dest string) error

ReleaseAll returns all resources hold by the client back to boskos and set them to dest state.

func (*Client) ReleaseOne

func (c *Client) ReleaseOne(name, dest string) error

ReleaseOne returns one of owned resources back to boskos and set it to dest state.

func (*Client) Reset

func (c *Client) Reset(rtype, state string, expire time.Duration, dest string) (map[string]string, error)

Reset will scan all boskos resources of type, in state, last updated before expire, and set them to dest state. Returns a map of {resourceName:owner} for further actions.

func (*Client) SyncAll

func (c *Client) SyncAll() error

SyncAll signals update for all resources hold by the client.

func (*Client) Update

func (c *Client) Update(name, state string, userData *common.UserData) error

Update a resource on the server, setting the state and user data

func (*Client) UpdateAll

func (c *Client) UpdateAll(state string) error

UpdateAll signals update for all resources hold by the client.

func (*Client) UpdateOne

func (c *Client) UpdateOne(name, state string, userData *common.UserData) error

UpdateOne signals update for one of the resources hold by the client.

type DialerWithRetry

type DialerWithRetry struct {
	net.Dialer

	// RetryCount is the number of times to retry a connection attempt.
	RetryCount uint

	// RetrySleep is the length of time to pause between retry attempts.
	RetrySleep time.Duration
}

DialerWithRetry is a composite version of the net.Dialer that retries connection attempts.

func (*DialerWithRetry) Dial

func (d *DialerWithRetry) Dial(network, address string) (net.Conn, error)

Dial connects to the address on the named network.

func (*DialerWithRetry) DialContext

func (d *DialerWithRetry) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext connects to the address on the named network using the provided context.