RubyGems - transport - Versions diffs - 1.0.0 - Mend

transport 1.0.0

Files changed (31) hide show

data/LICENSE +20 -0
data/README.rdoc +109 -0
data/Rakefile +50 -0
data/lib/transport.rb +9 -0
data/lib/transport/common.rb +41 -0
data/lib/transport/common/request_builder.rb +43 -0
data/lib/transport/http.rb +43 -0
data/lib/transport/http/formatter.rb +85 -0
data/lib/transport/http/request_builder.rb +73 -0
data/lib/transport/http/request_builder/parameter_serializer.rb +61 -0
data/lib/transport/json.rb +37 -0
data/lib/transport/json/request_builder.rb +56 -0
data/lib/transport/json/response_parser.rb +33 -0
data/lib/transport/spec.rb +10 -0
data/lib/transport/spec/faker.rb +75 -0
data/lib/transport/unexpected_status_code_error.rb +21 -0
data/spec/acceptance/http_spec.rb +20 -0
data/spec/acceptance/json_spec.rb +10 -0
data/spec/lib/transport/common/request_builder_spec.rb +61 -0
data/spec/lib/transport/common_spec.rb +68 -0
data/spec/lib/transport/http/formatter_spec.rb +28 -0
data/spec/lib/transport/http/request_builder/parameter_serializer_spec.rb +18 -0
data/spec/lib/transport/http/request_builder_spec.rb +134 -0
data/spec/lib/transport/http_spec.rb +61 -0
data/spec/lib/transport/json/request_builder_spec.rb +78 -0
data/spec/lib/transport/json/response_parser_spec.rb +52 -0
data/spec/lib/transport/json_spec.rb +58 -0
data/spec/lib/transport/spec/faker_spec.rb +87 -0
data/spec/lib/transport/unexpected_status_code_error_spec.rb +18 -0
data/spec/spec_helper.rb +6 -0
metadata +133 -0

data/LICENSE ADDED Viewed

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Philipp Brüll
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc ADDED Viewed

@@ -0,0 +1,109 @@
+= Transport
+A HTTP/JSON transport layer. Provides a single command interface to perform http/json requests. A spec helper to
+perform request against a fake server is also included.
+== HTTP requests
+To perform a http request the call of a single command is needed.
+  Transport::HTTP.request :get, "http://www.google.com", :expected_status_code => 200
+The method will return a string with the content of Google home page. If another status code is received than the
+expected one, an <tt>Transport::UnexpectedStatusCodeError</tt> will be raised. In that case, the status code can be
+read from the raised error object.
+  begin
+    Transport::HTTP.request :get, "http://www.google.com", :expected_status_code => 200
+  rescue Transport::UnexpectedStatusCodeError => error
+    puts "error code = #{error.status_code}"
+  end
+=== Parameters, headers and the request body
+Parameters and headers can also be passed to the request method.
+  Transport::HTTP.request :get, "http://www.somesite.com",
+    :parameters => { "test" => "test value" },
+    :headers => { "Accept" => "text/html", "Content-Type" => "application/x-www-form-urlencoded" }
+Before performing a GET or DELETE request, the given parameters will be encoded in the request url (e.g.
+<tt>?test=test%20value</tt>). POST and PUT request will transport the encoded parameters in their request body, unless
+a request body is explicitly specified.
+  Transport::HTTP.request :post, "http://www.somesite.com",
+    :headers => { "Accept" => "text/html", "Content-Type" => "text/html" },
+    :body => "<html>some data</html>"
+=== Authentication
+Currently, BASIC authentication is supported for requests. To enable it, simply pass the parameter <tt>auth_type</tt>
+along with <tt>username</tt> and <tt>password</tt> to the request method.
+  Transport::HTTP.request :get, "http://www.somesite.com",
+    :auth_type => :basic, :username => "user", :password => "pass"
+== JSON requests
+A JSON request is basically an extensions of a HTTP request. All options that are possible on HTTP request are also
+possible on JSON requests. But a few differences should be mentioned here.
+* The <tt>Accept</tt> header will be set to <tt>application/json</tt> anyway.
+* If a request body is specified, the <tt>Content-Type</tt> will also be set to <tt>application/json</tt> cause only
+  json data should be transferred.
+* If the option <tt>encode_parameters</tt> is set the true, all parameters will be encoded to json, before encoded to
+  the url. This makes it possible to transfer more complex parameters like arrays and hashes.
+* The response body will also be parsed to json.
+=== Example
+  Transport::JSON.request :get, "http://www.somesite.com/content.json",
+    :auth_type => :basic, :username => "user", :password => "pass",
+    :parameters => { "filter" => { "date" => Date.today, "tags" => [ "gossip", "serious" ] } },
+    :encode_parameters => true
+This will perform an authenticated GET request to the given url and passes the json-encoded parameters.
+== Fake requests
+For test proposes, this gem also comes with the possibility of doing fake requests. If you want to test your code
+against a webservice, but don't want to dependent on a network connection or on the webservice itself - or just want
+to speed up your tests, you can fake the webservice by calling <tt>Transport::Spec::Faker.fake!</tt>.
+  describe "webservice" do
+    before :each do
+      Transport::Spec::Faker.fake! "some_filename.yml"
+    end
+    ...
+  end
+The given filename should point to a YML file that contains an array of all fake requests. The file should look like
+the following example.
+  -- # use a single dash here
+    :http_method: "get"
+    :url:         "http://www.somesite.com/content.json"
+    :response:
+      :code: 200
+      :body:
+        "test": "test value"
+  -- # use a single dash here
+    :http_method: "post"
+    :url:         "http://www.somesite.com"
+    :headers:
+      "Accept": "text/html"
+      "Content-Type": "text/html"
+    :response:
+      :code: 200
+      :body: "<html>test value</html>"
+Once the faker is activated, it will try to fake any request. If your software is trying to do a request that isn't
+defined in the YML file, it will raises a <tt>Transport::Spec::Faker::NoFakeRequestError</tt>.
+== Development
+This project is still experimental and under development. Any bug report and contribution is welcome!

