client

Documentation

Index

• type Client
  • func New(options ...Option) (Client, error)
  • func NewCachingClient(client Client, size int, log log.Logger) (Client, error)
  • func NewHTTPClient(url string, groupHash []byte, client HTTPGetter) (Client, error)
  • func NewHTTPClientWithGroup(url string, group *key.Group, client HTTPGetter) (Client, error)
  • func NewPrioritizingClient(clients []Client, groupHash []byte, group *key.Group, log log.Logger) (Client, error)
• type HTTPGetter
• type Option
  • func WithCacheSize(size int) Option
  • func WithGroup(group *key.Group) Option
  • func WithGroupHash(grouphash []byte) Option
  • func WithHTTPEndpoints(urls []string) Option
  • func WithHTTPGetter(getter HTTPGetter) Option
  • func WithInsecureHTTPEndpoints(urls []string) Option
  • func WithLogger(l log.Logger) Option
• type RandomData
  • func (r *RandomData) Randomness() []byte
  • func (r *RandomData) Round() uint64
• type Result

Types

type Client

type Client interface {
	// Get returns a the randomness at `round` or an error.
	// Requesting round = 0 will return randomness for the most
	// recent known round, bounded at a minimum to the `RoundAt(time.Now())`
	Get(ctx context.Context, round uint64) (Result, error)

	// Watch returns new randomness as it becomes available.
	Watch(ctx context.Context) <-chan Result

	// RoundAt will return the most recent round of randomness that will be available
	// at time for the current client.
	RoundAt(time time.Time) uint64
}

Client represents the drand Client interface.

func New

func New(options ...Option) (Client, error)

New Creates a client with specified configuration.

func NewCachingClient

func NewCachingClient(client Client, size int, log log.Logger) (Client, error)

NewCachingClient is a meta client that stores an LRU cache of recently fetched random values.

func NewHTTPClient

func NewHTTPClient(url string, groupHash []byte, client HTTPGetter) (Client, error)

NewHTTPClient creates a new client pointing to an HTTP endpoint

func NewHTTPClientWithGroup

func NewHTTPClientWithGroup(url string, group *key.Group, client HTTPGetter) (Client, error)

NewHTTPClientWithGroup constructs an http client when the group parameters are already known.

func NewPrioritizingClient

func NewPrioritizingClient(clients []Client, groupHash []byte, group *key.Group, log log.Logger) (Client, error)

NewPrioritizingClient is a meta client that asks each sub-client in succession on requests until an answer is found. If a sub-client fails, it is moved to the end of the list.

type HTTPGetter

type HTTPGetter interface {
	Do(req *http.Request) (*http.Response, error)
	Get(url string) (resp *http.Response, err error)
}

HTTPGetter is an interface for the exercised methods of an `http.Client`, or equivalent alternative.

type Option

type Option func(cfg *clientConfig) error

Option is an option configuring a client.

func WithCacheSize

func WithCacheSize(size int) Option

WithCacheSize specifies how large of a cache of randomness values should be kept locally. Default 32

func WithGroup

func WithGroup(group *key.Group) Option

WithGroup configures the client to root trust in the given group information

func WithGroupHash

func WithGroupHash(grouphash []byte) Option

WithGroupHash configures the client to root trust with a given drand group hash, the group parameters will be fetched from an HTTP endpoint.

func WithHTTPEndpoints

func WithHTTPEndpoints(urls []string) Option

WithHTTPEndpoints configures the client to use the provided URLs.

func WithHTTPGetter

func WithHTTPGetter(getter HTTPGetter) Option

WithHTTPGetter specifies the HTTP Client (or mocked equivalent) for fetching randomness from an HTTP endpoint.

func WithInsecureHTTPEndpoints

func WithInsecureHTTPEndpoints(urls []string) Option

WithInsecureHTTPEndpoints configures the client to pull randomness from provided URLs without validating the group trust root.

func WithLogger

func WithLogger(l log.Logger) Option

WithLogger overrides the logging options for the client, allowing specification of additional tags, or redirection / configuration of logging level and output.

type RandomData

type RandomData struct {
	Rnd               uint64 `json:"round,omitempty"`
	Random            []byte `json:"randomness,omitempty"`
	Signature         []byte `json:"signature,omitempty"`
	PreviousSignature []byte `json:"previous_signature,omitempty"`
}

RandomData holds the full random response from the server, including data needed for validation.

func (*RandomData) Randomness

func (r *RandomData) Randomness() []byte

Randomness exports the randomness

func (*RandomData) Round

func (r *RandomData) Round() uint64

Round provides access to the round associatted with this random data.

type Result

type Result interface {
	Round() uint64
	Randomness() []byte
}

Result represents the randomness for a single drand round.