interpol 0.5.0 → 0.6.0

data/Rakefile

@@ -14,11 +14,9 @@ if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby' # MRI only
   desc "Run cane to check quality metrics"
   Cane::RakeTask.new(:quality) do |cane|
     cane.abc_max = 13
-    cane.add_threshold 'coverage/coverage_percent.txt', :==, 100
     cane.style_measure = 100
 
     cane.abc_exclude = %w[
-      Interpol::Configuration#register_default_callbacks
       Interpol::StubApp::Builder#initialize
     ]
 
@@ -26,11 +24,24 @@ if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby' # MRI only
       spec/unit/interpol/sinatra/request_params_parser_spec.rb
     ]
   end
+
+  desc "Checks the spec coverage and fails if it is less than 100%"
+  task :check_coverage do
+    puts "Checking code coverage..."
+    percent = File.read("coverage/coverage_percent.txt").to_f
+
+    if percent < 100
+      raise "Failed to achieve 100% code coverage: #{percent}"
+    else
+      puts "Nice work! Code coverage is still 100%"
+    end
+  end
 else
   task(:quality) { } # no-op
+  task(:check_coverage) { } # no-op
 end
 
-task :default => [:spec, :quality]
+task :default => [:spec, :quality, :check_coverage]
 
 desc "Watch Documentation App Compass Files"
 task :compass_watch do

data/lib/interpol/configuration/built_in_param_parsers.rb

@@ -0,0 +1,86 @@
+define_request_param_parser('integer') do |param|
+  param.string_validation_options 'pattern' => '^\-?\d+$'
+
+  param.parse do |value|
+    begin
+      raise TypeError unless value # On 1.8.7 Integer(nil) does not raise an error
+      Integer(value)
+    rescue TypeError
+      raise ArgumentError, "Could not convert #{value.inspect} to an integer"
+    end
+  end
+end
+
+define_request_param_parser('number') do |param|
+  param.string_validation_options 'pattern' => '^\-?\d+(\.\d+)?$'
+
+  param.parse do |value|
+    begin
+      Float(value)
+    rescue TypeError
+      raise ArgumentError, "Could not convert #{value.inspect} to a float"
+    end
+  end
+end
+
+define_request_param_parser('boolean') do |param|
+  param.string_validation_options 'enum' => %w[ true false ]
+
+  booleans = { 'true'  => true,  true  => true,
+               'false' => false, false => false }
+  param.parse do |value|
+    booleans.fetch(value) do
+      raise ArgumentError, "Could not convert #{value.inspect} to a boolean"
+    end
+  end
+end
+
+define_request_param_parser('null') do |param|
+  param.string_validation_options 'enum' => ['']
+
+  nulls = { '' => nil, nil => nil }
+  param.parse do |value|
+    nulls.fetch(value) do
+      raise ArgumentError, "Could not convert #{value.inspect} to a null"
+    end
+  end
+end
+
+define_request_param_parser('string') do |param|
+  param.parse do |value|
+    unless value.is_a?(String)
+      raise ArgumentError, "#{value.inspect} is not a string"
+    end
+
+    value
+  end
+end
+
+define_request_param_parser('string', 'format' => 'date') do |param|
+  param.parse do |value|
+    unless value =~ /\A\d{4}\-\d{2}\-\d{2}\z/
+      raise ArgumentError, "#{value.inspect} is not in iso8601 format"
+    end
+
+    Date.new(*value.split('-').map(&:to_i))
+  end
+end
+
+define_request_param_parser('string', 'format' => 'date-time') do |param|
+  param.parse &Time.method(:iso8601)
+end
+
+define_request_param_parser('string', 'format' => 'uri') do |param|
+  param.parse do |value|
+    begin
+      URI(value).tap do |uri|
+        unless uri.scheme && uri.host
+          raise ArgumentError, "#{uri.inspect} is not a valid full URI"
+        end
+      end
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, e.message, e.backtrace
+    end
+  end
+end
+

data/lib/interpol/configuration/default_callbacks.rb

