openapi_first 1.4.3 → 2.0.0

data/lib/openapi_first/error_responses/default.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module ErrorResponses
+    # An error reponse that returns application/problem+json with a list of "errors"
+    # See also https://www.rfc-editor.org/rfc/rfc9457.html
+    class Default
+      include OpenapiFirst::ErrorResponse
+      OpenapiFirst.register_error_response(:default, self)
+
+      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: 'Bad Request Cookie'
+      }.freeze
+      private_constant :TITLES
+
+      def body
+        result = {
+          title:,
+          status:
+        }
+        result[:errors] = errors if failure.errors
+        MultiJson.dump(result)
+      end
+
+      def type = failure.type
+
+      def title
+        TITLES.fetch(type)
+      end
+
+      def content_type
+        'application/problem+json'
+      end
+
+      def errors
+        key = pointer_key
+        failure.errors.map do |error|
+          {
+            message: error.message,
+            key => pointer(error.data_pointer),
+            code: error.type
+          }
+        end
+      end
+
+      def pointer_key
+        case 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 type == :invalid_body
+
+        data_pointer.delete_prefix('/')
+      end
+    end
+  end
+end

data/lib/openapi_first/error_responses/jsonapi.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module ErrorResponses
+    # A JSON:API conform error response. See https://jsonapi.org/.
+    class Jsonapi
+      include OpenapiFirst::ErrorResponse
+      OpenapiFirst.register_error_response(:jsonapi, self)
+
+      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.data_pointer) },
+            title: error.message,
+            code: error.type
+          }
+        end
+      end
+
+      def default_errors
+        [{
+          status: status.to_s,
+          title: Rack::Utils::HTTP_STATUS_CODES[status]
+        }]
+      end
+
+      def pointer_key
+        case failure.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.type == :invalid_body
+
+        data_pointer.delete_prefix('/')
+      end
+    end
+  end
+end

data/lib/openapi_first/errors.rb

@@ -4,13 +4,35 @@ module OpenapiFirst
   # @!visibility private
   class Error < StandardError; end
   # @!visibility private
+  class FileNotFoundError < Error; end
+  # @!visibility private
   class ParseError < Error; end
+
   # @!visibility private
-  class NotFoundError < Error; end
+  class RequestInvalidError < Error
+    def initialize(message, validated_request)
+      super(message)
+      @request = validated_request
+    end
+
+    # @attr_reader [OpenapiFirst::ValidatedRequest] request The validated request
+    attr_reader :request
+  end
+
   # @!visibility private
-  class RequestInvalidError < Error; end
+  class NotFoundError < RequestInvalidError; end
+
   # @!visibility private
-  class ResponseNotFoundError < Error; end
+  class ResponseInvalidError < Error
+    def initialize(message, validated_response)
+      super(message)
+      @response = validated_response
+    end
+
+    # @attr_reader [OpenapiFirst::ValidatedResponse] request The validated response
+    attr_reader :response
+  end
+
   # @!visibility private
-  class ResponseInvalidError < Error; end
+  class ResponseNotFoundError < ResponseInvalidError; end
 end

data/lib/openapi_first/failure.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  # A failure object returned when validation of request or response has failed.
+  # A failure object returned when validation or parsing of a request or response has failed.
+  # This returned in ValidatedRequest#error and ValidatedResponse#error.
   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.'],
@@ -14,64 +13,68 @@ module OpenapiFirst
       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.'],
+      response_not_found: [ResponseNotFoundError],
       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 type [Symbol] See Failure::TYPES.keys
     # @param errors [Array<OpenapiFirst::Schema::ValidationError>]
-    def self.fail!(error_type, message: nil, errors: nil)
+    def self.fail!(type, message: nil, errors: nil)
       throw FAILURE, new(
-        error_type,
+        type,
         message:,
         errors:
       )
     end
 
-    # @param error_type [Symbol] See TYPES.keys
+    # @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)
+    def initialize(type, message: nil, errors: nil)
+      unless TYPES.key?(type)
         raise ArgumentError,
-              "error_type must be one of #{TYPES.keys} but was #{error_type.inspect}"
+              "type must be one of #{TYPES.keys} but was #{type.inspect}"
       end
 
-      @error_type = error_type
+      @type = type
       @message = message
       @errors = errors
     end
 
-    # @attr_reader [Symbol] error_type The type of the failure. See TYPES.keys.
-    # @alias type error_type
+    # @attr_reader [Symbol] type The type of the failure. See TYPES.keys.
     # Example: :invalid_body
