openapi_first 1.4.3 → 2.0.0

data/lib/openapi_first/{definition → router}/path_template.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  class Definition
+  class Router
     # @visibility private
     class PathTemplate
       # See also https://spec.openapis.org/oas/v3.1.0#path-templating
@@ -9,12 +9,20 @@ module OpenapiFirst
       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?

data/lib/openapi_first/router.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+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
+    # 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)
+
+    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
+
+    # 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
+
+          Route.new(path:, request_method:, requests: content[:requests].each_value,
+                    responses: content[:responses].each_value.lazy.flat_map(&:values))
+        end
+      end
+    end
+
+    # Add a request definition
+    def add_request(request, request_method:, path:, content_type: nil)
+      route_at(path, request_method)[:requests][content_type] = request
+    end
+
+    # 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
+
+    # 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)
+      return NOT_FOUND unless path_item
+
+      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
+
+      responses = path_item.dig(request_method, :responses)
+      RequestMatch.new(request_definition:, params:, error: nil, responses:)
+    end
+
+    private
+
+    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?
+
+      "Content-Type #{content_type} is not defined."
+    end
+
+    def find_path_item(request_path)
+      found = @static[request_path]
+      return [found, {}] if found
+
+      @dynamic.find do |_path, path_item|
+        params = path_item[:template].match(request_path)
+        return [path_item, params] if params
+      end
+    end
+  end
+end

data/lib/openapi_first/schema/validation_error.rb

@@ -3,18 +3,24 @@
 module OpenapiFirst
   class Schema
     # One of multiple validation errors. Returned by Schema::ValidationResult#errors.
-    class ValidationError
-      def initialize(json_schemer_error)
-        @error = json_schemer_error
+    ValidationError = Data.define(:message, :data_pointer, :schema_pointer, :type, :details) do
+      # @deprecated Please use {#message} instead
+      def error
+        warn 'OpenapiFirst::Schema::ValidationError#error is deprecated. Use #message instead.'
+        message
       end
 
-      def error = @error['error']
-      alias message 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']
+      # @deprecated Please use {#data_pointer} instead
+      def instance_location
+        warn 'OpenapiFirst::Schema::ValidationError#instance_location is deprecated. Use #data_pointer instead.'
+        data_pointer
+      end
+
+      # @deprecated Please use {#schema_pointer} instead
+      def schema_location
+        warn 'OpenapiFirst::Schema::ValidationError#schema_location is deprecated. Use #schema_pointer instead.'
+        schema_pointer
+      end
     end
   end
 end

data/lib/openapi_first/schema/validation_result.rb

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

data/lib/openapi_first/schema.rb

@@ -13,24 +13,20 @@ module OpenapiFirst
       '3.0' => 'json-schemer://openapi30/schema'
     }.freeze
 
-    def initialize(schema, openapi_version:, write: true)
-      @schema = schema
+    def initialize(schema, openapi_version: '3.1', write: true, after_property_validation: nil)
       @schemer = JSONSchemer.schema(
         schema,
         access_mode: write ? 'write' : 'read',
         meta_schema: SCHEMAS.fetch(openapi_version),
         insert_property_defaults: true,
         output_format: 'classic',
-        before_property_validation: method(:before_property_validation)
+        before_property_validation: method(:before_property_validation),
+        after_property_validation:
       )
     end
 
     def validate(data)
-      ValidationResult.new(
-        @schemer.validate(data),
-        schema:,
-        data:
-      )
+      ValidationResult.new(@schemer.validate(data))
     end
 
     private

data/lib/openapi_first/test/methods.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Methods to use in integration tests
+    module Methods
+      def assert_api_conform(status: nil, api: :default)
+        api = OpenapiFirst::Test[api]
+        request = respond_to?(:last_request) ? last_request : @request
+        response = respond_to?(:last_response) ? last_response : @response
+        if status && status != response.status
+          raise OpenapiFirst::Error,
+                "Expected status #{status}, but got #{response.status} " \
+                "from #{request.request_method.upcase} #{request.path}."
+        end
+        api.validate_request(request, raise_error: true)
+        api.validate_response(request, response, raise_error: true)
+      end
+    end
+  end
+end