@@ -0,0 +1,46 @@
+request_version do
+  raise ConfigurationError, "request_version has not been configured"
+end
+
+response_version do
+  raise ConfigurationError, "response_version has not been configured"
+end
+
+validate_response_if do |env, status, headers, body|
+  headers['Content-Type'].to_s.include?('json') &&
+  status >= 200 && status <= 299 && status != 204 # No Content
+end
+
+validate_request_if do |env|
+  env['CONTENT_TYPE'].to_s.include?('json') &&
+  %w[ POST PUT PATCH ].include?(env.fetch('REQUEST_METHOD'))
+end
+
+on_unavailable_request_version do |env, requested, available|
+  message = "The requested request version is invalid. " +
+            "Requested: #{requested}. " +
+            "Available: #{available}"
+
+  rack_json_response(406, :error => message)
+end
+
+on_unavailable_sinatra_request_version do |requested, available|
+  message = "The requested request version is invalid. " +
+            "Requested: #{requested}. " +
+            "Available: #{available}"
+
+  halt 406, JSON.dump(:error => message)
+end
+
+on_invalid_request_body do |env, error|
+  rack_json_response(400, :error => error.message)
+end
+
+on_invalid_sinatra_request_params do |error|
+  halt 400, JSON.dump(:error => error.message)
+end
+
+select_example_response do |endpoint_def, _|
+  endpoint_def.examples.first
+end
+

data/lib/interpol/configuration.rb

@@ -2,6 +2,7 @@ require 'interpol/endpoint'
 require 'interpol/errors'
 require 'yaml'
 require 'interpol/configuration_ruby_18_extensions'  if RUBY_VERSION.to_f < 1.9
+require 'uri'
 
 module Interpol
   module DefinitionFinder
@@ -40,6 +41,7 @@ module Interpol
       self.endpoint_definition_merge_key_files = []
       self.documentation_title = "API Documentation Provided by Interpol"
       register_default_callbacks
+      register_built_in_param_parsers
       @filter_example_data_blocks = []
 
       yield self if block_given?
@@ -163,6 +165,23 @@ module Interpol
       dup.tap(&block)
     end
 
+    def define_request_param_parser(type, options = {}, &block)
+      ParamParser.new(type, options, &block).tap do |parser|
+        # Use unshift so that new parsers take precedence over older ones.
+        param_parsers[type].unshift parser
+      end
+    end
+
+    def param_parser_for(type, options)
+      match = param_parsers[type].find do |parser|
+        parser.matches_options?(options)
+      end
+
+      return match if match
+
+      raise UnsupportedTypeError.new(type, options)
+    end
+
   private
 
     # 1.9 version
@@ -204,51 +223,70 @@ module Interpol
       @named_example_selectors ||= {}
     end
 
-    def register_default_callbacks
-      request_version do
-        raise ConfigurationError, "request_version has not been configured"
-      end
+    def param_parsers
+      @param_parsers ||= Hash.new { |h, k| h[k] = [] }
+    end
 
-      response_version do
-        raise ConfigurationError, "response_version has not been configured"
-      end
+    def self.instance_eval_args_for(file)
+      filename = File.expand_path("../configuration/#{file}.rb", __FILE__)
+      contents = File.read(filename)
+      [contents, filename, 1]
+    end
 
-      validate_response_if do |env, status, headers, body|
-        headers['Content-Type'].to_s.include?('json') &&
-        status >= 200 && status <= 299 && status != 204 # No Content
-      end
+    BUILT_IN_PARSER_EVAL_ARGS = instance_eval_args_for("built_in_param_parsers")
 
-      validate_request_if do |env|
-        env['CONTENT_TYPE'].to_s.include?('json') &&
-        %w[ POST PUT PATCH ].include?(env.fetch('REQUEST_METHOD'))
-      end
+    def register_built_in_param_parsers
+      instance_eval(*BUILT_IN_PARSER_EVAL_ARGS)
+    end
 
-      on_unavailable_request_version do |env, requested, available|
-        message = "The requested request version is invalid. " +
-                  "Requested: #{requested}. " +
-                  "Available: #{available}"
+    DEFAULT_CALLBACK_EVAL_ARGS = instance_eval_args_for("default_callbacks")
+    def register_default_callbacks
+      instance_eval(*DEFAULT_CALLBACK_EVAL_ARGS)
+    end
+  end
 
-        rack_json_response(406, :error => message)
-      end
+  # Holds the validation/parsing logic for a particular parameter
+  # type (w/ additional options).
+  class ParamParser
+    def initialize(type, options = {})
+      @type = type
+      @options = options
+      yield self
+    end
 
-      on_unavailable_sinatra_request_version do |requested, available|
-        message = "The requested request version is invalid. " +
-                  "Requested: #{requested}. " +
-                  "Available: #{available}"
+    def string_validation_options(options = nil, &block)
+      @string_validation_options_block = block || Proc.new { options }
+    end
 
-        halt 406, JSON.dump(:error => message)
-      end
+    def parse(&block)
+      @parse_block = block
+    end
 
-      on_invalid_request_body do |env, error|
-        rack_json_response(400, :error => error.message)
+    def matches_options?(options)
+      @options.all? do |key, value|
+        options.has_key?(key) && options[key] == value
       end
