committee_firetail 5.0.0

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Committee
+  class Error < StandardError
+  end
+
+  class BadRequest < Error
+  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
+  end
+
+  class ReferenceNotFound < Error
+  end
+
+  class OpenAPI3Unsupported < Error
+  end
+end

data/lib/committee/middleware/base.rb

@@ -0,0 +1,57 @@
+# 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
+
+      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
+
+      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
+
+          # 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
+
+          return schema
+        end
+      end
+
+      private
+
+      def build_schema_validator(request)
+        @router.build_schema_validator(request)
+      end
+    end
+  end
+end

data/lib/committee/middleware/request_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Committee
+  module Middleware
+    class RequestValidation < Base
+      def initialize(app, options={})
+        super
+
+        @strict  = options[:strict]
+      end
+
+      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
+
+        @app.call(request.env)
+      end
+
+      private
+
+      def handle_exception(e, env)
+        @error_handler.call(e, env) if @error_handler
+      end
+    end
+  end
+end

data/lib/committee/middleware/response_validation.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Committee
+  module Middleware
+    class ResponseValidation < Base
+      attr_reader :validate_success_only
+
+      def initialize(app, options = {})
+        super
+        @strict = options[:strict]
+        @validate_success_only = @schema.validator_option.validate_success_only
+      end
+
+      def handle(request)
+        status, headers, response = @app.call(request.env)
+
+        begin
+          v = build_schema_validator(request)
+          v.response_validate(status, headers, response, @strict) if v.link_exist? && self.class.validate?(status, validate_success_only)
+
+        rescue Committee::InvalidResponse
+          handle_exception($!, request.env)
+
+          raise if @raise
+          return @error_class.new(500, :invalid_response, $!.message).render unless @ignore_error
+        rescue JSON::ParserError
+          handle_exception($!, request.env)
+
+          raise Committee::InvalidResponse if @raise
+          return @error_class.new(500, :invalid_response, "Response wasn't valid JSON.").render unless @ignore_error
+        end
+
+        [status, headers, response]
+      end
+
+      class << self
+        def validate?(status, validate_success_only)
+          case status
+          when 204
+            false
+          when 200..299
+            true
+          when 304
+            false
+          else
+            !validate_success_only
+          end
+        end
+      end
+
+      private
+
+      def handle_exception(e, env)
+        @error_handler.call(e, env) if @error_handler
+      end
+    end
+  end
+end

data/lib/committee/middleware/stub.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Stub is not yet supported in OpenAPI 3
+
+module Committee
+  module Middleware
+    class Stub < Base
+      def initialize(app, options={})
+        super
+
+        # A bug in Committee's cache implementation meant that it wasn't working
+        # for a very long time, even for people who thought they were taking
+        # advantage of it. I repaired the caching feature, but have disable it by
+        # default so that we don't need to introduce any class-level variables
+        # that could have memory leaking implications. To enable caching, just
+        # pass an empty hash to this option.
+        @cache = options[:cache]
+
+        @call = options[:call]
+
+        raise Committee::OpenAPI3Unsupported.new("Stubs are not yet supported for OpenAPI 3") unless @schema.supports_stub?
+      end
+
+      def handle(request)
+        link, _ = @router.find_request_link(request)
+        if link
+          headers = { "Content-Type" => "application/json" }
+
+          data, schema = cache(link) do
+            Committee::SchemaValidator::HyperSchema::ResponseGenerator.new.call(link)
+          end
+
+          if @call
+            request.env["committee.response"] = data
+            request.env["committee.response_schema"] = schema
+            call_status, call_headers, call_body = @app.call(request.env)
+
+            # a committee.suppress signal initiates a direct pass through
+            if request.env["committee.suppress"] == true
+              return call_status, call_headers, call_body
+            end
+
+            # otherwise keep the headers and whatever data manipulations were
+            # made, and stub normally
+            headers.merge!(call_headers)
+
+            # allow the handler to change the data object (if unchanged, it
+            # will be the same one that we set above)
+            data = request.env["committee.response"]
+          end
+
+          [link.status_success, headers, [JSON.pretty_generate(data)]]
+        else
+          @app.call(request.env)
+        end
+      end
+
+      private
+
+      def cache(link)
+        return yield unless @cache
+
+        # Just the object ID is enough to uniquely identify the link, but store
+        # the method and href so that we can more easily introspect the cache if
+        # necessary.
+        key = "#{link.object_id}##{link.method}+#{link.href}"
+        if @cache[key]
+          @cache[key]
+        else
+          @cache[key] = yield
+        end
+      end
+    end
+  end
+end

data/lib/committee/middleware.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Committee
+  module Middleware
+  end
+end
+
+require_relative "middleware/base"
+require_relative "middleware/request_validation"
+require_relative "middleware/response_validation"
+require_relative "middleware/stub"