committee 1.15.0 → 5.0.0

data/lib/committee/drivers/open_api_2/link.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      # Link abstracts an API link specifically for OpenAPI 2.
+      class Link
+        # The link's input media type. i.e. How requests should be encoded.
+        attr_accessor :enc_type
+
+        attr_accessor :href
+
+        # The link's output media type. i.e. How responses should be encoded.
+        attr_accessor :media_type
+
+        attr_accessor :method
+
+        # The link's input schema. i.e. How we validate an endpoint's incoming
+        # parameters.
+        attr_accessor :schema
+
+        attr_accessor :status_success
+
+        # The link's output schema. i.e. How we validate an endpoint's response
+        # data.
+        attr_accessor :target_schema
+
+        attr_accessor :header_schema
+
+        def rel
+          raise "Committee: rel not implemented for OpenAPI"
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_2/parameter_schema_builder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      # ParameterSchemaBuilder converts OpenAPI 2 link parameters, which are not
+      # quite JSON schemas (but will be in OpenAPI 3) into synthetic schemas that
+      # we can use to do some basic request validation.
+      class ParameterSchemaBuilder < SchemaBuilder
+        # Returns a tuple of (schema, schema_data) where only one of the two
+        # values is present. This is either a full schema that's ready to go _or_
+        # a hash of unparsed schema data.
+        def call
+          if link_data["parameters"]
+            body_param = link_data["parameters"].detect { |p| p["in"] == "body" }
+            if body_param
+              check_required_fields!(body_param)
+
+              if link_data["parameters"].detect { |p| p["in"] == "form" } != nil
+                raise ArgumentError, "Committee: can't mix body parameter " \
+                  "with form parameters."
+              end
+
+              schema_data = body_param["schema"]
+              [nil, schema_data]
+            else
+              link_schema = JsonSchema::Schema.new
+              link_schema.properties = {}
+              link_schema.required = []
+
+              parameters = link_data["parameters"].reject { |param_data| param_data["in"] == "header" }
+              parameters.each do |param_data|
+                check_required_fields!(param_data)
+
+                param_schema = JsonSchema::Schema.new
+
+                # We could probably use more validation here, but the formats of
+                # OpenAPI 2 are based off of what's available in JSON schema, and
+                # therefore this should map over quite well.
+                param_schema.type = [param_data["type"]]
+
+                param_schema.enum = param_data["enum"] unless param_data["enum"].nil?
+
+                # validation: string
+                param_schema.format = param_data["format"] unless param_data["format"].nil?
+                param_schema.pattern = Regexp.new(param_data["pattern"]) unless param_data["pattern"].nil?
+                param_schema.min_length = param_data["minLength"] unless param_data["minLength"].nil?
+                param_schema.max_length = param_data["maxLength"] unless param_data["maxLength"].nil?
+
+                # validation: array
+                param_schema.min_items = param_data["minItems"] unless param_data["minItems"].nil?
+                param_schema.max_items = param_data["maxItems"] unless param_data["maxItems"].nil?
+                param_schema.unique_items = param_data["uniqueItems"] unless param_data["uniqueItems"].nil?
+
+                # validation: number/integer
+                param_schema.min = param_data["minimum"] unless param_data["minimum"].nil?
+                param_schema.min_exclusive = param_data["exclusiveMinimum"] unless param_data["exclusiveMinimum"].nil?
+                param_schema.max = param_data["maximum"] unless param_data["maximum"].nil?
+                param_schema.max_exclusive = param_data["exclusiveMaximum"] unless param_data["exclusiveMaximum"].nil?
+                param_schema.multiple_of = param_data["multipleOf"] unless param_data["multipleOf"].nil?
+
+                # And same idea: despite parameters not being schemas, the items
+                # key (if preset) is actually a schema that defines each item of an
+                # array type, so we can just reflect that directly onto our
+                # artificial schema.
+                if param_data["type"] == "array" && param_data["items"]
+                  param_schema.items = param_data["items"]
+                end
+
+                link_schema.properties[param_data["name"]] = param_schema
+                if param_data["required"] == true
+                  link_schema.required << param_data["name"]
+                end
+              end
+
+              [link_schema, nil]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_2/schema.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      class Schema < ::Committee::Drivers::Schema
+        attr_accessor :base_path
+        attr_accessor :consumes
+
+        # A link back to the derivative instance of Committee::Drivers::Driver
+        # that create this schema.
+        attr_accessor :driver
+
+        attr_accessor :definitions
+        attr_accessor :produces
+        attr_accessor :routes
+        attr_reader :validator_option
+
+        def build_router(options)
+          @validator_option = Committee::SchemaValidator::Option.new(options, self, :hyper_schema)
+          Committee::SchemaValidator::HyperSchema::Router.new(self, @validator_option)
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_2/schema_builder.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+      class SchemaBuilder
+        def initialize(link_data)
+          @link_data = link_data
+        end
+
+        private
+
+        LINK_REQUIRED_FIELDS = [
+          :name
+        ].map(&:to_s).freeze
+
+        attr_accessor :link_data
+
+        def check_required_fields!(param_data)
+          LINK_REQUIRED_FIELDS.each do |field|
+            if !param_data[field]
+              raise ArgumentError,
+                    "Committee: no #{field} section in link data."
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'header_schema_builder'
+require_relative 'parameter_schema_builder'