-    attr_reader :error_type
-    alias type error_type
-
-    # @attr_reader [String] message A generic error message
-    attr_reader :message
+    attr_reader :type
 
     # @attr_reader [Array<OpenapiFirst::Schema::ValidationError>] errors Schema validation errors
     attr_reader :errors
 
-    # Raise an exception that fits the failure.
-    def raise!
-      exception, = TYPES.fetch(error_type)
-      raise exception, exception_message
+    # A generic error message
+    def message
+      @message ||= exception_message
+    end
+
+    def exception(context = nil)
+      TYPES.fetch(type).first.new(exception_message, context)
     end
 
     def exception_message
-      _, message_prefix = TYPES.fetch(error_type)
+      _, message_prefix = TYPES.fetch(type)
+
+      [message_prefix, @message || generate_message].compact.join(' ')
+    end
 
-      "#{message_prefix} #{@message || generate_message}"
+    # @deprecated Please use {#type} instead
+    def error_type
+      warn 'OpenapiFirst::Failure#error_type is deprecated. Use #type instead.'
+      type
     end
 
     private
 
     def generate_message
-      messages = errors&.take(3)&.map(&:error)
+      messages = errors&.take(3)&.map(&:message)
       messages << "... (#{errors.size} errors total)" if errors && errors.size > 3
       messages&.join('. ')
     end

data/lib/openapi_first/json_refs.rb

@@ -33,9 +33,7 @@ require 'json'
 require 'yaml'
 
 module OpenapiFirst
-  class FileNotFoundError < StandardError; end
-
-  module JsonRefs
+  module JsonRefs # :nodoc:
     class << self
       def dereference(doc)
         file_cache = {}

data/lib/openapi_first/middlewares/request_validation.rb

@@ -27,7 +27,7 @@ module OpenapiFirst
 
       def call(env)
         validated = @definition.validate_request(Rack::Request.new(env), raise_error: @raise)
-        env[REQUEST] ||= validated
+        env[REQUEST] = validated
         failure = validated.error
         return @error_response_class.new(failure:).render if failure
 
@@ -37,7 +37,7 @@ module OpenapiFirst
       private
 
       def error_response(mod)
-        return OpenapiFirst.find_plugin(mod)::ErrorResponse if mod.is_a?(Symbol)
+        return OpenapiFirst.find_error_response(mod) if mod.is_a?(Symbol)
 
         mod || OpenapiFirst.configuration.request_validation_error_response
       end

data/lib/openapi_first/middlewares/response_validation.rb

@@ -8,9 +8,11 @@ module OpenapiFirst
     class ResponseValidation
       # @param app The parent Rack application
       # @param options Hash
-      #   :spec    Path to the OpenAPI file or an instance of Definition
+      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition
+      #   :raise_error [Boolean] Whether to raise an error if validation fails. default: true
       def initialize(app, options = {})
         @app = app
+        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.response_validation_raise_error)
 
         spec = options.fetch(:spec)
         raise "You have to pass spec: when initializing #{self.class}" unless spec
@@ -24,8 +26,7 @@ module OpenapiFirst
       def call(env)
         status, headers, body = @app.call(env)
         body = read_body(body)
-        @definition.validate_response(Rack::Request.new(env), Rack::Response[status, headers, body], raise_error: true)
-        env[REQUEST] ||= @definition.request(Rack::Request.new(env))
+        @definition.validate_response(Rack::Request.new(env), Rack::Response[status, headers, body], raise_error: @raise)
         [status, headers, body]
       end
 

