openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/lib/openapi_first/failure.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # 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
+    TYPES = {
+      not_found: [NotFoundError, 'Not found.'],
+      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_content_type_not_found: [ResponseNotFoundError],
+      response_status_not_found: [ResponseNotFoundError],
+      invalid_response_body: [ResponseInvalidError, 'Response body is invalid:'],
+      invalid_response_header: [ResponseInvalidError, 'Response header is invalid:']
+    }.freeze
+    private_constant :TYPES
+
+    # @param type [Symbol] See Failure::TYPES.keys
+    # @param errors [Array<OpenapiFirst::Schema::ValidationError>]
+    def self.fail!(type, message: nil, errors: nil)
+      throw FAILURE, new(
+        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(type, message: nil, errors: nil)
+      unless TYPES.key?(type)
+        raise ArgumentError,
+              "type must be one of #{TYPES.keys} but was #{type.inspect}"
+      end
+
+      @type = type
+      @message = message
+      @errors = errors
+    end
+
+    # @attr_reader [Symbol] type The type of the failure. See TYPES.keys.
+    # Example: :invalid_body
+    attr_reader :type
+
+    # @attr_reader [Array<OpenapiFirst::Schema::ValidationError>] errors Schema validation errors
+    attr_reader :errors
+
+    # 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(type)
+
+      [message_prefix, @message || generate_message].compact.join(' ')
+    end
+
+    private
+
+    def generate_message
+      messages = errors&.take(3)&.map(&:message)
+      messages << "... (#{errors.size} errors total)" if errors && errors.size > 3
+      messages&.join('. ')
+    end
+  end
+end

data/lib/openapi_first/file_loader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module OpenapiFirst
+  # @!visibility private
+  module FileLoader
+    module_function
+
+    def load(file_path)
+      raise FileNotFoundError, "File not found #{file_path.inspect}" unless File.exist?(file_path)
+
+      body = File.read(file_path)
+      extname = File.extname(file_path)
+      return ::JSON.parse(body) if extname == '.json'
+      return YAML.unsafe_load(body) if ['.yaml', '.yml'].include?(extname)
+
+      body
+    end
+  end
+end

data/lib/openapi_first/header.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  Header = Data.define(:name, :required?, :schema, :node) do
+    def resolved_schema
+      node['schema']&.resolved
+    end
+  end
+end

data/lib/openapi_first/json.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# This tries to load MultiJson if available to keep compatibility
+# with MultiJson until next major version
+
+begin
+  require 'multi_json'
+  module OpenapiFirst
+    # Compatibility with MultiJson
+    # @visibility private
+    module JSON
+      ParserError = MultiJson::ParseError
+
+      def self.parse(string)
+        MultiJson.load(string)
+      end
+
+      def self.generate(object)
+        MultiJson.dump(object)
+      end
+    end
+  end
+rescue LoadError
+  require 'json'
+end

data/lib/openapi_first/middlewares/request_validation.rb

@@ -0,0 +1,58 @@
+# 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 spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #   If you pass a Symbol, it will load the OAD registered via `OpenapiFirst.register`
+      #   If you leave this blank, it will load the OAD registered as `:default`
+      # @param options Hash
+      #   :spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #         This will be deprecated. Please use spec argument instead.
+      #   :raise_error    A Boolean indicating whether to raise an error if validation fails.
+      #                   default: false
+      #   :error_response The Class to use for error responses.
+      #                   This can be a Symbol-name of an registered error response (:default, :jsonapi)
+      #                   or it can be set to false to disable returning a response.
+      #                   default: OpenapiFirst::Plugins::Default::ErrorResponse (Config.default_options.error_response)
+      def initialize(app, spec = nil, options = {})
+        @app = app
+        if spec.is_a?(Hash)
+          options = spec
+          spec = options[:spec]
+        end
+        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.request_validation_raise_error)
+        @error_response_class = error_response_option(options[:error_response])
+
+        spec ||= :default
+        spec = OpenapiFirst[spec] if spec.is_a?(Symbol)
+
+        @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
+      end
+
+      # @attr_reader [Proc] app The upstream Rack application
+      attr_reader :app
+
+      def call(env)
+        validated = @definition.validate_request(Rack::Request.new(env), raise_error: @raise)
+        env[REQUEST] = validated
+        failure = validated.error
+        return @error_response_class.new(failure:).render if failure && @error_response_class
+
+        @app.call(env)
+      end
+
+      private
+
+      def error_response_option(value)
+        return if value == false
+        return OpenapiFirst.find_error_response(value) if value.is_a?(Symbol)
+
+        value || OpenapiFirst.configuration.request_validation_error_response
+      end
+    end
+  end
+end

