interpol 0.3.6 → 0.4.0

data/README.md

@@ -25,6 +25,8 @@ definitions:
 * `Interpol::Sinatra::RequestParamsParser` validates and parses
   a sinatra `params` hash based on your endpoint params schema
   definitions.
+* `Interpol::RequestBodyValidator` is a rack middleware that validates
+  and parses request bodies based on your schema definitions.
 
 You can use any of these tools individually or some combination of all
 of them.
@@ -145,22 +147,30 @@ Interpol.default_configuration do |config|
   # Needed by all tools.
   config.endpoint_definition_files = Dir["config/endpoints/*.yml"]
 
-  # Determines which versioned endpoint definition Interpol uses
+  # Determines which versioned response endpoint definition Interpol uses
   # for a request. You can also use a block form, which yields
   # the rack env hash and the endpoint object as arguments.
   # This is useful when you need to extract the version from a
   # request header (e.g. Accept) or from the request URI.
   #
-  # Needed by Interpol::StubApp, Interpol::ResponseSchemaValidator
-  # and Interpol::Sinatra::RequestParamsParser.
-  config.api_version '1.0'
+  # Needed by Interpol::StubApp and Interpol::ResponseSchemaValidator.
+  config.response_version '1.0'
+
+  # Determines which versioned response endpoint definition Interpol uses
+  # for a request. You can also use a block form, which yields
+  # the rack env hash and the endpoint object as arguments.
+  # This is useful when you need to extract the version from a
+  # request header (e.g. Content-Type) or from the request URI.
+  #
+  # Needed by Interpol::Sinatra::RequestParamsParser.
+  config.request_version '1.0'
 
   # Determines the stub app response when the requested version is not
   # available. This block will be eval'd in the context of a
   # sinatra application, so you can use sinatra helpers like `halt` here.
   #