data/lib/committee/drivers/open_api_2.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI2
+    end
+  end
+end
+
+require_relative 'open_api_2/driver'
+require_relative 'open_api_2/link'
+require_relative 'open_api_2/schema'
+require_relative 'open_api_2/schema_builder'

data/lib/committee/drivers/open_api_3/driver.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI3
+      class Driver < ::Committee::Drivers::Driver
+        def default_coerce_date_times
+          true
+        end
+
+        # Whether parameters that were form-encoded will be coerced by default.
+        def default_coerce_form_params
+          true
+        end
+
+        def default_allow_get_body
+          false
+        end
+
+        # Whether parameters in a request's path will be considered and coerced by
+        # default.
+        def default_path_params
+          true
+        end
+
+        # Whether parameters in a request's query string will be considered and
+        # coerced by default.
+        def default_query_params
+          true
+        end
+
+        def default_validate_success_only
+          false
+        end
+
+        def name
+          :open_api_3
+        end
+
+        # @return [Committee::Drivers::OpenAPI3::Schema]
+        def parse(open_api)
+          schema_class.new(self, open_api)
+        end
+
+        def schema_class
+          Committee::Drivers::OpenAPI3::Schema
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_3/schema.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI3
+      class Schema < ::Committee::Drivers::Schema
+        attr_reader :open_api
+        attr_reader :validator_option
+
+        # @!attribute [r] open_api
+        #   @return [OpenAPIParser::Schemas::OpenAPI]
+
+        def initialize(driver, open_api)
+          @open_api = open_api
+          @driver = driver
+        end
+
+        def supports_stub?
+          false
+        end
+
+        def driver # we don't use attr_reader because this method override super class
+          @driver
+        end
+
+        def build_router(options)
+          @validator_option = Committee::SchemaValidator::Option.new(options, self, :open_api_3)
+          Committee::SchemaValidator::OpenAPI3::Router.new(self, @validator_option)
+        end
+
+        # OpenAPI3 only
+        def operation_object(path, method)
+          request_operation = open_api.request_operation(method, path)
+          return nil unless request_operation
+
+          Committee::SchemaValidator::OpenAPI3::OperationWrapper.new(request_operation)
+        end
+      end
+    end
+  end
+end

data/lib/committee/drivers/open_api_3.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    module OpenAPI3
+    end
+  end
+end
+
+require_relative 'open_api_3/driver'
+require_relative 'open_api_3/schema'

data/lib/committee/drivers/schema.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    # Schema is a base class for driver schema implementations.
+    class Schema
+      # A link back to the derivative instance of Committee::Drivers::Driver
+      # that create this schema.
+      def driver
+        raise "needs implementation"
+      end
+
+      def build_router(options)
+        raise "needs implementation"
+      end
+
+      # Stubs are supported in JSON Hyper-Schema and OpenAPI 2, but not yet in OpenAPI 3
+      def supports_stub?
+        true
+      end
+    end
+  end
+end