data/lib/openapi_first/middlewares/response_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module OpenapiFirst
+  module Middlewares
+    # A Rack middleware to validate requests against an OpenAPI API description
+    class ResponseValidation
+      # @param spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #   If you pass a Symbol, it will load the OAD registered via `OpenapiFirst.register`
+      #   If you leave this blank, it will load the OAD registered as `:default`
+      # @param options Hash
+      #   :spec [String, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
+      #         This will be deprecated. Please use spec argument instead.
+      #   :raise_error [Boolean] Whether to raise an error if validation fails. default: true
+      def initialize(app, spec = nil, options = {})
+        @app = app
+        if spec.is_a?(Hash)
+          options = spec
+          spec = options[:spec]
+        end
+        @raise = options.fetch(:raise_error, OpenapiFirst.configuration.response_validation_raise_error)
+
+        spec ||= :default
+        spec = OpenapiFirst[spec] if spec.is_a?(Symbol)
+
+        @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
+      end
+
+      # @attr_reader [Proc] app The upstream Rack application
+      attr_reader :app
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        @definition.validate_response(Rack::Request.new(env), Rack::Response[status, headers, body],
+                                      raise_error: @raise)
+        [status, headers, body]
+      end
+    end
+  end
+end

data/lib/openapi_first/parsed_request.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  ParsedRequest = Data.define(:path, :query, :headers, :body, :cookies)
+end

