View Source Money.ExchangeRates behaviour (Money v5.17.0)
Implements a behaviour and functions to retrieve exchange rates from an exchange rate service.
Configuration for the exchange rate service is defined
in a Money.ExchangeRates.Config
struct. A default
configuration is returned by Money.ExchangeRates.default_config/0
.
The default configuration is:
config :ex_money,
exchange_rate_service: false,
exchange_rates_retrieve_every: 300_000,
api_module: Money.ExchangeRates.OpenExchangeRates,
callback_module: Money.ExchangeRates.Callback,
preload_historic_rates: nil
log_failure: :warn,
log_info: :info,
log_success: nil
These keys are are defined as follows:
:exchange_rate_service
is a boolean that determines whether to automatically start the exchange rate retrieval service. The default it false.:exchange_rates_retrieve_every
defines how often the exchange rates are retrieved in milliseconds. The default is 5 minutes (300,000 milliseconds):api_module
identifies the module that does the retrieval of exchange rates. This is any module that implements theMoney.ExchangeRates
behaviour. The default isMoney.ExchangeRates.OpenExchangeRates
:callback_module
defines a module that follows the Money.ExchangeRates.Callback behaviour whereby the functionrates_retrieved/2
is invoked after every successful retrieval of exchange rates. The default isMoney.ExchangeRates.Callback
.:preload_historic_rates
defines a date or a date range, that will be requested when the exchange rate service starts up. The date or date range should be specified as either aDate.t
or aDate.Range.t
or a tuple of{Date.t, Date.t}
representing thefrom
andto
dates for the rates to be retrieved. The default isnil
meaning no historic rates are preloaded.:log_failure
defines the log level at which api retrieval errors are logged. The default is:warn
:log_success
defines the log level at which successful api retrieval notifications are logged. The default isnil
which means no logging.:log_info
defines the log level at which service startup messages are logged. The default is:info
.:retriever_options
is available for exchange rate retriever module developers as a place to add retriever-specific configuration information. This information should be added in theinit/1
callback in the retriever module. SeeMoney.ExchangeRates.OpenExchangeRates.init/1
for an example.
Keys can also be configured to retrieve values from environment
variables. This lookup is done at runtime to facilitate deployment
strategies. If the value of a configuration key is
{:system, "some_string"}
then "some_string" is interpreted as
an environment variable name which is passed to System.get_env/2.
An example configuration might be:
config :ex_money,
exchange_rate_service: {:system, "RATE_SERVICE"},
exchange_rates_retrieve_every: {:system, "RETRIEVE_EVERY"},
Open Exchange Rates
If you plan to use the provided Open Exchange Rates module
to retrieve exchange rates then you should also provide the additional
configuration key for app_id
:
config :ex_money,
open_exchange_rates_app_id: "your_app_id"
or configure it via environment variable:
config :ex_money,
open_exchange_rates_app_id: {:system, "OPEN_EXCHANGE_RATES_APP_ID"}
The default exchange rate retrieval module is provided in
Money.ExchangeRates.OpenExchangeRates
which can be used
as a example to implement your own retrieval module for
other services.
Managing the configuration at runtime
During exchange rate service startup, the function init/1
is called
on the configuration exchange rate retrieval module. This module is
expected to return an updated configuration allowing a developer to
customise how the configuration is to be managed. See the implementation
at Money.ExchangeRates.OpenExchangeRates.init/1
for an example.
Summary
Callbacks
Decode the body returned from the API request and return a map of rates. THe map of rates must have an upcased atom key representing an ISO 4217 currency code and the value must be a Decimal number.
Invoked to return the historic exchange rates from the configured exchange rate retrieval service.
Invoked to return the latest exchange rates from the configured exchange rate retrieval service.
Given the default configuration, returns an updated configuration at runtime during exchange rates service startup.
Functions
Returns the configuration for ex_money
including the
configuration merged from the configured exchange rates
retriever module.
Returns the default configuration for the exchange rates retriever.
Return historic exchange rates.
Return the timestamp of the last successful retrieval of exchange rates or
{:error, reason}
if no timestamp is known.
Return the latest exchange rates.
Returns true
if the latest exchange rates are available
and false otherwise.
Types
@type t() :: %{required(Money.currency_code()) => Decimal.t()}
Callbacks
Decode the body returned from the API request and return a map of rates. THe map of rates must have an upcased atom key representing an ISO 4217 currency code and the value must be a Decimal number.
@callback get_historic_rates(Date.t(), config :: Money.ExchangeRates.Config.t()) :: {:ok, map()} | {:error, binary()}
Invoked to return the historic exchange rates from the configured exchange rate retrieval service.
config
is an%Money.ExchangeRataes.Config{}
struct
Returns {:ok, map_of_historic_rates}
or {:error, reason}
@callback get_latest_rates(config :: Money.ExchangeRates.Config.t()) :: {:ok, map()} | {:error, binary()}
Invoked to return the latest exchange rates from the configured exchange rate retrieval service.
config
is an%Money.ExchangeRataes.Config{}
struct
Returns {:ok, map_of_rates}
or {:error, reason}
@callback init(config :: Money.ExchangeRates.Config.t()) :: Money.ExchangeRates.Config.t()
Given the default configuration, returns an updated configuration at runtime during exchange rates service startup.
This callback is optional. If the callback is not defined, the default
configuration returned by Money.ExchangeRates.default_config/0
is used.
config
is the configuration returned byMoney.ExchangeRates.default_config/0
The callback is expected to return a %Money.ExchangeRates.Config.t()
struct
which may have been updated. The configuration key :retriever_options
is
available for any service-specific configuration.
Functions
Returns the configuration for ex_money
including the
configuration merged from the configured exchange rates
retriever module.
Returns the default configuration for the exchange rates retriever.
@spec historic_rates(Date.t()) :: {:ok, map()} | {:error, {Exception.t(), binary()}}
Return historic exchange rates.
date
is a date returned byDate.new/3
or any struct with the elements:year
,:month
and:day
.
Returns:
{:ok, rates}
if exchange rates are successfully retrieved.rates
is a map of exchange rates.{:error, reason}
if no exchange rates can be returned.
Note; all dates are expected to be in the Calendar.ISO calendar
This function looks up the historic exchange rates in a an ETS table
called :exchange_rates
. The actual retrieval of rates is requested
through Money.ExchangeRates.Retriever.historic_rates/1
.
@spec last_updated() :: {:ok, DateTime.t()} | {:error, {Exception.t(), binary()}}
Return the timestamp of the last successful retrieval of exchange rates or
{:error, reason}
if no timestamp is known.
Example
Money.ExchangeRates.last_updated
#> {:ok,
%DateTime{calendar: Calendar.ISO, day: 20, hour: 12, microsecond: {731942, 6},
minute: 36, month: 11, second: 6, std_offset: 0, time_zone: "Etc/UTC",
utc_offset: 0, year: 2016, zone_abbr: "UTC"}}
@spec latest_rates() :: {:ok, map()} | {:error, {Exception.t(), binary()}}
Return the latest exchange rates.
Returns:
{:ok, rates}
if exchange rates are successfully retrieved.rates
is a map of exchange rates.{:error, reason}
if no exchange rates can be returned.
This function looks up the latest exchange rates in a an ETS table
called :exchange_rates
. The actual retrieval of rates is requested
through Money.ExchangeRates.Retriever.latest_rates/0
.
@spec latest_rates_available?() :: boolean()
Returns true
if the latest exchange rates are available
and false otherwise.