gokuu

README

Gokuu

Gokuu is a library for getting up-to-date exchange rates and converting them on Go. Gokuu is a controller and plug-in data sources that work with a specific financial institution.

Right now, Gokuu can retrieve data from the European central bank, the Russian central bank and the central bank of the United Arab Emirates. Altogether, these sources cover exchange rates for 59 currencies

Installation

go get github.com/robotomize/gokuu

Features

• Currently supports 59 currency pairs
• Use your own data sources with provider.Source interface

Usage

If you want to get all current exchange rates, you can use the following GetLatest method. When you match currency pairs from different providers, Gokuu by default saves the data from the provider who gave it faster.

ctx := context.Background()
g := gokuu.New(http.DefaultClient)

latest := g.GetLatest(ctx)
for _, r := range latest.Result {
	fmt.Printf("from: %s, to: %s, rate: %f, date: %v", 
		r.From().Symbol, r.To().Symbol, r.Rate(), r.Time(),
	)
}

With options you can change the strategy for merging data from multiple providers. For example, a merger based on priorities

g := gokuu.New(http.DefaultClient, gokuu.WithPriorityMergeStrategy())

Calculate the arithmetic average of the currency pair from all providers

g := gokuu.New(http.DefaultClient, gokuu.WithAverageMergeStrategy())

You can also use the conversion function

ctx := context.Background()
g := gokuu.New(http.DefaultClient)

conv, err := g.Convert(
	ctx, gokuu.ConvOpt{
		From:  label.USD,
		To:    label.RUB,
		Value: 10,
	},
)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(conv)

Use your caching function for better performance. For example like this

g := gokuu.New(http.DefaultClient, gokuu.WithAverageMergeStrategy())
latest := g.GetLatest(ctx)
conv, err := g.Convert(
	ctx, gokuu.ConvOpt{
		From:  label.USD,
		To:    label.RUB,
		Value: 10,
		CacheFn: func(ctx context.Context) gokuu.LatestResponse {
			return latest
		},
	},
)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(conv)

You can also use the helper functions from the package github.com/robotomize/gokuu/label

label.GetSymbols()
label.GetCountries()
label.GetCurrencies()
label.GetCountriesUsingCurrency("currency-symbol")
label.GetCurrenciesUsedCountry("countryname")

Contributing

welcome

License

SOD is under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Index

• Constants
• Variables
• func New(client *http.Client, opts ...Option) *exchanger
• type BatchExchanges
• type ConvOpt
• type ConversionResponse
  • func (e ConversionResponse) String() string
• type ExchangeRate
  • func (r ExchangeRate) From() label.Currency
  • func (r ExchangeRate) Rate() float64
  • func (r ExchangeRate) Time() time.Time
  • func (r ExchangeRate) To() label.Currency
• type Exchanger
• type FetchFunc
• type LatestResponse
  • func (e LatestResponse) Verify() bool
• type MergeFunc
• type MergeStrategyType
• type Option
  • func WithAverageMergeStrategy() Option
  • func WithMergeFunc(f MergeFunc) Option
  • func WithPriorityMergeStrategy() Option
  • func WithRaceMergeStrategy() Option
  • func WithRequestTimeout(t time.Duration) Option
  • func WithRetryDuration(t time.Duration) Option
  • func WithRetryNum(n uint64) Option
• type Options
• type Prior
• type Provider
• type ProviderRespStatus
• type SourceInfo

Constants

const (
	DefaultRequestTimeout = 10 * time.Second
	DefaultRetryNum       = 1
	DefaultRetryDuration  = 5 * time.Second
)

const (
	// ProviderNameECB source name for European central bank
	ProviderNameECB = "ecb"
	// ProviderNameRCB source name for the Russia central bank
	ProviderNameRCB = "rcb"
	// ProviderNameCAE source name for the UAE central bank
	ProviderNameCAE = "cae"
)

Variables

var (
	ErrConversionRate   = errors.New("can not convert")
	ErrCurrencyNotFound = errors.New("currency symbol is not supported")
)

Functions

func New

func New(client *http.Client, opts ...Option) *exchanger

New return exchanger

Types

type BatchExchanges

type BatchExchanges struct {
	Items map[label.Symbol]map[label.Symbol]ExchangeRate
	// contains filtered or unexported fields
}

type ConvOpt

type ConvOpt struct {
	From    label.Symbol
	To      label.Symbol
	Value   float64
	CacheFn FetchFunc
}

type ConversionResponse

type ConversionResponse struct {
	Date   time.Time
	Value  float64
	From   label.Currency
	To     label.Currency
	Rate   float64
	Amount float64
	Info   []SourceInfo
}

func (ConversionResponse) String

func (e ConversionResponse) String() string

type ExchangeRate

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

func (ExchangeRate) From

func (r ExchangeRate) From() label.Currency

func (ExchangeRate) Rate

func (r ExchangeRate) Rate() float64

func (ExchangeRate) Time

func (r ExchangeRate) Time() time.Time

func (ExchangeRate) To

func (r ExchangeRate) To() label.Currency

type Exchanger

type Exchanger interface {
	GetExchangeable() []label.Symbol
	GetLatest() LatestResponse
	Convert(ctx context.Context, from, to label.Symbol, value float64) (ConversionResponse, error)
}

type FetchFunc

type FetchFunc func(ctx context.Context) LatestResponse

type LatestResponse

type LatestResponse struct {
	Expected   []label.Symbol
	Unreceived []label.Symbol
	Info       []SourceInfo
	Result     []ExchangeRate
}

func (LatestResponse) Verify

func (e LatestResponse) Verify() bool

type MergeFunc

type MergeFunc func(*BatchExchanges, []ExchangeRate)

type MergeStrategyType

type MergeStrategyType string

const (
	MergeStrategyTypeRace     MergeStrategyType = "race"
	MergeStrategyTypeAverage  MergeStrategyType = "average"
	MergeStrategyTypePriority MergeStrategyType = "priority"
)

type Option

type Option func(*exchanger)

func WithAverageMergeStrategy

func WithAverageMergeStrategy() Option

WithAverageMergeStrategy use the merge strategy to calculate the average Value of exchange rates with a large number of providers

func WithMergeFunc

func WithMergeFunc(f MergeFunc) Option

WithMergeFunc set the custom currency merge function

func WithPriorityMergeStrategy

func WithPriorityMergeStrategy() Option

WithPriorityMergeStrategy use a strategy of merging by priority. You can set the priority of each source. You'll get a response based on priorities

func WithRaceMergeStrategy

func WithRaceMergeStrategy() Option

WithRaceMergeStrategy use the "who's the fastest" merger strategy. Duplicate data that came later are discarded

func WithRequestTimeout

func WithRequestTimeout(t time.Duration) Option

WithRequestTimeout set a timeout for source requests

func WithRetryDuration

func WithRetryDuration(t time.Duration) Option

WithRetryDuration max retry backoff

func WithRetryNum

func WithRetryNum(n uint64) Option

WithRetryNum set number of repeated requests for data retrieval errors from the source

type Options

type Options struct {
	RetryNum       uint64
	RetryDuration  time.Duration
	RequestTimeout time.Duration
	MergeStrategy  MergeStrategyType
}

type Prior

type Prior int32

type Provider

type Provider struct {
	provider.Source
	// contains filtered or unexported fields
}

type ProviderRespStatus

type ProviderRespStatus byte

const (
	ProviderRespStatusFailed ProviderRespStatus = iota
	ProviderRespStatusOK
)

type SourceInfo

type SourceInfo struct {
	Name         string
	Status       ProviderRespStatus
	ErrorMessage string
}