data/lib/openapi_first/request.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'request_parser'
+require_relative 'request_validator'
+require_relative 'validated_request'
+
+module OpenapiFirst
+  # Represents one request definition of an OpenAPI description.
+  # Note that this is not the same as an OpenAPI 3.x Operation.
+  # An 3.x Operation object can accept multiple requests, because it can handle multiple content-types.
+  # This class represents one of those requests.
+  class Request
+    def initialize(path:, request_method:, operation_object:,
+                   parameters:, content_type:, content_schema:, required_body:,
+                   hooks:, openapi_version:)
+      @path = path
+      @request_method = request_method
+      @content_type = content_type
+      @content_schema = content_schema
+      @required_request_body = required_body == true
+      @operation = operation_object
+      @parameters = build_parameters(parameters)
+      @request_parser = RequestParser.new(
+        query_parameters: @parameters[:query],
+        path_parameters: @parameters[:path],
+        header_parameters: @parameters[:header],
+        cookie_parameters: @parameters[:cookie],
+        content_type:
+      )
+      @validator = RequestValidator.new(self, hooks:, openapi_version:)
+    end
+
+    attr_reader :content_type, :content_schema, :operation, :request_method, :path
+
+    def validate(request, route_params:)
+      parsed_values = {}
+      error = catch FAILURE do
+        parsed_values = @request_parser.parse(request, route_params:)
+        @validator.call(parsed_values)
+        nil
+      end
+      ValidatedRequest.new(request, parsed_values:, error:, request_definition: self)
+    end
+
+    # These return a Schema instance for each type of parameters
+    %i[path query header cookie].each do |location|
+      define_method(:"#{location}_schema") do
+        build_parameters_schema(@parameters[location])
+      end
+    end
+
+    def required_request_body?
+      @required_request_body
+    end
+
+    def operation_id
+      @operation['operationId']
+    end
+
+    private
+
+    IGNORED_HEADERS = Set['Content-Type', 'Accept', 'Authorization'].freeze
+    private_constant :IGNORED_HEADERS
+
+    def build_parameters(parameter_definitions)
+      result = {}
+      parameter_definitions&.each do |parameter|
+        (result[parameter['in'].to_sym] ||= []) << parameter
+      end
+      result[:header]&.reject! { IGNORED_HEADERS.include?(_1['name']) }
+      result
+    end
+
+    def build_parameters_schema(parameters)
+      return unless parameters
+
+      properties = {}
+      required = []
+      parameters.each do |parameter|
+        schema = parameter['schema']
+        name = parameter['name']
+        properties[name] = schema if schema
+        required << name if parameter['required']
+      end
+
+      {
+        'properties' => properties,
+        'required' => required
+      }
+    end
+  end
+end

data/lib/openapi_first/request_parser.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'openapi_parameters'
+require_relative 'body_parser'
+
+module OpenapiFirst
+  # Parse a request
+  class RequestParser
+    def initialize(
+      query_parameters:,
+      path_parameters:,
+      header_parameters:,
+      cookie_parameters:,
+      content_type:
+    )
+      @query_parser = OpenapiParameters::Query.new(query_parameters) if query_parameters
+      @path_parser = OpenapiParameters::Path.new(path_parameters) if path_parameters
+      @headers_parser = OpenapiParameters::Header.new(header_parameters) if header_parameters
+      @cookies_parser = OpenapiParameters::Cookie.new(cookie_parameters) if cookie_parameters
+      @body_parser = BodyParser.new(content_type) if content_type
+    end
+
+    attr_reader :query, :path, :headers, :cookies
+
+    def parse(request, route_params:)
+      result = {}
+      result[:path] = @path_parser.unpack(route_params) if @path_parser
+      result[:query] = @query_parser.unpack(request.env[Rack::QUERY_STRING]) if @query_parser
+      result[:headers] = @headers_parser.unpack_env(request.env) if @headers_parser
+      result[:cookies] = @cookies_parser.unpack(request.env[Rack::HTTP_COOKIE]) if @cookies_parser
+      result[:body] = @body_parser.parse(request) if @body_parser
+      result
+    end
+  end
+end

data/lib/openapi_first/request_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'failure'
+require_relative 'validators/request_parameters'
+require_relative 'validators/request_body'
+
+module OpenapiFirst
+  # Validates a Request against a request definition.
+  class RequestValidator
+    VALIDATORS = [
+      Validators::RequestParameters,
+      Validators::RequestBody
+    ].freeze
+
+    def initialize(request_definition, openapi_version:, hooks: {})
+      @validators = VALIDATORS.filter_map do |klass|
+        klass.for(request_definition, hooks:, openapi_version:)
+      end
+    end
+
+    def call(parsed_request)
+      @validators.each { |v| v.call(parsed_request) }
+    end
+  end
+end

data/lib/openapi_first/response.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'response_parser'
+require_relative 'response_validator'
+require_relative 'validated_response'
+
+module OpenapiFirst
+  # Represents a response definition in the OpenAPI document.
+  # This is not a direct reflecton of the OpenAPI 3.X response definition, but a combination of
+  # status, content type and content schema.
+  class Response
+    def initialize(status:, headers:, content_type:, content_schema:, openapi_version:)
+      @status = status
+      @content_type = content_type
+      @content_schema = content_schema
+      @headers = headers
+      @headers_schema = build_headers_schema(headers)
+      @parser = ResponseParser.new(headers:, content_type:)
+      @validator = ResponseValidator.new(self, openapi_version:)
+    end
+
+    # @attr_reader [Integer] status The HTTP status code of the response definition.
+    # @attr_reader [String, nil] content_type Content type of this response.
+    # @attr_reader [Schema, nil] content_schema the Schema of the response body.
+    attr_reader :status, :content_type, :content_schema, :headers, :headers_schema
+
+    def validate(response)
+      parsed_values = @parser.parse(response)
+      error = @validator.call(parsed_values)
+      ValidatedResponse.new(response, parsed_values:, error:, response_definition: self)
+    end
+
+    private
+
+    def parse(request)
+      @parser.parse(request)
+    end
+
+    def build_headers_schema(headers_object)
+      return unless headers_object&.any?
+
+      properties = {}
+      required = []
+      headers_object.each do |name, header|
+        schema = header['schema']
+        next if name.casecmp('content-type').zero?
+
+        properties[name] = schema if schema
+        required << name if header['required']
+      end
+      {
+        'properties' => properties,
+        'required' => required
+      }
+    end
+  end
+end