data/lib/openapi_first/ref_resolver.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+module OpenapiFirst
+  # This is here to give traverse an OAD while keeping $refs intact
+  # @visibility private
+  module RefResolver
+    def self.load(filepath)
+      contents = OpenapiFirst::FileLoader.load(filepath)
+      self.for(contents, filepath:)
+    end
+
+    def self.for(value, filepath: nil, context: value)
+      case value
+      when ::Hash
+        resolver = Hash.new(value, context:, filepath:)
+        if value.key?('$ref')
+          probe = resolver.resolve_ref(value['$ref'])
+          return probe if probe.is_a?(Array)
+        end
+        resolver
+      when ::Array
+        Array.new(value, context:, filepath:)
+      when ::NilClass
+        nil
+      else
+        Simple.new(value)
+      end
+    end
+
+    # @visibility private
+    module Diggable
+      def dig(*keys)
+        keys.inject(self) do |result, key|
+          break unless result.respond_to?(:[])
+
+          result[key]
+        end
+      end
+    end
+
+    # @visibility private
+    module Resolvable
+      def initialize(value, context: value, filepath: nil)
+        @value = value
+        @context = context
+        @filepath = filepath
+        @dir = if filepath
+                 File.dirname(File.absolute_path(filepath))
+               else
+                 Dir.pwd
+               end
+      end
+
+      # The value of this node
+      attr_reader :value
+      # The path of the file sytem directory where this was loaded from
+      attr_reader :dir
+      # The object where this node was found in
+      attr_reader :context
+
+      attr_reader :filepath
+
+      def ==(_other)
+        raise "Don't call == on an unresolved value. Use .value == other instead."
+      end
+
+      def resolve_ref(pointer)
+        if pointer.start_with?('#')
+          value = Hana::Pointer.new(pointer[1..]).eval(context)
+          raise "Unknown reference #{pointer} in #{context}" unless value
+
+          return RefResolver.for(value, filepath:, context:)
+        end
+
+        relative_path, file_pointer = pointer.split('#')
+        full_path = File.expand_path(relative_path, dir)
+        return RefResolver.load(full_path) unless file_pointer
+
+        file_contents = FileLoader.load(full_path)
+        value = Hana::Pointer.new(file_pointer).eval(file_contents)
+        RefResolver.for(value, filepath: full_path, context: file_contents)
+      rescue OpenapiFirst::FileNotFoundError => e
+        message = "Problem with reference resolving #{pointer.inspect} in " \
+                  "file #{File.absolute_path(filepath).inspect}: #{e.message}"
+        raise OpenapiFirst::FileNotFoundError, message
+      end
+    end
+
+    # @visibility private
+    class Simple
+      include Resolvable
+
+      def resolved = value
+    end
+
+    # @visibility private
+    class Hash
+      include Resolvable
+      include Diggable
+      include Enumerable
+
+      def ==(_other)
+        raise "Don't call == on an unresolved value. Use .value == other instead."
+      end
+
+      def resolved
+        return resolve_ref(value['$ref']).value if value.key?('$ref')
+
+        value
+      end
+
+      def [](key)
+        return resolve_ref(@value['$ref'])[key] if !@value.key?(key) && @value.key?('$ref')
+
+        RefResolver.for(@value[key], filepath:, context:)
+      end
+
+      def fetch(key)
+        return resolve_ref(@value['$ref']).fetch(key) if !@value.key?(key) && @value.key?('$ref')
+
+        RefResolver.for(@value.fetch(key), filepath:, context:)
+      end
+
+      def each
+        resolved.each_key do |key|
+          yield key, self[key]
+        end
+      end
+
+      # You have to pass configuration or ref_resolver
+      def schema(options)
+        base_uri = URI::File.build({ path: "#{dir}/" })
+        Schema.new(value:, context:, base_uri:, options:)
+      end
+    end
+
+    # @visibility private
+    # Defers initialization JSONSchemer::Schema, because that takes time.
+    class Schema
+      extend Forwardable
+
+      def initialize(value:, context:, base_uri:, options:)
+        @value = value
+        @context = context
+        @base_uri = base_uri
+        @options = options
+      end
+
+      attr_reader :value, :context, :base_uri, :options
+
+      def_delegators :schema, :validate, :valid?
+
+      def schema
+        @schema ||= begin
+          root_schema = JSONSchemer::Schema.new(context, base_uri:, **options)
+          JSONSchemer::Schema.new(value, nil, root_schema, base_uri:, **options)
+        end
+      end
+    end
+
+    # @visibility private
+    class Array
+      include Enumerable
+      include Resolvable
+      include Diggable
+
+      def [](index)
+        item = @value[index]
+        return resolve_ref(item['$ref']) if item.is_a?(::Hash) && item.key?('$ref')
+
+        RefResolver.for(item, filepath:, context:)
+      end
+
+      def each
+        resolved.each_with_index do |_item, index|
+          yield self[index]
+        end
+      end
+
+      def resolved
+        value.map do |item|
+          if item.respond_to?(:key?) && item.key?('$ref')
+            resolve_ref(item['$ref']).resolved
+          else
+            item
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/registry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class NotRegisteredError < Error; end
+  class AlreadyRegisteredError < Error; end
+
+  # @visibility private
+  module Registry
+    def definitions
+      @definitions ||= {}
+    end
+
+    # Register an OpenAPI definition for testing
+    # @param path_or_definition [String, Definition] Path to the OpenAPI file or a Definition object
+    # @param as [Symbol] Name to register the API definition as
+    def register(path_or_definition, as: :default)
+      if definitions.key?(as) && as == :default
+        raise(
+          AlreadyRegisteredError,
+          "#{definitions[as].inspect} is already registered " \
+          "as ':default' so you cannot register #{path_or_definition.inspect} without " \
+          'giving it a custom name. Please call register with a custom key like: ' \
+          "#{name}.register(#{path_or_definition.inspect}, as: :my_other_api)"
+        )
+      end
+
+      definition = OpenapiFirst.load(path_or_definition)
+      definitions[as] = definition
+      definition
+    end
+
+    def [](api)
+      return api if api.is_a?(Definition)
+
+      definitions.fetch(api) do
+        option = api == :default ? '' : ", as: #{api.inspect}"
+        raise(NotRegisteredError,
+              "API description '#{api.inspect}' not found." \
+              "Please call #{name}.register('myopenapi.yaml'#{option}) " \
+              'once before running your app.')
+      end
+    end
+  end
+end

