oanda_api 0.8.3 → 0.9.0

data/lib/oanda_api/streaming/request.rb

@@ -0,0 +1,135 @@
+module OandaAPI
+  module Streaming
+    # An HTTP 1.1 streaming request. Used to create a persistent connection
+    #   with the server and continuously download a stream of resource
+    #   representations. Resources are emitted as {OandaAPI::ResourceBase}
+    #   instances.
+    #
+    # @!attribute [rw] client
+    #   @return [OandaAPI::Streaming::Client] a streaming client instance.
+    #
+    # @!attribute [rw] emit_heartbeats
+    #   @return [boolean]
+    #
+    # @!attribute [r] uri
+    #   @return [URI::HTTPS] a URI instance.
+    #
+    # @!attribute [r] request
+    #   @return [URI::HTTPS] a URI instance.
+    class Request
+      attr_accessor :client, :emit_heartbeats
+      attr_reader :uri, :request
+
+      # Creates an OandaAPI::Streaming::Request instance.
+      # @param [Streaming::Client] client a streaming client instance that can be used to
+      #   send signals to an instance of this Streaming::Request.
+      # @param [String] uri an absolute URI to the service endpoint.
+      # @param [Hash] query a list of query parameters, unencoded. The list
+      #   is converted into a query string. See {OandaAPI::Client#query_string_normalizer}.
+      # @param [Hash] headers a list of header values that will be sent with the request.
+      def initialize(client: nil, uri:, query: {}, headers: {})
+        self.client = client.nil? ? self : client
+        @uri = URI uri
+        @uri.query = OandaAPI::Client.default_options[:query_string_normalizer].call(query)
+        @http = Net::HTTP.new @uri.host, 443
+        @http.use_ssl = true
+        @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        @request = Net::HTTP::Get.new @uri
+        headers.each_pair { |pair| @request.add_field(*pair) }
+      end
+
+      # Sets the client attribute
+      # @param [OandaAPI::Streaming::Client] value
+      # @return [void]
+      # @raise [ArgumentError] if value is not an OandaAPI::Streaming::Client instance.
+      def client=(value)
+        fail ArgumentError, "Expecting an OandaAPI::Streaming::Client" unless (value.is_a?(OandaAPI::Streaming::Client) || value.is_a?(OandaAPI::Streaming::Request))
+        @client = value
+      end
+
+      # @return [boolean] true if heatbeats are emitted.
+      def emit_heartbeats?
+        !!@emit_heartbeats
+      end
+
+      # Signals the streaming request to disconnect and terminates streaming.
+      # @return [void]
+      def stop!
+        @stop_requested = true
+      end
+
+      # Returns `true` if the request has been signalled to terminate. See {#stop!}.
+      # @return [boolean]
+      def stop_requested?
+        !!@stop_requested
+      end
+
+      # @return [true] if the instance is connected and streaming a response.
+      def running?
+        !!@running
+      end
+
+      # Emits a stream of {OandaAPI::ResourceBase} instances, depending
+      #  on the endpoint that the request is servicing, either
+      #  {OandaAPI::Resource::Price} or {OandaAPI::Resource::Transaction}
+      #  instances are emitted. When #emit_heartbeats? is `true`, then
+      #  resources could also be {OandaAPI::Resource::Heartbeat}.
+      #
+      #  Note this method runs as an infinite loop and will block indefinitely
+      #  until either the connection is halted or a {#stop!} signal is recieved.
+      #
+      # @yield [OandaAPI::ResourceBase, OandaAPI::Streaming::Client] Each resource found in the response
+      #   stream is yielded as they are received. The client instance controlling the
+      #   streaming request is also yielded. It can be used to issue a signaller.#stop! to terminate the resquest.
+      # @raise [OandaAPI::StreamingDisconnect] if the endpoint was disconnected by server.
+      # @raise [OandaAPI::RequestError] if an unexpected resource is returned.
+      # @return [void]
+      def stream(&block)
+        @stop_requested = false
+        @running = true
+        # @http.set_debug_output $stderr
+        @http.request(@request) do |response|
+          response.read_body do |chunk|
+            handle_response(chunk).each do |resource|
+              block.call(resource, @client)
+              return if stop_requested?
+            end
+            return if stop_requested?
+            sleep 0.01
+          end
+        end
+      ensure
+        @running = false
+        @http.finish if @http.started?
+      end
+
+      private
+
+      # @private
+      # Converts a raw json response into {OandaAPI::ResourceBase} instances.
+      # @return [Array<OandaAPI::ResourceBase>] depending on the endpoint
+      #   that the request is servicing, which is either an array of
+      #   {OandaAPI::Resource::Price} or {OandaAPI::Resource::Transaction} instances.
+      #   When #emit_heartbeats? is `true`, then the instance could be an {OandaAPI::Resource::Heartbeat}.
+      # @raise [OandaAPI::StreamingDisconnect] if the endpoint was disconnected by server.
+      # @raise [OandaAPI::RequestError] if an unexpected resource is returned.
+      def handle_response(response)
+        response.split("\r\n").map do |json|
+          parsed_response = JSON.parse json
+          case
+          when parsed_response["heartbeat"]
+            OandaAPI::Resource::Heartbeat.new parsed_response["heartbeat"] if emit_heartbeats?
+          when parsed_response["tick"]
+            OandaAPI::Resource::Price.new parsed_response["tick"]
+          when parsed_response["transaction"]
+            OandaAPI::Resource::Transaction.new parsed_response["transaction"]
+          when parsed_response["disconnect"]
+            raise OandaAPI::StreamingDisconnect, parsed_response["disconnect"]["message"]
+          else
+            raise OandaAPI::RequestError, "unknown resource: #{json}"
+          end
+        end.compact
+      end
+    end
+  end
+end