data/lib/openapi_first/test.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'test/methods'
+
+module OpenapiFirst
+  # Test integration
+  module Test
+    def self.register(path, as: :default)
+      @registry ||= {}
+      @registry[as] = OpenapiFirst.load(path)
+    end
+
+    def self.[](api)
+      @registry[api] || raise(ArgumentError,
+                              "API description #{api} not found to be used via assert_api_conform. " \
+                              'Use OpenapiFirst::Test.register to load an API description first.')
+    end
+  end
+end

data/lib/openapi_first/validated_request.rb

@@ -0,0 +1,81 @@
+# 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_values: {}, request_definition: nil)
+      super(original_request)
+      @parsed_values = Hash.new({}).merge(parsed_values)
+      @error = error
+      @request_definition = request_definition
+    end
+
+    # @!method error
+    #   @return [Failure, nil] The error that occurred during validation.
+    # @!method request_definition
+    #   @return [Request, nil]
+    attr_reader :parsed_values, :error, :request_definition
+
+    # Openapi 3 specific
+    # @!method operation
+    #   @return [Hash] The OpenAPI 3 operation object
+    # @!method operation_id
+    #   @return [String, nil] The OpenAPI 3 operationId
+    def_delegators :request_definition, :operation_id, :operation
+
+    # Parsed path parameters
+    #   @return [Hash] A string keyed hash of path parameters
+    def parsed_path_parameters
+      parsed_values[:path]
+    end
+
+    # Parsed query parameters. This only returns the query parameters that are defined in the OpenAPI spec.
+    def parsed_query
+      parsed_values[:query]
+    end
+
+    # Parsed headers. This only returns the query parameters that are defined in the OpenAPI spec.
+    def parsed_headers
+      parsed_values[:headers]
+    end
+
+    # Parsed cookies. This only returns the query parameters that are defined in the OpenAPI spec.
+    def parsed_cookies
+      parsed_values[:cookies]
+    end
+
+    # 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
+    # returns a validation error if the body contains unknown fields.
+    def parsed_body
+      parsed_values[:body]
+    end
+
+    # Checks if the request is valid.
+    def valid?
+      error.nil?
+    end
+
+    # Checks if the request is invalid.
+    def invalid?
+      !valid?
+    end
+
+    # Returns true if the request is defined.
+    def known?
+      request_definition != nil
+    end
+
+    # Merged path, query, body parameters.
+    # Here path has the highest precedence, then query, then body.
+    def parsed_params
+      @parsed_params ||= parsed_body.merge(parsed_query, parsed_path_parameters)
+    end
+  end
+end

data/lib/openapi_first/validated_response.rb

@@ -0,0 +1,33 @@
+# 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
+
+    attr_reader :parsed_values, :error, :response_definition
+
+    def_delegator :parsed_values, :headers, :parsed_headers
+    def_delegator :parsed_values, :body, :parsed_body
+
+    # Checks if the response is valid.
+    # @return [Boolean] true if the response is valid, false otherwise.
+    def valid?
+      error.nil?
+    end
+
+    def invalid?
+      !valid?
+    end
+  end
+end

