odata4 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a9465568c8c8b575d04c9367e8c51b3c6161a8b9
-  data.tar.gz: 1da130b782964c9ccf410e74a6309c78bd13e050
+  metadata.gz: d39ce48da9f2bd4c5e58b4be1e0d5ac4a60c4f3e
+  data.tar.gz: 0428d049a8e814d727fc7796c795fc4fddbe8265
 SHA512:
-  metadata.gz: c2949929b4b43e3fde0b26d845f630d59dfc7d5936717dca0531c11bba7514487c72e889a372863f8be2c2934ff85dee1cd8df9dc67193d145ca0245f42133cf
-  data.tar.gz: a1de80f33ab0719567cabbc948dc645a31363697ee705ba0654cabb31fbaffeb130cb751ed061b55dccf169f977e62689b96d3b6180a4052d1fdd31a10b7b5ca
+  metadata.gz: 6d7a7d71b67e188600e7c7ccce3dd55721a27e3cc3371d790eb2d430f4b045e365d37871cd6dd9629586553e22029b52020c622cb0840ab94a52ef05475eb66d
+  data.tar.gz: 70712da5e1e2e2dfc6b9d244b97cdd95c1fa4f727dac590aea3786e8494efa1f8244f82a65b778a2a824fd7bf16ac43a177e1842017789e7cd681ed28819f9f4

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 0.9.0
+
+* [Breaking] Use Faraday instead of Typhoeus as HTTP connection adapter.
+* [Breaking] Deprecate `Service.open` in favor of using constructor directly.
+
 ## 0.8.2
 
 * [Refactor] Moved `ComplexType` and `EnumType` class into `Schema`, respective property types into `Properties` namespace

data/README.md

@@ -41,16 +41,18 @@ The nice thing about `OData4::Service` is that it automatically registers with t
 To create an `OData4::Service` simply provide the location of a service endpoint to it like this:
 
 ```ruby
-  OData4::Service.open('http://services.odata.org/V4/OData/OData.svc')
+  OData4::Service.new('http://services.odata.org/V4/OData/OData.svc')
 ```
 
 You may also provide an options hash after the URL.
 It is suggested that you supply a name for the service via this hash like so:
 
 ```ruby
-  OData4::Service.open('http://services.odata.org/V4/OData/OData.svc', name: 'ODataDemo')
+  OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', name: 'ODataDemo')
 ```
 
