openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/lib/openapi_first/builder.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+require_relative 'failure'
+require_relative 'router'
+require_relative 'header'
+require_relative 'request'
+require_relative 'response'
+require_relative 'schema/hash'
+require_relative 'ref_resolver'
+
+module OpenapiFirst
+  # Builds parts of a Definition
+  # This knows how to read a resolved OpenAPI document and build {Request} and {Response} objects.
+  class Builder # rubocop:disable Metrics/ClassLength
+    REQUEST_METHODS = %w[get head post put patch delete trace options query].freeze
+
+    # Builds a router from a resolved OpenAPI document.
+    # @param contents [Hash] The OpenAPI document Hash.
+    # @param config [OpenapiFirst::Configuration] The configuration object.
+    def self.build_router(contents, filepath:, config:)
+      new(contents, filepath:, config:).router
+    end
+
+    def initialize(contents, filepath:, config:)
+      meta_schema = detect_meta_schema(contents, filepath)
+      @schemer_configuration = build_schemer_config(filepath:, meta_schema:)
+      @config = config
+      @contents = RefResolver.for(contents, filepath:)
+    end
+
+    attr_reader :config
+    private attr_reader :schemer_configuration
+
+    def build_schemer_config(filepath:, meta_schema:)
+      result = JSONSchemer.configuration.clone
+      dir = (filepath && File.absolute_path(File.dirname(filepath))) || Dir.pwd
+      result.base_uri = URI::File.build({ path: "#{dir}/" })
+      result.ref_resolver = JSONSchemer::CachedResolver.new do |uri|
+        FileLoader.load(uri.path)
+      end
+      result.meta_schema = meta_schema
+      result.insert_property_defaults = true
+      result
+    end
+
+    def detect_meta_schema(document, filepath)
+      # Copied from JSONSchemer 🙇🏻‍♂️
+      version = document['openapi']
+      case version
+      when /\A3\.1\.\d+\z/
+        document.fetch('jsonSchemaDialect') { JSONSchemer::OpenAPI31::BASE_URI.to_s }
+      when /\A3\.0\.\d+\z/
+        JSONSchemer::OpenAPI30::BASE_URI.to_s
+      else
+        raise Error, "Unsupported OpenAPI version #{version.inspect} #{filepath}"
+      end
+    end
+
+    def router # rubocop:disable Metrics/MethodLength
+      router = OpenapiFirst::Router.new
+      @contents.fetch('paths').each do |path, path_item_object|
+        path_parameters = path_item_object['parameters'] || []
+        path_item_object.resolved.keys.intersection(REQUEST_METHODS).map do |request_method|
+          operation_object = path_item_object[request_method]
+          operation_parameters = operation_object['parameters'] || []
+          parameters = parse_parameters(operation_parameters.chain(path_parameters))
+
+          build_requests(path:, request_method:, operation_object:,
+                         parameters:).each do |request|
+            router.add_request(
+              request,
+              request_method:,
+              path:,
+              content_type: request.content_type,
+              allow_empty_content: request.allow_empty_content?
+            )
+            build_responses(request:, responses: operation_object['responses']).each do |response|
+              router.add_response(
+                response,
+                request_method:,
+                path:,
+                status: response.status,
+                response_content_type: response.content_type
+              )
+            end
+          end
+        end
+      end
+      router
+    end
+
+    def parse_parameters(parameters)
+      grouped_parameters = group_parameters(parameters)
+      ParsedParameters.new(
+        query: resolve_parameters(grouped_parameters[:query]),
+        path: resolve_parameters(grouped_parameters[:path]),
+        cookie: resolve_parameters(grouped_parameters[:cookie]),
+        header: resolve_parameters(grouped_parameters[:header]),
+        query_schema: build_parameter_schema(grouped_parameters[:query]),
+        path_schema: build_parameter_schema(grouped_parameters[:path]),
+        cookie_schema: build_parameter_schema(grouped_parameters[:cookie]),
+        header_schema: build_parameter_schema(grouped_parameters[:header])
+      )
+    end
+
+    def resolve_parameters(parameters)
+      parameters&.map do |parameter|
+        result = parameter.resolved
+        result['schema'] = parameter['schema'].resolved
+        result
+      end.to_a
+    end
+
+    def build_parameter_schema(parameters)
+      return unless parameters
+
+      required = []
+      schemas = parameters.each_with_object({}) do |parameter, result|
+        schema = parameter['schema'].schema(configuration: schemer_configuration)
+        name = parameter['name']&.value
+        required << name if parameter['required']&.value
+        result[name] = schema if schema
+      end
+
+      Schema::Hash.new(schemas, required:, configuration: schemer_configuration,
+                                after_property_validation: config.after_request_parameter_property_validation)
+    end
+
+    def build_requests(path:, request_method:, operation_object:, parameters:)
+      content_objects = operation_object.dig('requestBody', 'content')
+      if content_objects.nil?
+        return [
+          request_without_body(path:, request_method:, parameters:, operation_object:)
+        ]
+      end
+      required_body = operation_object['requestBody']&.resolved&.fetch('required', false) == true
+      content_objects.map do |content_type, content_object|
+        content_schema = content_object['schema'].schema(
+          configuration: schemer_configuration,
+          after_property_validation: config.after_request_body_property_validation
+        )
+        Request.new(path:, request_method:, parameters:,
+                    operation_object: operation_object.resolved,
+                    content_type:,
+                    content_schema:,
+                    required_body:,
+                    key: [path, request_method, content_type].join(':'))
+      end
+    end
+
+    def request_without_body(path:, request_method:, parameters:, operation_object:)
+      Request.new(path:, request_method:, parameters:,
+                  operation_object: operation_object.resolved,
+                  content_type: nil,
+                  content_schema: nil,
+                  required_body: false,
+                  key: [path, request_method, nil].join(':'))
+    end
+
+    def build_responses(responses:, request:)
+      return [] unless responses
+
+      responses.flat_map do |status, response_object|
+        headers = build_response_headers(response_object['headers'])
+        response_object['content']&.map do |content_type, content_object|
+          content_schema = content_object['schema'].schema(configuration: schemer_configuration)
+          Response.new(status:,
+                       headers:,
+                       content_type:,
+                       content_schema:,
+                       key: [request.key, status, content_type].join(':'))
+        end || Response.new(status:, headers:, content_type: nil,
+                            content_schema: nil, key: [request.key, status, nil].join(':'))
+      end
+    end
+
+    IGNORED_HEADER_PARAMETERS = Set['Content-Type', 'Accept', 'Authorization'].freeze
+    private_constant :IGNORED_HEADER_PARAMETERS
+
+    def build_response_headers(headers_object)
+      return if headers_object.nil?
+
+      result = []
+      headers_object.each do |name, header|
+        next if header['schema'].nil?
+        next if IGNORED_HEADER_PARAMETERS.include?(name)
+
+        header = Header.new(
+          name:,
+          schema: header['schema'].schema(configuration: schemer_configuration),
+          required?: header['required']&.value == true,
+          node: header
+        )
+        result << header
+      end
+      result
+    end
+
+    def group_parameters(parameter_definitions)
+      result = {}
+      parameter_definitions&.each do |parameter|
+        (result[parameter['in']&.value&.to_sym] ||= []) << parameter
+      end
+      result[:header]&.reject! { IGNORED_HEADER_PARAMETERS.include?(_1['name']&.value) }
+      result
+    end
+
+    ParsedParameters = Data.define(:path, :query, :header, :cookie, :path_schema, :query_schema, :header_schema,
+                                   :cookie_schema)
+    private_constant :ParsedParameters
+  end
+end

