A GenServer that retrieves exchange rates from a configured API module on a
periodic or on-demand basis.
Add it to your application's supervision tree to enable the exchange rates service:
children = [
MyApp.Repo,
Money.ExchangeRates.Retriever
]To start with a custom configuration:
children = [
{Money.ExchangeRates.Retriever, [config: my_config]}
]Multiple named retrievers can be started independently, each backed by a different API source:
children = [
{Money.ExchangeRates.Retriever, [name: :open_exchange_rates, config: oxr_config]},
{Money.ExchangeRates.Retriever, [name: :fixer, config: fixer_config]}
]
Money.ExchangeRates.Retriever.latest_rates(:open_exchange_rates)
Money.ExchangeRates.Retriever.historic_rates(:fixer, ~D[2024-01-01])Each named retriever needs its own cache module
The bundled cache implementations (Money.ExchangeRates.Cache.Ets and
Money.ExchangeRates.Cache.Dets) use a fixed, module-wide storage location
(the :exchange_rates ETS table / a single DETS file). Two retrievers
configured with the same cache_module therefore share one cache and will
overwrite each other's rates. When running multiple named retrievers, give
each its own cache_module (a distinct module backed by a distinct ETS
table name or DETS path) in its configuration.
By default exchange rates are retrieved from
Open Exchange Rates. The retrieval interval
is configured via the :exchange_rates_retrieve_every key (milliseconds):
config :ex_money,
exchange_rates_retrieve_every: 300_000Summary
Functions
Returns a specification to start this module under a supervisor.
Returns the current configuration of the Exchange Rates Retrieval service
Forces retrieval of historic exchange rates for a single date
Forces retrieval of historic exchange rates for a range of dates
Returns the timestamp of the last successful exchange rate retrieval.
Forces retrieval of the latest exchange rates
Returns true if the latest exchange rates are available in the cache,
false otherwise.
Updates the configuration for the Exchange Rate Service
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
Returns the current configuration of the Exchange Rates Retrieval service
@spec historic_rates(Calendar.date()) :: {:ok, map()} | {:error, {Exception.t(), binary()}}
@spec historic_rates(Date.Range.t()) :: [ok: map(), error: {Exception.t(), binary()}] | {:error, {Exception.t(), binary()}}
Forces retrieval of historic exchange rates for a single date
dateis aDate.t/0or any date-compatible map or struct (Calendar.date/0) ora
Date.Range.tcreated byDate.range/2that specifies a range of dates to retrieve
Returns:
{:ok, rates}if exchange rates request is successfully sent.{:error, reason}if the request cannot be sent.
Sends a message to the exchange rate retrieval worker to request historic rates for a specified date or range be retrieved and stored.
This function does not return exchange rates, for that see
Money.ExchangeRates.latest_rates/0 or
Money.ExchangeRates.historic_rates/1.
@spec historic_rates(GenServer.server(), Calendar.date()) :: {:ok, map()} | {:error, {Exception.t(), binary()}}
@spec historic_rates(GenServer.server(), Date.Range.t()) :: [ok: map(), error: {Exception.t(), binary()}] | {:error, {Exception.t(), binary()}}
@spec historic_rates(Calendar.date(), Calendar.date()) :: [ok: map(), error: {Exception.t(), binary()}] | {:error, {Exception.t(), binary()}}
Forces retrieval of historic exchange rates for a range of dates
fromis aDate.t/0or any date-compatible map or struct (Calendar.date/0).tois aDate.t/0or any date-compatible map or struct (Calendar.date/0).
Returns:
{:ok, rates}if exchange rates request is successfully sent.{:error, reason}if the request cannot be sent.
Sends a message to the exchange rate retrieval process for each
date in the range from..to to request historic rates be
retrieved.
@spec historic_rates(GenServer.server(), Calendar.date(), Calendar.date()) :: [ok: map(), error: {Exception.t(), binary()}] | {:error, {Exception.t(), binary()}}
@spec last_updated(GenServer.server()) :: {:ok, DateTime.t()} | {:error, {Exception.t(), binary()}}
Returns the timestamp of the last successful exchange rate retrieval.
Returns:
{:ok, datetime}if rates have been retrieved at least once.{:error, reason}if the retriever is not running or no retrieval has occurred yet.
@spec latest_rates(GenServer.server()) :: {:ok, map()} | {:error, {Exception.t(), binary()}}
Forces retrieval of the latest exchange rates
Sends a message to the exchange rate retrieval worker to request current rates be retrieved and stored.
Returns:
{:ok, rates}if exchange rates request is successfully sent.{:error, reason}if the request cannot be sent.
This function does not return exchange rates, for that see
Money.ExchangeRates.latest_rates/0 or
Money.ExchangeRates.historic_rates/1.
@spec latest_rates_available?(GenServer.server()) :: boolean()
Returns true if the latest exchange rates are available in the cache,
false otherwise.
Returns false when the retriever is not running, even if the cache table
still exists.
Updates the configuration for the Exchange Rate Service