fx_exchange_rate 1.0.0

data/lib/exchange_rate/currency_converter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ExchangeRate
+  ##
+  # Convert between currencies, using the local cache store
+  #
+  # Examples
+  #
+  #   CurrencyConverter.new(Date.today, 'GBP', 'USD').convert!
+  #   # => 1.291700027
+  #
+  class CurrencyConverter
+    ##
+    # Builds a CurrencyConverter. The cache is not accessed on initialization.
+    #
+    # date_of_rate    - The date the rate should be used, for historical conversions.
+    # source_currency - The source currency code, e.g. 'GBP'.
+    # target_currency - The target currency code, e.g. 'USD'.
+    def initialize(date_of_rate, source_currency, target_currency)
+      @date_of_rate = date_of_rate
+      @source_currency = source_currency
+      @target_currency = target_currency
+    end
+
+    ##
+    # Convert between the source and target currencies.
+    # By default this will take 1 unit of the source currency.
+    #
+    # source_value - The number of units of source currency to convert.
+    #
+    # Examples
+    #
+    #   converter = CurrencyConverter.new(Date.today, 'GBP', 'USD')
+    #
+    #   converter.convert
+    #   # => 1.291700027
+    #
+    #   converter.convert(source_value: 2)
+    #   # => 2.583400054
+    #
+    def convert!(source_value: 1)
+      (source_value / source_rate) * target_rate
+    end
+
+    ##
+    # The (cached) source ExchangeRate::CurrencyRate object.
+    #
+    # Returns ExchangeRate::CurrencyRate.
+    #
+    # Raises ExchangeRate::MissingRateError if a cached rate does not exist.
+    def source_rate
+      find_currency_rate(@source_currency, @date_of_rate).value_in_euro
+    end
+
+    ##
+    # The (cached) source ExchangeRate::CurrencyRate object.
+    #
+    # Returns ExchangeRate::CurrencyRate.
+    #
+    # Raises ExchangeRate::MissingRateError if a cached rate does not exist.
+    def target_rate
+      find_currency_rate(@target_currency, @date_of_rate).value_in_euro
+    end
+
+    private
+
+    ##
+    # Finds a currency rate
+    #
+    # Returns ExchangeRate::CurrencyRate.
+    #
+    # Raises ExchangeRate::MissingRateError if a cached rate does not exist.
+    def find_currency_rate(currency, date_of_rate)
+      CurrencyRate.first(currency: currency, date_of_rate: date_of_rate)
+                  .tap { |rate| raise ExchangeRate::MissingRateError if rate.nil? }
+    end
+  end
+end

data/lib/exchange_rate/currency_rate.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require 'exchange_rate/database_connection'
+
+module ExchangeRate
+  ##
+  # A currency/rate/date tuple. Represents the
+  # value of the currency on a specific date, in Euro
+  # Examples
+  #
+  #   CurrencyRate.new(currency = 'GBP',
+  #                    value_in_euro = 0.001,
+  #                    date_of_rate = Date.parse('2019-03-30'))
+  #
+  class CurrencyRate < Sequel::Model(DatabaseConnection.connection[:currency_rates])
+    ##
+    # :attr_writer: currency
+    # The currency short-code String
+
+    ##
+    # :attr_writer: value_in_euro
+    # The value of one unit of the currency in Euro
+
+    ##
+    # :attr_writer: date_of_rate
+    # The effective date of this FX rate for the currency
+
+    def validate
+      super
+      validates_presence %i[currency value_in_euro date_of_rate]
+    end
+  end
+end

data/lib/exchange_rate/database_connection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require 'sequel/extensions/migration'
+require 'yaml'
+
+module ExchangeRate
+  ##
+  # Database connection management for ::ExchangeRate.
+  class DatabaseConnection
+    ##
+    # Establish a connection to the database, and ensure the schema is
+    # loaded. The connection is cached and kept open.
+    #
+    # Returns nothing
+    def self.connection
+      database_url = ExchangeRate.configuration.datastore_url
+      @connection ||= Sequel.connect(database_url).tap { |connection| apply_migrations(connection) }
+    end
+
+    ##
+    # Closes any open connections to the database and removes the cached connection.
+    def self.disconnect
+      @connection&.disconnect
+      @connection = nil
+    end
+
+    ##
+    # Apply the schema definitions to the database.
+    #
+    # Returns nothing
+    def self.apply_migrations(connection)
+      return if connection.nil?
+      Sequel::Migrator.run(connection, 'lib/exchange_rate/db/migrate/')
+    end
+  end
+end

data/lib/exchange_rate/db/migrate/20180827184400_create_currency_rates.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateCurrencyRates < Sequel::Migration
+  def up
+    create_table(:currency_rates) do |_t|
+      primary_key :id
+      String :currency, null: false
+      BigDecimal :value_in_euro, null: false
+      Date  :date_of_rate, null: false
+
+      index %i[currency date_of_rate], unique: true
+    end
+  end
+
+  def down
+    self << 'DROP TABLE currency_rates'
+  end
+end

