cp-sparrow 0.0.12 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8c0adb0e16e2c7a97a4b7c4d6db2506cd3c3f91e
-  data.tar.gz: 7e58676322eb7f4981618f359ab3a2fcef609bd4
+  metadata.gz: d21e1f781a7f5f4a27d6d8c286cd46d9af31cba4
+  data.tar.gz: 838ed5f0629f44eb18c8041c1dcaf3d5048b1630
 SHA512:
-  metadata.gz: e653bf471ed0d7d59ce627d1b26dd219b9807bf42e52663af3a3a4f884ea53c3a1c6472fdeb02cda302666ebdb2a9d293cbcdd0195d6f163b8581f1f38cec34c
-  data.tar.gz: a4542efb1cd4984760480db9b200bc1e6da846bbfde61b44294715c83ae3d625e486be14bef7bf01c9ccf4fa49daa6c0c9d91a4de6d6858e724e59e5094c2e0b
+  metadata.gz: 99f670f75b1a3dc078130af3d946738f80705f1c79e26922afbbcba0921aecaa1c38bc7edd1253fb3f0a07fbad8c9635f5d6a7e332a407b4109d8b122a59c301
+  data.tar.gz: cd0a34026665ddfd21c075a05af4839b5f1995cc0d45d70009a205329a2862dd8eb752b243f5fa6c1937b2e973245a3130a2d2c33d25ced0bccbef71761b41df

data/.gitignore

@@ -20,4 +20,5 @@ test/tmp
 test/version_tmp
 tmp
 .idea
-.project
+.project
+hoogfile.yml

data/.ruby-version

@@ -1 +1 @@
-2.1.5
+2.2

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Daniel Schmidt
+Copyright (c) 2014 gateprotect GmbH
 
 MIT License
 

data/README.md

@@ -25,7 +25,8 @@ If you're using Rails, that's it. You haven't to do anything more. If you're not
 ```rb
 require 'sparrow'
 
-use Sparrow::Middleware
+use Sparrow::RequestMiddleware
+use Sparrow::ResponseMiddleware
 ```
 
 ## Configuration
