openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/lib/openapi_first/response.rb

@@ -0,0 +1,43 @@
+# 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:, key:)
+      @status = status
+      @content_type = content_type
+      @content_schema = content_schema
+      @headers = headers
+      @key = key
+      @parser = ResponseParser.new(headers:, content_type:)
+      @validator = ResponseValidator.new(content_schema:, headers:)
+    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, :key
+
+    def validate(response)
+      parsed_values = nil
+      error = catch FAILURE do
+        parsed_values = @parser.parse(response)
+        nil
+      end
+      error ||= @validator.call(parsed_values)
+      ValidatedResponse.new(response, parsed_values:, error:, response_definition: self)
+    end
+
+    private
+
+    def parse(request)
+      @parser.parse(request)
+    end
+  end
+end

data/lib/openapi_first/response_body_parsers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # @visibility private
+  module ResponseBodyParsers
+    DEFAULT = ->(body) { body }
+
+    @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
+
+    register(/json/i, lambda do |body|
+      JSON.parse(body)
+    rescue JSON::ParserError
+      return Failure.fail!(:invalid_response_body, message: 'JSON response body must not be empty') if body.empty?
+
+      Failure.fail!(:invalid_response_body, message: 'Failed to parse response body as JSON')
+    end)
+  end
+end

data/lib/openapi_first/response_parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'response_body_parsers'
+
+module OpenapiFirst
+  ParsedResponse = Data.define(:body, :headers)
+
+  # Parse a response
+  class ResponseParser
+    def initialize(headers:, content_type:)
+      @headers_parser = build_headers_parser(headers)
+      @body_parser = ResponseBodyParsers[content_type]
+    end
+
+    def parse(rack_response)
+      ParsedResponse.new(
+        body: @body_parser.call(read_body(rack_response)),
+        headers: @headers_parser&.call(rack_response.headers) || {}
+      )
+    end
+
+    private
+
+    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
+    rescue TypeError
+      raise Error, "Cannot not read response body. Response is not string-like, but is a #{rack_response.body.class}."
+    end
+
+    def build_headers_parser(headers)
+      return unless headers&.any?
+
+      headers_as_parameters = headers.map do |header|
+        {
+          'name' => header.name,
+          'explode' => false,
+          'in' => 'header',
+          'schema' => header.resolved_schema
+        }
+      end
+      OpenapiParameters::Header.new(headers_as_parameters).method(:unpack)
+    end
+  end
+end

data/lib/openapi_first/response_validator.rb

@@ -1,59 +1,27 @@
 # frozen_string_literal: true
 
-require 'json_schemer'
-require 'multi_json'
-require_relative 'validation'
+require_relative 'validators/response_headers'
+require_relative 'validators/response_body'
 
 module OpenapiFirst
+  # Entry point for response validators
   class ResponseValidator
-    def initialize(spec)
-      @spec = spec
+    VALIDATORS = [
+      Validators::ResponseHeaders,
+      Validators::ResponseBody
+    ].freeze
+
+    def initialize(content_schema:, headers:)
+      @validators = []
+      @validators << Validators::ResponseBody.new(content_schema) if content_schema
+      @validators << Validators::ResponseHeaders.new(headers) if headers&.any?
     end
 
-    def validate(request, response)
-      errors = validation_errors(request, response)
-      Validation.new(errors || [])
-    rescue OasParser::ResponseCodeNotFound, OasParser::MethodNotFound => e
-      Validation.new([e.message])
-    end
-
-    private
-
-    def validation_errors(request, response)
-      content = response_for(request, response)&.content
-      return unless content
-
-      content_type = content[response.content_type]
-      unless content_type
-        return ["Content type not found: '#{response.content_type}'"]
-      end
-
-      response_schema = content_type['schema']
-      return unless response_schema
-
-      response_data = MultiJson.load(response.body)
-      validate_json_schema(response_schema, response_data)
-    end
-
-    def validate_json_schema(schema, data)
-      JSONSchemer.schema(schema).validate(data).to_a.map do |error|
-        format_error(error)
+    def call(parsed_response)
+      catch FAILURE do
+        @validators.each { |v| v.call(parsed_response) }
+        nil
       end
     end