data/lib/exchange_rate/initializers/sequel.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'sequel'
+
+# ActiveRecord-style migrations
+Sequel.extension :migration
+
+# Add helpers for when we're not sure if a record exists or not
+Sequel::Model.plugin :update_or_create
+
+# Adds ActiveRecord-style #validates_presence helpers
+Sequel::Model.plugin :validation_helpers

data/lib/exchange_rate/missing_rate_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ExchangeRate
+  ##
+  # Represents a cache-miss when requesting an FX
+  # rate.
+  class MissingRateError < StandardError; end
+end

data/lib/exchange_rate/module_methods.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+##
+# Module Methods for ExchangeRate.
+#
+#--
+# These methods are here because the configuration methods are needed in other classes which are
+# required above the ExchangeRate module definition. It felt cleaner to move the module methods
+# here than shift the module definition above the require statements.
+#
+# Note: this defines methods on the module rather than providing a mixin because the latter still
+# required the mixin to be included in the module of any class which referenced it. That might be
+# cleaner in the long run.
+#++
+module ExchangeRate
+  ##
+  # Retrieve the remote FX rate feed and cache locally.
+  #
+  # Returns nothing.
+  #
+  # Raises ExchangeRate::RetrievalFailedError if the retrieval fails or the cache cannot be updated.
+  def self.retrieve
+    configuration.rate_retriever.save!
+    nil
+  # We expect all rate retrievers to be nice and return ExchangeRate::RetrievalFailed
+  # but we'll catch everything here to safeguard against custom providers' errors
+  # bubbling up to the caller
+  rescue StandardError
+    raise ExchangeRate::RetrievalFailedError
+  end
+
+  ##
+  # Converts from from_currency to to_currency using the FX rate
+  # valid on the date_of_rate.
+  #
+  # date_of_rate  - The Date to use for conversion
+  # from_currency - The source currency code String
+  # from_currency - The target currency code String
+  #
+  # Examples
+  #
+  #   ExchangeRate.at(Date.today,'GBP','USD')
+  #   # => 0.12883019198912e1
+  #
+  # Returns the value of 1 unit of from_currency in to_currency.
+  #
+  # Raises ExchangeRate::MissingRateError if the local cache cannot be accessed or the value has not been cached.
+  def self.at(date_of_rate, from_currency, to_currency)
+    ExchangeRate::CurrencyConverter.new(date_of_rate, from_currency, to_currency).convert!
+  rescue StandardError
+    raise ExchangeRate::MissingRateError
+  end
+
+  ##
+  # The configuration object used by this module.
+  #
+  # See ExchangeRate::Configuration.
+  #
+  # Returns a singleton ExchangeRate::Configuration global configuration object.
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  ##
+  # Set the configuration object used by this module.
+  #
+  # See ExchangeRate::Configuration.
+  def self.configuration=(configuration)
+    @configuration = configuration
+  end
+
+  ##
+  # Configures the ExchangeRate module with the provided block.
+  #
+  # See ExchangeRate::Configuration.
+  #
+  # Examples
+  #
+  #   ExchangeRate.configure do |configuration|
+  #     configuration.rate_retriever = CustomRateRetriever.new
+  #   end
+  #
+  # Returns nothing
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/exchange_rate/rate_sources.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ExchangeRate
+  ##
+  # Rate retrieval classes.
+  #
+  # See ExchangeRate::RateSources::ECBRateRetriever for an example implementation.
+  module RateSources; end
+end