-  # Needed by Interpol::StubApp and Interpol::Sinatra::RequestParamsParser.
-  config.on_unavailable_request_version do |requested_version, available_versions|
+  # Used by Interpol::StubApp and Interpol::Sinatra::RequestParamsParser.
+  config.on_unavailable_sinatra_request_version do |requested_version, available_versions|
     message = JSON.dump(
       "message" => "Not Acceptable",
       "requested_version" => requested_version,
@@ -170,18 +180,33 @@ Interpol.default_configuration do |config|
     halt 406, message
   end
 
+  # Determines the response when the requested version is not available.
+  #
+  # Used by Interpol::RequestBodyValidator.
+  config.on_unavailable_request_version do |env, requested_version, available_versions|
+    [406, { 'Content-Type' => 'text/plain' }, ['Wrong Version!']]
+  end
+
   # Determines which responses will be validated against the endpoint
   # definition when you use Interpol::ResponseSchemaValidator. The
   # validation is meant to run against the "happy path" response.
   # For responses like "404 Not Found", you probably don't want any
-  # validation performed. The default validate_if hook will cause
+  # validation performed. The default validate_response_if hook will cause
   # validation to run against any 2xx response except 204 ("No Content").
   #
   # Used by Interpol::ResponseSchemaValidator.
-  config.validate_if do |env, status, headers, body|
+  config.validate_response_if do |env, status, headers, body|
     headers['Content-Type'] == my_custom_mime_type
   end
 
+  # Determines which request bodies to validate.
+  #
+  # Used by Interpol::RequestBodyValidator.
+  config.validate_request_if do |env|
+    env.fetch('CONTENT_TYPE').to_s.include?('json') &&
+    %w[ POST PUT ].include?(env.fetch('REQUEST_METHOD'))
+  end
+
   # Determines how Interpol::ResponseSchemaValidator handles
   # invalid data. By default it will raise an error, but you can
   # make it print a warning instead.
@@ -216,6 +241,14 @@ Interpol.default_configuration do |config|
   config.on_invalid_sinatra_request_params do |error|
     halt 400, JSON.dump(:error => error.message)
   end
+
+  # Determines how to respond when the request body is invalid
+  # based on your schema definition.
+  #
+  # Used by Interpol::RequestBodyValidator.
+  config.on_invalid_request_body do |env, error|
+    [400, { 'Content-Type' => 'text/plain' }, [error.message]]
+  end
 end
 
 ```
@@ -275,7 +308,7 @@ require 'interpol/stub_app'
 # config or if you have not set a default config.
 stub_app = Interpol::StubApp.build do |app|
   app.endpoint_definition_files = Dir["config/endpoints_definitions/*.yml"]
-  app.api_version do |env|
+  app.response_version do |env|
     RequestVersion.extract_from(env['HTTP_ACCEPT'])
   end
 end
@@ -300,7 +333,7 @@ unless ENV['RACK_ENV'] == 'production'
   # config or if you have not set a default config.
   use Interpol::ResponseSchemaValidator do |config|
     config.endpoint_definition_files = Dir["config/endpoints_definitions/*.yml"]
-    config.api_version do |env|
+    config.response_version do |env|
       RequestVersion.extract_from(env['HTTP_ACCEPT'])
     end
   end
@@ -384,6 +417,38 @@ class MySinatraApp < Sinatra::Base
 end
 ```
 
+### Interpol::RequestBodyValidator
+
+This rack middleware validates request body (e.g. for POST or PUT
+requests) based on your endpoint request schema definitions.
+It also makes the parsed request body available as
+`interpol.parsed_body` in the rack env hash.
+
+``` ruby
+require 'sinatra/base'
+require 'interpol/request_body_validator'
+
+class MySinatraApp < Sinatra::Base
+  # The block is only necessary if you want to override the
+  # default config or have not set a default config.
+  use Interpol::RequestBodyValidator do |config|
+    config.on_invalid_request_body do |error|
+      [400, { 'Content-Type' => 'text/plain' }, [error.message]]
+    end
+  end
+
+  helpers do
+    def parsed_body
+      env.fetch('interpol.parsed_body')
+    end
+  end
+
+  put '/users/:user_id' do
+    User.create_or_replace(parsed_body.user_id, parsed_body.attributes)
+  end
+end
+```
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,4 +1,5 @@
 #!/usr/bin/env rake
+require File.expand_path('../config/setup_load_paths', __FILE__)
 require "bundler/gem_tasks"
 
 require 'rspec/core/rake_task'
@@ -40,9 +41,6 @@ end
 
 desc "Import the twitter bootstrap assets from the compass_twitter_bootstrap gem"
 task :import_bootstrap_assets do
-  require 'bundler'
-  Bundler.setup
-
   # when the gem installed as a :git gem, it has "-" as a separator;
   # when it's installed as a released rubygem, it has "_" as a separator.
   gem_lib_path = $LOAD_PATH.grep(/compass[-_]twitter[-_]bootstrap/).first

data/lib/interpol/configuration.rb

@@ -56,33 +56,69 @@ module Interpol
       @endpoints = endpoints.extend(DefinitionFinder)
     end
 
+    [:request, :response].each do |type|
+      class_eval <<-EOEVAL, __FILE__, __LINE__ + 1
+        def #{type}_version(version = nil, &block)
+          if [version, block].compact.size.even?
+            raise ConfigurationError.new("#{type}_version requires a static version " +
+                                         "or a dynamic block, but not both")
+          end
+
+          @#{type}_version_block = block || lambda { |*a| version }
+        end
+
+        def #{type}_version_for(rack_env, *extra_args)
+          @#{type}_version_block.call(rack_env, *extra_args).to_s
+        end
+      EOEVAL
+    end
+
     def api_version(version=nil, &block)
-      if [version, block].compact.size.even?
-        raise ConfigurationError.new("api_version requires a static version " +
-                                     "or a dynamic block, but not both")
-      end
+      warn "WARNING: Interpol's #api_version config option is deprecated. " +
+           "Instead, use separate #request_version and #response_version " +
+           "config options."
+
+      request_version(version, &block)
+      response_version(version, &block)
+    end
 
-      @api_version_block = block || lambda { |*a| version }
+    def validate_response_if(&block)
+      @validate_response_if_block = block
     end
 
-    def api_version_for(rack_env, endpoint=nil)
-      @api_version_block.call(rack_env, endpoint).to_s
+    def validate_response?(*args)
+      @validate_response_if_block.call(*args)
     end
 
     def validate_if(&block)
-      @validate_if_block = block
+      warn "WARNING: Interpol's #validate_if config option is deprecated. " +
+           "Instead, use #validate_response_if."
+
+      validate_response_if(&block)
     end
 
-    def validate?(*args)
-      @validate_if_block.call(*args)
+    def validate_request?(env)
+      @validate_request_if_block.call(env)
+    end
+
+    def validate_request_if(&block)
+      @validate_request_if_block = block
+    end
+
+    def on_unavailable_sinatra_request_version(&block)
+      @unavailable_sinatra_request_version_block = block
+    end
+
+    def sinatra_request_version_unavailable(execution_context, *args)
+      execution_context.instance_exec(*args, &@unavailable_sinatra_request_version_block)
     end
 
     def on_unavailable_request_version(&block)
       @unavailable_request_version_block = block
     end
 
-    def request_version_unavailable(execution_context, *args)
-      execution_context.instance_exec(*args, &@unavailable_request_version_block)
+    def request_version_unavailable(*args)
+      @unavailable_request_version_block.call(*args)
     end
 
     def on_invalid_sinatra_request_params(&block)
@@ -93,6 +129,14 @@ module Interpol
       execution_context.instance_exec(*args, &@invalid_sinatra_request_params_block)
     end
 
+    def on_invalid_request_body(&block)
+      @invalid_request_body_block = block
+    end
+
+    def request_body_invalid(*args)
+      @invalid_request_body_block.call(*args)
+    end
+
     def filter_example_data(&block)
       filter_example_data_blocks << block
     end
@@ -136,23 +180,52 @@ module Interpol
       }.join("\n\n")
     end
 