+    end
+
+    def type_validation_options_for(type, options)
+      return type unless @string_validation_options_block
+      string_options = @string_validation_options_block.call(options)
+      Array(type) + [string_options.merge('type' => 'string')]
+    end
 
-      on_invalid_sinatra_request_params do |error|
-        halt 400, JSON.dump(:error => error.message)
+    def parse_value(value)
+      unless @parse_block
+        raise "No parse callback has been set for param type definition: #{description}"
       end
 
-      select_example_response do |endpoint_def, _|
-        endpoint_def.examples.first
+      @parse_block.call(value)
+    end
+
+    def description
+      @description ||= @type.inspect.tap do |desc|
+        if @options.any?
+          desc << " (with options: #{@options.inspect})"
+        end
       end
     end
   end

data/lib/interpol/dynamic_struct.rb

@@ -25,10 +25,16 @@ module Interpol
         when Array
           object.each { |obj| recursively_freeze(obj) }
         when Hash
-          object.default_proc = DEFAULT_PROC
+          set_default_proc_on(object)
           recursively_freeze(object.values)
       end
     end
+
+    def self.set_default_proc_on(hash)
+      hash.default_proc = DEFAULT_PROC
+    end
   end
 end
 
+require 'interpol/hash_set_default_proc_18' unless {}.respond_to?(:default_proc=)
+

data/lib/interpol/endpoint.rb

@@ -201,14 +201,6 @@ module Interpol
       @example_status_code ||= @status_codes.example_status_code
     end
 
-    def parse_request_params(request_params)
-      request_params_parser.parse(request_params)
-    end
-
-    def request_params_parser
-      @request_params_parser ||= RequestParamsParser.new(self)
-    end
-
   private
 
     def make_schema_strict!(raw_schema, modify_object=true)

data/lib/interpol/errors.rb

@@ -38,5 +38,35 @@ module Interpol
 
   # Raised when an invalid status code is found during validate_codes!
   class StatusCodeMatcherArgumentError < ArgumentError; end
+
+  # Raised when an unsupported parameter type is defined.
+  class UnsupportedTypeError < ArgumentError
+    attr_reader :type, :options
+
+    def initialize(type, options = {})
+      @type = type
+      @options = options
+
+      description = type.inspect
+      description << " (#{options.inspect})" if options.any?
+      super("No param parser can be found for #{description}")
+    end
+  end
+
+  # Raised when the path_params are not part of the endpoint route.
+  class InvalidPathParamsError < ArgumentError
+    attr_reader :invalid_params
+
+    def initialize(*invalid_params)
+      @invalid_params = invalid_params
+      super("The path params #{invalid_params.join(', ')} are not in the route")
+    end
+  end
+
+  # Raised when a parameter value cannot be parsed.
+  CannotBeParsedError = Class.new(ArgumentError)
+
+  # Raised when a params definition is invalid.
+  InvalidParamsDefinitionError = Class.new(ArgumentError)
 end
 

data/lib/interpol/hash_set_default_proc_18.rb

@@ -0,0 +1,9 @@
+module Interpol
+  module DynamicStruct
+    # Hash#default_proc= isn't defined on 1.8; this is the best we can do.
+    def self.set_default_proc_on(hash)
+      hash.replace(Hash.new(&DEFAULT_PROC).merge(hash))
+    end
+  end
+end
+

data/lib/interpol/request_params_parser.rb

@@ -1,6 +1,5 @@
 require 'interpol'
 require 'interpol/dynamic_struct'
-require 'uri'
 require 'interpol/each_with_object' unless Enumerable.method_defined?(:each_with_object)
 
 module Interpol
@@ -20,10 +19,10 @@ module Interpol
   # The parsed params object supports dot-syntax for accessing parameters
   # and will convert values where feasible (e.g. '3' = 3, 'true' => true, etc).
   class RequestParamsParser
-    def initialize(endpoint_definition)
-      @validator = ParamValidator.new(endpoint_definition)
+    def initialize(endpoint_definition, configuration)
+      @validator = ParamValidator.new(endpoint_definition, configuration)
       @validator.validate_path_params_valid_for_route!
-      @converter = ParamConverter.new(@validator.param_definitions)
+      @converter = ParamConverter.new(@validator.param_definitions, configuration)
     end
 
     def parse(params)
@@ -37,8 +36,9 @@ module Interpol
 
     # Private: This takes care of the validation.
     class ParamValidator
-      def initialize(endpoint_definition)
+      def initialize(endpoint_definition, configuration)
         @endpoint_definition = endpoint_definition
