openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/lib/openapi_first/test/plain_helpers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Assertion methods to use when no known test framework was found
+    # These methods just raise an exception if an error was found
+    module PlainHelpers
+      def assert_api_conform(status: nil, api: openapi_first_default_api)
+        api = OpenapiFirst::Test[api]
+        # :nocov:
+        request = respond_to?(:last_request) ? last_request : @request
+        response = respond_to?(:last_response) ? last_response : @response
+        # :nocov:
+
+        if status && status != response.status
+          raise OpenapiFirst::Error,
+                "Expected status #{status}, but got #{response.status} " \
+                "from #{request.request_method.upcase} #{request.path}."
+        end
+
+        validated = api.validate_request(request, raise_error: false)
+        # :nocov:
+        raise validated.error.exception if validated.invalid?
+
+        validated = api.validate_response(request, response, raise_error: false)
+        raise validated.error.exception if validated.invalid?
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/openapi_first/test.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require_relative 'test/configuration'
+require_relative 'registry'
+
+module OpenapiFirst
+  # Test integration
+  module Test # rubocop:disable Metrics/ModuleLength
+    autoload :Coverage, 'openapi_first/test/coverage'
+    autoload :Methods, 'openapi_first/test/methods'
+    autoload :Observe, 'openapi_first/test/observe'
+    autoload :App, 'openapi_first/test/app'
+    extend Registry
+
+    class CoverageError < Error; end
+    class UnknownQueryParameterError < Error; end
+
+    # Inject request/response validation in a rack app class
+    def self.observe(app, api: :default)
+      Observe.observe(app, api:)
+    end
+
+    def self.minitest?(base)
+      base.include?(::Minitest::Assertions)
+    rescue NameError
+      false
+    end
+
+    def self.definitions
+      super.empty? ? OpenapiFirst.definitions : super
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.registered?(oad)
+      key = oad.key
+      definitions.any? { |(_name, registered)| registered.key == key }
+    end
+
+    # Sets up OpenAPI test coverage and OAD registration.
+    # @yieldparam [OpenapiFirst::Test::Configuration] configuration A configuration to setup test integration
+    def self.setup
+      install
+      yield configuration if block_given?
+
+      Coverage.start(skip_response: configuration.skip_response_coverage, skip_route: configuration.skip_coverage)
+
+      if definitions.empty?
+        raise NotRegisteredError,
+              'No API descriptions have been registered. ' \
+              'Please register your API description via ' \
+              "`OpenapiFirst.register('myopenapi.yaml)` or " \
+              'in a block passed to `OpenapiFirst::Test.setup` like this: ' \
+              "`OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }` " \
+
+      end
+
+      @exit_handler = method(:handle_exit)
+
+      main_process = Process.pid
+      @setup ||= at_exit do
+        # :nocov:
+        # Only handle exit once in the main process
+        @exit_handler&.call if Process.pid == main_process
+        # :nocov:
+      end
+    end
+
+    def self.handle_exit
+      return unless configuration.report_coverage
+
+      report_coverage(
+        formatter: configuration.coverage_formatter,
+        **configuration.coverage_formatter_options
+      )
+      return unless configuration.report_coverage == true
+
+      coverage = Coverage.result.coverage
+      return if coverage >= configuration.minimum_coverage
+
+      puts "API Coverage fails with exit 2, because not all described requests and responses have been tested (#{coverage.round(4)}% covered)." # rubocop:disable Layout/LineLength
+
+      exit 2
+    end
+
+    # Print the coverage report
+    # @param formatter A formatter to define the report.
+    # @output [IO] An output where to puts the report.
+    def self.report_coverage(formatter: Coverage::TerminalFormatter, **)
+      puts formatter.new(**).format(Coverage.result)
+    end
+
+    # Returns the Rack app wrapped with silent request, response validation
+    # You can use this if you want to track coverage via Test::Coverage, but don't want to use
+    # the middlewares or manual request, response validation.
+    def self.app(app, spec: nil, api: :default)
+      spec ||= self[api]
+      App.new(app, api: spec)
+    end
+
+    def self.install
+      return if @installed
+
+      OpenapiFirst.configure do |config|
+        @after_request_validation = config.after_request_validation do |validated_request, oad|
+          next unless registered?(oad)
+          raise validated_request.error.exception if raise_request_error?(validated_request)
+
+          check_unknown_query_parameters(validated_request)
+
+          Coverage.track_request(validated_request, oad)
+        end
+
+        @after_response_validation = config.after_response_validation do |validated_response, rack_request, oad|
+          next unless registered?(oad)
+          if validated_response.invalid? && raise_response_error?(validated_response)
+            raise validated_response.error.exception
+          end
+
+          Coverage.track_response(validated_response, rack_request, oad)
+        end
+      end
+      @installed = true
+    end
+
+    def self.uninstall
+      configuration = OpenapiFirst.configuration
+      configuration.after_request_validation.delete(@after_request_validation)
+      configuration.after_response_validation.delete(@after_response_validation)
+      definitions.clear
+      @configuration = nil
+      @installed = nil
+      @exit_handler = nil
+    end
+
+    class << self
+      private
+
+      def check_unknown_query_parameters(validated_request)
+        return unless validated_request.known?
+
+        unknown_parameters = validated_request.unknown_query_parameters
+        return unless unknown_parameters
+
+        message = unknown_parameters_message(unknown_parameters, validated_request)
+        raise UnknownQueryParameterError, message
+      end
+
+      def unknown_parameters_message(unknown_parameters, validated_request)
+        s = 's' if many?(unknown_parameters)
+        list = unknown_parameters.keys.map(&:inspect).join(', ')
+        "Unknown query parameter#{s} #{list} for #{validated_request.fullpath}"
+      end
+
+      def raise_request_error?(validated_request)
+        return false if validated_request.valid?
+        return false if validated_request.known?
+
+        !configuration.ignore_unknown_requests
+      end
+
+      def many?(array) = array.length > 1
+
+      def raise_response_error?(invalid_response)
+        configuration.response_raise_error && !configuration.ignore_response?(invalid_response)
+      end
+    end
+  end
+end

