openapi_first 3.3.1 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1786c083ff520504c716e9bdd1e8b92754be71e70dd774644b6a0c655681369a
-  data.tar.gz: bc86929efbbe041515cfb12e6d453133cb4cf0a849c40ae5c526eda1b910a4cd
+  metadata.gz: 25a078c6bc5ab1617e9dd79545146b3ef7a0f28dbf5d9550819907e8e36c5b1b
+  data.tar.gz: 4478e189440cf7915416eb10b61b8a62e7a7465ffd62d64bf9663b2fab1fafde
 SHA512:
-  metadata.gz: 4b745143e975173192680152d5b42243c4eb58e8158b4f71aa67730780ad9ec49e788767f8bd5816f0b5dc6ffb711bbba362968a2c075db11dc5c7f11d29733d
-  data.tar.gz: 32b7bbab75bd6fbb1620808f389d4bfc051a20da124823ada6ea154635306b8b6f6ad378c4bc55a1733211b6438092b307d36d83cc3d23494462729c7b80c817
+  metadata.gz: ebee301cf2048cabd799f604073b34691434a55ee2f0787428588c33c4bc9ee49d551e7eee761641bfc61ac724e68f4e7774e6c25eb073aab6bdbcbf2ddd4f10
+  data.tar.gz: 53b1e8f5776ba5dfd41be46f9651e76e64a54ae849984a1b93980c7ab9da3353140fefb8ed4399679098f14d631d17ff30ab66cb7f4f9c7315308018aa727533

data/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 3.4.1
+
+Fixed: Added missing ERB and css file to the gem
+
+## 3.4.0
+
+### Changed
+- Use a new coverage reporter `OpenapiFirst::Test::Coverage::HtmlReporter` by default that writes a self-contained HTML coverage report to `coverage/openapi_coverage.html`.
+
+### Added
+- Apps using request validation middleware can call `OpenapiFirst::Failure.fail!` to produce an error result
+- The `after_request_validation` now supports throwing a Failure (via `OpenapiFirst::Failure.fail!`), which will result in a failed request
+- Added new hook `before_request_validation`. Called after a request routed to an operation but before the request is validated. You can throw via `Failure.fail!` to abort request validation immediately.
+- `OpenapiFirst::Test.logger` is now configurable via the setup block: `OpenapiFirst::Test.setup { |test| test.logger = Logger.new($stderr) }`. The logger defaults to `Logger.new($stdout)`.
+- Support `encoding[<field>].contentType` on `multipart/form-data` request bodies. Fields whose encoding declares a JSON content type are JSON-parsed before schema validation. Fixes [#398](https://github.com/ahx/openapi_first/issues/398).
+- Start introducing a plugin system modeled after Sequels plugin system.
+  - Add an example plugin: 'x_public' (`OpenapiFirst.plugin :x_public`) that returns 404 unless the operatio has `x-public: true`
+- Update openapi_parameters dependency to support `content` field in parameter. Solves [#476](https://github.com/ahx/openapi_first/issues/476)
+
+### Deprecated
+- Deprecated `OpenapiFirst::Test::Coverage::TerminalFormatter`. Use `TerminalReporter` instead
+- Deprecated and `Test::Configuration#coverage_formatter_options`. Use `#coverage_reporter_options` instead.
+- Deprecated `TerminalFormatter#format`. Use `#report` instead.
+
 ## 3.3.1
 
 - Optimized caching towards reducing retained memory after calling `OpenapiFirst.load` without using a global cache. (Removed `OpenapiFirst.clear_cache!`.)

data/README.md

@@ -378,6 +378,7 @@ You can integrate your code at certain points during request/response validation
 
 Available hooks:
 
+- `before_request_validation`
 - `after_request_validation`
 - `after_response_validation`
 - `after_request_parameter_property_validation`

data/lib/openapi_first/builder.rb

@@ -13,7 +13,7 @@ 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
+  class Builder
     REQUEST_METHODS = %w[get head post put patch delete trace options query].freeze
 
     # Builds a router from a resolved OpenAPI document.
@@ -130,7 +130,7 @@ module OpenapiFirst
                                 after_property_validation: config.after_request_parameter_property_validation)
     end
 
-    def build_requests(path:, request_method:, operation_object:, parameters:)
+    def build_requests(path:, request_method:, operation_object:, parameters:) # rubocop:disable Metrics/MethodLength
       content_objects = operation_object.dig('requestBody', 'content')
       if content_objects.nil?
         return [
@@ -143,10 +143,12 @@ module OpenapiFirst
           configuration: schemer_configuration,
           after_property_validation: config.after_request_body_property_validation
         )
+        encoding = content_object['encoding']&.resolved
         Request.new(path:, request_method:, parameters:,
                     operation_object: operation_object.resolved,
                     content_type:,
                     content_schema:,
+                    encoding:,
                     required_body:,
                     key: [path, request_method, content_type].join(':'))
       end
@@ -157,6 +159,7 @@ module OpenapiFirst
                   operation_object: operation_object.resolved,
                   content_type: nil,
                   content_schema: nil,
+                  encoding: nil,
                   required_body: false,
                   key: [path, request_method, nil].join(':'))
     end

