oanda_api 0.8.1 → 0.8.3

data/lib/oanda_api/client/namespace_proxy.rb

@@ -0,0 +1,112 @@
+module OandaAPI
+  module Client
+    # A client proxy and method-chaining enabler.
+    #
+    # @example Example usage
+    #   client  = OandaAPI::Client::TokenClient.new :practice, token
+    #   account = client.account(1234) # => OandaAPI::Client::NamespaceProxy
+    #   account.get                    # => OandaAPI::Resource::Account
+    #   account.orders.get             # => OandaAPI::Resource::ResourceCollection
+    #
+    # @!attribute [rw] conditions
+    #   @return [Hash] a collection of parameters that typically specifies
+    #     conditions and filters for a resource request.
+    #
+    # @!attribute [rw] namespace_segments
+    #   @return [Array<String>] an ordered list of namespaces, when joined,
+    #     creates a path to a resource URI.
+    class NamespaceProxy
+      attr_accessor :conditions, :namespace_segments
+
+      # @param [OandaAPI::Client] client
+      #
+      # @param [String] namespace_segment a _segment_ in a resource's URI. An
+      #   ordered list of segments, joined, creates a path to a resource URI.
+      #
+      # @param [Hash] conditions an optional list of parameters that typically
+      #   specifies conditions and filters for a resource request. A a _"key"_
+      #   or _"id"_ is a condition that identifies a particular resource. If a
+      #   key condition is included, it is extracted and added as a namespace
+      #   segment. See {#extract_key_and_conditions}.
+      def initialize(client, namespace_segment, conditions)
+        fail ArgumentError, "expecting an OandaAPI::Client instance" unless client && client.is_a?(OandaAPI::Client)
+        fail ArgumentError, "expecting a namespace value" if namespace_segment.to_s.empty?
+
+        @client = client
+        @conditions = {}
+        @namespace_segments = [Utils.pluralize(namespace_segment)]
+        extract_key_and_conditions conditions
+      end
+
+      # Returns a deep clone of +self+.
+      # @return [NamespaceProxy]
+      def clone
+        ns = self.dup
+        ns.conditions = conditions.dup
+        ns.namespace_segments = namespace_segments.dup
+        ns
+      end
+
+      # Returns the namespace (URI path to a resource).
+      # @return [String]
+      def namespace
+        "/" + @namespace_segments.join("/")
+      end
+
+      # Extracts a _key_ parameter from the arguments.
+      # If a key is found, it's appended to the list namespace segments. Non-key
+      # parameters are merged into the {#conditions} collection. A parameter is a
+      # key if it's named ":id", or if there is only a single scalar argument.
+      #
+      # @example "key" parameters
+      #  client  = OandaAPI::Client::TokenClient.new :practice, token
+      #  account = client.account(1234)                  # 1234 is a _key_ (accountId)
+      #  account.namespace                               # => /accounts/1234
+      #
+      #  order = account.order(instrument: "USD_JPY",
+      #                              type: "market",
+      #                             units: 10_000,
+      #                              side: "buy").create # No key parameters here
+      #
+      #  position = account.position("USD_JPY").get      # USD_JPY is a key
+      #
+      # @param conditions either a hash of parameter values, single scalar value, or nil.
+      #
+      # @return [void]
+      def extract_key_and_conditions(conditions)
+        key =
+          case
+          when conditions && conditions.is_a?(Hash)
+            @conditions.merge! Utils.rubyize_keys(conditions)
+            @conditions.delete :id
+          when conditions
+            conditions
+          end
+        @namespace_segments << key if key
+      end
+
+      # Executes an API request and returns a resource object, or returns a
+      # clone of +self+ for method chaining.
+      #
+      # @return [OandaAPI::Client::NamespaceProxy] if the method is used
+      #   for chaining.
+      #
+      # @return [OandaAPI::ResourceBase] if the method is one of the supported
+      #   _terminating_ methods (+:create+, +:close+, +:delete+, +:get+, +:update+).
+      #
+      # @return [OandaAPI::ResourceCollection] if the method is +:get+ and the
+      #   API returns a collection of resources.
+      def method_missing(sym, *args)
+        # Check for terminating method
+        if [:create, :close, :delete, :get, :update].include?(sym)
+          @client.execute_request sym, namespace, conditions
+        else
+          ns = self.clone
+          ns.namespace_segments << Utils.pluralize(sym)
+          ns.extract_key_and_conditions args.first
+          ns
+        end
+      end
+    end
+  end
+end