data/Rakefile ADDED Viewed

@@ -0,0 +1,50 @@
+require 'rubygems'
+gem 'rspec'
+require 'rspec'
+require 'rspec/core/rake_task'
+gem 'reek'
+require 'reek/rake/task'
+require 'rake/rdoctask'
+task :default => :spec
+namespace :gem do
+  desc "Builds the gem"
+  task :build do
+    system "gem build *.gemspec && mkdir -p pkg/ && mv *.gem pkg/"
+  end
+  desc "Builds and installs the gem"
+  task :install => :build do
+    system "gem install pkg/"
+  end
+end
+Reek::Rake::Task.new do |task|
+  task.fail_on_error = true
+end
+desc "Generate the rdoc"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.add [ "README.rdoc", "lib/**/*.rb" ]
+  rdoc.main = "README.rdoc"
+end
+desc "Run all specs in spec directory"
+RSpec::Core::RakeTask.new do |task|
+  task.pattern = "spec/lib/**/*_spec.rb"
+end
+namespace :spec do
+  desc "Run all integration specs in spec/acceptance directory"
+  RSpec::Core::RakeTask.new(:acceptance) do |task|
+    task.pattern = "spec/acceptance/**/*_spec.rb"
+  end
+end

data/lib/transport.rb ADDED Viewed

@@ -0,0 +1,9 @@
+module Transport
+  autoload :Common, File.join(File.dirname(__FILE__), "transport", "common")
+  autoload :HTTP, File.join(File.dirname(__FILE__), "transport", "http")
+  autoload :JSON, File.join(File.dirname(__FILE__), "transport", "json")
+  autoload :UnexpectedStatusCodeError, File.join(File.dirname(__FILE__), "transport", "unexpected_status_code_error")
+end

data/lib/transport/common.rb ADDED Viewed

@@ -0,0 +1,41 @@
+module Transport
+  module Common
+    autoload :RequestBuilder, File.join(File.dirname(__FILE__), "common", "request_builder")
+    def self.included(base_class)
+      base_class.class_eval do
+        include InstanceMethods
+        extend ClassMethods
+      end
+    end
+    module InstanceMethods
+      attr_reader :uri
+      attr_reader :request
+      attr_reader :options
+      attr_reader :response
+      def initialize(uri, request, options = { })
+        @uri, @request, @options = uri, request, options
+      end
+    end
+    module ClassMethods
+      def request(http_method, url, options = { })
+        uri, request = self::RequestBuilder.build http_method, url, options
+        transport = new uri, request, options
+        transport.perform
+        transport.response
+      end
+    end
+  end
+end

data/lib/transport/common/request_builder.rb ADDED Viewed

@@ -0,0 +1,43 @@
+require 'uri'
+module Transport
+  module Common
+    module RequestBuilder
+      def self.included(base_class)
+        base_class.class_eval do
+          include InstanceMethods
+          def self.build(*arguments)
+            request_builder = new *arguments
+            request_builder.perform
+            [ request_builder.uri, request_builder.request ]
+          end
+        end
+      end
+      module InstanceMethods
+        HTTP_METHODS_WITH_PARAMETERS = [ :get, :delete ].freeze unless defined?(HTTP_METHODS_WITH_PARAMETERS)
+        HTTP_METHODS_WITH_BODY       = [ :post, :put ].freeze unless defined?(HTTP_METHODS_WITH_BODY)
+        attr_reader :http_method
+        attr_reader :url
+        attr_reader :options
+        attr_reader :uri
+        def initialize(http_method, url, options = { })
+          @http_method, @url, @options = http_method, url, options
+          @uri = URI.parse @url
+        end
+      end
+    end
+  end
+end

data/lib/transport/http.rb ADDED Viewed

