Money.ExchangeRates.Retriever (Money v6.2.1)

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])

Named retrievers each get their own cache

The bundled cache implementations (Money.ExchangeRates.Cache.Ets and Money.ExchangeRates.Cache.Dets) key their storage (the ETS table name / DETS file path) by the retriever's :name, so multiple named retrievers can safely share the same cache_module - each gets its own separated cache.

A custom cache module that implements only the deprecated, lower-arity Money.ExchangeRates.Cache callbacks behaves as a single, module-wide cache instead. Named retrievers sharing such a module will overwrite each other's rates; give each its own cache_module in that case.

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_000

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

config(retriever \\ __MODULE__)

Returns the current configuration of the Exchange Rates Retrieval service

delete(retriever \\ __MODULE__) deprecated

historic_rates(date_or_range)

Forces retrieval of historic exchange rates for a single date

historic_rates(retriever, date)

Forces retrieval of historic exchange rates for a range of dates

historic_rates(retriever, from, to)

last_updated(retriever \\ __MODULE__)

Returns the timestamp of the last successful exchange rate retrieval.

latest_rates(retriever \\ __MODULE__)

Forces retrieval of the latest exchange rates

latest_rates_available?(retriever \\ __MODULE__)

Returns true if the latest exchange rates are available in the cache, false otherwise.

reconfigure(retriever \\ __MODULE__, config)

Updates the configuration for the Exchange Rate Service

restart(retriever \\ __MODULE__) deprecated

retrieve_rates(url, config) deprecated

start(name \\ __MODULE__, config \\ ExchangeRates.config()) deprecated

stop(retriever \\ __MODULE__) deprecated

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

config(retriever \\ MODULE)

@spec config(GenServer.name()) ::
  Money.ExchangeRates.Config.t() | {:error, {module(), String.t()}}

Returns the current configuration of the Exchange Rates Retrieval service

delete(retriever \\ MODULE)

This function is deprecated. Use `Supervisor.delete_child/2` on your application's supervisor instead.

@spec delete(GenServer.server()) :: :ok

historic_rates(date_or_range)

@spec historic_rates(Calendar.date()) ::
  {:ok, Money.ExchangeRates.t()} | {:error, {Exception.t(), binary()}}

@spec historic_rates(Date.Range.t()) ::
  [ok: Money.ExchangeRates.t(), error: {Exception.t(), binary()}]
  | {:error, {Exception.t(), binary()}}

Forces retrieval of historic exchange rates for a single date

date is a Date.t/0 or any date-compatible map or struct (Calendar.date/0) or
a Date.Range.t created by Date.range/2 that 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.

historic_rates(retriever, date)

@spec historic_rates(GenServer.server(), Calendar.date()) ::
  {:ok, Money.ExchangeRates.t()} | {:error, {Exception.t(), binary()}}

@spec historic_rates(GenServer.server(), Date.Range.t()) ::
  [ok: Money.ExchangeRates.t(), error: {Exception.t(), binary()}]
  | {:error, {Exception.t(), binary()}}

@spec historic_rates(Calendar.date(), Calendar.date()) ::
  [ok: Money.ExchangeRates.t(), error: {Exception.t(), binary()}]
  | {:error, {Exception.t(), binary()}}

Forces retrieval of historic exchange rates for a range of dates

from is a Date.t/0 or any date-compatible map or struct (Calendar.date/0).
to is a Date.t/0 or 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.

historic_rates(retriever, from, to)

@spec historic_rates(GenServer.server(), Calendar.date(), Calendar.date()) ::
  [ok: Money.ExchangeRates.t(), error: {Exception.t(), binary()}]
  | {:error, {Exception.t(), binary()}}

last_updated(retriever \\ MODULE)

@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.

latest_rates(retriever \\ MODULE)

@spec latest_rates(GenServer.server()) ::
  {:ok, Money.ExchangeRates.t()} | {: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.

latest_rates_available?(retriever \\ MODULE)

@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.

reconfigure(retriever \\ MODULE, config)

@spec reconfigure(GenServer.name(), Money.ExchangeRates.Config.t()) ::
  Money.ExchangeRates.Config.t() | {:error, {module(), String.t()}}

Updates the configuration for the Exchange Rate Service

restart(retriever \\ MODULE)

This function is deprecated. Use `Supervisor.restart_child/2` on your application's supervisor instead.

@spec restart(GenServer.name()) :: GenServer.on_start()

retrieve_rates(url, config)

This function is deprecated. Use `Money.ExchangeRates.HTTP` or the HTTP client of your preference directly instead.

@spec retrieve_rates(charlist() | String.t(), Money.ExchangeRates.Config.t()) ::
  {:ok, map() | :not_modified} | {:error, term()}

start(name \\ MODULE, config \\ ExchangeRates.config())

This function is deprecated. Use `Supervisor.start_child/2` on your application's supervisor instead.

@spec start(GenServer.name(), Money.ExchangeRates.Config.t()) :: GenServer.on_start()

stop(retriever \\ MODULE)

This function is deprecated. Use `Supervisor.terminate_child/2` on your application's supervisor instead.

@spec stop(GenServer.server()) :: :ok