openapi_first 1.0.0.beta6 → 1.0.0

data/lib/openapi_first/failure.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Failure
+    FAILURE = :openapi_first_validation_failure
+
+    TYPES = {
+      not_found: [NotFoundError, 'Request path is not defined.'],
+      method_not_allowed: [RequestInvalidError, 'Request method is not defined.'],
+      unsupported_media_type: [RequestInvalidError, 'Request content type is not defined.'],
+      invalid_body: [RequestInvalidError, 'Request body invalid:'],
+      invalid_query: [RequestInvalidError, 'Query parameter is invalid:'],
+      invalid_header: [RequestInvalidError, 'Request header is invalid:'],
+      invalid_path: [RequestInvalidError, 'Path segment is invalid:'],
+      invalid_cookie: [RequestInvalidError, 'Cookie value is invalid:'],
+      response_not_found: [ResponseNotFoundError, 'Response is not defined.'],
+      invalid_response_body: [ResponseInvalidError, 'Response body is invalid:'],
+      invalid_response_header: [ResponseInvalidError, 'Response header is invalid:']
+    }.freeze
+    private_constant :TYPES
+
+    # @param error_type [Symbol] See Failure::TYPES.keys
+    # @param errors [Array<OpenapiFirst::Schema::ValidationResult>]
+    def self.fail!(error_type, message: nil, errors: nil)
+      throw FAILURE, new(
+        error_type,
+        message:,
+        errors:
+      )
+    end
+
+    # @param type [Symbol] See TYPES.keys
+    # @param message [String] A generic error message
+    # @param errors [Array<OpenapiFirst::Schema::ValidationError>]
+    def initialize(error_type, message: nil, errors: nil)
+      unless TYPES.key?(error_type)
+        raise ArgumentError,
+              "error_type must be one of #{TYPES.keys} but was #{error_type.inspect}"
+      end
+
+      @error_type = error_type
+      @message = message
+      @errors = errors
+    end
+
+    attr_reader :error_type, :message, :errors
+
+    # Raise an exception that fits the failure.
+    def raise!
+      exception, message_prefix = TYPES.fetch(error_type)
+
+      raise exception, "#{message_prefix} #{@message || errors&.map(&:error)&.join('. ')}"
+    end
+  end
+end

data/lib/openapi_first/middlewares/request_validation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rack'
+module OpenapiFirst
+  module Middlewares
+    # A Rack middleware to validate requests against an OpenAPI API description
+    class RequestValidation
+      # @param app The parent Rack application
+      # @param options An optional Hash of configuration options to override defaults
+      #   :raise_error    A Boolean indicating whether to raise an error if validation fails.
+      #                   default: false
+      #   :error_response The Class to use for error responses.
+      #                   default: OpenapiFirst::Plugins::Default::ErrorResponse (Config.default_options.error_response)
+      def initialize(app, options = {})
+        @app = app
+        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.request_validation_raise_error)
+        @error_response_class = error_response(options[:error_response])
+
+        spec = options.fetch(:spec)
+        raise "You have to pass spec: when initializing #{self.class}" unless spec
+
+        @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
+      end
+
+      def call(env)
+        request = find_request(env)
+        return @app.call(env) unless request
+
+        failure = if @raise
+                    request.validate!
+                  else
+                    request.validate
+                  end
+        return @error_response_class.new(failure:).render if failure
+
+        @app.call(env)
+      end
+
+      private
+
+      def find_request(env)
+        env[REQUEST] ||= @definition.request(Rack::Request.new(env))
+      end
+
+      def error_response(mod)
+        return OpenapiFirst.plugin(mod)::ErrorResponse if mod.is_a?(Symbol)
+
+        mod || OpenapiFirst.configuration.request_validation_error_response
+      end
+    end
+  end
+end

data/lib/openapi_first/middlewares/response_validation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rack'
+module OpenapiFirst
+  module Middlewares
+    # A Rack middleware to validate requests against an OpenAPI API description
+    class ResponseValidation
+      # @param app The parent Rack application
+      # @param options Hash
+      #   :spec    Path to the OpenAPI file or an instance of Definition
+      def initialize(app, options = {})
+        @app = app
+
+        spec = options.fetch(:spec)
+        raise "You have to pass spec: when initializing #{self.class}" unless spec
+
+        @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
+      end
+
+      def call(env)
+        request = find_request(env)
+        response = @app.call(env)
+        request.response(response).validate!
+
+        response
+      end
+
+      private
+
+      def find_request(env)
+        env[REQUEST] ||= @definition.request(Rack::Request.new(env))
+      end
+    end
+  end
+end

