Merge pull request #1886 from fog/isolate_data_exchange_formats

Separate XML from Fog::Core::Connection

lib/fog/aws/credential_fetcher.rb

@@ -1,4 +1,5 @@
-require 'fog/core/json'
+require "fog/json"
+
 module Fog
   module AWS
     module CredentialFetcher
@@ -61,4 +62,3 @@ module Fog
     end
   end
 end
-

lib/fog/core.rb

@@ -19,11 +19,9 @@ require 'fog/core/current_machine'
 require 'fog/core/deprecation'
 require 'fog/core/errors'
 require 'fog/core/hmac'
-require 'fog/core/json'
 require 'fog/core/logger'
 require 'fog/core/model'
 require 'fog/core/mock'
-require 'fog/core/parser' # FIXME: would be better to only load when nokogiri is required
 require 'fog/core/provider'
 require 'fog/core/service'
 require 'fog/core/ssh'
@@ -32,6 +30,13 @@ require 'fog/core/time'
 require 'fog/core/timeout'
 require 'fog/core/wait_for'
 
+# data exchange specific (to be extracted and used on a per provider basis)
+require 'fog/xml'
+require 'fog/json'
+
+# deprecation wrappers
+require 'fog/core/deprecated/connection'
+
 # service wrappers
 require 'fog/compute'
 require 'fog/identity'

lib/fog/core/connection.rb

@@ -1,40 +1,73 @@
 module Fog
-  class Connection
+  module Core
 
-    def initialize(url, persistent=false, params={})
-      unless params.has_key?(:debug_response)
-        params[:debug_response] = true
-      end
-      params[:headers] ||= {}
-      params[:headers]['User-Agent'] ||= "fog/#{Fog::VERSION}"
-      @excon = Excon.new(url, params)
-      @persistent = persistent
-    end
-
-    def request(params, &block)
-      unless @persistent
-        reset
-      end
-      unless block_given?
-        if (parser = params.delete(:parser))
-          body = Nokogiri::XML::SAX::PushParser.new(parser)
-          params[:response_block] = lambda { |chunk, remaining, total| body << chunk }
+    # Fog::Core::Connection is a generic class to contain a HTTP link to an API.
+    #
+    # It is intended to be subclassed by providers who can then add their own
+    # modifications such as authentication or response object.
+    #
+    class Connection
+      # Prepares the connection and sets defaults for any future requests.
+      #
+      # @param [String] url The destination URL
+      # @param persistent [Boolean]
+      # @param [Hash] params
+      # @option params [String] :body Default text to be sent over a socket. Only used if :body absent in Connection#request params
+      # @option params [Hash<Symbol, String>] :headers The default headers to supply in a request. Only used if params[:headers] is not supplied to Connection#request
+      # @option params [String] :host The destination host's reachable DNS name or IP, in the form of a String
+      # @option params [String] :path Default path; appears after 'scheme://host:port/'. Only used if params[:path] is not supplied to Connection#request
+      # @option params [Fixnum] :port The port on which to connect, to the destination host
+      # @option params [Hash]   :query Default query; appended to the 'scheme://host:port/path/' in the form of '?key=value'. Will only be used if params[:query] is not supplied to Connection#request
+      # @option params [String] :scheme The protocol; 'https' causes OpenSSL to be used
+      # @option params [String] :proxy Proxy server; e.g. 'http://myproxy.com:8888'
+      # @option params [Fixnum] :retry_limit Set how many times we'll retry a failed request.  (Default 4)
+      # @option params [Class] :instrumentor Responds to #instrument as in ActiveSupport::Notifications
+      # @option params [String] :instrumentor_name Name prefix for #instrument events.  Defaults to 'excon'
+      #
+      def initialize(url, persistent=false, params={})
+        unless params.has_key?(:debug_response)
+          params[:debug_response] = true
         end
+        params[:headers] ||= {}
+        params[:headers]['User-Agent'] ||= "fog/#{Fog::VERSION}"
+        @excon = Excon.new(url, params)
+        @persistent = persistent
       end
 
-      response = @excon.request(params, &block)
-
-      if parser
-        body.finish
-        response.body = parser.response
+      # Makes a request using the connection using Excon
+      #
+      # @param [Hash] params
+      # @option params [String] :body text to be sent over a socket
+      # @option params [Hash<Symbol, String>] :headers The default headers to supply in a request
+      # @option params [String] :host The destination host's reachable DNS name or IP, in the form of a String
+      # @option params [String] :path appears after 'scheme://host:port/'
+      # @option params [Fixnum] :port The port on which to connect, to the destination host
+      # @option params [Hash]   :query appended to the 'scheme://host:port/path/' in the form of '?key=value'
+      # @option params [String] :scheme The protocol; 'https' causes OpenSSL to be used
+      # @option params [Proc] :response_block
+      #
+      # @return [Excon::Response]
+      #
+      # @raise [Excon::Errors::StubNotFound]
+      # @raise [Excon::Errors::Timeout]
+      # @raise [Excon::Errors::SocketError]
+      #
+      def request(params, &block)
+        reset unless @persistent
+        @excon.request(params, &block)
       end
 
-      response
-    end
+      # Make {#request} available even when it has been overidden by a subclass
+      # to allow backwards compatibility.
+      #
+      alias_method :original_request, :request
+      protected :original_request
 