-
-    def format_error(error)
-      ValidationFormat.error_details(error)
-                      .merge!(
-                        data_pointer: error['data_pointer'],
-                        schema_pointer: error['schema_pointer']
-                      ).tap do |formatted|
-      end
-    end
-
-    def response_for(request, response)
-      @spec
-        .find_operation!(request)
-        &.response_by_code(response.status.to_s, use_default: true)
-    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,53 @@
+# 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)
+        return response_status_not_found(status:, request_method:, path:, responses:) if contents.nil?
+
+        response = FindContent.call(contents, content_type)
+        return response_content_type_not_found(content_type:, contents:, request_method:, path:) unless response
+
+        Match.new(response:, error: nil)
+      end
+
+      def self.response_content_type_not_found(content_type:, contents:, request_method:, path:)
+        empty_content = content_type.nil? || content_type.empty?
+        message =
+          "Content-Type should be #{contents.keys.join(' or ')}, " \
+          "but was #{empty_content ? 'empty' : content_type} for " \
+          "#{request_method.upcase} #{path}"
+
+        Match.new(
+          error: Failure.new(:response_content_type_not_found, message:),
+          response: nil
+        )
+      end
+      private_class_method :response_content_type_not_found
+
+      def self.response_status_not_found(status:, request_method:, path:, responses:)
+        message = "Status #{status} is not defined for #{request_method.upcase} #{path}. " \
+                  "Defined statuses are: #{responses.keys.join(', ')}."
+        Match.new(error: Failure.new(:response_status_not_found, message:), response: nil)
+      end
+      private_class_method :response_status_not_found
+
+      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