data/lib/committee/drivers.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Committee
+  module Drivers
+    # Gets a driver instance from the specified name. Raises ArgumentError for
+    # an unknown driver name.
+    def self.driver_from_name(name)
+      case name
+      when :hyper_schema
+        Committee::Drivers::HyperSchema::Driver.new
+      when :open_api_2
+        Committee::Drivers::OpenAPI2::Driver.new
+      when :open_api_3
+        Committee::Drivers::OpenAPI3::Driver.new
+      else
+        raise ArgumentError, %{Committee: unknown driver "#{name}".}
+      end
+    end
+
+    # load and build drive from JSON file
+    # @param [String] schema_path
+    # @return [Committee::Driver]
+    def self.load_from_json(schema_path, parser_options: {})
+      load_from_data(JSON.parse(File.read(schema_path)), schema_path, parser_options: parser_options)
+    end
+
+    # load and build drive from YAML file
+    # @param [String] schema_path
+    # @return [Committee::Driver]
+    def self.load_from_yaml(schema_path, parser_options: {})
+      data = YAML.respond_to?(:unsafe_load_file) ? YAML.unsafe_load_file(schema_path) : YAML.load_file(schema_path)
+      load_from_data(data, schema_path, parser_options: parser_options)
+    end
+
+    # load and build drive from file
+    # @param [String] schema_path
+    # @return [Committee::Driver]
+    def self.load_from_file(schema_path, parser_options: {})
+      case File.extname(schema_path)
+      when '.json'
+        load_from_json(schema_path, parser_options: parser_options)
+      when '.yaml', '.yml'
+        load_from_yaml(schema_path, parser_options: parser_options)
+      else
+        raise "Committee only supports the following file extensions: '.json', '.yaml', '.yml'"
+      end
+    end
+
+    # load and build drive from Hash object
+    # @param [Hash] hash
+    # @return [Committee::Driver]
+    def self.load_from_data(hash, schema_path = nil, parser_options: {})
+      if hash['openapi']&.start_with?('3.0.')
+        # From the next major version, we want to ensure `{ strict_reference_validation: true }`
+        # as a parser option here, but since it may break existing implementations, just warn
+        # if it is not explicitly set. See: https://github.com/interagent/committee/issues/343#issuecomment-997400329
+        opts = parser_options.dup
+
+        Committee.warn_deprecated_until_6(!opts.key?(:strict_reference_validation), 'openapi_parser will default to strict reference validation ' +
+        'from next version. Pass config `strict_reference_validation: true` (or false, if you must) ' +
+        'to quiet this warning.')
+        opts[:strict_reference_validation] ||= false
+        
+        openapi = OpenAPIParser.parse_with_filepath(hash, schema_path, opts)
+        return Committee::Drivers::OpenAPI3::Driver.new.parse(openapi)
+      end
+
+      driver = if hash['swagger'] == '2.0'
+                 Committee::Drivers::OpenAPI2::Driver.new
+               else
+                 Committee::Drivers::HyperSchema::Driver.new
+               end
+
+      # TODO: in the future, pass `opts` here and allow optionality in other drivers?
+      driver.parse(hash)
+    end
+  end
+end
+
+require_relative "drivers/driver"
+require_relative "drivers/schema"
+require_relative "drivers/hyper_schema"
+require_relative "drivers/open_api_2"
+require_relative "drivers/open_api_3"

data/lib/committee/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Committee
   class Error < StandardError
   end
@@ -6,9 +8,21 @@ module Committee
   end
 
   class InvalidRequest < Error
+    attr_reader :original_error
+
+    def initialize(error_message=nil, original_error: nil)
+      @original_error = original_error
+      super(error_message)
+    end
   end
 
   class InvalidResponse < Error
+    attr_reader :original_error
+
+    def initialize(error_message=nil, original_error: nil)
+      @original_error = original_error
+      super(error_message)
+    end
   end
 
   class NotFound < Error
@@ -16,4 +30,7 @@ module Committee
 
   class ReferenceNotFound < Error
   end
+
+  class OpenAPI3Unsupported < Error
+  end
 end

data/lib/committee/middleware/base.rb

@@ -1,40 +1,57 @@
-module Committee::Middleware
-  class Base
-    def initialize(app, options={})
-      @app = app
-
-      @error_class = options.fetch(:error_class, Committee::ValidationError)
-      @params_key = options[:params_key] || "committee.params"
-      @raise = options[:raise]
-
-      schema = options[:schema] || raise("need option `schema`")
-      if schema.is_a?(String)
-        warn_string_deprecated
-        schema = JSON.parse(schema)
+# frozen_string_literal: true
+
+module Committee
+  module Middleware
+    class Base
+      def initialize(app, options={})
+        @app = app
+
+        @error_class = options.fetch(:error_class, Committee::ValidationError)
+        @error_handler = options[:error_handler]
+        @ignore_error = options.fetch(:ignore_error, false)
+
+        @raise = options[:raise]
+        @schema = self.class.get_schema(options)
+
+        @router = @schema.build_router(options)
+        @accept_request_filter = options[:accept_request_filter] || -> (_) { true }
       end
-      if schema.is_a?(Hash)
-        schema = JsonSchema.parse!(schema)
-        schema.expand_references!
+
+      def call(env)
+        request = Rack::Request.new(env)
+
+        if @router.includes_request?(request) && @accept_request_filter.call(request)
+          handle(request)
+        else
+          @app.call(request.env)
+        end
       end