data/lib/openapi_first/plugins/default/error_response.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Plugins
+    module Default
+      # An error reponse that returns application/problem+json with a list of "errors"
+      # See also https://www.rfc-editor.org/rfc/rfc9457.html
+      class ErrorResponse
+        include OpenapiFirst::ErrorResponse
+
+        TITLES = {
+          not_found: 'Not Found',
+          method_not_allowed: 'Request Method Not Allowed',
+          unsupported_media_type: 'Unsupported Media Type',
+          invalid_body: 'Bad Request Body',
+          invalid_query: 'Bad Query Parameter',
+          invalid_header: 'Bad Request Header',
+          invalid_path: 'Bad Request Path',
+          invalid_cookie: 'Bod Request Cookie'
+        }.freeze
+        private_constant :TITLES
+
+        def body
+          result = {
+            title:,
+            status:
+          }
+          result[:errors] = errors if failure.errors
+          MultiJson.dump(result)
+        end
+
+        def error_type = failure.error_type
+
+        def title
+          TITLES.fetch(error_type)
+        end
+
+        def content_type
+          'application/problem+json'
+        end
+
+        def errors
+          key = pointer_key
+          failure.errors.map do |error|
+            {
+              message: error.error,
+              key => pointer(error.instance_location),
+              code: error.type
+            }
+          end
+        end
+
+        def pointer_key
+          case error_type
+          when :invalid_body
+            :pointer
+          when :invalid_query, :invalid_path
+            :parameter
+          when :invalid_header
+            :header
+          when :invalid_cookie
+            :cookie
+          end
+        end
+
+        def pointer(data_pointer)
+          return data_pointer if error_type == :invalid_body
+
+          data_pointer.delete_prefix('/')
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/plugins/default.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'default/error_response'
+
+module OpenapiFirst
+  module Plugins
+    module Default
+      OpenapiFirst.register(:default, self)
+    end
+  end
+end

data/lib/openapi_first/plugins/jsonapi/error_response.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Plugins
+    module Jsonapi
+      class ErrorResponse
+        include OpenapiFirst::ErrorResponse
+
+        def body
+          MultiJson.dump({ errors: serialized_errors })
+        end
+
+        def content_type
+          'application/vnd.api+json'
+        end
+
+        def serialized_errors
+          return default_errors unless failure.errors
+
+          key = pointer_key
+          failure.errors.map do |error|
+            {
+              status: status.to_s,
+              source: { key => pointer(error.instance_location) },
+              title: error.error
+            }
+          end
+        end
+
+        def default_errors
+          [{
+            status: status.to_s,
+            title: Rack::Utils::HTTP_STATUS_CODES[status]
+          }]
+        end
+
+        def pointer_key
+          case failure.error_type
+          when :invalid_body
+            :pointer
+          when :invalid_query, :invalid_path
+            :parameter
+          when :invalid_header
+            :header
+          when :invalid_cookie
+            :cookie
+          end
+        end
+
+        def pointer(data_pointer)
+          return data_pointer if failure.error_type == :invalid_body
+
+          data_pointer.delete_prefix('/')
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/plugins/jsonapi.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'jsonapi/error_response'
+
+module OpenapiFirst
+  module Plugins
+    module Jsonapi
+      OpenapiFirst.register(:jsonapi, self)
+    end
+  end
+end

data/lib/openapi_first/plugins.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
+  # Plugin System adapted from
+  # Polished Ruby Programming by Jeremy Evans
+  # https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewBook?id=0
   module Plugins
-    ERROR_RESPONSES = {} # rubocop:disable Style/MutableConstant
+    PLUGINS = {} # rubocop:disable Style/MutableConstant
 
-    def self.register_error_response(name, klass)
-      ERROR_RESPONSES[name] = klass
+    def register(name, klass)
+      PLUGINS[name] = klass
     end
 
-    def self.find_error_response(name)
-      return name if name.is_a?(Class)
-
-      ERROR_RESPONSES.fetch(name)
+    def plugin(name)
+      require "openapi_first/plugins/#{name}"
+      PLUGINS.fetch(name)
     end
   end
 end