+    def rack_json_response(status, hash)
+      json = JSON.dump(hash)
+
+      [status, { 'Content-Type'   => 'application/json',
+                 'Content-Length' => json.bytesize }, [json]]
+    end
+
     def register_default_callbacks
-      api_version do
-        raise ConfigurationError, "api_version has not been configured"
+      request_version do
+        raise ConfigurationError, "request_version has not been configured"
       end
 
-      validate_if do |env, status, headers, body|
+      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
 
-      on_unavailable_request_version do |requested, available|
-        message = "The requested API version is invalid. " +
+      validate_request_if do |env|
+        env.fetch('CONTENT_TYPE').to_s.include?('json') &&
+        %w[ POST PUT ].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

data/lib/interpol/endpoint.rb

@@ -71,10 +71,12 @@ module Interpol
       find_definition!(version, 'response').first.example_status_code
     end
 
-    def available_versions
-      @all_definitions.inject(Set.new) do |set, definition|
-        set << definition.version
-      end.to_a
+    def available_request_versions
+      available_versions_matching &:request?
+    end
+
+    def available_response_versions
+      available_versions_matching &:response?
     end
 
     def definitions
@@ -95,6 +97,12 @@ module Interpol
 
   private
 
+    def available_versions_matching
+      @all_definitions.each_with_object(Set.new) do |definition, set|
+        set << definition.version if yield definition
+      end.to_a
+    end
+
     def route_regex
       @route_regex ||= begin
         regex_string = route.split('/').map do |path_part|
@@ -163,6 +171,10 @@ module Interpol
       message_type == "request"
     end
 
+    def response?
+      message_type == "response"
+    end
+
     def endpoint_name
       @endpoint.name
     end
@@ -175,7 +187,9 @@ module Interpol
     end
 
     def description
-      "#{endpoint_name} (v. #{version}, mt. #{message_type}, sc. #{status_codes})"
+      subdescription = "#{message_type} v. #{version}"
+      subdescription << " for status: #{status_codes}" if message_type == 'response'
+      "#{endpoint_name} (#{subdescription})"
     end
 
     def status_codes

data/lib/interpol/request_body_validator.rb