data/lib/openapi_first/child_configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # A subclass to configuration that points to its parent
+  class ChildConfiguration < Configuration
+    def initialize(parent:)
+      super()
+      @parent = parent
+      @request_validation_error_response = parent.request_validation_error_response
+      @request_validation_raise_error = parent.request_validation_raise_error
+      @response_validation_raise_error = parent.response_validation_raise_error
+      @path = parent.path
+    end
+
+    private attr_reader :parent
+
+    HOOKS.each do |hook|
+      define_method(hook) do |&block|
+        return hooks[hook].chain(parent.hooks[hook]) if block.nil?
+
+        hooks[hook] << block
+        block
+      end
+    end
+  end
+end

data/lib/openapi_first/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # Global configuration. Currently only used for the request validation middleware.
+  class Configuration
+    HOOKS = %i[
+      after_request_validation
+      after_response_validation
+      after_request_parameter_property_validation
+      after_request_body_property_validation
+    ].freeze
+
+    def initialize
+      @request_validation_error_response = OpenapiFirst.find_error_response(:default)
+      @request_validation_raise_error = false
+      @response_validation_raise_error = true
+      @hooks = HOOKS.to_h { [_1, Set.new] }
+      @path = nil
+    end
+
+    def register(path_or_definition, as: :default)
+      OpenapiFirst.register(path_or_definition, as:)
+    end
+
+    attr_reader :hooks, :request_validation_error_response
+    attr_accessor :path
+
+    # @deprecated
+    attr_reader :request_validation_raise_error
+    # @deprecated
+    attr_reader :response_validation_raise_error
+
+    # Return a child configuration that still receives updates of global hooks.
+    def child
+      ChildConfiguration.new(parent: self)
+    end
+
+    # @visibility private
+    def clone
+      raise NoMethodError, 'OpenapiFirst::Configuration#clone was removed. You want to call #child instead'
+    end
+
+    # @deprecated Pass `raise_error:` to OpenapiFirst::Middlewares::RequestValidation directly
+    def request_validation_raise_error=(value)
+      message = 'Setting OpenapiFirst::Configuration#request_validation_raise_error will be removed. ' \
+                'Please pass `raise_error:` to `OpenapiFirst::Middlewares::RequestValidation directly`'
+      warn message, category: :deprecated
+      @request_validation_raise_error = value
+    end
+
+    # @deprecated Pass `raise_error:` to OpenapiFirst::Middlewares::ResponseValidation directly
+    def response_validation_raise_error=(value)
+      message = 'Setting OpenapiFirst::Configuration#request_validation_raise_error will be removed. ' \
+                'Please pass `raise_error:` to `OpenapiFirst::Middlewares::ResponseValidation directly`'
+      warn message
+      @response_validation_raise_error = value
+    end
+
+    HOOKS.each do |hook|
+      define_method(hook) do |&block|
+        return hooks[hook] if block.nil?
+
+        hooks[hook] << block
+        block
+      end
+    end
+
+    def request_validation_error_response=(mod)
+      @request_validation_error_response = if mod.is_a?(Symbol)
+                                             OpenapiFirst.find_error_response(mod)
+                                           else
+                                             mod
+                                           end
+    end
+  end
+end