data/lib/openapi_first/router/path_template.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  class Router
+    # @visibility private
+    class PathTemplate
+      # See also https://spec.openapis.org/oas/v3.1.0#path-templating
+      TEMPLATE_EXPRESSION = /(\{[^{}]+\})/
+      TEMPLATE_EXPRESSION_NAME = /\{([^{}]+)\}/
+      ALLOWED_PARAMETER_CHARACTERS = %r{([^/?#]+)}
+
+      def self.template?(string)
+        string.include?('{')
+      end
+
+      def initialize(template)
+        @template = template
+        @names = template.scan(TEMPLATE_EXPRESSION_NAME).flatten
+        @pattern = build_pattern(template)
+      end
+
+      def to_s
+        @template
+      end
+
+      def match(path)
+        return {} if path == @template
+        return if @names.empty?
+
+        matches = path.match(@pattern)
+        return unless matches
+
+        values = matches.captures
+        @names.zip(values).to_h
+      end
+
+      private
+
+      def build_pattern(template)
+        parts = template.split(TEMPLATE_EXPRESSION).map! do |part|
+          part.start_with?('{') ? ALLOWED_PARAMETER_CHARACTERS : Regexp.escape(part)
+        end
+
+        /^#{parts.join}$/
+      end
+    end
+  end
+end

data/lib/openapi_first/router.rb

@@ -1,84 +1,111 @@
 # frozen_string_literal: true
 
-require 'rack'
-require 'hanami/router'
-require_relative 'utils'
+require_relative 'router/path_template'
+require_relative 'router/find_content'
+require_relative 'router/find_response'
 
 module OpenapiFirst
+  # Router can map requests / responses to their API definition
   class Router
-    NOT_FOUND = Rack::Response.new('', 404).finish.freeze
+    # Returned by {#match}
+    RequestMatch = Data.define(:request_definition, :params, :error, :responses) do
+      def match_response(status:, content_type:)
+        FindResponse.call(responses, status, content_type, request_method: request_definition.request_method,
+                                                           path: request_definition.path)
+      end
+    end
+
+    # Returned by {#routes} to introspect all routes
+    Route = Data.define(:path, :request_method, :requests, :responses)
 
-    def initialize(app, options)
-      @app = app
-      @namespace = options.fetch(:namespace)
-      @parent_app = options.fetch(:parent_app, nil)
-      @router = build_router(options.fetch(:spec).operations)
+    NOT_FOUND = RequestMatch.new(request_definition: nil, params: nil, responses: nil, error: Failure.new(:not_found))
+    private_constant :NOT_FOUND
+
+    def initialize
+      @static = {}
+      @dynamic = {} # TODO: use a trie or similar
     end
 
-    def call(env)
-      route = @router.recognize(env)
-      return route.endpoint.call(env) if route.routable?
+    # Returns an enumerator of all routes
+    def routes
+      @static.chain(@dynamic).lazy.flat_map do |path, request_methods|
+        request_methods.filter_map do |request_method, content|
+          next if request_method == :template
 
-      return @parent_app.call(env) if @parent_app
+          Route.new(path:, request_method:, requests: content[:requests].each_value.lazy.uniq,
+                    responses: content[:responses].each_value.lazy.flat_map(&:values))
+        end
+      end
+    end
 
-      NOT_FOUND
+    # Add a request definition
+    def add_request(request, request_method:, path:, content_type: nil, allow_empty_content: false)
+      route = route_at(path, request_method)
+      requests = route[:requests]
+      requests[content_type] = request
+      requests[nil] = request if allow_empty_content
     end
 
-    def find_handler(operation_id) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      name = operation_id.match(/:*(.*)/)&.to_a&.at(1)
-      return if name.nil?
+    # Add a response definition
+    def add_response(response, request_method:, path:, status:, response_content_type: nil)
+      (route_at(path, request_method)[:responses][status] ||= {})[response_content_type] = response
+    end
 
-      if name.include?('.')
-        module_name, method_name = name.split('.')
-        klass = find_const(@namespace, module_name)
-        return klass&.method(Utils.underscore(method_name))
+    # Return all request objects that match the given path and request method
+    def match(request_method, path, content_type: nil)
+      path_item, params = find_path_item(path)
+      unless path_item
+        message = "Request path #{path} is not defined in API description."
+        return NOT_FOUND.with(error: Failure.new(:not_found, message:))
       end
-      if name.include?('#')
-        module_name, klass_name = name.split('#')
-        const = find_const(@namespace, module_name)
-        klass = find_const(const, klass_name)
-        return ->(params, res) { klass.new.call(params, res) }
+
+      contents = path_item.dig(request_method, :requests)
+      return NOT_FOUND.with(error: Failure.new(:method_not_allowed)) unless contents
+
+      request_definition = FindContent.call(contents, content_type)
+      unless request_definition
+        message = "#{content_type_err(content_type)} Content-Type should be #{contents.keys.join(' or ')}."
+        return NOT_FOUND.with(error: Failure.new(:unsupported_media_type, message:))
       end
-      method_name = Utils.underscore(name)
-      return unless @namespace.respond_to?(method_name)
 
-      @namespace.method(method_name)
+      responses = path_item.dig(request_method, :responses)
+      RequestMatch.new(request_definition:, params:, error: nil, responses:)
     end
 
     private
 
-    def find_const(parent, name)
-      name = Utils.classify(name)
-      return unless parent.const_defined?(name, false)
+    def route_at(path, request_method)
+      request_method = request_method.upcase
+      path_item = if PathTemplate.template?(path)
+                    @dynamic[path] ||= { template: PathTemplate.new(path) }
+                  else
+                    @static[path] ||= {}
+                  end
+      path_item[request_method] ||= {
+        requests: {},
+        responses: {}
+      }
+    end
+
+    def content_type_err(content_type)
+      return 'Content-Type must not be empty.' if content_type.nil? || content_type.empty?
 
-      parent.const_get(name, false)
+      "Content-Type #{content_type} is not defined."
     end
 
-    def build_router(operations) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      router = Hanami::Router.new {}
-      operations.each do |operation|
-        normalized_path = operation.path.gsub('{', ':').gsub('}', '')
-        if operation.operation_id.nil?
-          warn "operationId is missing in '#{operation.method} #{operation.path}'. I am ignoring this operation." # rubocop:disable Layout/LineLength
-          next
-        end
-        handler = find_handler(operation.operation_id)
-        if handler.nil?
-          warn "could not find handler for '#{operation.operation_id}' (#{operation.method} #{operation.path}). I am ignoring this operation." # rubocop:disable Layout/LineLength
-          next
-        end
-        router.public_send(
-          operation.method,
-          normalized_path,
-          to: lambda do |env|
-            env[OPERATION] = operation
-            env[PARAMS] = Utils.deep_stringify(env['router.params'])
-            env[HANDLER] = handler
-            @app.call(env)
-          end
-        )
+    def find_path_item(request_path)
+      found = @static[request_path]
+      return [found, {}] if found
+
+      matches = @dynamic.filter_map do |_path, path_item|
+        params = path_item[:template].match(request_path)
+        next unless params
+
+        [path_item, params]
       end
-      router
+      return matches.first if matches.length == 1
+
+      matches&.min_by { |match| match[1].values.sum(&:length) }
     end
   end
 end

data/lib/openapi_first/schema/hash.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'validation_error'
+
+module OpenapiFirst
+  module Schema
+    # A hash of Schemas
+    class Hash
+      # @param schema Hash of schemas
+      # @param required Array of required keys
+      def initialize(schemas, required: nil, **options)
+        @schemas = schemas
+        @options = options
+        @after_property_validation = options.delete(:after_property_validation)
+        schema = { 'type' => 'object' }
+        schema['required'] = required if required
+        @root_schema = JSONSchemer.schema(schema, **options)
+      end
+
+      def validate(root_value)
+        validation = @root_schema.validate(root_value)
+        validations = @schemas.reduce(validation) do |enum, (key, schema)|
+          root_value[key] = schema.value['default'] if schema.value.key?('default') && !root_value.key?(key)
+          next enum unless root_value.key?(key)
+
+          value = root_value[key]
+          key_validation = schema.validate(value)
+          @after_property_validation&.each do |hook|
+            hook.call(root_value, key, schema.value, nil)
+          end
+          enum.chain(key_validation.map do |err|
+            err.merge('data_pointer' => "/#{key}")
+          end)
+        end
+        ValidationResult.new(validations)
+      end
+    end
+  end
+end

data/lib/openapi_first/schema/validation_error.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Schema
+    # One of multiple validation errors. Returned by Schema::ValidationResult#errors.
+    ValidationError = Data.define(:value, :data_pointer, :schema_pointer, :type, :details, :schema) do
+      # This returns an error message for this specific error.
+      # This it copied from json_schemer here to be easier to customize when passing custom data_pointers.
+      def message
+        location = data_pointer.empty? ? 'root' : "`#{data_pointer}`"
+
+        case type
+        when 'required'
+          keys = details.fetch('missing_keys', []).join(', ')
+          "object at #{location} is missing required properties: #{keys}"
+        when 'dependentRequired'
+          keys = details.fetch('missing_keys').join(', ')
+          "object at #{location} is missing required properties: #{keys}"
+        when 'string', 'boolean', 'number'
+          "value at #{location} is not a #{type}"
+        when 'array', 'object', 'integer'
+          "value at #{location} is not an #{type}"
+        when 'null'
+          "value at #{location} is not #{type}"
+        when 'pattern'
+          "string at #{location} does not match pattern: #{schema.fetch('pattern')}"
+        when 'format'
+          "value at #{location} does not match format: #{schema.fetch('format')}"
+        when 'const'
+          "value at #{location} is not: #{schema.fetch('const').inspect}"
+        when 'enum'
+          "value at #{location} is not one of: #{schema.fetch('enum')}"
+        when 'minimum'
+          "number at #{location} is less than: #{schema['minimum']}"
+        when 'maximum'
+          "number at #{location} is greater than: #{schema['maximum']}"
+        when 'readOnly'
+          "value at #{location} is `readOnly`"
+        else
+          "value at #{location} is invalid (#{type.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/schema/validation_result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'validation_error'
+
+module OpenapiFirst
+  module Schema
+    # Result of validating data against a schema. Return value of Schema#validate.
+    class ValidationResult
+      def initialize(validation)
+        @validation = validation
+      end
+
+      def error? = @validation.any?
+
+      # Returns an array of ValidationError objects.
+      def errors
+        @errors ||= @validation.map do |err|
+          ValidationError.new(
+            value: err['data'],
+            data_pointer: err['data_pointer'],
+            schema_pointer: err['schema_pointer'],
+            type: err['type'],
+            details: err['details'],
+            schema: err['schema']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/app.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'observe'
+
+module OpenapiFirst
+  module Test
+    REQUEST = 'openapi.test.request'
+    RESPONSE = 'openapi.test.response'
+
+    # A wrapper of the original app
+    # with silent request/response validation to track requests/responses.
+    class App < SimpleDelegator
+      def initialize(app, api:)
+        super(app)
+        @app = app
+        @definition = Test[api]
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        env[Test::REQUEST] = @definition.validate_request(request, raise_error: false)
+        response = @app.call(env)
+        status, headers, body = response
+        env[Test::RESPONSE] =
+          @definition.validate_response(request, Rack::Response[status, headers, body], raise_error: false)
+        response
+      end
+    end
+  end
+end

data/lib/openapi_first/test/callable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Return a Module with a call method that wrapps silent request/response validation to monitor a Rack app
+    # This is used by Openapi::Test.observe
+    module Callable
+      # Returns a Module with a `call(env)` method that wraps super inside silent request/response validation
+      # You can use `Application.prepend(OpenapiFirst::Test::Callable[oad])` to monitor your app during testing.
+      def self.[](definition)
+        Module.new.tap do |mod|
+          mod.define_method(:call) do |env|
+            request = Rack::Request.new(env)
+
+            definition.validate_request(request, raise_error: false)
+            response = super(env)
+            status, headers, body = response
+            definition.validate_response(request, Rack::Response[status, headers, body], raise_error: false)
+            response
+          end
+        end
+      end
+    end
+  end
+end