data/lib/openapi_first/request_validation/request_body_validator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative '../failure'
+
+module OpenapiFirst
+  module RequestValidation
+    class RequestBodyValidator
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def validate!(parsed_request_body, request_content_type)
+        request_body = operation.request_body
+        schema = request_body.schema_for(request_content_type)
+        unless schema
+          Failure.fail!(:unsupported_media_type,
+                        message: "Unsupported Media Type '#{request_content_type}'")
+        end
+
+        if request_body.required? && parsed_request_body.nil?
+          Failure.fail!(:invalid_body,
+                        message: 'Request body is not defined')
+        end
+
+        validate_body!(parsed_request_body, schema)
+      end
+
+      private
+
+      attr_reader :operation
+
+      def validate_body!(parsed_request_body, schema)
+        request_body_schema = schema
+        return unless request_body_schema
+
+        validation = request_body_schema.validate(parsed_request_body)
+        Failure.fail!(:invalid_body, errors: validation.errors) if validation.error?
+      end
+    end
+  end
+end

data/lib/openapi_first/request_validation/validator.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative '../failure'
+require_relative 'request_body_validator'
+
+module OpenapiFirst
+  module RequestValidation
+    class Validator
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def validate(runtime_request)
+        catch Failure::FAILURE do
+          validate_defined(runtime_request)
+          validate_parameters!(runtime_request)
+          validate_request_body!(runtime_request)
+          nil
+        end
+      end
+
+      private
+
+      attr_reader :operation, :raw_path_params
+
+      def validate_defined(request)
+        return if request.known?
+        return Failure.fail!(:not_found) unless request.known_path?
+
+        Failure.fail!(:method_not_allowed) unless request.known_request_method?
+      end
+
+      def validate_parameters!(request)
+        validate_query_params!(request)
+        validate_path_params!(request)
+        validate_cookie_params!(request)
+        validate_header_params!(request)
+      end
+
+      def validate_path_params!(request)
+        parameters = operation.path_parameters
+        return unless parameters
+
+        validation = parameters.schema.validate(request.path_parameters)
+        Failure.fail!(:invalid_path, errors: validation.errors) if validation.error?
+      end
+
+      def validate_query_params!(request)
+        parameters = operation.query_parameters
+        return unless parameters
+
+        validation = parameters.schema.validate(request.query)
+        Failure.fail!(:invalid_query, errors: validation.errors) if validation.error?
+      end
+
+      def validate_cookie_params!(request)
+        parameters = operation.cookie_parameters
+        return unless parameters
+
+        validation = parameters.schema.validate(request.cookies)
+        Failure.fail!(:invalid_cookie, errors: validation.errors) if validation.error?
+      end
+
+      def validate_header_params!(request)
+        parameters = operation.header_parameters
+        return unless parameters
+
+        validation = parameters.schema.validate(request.headers)
+        Failure.fail!(:invalid_header, errors: validation.errors) if validation.error?
+      end
+
+      def validate_request_body!(request)
+        return unless operation.request_body
+
+        RequestBodyValidator.new(operation).validate!(request.body, request.content_type)
+      rescue BodyParser::ParsingError => e
+        Failure.fail!(:invalid_body, message: e.message)
+      end
+    end
+  end
+end