data/lib/openapi_first/validated_request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'delegate'
+
+module OpenapiFirst
+  # A validated request. It can be valid or not.
+  class ValidatedRequest < SimpleDelegator
+    extend Forwardable
+
+    def initialize(original_request, error:, parsed_request: nil, request_definition: nil, query_parser: nil)
+      super(original_request)
+      @parsed_request = parsed_request
+      @error = error
+      @request_definition = request_definition
+      @query_parser = query_parser
+    end
+
+    # A Failure object if the request is invalid
+    # @return [Failure, nil]
+    attr_reader :error
+
+    # The request definition if this request is defined in the API description
+    # @return [Request, nil]
+    attr_reader :request_definition
+
+    # @!method operation_id
+    # @return [String, nil] The OpenAPI 3 operationId
+    def_delegator :request_definition, :operation_id
+
+    # @!method operation
+    # @return [Hash] The raw OpenAPI 3 operation object
+    def_delegator :request_definition, :operation
+
+    # @return [Hash] Query parameters and values that are not defined in the OpenAPI spec.
+    def unknown_query_parameters
+      @query_parser&.unknown_values(query_string)
+    end
+
+    # Parsed path parameters
+    # @return [Hash<String, anything>]
+    def parsed_path_parameters = @parsed_request&.path || {}
+
+    # Parsed query parameters. This only returns the query parameters that are defined in the OpenAPI spec.
+    # @return [Hash<String, anything>]
+    def parsed_query = @parsed_request&.query || {}
+
+    # Parsed headers. This only returns the query parameters that are defined in the OpenAPI spec.
+    # @return [Hash<String, anything>]
+    def parsed_headers = @parsed_request&.headers || {}
+
+    # Parsed cookies. This only returns the query parameters that are defined in the OpenAPI spec.
+    # @return [Hash<String, anything>]
+    def parsed_cookies = @parsed_request&.cookies || {}
+
+    # Parsed body. This parses the body according to the content type.
+    # Note that this returns the hole body, not only the fields that are defined in the OpenAPI spec.
+    # You can use JSON Schemas `additionalProperties` or `unevaluatedProperties` to
+    # return a validation error if the body contains unknown fields.
+    # @return [Hash<String, anything>, anything]
+    def parsed_body = @parsed_request&.body
+
+    # Checks if the request is valid.
+    def valid? = error.nil?
+
+    # Checks if the request is invalid.
+    def invalid? = !valid?
+
+    # Returns true if the request is defined.
+    def known? = request_definition != nil
+
+    # Merged path, query, body parameters.
+    # Here path has the highest precedence, then query, then body.
+    # @return [Hash<String, anything>]
+    def parsed_params
+      @parsed_params ||= parsed_body.to_h.merge(parsed_query, parsed_path_parameters) || {}
+    end
+  end
+end