data/lib/oanda_api/client/resource_descriptor.rb

@@ -0,0 +1,52 @@
+module OandaAPI
+  module Client
+    # @private
+    # Metadata about a resource request.
+    #
+    # @!attribute [r] collection_name
+    #   @return [Symbol] method name that returns a collection of the resource
+    #     from the API response.
+    #
+    # @!attribute [r] path
+    #   @return [String] path of the resource URI.
+    #
+    # @!attribute [r] resource_klass
+    #   @return [Symbol] class of the resource.
+    class ResourceDescriptor
+      attr_reader :collection_name, :path, :resource_klass
+
+      # Analyzes the resource request and determines the type of resource
+      # expected from the API.
+      #
+      # @param [String] path a path to a resource.
+      #
+      # @param [Symbol] method an http verb (see {OandaAPI::Client.map_method_to_http_verb}).
+      def initialize(path, method)
+        @path = path
+        path.match(/\/(?<resource_name>[a-z]*)\/?(?<resource_id>\w*?)$/) do |names|
+          resource_name, resource_id = [Utils.singularize(names[:resource_name]), names[:resource_id]]
+          self.resource_klass = resource_name
+          @is_collection      = method == :get && resource_id.empty?
+          @collection_name    = Utils.pluralize(resource_name).to_sym if is_collection?
+        end
+      end
+
+      # True if the request returns a collection.
+      # @return [Boolean]
+      def is_collection?
+        @is_collection
+      end
+
+      private
+
+      # The resource type
+      # @param [String] resource_name
+      # @return [void]
+      def resource_klass=(resource_name)
+        klass_symbol = resource_name.capitalize.to_sym
+        fail ArgumentError, "Invalid resource" unless OandaAPI::Resource.constants.include?(klass_symbol)
+        @resource_klass = OandaAPI::Resource.const_get klass_symbol
+      end
+    end
+  end
+end

data/lib/oanda_api/client/token_client.rb

@@ -0,0 +1,69 @@
+module OandaAPI
+  module Client
+    # Makes requests to the API.
+    # Instances access Oanda's _practice_ or _live_ environments.
+    # Most API methods require an account API token to perform requests in the
+    # associated environment.
+    # See the Oanda Development Guide for information about
+    # {http://developer.oanda.com/rest-live/authentication/ obtaining a personal access token from Oanda}.
+    #
+    # @example Example usage
+    #   token  = ENV["oanda_practice_account_token"]
+    #   client = OandaAPI::Client::TokenClient.new :practice, token
+    #
+    #   # Get information for an account.
+    #   # See http://developer.oanda.com/rest-live/accounts/
+    #   account = client.accounts.get.first   # => OandaAPI::Resource::Account
+    #
+    #   # Get a list of open positions.
+    #   # See http://developer.oanda.com/rest-live/positions/
+    #   positions = client.account(account.id)
+    #                     .positions.get      # => OandaAPI::ResourceCollection
+    #
+    #
+    # @!attribute [r] auth_token
+    #   @return [String] Oanda personal access token.
+    #
+    # @!attribute [rw] domain
+    #   @return [Symbol] identifies the Oanda subdomain (+:practice+ or +:live+)
+    #     accessed by the client.
+    #
+    # @!attribute [rw] default_params
+    #   @return [Hash] parameters that are included with every API
+    #     request as either query or url_form encoded parameters.
+    #
+    # @!attribute [rw] headers
+    #   @return [Hash] parameters that are included with every API request
+    #     as HTTP headers.
+    class TokenClient
+      include Client
+
+      attr_reader :auth_token
+      attr_accessor :domain, :default_params, :headers
+
+      # @param [Symbol] domain see {#domain}
+      # @param [String] auth_token see {#auth_token}
+      def initialize(domain, auth_token)
+        super()
+        @auth_token = auth_token
+        @default_params = {}
+        self.domain = domain
+        @headers = auth
+      end
+
+      # Parameters used for authentication.
+      # @return [Hash]
+      def auth
+        { "Authorization" => "Bearer #{auth_token}" }
+      end
+
+      # @private
+      # Sets the domain the client can access. (Testing convenience only).
+      # @return [void]
+      def domain=(value)
+        fail ArgumentError, "Invalid domain" unless OandaAPI::DOMAINS.include? value
+        @domain = value
+      end
+    end
+  end
+end