@@ -43,18 +44,100 @@ Sparrow.configure do |config|
 end
 ```
 
-There are several options available
-
-| Option | Example | Meaning |
-|---------|---------|----------------------|
-| excluded_routes | see above | An Array of Strings and/or Regexps defining which paths should not be touched by the middleware. The entries should matchs paths for your application. They should *not* start with a leading slash. |
-| default_json_request_key_transformation_strategy | "underscore" | Defines how the middleware should treat incoming parameters via Request. Which means how they get tranformed, i.e. defining _underscore_ here means that incoming parameters get underscore. Possible values are _underscore_ and _camelize_ |
-| default_json_response_key_transformation_strategy | "camelize" | Same as *default_json_request_key_transformation_strategy, but for responses. I.e. this defines to which format the keys get transformed when the response gets sent.
-| json_request_format_header| "request-json-format" | Defines the HTTP Header key which sets the request transformation strategy as in default_json_request_key_transformation_strategy*. This definition has higher priority than the default definition. Any valid HTTP Header String value is possible. Defaults to 'request-json-format' |
-| json_response_format_header| "response-json-format" | Same as *json_request_format_header*, but for the response handling. Defaults to 'response-json-format' |
-| camelize_ignore_uppercase_keys | `true` | A boolean that indicates to not camelize keys that are all Uppercase, like CountryCodes "EN" ... |
-| allowed_content_types |`['application/json', 'text/x-json']` | A list of HTTP content types upon which the middleware shall trigger and possibly start  conversion. Defaults to `['application/json', 'application/x-www-form-urlencoded', 'text/x-json']`. If `nil` is present in the list, requests/responses with *no* Content-Type header will be processed as well. Possible values can also be the start of the content-type-header like ```application/``` which matches everything which starts with ```application/``` like ```application/json```  |
-| allowed_accepts | `['application/json', 'text/x-json']` | Same as **allowed_content_types**, but reacts to the HTTP Accept Header. Applies to the same possible options, behavior. Defaults to the same set of MIME types, but also includes `nil` by default, which ignores checking the Accept header in default configuration |
+Options may be:
+
+### excluded_routes
+
+> `Array(String|Regexp)`. Default: `[]`
+
+An Array of Strings and/or Regexps defining which paths should not be touched by the middleware. The entries should matchs paths for your application. They should *not* start with a leading slash.
+
+Example:
+`config.excluded_routes = ['api/model/certificates']`
+
+
+### default_json_request_key_transformation_strategy
+
+> `String`. Default: `camelize`
+
+Defines how the middleware should treat incoming parameters via Request. Which means how they get tranformed, i.e. defining _underscore_ here means that incoming parameters get underscore. Possible values are _underscore_ and _camelize_
+
+Example:
+`config.default_json_request_key_transformation_strategy = "underscore"`
+
+### default_json_response_key_transformation_strategy
+
+> `String`. Default: `camelize`
+
+Same as **default_json_request_key_transformation_strategy**, but for responses. I.e. this defines to which format the keys get transformed when the response gets sent.
+
+Example:
+`config.default_json_response_key_transformation_strategy = "camelize"`
+
+### json_request_format_header
+
+> `String`. Default: `request-json-format`
+
+Defines the HTTP Header key which sets the request transformation strategy as in default_json_request_key_transformation_strategy*. This definition has higher priority than the default definition. Any valid HTTP Header String value is possible. Defaults to `request-json-format`.
+
+Example:
+> `config.json_request_format_header = "request-json-format"`
+
+
+### json_response_format_header
+
+> `String`. Default: `response-json-format`
+
+Same as **json_request_format_header**, but for the response handling. Defaults to `response-json-format`
+
+Example:
+`config.json_response_format_header = "response-json-format"`
+
+### camelize_ignore_uppercase_keys
+
+> `Boolean`. Default: `true`
+
+A boolean that indicates to not camelize keys that are all Uppercase, like CountryCodes "EN", etc.
+
+Example:
+`config.camelize_ignore_uppercase_keys = true `
+
+### allowed_content_types
+
+> `Array(String)`. Default: `%w[application/json application/x-www-form-urlencoded text/x-json]`
+
+A list of HTTP content types upon which the middleware shall trigger and possibly start  conversion. Defaults to `['application/json', 'application/x-www-form-urlencoded', 'text/x-json']`. If `nil` is present in the list, requests/responses with *no* Content-Type header will be processed as well. Possible values can also be the start of the content-type-header like ```application/``` which matches everything that starts with ```application/``` like ```application/json```
+
+Example:
+`config.allowed_content_types = ['application/json', 'text/x-json']`
+
+### allowed_accepts
+
+> `Array(String)`. Default: `['application/json', 'application/x-www-form-urlencoded', 'text/x-json', nil]`
+
+Same as [allowed_content_types], but reacts to the HTTP Accept Header. Applies to the same possible options, behavior. Defaults to the same set of MIME types, but also includes `nil` by default, which ignores checking the Accept header in default configuration
+
+Example:
+`config.allowed_accepts = ['application/json', 'text/x-json']`
+
+### enable_logging
+
+> `Boolean`. Default: `false`
+
+Determines logging while the middleware is active. Primary output is which conversion strategy gets chosen upon which request/response.
+
+Example:
+`config.enable_logging = true`
+
+### camelize_strategy
+
+> `Symbol`. Default: `:lower`
+
+Defines which strategy to use when camelizing keys. Possible options are `:lower` and `:upper`, which tells the middleware to 
+start camelized keys with an uppercased character or with a lowercased character.
+
+Example:
+`config.camelize_strategy = :lower`
 
 ## Tests
 

data/lib/sparrow.rb

@@ -1,25 +1,42 @@
-require 'active_support/version'
+require 'sparrow/dependencies'
 require 'sparrow/version'
 require 'sparrow/configuration'
 require 'sparrow/route_parser'
+require 'sparrow/transformable'
+require 'sparrow/strategies'
+require 'sparrow/http_message'
+require 'sparrow/request_http_message'
+require 'sparrow/response_http_message'
+require 'sparrow/steward'
+require 'sparrow/response_steward'
+require 'sparrow/middleware'
 require 'sparrow/request_middleware'
 require 'sparrow/response_middleware'
-require 'sparrow/strategies/json_format_strategies/rack_body'
-require 'sparrow/strategies/json_format_strategies/array_strategy'
+require 'sparrow/logger'
 require 'sparrow/railtie' if defined?(Rails)
 
 module Sparrow
   class << self
+    # @yield [Configuration] configuration
     def configure
       yield configuration
     end
 
+    # @return [Configuration] the configuration
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # resets the configuration values to their defaults, i.e.
+    # reinitializes the Configuration object without any arguments
+    # @return [Configuration] the (new initial) configuration
     def reset_configuration
-      @configuration = nil
+      @configuration = Configuration.new
+    end
+
+    # @return [Logger] the middleware's logger
+    def logger
+      @logger ||= Logger.new(configuration.enable_logging)
     end
   end
 end

data/lib/sparrow/configuration.rb

@@ -1,4 +1,6 @@
 module Sparrow
+  # Middleware configuration store
+  # see {https://github.com/GateprotectGmbH/sparrow#configuration}
   class Configuration
     attr_accessor :json_request_format_header,
                   :json_response_format_header,
@@ -7,9 +9,15 @@ module Sparrow
                   :default_json_response_key_transformation_strategy,
                   :camelize_ignore_uppercase_keys,
                   :allowed_content_types,
-                  :allowed_accepts
+                  :allowed_accepts,
+                  :enable_logging,
+                  :ignored_response_codes,
+                  :camelize_strategy
 
+    ##
+    # Initializes a new Configuration with default parameters
     def initialize
+      @enable_logging                                    = false
       @json_request_format_header                        = 'request-json-format'
       @json_response_format_header                       = 'response-json-format'
       @excluded_routes                                   = []
@@ -22,13 +30,26 @@ module Sparrow
         text/x-json
       ]
 
-      @allowed_accepts = @allowed_content_types + [nil]
+      @allowed_accepts        = @allowed_content_types + [nil]
+      @ignored_response_codes = [404] + (500..511).to_a
+      @camelize_strategy      = :lower
     end
 
+    ##
+    # @param type [String] the http message type.
+    #   Must be either 'request' or 'response'.
+    # @return [String] the configuration value for the json_format_header for
+    #   the given http message type
     def json_format_header(type)
       public_send("json_#{type}_format_header")
     end
 
+    ##
+    # the default json_key_transformation_strategy option for the given
+    # http message type
+    # @param type [String] http message type. Must be either 'request' or
+    #   'response'
+    # @return [String] the configuration option value
     def default_json_key_transformation_strategy(type)
       public_send("default_json_#{type}_key_transformation_strategy")
     end

data/lib/sparrow/core_ext/hash.rb

@@ -1,4 +1,6 @@
 class Hash
+  # Defines deep_transform_keys as available in ActiveSupport >= 4.0.2.
+  # See {http://apidock.com/rails/v4.2.1/Hash/deep_transform_keys}
   def deep_transform_keys(&block)
     deep_transform_in_object(self, &block)
   end

data/lib/sparrow/dependencies.rb

@@ -0,0 +1,15 @@
+require 'active_support/core_ext/object'
+require 'active_support/core_ext/string'
+require 'active_support/version'
+
+if ActiveSupport::VERSION::STRING.match(/3\.\d+\.\d+/)
+  require 'sparrow/core_ext/hash'
+  require 'active_support/core_ext/object/to_param'
+  require 'active_support/core_ext/object/to_query'
+end
+
+unless defined?(Rails)
+  require 'active_support/core_ext/logger'
+end
+
+require 'singleton'

data/lib/sparrow/http_message.rb

@@ -0,0 +1,103 @@
+module Sparrow
+  ##
+  # Wrapper class for either a ::ActiveDispatch::Request or ::Rack::Request
+  # instance for the given rack environment.
+  # The wrapped class is determined based on the presence of the Rails constant.
+  # @abstract RequestHttpMessage and ResponseHttpMessage should be used in
+  #   practice
+  class HttpMessage
+    # The rack environment hash key that determines if it is a form hash request
+    FORM_HASH_KEY  = 'rack.request.form_hash'
+    # The rack environment hash key to access the input/output
+    RACK_INPUT_KEY = 'rack.input'
+
+    ##
+    # @return [Hash] the Rack environment
+    # @see #initialize
+    attr_reader :env
+
+    ##
+    # Initializes the HttpMessage
+    # @param [Hash] env The Rack environment
+    def initialize(env)
+      @env = env
+    end
+
+    ##
+    # Depending on the environment this attribute may either be a
+    # [::ActionDispatch::Request], when running in a Rails environment,
+    # or a [::Rack::Request] otherwise
+    # Encapsulates the Rack env.
+    # @see #env
+    # @return [Object]
+    def request
+      @request ||= request_class.new(env)
+    end
+
+    # @return [Boolean] true any values is insides the FORM_HASH_KEY of the
+    #   rack environment
+    # @see ::FORM_HASH_KEY
+    # @see #env
+    def form_hash?
+      env[FORM_HASH_KEY].present?
+    end
+
+    # Requested path within this HTTP message
+    # @return [String] the path
+    def path
+      http_header(:path_info)
+    end
+
+    ##
+    # The HTTP Accept Header field
+    # @return String the HTTP Accept Header value
+    def accept
+      http_header(:accept)
+    end
+
+    ##
+    # The HTTP Content Type Field
+    # @return String the HTTP Content-Type Header value
+    def content_type
+      http_header(:content_type)
+    end
+
+    ##
+    # Delegates all unknown method calls to the wrapped request
+    # @see #request
+    def method_missing(method_name, *args)
+      request.public_send(method_name, *args)
+    end
+
+    private
+
+    def request_class
+      if defined?(Rails)
+        ::ActionDispatch::Request
+      else
+        ::Rack::Request
+      end
+    end
+
+    ##
+    # Make sure to use any appropriate format of common HTTP Header key syntax
+    # for the given key
+    def http_header(key)
+      key        = key.to_s
+      header_key = [
+          key,
+          key.upcase,
+          key.upcase.dasherize,
+          key.humanize,
+          key.dasherize,
+          key.parameterize,
+          key.underscore.split('_').map(&:humanize).join('-')
+      ].detect do |transformed_key|
+        headers_hash[transformed_key]
+      end
+
+      return nil unless header_key
+      headers_hash[header_key].to_s.split(';').first
+    end
+  end
+end

data/lib/sparrow/logger.rb

@@ -0,0 +1,53 @@
+module Sparrow
+  ##
+  # Simple Logger class to handle behavior's in Rails and Rack environment
+  # without the need to depend on an a "real" Logger to be available under the
+  # hood.
+  #
+  # If the middleware is running in a Rails environment
+  # (i.e. the Rails-constant is defined), is will delegate all its method calls
+  # to the Rails logger.
+  # Otherwise a simple log to STDOUT will get triggered using the method name as
+  # log level and the argument as message.
+  #
+  # Examples:
+  #
+  #   Sparrow::Logger.debug('this is a debug message')
+  #
+  # when in a Rails env equals
+  #
+  #   Rails.logger.debug('this is a debug message')
+  #
+  # when not in a Rails environment the same call equals
+  #
+  #   ActiveSupport::Logger.debug("this is a debug message")
+  class Logger
+    ##
+    # @return [Boolean] logging enabled
+    attr_accessor :enabled
+    alias_method :enabled?, :enabled
+
+    ##
+    # Wrapped Logger class
+    # the Rails logger or a plain ActiveSupport::Logger instance using STDOUT
+    attr_reader :logger
+
+    # Initialize the Logger
+    # Enables the logging only if +enabled+ is truthy.
+    # Otherwise the logger will do nothing at all.
+    #
+    # @param [Boolean] enabled logging enabled
+    def initialize(enabled)
+      self.enabled = enabled
+      @logger = if defined?(Rails) then
+                  Rails.logger
+                else
+                  ::Logger.new(STDOUT)
+                end
+    end
+
+    def method_missing(method_name, *args)
+      logger.public_send(method_name, *args) if enabled?
+    end
+  end
+end

data/lib/sparrow/middleware.rb

@@ -1,88 +1,69 @@
-require 'active_support/core_ext/object/blank'
-require 'sparrow/strategies/form_hash'
-require 'sparrow/strategies/raw_input'
-require 'sparrow/strategies/ignore'
-
 module Sparrow
+  ##
+  # Parent middleware class for both Requests and Responses.
+  # Provides common accessors, but does not modify the http message.
   class Middleware
-    attr_reader :app, :body, :status, :headers
-
+    # @return [Object] the parent Rack application in the stack.
+    attr_reader :app
+    # @return [Array<String>] the rack body after the middleware call
+    attr_reader :body
+    # @return [Hash<String, String>] the HTTP Headers after the middleware call
+    attr_reader :headers
+    # @return [Integer] the HTTP status after the middleware call
+    attr_reader :status
+    # @return [Array<Integer>] List of ignored HTTP response codes
+    # @see Configuration#ignored_response_codes
+    attr_reader :ignored_response_codes
+
+
+    ##
+    # Creates a new Middleware object
+    # @param [#call] app the Rack application as defined by. Any object that
+    #   responds to #call as defined in {https://rack.github.io/}.
     def initialize(app)
-      @app = app
+      @app                    = app
+      @ignored_response_codes = ignored_response_codes
     end
 
+    # @return [Array] The Rack tuple of status, headers and body
+    # as defined by {https://rack.github.io/}
+    # Does nothing by default.
     def call(env)
       @last_env                = env
       @status, @headers, @body = @app.call(convert(env))
     end
 
+    # Converts the Rack environment
+    # Does nothing.
+    # @param [Hash] env the rack env
+    # @return [Hash] the rack env
     def convert(env)
       env
     end
 
     private
 
-    def strategy
-      if is_processable?
-        Rails.logger.debug 'Choosing strategy RawInput' if defined? Rails
-        Strategies::RawInput
-      else
-        Rails.logger.debug 'Choosing strategy Ignore' if defined? Rails
-        Strategies::Ignore
-      end
-    end
-
-    def is_processable?
-      accepted_content_type? && accepted_accept_header? && includes_route?
+    def steward
+      Steward.new(http_message,
+                  allowed_content_types:  Sparrow.configuration.allowed_content_types,
+                  allowed_accepts:        Sparrow.configuration.allowed_accepts,
+                  excluded_routes:        Sparrow.configuration.excluded_routes,
+                  ignored_response_codes: Sparrow.configuration.ignored_response_codes)
     end
 
-    def includes_route?
-      path = request.path || last_env['PATH_INFO']
-      RouteParser.new.allow?(path)
-    end
-
-    def accepted_content_type?
-      content_type_equals?(content_type) || content_type_matches?(content_type)
-    end
-
-    def accepted_accept_header?
-      allowed_accepts = Sparrow.configuration.allowed_accepts
-      accept_header = last_env['ACCEPT'] || last_env['Accept']
-
-      allowed_accepts.include?(nil) || accept_type_matches?(allowed_accepts, accept_header)
+    def strategy
+      strategy = if steward.has_processable_http_message?
+                   Strategies::RawInput
+                 else
+                   Strategies::Ignore
+                 end
+      
+      Sparrow.logger.debug("#{self.class.name} choosing strategy #{strategy.name}")
+      strategy
     end
 
     def last_env
       @last_env || {}
     end
-
-    def request
-      request_class = if defined?(Rails) then
-                        ActionDispatch::Request
-                      else
-                        Rack::Request
-                      end
-
-      request_class.new(last_env)
-    end
-
-    def content_type_equals?(type)
-      Sparrow.configuration.allowed_content_types.include?(type)
-    end
-
-    def content_type_matches?(type)
-      matches = Sparrow.configuration.allowed_content_types.map do |acceptable_content_type|
-        (acceptable_content_type && type.to_s.starts_with?(acceptable_content_type.to_s))
-      end
-
-      matches.any?
-    end
-
-    def accept_type_matches?(accepted_headers, type)
-      accepted_headers.detect do |accept|
-        type.include?(accept)
-      end
-    end
   end
 end
-