+        @configuration = configuration
         @params_schema = build_params_schema
       end
 
@@ -107,26 +107,19 @@ module Interpol
         ].none? { |params| params['additionalProperties'] }
       end
 
-      STRING_EQUIVALENTS = {
-        'string'  => nil,
-        'integer' => { 'type' => 'string', 'pattern' => '^\-?\d+$' },
-        'number'  => { 'type' => 'string', 'pattern' => '^\-?\d+(\.\d+)?$' },
-        'boolean' => { 'type' => 'string', 'enum'    => %w[ true false ] },
-        'null'    => { 'type' => 'string', 'enum'    => [''] }
-      }
-
       def adjusted_schema(schema)
-        types = Array(schema['type'])
-
-        string_equivalents = types.map do |type|
-          STRING_EQUIVALENTS.fetch(type) do
-            unless type.is_a?(Hash) # a nested union type
-              raise UnsupportedTypeError.new(type)
-            end
+        adjusted_types = Array(schema['type']).inject([]) do |type_list, type|
+          type_string, options = if type.is_a?(Hash)
+            [type.fetch('type'), type]
+          else
+            [type, schema]
           end
-        end.compact
 
-        schema.merge('type' => (types + string_equivalents)).tap do |adjusted|
+          @configuration.param_parser_for(type_string, options).
+                         type_validation_options_for([type] + type_list, options)
+        end
+
+        schema.merge('type' => adjusted_types).tap do |adjusted|
           adjusted['required'] = true unless adjusted['optional']
         end
       end
@@ -136,8 +129,9 @@ module Interpol
     class ParamConverter
       attr_reader :param_definitions
 
-      def initialize(param_definitions)
+      def initialize(param_definitions, configuration)
         @param_definitions = param_definitions
+        @configuration = configuration
       end
 
       def convert(params)
@@ -156,10 +150,10 @@ module Interpol
         definition = param_definitions.fetch(name)
 
         Array(definition['type']).each do |type|
-          converter = converter_for(type, definition)
+          parser = parser_for(type, definition)
 
           begin
-            return converter.call(value)
+            return parser.parse_value(value)
           rescue ArgumentError => e
             # Try the next unioned type...
           end
@@ -168,96 +162,14 @@ module Interpol
         raise CannotBeParsedError, "The #{name} #{value.inspect} cannot be parsed"
       end
 
-      BOOLEANS = { 'true'  => true,  true  => true,
-                   'false' => false, false => false }
-      def self.convert_boolean(value)
-        BOOLEANS.fetch(value) do
-          raise ArgumentError, "#{value} is not convertable to a boolean"
-        end
-      end
-
-      NULLS = { '' => nil, nil => nil }
-      def self.convert_null(value)
-        NULLS.fetch(value) do
-          raise ArgumentError, "#{value} is not convertable to null"
-        end
-      end
-
-      def self.convert_date(value)
-        unless value =~ /\A\d{4}\-\d{2}\-\d{2}\z/
-          raise ArgumentError, "Not in iso8601 format"
+      def parser_for(type, options)
+        if type.is_a?(Hash)
+          return parser_for(type.fetch('type'), type)
         end
 
-        Date.new(*value.split('-').map(&:to_i))
-      end
-
-      def self.convert_uri(value)
-        URI(value).tap do |uri|
-          unless uri.scheme && uri.host
-            raise ArgumentError, "Not a valid full URI"
-          end
-        end
-      rescue URI::InvalidURIError => e
-        raise ArgumentError, e.message, e.backtrace
-      end
-
-      CONVERTERS = {
-        'integer' => method(:Integer),
-        'number'  => method(:Float),
-        'boolean' => method(:convert_boolean),
-        'null'    => method(:convert_null)
-      }
-
-      IDENTITY_CONVERTER = lambda { |v| v }
-
-      def converter_for(type, definition)
-        CONVERTERS.fetch(type) do
-          if Hash === type && type['type']
-            converter_for(type['type'], type)
-          elsif type == 'string'
-            string_converter_for(definition)
-          else
-            raise CannotBeParsedError, "#{type} cannot be parsed"
-          end
-        end
-      end
-
-      STRING_CONVERTERS = {
-        'date'      => method(:convert_date),
-        'date-time' => Time.method(:iso8601),
-        'uri'       => method(:convert_uri)
-      }
-
-      def string_converter_for(definition)
-        STRING_CONVERTERS.fetch(definition['format'], IDENTITY_CONVERTER)
+        @configuration.param_parser_for(type, options)
       end
     end