+For more information regarding available options and how to configure a service instance, refer to [Service Configuration](#service-configuration) below.
+
 This one call will setup the service and allow for the discovery of everything the other parts of the OData4 gem need to function.
 The two methods you will want to remember from `OData4::Service` are `#service_url` and `#name`.
 Both of these methods are available on instances and will allow for lookup in the `OData4::ServiceRegistry`, should you need it.
@@ -66,6 +68,112 @@ Both of the above calls would retrieve the same service from the registry.
 At the moment there is no protection against name collisions provided in `OData4::ServiceRegistry`.
 So, looking up services by their service URL is the most exact method, but lookup by name is provided for convenience.
 
+### Service Configuration
+
+#### Metadata File
+
+Typically the metadata file of a service can be quite large.
+You can speed your load time by forcing the service to load the metadata from a file rather than a URL.
+This is only recommended for testing purposes, as the metadata file can change.
+
+```ruby
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', {
+    name: 'ODataDemo',
+    metadata_file: "metadata.xml",
+  })
+```
+
+#### Headers & Authorization
+
+The OData protocol does not deal with authentication and authorization at all, nor does it need to, since [HTTP already provides many different options][http-auth] for this, such as HTTP Basic or token authorization.
+Hence, this gem does not implement any special authentication mechanisms either, and relies on the underlying HTTP library ([Faraday][faraday]) to take care of this.
+
+##### Setting Custom Headers
+
+You can customize request headers with the **:connection** option key.
+This allows you to e.g. set custom headers (such as `Authorization`) that may be required by your service.
+
+```ruby
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', {
+    name: 'ODataDemo',
+    connection: {
+      headers: {
+        "Authorization" => "Bearer #{access_token}"
+      }
+    }
+  })
+```
+
+##### Using Authentication Helpers
+
+You may also set up authorization by directly accessing the underlying `Faraday::Connection` object (as explained in [Advanced Customization](#advanced-connection-customization) below).
+This allows you to make use of Faraday's [authentication helpers][faraday-auth], such as `basic_auth` or `token_auth`.
+
+For instance, if your service requires HTTP basic authentication:
+
+```ruby
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', {
+    name: 'ODataDemo'
+  })
+  service.connection.basic_auth('username', 'password')
+```
+
+You may also use these helpers when passing a block to the constructor (see second example [below](#passing-a-block-to-the-constructor)).
+
+[http-auth]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
+[faraday]: https://github.com/lostisland/faraday
+[faraday-auth]: https://github.com/lostisland/faraday#authentication
+
+#### Advanced Connection Customization
+
+Under the hood, the gem uses the [Faraday][faraday] HTTP library to provide flexible
+integration of various Ruby HTTP backends.
+
+There are several ways to access the underlying `Faraday::Connection`:
+
+##### As a service option
+
+If you already have a `Faraday::Connection` instance that you want the service to use, you can simply pass it to the constructor *instead* of the service URL as first parameter.
+In this case, you'll be setting the service URL on the connection object, as shown below:
+
+```ruby
+  conn = Faraday.new('http://services.odata.org/V4/OData/OData.svc') do |conn|
+    # ... customize connection ...
+  end
+
+  service = OData4::Service.new(conn, name: 'ODataDemo')
+```
+
+##### Passing a block to the constructor
+
+Alternatively, the connection object is also `yield`ed by the constructor, so you may customize it by passing a block argument.
+For instance, if you wanted to use [Typhoeus][typhoeus] as your HTTP library:
+
+```ruby
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', {
+    name: 'ODataDemo'
+  }) do |conn|
+    conn.adapter :typhoeus
+  end
+```
+
+**IMPORTANT**
+
+Please be aware that if you use this method to customize the connection, you must ALWAYS specify an adapter:
+
+```ruby
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', {
+    name: 'ODataDemo'
+  }) do |conn|
+    conn.basic_auth('username', 'password')
+    conn.adapter Faraday.default_adapter
+  end
+```
+
+Otherwise, your requests WILL fail!
+
+[typhoeus]: https://github.com/typhoeus/typhoeus
+
 ### Exploring a Service
 
 Once instantiated, you can request various information about the service, such as the names and types of entity sets it exposes, or the names of the entity types (and custom datatypes) it defines.
@@ -121,56 +229,6 @@ Get a list of enum types
 
 For more examples, refer to [usage_example_specs.rb](spec/odata4/usage_example_specs.rb).
 
-### Authentication
-
-When authenticating with your service you can set parameters to the Typhoeus gem which uses libcurl.
-Use the **:typhoeus** option to set your authentication.
-
-For example using **ntlm** authentication:
-
-```ruby
-  conn = OData4::Service.open('http://services.odata.org/V4/OData/OData.svc', {
-    name: 'ODataDemo',
-    typhoeus: {
-      username: 'username',
-      password: 'password',
-      httpauth: :ntlm
-    }
-  })
-```
-
-For more authentication options see [libcurl][libcurl] or [typhoeus][typhoeus].
-
-[libcurl]: http://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html
-[typhoeus]: https://github.com/typhoeus/typhoeus
-
-### Metadata File
-
-Typically the metadata file of a service can be quite large.
-You can speed your load time by forcing the service to load the metadata from a file rather than a URL.
-This is only recommended for testing purposes, as the metadata file can change.
-
-```ruby
-  conn = OData4::Service.open('http://services.odata.org/V4/OData/OData.svc', {
-      name: 'ODataDemo',
-      metadata_file: "metadata.xml",
-  })
-```
-
-### Headers
-
-You can set the headers with the **:typhoeus** param like so:
-
-```ruby
-  conn = OData4::Service.open('http://services.odata.org/V4/OData/OData.svc', {
-    name: 'ODataDemo',
-    typhoeus: {
-      headers: {
-        "Authorization" => "Bearer #{token}"
-      }
-    }
-  })
-```
 
 ### Entity Sets
 
@@ -179,7 +237,7 @@ Under normal circumstances you should never need to worry about an `OData4::Enti
 For example, to get an `OData4::EntitySet` for the products in the ODataDemo service simply access the entity set through the service like this:
 
 ```ruby
-  service = OData4::Service.open('http://services.odata.org/V4/OData/OData.svc')
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc')
   products = service['ProductsSet'] # => OData4::EntitySet
 ```
 
@@ -305,7 +363,7 @@ Simply add `strict: false` to the service constructor options.
 In this mode, any property validation error will log a warning instead of raising an exception. The corresponding property value will be `nil` (even if the property is declared as not allowing NULL values).
 
 ```ruby
-  service = OData4::Service.open('http://services.odata.org/V4/OData/OData.svc', strict: false)
+  service = OData4::Service.new('http://services.odata.org/V4/OData/OData.svc', strict: false)
   # -- alternatively, for an existing service instance --
   service.options[:strict] = false
 ```

data/lib/odata4.rb

@@ -3,7 +3,8 @@ require 'date'
 require 'time'
 require 'bigdecimal'
 require 'nokogiri'
-require 'typhoeus'
+require 'faraday'
+require 'logger'
 require 'andand'
 require 'json'
 

data/lib/odata4/service.rb

@@ -5,12 +5,14 @@ module OData4
   # Encapsulates the basic details and functionality needed to interact with an
   # OData4 service.
   class Service
+    # The Faraday connection object used by the service to make requests
+    attr_reader :connection
     # The OData4 Service's URL
     attr_reader :service_url
-    # Options to pass around
+    # Service options
     attr_reader :options
 
-    HTTP_TIMEOUT = 20
+    DEFAULT_TIMEOUT = 20
 
     METADATA_TIMEOUTS = [20, 60]
 
@@ -24,24 +26,32 @@ module OData4
     # Opens the service based on the requested URL and adds the service to
     # {OData4::Registry}
     #
-    # @param service_url [String] the URL to the desired OData4 service
+    # @param service_url [String|Faraday::Connection]
+    #   The URL to the desired OData4 service, or a Faraday connection object
     # @param options [Hash] options to pass to the service
     # @return [OData4::Service] an instance of the service
-    def initialize(service_url, options = {})
-      @service_url = service_url
-      @options = default_options.merge(options)
+    def initialize(service_url, options = {}, &block)
+      if service_url.is_a? Faraday::Connection
+        @connection  = service_url
+        @service_url = connection.url_prefix
+      else
+        @service_url = service_url
+        @connection  = Faraday.new(service_url, options[:connection], &block)
+      end
+      @options     = default_options.merge(options)
       OData4::ServiceRegistry.add(self)
       register_custom_types
     end
 
     # Opens the service based on the requested URL and adds the service to
     # {OData4::Registry}
+    # @deprecated Use {Service.new} instead.
     #
     # @param service_url [String] the URL to the desired OData4 service
     # @param options [Hash] options to pass to the service
     # @return [OData4::Service] an instance of the service
-    def self.open(service_url, options = {})
-      Service.new(service_url, options)
+    def self.open(service_url, options = {}, &block)
+      Service.new(service_url, options, &block)
     end
 
     # Returns user supplied name for service, or its URL
@@ -176,14 +186,6 @@ module OData4
       schemas[namespace].properties_for_entity(entity_name)
     end
 
-    # Returns the log level set via initial options, or the
-    # default log level (`Logger::WARN`) if none was specified.
-    # @see Logger
-    # @return [Fixnum|Symbol]
-    def log_level
-      options[:log_level] || Logger::WARN
-    end
-
     # Returns the logger instance used by the service.
     # When Ruby on Rails has been detected, the service will
     # use `Rails.logger`. The log level will NOT be changed.
@@ -191,18 +193,13 @@ module OData4
     # When no Rails has been detected, a default logger will
     # be used that logs to STDOUT with the log level supplied
     # via options, or the default log level if none was given.
-    # @see #log_level
     # @return [Logger]
     def logger
-      @logger ||= lambda do
-        if defined?(Rails)
-          Rails.logger
-        else
-          logger = Logger.new(STDOUT)
-          logger.level = log_level
-          logger
-        end
-      end.call
+      @logger ||= options[:logger] || if defined?(Rails)
+        Rails.logger
+      else
+        default_logger
+      end
     end
 
     # Allows the logger to be set to a custom `Logger` instance.
@@ -215,14 +212,19 @@ module OData4
 
     def default_options
       {
-        typhoeus: {
-          headers: { 'OData-Version' => '4.0' },
-          timeout: HTTP_TIMEOUT
+        request: {
+          timeout: DEFAULT_TIMEOUT
         },
         strict: true # strict property validation
       }
     end
 
+    def default_logger
+      Logger.new(STDOUT).tap do |logger|
+        logger.level = options[:log_level] || Logger::WARN
+      end
+    end
+
     def read_metadata
       # From file, good for debugging
       if options[:metadata_file]

data/lib/odata4/service/request.rb

@@ -18,9 +18,10 @@ module OData4
       def initialize(service, url_chunk, options = {})
         @service = service
         @url_chunk = url_chunk
-        @method = options[:method] || :get
-        @format = options[:format] || :auto
-        @query  = options[:query]
+        @method = options.delete(:method) || :get
+        @format = options.delete(:format) || :auto
+        @query  = options.delete(:query)
+        @options = options
       end
 
       # Return the full request URL (including service base)
@@ -43,38 +44,41 @@ module OData4
 
       # Execute the request
       #
-      # @param additional_options [Hash] options to pass to Typhoeus
+      # @param additional_options [Hash] Request options to pass to Faraday
       # @return [OData4::Service::Response]
       def execute(additional_options = {})
-        options = request_options(additional_options)
-        request = ::Typhoeus::Request.new(url, options)
-        logger.info "Requesting #{method.to_s.upcase} #{url}..."
-        request.run
+        request_options = service.options[:request].merge(additional_options)
 
-        Response.new(service, request.response, query)
+        logger.info "Requesting #{method.to_s.upcase} #{url}..."
+        Response.new(service, query) do
+          connection.run_request(method, url_chunk, nil, headers) do |conn|
+            conn.options.merge! request_options
+          end
+        end
       end
 
       private
 
       attr_reader :url_chunk
 
-      def logger
-        service.logger
+      def connection
+        service.connection
       end
 
-      def request_options(additional_options = {})
-        options = service.options[:typhoeus]
-          .merge({ method: method })
-          .merge(additional_options)
+      def default_headers
+        {
+          'Accept'        => content_type,
+          'Content-Type'  => content_type,
+          'OData-Version' => '4.0'
+        }
+      end
 
-        # Don't overwrite Accept header if already present
-        unless options[:headers]['Accept']
-          options[:headers] = options[:headers].merge({
-            'Accept' => content_type
-          })
-        end
+      def headers
+        default_headers.merge(@options[:headers] || {})
+      end
 
-        options
+      def logger
+        service.logger
       end
     end
   end

data/lib/odata4/service/response.rb

@@ -17,19 +17,19 @@ module OData4
       attr_reader :query
 
       # Create a new response given a service and a raw response.
-      # @param service [OData4::Service]
-      # @param response [Typhoeus::Result]
-      def initialize(service, response, query = nil)
+      # @param service [OData4::Service] The executing service.
+      # @param query [OData4::Query] The related query (optional).
+      # @param
+      def initialize(service, query = nil, &block)
         @service  = service
-        @response = response
         @query    = query
-        check_content_type
-        validate!
+        @timed_out = false
+        execute(&block)
       end
 
       # Returns the HTTP status code.
       def status
-        response.code
+        response.status
       end
 
       # Whether the request was successful.
@@ -66,7 +66,7 @@ module OData4
 
       # Whether the response failed due to a timeout
       def timed_out?
-        response.timed_out?
+        @timed_out
       end
 
       # Iterates over all entities in the response, using
@@ -95,30 +95,39 @@ module OData4
       #
       # @return [self]
       def validate!
-        raise "Bad Request. #{error_message(response)}" if response.code == 400
-        raise "Access Denied" if response.code == 401
-        raise "Forbidden" if response.code == 403
-        raise "Not Found" if [0,404].include?(response.code)
-        raise "Method Not Allowed" if response.code == 405
-        raise "Not Acceptable" if response.code == 406
-        raise "Request Entity Too Large" if response.code == 413
-        raise "Internal Server Error" if response.code == 500
-        raise "Service Unavailable" if response.code == 503
+        raise "Bad Request. #{error_message(response)}" if status == 400
+        raise "Access Denied" if status == 401
+        raise "Forbidden" if status == 403
+        raise "Not Found" if [0,404].include?(status)
+        raise "Method Not Allowed" if status == 405
+        raise "Not Acceptable" if status == 406
+        raise "Request Entity Too Large" if status == 413
+        raise "Internal Server Error" if status == 500
+        raise "Service Unavailable" if status == 503
         self
       end
 
       private
 
-      def logger
-        service.logger
-      end
-
-      def check_content_type
+      def execute(&block)
+        @response = block.call
         logger.debug <<-EOS
           [OData4: #{service.name}] Received response:
             Headers: #{response.headers}
             Body: #{response.body}
         EOS
+        check_content_type
+        validate!
+      rescue Faraday::TimeoutError
+        logger.info "Request timed out."
+        @timed_out = true
+      end
+
+      def logger
+        service.logger
+      end
+
+      def check_content_type
         # Dynamically extend instance with methods for
         # processing the current result type
         if is_atom?