@@ -0,0 +1,82 @@
+require 'interpol'
+require 'interpol/dynamic_struct'
+
+module Interpol
+  # Validates and parses a request body according to the endpoint
+  # schema definitions.
+  class RequestBodyValidator
+    def initialize(app, &block)
+      @config = Configuration.default.customized_duplicate(&block)
+      @app = app
+    end
+
+    def call(env)
+      if @config.validate_request?(env)
+        handler = Handler.new(env, @config)
+
+        handler.validate do |error_response|
+          return error_response
+        end
+
+        env['interpol.parsed_body'] = handler.parse
+      end
+
+      @app.call(env)
+    end
+
+    # Handles request body validation for a single request.
+    class Handler
+      attr_reader :env, :config
+
+      def initialize(env, config)
+        @env = env
+        @config = config
+      end
+
+      def parse
+        DynamicStruct.new(parsed_body)
+      end
+
+      def validate(&block)
+        endpoint_definition(&block).validate_data!(parsed_body)
+      rescue Interpol::ValidationError => e
+        yield @config.request_body_invalid(env, e)
+      end
+
+    private
+
+      def request_method
+        env.fetch('REQUEST_METHOD')
+      end
+
+      def path
+        env.fetch('PATH_INFO')
+      end
+
+      def parsed_body
+        @parsed_body ||= JSON.parse(unparsed_body)
+      end
+
+      def unparsed_body
+        @unparsed_body ||= begin
+          input = env.fetch('rack.input')
+          input.read.tap { input.rewind }
+        end
+      end
+
+      def endpoint_definition(&block)
+        config.endpoints.find_definition(request_method, path, 'request', nil) do |endpoint|
+          available = endpoint.available_request_versions
+
+          @config.request_version_for(env, endpoint).tap do |requested|
+            unless available.include?(requested)
+              yield @config.request_version_unavailable(env, requested, available)
+            end
+          end
+        end
+      end
+
+    end
+  end
+end
+

data/lib/interpol/response_schema_validator.rb

@@ -15,7 +15,9 @@ module Interpol
 
     def call(env)
       status, headers, body = @app.call(env)
-      return status, headers, body unless @config.validate?(env, status, headers, body)
+      unless @config.validate_response?(env, status, headers, body)
+        return status, headers, body
+      end
 
       handler = @handler_class.new(status, headers, body, env, @config)
       handler.validate!
@@ -69,9 +71,13 @@ module Interpol
       def validator
         @validator ||= @config.endpoints.
             find_definition(request_method, path, 'response', status) do |endpoint|
-          @config.api_version_for(env, endpoint)
+          @config.response_version_for(env, endpoint, response_triplet)
         end
       end
+
+      def response_triplet
+        [status, headers, extracted_body]
+      end
     end
 
     # Private: Subclasses Handler in order to convert validation errors

data/lib/interpol/sinatra/request_params_parser.rb

@@ -83,14 +83,14 @@ module Interpol
 
           definition = config.endpoints.find_definition \
             request.env.fetch('REQUEST_METHOD'), request.path, 'request', nil do |endpoint|
-              available_versions ||= endpoint.available_versions
-              config.api_version_for(request.env, endpoint).tap do |_version|
+              available_versions ||= endpoint.available_request_versions
+              config.request_version_for(request.env, endpoint).tap do |_version|
                 version ||= _version
               end
             end
 
           if definition == DefinitionFinder::NoDefinitionFound
-            config.request_version_unavailable(app, version, available_versions)
+            config.sinatra_request_version_unavailable(app, version, available_versions)
           end
 
           definition

data/lib/interpol/stub_app.rb

@@ -53,10 +53,11 @@ module Interpol
       end
 
       def example_and_version_for(endpoint, app)
-        version = config.api_version_for(app.request.env, endpoint)
+        version = config.response_version_for(app.request.env, endpoint)
         example = endpoint.find_example_for!(version, 'response')
       rescue NoEndpointDefinitionFoundError
-        config.request_version_unavailable(app, version, endpoint.available_versions)
+        config.sinatra_request_version_unavailable(app, version,
+                                                   endpoint.available_response_versions)
       else
         example = example.apply_filters(config.filter_example_data_blocks, app.request.env)
         return example, version

data/lib/interpol/version.rb

@@ -1,3 +1,3 @@
 module Interpol
-  VERSION = "0.3.6"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: interpol
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-03 00:00:00.000000000 Z
+date: 2012-10-17 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
@@ -18,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.0.8
+        version: 1.0.10
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +193,7 @@ files:
 - lib/interpol/each_with_object.rb
 - lib/interpol/endpoint.rb
 - lib/interpol/errors.rb
+- lib/interpol/request_body_validator.rb
 - lib/interpol/request_params_parser.rb
 - lib/interpol/response_schema_validator.rb
 - lib/interpol/sinatra/request_params_parser.rb
@@ -221,18 +238,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 4001494580876368258
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 4001494580876368258
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24