data/lib/oanda_api/utils/utils.rb

@@ -45,7 +45,7 @@ module OandaAPI
     # Yields all keys of a hash, and safely applies whatever transform
     # the block provides. Supports nested hashes.
     #
-    # @param [Object] value can be a +Hash+, an +Array+ or scalar object type.
+    # @param [Object] value can be a `Hash`, an `Array` or scalar object type.
     #
     # @param [Block] block transforms the yielded key.
     #
@@ -68,7 +68,7 @@ module OandaAPI
     # transform the block provides to the values.
     # Supports nested hashes and arrays.
     #
-    # @param [Object] value can be a +Hash+, an +Array+ or scalar object type.
+    # @param [Object] value can be a `Hash`, an `Array` or scalar object type.
     #
     # @param [Object] key
     #

data/lib/oanda_api/version.rb

@@ -1,3 +1,3 @@
 module OandaAPI
-  VERSION = "0.8.3"
+  VERSION = "0.9.0"
 end

data/spec/oanda_api/resource_base_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+describe "OandaAPI::ResourceBase" do
+  class MyClass < OandaAPI::ResourceBase
+    attr_accessor :webbed_feet
+  end
+
+  class MyCustomizedClass < OandaAPI::ResourceBase
+    attr_accessor :webbed_feet
+
+    def custom_attributes
+      super.merge(webbed_feet: "customized #{webbed_feet}")
+    end
+  end
+
+  describe "#initialize" do
+    it "initializes writer methods with matching attributes" do
+      obj = MyClass.new webbed_feet: "webbed feet"
+      expect(obj.webbed_feet).to eq "webbed feet"
+    end
+
+    it "initializes snake_case writer methods with matching camelCase attributes" do
+      obj = MyClass.new webbedFeet: "webbed feet"
+      expect(obj.webbed_feet).to eq "webbed feet"
+    end
+  end
+
+  describe "#location" do
+    it "sets location" do
+      obj = MyClass.new location: "location"
+      expect(obj.location).to eq "location"
+    end
+  end
+
+  describe "#to_json" do
+    it "serializes all of an instance's attributes" do
+      obj = MyClass.new webbedFeet: "webbed feet", location: "location", extraAttribute: "extra"
+      h = JSON.parse obj.to_json
+      expect(h).to include("webbed_feet" => "webbed feet", "extra_attribute" => "extra", "location" => "location")
+    end
+
+    it "serializes all of an instance's customized attributes" do
+      obj = MyCustomizedClass.new webbedFeet: "webbed feet"
+      h = JSON.parse obj.to_json
+      expect(h).to include("webbed_feet" => "customized webbed feet")
+    end
+  end
+end