data/lib/openapi_first/configuration.rb

@@ -4,6 +4,7 @@ module OpenapiFirst
   # Global configuration. Currently only used for the request validation middleware.
   class Configuration
     HOOKS = %i[
+      before_request_validation
       after_request_validation
       after_response_validation
       after_request_parameter_property_validation
@@ -66,6 +67,11 @@ module OpenapiFirst
       end
     end
 
+    def plugin(name, **)
+      require_relative 'plugins'
+      Plugins.load(name).configure(self, **)
+    end
+
     def request_validation_error_response=(mod)
       @request_validation_error_response = if mod.is_a?(Symbol)
                                              OpenapiFirst.find_error_response(mod)

data/lib/openapi_first/definition.rb

@@ -44,6 +44,11 @@ module OpenapiFirst
     # @return [Enumerable[Router::Route]]
     def_delegators :@router, :routes
 
+    # @return [String,nil] The title from the OpenAPI document's `info.title`, if any.
+    def title
+      self['info']&.[]('title')
+    end
+
     # Returns a unique identifier for this API definition
     # @return [String] A unique key for this API definition
     def key
@@ -69,17 +74,23 @@ module OpenapiFirst
     # 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.
+    # @yield [ValidatedRequest] Optional block called after successful validation.
+    #   The block runs inside the same catch(FAILURE) as the after_request_validation hooks,
+    #   so it may call OpenapiFirst::Failure.fail! to short-circuit and produce an error.
     # @return [ValidatedRequest] The validated request object.
-    def validate_request(request, raise_error: false)
+    def validate_request(request, raise_error: false, &after_block)
       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
+      validated = if route.error
+                    ValidatedRequest.new(request, error: route.error)
+                  else
+                    result = call_before_request_validation_hooks(request, route.request_definition)
+                    result ||= route.request_definition.validate(request, route_params: route.params)
+                    result.is_a?(Failure) ? ValidatedRequest.new(request, error: result) : result
+                  end
+      validated = call_after_request_validation_hooks(request, validated, &after_block)
+      raise validated.error.exception(validated) if validated.error && raise_error
+
+      validated
     end
 
     # Validates the response against the API description.
@@ -106,6 +117,29 @@ module OpenapiFirst
 
     private
 
+    def call_before_request_validation_hooks(request, request_definition)
+      return if @config.before_request_validation.none?
+
+      catch(FAILURE) do
+        @config.before_request_validation.each do |hook|
+          hook.call(request, request_definition, self)
+        end
+        nil
+      end
+    end
+
+    def call_after_request_validation_hooks(request, validated)
+      hooks = @config.after_request_validation
+      return validated if hooks.none? && !block_given?
+
+      error = catch(FAILURE) do
+        hooks.each { |hook| hook.call(validated, self) }
+        yield validated if block_given? && validated.valid?
+        return validated
+      end
+      ValidatedRequest.new(request, error: error)
+    end
+
     def resolve_path(rack_request)
       return rack_request.path.delete_prefix(path_prefix) if path_prefix && rack_request.path.start_with?(path_prefix)
       return rack_request.path unless @config.path

data/lib/openapi_first/middlewares/request_validation.rb

@@ -3,7 +3,19 @@
 require 'rack'
 module OpenapiFirst
   module Middlewares
-    # A Rack middleware to validate requests against an OpenAPI API description
+    # A Rack middleware to validate requests against an OpenAPI API description.
+    # All error responses can be customized via the +error_response:+ option.
+    # === Request body validation
+    #
+    # * Returns +415+ if the request content-type does not match the OpenAPI description.
+    # * Returns +400+ for invalid JSON, missing required fields, type/enum/schema violations, or +readOnly+ fields.
+    # * Empty bodies are accepted when the body is optional in the spec.
+    #
+    # === Parameter validation
+    #
+    # Query, path, header, and cookie parameters are validated and type-converted against the spec.
+    # Missing required parameters or type/format violations return +400+.
+    #
     class RequestValidation
       # @param app The parent Rack application
       # @param spec [String, Symbol, OpenapiFirst::Definition] Path to the OpenAPI file or an instance of Definition.
@@ -37,10 +49,17 @@ module OpenapiFirst
       attr_reader :app
 
       def call(env)
-        validated = @definition.validate_request(Rack::Request.new(env), raise_error: @raise)
+        rack_response = nil
+        app_called = false
+        validated = @definition.validate_request(Rack::Request.new(env), raise_error: @raise) do |v|
+          app_called = true
+          env[REQUEST] = v
+          rack_response = @app.call(env)
+        end
         env[REQUEST] = validated
         failure = validated.error
         return @error_response_class.new(failure:).render if failure && @error_response_class
+        return rack_response if app_called
 
         @app.call(env)
       end

data/lib/openapi_first/middlewares/response_validation.rb

@@ -4,7 +4,8 @@ require 'rack'
 
 module OpenapiFirst
   module Middlewares
-    # A Rack middleware to validate requests against an OpenAPI API description
+    # A Rack middleware to validate requests against an OpenAPI API description.
+    # You probably want to use +OpenapiFirst::Test+ instead of this middleware.
     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`

data/lib/openapi_first/plugins/x_public.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Plugins
+    # Enforces that only operations explicitly marked as public are accessible.
+    # Throws a :not_found failure for any matched operation that lacks the configured field.
+    #
+    # Options:
+    #   field: [String] The OpenAPI extension field to check. Default: 'x-public'.
+    #   if:    [Proc]   Optional condition proc. Receives the Rack::Request and must
+    #                   return truthy for the check to apply. Use this to restrict the
+    #                   plugin to certain hosts or path prefixes.
+    #
+    # Example:
+    #   OpenapiFirst.plugin :x_public
+    #   OpenapiFirst.plugin :x_public, field: 'x-visible'
+    #   OpenapiFirst.plugin :x_public, if: ->(req) { req.host == 'api.example.com' }
+    module XPublic
+      def self.configure(config, field: 'x-public', **opts)
+        condition = opts[:if]
+        config.before_request_validation do |request, request_definition|
+          next if condition && !condition.call(request)
+
+          Failure.fail!(:not_found) unless request_definition.operation[field]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/plugins.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # Plugin system for extending openapi_first behaviour. Modeled after Sequels plugin system.
+  #
+  # A plugin is a module under the +OpenapiFirst::Plugins+ namespace with a
+  # +.configure(config, **opts)+ class method. Plugins wire themselves in by
+  # registering hooks on the +Configuration+ object they receive.
+  #
+  # Loading a plugin:
+  #
+  #   # Globally (applies to all definitions):
+  #   OpenapiFirst.plugin :x_public
+  #
+  #   # Per definition:
+  #   OpenapiFirst.load('openapi.yaml') { |c| c.plugin :x_public, field: 'x-visible' }
+  #
+  # Writing a plugin:
+  #
+  #   module OpenapiFirst::Plugins::MyPlugin
+  #     def self.configure(config, **)
+  #       config.after_request_validation do |validated_request|
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  # Third-party plugins are discovered by placing a module at the expected
+  # constant path and/or providing a file at <tt>openapi_first/plugins/<name></tt>
+  # on the load path.
+  module Plugins
+    def self.load(name)
+      module_name = name.to_s.split('_').map(&:capitalize).join
+      mod = const_get(module_name) if const_defined?(module_name, false)
+      mod ||= begin
+        require "openapi_first/plugins/#{name}"
+        const_get(module_name)
+      end
+      raise ArgumentError, "Plugin #{name.inspect} must respond to .configure" unless mod.respond_to?(:configure)
+
+      mod
+    end
+  end
+end

data/lib/openapi_first/registry.rb

@@ -13,7 +13,7 @@ module OpenapiFirst
     # 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)
+    def register(path_or_definition, as: :default, &)
       if definitions.key?(as) && as == :default
         raise(
           AlreadyRegisteredError,
@@ -24,7 +24,7 @@ module OpenapiFirst
         )
       end
 
-      definition = OpenapiFirst.load(path_or_definition)
+      definition = OpenapiFirst.load(path_or_definition, &)
       definitions[as] = definition
       definition
     end

data/lib/openapi_first/request.rb

@@ -12,8 +12,8 @@ module OpenapiFirst
   # 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:)
+    def initialize(path:, request_method:, operation_object:, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
+                   parameters:, content_type:, content_schema:, required_body:, key:, encoding: nil)
       @path = path
       @request_method = request_method
       @content_type = content_type
@@ -25,7 +25,7 @@ module OpenapiFirst
       @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
+      @body_parsers = build_body_parser(content_type, encoding) if content_type
       @validator = RequestValidator.new(
         content_schema:,
         required_request_body: required_body == true,
@@ -45,12 +45,8 @@ module OpenapiFirst
     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
+      parsed_request, error = parse_request(request, route_params:)
+      error ||= @validator.call(parsed_request) if parsed_request
       ValidatedRequest.new(request, parsed_request:, error:, request_definition: self, query_parser:)
     end
 
@@ -58,22 +54,39 @@ module OpenapiFirst
       @operation['operationId']
     end
 
+    MULTIPART_CONTENT_TYPE = %r{\Amultipart/form-data\b}i
+    private_constant :MULTIPART_CONTENT_TYPE
+
     private
 
     def parse_request(request, route_params:)
-      ParsedRequest.new(
+      query, query_error = parse_query(request.env[Rack::QUERY_STRING])
+      return [nil, query_error] if query_error
+
+      body = @body_parsers&.call(request)
+      return [nil, body] if body.is_a?(Failure)
+
+      [ParsedRequest.new(
         path: @path_parser&.unpack(route_params),
-        query: parse_query(request.env[Rack::QUERY_STRING]),
+        query:,
         headers: @headers_parser&.unpack_env(request.env),
         cookies: @cookies_parser&.unpack(request.env[Rack::HTTP_COOKIE]),
-        body: @body_parsers&.call(request)
-      )
+        body:
+      ), nil]
     end
 
     def parse_query(query_string)
-      @query_parser&.unpack(query_string)
+      [@query_parser&.unpack(query_string), nil]
     rescue OpenapiParameters::InvalidParameterError
-      Failure.fail!(:invalid_query, message: 'Invalid query parameter.')
+      [nil, Failure.new(:invalid_query, message: 'Invalid query parameter.')]
+    end
+
+    def build_body_parser(content_type, encoding)
+      if content_type.match?(MULTIPART_CONTENT_TYPE)
+        RequestBodyParsers::MultipartBodyParser.new(encoding: encoding || {})
+      else
+        RequestBodyParsers[content_type]
+      end
     end
   end
 end

data/lib/openapi_first/request_body_parsers.rb

@@ -33,27 +33,59 @@ module OpenapiFirst
       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')
+      Failure.new(: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
+    #
+    # Honors the OpenAPI `encoding` map: when a top-level field has
+    # `contentType: application/json` (or any */json), the field's raw value
+    # is JSON-parsed before schema validation.
+    class MultipartBodyParser
+      def initialize(encoding: {})
+        @encoding = encoding || {}
+      end
+
       def self.call(request)
-        request.POST.transform_values do |value|
-          unpack_value(value)
+        new.call(request)
+      end
+
+      def call(request)
+        result = {}
+        request.POST.each do |name, value|
+          decoded = decode_field(name, value)
+          return decoded if decoded.is_a?(Failure)
+
+          result[name] = decoded
         end
+        result
+      end
+
+      private
+
+      def decode_field(name, value)
+        raw = unpack_value(value)
+        content_type = @encoding.dig(name, 'contentType')
+        return raw unless content_type && raw.is_a?(String) && json?(content_type)
+
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        Failure.new(:invalid_body,
+                    message: %(Failed to parse multipart field "#{name}" as JSON: #{e.message}))
       end
 
-      def self.unpack_value(value)
+      def json?(content_type)
+        content_type.match?(%r{[/+]json\b}i)
+      end
+
+      def 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
+        value.transform_values { unpack_value(_1) }
       end
     end
 

data/lib/openapi_first/request_validator.rb

@@ -26,7 +26,11 @@ module OpenapiFirst
     end
 
     def call(parsed_request)
-      @validators.each { |v| v.call(parsed_request) }
+      @validators.each do |v|
+        result = v.call(parsed_request)
+        return result if result.is_a?(Failure)
+      end
+      nil
     end
   end
 end

data/lib/openapi_first/response.rb

@@ -25,19 +25,9 @@ module OpenapiFirst
     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)
+      parsed_values, error = @parser.parse(response)
+      error ||= @validator.call(parsed_values) if 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

@@ -23,9 +23,9 @@ module OpenapiFirst
     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?
+      return Failure.new(: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')
+      Failure.new(:invalid_response_body, message: 'Failed to parse response body as JSON')
     end)
   end
 end

data/lib/openapi_first/response_parser.rb

@@ -13,10 +13,13 @@ module OpenapiFirst
     end
 
     def parse(rack_response)
-      ParsedResponse.new(
-        body: @body_parser.call(read_body(rack_response)),
+      body = @body_parser.call(read_body(rack_response))
+      return [nil, body] if body.is_a?(Failure)
+
+      [ParsedResponse.new(
+        body:,
         headers: @headers_parser&.call(rack_response.headers) || {}
-      )
+      ), nil]
     end
 
     private

data/lib/openapi_first/response_validator.rb

@@ -18,10 +18,11 @@ module OpenapiFirst
     end
 
     def call(parsed_response)
-      catch FAILURE do
-        @validators.each { |v| v.call(parsed_response) }
-        nil
+      @validators.each do |v|
+        result = v.call(parsed_response)
+        return result if result.is_a?(Failure)
       end
+      nil
     end
   end
 end

data/lib/openapi_first/schema/hash.rb

@@ -6,7 +6,7 @@ module OpenapiFirst
   module Schema
     # A hash of Schemas
     class Hash
-      # @param schema Hash of schemas
+      # @param schemas Hash of schemas
       # @param required Array of required keys
       def initialize(schemas, required: nil, **options)
         @schemas = schemas