-    def reset
-      @excon.reset
+      # Closes the connection
+      #
+      def reset
+        @excon.reset
+      end
     end
-
   end
 end

lib/fog/core/deprecated/connection.rb

@@ -0,0 +1,24 @@
+require "fog/xml"
+
+module Fog
+
+  # @deprecated Use {Fog::Core::Connection} or {XML::SAXParserConnection} if you
+  #   require the response body to be parsed.
+  #
+  # The Connection class is a wrapper around an instance of Excon::Connection
+  # supporting {#request} and {#reset} only.
+  #
+  # {#request} includes an option to perform SAX parsing for XML APIs.
+  #
+  # @see https://github.com/geemus/excon/blob/master/lib/excon/connection.rb
+  #
+  class Connection < Fog::XML::SAXParserConnection
+    def request(params, &block)
+      if (parser = params.delete(:parser))
+        super(parser, params)
+      else
+        original_request(params)
+      end
+    end
+  end
+end

lib/fog/core/parser.rb

@@ -1,4 +1,4 @@
-require 'nokogiri'
+require "nokogiri"
 
 module Fog
   module Parsers

lib/fog/json.rb

@@ -1,6 +1,18 @@
-require 'multi_json'
+require "multi_json"
 
 module Fog
+
+  # @note Extracting JSON components out of core is a work in progress.
+  #
+  # The {JSON} module includes functionality that is common between APIs using
+  # JSON to send and receive data.
+  #
+  # The intent is to provide common code for provider APIs using JSON but not
+  # require it for those using XML.
+  #
+  # @todo Add +require "fog/json" and/or +include Fog::JSON+ to providers using
+  #   its services
+  #
   module JSON
 
     def self.sanitize(data)
@@ -28,6 +40,5 @@ module Fog
     def self.decode(obj)
       MultiJson.decode(obj)
     end
-
   end
 end

lib/fog/xml.rb

@@ -0,0 +1,21 @@
+require "nokogiri"
+require "fog/core/parser"
+
+module Fog
+
+  # @note Extracting XML components out of core is a work in progress.
+  #
+  # The {XML} module includes functionality that is common between APIs using
+  # XML to send and receive data.
+  #
+  # The intent is to provide common code for provider APIs using XML but not
+  # require it for those using JSON.
+  #
+  # @todo Add +require "fog/xml"+ and/or +include Fog::XML+ to providers using
+  #   its services
+  #
+  module XML
+  end
+end
+
+require "fog/xml/sax_parser_connection"

lib/fog/xml/sax_parser_connection.rb

@@ -0,0 +1,43 @@
+module Fog
+  module XML
+    class SAXParserConnection < Fog::Core::Connection
+
+      # Makes a request using the connection using Excon
+      #
+      # @param [Hash] params
+      # @option params [String] :body text to be sent over a socket
+      # @option params [Hash<Symbol, String>] :headers The default headers to supply in a request
+      # @option params [String] :host The destination host's reachable DNS name or IP, in the form of a String
+      # @option params [String] :path appears after 'scheme://host:port/'
+      # @option params [Fixnum] :port The port on which to connect, to the destination host
+      # @option params [Hash]   :query appended to the 'scheme://host:port/path/' in the form of '?key=value'
+      # @option params [String] :scheme The protocol; 'https' causes OpenSSL to be used
+      # @option params [Proc] :response_block
+      # @option params [Nokogiri::XML::SAX::Document] :parser
+      #
+      # @return [Excon::Response]
+      #
+      # @raise [Excon::Errors::StubNotFound]
+      # @raise [Excon::Errors::Timeout]
+      # @raise [Excon::Errors::SocketError]
+      #
+      def request(parser, params)
+        reset unless @persistent
+
+        # Prepare the SAX parser
+        data_stream = Nokogiri::XML::SAX::PushParser.new(parser)
+        params[:response_block] = lambda do |chunk, remaining, total|
+          data_stream << chunk
+        end
+
+        # Make request which read chunks into parser
+        response = @excon.request(params)
+
+        # Cease parsing and override response.body with parsed data
+        data_stream.finish
+        response.body = parser.response
+        response
+      end
+    end
+  end
+end

tests/core/connection_tests.rb

@@ -0,0 +1,26 @@
+Shindo.tests('Fog::Core::Connection', ['core']) do
+
+  raises(ArgumentError, "raises ArgumentError when no arguments given") do
+    Fog::Core::Connection.new
+  end
+
+  tests('new("http://example.com")') do
+    @instance = Fog::Core::Connection.new("http://example.com")
+    responds_to([:request, :reset])
+
+    tests('user agent').returns("fog/#{Fog::VERSION}") do
+      @instance.instance_variable_get(:@excon).data[:headers]['User-Agent']
+    end
+  end
+
+  tests('new("http://example.com", true)') do
+    Fog::Core::Connection.new("http://example.com", true)
+  end
+
+  tests('new("http://example.com", false, options")') do
+    options = {
+      :debug_response => false
+    }
+    Fog::Core::Connection.new("http://example.com", true, options)
+  end
+end

tests/core/user_agent_tests.rb

@@ -1,6 +0,0 @@
-Shindo.tests('Fog::Connection', 'core') do
-  tests('user_agent').returns("fog/#{Fog::VERSION}") do
-    conn = Fog::Connection.new("http://www.testserviceurl.com", false, {})
-    conn.instance_variable_get(:@excon).data[:headers]['User-Agent']
-  end
-end