data/spec/oanda_api/resource_collection_spec.rb

@@ -26,7 +26,7 @@ describe "OandaAPI::ResourceCollection" do
       describe "when the collection element is empty" do
         let(:resource_collection) { OandaAPI::ResourceCollection.new({ candles: [] }, resource_descriptor) }
         it "returns a ResourceCollection" do
-           expect(resource_collection).to be_an(OandaAPI::ResourceCollection)
+          expect(resource_collection).to be_an(OandaAPI::ResourceCollection)
         end
         it "is an empty collection" do
           expect(resource_collection.empty?).to be true
@@ -106,4 +106,4 @@ describe "OandaAPI::ResourceCollection" do
       expect(resource_collection.respond_to?(:location)).to be true
     end
   end
-end
+end

data/spec/oanda_api/streaming/client_spec.rb

@@ -0,0 +1,132 @@
+require 'spec_helper'
+require 'uri'
+require 'webmock/rspec'
+
+describe "OandaAPI::Streaming::Client" do
+  let(:client) { OandaAPI::Streaming::Client.new(:practice, "token") }
+
+  describe "#initialize" do
+    it "creates a Streaming::Client instance" do
+      expect(client).to be_a(OandaAPI::Streaming::Client)
+    end
+
+    it "sets the authorization token" do
+      expect(client.auth_token).to eq("token")
+    end
+
+    it "sets the domain" do
+      expect(client.domain).to eq(:practice)
+    end
+
+    it "sets authorization headers" do
+      expect(client.headers).to eq(client.auth)
+    end
+
+    it "defaults emit_heartbeats to false" do
+      expect(client.emit_heartbeats?).to be false
+    end
+  end
+
+  describe "#api_uri" do
+    let(:client) { Struct.new(:domain) { include OandaAPI::Client }.new }
+    it "is domain specific" do
+      uris = {}
+      OandaAPI::DOMAINS.each do |domain|
+        client.domain = domain
+        uris[client.api_uri("/path")] = domain
+      end
+      expect(uris.size).to eq(3)
+    end
+
+    it "is an absolute URI" do
+      OandaAPI::DOMAINS.each do |domain|
+        client.domain = domain
+        uri = URI.parse client.api_uri("/path")
+        expect(uri.absolute?).to be true
+      end
+    end
+  end
+
+  describe "#auth" do
+    it "returns a hash with an Authorization key" do
+      expect(client.auth["Authorization"]).to eq("Bearer token")
+    end
+  end
+
+  describe "#domain=" do
+    OandaAPI::DOMAINS.each do |domain|
+      it "allows domain :#{domain} " do
+        client.domain = domain
+        expect(client.domain).to be(domain)
+      end
+    end
+
+    it "doesn't allow invalid domains" do
+      expect { client.domain = :bogus }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#emit_heartbeats=" do
+    it "sets the emits heartbeats attribute" do
+      [true, false].each do |value|
+        client.emit_heartbeats = value
+        expect(client.emit_heartbeats?).to be value
+      end
+    end
+  end
+
+  describe "headers" do
+    it "has a reader and writer" do
+      client.headers = { key: "value" }
+      expect(client.headers).to eq(key: "value")
+    end
+  end
+
+  describe "#running?" do
+    it "returns true if a streaming request is running" do
+      events_json = <<-END
+      {"heartbeat":{"time":"2014-05-26T13:58:40Z"}}\r\n
+      {"transaction":{"id":10001}}\r\n
+      {"transaction":{"id":10002}}
+      END
+      stub_request(:get, "https://stream-fxpractice.oanda.com/v1/events").to_return(body: events_json, status: 200)
+
+      client = OandaAPI::Streaming::Client.new(:practice, "token")
+      expect(client.running?).to be false
+      client.events.stream do |_event, signaller|
+        expect(client.running?).to be true
+        signaller.stop!
+      end
+    end
+  end
+
+  describe "#stop!" do
+    events_json = <<-END
+      {"transaction":{"id": 1}}\r\n
+      {"transaction":{"id": 2}}
+    END
+
+    context "without using #stop!" do
+      it "emits all objects in the stream" do
+        stub_request(:get, "https://stream-fxpractice.oanda.com/v1/events").to_return(body: events_json, status: 200)
+        client = OandaAPI::Streaming::Client.new(:practice, "token")
+        event_ids = []
+        client.events.stream { |event| event_ids << event.id }
+        expect(event_ids).to contain_exactly(1, 2)
+      end
+    end
+
+    context "when using #stop!" do
+      it "terminates emitting objects in the stream" do
+        stub_request(:get, "https://stream-fxpractice.oanda.com/v1/events").to_return(body: events_json, status: 200)
+        client = OandaAPI::Streaming::Client.new(:practice, "token")
+        event_ids = []
+        client.events.stream do |event, signaller|
+          event_ids << event.id
+          signaller.stop!
+        end
+        expect(event_ids).to contain_exactly(1)
+      end
+    end
+  end
+end