-      @schema = schema
 
-      @router = Committee::Router.new(@schema, options)
-    end
+      class << self
+        def get_schema(options)
+          schema = options[:schema]
+          if !schema && options[:schema_path]
+            # In the future, we could have `parser_options` as an exposed config?
+            parser_options = options.key?(:strict_reference_validation) ? { strict_reference_validation: options[:strict_reference_validation] } : {}
+            schema = Committee::Drivers::load_from_file(options[:schema_path], parser_options: parser_options)
+          end
+          raise(ArgumentError, "Committee: need option `schema` or `schema_path`") unless schema
 
-    def call(env)
-      request = Rack::Request.new(env)
+          # Expect the type we want by now. If we don't have it, the user passed
+          # something else non-standard in.
+          if !schema.is_a?(Committee::Drivers::Schema)
+            raise ArgumentError, "Committee: schema expected to be an instance of Committee::Drivers::Schema."
+          end
 
-      if @router.includes_request?(request)
-        handle(request)
-      else
-        @app.call(request.env)
+          return schema
+        end
       end
-    end
 
-    private
+      private
 
-    def warn_string_deprecated
-      Committee.warn_deprecated("Committee: passing a string to `schema` option is deprecated; please send a deserialized hash instead.")
+      def build_schema_validator(request)
+        @router.build_schema_validator(request)
+      end
     end
   end
 end

data/lib/committee/middleware/request_validation.rb

@@ -1,59 +1,41 @@
-module Committee::Middleware
-  class RequestValidation < Base
-    def initialize(app, options={})
-      super
-      @allow_form_params   = options.fetch(:allow_form_params, true)
-      @allow_query_params  = options.fetch(:allow_query_params, true)
-      @check_content_type  = options.fetch(:check_content_type, true)
-      @optimistic_json     = options.fetch(:optimistic_json, false)
-      @coerce_query_params = options.fetch(:coerce_query_params, false)
-      @strict              = options[:strict]
+# frozen_string_literal: true
 
-      # deprecated
-      @allow_extra = options[:allow_extra]
-    end
-
-    def handle(request)
-      link = @router.find_request_link(request)
+module Committee
+  module Middleware
+    class RequestValidation < Base
+      def initialize(app, options={})
+        super
 
-      if link && @coerce_query_params && !request.GET.nil? && !link.schema.nil?
-        request.env["rack.request.query_hash"].merge!(
-          Committee::QueryParamsCoercer.new(
-            request.GET,
-            link.schema
-          ).call
-        )
+        @strict  = options[:strict]
       end
 
-      request.env[@params_key] = Committee::RequestUnpacker.new(
-        request,
-        allow_form_params:  @allow_form_params,
-        allow_query_params: @allow_query_params,
-        optimistic_json:    @optimistic_json
-      ).call
+      def handle(request)
+        begin
+          schema_validator = build_schema_validator(request)
+          schema_validator.request_validate(request)
+
+          raise Committee::NotFound, "That request method and path combination isn't defined." if !schema_validator.link_exist? && @strict
+        rescue Committee::BadRequest, Committee::InvalidRequest
+          handle_exception($!, request.env)
+          raise if @raise
+          return @error_class.new(400, :bad_request, $!.message, request).render unless @ignore_error
+        rescue Committee::NotFound => e
+          raise if @raise
+          return @error_class.new(404, :not_found, e.message, request).render unless @ignore_error
+        rescue JSON::ParserError
+          handle_exception($!, request.env)
+          raise Committee::InvalidRequest if @raise
+          return @error_class.new(400, :bad_request, "Request body wasn't valid JSON.", request).render unless @ignore_error
+        end
 
-      if link
-        validator = Committee::RequestValidator.new(link, check_content_type: @check_content_type)
-        validator.call(request, request.env[@params_key])
-        @app.call(request.env)
-      elsif @strict
-        raise Committee::NotFound
-      else
         @app.call(request.env)
       end
-    rescue Committee::BadRequest, Committee::InvalidRequest
-      raise if @raise
-      @error_class.new(400, :bad_request, $!.message).render
-    rescue Committee::NotFound
-      raise if @raise
-      @error_class.new(
-        404,
-        :not_found,
-        "That request method and path combination isn't defined."
-      ).render
-    rescue JSON::ParserError
-      raise Committee::InvalidRequest if @raise
-      @error_class.new(400, :bad_request, "Request body wasn't valid JSON.").render
+
+      private
+
+      def handle_exception(e, env)
+        @error_handler.call(e, env) if @error_handler
+      end
     end
   end
 end