data/lib/openapi_first/response_validation/validator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative '../failure'
+
+module OpenapiFirst
+  module ResponseValidation
+    class Validator
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def validate(rack_response)
+        return unless operation
+
+        response = Rack::Response[*rack_response.to_a]
+        catch Failure::FAILURE do
+          response_definition = response_for(operation, response.status, response.content_type)
+          validate_response_body(response_definition.content_schema, response.body)
+          validate_response_headers(response_definition.headers, response.headers)
+          nil
+        end
+      end
+
+      private
+
+      attr_reader :operation
+
+      def response_for(operation, status, content_type)
+        response = operation.response_for(status, content_type)
+        return response if response
+
+        unless operation.response_status_defined?(status)
+          message = "Response status '#{status}' not found for '#{operation.name}'"
+          Failure.fail!(:response_not_found, message:)
+        end
+        if content_type.nil? || content_type.empty?
+          message = "Content-Type for '#{operation.name}' must not be empty"
+          Failure.fail!(:invalid_response_header, message:)
+        end
+
+        message = "Content-Type '#{content_type}' is not defined for '#{operation.name}'"
+        Failure.fail!(:invalid_response_header, message:)
+      end
+
+      def validate_response_body(schema, response)
+        return unless schema
+
+        full_body = +''
+        response.each { |chunk| full_body << chunk }
+        data = full_body.empty? ? {} : load_json(full_body)
+        validation = schema.validate(data)
+        Failure.fail!(:invalid_response_body, errors: validation.errors) if validation.error?
+      end
+
+      def validate_response_headers(response_header_definitions, response_headers)
+        return unless response_header_definitions
+
+        unpacked_headers = unpack_response_headers(response_header_definitions, response_headers)
+        response_header_definitions.each do |name, definition|
+          next if name == 'Content-Type'
+
+          validate_response_header(name, definition, unpacked_headers, openapi_version: operation.openapi_version)
+        end
+      end
+
+      def validate_response_header(name, definition, unpacked_headers, openapi_version:)
+        unless unpacked_headers.key?(name)
+          if definition['required']
+            Failure.fail!(:invalid_response_header,
+                          message: "Required response header '#{name}' is missing")
+          end
+
+          return
+        end
+
+        return unless definition.key?('schema')
+
+        validation = Schema.new(definition['schema'], openapi_version:)
+        value = unpacked_headers[name]
+        validation_result = validation.validate(value)
+        return unless validation_result.error?
+
+        Failure.fail!(:invalid_response_header,
+                      errors: validation_result.errors)
+      end
+
+      def unpack_response_headers(response_header_definitions, response_headers)
+        headers_as_parameters = response_header_definitions.map do |name, definition|
+          definition.merge('name' => name, 'in' => 'header')
+        end
+        OpenapiParameters::Header.new(headers_as_parameters).unpack(response_headers)
+      end
+
+      def load_json(string)
+        MultiJson.load(string)
+      rescue MultiJson::ParseError
+        string
+      end
+    end
+  end
+end

data/lib/openapi_first/runtime_request.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require_relative 'runtime_response'
+require_relative 'body_parser'
+require_relative 'request_validation/validator'
+
+module OpenapiFirst
+  # RuntimeRequest represents how an incoming request (Rack::Request) matches a request definition.
+  class RuntimeRequest
+    extend Forwardable
+
+    def initialize(request:, path_item:, operation:, path_params:)
+      @request = request
+      @path_item = path_item
+      @operation = operation
+      @original_path_params = path_params
+    end
+
+    def_delegators :@request, :content_type, :media_type
+    def_delegators :@operation, :operation_id
+
+    def known?
+      known_path? && known_request_method?
+    end
+
+    def known_path?
+      !!path_item
+    end
+
+    def known_request_method?
+      !!operation
+    end
+
+    # Merged path and query parameters
+    def params
+      @params ||= query.merge(path_parameters)
+    end
+
+    def path_parameters
+      @path_parameters ||=
+        operation.path_parameters&.unpack(@original_path_params) || {}
+    end
+
+    def query
+      @query ||=
+        operation.query_parameters&.unpack(request.env) || {}
+    end
+
+    alias query_parameters query
+
+    def headers
+      @headers ||=
+        operation.header_parameters&.unpack(request.env) || {}
+    end
+
+    def cookies
+      @cookies ||=
+        operation.cookie_parameters&.unpack(request.env) || {}
+    end
+
+    def body
+      @body ||= BodyParser.new.parse(request, request.media_type)
+    end
+    alias parsed_body body
+
+    def validate
+      RequestValidation::Validator.new(operation).validate(self)
+    end
+
+    def validate!
+      error = validate
+      error&.raise!
+    end
+
+    def response(rack_response)
+      RuntimeResponse.new(operation, rack_response)
+    end
+
+    private
+
+    attr_reader :request, :operation, :path_item
+  end
+end

data/lib/openapi_first/runtime_response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'response_validation/validator'
+
+module OpenapiFirst
+  class RuntimeResponse
+    def initialize(operation, rack_response)
+      @operation = operation
+      @rack_response = rack_response
+    end
+
+    def description
+      response_definition&.description
+    end
+
+    def validate
+      ResponseValidation::Validator.new(@operation).validate(@rack_response)
+    end
+
+    def validate!
+      error = validate
+      error&.raise!
+    end
+
+    private
+
+    def response_definition
+      @response_definition ||= @operation.response_for(@rack_response.status, @rack_response.content_type)
+    end
+  end
+end

data/lib/openapi_first/schema/validation_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Schema
+    class ValidationError
+      def initialize(json_schemer_error)
+        @error = json_schemer_error
+      end
+
+      def error = @error['error']
+      def schemer_error = @error
+      def instance_location = @error['data_pointer']
+      def schema_location = @error['schema_pointer']
+      def type = @error['type']
+      def details = @error['details']
+    end
+  end
+end