data/lib/oanda_api/client/username_client.rb

@@ -0,0 +1,53 @@
+module OandaAPI
+  module Client
+    # Makes requests to the API.
+    # Instances access the Oanda _sandbox_ environment.
+    # Most client requests require a valid Oanda sandbox account username.
+    # See the Oanda Development Guide for information about
+    # {http://developer.oanda.com/rest-live/accounts/#createTestAccount creating a test account}.
+    #
+    # @example Example usage (creates a new test account).
+    #   client = OandaAPI::Client::UsernameClient.new "_"  # Note: A new test account can be created without having an
+    #                                                      # existing account, which is why we create a client in this
+    #                                                      # example with a bogus username ("_").
+    #   new_account = client.account.create                # => OandaAPI::Resource::Account
+    #   new_account.username                               # => "<username>"
+    #
+    #
+    # @!attribute [r] domain
+    #   @return [Symbol] identifies the Oanda subdomain (+:sandbox+) which the
+    #     client accesses.
+    #
+    # @!attribute [r] username
+    #  @return [String] the username used for authentication.
+    #
+    # @!attribute [rw] default_params
+    #   @return [Hash] parameters that are included with every API request as
+    #     either query or url_form encoded parameters.
+    #
+    # @!attribute [rw] headers
+    #   @return [Hash] parameters that are included with every API request as
+    #     HTTP headers.
+    class UsernameClient
+      include Client
+
+      attr_reader :domain, :username
+      attr_accessor :default_params, :headers
+
+      # @param [String] username used for authentication.
+      def initialize(username)
+        super()
+        @domain = :sandbox
+        @username = username
+        @default_params = auth
+        @headers = {}
+      end
+
+      # Parameters used for authentication.
+      # @return [Hash]
+      def auth
+        { "username" => @username }
+      end
+    end
+  end
+end

data/lib/oanda_api/configuration.rb

