further performance improvements for individual pattern matching

Author: rkh

CHANGELOG.md

@@ -58,20 +58,66 @@ set.expand("posts.index", user_id: 42) # => "/users/42/posts"
 * Major performance improvements for `Mustermann::Mapper`, as it is based on `Mustermann::Set` now, and can dispatch in logarithmic time instead of linear time.
 * Major speed improvements for sub-segment patterns with optional elements (like a format at the end of a path). These patterns are common in web applications.
 
- | Scenario                      | Improvement over 3.1  |
- | ----------------------------- | --------------------- |
- | Simple pattern compilation    | 6x speedup            |
- | Complex pattern compilation   | 30% speedup           |
- | Simple param extraction       | 2.4x speedup          |
- | Complex param extraction      | 70% speedup           |
- | Matching a simple pattern     | Same performance      |
- | Matching a complex pattern    | 8x speedup            |
- | Matching against 1k patterns  | 20x to 350x speedup   |
- | Matching against 10k patterns | 200x to 3500x speedup |
-
- Numbers are based on simple and realistic patterns run on MRI Ruby 4.0 on a MacBook Pro. The improvements you will see may vary based on your Ruby implementation, platform and patterns used.
-
- Simple and complex in the above table refer to patterns with only static segments or captures matching exactly one segment each (like `/resource/:id` or `/:controller/:action`) versus patterns with more complex captures (like `/resource/*path/:id` or `/resource/:id(.:format)?`). The matching improvements against 1k and 10k patterns assume the new `Mustermann::Set` is used. Otherwise the difference should be in line with the single pattern matching improvements.
+<table>
+  <thead>
+    <tr>
+      <th colspan="2">Scenario</th>
+      <th>Mustermann 3.1</th>
+      <th>Mustermann 4.0</th>
+      <th>Improvement</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td rowspan="5">Simple patterns</td>
+      <td>Compilation</td>
+      <td>12.1 K/s</td>
+      <td>70.8 K/s</td>
+      <td>6x</td>
+    </tr>
+    <tr>
+      <td>Matching non-repeating strings</td>
+      <td>4.5 M/s</td>
+      <td>4.5 M/s</td>
+      <td>none</td>
+    </tr>
+    <tr>
+      <td>Matching repeating strings</td>
+      <td>5.9 M/s</td>
+      <td>17.1 M/s</td>
+      <td>3x</td>
+    </tr>
+    <tr>
+      <td>Extracting params</td>
+      <td>0.7 M/s</td>
+      <td>2.2 M/s</td>
+      <td>3x</td>
+    </tr>
+    <tr>
+      <td>Matching against 1k different patterns</td>
+      <td>3 M/s</td>
+      <td>7.1 K/s</td>
+      <td>425x</td>
+    </tr>
+    <tr>
+      <td rowspan="2">Complex patterns</td>
+      <td>Extracting params</td>
+      <td>486 K/s</td>
+      <td>955 K/s</td>
+      <td>2x</td>
+    </tr>
+    <tr>
+      <td>Matching against malicious input</td>
+      <td>3.6 K/s</td>
+      <td>582 K/s</td>
+      <td>162x</td>
+    </tr>
+  </tbody>
+</table>
+
+Higher numbers are better.
+
+Performance measured on local development machine (MacBook Pro 2024, Ruby 4.0.2) with the `bench/versions.rb` script, which measures single-threaded performance.
 
 #### Housekeeping
 

bench/versions.rb

@@ -29,8 +29,10 @@
 scenarios = {
   compile: "Compilation of #{format[counts[:compile]]} patterns",
   single_match: "Matching #{format[counts[:single_match]]} times against a single pattern",
+  single_string: "Matching #{format[counts[:single_match]]} times against the same string",
   simple_params: "Extracting params #{format[counts[:params]]} times for a simple pattern",
   complex_params: "Extracting params #{format[counts[:params]]} times for a complex pattern",
+  expand: "Expanding #{format[counts[:params]]} times for a simple pattern",
   set_match: "Matching #{format[counts[:set_match]]} times against a set of #{format[counts[:set_size]]} patterns",
   look_ahead_fail: "Matching #{format[counts[:look_ahead_fail]]} times with look-ahead pattern on a long failing input (atomic group speedup)",
 }
@@ -86,13 +88,25 @@
     strings = counts[:single_match].times.map { "/foo/#{element.succ!}" }
     x.report(version) { strings.each { |string| pattern === string } }
 
+  when "single_string"
+    pattern = Mustermann.new("/foo/:bar")
+    string  = "/foo/bar"
+    x.report(version) { counts[:single_match].times { pattern.match(string) } }
+
   when "simple_params"
     pattern = Mustermann.new("/:controller/:action")
     element = String.new("a")
     100.times { pattern.params("/#{element.succ!}/show.html") }
     strings = counts[:params].times.map { "/#{element.succ!}/show.html" }
     x.report(version) { strings.each { |string| pattern.params(string) } }
-  
+
+  when "expand"
+    pattern = Mustermann.new("/foo/:bar")
+    element = String.new("a")
+    100.times { pattern.expand(bar: element.succ!) }
+    params = counts[:params].times.map { { bar: element.succ!.dup } }
+    x.report(version) { params.each { |param| pattern.expand(param) } }
+
   when "complex_params"
     pattern = Mustermann.new("/:controller/:action(.:format)")
     element = String.new("a")

mustermann/lib/mustermann/ast/fast_pattern.rb