data/lib/exchange_rate/rate_sources/e_c_b_rate_retriever.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/conversions.rb'
+require 'net/http'
+require 'sequel/exceptions'
+require 'uri'
+
+module ExchangeRate
+  module RateSources
+    ##
+    # Retrieves FX rates from the 90 day European Central Bank (ECB) feed.
+    class ECBRateRetriever
+      ##
+      # The ECB feed URL
+      DEFAULT_FEED_URL = 'http://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml'
+
+      ##
+      # Builds a new ECBRateRetriever.
+      #
+      # - feed_url - The URL to request the ECB feed from.
+      def initialize(feed_url: DEFAULT_FEED_URL)
+        @feed_url = feed_url
+      end
+
+      ##
+      # Retrieve the feed, parse the contents, and update the local cache.
+      #
+      # Returns nothing
+      # Raises ExchangeRate::RetrievalFailedError if the feed could not be loaded
+      # Raises ExchangeRate::RetrievalFailedError if the cache could not be updated
+      #--
+      # TODO: This makes 1 database call per record to be saved. A bulk-insert would speed
+      #       things up considerably.
+      #++
+      def save!
+        retrieve_feed
+          .yield_self { |feed_body| parse_feed(feed_body) }
+          .map { |rate_date_hash| rates_from(rate_date_hash, date_from(rate_date_hash)) }
+          .flatten
+          .map(&:save)
+        nil
+      rescue StandardError
+        raise ExchangeRate::RetrievalFailedError
+      end
+
+      private
+
+      ##
+      # Perform the HTTP request to grab the feed contents.
+      #
+      # Returns the response body as a String.
+      def retrieve_feed
+        uri = URI.parse(@feed_url)
+        Net::HTTP.get_response(uri).body
+      end
+
+      ##
+      # Parse the ECB feed XML into an array of feed ::Hash objects.
+      #
+      # feed_body - The XML ECB feed document as a String.
+      #
+      # Returns an array of currency/date/rate ::Hash objects, grouped by date (see #rate_array_from).
+      def parse_feed(feed_body)
+        Hash.from_xml(feed_body)
+            .yield_self { |feed_hash| rate_array_from(feed_hash) }
+      end
+
+      ##
+      # Extract the array of FX rates from the XML document.
+      #
+      # feed_hash - A ::Hash representation of the XML ECB feed document.
+      #
+      # Returns An array of date/rate/currency ::Hash objects, grouped by date.
+      def rate_array_from(feed_hash)
+        feed_hash['Envelope']['Cube']['Cube']
+      end
+
+      ##
+      # Extract the effective date of an FX rate.
+      #
+      # rate_date_hash - A single currency/date/rate ::Hash object.
+      #
+      # Returns the effective ::Date of the FX rate.
+      def date_from(rate_date_hash)
+        Date.parse(rate_date_hash['time'])
+      end
+
+      ##
+      # Builds an array of ExchangeRate::CurrencyRate objects.
+      #
+      # rate_date_array    - An array of currency/rate ::Hash objects
+      # rate_effective_date - The effective ::Date for FX rates in the rate_date_hash.
+      def rates_from(rate_date_array, rate_effective_date)
+        rate_date_array['Cube'].map do |currency_rate_hash|
+          create_or_update_currency_rate(currency: currency_rate_hash['currency'],
+                                         value_in_euro: currency_rate_hash['rate'].to_f,
+                                         date_of_rate: rate_effective_date)
+        end
+      end
+
+      ##
+      # Creates or updates the local cache of the currency/rate/date tuple
+      #
+      # currency      - The currency short-code, e.g. 'GBP'.
+      # value_in_euro - The value of one unit (e.g. $1) in Euro.
+      # date_of_rate  - The date this value applies to.
+      #
+      # Returns true if the record saved
+      # Raises ExchangeRate::RetrievalFailedError if the record could not be saved
+      def create_or_update_currency_rate(currency:, value_in_euro:, date_of_rate:)
+        rate = CurrencyRate.find_or_new(currency: currency, date_of_rate: date_of_rate)
+        rate.value_in_euro = value_in_euro
+        rate.tap(&:save)
+      rescue Sequel::ValidationFailed, Sequel::HookFailed
+        raise ExchangeRate::RetrievalFailedError
+      end
+    end
+  end
+end

data/lib/exchange_rate/retrieval_failed_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ExchangeRate
+  ##
+  # An error raised during rate feed retrieval
+  class RetrievalFailedError < StandardError; end
+end

data/lib/exchange_rate/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ExchangeRate
+  ##
+  # The module version. Uses {Semantic Versioning}[https://www.semver.org/spec/v2.0.0.html]
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,247 @@
+--- !ruby/object:Gem::Specification
+name: fx_exchange_rate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ryan Brooks
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.58.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.58.2
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.4.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.3
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.2.1
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.11.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.13
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.13
+description: ExchangeRate uses a cache for FX rates so you are not dependent on a
+  constant connection to your FX rate provider of choice, and allow custom FX rate
+  providers to be added with ease.
+email:
+- ryan@ryanbrooks.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rdoc_options"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- fixtures/vcr_cassettes/ExchangeRate/_retrieve/fetches_the_feed_and_stores_the_values_locally.yml
+- fixtures/vcr_cassettes/ExchangeRate/_retrieve/overwrites_existing_values.yml
+- fixtures/vcr_cassettes/ExchangeRate/_retrieve/raises_ExchangeRate_RetrievalFailed_when_the_the_feed_cannot_be_retrieved.yml
+- fixtures/vcr_cassettes/ExchangeRate_RateSources_ECBRateRetriever/_save_/raises_when_the_feed_content_is_invalid.yml
+- fixtures/vcr_cassettes/ExchangeRate_RateSources_ECBRateRetriever/_save_/retrieves_the_feed.yml
+- fx_exchange_rate.gemspec
+- lib/exchange_rate.rb
+- lib/exchange_rate/configuration.rb
+- lib/exchange_rate/currency_converter.rb
+- lib/exchange_rate/currency_rate.rb
+- lib/exchange_rate/database_connection.rb
+- lib/exchange_rate/db/migrate/20180827184400_create_currency_rates.rb
+- lib/exchange_rate/initializers/sequel.rb
+- lib/exchange_rate/missing_rate_error.rb
+- lib/exchange_rate/module_methods.rb
+- lib/exchange_rate/rate_sources.rb
+- lib/exchange_rate/rate_sources/e_c_b_rate_retriever.rb
+- lib/exchange_rate/retrieval_failed_error.rb
+- lib/exchange_rate/version.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Retrieve and cache historical foreign exchange rates
+test_files: []