data/spec/oanda_api/streaming/request_spec.rb

@@ -0,0 +1,172 @@
+require 'spec_helper'
+require 'uri'
+require 'webmock/rspec'
+
+describe "OandaAPI::Streaming::Request" do
+  let(:streaming_request) {
+    OandaAPI::Streaming::Request.new(uri: "https://a.url.com",
+                                     query: { account: 1234, instruments: %w[AUD_CAD AUD_CHF] },
+                                     headers: { "some-header" => "header value" })
+  }
+
+  describe "#initialize" do
+    it "creates a Streaming::Request instance" do
+      expect(streaming_request).to be_an(OandaAPI::Streaming::Request)
+    end
+
+    it "initializes the uri attribute" do
+      expect(streaming_request.uri.to_s).to eq "https://a.url.com?account=1234&instruments=AUD_CAD%2CAUD_CHF"
+    end
+
+    it "initializes the request headers attribute" do
+      expect(streaming_request.request["some-header"]).to eq "header value"
+    end
+
+    it "initializes the request's client attribute" do
+      client = OandaAPI::Streaming::Client.new :practice, "token"
+      streaming_request = OandaAPI::Streaming::Request.new(client: client,
+                                                           uri: "https://a.url.com",
+                                                           query: { account: 1234, instruments: %w[AUD_CAD AUD_CHF] },
+                                                           headers: { "some-header" => "header value" })
+      expect(streaming_request.client).to eq client
+    end
+  end
+
+  describe "#client=" do
+    it "sets the request's client attribute" do
+      client = OandaAPI::Streaming::Client.new(:practice, "token")
+      streaming_request.client = client
+      expect(streaming_request.client).to eq client
+    end
+
+    it "fails if the value is not an Oanda::Streaming::Client" do
+      expect { streaming_request.client = "" }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "#stop!" do
+    it "sets the stop_requested signal" do
+      expect(streaming_request.stop_requested?).to be false
+      streaming_request.stop!
+      expect(streaming_request.stop_requested?).to be true
+    end
+  end
+
+  describe "#stream" do
+    it "yields all resources returned in the response stream" do
+      events_json = <<-END
+        {"transaction":{"id": 1}}\r\n
+        {"transaction":{"id": 2}}
+      END
+      ids = []
+      stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+      streaming_request.stream { |resource| ids << resource.id }
+      expect(ids).to contain_exactly(1, 2)
+    end
+
+    context "when emit_heartbeats? is false" do
+      it "ignores 'heartbeats' in the response stream" do
+        events_json = <<-END
+          {"heartbeat":{"id" : 0}}\r\n
+          {"transaction":{"id": 1}}\r\n
+          {"heartbeat":{"id" : 0}}\r\n
+          {"transaction":{"id": 2}}\r\n
+          {"heartbeat":{"id" : 0}}
+        END
+        ids =  []
+        stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+        streaming_request.emit_heartbeats = false
+        streaming_request.stream { |resource| ids << resource.id }
+        expect(ids).to contain_exactly(1, 2)
+      end
+    end
+
+    context "when emit_heartbeats? is true" do
+      it "includes 'heartbeats' in the response stream" do
+        events_json = <<-END
+          {"heartbeat":{"id" : 10}}\r\n
+          {"transaction":{"id": 1}}\r\n
+          {"heartbeat":{"id" : 20}}\r\n
+          {"transaction":{"id": 2}}\r\n
+          {"heartbeat":{"id" : 30}}
+        END
+        transactions = []
+        heartbeats = 0
+        stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+        streaming_request.emit_heartbeats = true
+        streaming_request.stream do |resource|
+          if resource.is_a? OandaAPI::Resource::Heartbeat
+            heartbeats += 1
+          else
+            transactions << resource.id
+          end
+        end
+        expect(transactions).to contain_exactly(1, 2)
+        expect(heartbeats).to be 3
+      end
+    end
+
+    context "when a 'disconnect' is received the response stream" do
+      it "raises an OandaAPI::StreamingDisconnect" do
+        events_json = <<-END
+          {"transaction":{"id": 1}}\r\n
+          {"disconnect":{"code":60,"message":"Access Token connection limit exceeded"}}\r\n
+          {"transaction":{"id": 2}}
+        END
+
+        stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+        expect {
+          streaming_request.stream { |resource| resource }
+        }.to raise_error(OandaAPI::StreamingDisconnect, /connection limit exceeded/)
+      end
+    end
+
+    context "when an unknown resource type is received the response stream" do
+      it "raises an OandaAPI::RequestError" do
+        events_json = <<-END
+          {"transaction":{"id": 1}}\r\n
+          {"sponge-bob":{"is": "awesome"}}\r\n
+          {"transaction":{"id": 2}}
+        END
+
+        stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+        expect {
+          streaming_request.stream { |resource| resource }
+        }.to raise_error(OandaAPI::RequestError, /unknown resource/)
+      end
+    end
+
+    it "yields an object that responds to stop! and terminates streaming when called" do
+      events_json = <<-END
+      {"transaction":{"id": 1}}\r\n
+      {"transaction":{"id": 2}}\r\n
+      {"transaction":{"id": 3}}
+      END
+      stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+      ids = []
+      streaming_request.stream do |resource, signaller|
+        ids << resource.id
+        signaller.stop! if ids.size > 1
+      end
+      expect(ids).to contain_exactly(1, 2)
+    end
+
+    context "when the stream contains only heartbeats" do
+      it "terminates streaming when a stop signal is received" do
+        events_json = <<-END
+        {"heartbeat":{"id": 1}}\r\n
+        {"heartbeat":{"id": 2}}\r\n
+        {"heartbeat":{"id": 3}}
+        END
+        stub_request(:any, /\.com/).to_return(body: events_json, status: 200)
+        heartbeats = 0
+        streaming_request.emit_heartbeats = true
+        streaming_request.stream do |_resource, signaller|
+          heartbeats += 1
+          signaller.stop!
+        end
+        expect(heartbeats).to eq 1
+      end
+    end
+  end
+end