@@ -26,17 +26,6 @@ module FastPattern
 
       private_constant :SIMPLE, :ENCODED, :SEGMENT_SCAN
 
-      # Bypasses the generic build_match overhead for simple patterns: uses
-      # MatchData#named_captures directly and avoids match.to_s / post_match /
-      # pre_match calls (all no-ops for \A…\Z anchored regexps).
-      def match(string)
-        return super unless @fast_match
-        return unless match = @regexp.match(string)
-        params = match.named_captures
-        params.transform_values! { |v| unescape(v) } if string.include?('%')
-        Match.new(self, match, params:)
-      end
-
       # Public override: fast path for simple patterns, falls through to super otherwise.
       # Must remain public to match AST::Pattern#to_ast visibility.
       def to_ast
@@ -46,8 +35,24 @@ def to_ast
         ast
       end
 
+      def params(string = nil)
+        return super unless @fast_match
+        return unless md = @regexp.match(string)
+        result = md.named_captures
+        result.transform_values! { |v| v.include?('%') ? unescape(v) : v } if string.include?('%')
+        result
+      end
+
       private
 
+      def build_match(regexp, string)
+        return super unless @fast_match
+        return unless match = regexp.match(string)
+        params = match.named_captures
+        params.transform_values! { |v| v.include?('%') ? unescape(v) : v } if string.include?('%')
+        Match.new(self, match, params: params)
+      end
+
       def simple_pattern?
         options[:capture].nil?  &&
           options[:except].nil? &&

mustermann/lib/mustermann/regexp_based.rb

@@ -20,6 +20,14 @@ def initialize(string, **options)
       @peek_regexp     = /\A#{regexp}/
       @regexp          = /\A#{regexp}\Z/
       @simple_captures = @regexp.named_captures.none? { |name, positions| positions.size > 1 || always_array?(name) }
+
+      if defined?(ObjectSpace::WeakKeyMap)
+        @match_cache = ObjectSpace::WeakKeyMap.new
+        @peek_cache  = ObjectSpace::WeakKeyMap.new
+      else
+        @match_cache = false
+        @peek_cache  = false
+      end
     end
 
     # @param (see Mustermann::Pattern#peek_size)
@@ -33,20 +41,38 @@ def peek_size(string)
     # @param (see Mustermann::Pattern#peek_match)
     # @return (see Mustermann::Pattern#peek_match)
     # @see (see Mustermann::Pattern#peek_match)
-    def peek_match(string) = build_match(@peek_regexp.match(string))
+    def peek_match(string) = cache_match(@peek_cache, @peek_regexp, string)
 
     # @param (see Mustermann::Pattern#match)
     # @return (see Mustermann::Pattern#match)
     # @see (see Mustermann::Pattern#match)
-    def match(string) = build_match(@regexp.match(string))
+    def match(string) = cache_match(@match_cache, @regexp, string)
+
+    # Extracts params directly from the regexp without allocating a Match object or
+    # populating the match cache — significant GC savings when called in hot loops.
+    # @param (see Mustermann::Pattern#params)
+    # @return (see Mustermann::Pattern#params)
+    def params(string = nil)
+      return unless md = @regexp.match(string)
+      build_params(md)
+    end
 
     extend Forwardable
     def_delegators :regexp, :===, :=~, :names
 
     private
 
-    def build_match(match)
-      return unless match
+    def cache_match(cache, regexp, string)
+      if cache
+        return cache[string] if cache.key?(string)
+        cache[string] = build_match(regexp, string)
+      else
+        build_match(regexp, string)
+      end
+    end
+
+    def build_match(regexp, string)
+      return unless match = regexp.match(string)
       Match.new(self, match, params: build_params(match))
     end
 

mustermann/spec/sinatra_spec.rb

@@ -1019,4 +1019,53 @@
     let(:pattern) { "/:b(.:c)?" }
     it { should match("/a/b.json") }
   end
+
+  describe "match caching" do
+    subject(:pattern) { Mustermann.new("/foo/:bar") }
+
+    if defined?(ObjectSpace::WeakKeyMap)
+      it "returns the same Match object for the same string object" do
+        string = "/foo/bar"
+        expect(pattern.match(string)).to be_equal(pattern.match(string))
+      end
+
+      it "returns nil for a non-matching string without caching errors" do
+        expect(pattern.match("/nope")).to be_nil
+        expect(pattern.match("/nope")).to be_nil
+      end
+    end
+
+    it "returns a match without a cache" do
+      pattern.instance_variable_set(:@match_cache, false)
+      expect(pattern.match("/foo/bar")).not_to be_nil
+      expect(pattern.match("/nope")).to be_nil
+    end
+  end
+
+  describe "params without match caching" do
+    subject(:pattern) { Mustermann.new("/params_cache_test/:bar") }
+
+    it "extracts params correctly" do
+      expect(pattern.params("/params_cache_test/baz")).to eq("bar" => "baz")
+    end
+
+    it "decodes percent-encoded params" do
+      expect(pattern.params("/params_cache_test/f%20o")).to eq("bar" => "f o")
+    end
+
+    it "returns nil for non-matching string" do
+      expect(pattern.params("/nope")).to be_nil
+    end
+
+    if defined?(ObjectSpace::WeakKeyMap)
+      it "does not populate the match cache when calling params" do
+        string = "/params_cache_test/baz"
+        cache  = pattern.instance_variable_get(:@match_cache)
+
+        pattern.params(string)
+
+        expect(cache.key?(string)).to be false
+      end
+    end
+  end
 end