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 the Money.ExchangeRates behaviour. The default is Money.ExchangeRates.OpenExchangeRates

• :callback_module defines a module that follows the Money.ExchangeRates.Callback behaviour whereby the function rates_retrieved/2 is invoked after every successful retrieval of exchange rates. The default is Money.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 a Date.t or a Date.Range.t or a tuple of {Date.t, Date.t} representing the from and to dates for the rates to be retrieved. The default is nil 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 is nil 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 the init/1 callback in the retriever module. See Money.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.