openapi_first 4.2.1 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20ff22852f152edfbbf62ad27d2672d286be8e07d9ec0d3a6a4a6b8d2608ea23
-  data.tar.gz: 4d956b76a491067d3c2a7d2d0716fbad834d62f6e7d643e9ac51c92938b6416b
+  metadata.gz: ef15e925e193150f3425c32bd94986f3c069f12af86a88ad043886de13c1ca8a
+  data.tar.gz: d4f11e849a469be720cbd5973ffb04e039664101ed44484d4b4f4b2c5ef542f8
 SHA512:
-  metadata.gz: 974432feb3f2b69cf7f1d613980d54bb2cbf25ae39ff09c2afc3f9aa0a8d4246bbd17c555ef7814533dcaee9ea9eee6d9aa9856a23b5869a2dcc61f8b5c06c32
-  data.tar.gz: 907638cdecc5ba7f0504a8a41555359db2a5dd924644495848836fc39e791624283050bdd7923afcd4eedf08a26fa5bb13b8ff06d91971033a4bb3a9507d3b53
+  metadata.gz: 8aa700d2587944d67f5e2372fe7793c1cd71a76e6c772bf56938564e4f4c4221cb29e54e0ec37bec66c1da370415aabbebb7f722f4cd4fbeba478919308df6cb
+  data.tar.gz: 6ef3870f3b011ac35065775da7265d6bc6dff0b121ec0ee42a7e5b47a9fd69d17dbc25ea85723615206d9704afcaee4f65ff3f04e6c85f430ea4781316260ff8

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 4.4.0
+
+- Changed: Percent-encoded path parameters are now decoded. For example `/files/my%20file` yields `my file` for `/files/{name}`. A `+` stays a `+`. Values with a malformed encoding or that do not decode to valid UTF-8 are kept as they are. If your application decodes path parameters itself, remove that, or values get decoded twice. Known limitation: An encoded delimiter inside an array or object path parameter is decoded before the value is split, so `/files/a%2Cb,c` yields `["a", "b", "c"]`.
+- Added: You can pass a block to `OpenapiFirst::Middlewares::RequestValidation` to configure hooks and other options specifically for that middleware. With a registered name or a Definition it creates a copy of that OAD, so the registered OAD stays unchanged.
+- Fix: `OpenapiFirst.load` now accepts and applies a configuration block.
+
+## 4.3.0
+
+- Fix: Passing a block to `config.register` not works when called inside `OpenapiFirst.configure` block. Before the block was ignored.
+- Faster routing for OADs with many dynamic paths. The router now looks up path templates in a prefix tree of path segments instead of trying each template one by one.
+- Changed: If more than one path template matches a request path, the router now compares the templates segment by segment from left to right. For example `/users/{id}/{action}` wins over `/{tenant}/settings/profile` for `/users/settings/profile`. Before, the template with more literal characters overall won.
+
 ## 4.2.1
 
 - Fix deprecation warnings when using multi_json >= 1.21. openapi_first now uses `MultiJSON.parse`/`MultiJSON.generate` if available ([#508](https://github.com/ahx/openapi_first/issues/508)).

data/README.md

@@ -84,6 +84,19 @@ The request validation middleware returns a 4xx if the request is invalid or not
 use OpenapiFirst::Middlewares::RequestValidation
 ```
 
+You can pass a block to configure [hooks](#hooks) and other options for this middleware only:
+
+```ruby
+use OpenapiFirst::Middlewares::RequestValidation, :v1 do |config|
+  config.request_validation_error_response = :jsonapi
+  config.after_request_validation do |validated_request|
+    warn validated_request.error.message if validated_request.invalid?
+  end
+end
+```
+
+If you pass a registered name or a Definition together with a block, the middleware uses a copy of that OAD that keeps its configuration and adds yours. The registered OAD stays unchanged.
+
 #### Error responses
 
 openapi_first produces a useful machine readable error response that can be customized.

data/lib/openapi_first/child_configuration.rb

@@ -6,16 +6,20 @@ module OpenapiFirst
     def initialize(parent:)
       super()
       @parent = parent
-      @request_validation_error_response = parent.request_validation_error_response
+      @request_validation_error_response = nil
       @path = parent.path
       @regexp_resolver = parent.regexp_resolver
     end
 
     private attr_reader :parent
 
+    def request_validation_error_response
+      @request_validation_error_response || parent.request_validation_error_response
+    end
+
     HOOKS.each do |hook|
       define_method(hook) do |&block|
-        return hooks[hook].chain(parent.hooks[hook]) if block.nil?
+        return hooks[hook].chain(parent.public_send(hook)) if block.nil?
 
         hooks[hook] << block
         block

data/lib/openapi_first/configuration.rb

@@ -19,8 +19,8 @@ module OpenapiFirst
       @regexp_resolver = nil
     end
 
-    def register(path_or_definition, as: :default)
-      OpenapiFirst.register(path_or_definition, as:)
+    def register(path_or_definition, as: :default, &)
+      OpenapiFirst.register(path_or_definition, as:, &)
     end
 
     attr_reader :hooks, :request_validation_error_response, :regexp_resolver

data/lib/openapi_first/definition.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'path_template'
 require_relative 'builder'
 require 'forwardable'
 
@@ -23,10 +24,11 @@ module OpenapiFirst
     # @param contents [Hash] The OpenAPI document.
     # @param filepath [String] The file path of the OpenAPI document.
     # @param path_prefix [String,nil] An optional path prefix, that is not documented, that all requests begin with.
-    def initialize(contents, filepath = nil, path_prefix = nil)
+    # @param config [Configuration] The configuration to use. Gets yielded and frozen.
+    def initialize(contents, filepath = nil, path_prefix = nil, config: OpenapiFirst.configuration.child)
       @filepath = filepath
       @path_prefix = path_prefix
-      @config = OpenapiFirst.configuration.child
+      @config = config
       yield @config if block_given?
       @config.freeze
       @router = Builder.build_router(contents, filepath:, config:)
@@ -34,6 +36,14 @@ module OpenapiFirst
       @paths = @router.routes.map(&:path).to_a.uniq # TODO: Refactor
     end
 
+    # Returns a new Definition of the same document whose configuration is a child of this one's.
+    # @visibility private
+    # @yield [Configuration]
+    # @return [Definition]
+    def configure(&)
+      Definition.new(@resolved, filepath, path_prefix, config: @config.child, &)
+    end
+
     # Gives access to the raw resolved Hash. Like `mydefinition['components'].dig('schemas', 'Stations')`
     # @!method [](key)
     # @return [Hash]
@@ -80,8 +90,7 @@ module OpenapiFirst
       request_def = routes.lazy.flat_map(&:requests).find { |r| r.operation_id == operation_id.to_s }
       raise ArgumentError, "Operation #{operation_id.inspect} is not defined in #{key}." unless request_def
 
-      request_def.path.gsub(/\{([^}]+)\}/) do
-        name = Regexp.last_match(1)
+      PathTemplate.expand(request_def.path) do |name|
         params.fetch(name.to_sym) do
           params.fetch(name) do
             raise ArgumentError, "Missing path parameter #{name.inspect} for operation #{operation_id.inspect}."

data/lib/openapi_first/middlewares/request_validation.rb

@@ -29,20 +29,19 @@ module OpenapiFirst
       #   :error_response The Class to use for error responses.
       #                   This can be a Symbol-name of an registered error response (:default, :jsonapi)
       #                   or it can be set to false to disable returning a response.
-      #                   default: OpenapiFirst::Plugins::Default::ErrorResponse (Config.default_options.error_response)
-      def initialize(app, spec = nil, options = {})
+      #                   default: the configured request_validation_error_response
+      # @yield [Configuration] Optional block to configure hooks and other options for this middleware.
+      #   If spec is a registered name or a Definition, this uses a new Definition that inherits its configuration,
+      #   so the registered Definition is not changed.
+      def initialize(app, spec = nil, options = {}, &)
         @app = app
         if spec.is_a?(Hash)
           options = spec
           spec = options[:spec]
         end
         @raise = options.fetch(:raise_error, false)
+        @definition = OpenapiFirst.load(spec || :default, &)
         @error_response_class = error_response_option(options[:error_response])
-
-        spec ||= :default
-        spec = OpenapiFirst[spec] if spec.is_a?(Symbol)
-
-        @definition = spec.is_a?(Definition) ? spec : OpenapiFirst.load(spec)
       end
 
       # @attr_reader [Proc] app The upstream Rack application
@@ -70,7 +69,7 @@ module OpenapiFirst
         return if value == false
         return OpenapiFirst.find_error_response(value) if value.is_a?(Symbol)
 
-        value || OpenapiFirst.configuration.request_validation_error_response
+        value || @definition.config.request_validation_error_response
       end
     end
   end

data/lib/openapi_first/path_template.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  # Path templating as described in https://spec.openapis.org/oas/v3.1.0#path-templating
+  # @visibility private
+  module PathTemplate
+    VARIABLE = /\{(?<name>[^{}]+)\}/
+    SEGMENT_VARIABLE = /\A#{VARIABLE}\z/
+
+    # @return [Boolean] whether the path contains at least one variable
+    def self.template?(path)
+      path.match?(VARIABLE)
+    end
+
+    # @return [Boolean] whether the path segment consists of exactly one variable
+    def self.variable?(segment)
+      segment.match?(SEGMENT_VARIABLE)
+    end
+
+    # @return [Array<String>] the variable names in order of appearance
+    def self.variable_names(template)
+      template.scan(VARIABLE).flatten
+    end
+
+    # Replaces each variable with the value the block returns for its name
+    def self.expand(template)
+      template.gsub(VARIABLE) { yield Regexp.last_match(:name) }
+    end
+  end
+end

data/lib/openapi_first/registry.rb

@@ -23,7 +23,6 @@ module OpenapiFirst
           "#{name}.register(#{path_or_definition.inspect}, as: :my_other_api)"
         )
       end
-
       definition = OpenapiFirst.load(path_or_definition, &)
       definitions[as] = definition
       definition

data/lib/openapi_first/router/path_trie.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'rack/utils'
+require_relative '../path_template'
+require_relative 'segment_pattern'
+
+module OpenapiFirst
+  class Router
+    # @visibility private
+    class PathTrie
+      def initialize
+        @static = {}
+        @partial = {}
+        @variable = nil
+        @leaf = nil
+      end
+
+      def add(template, value)
+        names = PathTemplate.variable_names(template)
+        node = template.split('/', -1).reduce(self) { |parent, segment| parent.child(segment) }
+        node.leaf ||= [value, names]
+      end
+
+      def match(path)
+        values = []
+        value, names = find(path.split('/', -1), 0, values)
+        return unless value
+
+        values.map! { decode(_1) } if path.include?('%')
+        [value, names.zip(values).to_h]
+      end
+
+      def find(segments, index, values)
+        return @leaf if index == segments.size
+
+        @static[segments[index]]&.find(segments, index + 1, values) ||
+          find_partial(segments, index, values) ||
+          find_variable(segments, index, values)
+      end
+
+      protected
+
+      attr_accessor :leaf
+
+      def child(segment)
+        return @variable ||= PathTrie.new if PathTemplate.variable?(segment)
+        return partial_child(segment) if PathTemplate.template?(segment)
+
+        @static[segment] ||= PathTrie.new
+      end
+
+      private
+
+      def decode(value)
+        decoded = Rack::Utils.unescape_path(value).force_encoding(Encoding::UTF_8)
+        decoded.valid_encoding? ? decoded : value
+      end
+
+      def find_partial(segments, index, values)
+        @partial.each_value do |pattern, node|
+          captures = pattern.match(segments[index])
+          next unless captures
+
+          values.concat(captures)
+          found = node.find(segments, index + 1, values)
+          return found if found
+
+          values.pop(captures.size)
+        end
+        nil
+      end
+
+      def find_variable(segments, index, values)
+        segment = segments[index]
+        return if @variable.nil? || segment.empty?
+
+        values << segment
+        found = @variable.find(segments, index + 1, values)
+        values.pop unless found
+        found
+      end
+
+      def partial_child(segment)
+        @partial[segment] ||= [SegmentPattern.new(segment), PathTrie.new]
+        @partial = @partial.sort_by.with_index { |(key, _), i| [-literal_length(key), i] }.to_h
+        @partial[segment].last
+      end
+
+      def literal_length(segment)
+        segment.gsub(PathTemplate::VARIABLE, '').length
+      end
+    end
+  end
+end

data/lib/openapi_first/router/segment_pattern.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../path_template'
+
+module OpenapiFirst
+  class Router
+    # Matches one path segment against a segment of a path template that mixes literals and variables
+    # @visibility private
+    class SegmentPattern
+      def initialize(segment)
+        @pattern = build_pattern(segment)
+      end
+
+      # @return [Array<String>, nil] the variable values in order of appearance, or nil
+      def match(segment)
+        @pattern.match(segment)&.captures
+      end
+
+      private
+
+      def build_pattern(segment)
+        parts = segment.split(PathTemplate::VARIABLE).each_slice(2).map do |literal, name|
+          "#{Regexp.escape(literal)}#{'([^/?#]+)' if name}"
+        end
+        /\A#{parts.join}\z/
+      end
+    end
+  end
+end

data/lib/openapi_first/router.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'router/path_template'
+require_relative 'path_template'
+require_relative 'router/path_trie'
 require_relative 'router/find_content'
 require_relative 'router/find_response'
 
@@ -27,15 +28,14 @@ module OpenapiFirst
 
     def initialize
       @static = {}
-      @dynamic = {} # TODO: use a trie or similar
+      @dynamic = {}
+      @trie = PathTrie.new
     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
-
+        request_methods.map do |request_method, content|
           Route.new(path:, request_method:, requests: content.requests.each_value.lazy.uniq,
                     responses: content.responses.each_value.lazy.flat_map(&:values))
         end
@@ -95,7 +95,7 @@ module OpenapiFirst
     def route_at(path, request_method)
       request_method = request_method.upcase
       path_item = if PathTemplate.template?(path)
-                    @dynamic[path] ||= { template: PathTemplate.new(path) }
+                    @dynamic[path] ||= {}.tap { @trie.add(path, _1) }
                   else
                     @static[path] ||= {}
                   end
@@ -112,15 +112,7 @@ module OpenapiFirst
       found = @static[request_path]
       return [found, {}] if found
 
-      @dynamic.each_value.reduce(nil) do |best, path_item|
-        params = path_item[:template].match(request_path)
-        next best unless params
-
-        candidate = [path_item, params]
-        next candidate unless best
-
-        params.values.sum(&:length) < best[1].values.sum(&:length) ? candidate : best
-      end
+      @trie.match(request_path)
     end
   end
 end

data/lib/openapi_first/sinatra.rb

@@ -62,9 +62,6 @@ module OpenapiFirst
   # encoded characters, ...) - a request Sinatra matches is not re-checked against openapi_first's own
   # path matching. Avoid path shapes where the two routers disagree.
   module Sinatra
-    PATH_PARAMETER = /\{[^}]+\}/
-    private_constant :PATH_PARAMETER
-
     # The configuration lives in Sinatra settings (rather than plain instance variables) so a
     # subclass of a configured app inherits the loaded description and its operation index.
     def self.registered(app)
@@ -133,7 +130,7 @@ module OpenapiFirst
     end
 
     def operation_handler(path_template, block)
-      param_names = path_template.scan(PATH_PARAMETER).map! { |placeholder| placeholder[1..-2] }
+      param_names = PathTemplate.variable_names(path_template)
       proc do |*captures|
         path_params = param_names.zip(captures).to_h
         validated = settings.openapi_definition.validate_request(request, path_template:, path_params:)
@@ -147,7 +144,7 @@ module OpenapiFirst
     end
 
     def sinatra_pattern(path)
-      path.gsub(PATH_PARAMETER) { |placeholder| ":#{placeholder[1..-2].gsub(/[^A-Za-z0-9_]/, '_')}" }
+      PathTemplate.expand(path) { |name| ":#{name.gsub(/[^A-Za-z0-9_]/, '_')}" }
     end
 
     def build_operation_index(definition)

data/lib/openapi_first/test/configuration.rb

@@ -25,8 +25,8 @@ module OpenapiFirst
       # Register OADs, but don't load them just yet
       # @param [OpenapiFirst::OAD] oad The OAD to register
       # @param [Symbol] as The name to register the OAD under
-      def register(oad, as: :default)
-        Test.register(oad, as:)
+      def register(oad, as: :default, &)
+        Test.register(oad, as:, &)
       end
 
       # Observe a rack app

data/lib/openapi_first/version.rb

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

data/lib/openapi_first.rb

@@ -62,15 +62,20 @@ module OpenapiFirst
     configuration.plugin(name, **)
   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
+  # Load and dereference an OpenAPI spec file or return the Definition if it's already loaded.
+  # If a block is given together with a Definition or Symbol,
+  # this returns a new Definition with the configuration block applied.
+  # @param filepath_or_definition [String, Symbol, Definition] The path to the file, a registered name or a Definition
   # @param only [Proc, nil] An optional proc to filter paths. It is called with the path string and should return
   # true/false
   # @param path_prefix [String, nil] An optional path prefix, that is not documented, that all requests begin with.
+  # @yieldparam config [Configuration] Configuration of the returned Definition.
   # @return [Definition]
   def self.load(filepath_or_definition, only: nil, path_prefix: nil, &)
-    return filepath_or_definition if filepath_or_definition.is_a?(Definition)
-    return self[filepath_or_definition] if filepath_or_definition.is_a?(Symbol)
+    if filepath_or_definition.is_a?(Definition) || filepath_or_definition.is_a?(Symbol)
+      definition = self[filepath_or_definition]
+      return block_given? ? definition.configure(&) : definition
+    end
 
     filepath = filepath_or_definition
     raise FileNotFoundError, "File not found: #{filepath}" unless File.exist?(filepath)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 4.2.1
+  version: 4.4.0
 platform: ruby
 authors:
 - Andreas Haller
@@ -108,6 +108,7 @@ files:
 - lib/openapi_first/parameter_content_parsers.rb
 - lib/openapi_first/parameters_parser.rb
 - lib/openapi_first/parsed_request.rb
+- lib/openapi_first/path_template.rb
 - lib/openapi_first/plugins.rb
 - lib/openapi_first/plugins/x_public.rb
 - lib/openapi_first/query_string_parser.rb
@@ -125,7 +126,8 @@ files:
 - lib/openapi_first/router.rb
 - lib/openapi_first/router/find_content.rb
 - lib/openapi_first/router/find_response.rb
-- lib/openapi_first/router/path_template.rb
+- lib/openapi_first/router/path_trie.rb
+- lib/openapi_first/router/segment_pattern.rb
 - lib/openapi_first/schema/hash.rb
 - lib/openapi_first/schema/validation_error.rb
 - lib/openapi_first/schema/validation_result.rb

data/lib/openapi_first/router/path_template.rb

@@ -1,47 +0,0 @@
-# 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 = /(\{[^{}]+\})/
-
-      def self.template?(string)
-        string.include?('{')
-      end
-
-      def initialize(template)
-        @template = template
-        @pattern = build_pattern(template)
-      end
-
-      def to_s
-        @template
-      end
-
-      def match(path)
-        return {} if path == @template
-
-        matches = path.match(@pattern)
-        return unless matches
-
-        matches.named_captures
-      end
-
-      private
-
-      def build_pattern(template)
-        parts = template.split(TEMPLATE_EXPRESSION).map! do |part|
-          if part.start_with?('{')
-            "(?<#{part[1..-2]}>[^/?#]+)"
-          else
-            Regexp.escape(part)
-          end
-        end
-
-        /^#{parts.join}$/
-      end
-    end
-  end
-end