data/lib/openapi_first/definition.rb

@@ -1,27 +1,112 @@
 # frozen_string_literal: true
 
-require_relative 'operation'
+require_relative 'builder'
+require 'forwardable'
 
 module OpenapiFirst
+  # Represents an OpenAPI API Description document
+  # This is returned by OpenapiFirst.load.
   class Definition
-    def initialize(parsed)
-      @spec = parsed
+    extend Forwardable
+
+    # @return [String,nil]
+    attr_reader :filepath
+    # @return [Configuration]
+    attr_reader :config
+    # @return [Enumerable[String]]
+    attr_reader :paths
+    # @return [Router]
+    attr_reader :router
+
+    # @param contents [Hash] The OpenAPI document.
+    # @param filepath [String] The file path of the OpenAPI document.
+    def initialize(contents, filepath = nil)
+      @filepath = filepath
+      @config = OpenapiFirst.configuration.child
+      yield @config if block_given?
+      @config.freeze
+      @router = Builder.build_router(contents, filepath:, config:)
+      @resolved = contents
+      @paths = @router.routes.map(&:path).to_a.uniq # TODO: Refactor
     end
 
-    def operations
-      @spec.endpoints.map { |e| Operation.new(e) }
+    # Gives access to the raw resolved Hash. Like `mydefinition['components'].dig('schemas', 'Stations')`
+    # @!method [](key)
+    # @return [Hash]
+    def_delegators :@resolved, :[]
+
+    # Returns an Enumerable of available Routes for this API description.
+    # @!method routes
+    # @return [Enumerable[Router::Route]]
+    def_delegators :@router, :routes
+
+    # Returns a unique identifier for this API definition
+    # @return [String] A unique key for this API definition
+    def key
+      return filepath if filepath
+
+      info = self['info'] || {}
+      title = info['title']
+      version = info['version']
+
+      if title.nil? || version.nil?
+        raise ArgumentError,
+              "Cannot generate key for the OpenAPI document because 'info.title' or 'info.version' is missing. " \
+              'Please add these fields to your OpenAPI document.'
+      end
+
+      "#{title} @ #{version}"
     end
 