-
-    # Raised when an unsupported parameter type is defined.
-    class UnsupportedTypeError < ArgumentError
-      attr_reader :type
-
-      def initialize(type)
-        @type = type
-        super("#{type} params are not supported")
-      end
-    end
-
-    # Raised when the path_params are not part of the endpoint route.
-    class InvalidPathParamsError < ArgumentError
-      attr_reader :invalid_params
-
-      def initialize(*invalid_params)
-        @invalid_params = invalid_params
-        super("The path params #{invalid_params.join(', ')} are not in the route")
-      end
-    end
-
-    # Raised when a parameter value cannot be parsed.
-    CannotBeParsedError = Class.new(ArgumentError)
-
-    # Raised when a params definition is invalid.
-    InvalidParamsDefinitionError = Class.new(ArgumentError)
   end
 end
 

data/lib/interpol/sinatra/request_params_parser.rb

@@ -27,7 +27,13 @@ module Interpol
       # receive the app instance as an argument here.
       def validate_and_parse_params(app)
         return unless app.settings.parse_params?
-        SingleRequestParamsParser.parse_params(config, app)
+        SingleRequestParamsParser.parse_params(config, app, endpoint_parsers)
+      end
+
+      def endpoint_parsers
+        @endpoint_parsers ||= Hash.new do |hash, endpoint|
+          hash[endpoint] = Interpol::RequestParamsParser.new(endpoint, @config)
+        end
       end
 
     private
@@ -57,17 +63,18 @@ module Interpol
 
       # Handles finding parsing request params for a single request.
       class SingleRequestParamsParser
-        def self.parse_params(config, app)
-          new(config, app).parse_params
+        def self.parse_params(config, app, endpoint_parsers)
+          new(config, app, endpoint_parsers).parse_params
         end
 
-        def initialize(config, app)
+        def initialize(config, app, endpoint_parsers)
           @config = config
           @app = app
+          @endpoint_parsers = endpoint_parsers
         end
 
         def parse_params
-          endpoint_definition.parse_request_params(params_to_parse)
+          @endpoint_parsers[endpoint_definition].parse(params_to_parse)
         rescue Interpol::ValidationError => error
           request_params_invalid(error)
         end

data/lib/interpol/test_helper.rb

@@ -9,7 +9,7 @@ module Interpol
         config = Configuration.default.customized_duplicate(&block)
 
         each_definition_from(config.endpoints) do |endpoint, definition|
-          define_definition_test(endpoint, definition)
+          define_definition_test(config, endpoint, definition)
 
           each_example_from(definition) do |example, example_index|
             define_example_test(config, endpoint, definition, example, example_index)
@@ -40,13 +40,13 @@ module Interpol
         define_test(description) { example.validate! }
       end
 
-      def define_definition_test(endpoint, definition)
+      def define_definition_test(config, endpoint, definition)
         return unless definition.request?
 
         description = "#{endpoint.name} (v #{definition.version}) request " +
                       "definition has valid params schema"
         define_test description do
-          definition.request_params_parser # it will raise an error if it is invalid
+          RequestParamsParser.new(definition, config) # it will raise an error if it is invalid
         end
       end
 

data/lib/interpol/version.rb

@@ -1,3 +1,3 @@
 module Interpol
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interpol
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-19 00:00:00.000000000 Z
+date: 2012-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -199,9 +199,10 @@ files:
 - LICENSE
 - Gemfile
 - Rakefile
+- lib/interpol/configuration/built_in_param_parsers.rb
+- lib/interpol/configuration/default_callbacks.rb
 - lib/interpol/configuration.rb
 - lib/interpol/configuration_ruby_18_extensions.rb
-- lib/interpol/define_singleton_method.rb
 - lib/interpol/documentation.rb
 - lib/interpol/documentation_app/config.rb
 - lib/interpol/documentation_app.rb
@@ -209,6 +210,7 @@ files:
 - lib/interpol/each_with_object.rb
 - lib/interpol/endpoint.rb
 - lib/interpol/errors.rb
+- lib/interpol/hash_set_default_proc_18.rb
 - lib/interpol/request_body_validator.rb
 - lib/interpol/request_params_parser.rb
 - lib/interpol/response_schema_validator.rb

data/lib/interpol/define_singleton_method.rb

@@ -1,10 +0,0 @@
-module Interpol
-  # 1.9 has Object#define_singleton_method but 1.8 does not.
-  # This provides 1.8 compatibility for the places we need it.
-  module DefineSingletonMethod
-    def define_singleton_method(name, &block)
-      (class << self; self; end).send(:define_method, name, &block)
-    end
-  end
-end
-