chrysom

README

chrysom

The client library for communicating with Argus over HTTP.

Summary

This package enables CRUD operations on the items stored in Argus. The items being stored are valid JSON objects. The package also provides a listener that is able to poll from Argus on an interval.

CRUD Operations

• On a GetItems() call, chrysom returns a list of all items belonging to the provided owner.
• PushItem() updates an item if the item exists and the ownership matches. If the item does not exist then a new item will be created. It will return an error or a string saying whether the item was successfully created or updated.
• RemoveItem() removes the item if it exists and returns the data associated to it.

Listener

The client contains a listener that will listen for item updates from Argus on an interval based on the client configuration.

Listener provides a mechanism to fetch a copy of all items within a bucket on an interval. If not provided, listening won't be enable for this client.

• Start begins listening for updates on an interval. A Listener must be given in the ListenerConfig for this to work. If a listener process is already in progress, calling Start() is a NoOp. If you want to restart the current listener process, call Stop() first.
• Stop requests the current listener process to stop and waits for its goroutine to complete. Calling Stop() when a listener is not running (or while one is getting stopped) returns an error.

Documentation

Overview

Package chrysom provides a client in order to interact with argus.

Index

• Constants
• Variables
• func ProvideMetrics() fx.Option
• type Auth
• type BasicClient
  • func NewBasicClient(config BasicClientConfig, getLogger func(context.Context) *zap.Logger) (*BasicClient, error)
  • func (c *BasicClient) GetItems(ctx context.Context, owner string) (Items, error)
  • func (c *BasicClient) PushItem(ctx context.Context, owner string, item model.Item) (PushResult, error)
  • func (c *BasicClient) RemoveItem(ctx context.Context, id, owner string) (model.Item, error)
• type BasicClientConfig
• type ConfigureListener
• type Items
• type Listener
• type ListenerClient
  • func NewListenerClient(config ListenerClientConfig, ...) (*ListenerClient, error)
  • func (c *ListenerClient) Start(ctx context.Context) error
  • func (c *ListenerClient) Stop(ctx context.Context) error
• type ListenerClientConfig
• type ListenerFunc
  • func (l ListenerFunc) Update(items Items)
• type Measures
• type PushReader
• type PushResult
  • func (p PushResult) String() string
• type Pusher
• type Reader

Constants

const (
	SuccessOutcome = "success"
	FailureOutcome = "failure"
)

Label Values

const (
	OutcomeLabel = "outcome"
)

Labels

const (
	PollCounter = "chrysom_polls_total"
)

Names

Variables

var (
	ErrNilMeasures             = errors.New("measures cannot be nil")
	ErrAddressEmpty            = errors.New("argus address is required")
	ErrBucketEmpty             = errors.New("bucket name is required")
	ErrItemIDEmpty             = errors.New("item ID is required")
	ErrItemDataEmpty           = errors.New("data field in item is required")
	ErrUndefinedIntervalTicker = errors.New("interval ticker is nil. Can't listen for updates")
	ErrAuthAcquirerFailure     = errors.New("failed acquiring auth token")
	ErrBadRequest              = errors.New("argus rejected the request as invalid")
)

var (
	ErrFailedAuthentication = errors.New("failed to authentication with argus")

	ErrListenerNotStopped = errors.New("listener is either running or starting")
	ErrListenerNotRunning = errors.New("listener is either stopped or stopping")
	ErrNoListenerProvided = errors.New("no listener provided")
	ErrNoReaderProvided   = errors.New("no reader provided")
)

Errors that can be returned by this package. Since some of these errors are returned wrapped, it is safest to use errors.Is() to check for them. Some internal errors might be unwrapped from output errors but unless these errors become exported, they are not part of the library API and may change in future versions.

Functions

func ProvideMetrics

func ProvideMetrics() fx.Option

Metrics returns the Metrics relevant to this package

Types

type Auth

type Auth struct {
	JWT   acquire.RemoteBearerTokenAcquirerOptions
	Basic string
}

Auth contains authorization data for requests to Argus.

type BasicClient

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

BasicClient is the client used to make requests to Argus.

func NewBasicClient

func NewBasicClient(config BasicClientConfig,
	getLogger func(context.Context) *zap.Logger) (*BasicClient, error)