-    def find_operation!(request)
-      @spec
-        .path_by_path(request.path)
-        .endpoint_by_method(request.request_method.downcase)
+    def inspect
+      "#<#{self.class.name} @key='#{key}'>"
     end
 
-    def find_operation(request)
-      find_operation!(request)
-    rescue OasParser::PathNotFound, OasParser::MethodNotFound
-      nil
+    # Validates the request against the API description.
+    # @param [Rack::Request] request The Rack request object.
+    # @param [Boolean] raise_error Whether to raise an error if validation fails.
+    # @return [ValidatedRequest] The validated request object.
+    def validate_request(request, raise_error: false)
+      route = @router.match(request.request_method, resolve_path(request), content_type: request.content_type)
+      if route.error
+        ValidatedRequest.new(request, error: route.error)
+      else
+        route.request_definition.validate(request, route_params: route.params)
+      end.tap do |validated|
+        @config.after_request_validation.each { |hook| hook.call(validated, self) }
+        raise validated.error.exception(validated) if validated.error && raise_error
+      end
+    end
+
+    # Validates the response against the API description.
+    # @param rack_request [Rack::Request] The Rack request object.
+    # @param rack_response [Rack::Response] The Rack response object.
+    # @param raise_error [Boolean] Whethir to raise an error if validation fails.
+    # @return [ValidatedResponse] The validated response object.
+    def validate_response(rack_request, rack_response, raise_error: false)
+      route = @router.match(rack_request.request_method, resolve_path(rack_request),
+                            content_type: rack_request.content_type)
+      return if route.error # Skip response validation for unknown requests
+
+      response_match = route.match_response(status: rack_response.status, content_type: rack_response.content_type)
+      error = response_match.error
+      validated = if error
+                    ValidatedResponse.new(rack_response, error:)
+                  else
+                    response_match.response.validate(rack_response)
+                  end
+      @config.after_response_validation&.each { |hook| hook.call(validated, rack_request, self) }
+      raise validated.error.exception(validated) if raise_error && validated.invalid?
+
+      validated
+    end
+
+    private
+
+    def resolve_path(rack_request)
+      return rack_request.path unless @config.path
+
+      @config.path.call(rack_request)
     end
   end
 end

data/lib/openapi_first/error_response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # This is the base module for error responses
+  module ErrorResponse
+    ## @param failure [OpenapiFirst::Failure]
+    def initialize(failure: nil)
+      @failure = failure
+    end
+
+    attr_reader :failure
+
+    # The response body
+    def body
+      raise "#{self.class} must implement the method #{__method__}"
+    end
+
+    # The response content-type
+    def content_type
+      raise "#{self.class} must implement the method #{__method__}"
+    end
+
+    STATUS = {
+      not_found: 404,
+      method_not_allowed: 405,
+      unsupported_media_type: 415
+    }.freeze
+    private_constant :STATUS
+
+    # The response status
+    def status
+      STATUS[failure.type] || 400
+    end
+
+    # Render this error response
+    def render
+      Rack::Response.new(body, status, Rack::CONTENT_TYPE => content_type).finish
+    end
+  end
+end

data/lib/openapi_first/error_responses/default.rb

@@ -0,0 +1,74 @@
+# 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
+        JSON.generate(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,60 @@
+# 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
+        JSON.generate({ 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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # Base class for all errors
+  class Error < StandardError; end
+
+  # Raised if YAML/JSON file was not found
+  class FileNotFoundError < Error; end
+
+  # Raised if response body could not be parsed
+  class ParseError < Error; end
+
+  # Raised during request validation if request was invalid
+  class RequestInvalidError < Error
+    def initialize(message, validated_request)
+      super(message)
+      @request = validated_request
+    end
+
+    # @return [ValidatedRequest] The validated request
+    attr_reader :request
+  end
+
+  # Raised during request validation if request was not defined in the API description
+  class NotFoundError < RequestInvalidError; end
+
+  # Raised during response validation if request was invalid
+  class ResponseInvalidError < Error
+    def initialize(message, validated_response)
+      super(message)
+      @response = validated_response
+    end
+
+    # @return [ValidatedResponse] The validated response
+    attr_reader :response
+  end
+
+  # Raised during request validation if response was not defined in the API description
+  class ResponseNotFoundError < ResponseInvalidError; end
+end