data/lib/openapi_first/response_parser.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  ParsedResponse = Data.define(:body, :headers)
+
+  # Parse a response
+  class ResponseParser
+    def initialize(headers:, content_type:)
+      @headers = headers
+      @content_type = content_type
+    end
+
+    attr_reader :headers, :content_type
+
+    def parse(rack_response)
+      ParsedResponse.new(
+        body: parse_body(rack_response),
+        headers: parse_headers(rack_response)
+      )
+    end
+
+    private
+
+    def parse_body(rack_response)
+      MultiJson.load(read_body(rack_response)) if /json/i.match?(content_type)
+    rescue MultiJson::ParseError
+      Failure.fail!(:invalid_response_body, message: 'Response body is invalid: Failed to parse response body as JSON')
+    end
+
+    def read_body(rack_response)
+      buffered_body = +''
+      if rack_response.body.respond_to?(:each)
+        rack_response.body.each { |chunk| buffered_body.to_s << chunk }
+        return buffered_body
+      end
+      rack_response.body
+    end
+
+    def parse_headers(rack_response)
+      return {} if headers.nil?
+
+      # TODO: memoize unpacker
+      headers_as_parameters = headers.map do |name, definition|
+        definition.merge('name' => name, 'in' => 'header')
+      end
+      OpenapiParameters::Header.new(headers_as_parameters).unpack(rack_response.headers)
+    end
+  end
+end

data/lib/openapi_first/response_validator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'validators/response_headers'
+require_relative 'validators/response_body'
+
+module OpenapiFirst
+  # Entry point for response validators
+  class ResponseValidator
+    VALIDATORS = [
+      Validators::ResponseHeaders,
+      Validators::ResponseBody
+    ].freeze
+
+    def initialize(response_definition, openapi_version:)
+      @validators = VALIDATORS.filter_map do |klass|
+        klass.for(response_definition, openapi_version:)
+      end
+    end
+
+    def call(parsed_response)
+      catch FAILURE do
+        @validators.each { |v| v.call(parsed_response) }
+        nil
+      end
+    end
+  end
+end

data/lib/openapi_first/router/find_content.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Router
+    # @visibility private
+    module FindContent
+      def self.call(contents, content_type)
+        return contents[nil] if content_type.nil? || content_type.empty?
+
+        contents.fetch(content_type) do
+          type = content_type.split(';')[0]
+          contents[type] || contents["#{type.split('/')[0]}/*"] || contents['*/*'] || contents[nil]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/router/find_response.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'find_content'
+
+module OpenapiFirst
+  class Router
+    # @visibility private
+    module FindResponse
+      Match = Data.define(:response, :error)
+
+      def self.call(responses, status, content_type, request_method:, path:)
+        contents = find_status(responses, status)
+        if contents.nil?
+          message = "Status #{status} is not defined for #{request_method} #{path}. " \
+                    "Defined statuses are: #{responses.keys.join(', ')}."
+          return Match.new(error: Failure.new(:response_not_found, message:), response: nil)
+        end
+        response = FindContent.call(contents, content_type)
+        if response.nil?
+          message = "#{content_error(content_type, request_method:,
+                                                   path:)} Content-Type should be #{contents.keys.join(' or ')}."
+          return Match.new(error: Failure.new(:response_not_found, message:), response: nil)
+        end
+
+        Match.new(response:, error: nil)
+      end
+
+      def self.content_error(content_type, request_method:, path:)
+        return 'Response Content-Type must not be empty.' if content_type.nil? || content_type.empty?
+
+        "Response Content-Type #{content_type} is not defined for #{request_method} #{path}."
+      end
+
+      def self.find_status(responses, status)
+        # According to OAS status has to be a string,
+        # but there are a few API descriptions out there that use integers because of YAML.
+
+        responses[status] || responses[status.to_s] ||
+          responses["#{status / 100}XX"] ||
+          responses["#{status / 100}xx"] ||
+          responses['default']
+      end
+    end
+  end
+end