data/lib/openapi_first/validated_response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'delegate'
+
+module OpenapiFirst
+  # A validated response. It can be valid or not.
+  class ValidatedResponse < SimpleDelegator
+    extend Forwardable
+
+    def initialize(original_response, error:, parsed_values: nil, response_definition: nil)
+      super(original_response)
+      @error = error
+      @parsed_values = parsed_values
+      @response_definition = response_definition
+    end
+
+    # A Failure object if the response is invalid
+    # @return [Failure, nil]
+    attr_reader :error
+
+    # The response definition if this response is defined in the API description
+    # @return [Response, nil]
+    attr_reader :response_definition
+
+    # The parsed headers
+    # @return [Hash<String,anything>, nil]
+    def parsed_headers
+      @parsed_values&.headers
+    end
+
+    # The parsed body
+    # @return [Hash<String,anything>, nil]
+    def parsed_body
+      @parsed_values&.body
+    end
+
+    # Checks if the response is valid.
+    # @return [Boolean] true if the response is valid, false otherwise.
+    def valid?
+      error.nil?
+    end
+
+    # Returns true if the response is defined.
+    def known? = response_definition != nil
+
+    # Checks if the response is invalid.
+    # @return [Boolean]
+    def invalid?
+      !valid?
+    end
+  end
+end

data/lib/openapi_first/validators/request_body.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class RequestBody
+      def initialize(content_schema:, required_request_body:)
+        @schema = content_schema
+        @required = required_request_body
+      end
+
+      def call(parsed_request)
+        body = parsed_request.body
+        if body.nil?
+          Failure.fail!(:invalid_body, message: 'Request body must not be empty') if @required
+          return
+        end
+
+        validation = Schema::ValidationResult.new(
+          @schema.validate(body, access_mode: 'write')
+        )
+        Failure.fail!(:invalid_body, errors: validation.errors) if validation.error?
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/request_parameters.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    module RequestParameters
+      RequestHeaders = Data.define(:schema) do
+        def call(parsed_request)
+          validation = schema.validate(parsed_request.headers)
+          Failure.fail!(:invalid_header, errors: validation.errors) if validation.error?
+        end
+      end
+
+      Path = Data.define(:schema) do
+        def call(parsed_request)
+          validation = schema.validate(parsed_request.path)
+          Failure.fail!(:invalid_path, errors: validation.errors) if validation.error?
+        end
+      end
+
+      Query = Data.define(:schema) do
+        def call(parsed_request)
+          validation = schema.validate(parsed_request.query)
+          Failure.fail!(:invalid_query, errors: validation.errors) if validation.error?
+        end
+      end
+
+      RequestCookies = Data.define(:schema) do
+        def call(parsed_request)
+          validation = schema.validate(parsed_request.cookies)
+          Failure.fail!(:invalid_cookie, errors: validation.errors) if validation.error?
+        end
+      end
+
+      VALIDATORS = {
+        path_schema: Path,
+        query_schema: Query,
+        header_schema: RequestHeaders,
+        cookie_schema: RequestCookies
+      }.freeze
+
+      def self.for(args)
+        VALIDATORS.filter_map do |key, klass|
+          schema = args[key]
+          klass.new(schema) if schema
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/response_body.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../schema/validation_result'
+
+module OpenapiFirst
+  module Validators
+    class ResponseBody
+      def initialize(schema)
+        @schema = schema
+      end
+
+      attr_reader :schema
+
+      def call(response)
+        begin
+          parsed_body = response.body
+        rescue ParseError => e
+          Failure.fail!(:invalid_response_body, message: e.message)
+        end
+        validation = Schema::ValidationResult.new(
+          schema.validate(parsed_body, access_mode: 'read')
+        )
+        Failure.fail!(:invalid_response_body, errors: validation.errors) if validation.error?
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/response_headers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class ResponseHeaders
+      def initialize(headers)
+        @headers = headers
+      end
+
+      attr_reader :headers
+
+      def call(parsed_response)
+        headers.each do |header|
+          header_value = parsed_response.headers[header.name]
+          next if header_value.nil? && !header.required?
+
+          validation_errors = header.schema.validate(header_value)
+          next unless validation_errors.any?
+
+          Failure.fail!(:invalid_response_header,
+                        errors: [error_for(data_pointer: "/#{header.name}", value: header_value,
+                                           error: validation_errors.first)])
+        end
+      end
+
+      private
+
+      def error_for(data_pointer:, value:, error:)
+        Schema::ValidationError.new(
+          value: value,
+          data_pointer:,
+          schema_pointer: error['schema_pointer'],
+          type: error['type'],
+          details: error['details'],
+          schema: error['schema']
+        )
+      end
+    end
+  end
+end

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '0.7.0.alpha1'
+  VERSION = '3.1.0.beta1'
 end

data/lib/openapi_first.rb

@@ -1,50 +1,82 @@
 # frozen_string_literal: true
 