data/lib/openapi_first/request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'openapi_parameters'
+require_relative 'parsed_request'
+require_relative 'request_validator'
+require_relative 'validated_request'
+require_relative 'request_body_parsers'
+
+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:, # rubocop:disable Metrics/MethodLength
+                   parameters:, content_type:, content_schema:, required_body:, key:)
+      @path = path
+      @request_method = request_method
+      @content_type = content_type
+      @content_schema = content_schema
+      @operation = operation_object
+      @allow_empty_content = content_type.nil? || required_body == false
+      @key = key
+      @query_parser = parameters.query&.then { |params| OpenapiParameters::Query.new(params) }
+      @path_parser = parameters.path&.then { |params| OpenapiParameters::Path.new(params) }
+      @headers_parser = parameters.header&.then { |params| OpenapiParameters::Header.new(params) }
+      @cookies_parser = parameters.cookie&.then { |params| OpenapiParameters::Cookie.new(params) }
+      @body_parsers = RequestBodyParsers[content_type] if content_type
+      @validator = RequestValidator.new(
+        content_schema:,
+        required_request_body: required_body == true,
+        path_schema: parameters.path_schema,
+        query_schema: parameters.query_schema,
+        header_schema: parameters.header_schema,
+        cookie_schema: parameters.cookie_schema
+      )
+      @parameters = parameters
+    end
+
+    attr_reader :content_type, :content_schema, :operation, :request_method, :path, :key, :query_schema, :parameters
+    private attr_reader :query_parser
+
+    def allow_empty_content?
+      @allow_empty_content
+    end
+
+    def validate(request, route_params:)
+      parsed_request = nil
+      error = catch FAILURE do
+        parsed_request = parse_request(request, route_params:)
+        @validator.call(parsed_request)
+        nil
+      end
+      ValidatedRequest.new(request, parsed_request:, error:, request_definition: self, query_parser:)
+    end
+
+    def operation_id
+      @operation['operationId']
+    end
+
+    private
+
+    def parse_request(request, route_params:)
+      ParsedRequest.new(
+        path: @path_parser&.unpack(route_params),
+        query: parse_query(request.env[Rack::QUERY_STRING]),
+        headers: @headers_parser&.unpack_env(request.env),
+        cookies: @cookies_parser&.unpack(request.env[Rack::HTTP_COOKIE]),
+        body: @body_parsers&.call(request)
+      )
+    end
+
+    def parse_query(query_string)
+      @query_parser&.unpack(query_string)
+    rescue OpenapiParameters::InvalidParameterError
+      Failure.fail!(:invalid_query, message: 'Invalid query parameter.')
+    end
+  end
+end

data/lib/openapi_first/request_body_parsers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # @!visibility private
+  module RequestBodyParsers
+    DEFAULT = ->(request) { Utils.read_body(request) }
+
+    @parsers = {}
+
+    class << self
+      attr_reader :parsers
+
+      def register(pattern, parser)
+        parsers[pattern] = parser
+      end
+
+      def [](content_type)
+        key = parsers.keys.find { content_type.match?(_1) }
+        parsers.fetch(key) { DEFAULT }
+      end
+    end
+
+    # Not sure where to put this
+    module Utils
+      def self.read_body(request)
+        body = request.body&.read
+        request.body.rewind if request.body.respond_to?(:rewind)
+        body
+      end
+    end
+
+    register(/json/i, lambda do |request|
+      body = Utils.read_body(request)
+      JSON.parse(body) unless body.nil? || body.empty?
+    rescue JSON::ParserError
+      Failure.fail!(:invalid_body, message: 'Failed to parse request body as JSON')
+    end)
+
+    # Parses multipart/form-data requests and currently puts the contents of a file upload at the parsed hash values.
+    # NOTE: This behavior will probably change in the next major version.
+    #       The uploaded file should not be read during request validation.
+    module MultipartBodyParser
+      def self.call(request)
+        request.POST.transform_values do |value|
+          unpack_value(value)
+        end
+      end
+
+      def self.unpack_value(value)
+        return value.map { unpack_value(_1) } if value.is_a?(Array)
+        return value unless value.is_a?(Hash)
+        return value[:tempfile]&.read if value.key?(:tempfile)
+
+        value.transform_values do |v|
+          unpack_value(v)
+        end
+      end
+    end
+
+    register('multipart/form-data', MultipartBodyParser)
+
+    register('application/x-www-form-urlencoded', lambda(&:POST))
+  end
+end

data/lib/openapi_first/request_validator.rb

@@ -0,0 +1,32 @@
+# 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
+    def initialize(
+      content_schema:,
+      required_request_body:,
+      path_schema:,
+      query_schema:,
+      header_schema:,
+      cookie_schema:
+    )
+      @validators = []
+      @validators << Validators::RequestBody.new(content_schema:, required_request_body:) if content_schema
+      @validators.concat Validators::RequestParameters.for(
+        path_schema:,
+        query_schema:,
+        header_schema:,
+        cookie_schema:
+      )
+    end
+
+    def call(parsed_request)
+      @validators.each { |v| v.call(parsed_request) }
+    end
+  end
+end