data/lib/openapi_first/validators/request_body.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class RequestBody
+      def self.for(request_definition, openapi_version:, hooks: {})
+        schema = request_definition.content_schema
+        return unless schema
+
+        after_property_validation = hooks[:after_request_body_property_validation]
+
+        new(Schema.new(schema, after_property_validation:, openapi_version:),
+            required: request_definition.required_request_body?)
+      end
+
+      def initialize(schema, required:)
+        @schema = schema
+        @required = required
+      end
+
+      def call(request)
+        request_body = read_body(request)
+        if request_body.nil?
+          Failure.fail!(:invalid_body, message: 'Request body is not defined') if @required
+          return
+        end
+
+        validation = @schema.validate(request_body)
+        Failure.fail!(:invalid_body, errors: validation.errors) if validation.error?
+      end
+
+      private
+
+      def read_body(request)
+        request[:body]
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/request_parameters.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class RequestParameters
+      RequestHeaders = Data.define(:schema) do
+        def call(parsed_values)
+          validation = schema.validate(parsed_values[:headers])
+          Failure.fail!(:invalid_header, errors: validation.errors) if validation.error?
+        end
+      end
+
+      Path = Data.define(:schema) do
+        def call(parsed_values)
+          validation = schema.validate(parsed_values[:path])
+          Failure.fail!(:invalid_path, errors: validation.errors) if validation.error?
+        end
+      end
+
+      Query = Data.define(:schema) do
+        def call(parsed_values)
+          validation = schema.validate(parsed_values[:query])
+          Failure.fail!(:invalid_query, errors: validation.errors) if validation.error?
+        end
+      end
+
+      RequestCookies = Data.define(:schema) do
+        def call(parsed_values)
+          validation = schema.validate(parsed_values[: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(operation, openapi_version:, hooks: {})
+        after_property_validation = hooks[:after_request_parameter_property_validation]
+        validators = VALIDATORS.filter_map do |key, klass|
+          schema = operation.send(key)
+          klass.new(Schema.new(schema, after_property_validation:, openapi_version:)) if schema
+        end
+        return if validators.empty?
+
+        new(validators)
+      end
+
+      def initialize(validators)
+        @validators = validators
+      end
+
+      def call(parsed_values)
+        @validators.each { |validator| validator.call(parsed_values) }
+      end
+    end
+  end
+end

data/lib/openapi_first/validators/response_body.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class ResponseBody
+      def self.for(response_definition, openapi_version:)
+        schema = response_definition&.content_schema
+        return unless schema
+
+        new(Schema.new(schema, write: false, openapi_version:))
+      end
+
+      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.validate(parsed_body)
+        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,25 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Validators
+    class ResponseHeaders
+      def self.for(response_definition, openapi_version:)
+        schema = response_definition&.headers_schema
+        return unless schema
+
+        new(Schema.new(schema, openapi_version:))
+      end
+
+      def initialize(schema)
+        @schema = schema
+      end
+
+      attr_reader :schema
+
+      def call(parsed_request)
+        validation = schema.validate(parsed_request.headers)
+        Failure.fail!(:invalid_response_header, errors: validation.errors) if validation.error?
+      end
+    end
+  end
+end

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '1.4.3'
+  VERSION = '2.0.0'
 end

data/lib/openapi_first.rb

@@ -5,45 +5,63 @@ require 'multi_json'
 require_relative 'openapi_first/json_refs'
 require_relative 'openapi_first/errors'
 require_relative 'openapi_first/configuration'
-require_relative 'openapi_first/plugins'
 require_relative 'openapi_first/definition'
 require_relative 'openapi_first/version'
-require_relative 'openapi_first/error_response'
+require_relative 'openapi_first/schema'
 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
-  extend Plugins
+  # Key in rack to find instance of Request
+  REQUEST = 'openapi.request'
+  FAILURE = :openapi_first_validation_failure
 
-  class << self
-    # @return [Configuration]
-    def configuration
-      @configuration ||= Configuration.new
-    end
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
 
-    # @return [Configuration]
-    # @yield [Configuration]
-    def configure
-      yield configuration
-    end
+  # @return [Configuration]
+  # @yield [Configuration]
+  def self.configure
+    yield configuration
   end
 
-  # Key in rack to find instance of RuntimeRequest
-  REQUEST = 'openapi.request'
+  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
+
+  # @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
 
   # Load and dereference an OpenAPI spec file
   # @return [Definition]
-  def self.load(filepath, only: nil)
+  def self.load(filepath, only: nil, &)
+    raise FileNotFoundError, "File not found: #{filepath}" unless File.exist?(filepath)
+
     resolved = Bundle.resolve(filepath)
-    parse(resolved, only:, filepath:)
+    parse(resolved, only:, filepath:, &)
   end
 
   # Parse a dereferenced Hash
   # @return [Definition]
-  def self.parse(resolved, only: nil, filepath: nil)
+  def self.parse(resolved, only: nil, filepath: nil, &)
     resolved['paths'].filter!(&->(key, _) { only.call(key) }) if only
-    Definition.new(resolved, filepath)
+    Definition.new(resolved, filepath, &)
   end
 
   # @!visibility private
@@ -55,5 +73,6 @@ module OpenapiFirst
   end
 end
 
-OpenapiFirst.plugin(:default)
-OpenapiFirst.plugin(:jsonapi)
+require_relative 'openapi_first/error_response'
+require_relative 'openapi_first/error_responses/default'
+require_relative 'openapi_first/error_responses/jsonapi'