-require 'yaml'
-require 'oas_parser'
-require 'openapi_first/definition'
-require 'openapi_first/version'
-require 'openapi_first/router'
-require 'openapi_first/request_validation'
-require 'openapi_first/response_validator'
-require 'openapi_first/operation_resolver'
-require 'openapi_first/app'
+require_relative 'openapi_first/json'
+require_relative 'openapi_first/file_loader'
+require_relative 'openapi_first/errors'
+require_relative 'openapi_first/registry'
+require_relative 'openapi_first/configuration'
+require_relative 'openapi_first/child_configuration'
+require_relative 'openapi_first/definition'
+require_relative 'openapi_first/version'
+require_relative 'openapi_first/middlewares/response_validation'
+require_relative 'openapi_first/middlewares/request_validation'
 
+# OpenapiFirst is a toolchain to build HTTP APIS based on OpenAPI API descriptions.
 module OpenapiFirst
-  OPERATION = 'openapi_first.operation'
-  PARAMS = 'openapi_first.params'
-  REQUEST_BODY = 'openapi_first.parsed_request_body'
-  HANDLER = 'openapi_first.handler'
-
-  def self.load(spec_path, only: nil)
-    content = YAML.load_file(spec_path)
-    raw = OasParser::Parser.new(spec_path, content).resolve
-    raw['paths'].filter!(&->(key, _) { only.call(key) }) if only
-    parsed = OasParser::Definition.new(raw, spec_path)
-    Definition.new(parsed)
+  extend Registry
+
+  autoload :Test, 'openapi_first/test'
+
+  # Key in rack to find instance of Request
+  REQUEST = 'openapi.request'
+
+  FAILURE = :openapi_first_validation_failure
+
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
   end
 
-  def self.app(spec, namespace:)
-    spec = OpenapiFirst.load(spec) if spec.is_a?(String)
-    App.new(nil, spec, namespace: namespace)
+  # @return [Configuration]
+  # @yield [Configuration]
+  def self.configure
+    yield configuration if block_given?
   end
 
-  def self.middleware(spec, namespace:)
-    spec = OpenapiFirst.load(spec) if spec.is_a?(String)
-    AppWithOptions.new(spec, namespace: namespace)
+  ERROR_RESPONSES = {} # rubocop:disable Style/MutableConstant
+  private_constant :ERROR_RESPONSES
+
+  # Register an error response class
+  # @param name [Symbol]
+  # @param klass [Class] A class that includes / implements OpenapiFirst::ErrorResponse
+  def self.register_error_response(name, klass)
+    ERROR_RESPONSES[name.to_sym] = klass
   end
 
-  class AppWithOptions
-    def initialize(spec, options)
-      @spec = spec
-      @options = options
+  # @param name [Symbol]
+  # @return [Class] The error response class
+  def self.find_error_response(name)
+    ERROR_RESPONSES.fetch(name) do
+      raise "Unknown error response: #{name}. " \
+            'Register your error response class via `OpenapiFirst.register_error_response(name, klass)`. ' \
+            "Registered error responses are: #{ERROR_RESPONSES.keys.join(', ')}."
     end
+  end
 
-    def new(app)
-      App.new(app, @spec, **@options)
-    end
+  # Load and dereference an OpenAPI spec file or return the Definition if it's already loaded
+  # @param filepath_or_definition [String, Definition] The path to the file or a Definition object
+  # @return [Definition]
+  def self.load(filepath_or_definition, only: nil, &)
+    return filepath_or_definition if filepath_or_definition.is_a?(Definition)
+    return self[filepath_or_definition] if filepath_or_definition.is_a?(Symbol)
+
+    filepath = filepath_or_definition
+    raise FileNotFoundError, "File not found: #{filepath}" unless File.exist?(filepath)
+
+    contents = FileLoader.load(filepath)
+    parse(contents, only:, filepath:, &)
   end
 
-  class Error < StandardError; end
-  # Your code goes here...
+  # Parse a dereferenced Hash
+  # @return [Definition]
+  # TODO: This needs to work with unresolved contents as well
+  def self.parse(contents, only: nil, filepath: nil, &)
+    contents = ::JSON.parse(::JSON.generate(contents)) # Deeply stringify keys, because of YAML. See https://github.com/ahx/openapi_first/issues/367
+    contents['paths'].filter!(&->(key, _) { only.call(key) }) if only
+    Definition.new(contents, filepath, &)
+  end
 end
+
+require_relative 'openapi_first/error_response'
+require_relative 'openapi_first/error_responses/default'
+require_relative 'openapi_first/error_responses/jsonapi'