boskos

Documentation

Overview

Package boskos implements a boskos client.

Index

• Constants
• Variables
• func ResourceTypeNotFoundMessage(rType string) string
• type Client
  • func NewClient(owner, urlString string) (*Client, error)
  • func (c *Client) Acquire(rtype, state, dest string) (*Resource, error)
  • func (c *Client) AcquireByState(state, dest string, names []string) ([]Resource, error)
  • func (c *Client) AcquireByStateWait(ctx context.Context, state, dest string, names []string) ([]Resource, error)
  • func (c *Client) AcquireWait(ctx context.Context, rtype, state, dest string) (*Resource, error)
  • func (c *Client) AcquireWaitWithPriority(ctx context.Context, rtype, state, dest, requestID string) (*Resource, error)
  • func (c *Client) AcquireWithPriority(rtype, state, dest, requestID string) (*Resource, error)
  • func (c *Client) HasResource() bool
  • func (c *Client) Metric(rtype string) (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 *UserData) error
  • func (c *Client) UpdateAll(state string) error
  • func (c *Client) UpdateOne(name, state string, userData *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)
• type Metric
• type PersistenceLayer
  • func NewMemoryStorage() PersistenceLayer
• type Resource
• type UserData
  • func (ud *UserData) Extract(id string, out interface{}) error
  • func (ud *UserData) FromMap(m UserDataMap)
  • func (ud *UserData) MarshalJSON() ([]byte, error)
  • func (ud *UserData) ToMap() UserDataMap
  • func (ud *UserData) UnmarshalJSON(data []byte) error
  • func (ud *UserData) Update(newUserData *UserData) *UserData
• type UserDataMap
• type UserDataNotFound
  • func (ud *UserDataNotFound) Error() string

Constants

const (
	// Busy state defines a resource being used.
	Busy = "busy"
	// Cleaning state defines a resource being cleaned.
	Cleaning = "cleaning"
	// Dirty state defines a resource that needs cleaning.
	Dirty = "dirty"
	// Free state defines a resource that is usable.
	Free = "free"
	// Leased state defines a resource being leased in order to make a new resource.
	Leased = "leased"
	// ToBeDeleted is used for resources about to be deleted, they will be verified by a cleaner which mark them as tombstone.
	ToBeDeleted = "toBeDeleted"
	// Tombstone is the state in which a resource can safely be deleted.
	Tombstone = "tombstone"
	// Other is used to agglomerate unspecified states for metrics reporting.
	Other = "other"
)

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.

Functions

func ResourceTypeNotFoundMessage

func ResourceTypeNotFoundMessage(rType string) string

ResourceTypeNotFoundMessage returns a resource type not found message.

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, urlString 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. Note: username & passwordFile was dropped to avoid a dependency on "k8s.io/test-infra/prow/config/secret".

func (*Client) Acquire

func (c *Client) Acquire(rtype, state, dest string) (*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) ([]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) ([]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) (*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) (*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) (*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) (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 *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 *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.

type Metric

type Metric struct {
	Type    string         `json:"type"`
	Current map[string]int `json:"current"`
	Owners  map[string]int `json:"owner"`
}

Metric contains analytics about a specific resource type.

type PersistenceLayer

type PersistenceLayer interface {
	Add(r Resource) error
	Delete(name string) error
	Update(r Resource) (Resource, error)
	Get(name string) (Resource, error)
	List() ([]Resource, error)
}

PersistenceLayer defines a simple interface to persists Boskos Information.

func NewMemoryStorage

func NewMemoryStorage() PersistenceLayer

NewMemoryStorage creates an in memory persistence layer.

type Resource

type Resource struct {
	Type       string    `json:"type"`
	Name       string    `json:"name"`
	State      string    `json:"state"`
	Owner      string    `json:"owner"`
	LastUpdate time.Time `json:"lastupdate"`
	// Customized UserData
	UserData *UserData `json:"userdata"`
	// Used to clean up dynamic resources
	ExpirationDate *time.Time `json:"expiration-date,omitempty"`
}

Resource abstracts any resource type that can be tracked by boskos.

type UserData

type UserData struct {
	sync.Map
}

UserData is a map of Name to user defined interface, serialized into a string.

func (*UserData) Extract

func (ud *UserData) Extract(id string, out interface{}) error

Extract unmarshalls a string a given struct if it exists.

func (*UserData) FromMap

func (ud *UserData) FromMap(m UserDataMap)

FromMap feels updates user data from a map.

func (*UserData) MarshalJSON

func (ud *UserData) MarshalJSON() ([]byte, error)

MarshalJSON implements JSON Marshaler interface.

func (*UserData) ToMap

func (ud *UserData) ToMap() UserDataMap

ToMap converts a UserData to UserDataMap.

func (*UserData) UnmarshalJSON

func (ud *UserData) UnmarshalJSON(data []byte) error

UnmarshalJSON implements JSON Unmarshaler interface.

func (*UserData) Update

func (ud *UserData) Update(newUserData *UserData) *UserData

Update updates existing UserData with new UserData. If a key as an empty string, the key will be deleted.

type UserDataMap

type UserDataMap map[string]string

UserDataMap is the standard Map version of UserMap, it is used to ease UserMap creation.

type UserDataNotFound

type UserDataNotFound struct {
	ID string
}

UserDataNotFound will be returned if requested resource does not exist.

func (*UserDataNotFound) Error

func (ud *UserDataNotFound) Error() string