@@ -0,0 +1,43 @@
+require 'net/http'
+require File.join(File.dirname(__FILE__), "common")
+module Transport
+  # Common transport layer for http transfers.
+  class HTTP
+    include Common
+    autoload :RequestBuilder, File.join(File.dirname(__FILE__), "http", "request_builder")
+    autoload :Formatter, File.join(File.dirname(__FILE__), "http", "formatter")
+    def perform
+      perform_request
+      log_transport
+      check_status_code
+    end
+    private
+    def perform_request
+      @http_response = Net::HTTP.start(@uri.host, @uri.port) do |connection|
+        connection.request @request
+      end
+      @response = @http_response.body
+    end
+    def log_transport
+      @formatter ||= Formatter.new @options[:logger]
+      @formatter.log_transport @uri, @request, @http_response
+    end
+    def check_status_code
+      expected_status_code = @options[:expected_status_code]
+      return unless expected_status_code
+      response_code = @http_response.code.to_i
+      response_body = @http_response.body
+      raise UnexpectedStatusCodeError.new(response_code, response_body) if expected_status_code.to_i != response_code
+    end
+  end
+end

data/lib/transport/http/formatter.rb ADDED Viewed

@@ -0,0 +1,85 @@
+module Transport
+  # Common transport layer for http transfers.
+  class HTTP
+    # Formatter for the http request and response objects. Used for log output.
+    class Formatter
+      # Request formatter.
+      class Request
+        def initialize(uri, request)
+          @uri, @request = uri, request
+        end
+        def message
+          "transport to #{@uri.host} #{@uri.port}\n" +
+            request
+        end
+        private
+        def request
+          "request: #{@request.class} #{@request.path}\n" +
+            request_headers +
+            request_body
+        end
+        def request_headers
+          message = ""
+          @request.each_capitalized_name do |key|
+            message += "    #{key}: #{@request[key]}\n"
+          end
+          message == "" ? "" : "  headers:\n" + message
+        end
+        def request_body
+          request_body = @request.body
+          request_body ? "  body:\n" + Formatter.intend("    #{request_body}", 4) : ""
+        end
+      end
+      # Response formatter.
+      class Response
+        def initialize(response)
+          @response = response
+        end
+        def message
+          message = "response: #{@response.code}\n"
+          message += Formatter.intend("  #{@response.body}")
+          message
+        end
+      end
+      attr_reader :logger
+      def initialize(logger)
+        @logger = logger
+      end
+      def log_transport(uri, request, response)
+        log Request.new(uri, request).message + "\n" + Response.new(response).message
+      end
+      private
+      def log(message)
+        return unless @logger
+        @logger.info message
+      end
+      def self.intend(message, spaces = 2)
+        message.gsub "\n", "\n" + (" " * spaces)
+      end
+    end
+  end
+end

data/lib/transport/http/request_builder.rb ADDED Viewed

@@ -0,0 +1,73 @@
+require 'uri'
+require 'net/http'
+module Transport
+  # Common transport layer for http transfers.
+  class HTTP
+    # Builder for the http transport layer requests.
+    class RequestBuilder
+      include Common::RequestBuilder
+      autoload :ParameterSerializer, File.join(File.dirname(__FILE__), "request_builder", "parameter_serializer")
+      attr_reader :request
+      def perform
+        initialize_request_class
+        initialize_request_path
+        initialize_request
+        initialize_request_authentication
+        initialize_request_body
+      end
+      private
+      def initialize_request_class
+        request_class_name = @http_method.to_s.capitalize
+        raise NotImplementedError, "the request method #{@http_method} is not implemented" unless Net::HTTP.const_defined?(request_class_name)
+        @request_class = Net::HTTP.const_get request_class_name
+      end
+      def initialize_request_path
+        uri = URI.parse @url
+        generate_query
+        @request_path = uri.path
+        @request_path += "/" if @request_path == ""
+        @request_path += "?" + @query if HTTP_METHODS_WITH_PARAMETERS.include?(@http_method.to_sym) && @query
+      end
+      def initialize_request
+        @request = @request_class.new @request_path, @options[:headers]
+      end
+      def initialize_request_authentication
+        auth_type = @options[:auth_type]
+        return unless auth_type
+        send :"initialize_request_#{auth_type}_authentication"
+      rescue NoMethodError
+        raise NotImplementedError, "the given auth_type [#{auth_type}] is not implemented"
+      end
+      def initialize_request_basic_authentication
+        @request.basic_auth @options[:username], @options[:password]
+      end
+      def initialize_request_body
+        @request.body = (@options.has_key?(:body) ? @options[:body] : generate_query) if HTTP_METHODS_WITH_BODY.include?(@http_method.to_sym)
+      end
+      def generate_query
+        @query ||= begin
+          serializer = ParameterSerializer.new @options[:parameters]
+          serializer.perform
+          serializer.result
+        end
+      end
+    end
+  end
+end