NewBasicClient creates a new BasicClient that can be used to make requests to Argus.

func (*BasicClient) GetItems

func (c *BasicClient) GetItems(ctx context.Context, owner string) (Items, error)

GetItems fetches all items that belong to a given owner.

func (*BasicClient) PushItem

func (c *BasicClient) PushItem(ctx context.Context, owner string, item model.Item) (PushResult, error)

PushItem creates a new item if one doesn't already exist. If an item exists and the ownership matches, the item is simply updated.

func (*BasicClient) RemoveItem

func (c *BasicClient) RemoveItem(ctx context.Context, id, owner string) (model.Item, error)

RemoveItem removes the item if it exists and returns the data associated to it.

type BasicClientConfig

type BasicClientConfig struct {
	// Address is the Argus URL (i.e. https://example-argus.io:8090)
	Address string

	// Bucket partition to be used by this client.
	Bucket string

	// HTTPClient refers to the client that will be used to send requests.
	// (Optional) Defaults to http.DefaultClient.
	HTTPClient *http.Client

	// Auth provides the mechanism to add auth headers to outgoing requests.
	// (Optional) If not provided, no auth headers are added.
	Auth Auth
}

BasicClientConfig contains config data for the client that will be used to make requests to the Argus client.

type ConfigureListener

type ConfigureListener interface {
	// SetListener will attempt to set the lister.
	SetListener(listener Listener) error
}

type Items

type Items []model.Item

Items is a slice of model.Item(s) .

type Listener

type Listener interface {
	// Update is called when we get changes to our item listeners with either
	// additions, or updates.
	//
	// The list of hooks must contain only the current items.
	Update(items Items)
}

type ListenerClient

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

ListenerClient is the client used to poll Argus for updates.

func NewListenerClient

func NewListenerClient(config ListenerClientConfig,
	setLogger func(context.Context, *zap.Logger) context.Context,
	measures *Measures, r Reader,
) (*ListenerClient, error)

NewListenerClient creates a new ListenerClient to be used to poll Argus for updates.

func (*ListenerClient) Start

func (c *ListenerClient) Start(ctx context.Context) error

Start begins listening for updates on an interval given that client configuration is setup correctly. If a listener process is already in progress, calling Start() is a NoOp. If you want to restart the current listener process, call Stop() first.

func (*ListenerClient) Stop

func (c *ListenerClient) Stop(ctx context.Context) error

Stop requests the current listener process to stop and waits for its goroutine to complete. Calling Stop() when a listener is not running (or while one is getting stopped) returns an error.

type ListenerClientConfig

type ListenerClientConfig struct {
	// Listener provides a mechanism to fetch a copy of all items within a bucket on
	// an interval.
	// (Optional). If not provided, listening won't be enabled for this client.
	Listener Listener

	// PullInterval is how often listeners should get updates.
	// (Optional). Defaults to 5 seconds.
	PullInterval time.Duration

	// Logger to be used by the client.
	// (Optional). By default a no op logger will be used.
	Logger *zap.Logger
}

ListenerConfig contains config data for polling the Argus client.

type ListenerFunc

type ListenerFunc func(items Items)

func (ListenerFunc) Update

func (l ListenerFunc) Update(items Items)

type Measures

type Measures struct {
	fx.In
	Polls *prometheus.CounterVec `name:"chrysom_polls_total"`
}

type PushReader

type PushReader interface {
	Pusher
	Reader
}

type PushResult

type PushResult int64

PushResult is a simple type to indicate the result type for the PushItem operation.

const (
	UnknownPushResult PushResult = iota
	CreatedPushResult
	UpdatedPushResult
	NilPushResult
)

Types of pushItem successful results.

func (PushResult) String

func (p PushResult) String() string

type Pusher

type Pusher interface {
	// PushItem adds the item and establishes its link to the given owner in the store.
	PushItem(ctx context.Context, owner string, item model.Item) (PushResult, error)

	// Remove will remove the matching item from the store and return it.
	RemoveItem(ctx context.Context, id, owner string) (model.Item, error)
}

type Reader

type Reader interface {
	// GeItems returns all the items that belong to this owner.
	GetItems(ctx context.Context, owner string) (Items, error)
}