@@ -0,0 +1,167 @@
+module OandaAPI
+  DATETIME_FORMATS = [:rfc3339, :unix]
+
+  # Configures client API settings.
+  class Configuration
+    DATETIME_FORMAT         = :rfc3339
+    MAX_REQUESTS_PER_SECOND = 15
+    OPEN_TIMEOUT            = 10
+    READ_TIMEOUT            = 10
+    REST_API_VERSION        = "v1"
+    USE_COMPRESSION         = false
+    USE_REQUEST_THROTTLING  = false
+
+    # The format in which dates will be returned by the API (+:rfc3339+ or +:unix+).
+    # See the Oanda Development Guide for more details about {http://developer.oanda.com/rest-live/development-guide/#date_Time_Format DateTime formats}.
+    # @return [Symbol]
+    def datetime_format
+      @datetime_format ||= DATETIME_FORMAT
+    end
+
+    # See {#datetime_format}.
+    # @param [Symbol] value
+    # @return [void]
+    def datetime_format=(value)
+      fail ArgumentError, "Invalid datetime format" unless OandaAPI::DATETIME_FORMATS.include? value
+      @datetime_format = value
+    end
+
+    # The maximum number of requests per second allowed to be made through the
+    # API. Only enforced if {#use_request_throttling?} is +true+.
+    #
+    # @return [Numeric]
+    def max_requests_per_second
+      @max_requests_per_second ||= MAX_REQUESTS_PER_SECOND
+    end
+
+    # See {#max_requests_per_second}.
+    # @param [Numeric] value
+    # @return [void]
+    def max_requests_per_second=(value)
+      fail ArgumentError, "must be a number > 0" unless value.is_a?(Numeric) && value > 0
+      @min_request_interval = nil
+      @max_requests_per_second = value
+    end
+
+    # The minimum amount of time in seconds that must elapse between consecutive requests to the API.
+    # Determined by {#max_requests_per_second}. Only enforced if {#use_request_throttling?} is +true+.
+    # @return [Float]
+    def min_request_interval
+      @min_request_interval ||= (1.0 / max_requests_per_second)
+    end
+
+    # The number of seconds the client waits for a new HTTP connection to be established before
+    # raising a timeout exception.
+    # @return [Numeric]
+    def open_timeout
+      @open_timeout ||= OPEN_TIMEOUT
+    end
+
+    # See {#open_timeout}.
+    # @param [Numeric] value
+    # @return [void]
+    def open_timeout=(value)
+      fail ArgumentError, "must be an integer or float" unless value && (value.is_a?(Integer) || value.is_a?(Float))
+      @open_timeout = value
+    end
+
+    # The number of seconds the client waits for a response from the API before
+    # raising a timeout exception.
+    # @return [Numeric]
+    def read_timeout
+      @read_timeout ||= READ_TIMEOUT
+    end
+
+    # See {#read_timeout}.
+    # @param [Numeric] value
+    # @return [void]
+    def read_timeout=(value)
+      fail ArgumentError, "must be an integer or float" unless value && (value.is_a?(Integer) || value.is_a?(Float))
+      @read_timeout = value
+    end
+
+    # The Oanda REST API version used by the client.
+    # @return [String]
+    def rest_api_version
+      @rest_api_version ||= REST_API_VERSION
+    end
+
+    # See {#rest_api_version}.
+    # @param [String] value
+    # @return [void]
+    def rest_api_version=(value)
+      @rest_api_version = value
+    end
+
+    # Specifies whether the API uses compressed responses. See the Oanda Development Guide
+    # for more information about {http://developer.oanda.com/rest-live/best-practices/#compression compression}.
+    #
+    # @return [Boolean]
+    def use_compression
+      @use_compression = USE_COMPRESSION if @use_compression.nil?
+      @use_compression
+    end
+
+    alias_method :use_compression?, :use_compression
+
+    # See {#use_compression}.
+    # @param [Boolean] value
+    # @return [void]
+    def use_compression=(value)
+      @use_compression = !!value
+    end
+
+    # Throttles the rate of requests made to the API. See the Oanda Developers
+    # Guide for information about
+    # {http://developer.oanda.com/rest-live/best-practices/ connection limits}.
+    # If enabled, requests will not exceed {#max_requests_per_second}. If the
+    # rate of requests received by the client exceeds this limit, the client
+    # delays the rate-exceeding request for the minimum amount of time needed
+    # to satisfy the rate limit.
+    #
+    # @return [Boolean]
+    def use_request_throttling
+      @use_request_throttling = USE_REQUEST_THROTTLING if @use_request_throttling.nil?
+      @use_request_throttling
+    end
+
+    alias_method :use_request_throttling?, :use_request_throttling
+
+    # See {#use_request_throttling}.
+    # @param [Boolean] value
+    # @return [void]
+    def use_request_throttling=(value)
+      @use_request_throttling = !!value
+    end
+
+    # @private
+    # @return [Hash] headers that are set on every request as a result of
+    #   configuration settings.
+    def headers
+      h = {}
+      h["X-Accept-Datetime-Format"] = datetime_format.to_s.upcase
+      h["Accept-Encoding"] = "deflate, gzip" if use_compression?
+      h
+    end
+  end
+
+  # Use to configure application-wide settings.
+  #
+  # @example Example Usage
+  #   OandaAPI.configure |config|
+  #     config.use_compression = true
+  #     config.use_request_throttling = true
+  #   end
+  #
+  # @yield [Configuration]
+  # @return [void]
+  def self.configure
+    yield configuration
+  end
+
+  # @private
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+end