mustermann 4.0.0.alpha → 4.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 295f1b612e2e5a51c3edb1d1fa1c1ed66f56792d3782dda3adb1f48082d702ac
-  data.tar.gz: db02262f6b9853a63b8718e87e984526655b90e0e0648c1250ea4af23cb497da
+  metadata.gz: c6a0beea1e6d365356c6444910ec10200dcaf98f1968e88ac2fe91e0a7b23b93
+  data.tar.gz: 1be43d10761af60bbd4cdd5d087214073984825b05f397de8d1475a7f35686d6
 SHA512:
-  metadata.gz: ae9f2778ec8d47418feec32de4ee1ca837b2ad22076ccd59c438872f075bbcd7deef2be648a7710570e45cb49e5c82085b5da1435641c5143131fee69734b8ec
-  data.tar.gz: d43838b66491e62f6fc7cf066fcce44ae2a7ec9a28e47abbad100519d3db13d1b0c8eed789bdff64b5f3f18e6548cfbe2e6312288ebe96c6bf236aac80eb0807
+  metadata.gz: 710a7afa55bdbd0f6fb17845458572ea9adaf8149674c9b1e54ddba333382be9e05136d37d7680595bead97b21bee76334d129cbf96c320b0f975688b20ad29c
+  data.tar.gz: 64e15b87da6f731fce7d0e50eb4ee13511c175b979765d9a233a066c026026c0c82300e22b8492db8220d2f89995cadb471c78ac00da60ea8be360a22b8290be

data/README.md

@@ -420,19 +420,6 @@ set.add('/ping')
 set.match('/ping').value  # => nil
 ```
 
-### Conflict Resolution
-
-The set follows insertion order: when two patterns both match a string, the one added first wins. Use `match_all` to retrieve every match:
-
-``` ruby
-set = Mustermann::Set.new
-set.add('/foo',  :static)
-set.add('/:var', :dynamic)
-
-set.match('/foo').value            # => :static
-set.match_all('/foo').map(&:value) # => [:static, :dynamic]
-```
-
 ### Peeking
 
 `peek_match` matches a prefix of the input rather than the full string. The unmatched remainder is available via `post_match`:
@@ -489,6 +476,66 @@ object = MyObject.new
 Mustermann.new(object, type: :rails) # => #<Mustermann::Rails:"/foo">
 ```
 
+### Match order
+
+A set can match patterns and values in loose or strict insertion order.
+
+You have the following guarantees without strict ordering:
+
+* Patterns with dynamic segments in the same position and equal static parts will always match in the order they were added.
+* Multiple values for the same pattern will retain their insertion order in regards to that pattern.
+
+Trade-offs without strict ordering:
+
+* Static segments may be favored over dynamic segments. If you want to guarantee this behavior, enable trie-mode proactively.
+* When a pattern has multiple values, these will follow each other directly when using `match_all` or `peek_match_all`.
+
+Strict ordering comes with both a performance overhead and marginally increased memory usage.
+How big the performance overhead is depends on the number of patterns that overlap in the strings they successfully match against.
+It does use Ruby's built-in sorting, which on MRI is based on quicksort. The memory overhead grows linear with the number
+of pattern and value combinations, but is generally small compared to the memory used by the patterns and values themselves.
+
+With strict ordering enabled, patterns and values are guaranteed to occur in insertion order.
+
+Without strict ordering, not using a trie:
+
+```ruby
+set = Mustermann::Set.new(use_trie: false)
+
+set.add("/:path",  :first)
+set.add("/static", :second)
+set.add("/:path",  :third)
+
+set.match("/static").value             # => :first
+set.match_all("/static").map(&:value)  # => [:first, :third, :second]
+```
+
+Without strict ordering, using a trie:
+
+```ruby
+set = Mustermann::Set.new(use_trie: true)
+
+set.add("/:path",  :first)
+set.add("/static", :second)
+set.add("/:path",  :third)
+
+set.match("/static").value             # => :second
+set.match_all("/static").map(&:value)  # => [:second, :first, :third]
+```
+
+With strict ordering enabled, regardless of whether a trie is used or not:
+
+```ruby
+set = Mustermann::Set.new(strict_order: true)
+
+set.add("/:path",  :first)
+set.add("/static", :second)
+set.add("/:path",  :third)
+
+set.match("/static").value             # => :first
+set.match_all("/static").map(&:value)  # => [:first, :second, :third]
+```
+
 <a name="-duck-typing-respond-to"></a>
 ### `respond_to?`
 

data/lib/mustermann/ast/fast_pattern.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Mustermann
+  module AST
+    # Mixin for AST::Pattern subclasses that accelerates compilation and AST
+    # construction for "simple" patterns: only static path segments and
+    # unconstrained full-segment captures (e.g. /foo/:bar/baz/:id).
+    # Patterns with optional groups, constraints, or non-default options fall
+    # through to the full AST pipeline.
+    module FastPattern
+      # Matches patterns that consist only of slashes, static segments, and
+      # simple :name captures — no optional groups, no constraints.
+      SIMPLE = /\A(?:\/(?:[a-zA-Z0-9\-_.~]+|:[a-zA-Z_]\w*))+\z/
+
+      # Regexp fragment for each printable ASCII char, matching the same output
+      # as Compiler#encoded with uri_decode: true.
+      ENCODED = (0..127).each_with_object({}) do |byte, h|
+        c   = byte.chr
+        pct = '%%%02X' % byte
+        reps = [c, pct, pct.downcase].uniq
+        h[c] = reps.size == 1 ? Regexp.escape(reps.first) :
+          '(?:%s)' % reps.map { |r| Regexp.escape(r) }.join('|')
+      end.freeze
+
+      SEGMENT_SCAN = %r{(/)|(:[a-zA-Z_]\w*)|([^/:]+)}
+
+      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, string, 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
+        return super unless simple_pattern?
+        ast = self.class.ast_cache.fetch(@string) { build_fast_ast }
+        @param_converters ||= {}
+        ast
+      end
+
+      private
+
+      def simple_pattern?
+        options[:capture].nil?  &&
+          options[:except].nil? &&
+          options.fetch(:greedy, true) != false &&
+          uri_decode &&
+          @string.match?(SIMPLE)
+      end
+
+      def compile(**options)
+        return super unless simple_pattern?
+        result = fast_compile
+        @fast_match = true
+        result
+      end
+
+      def fast_compile
+        tokens = @string.scan(SEGMENT_SCAN)
+        src = String.new
+        tokens.each_with_index do |(sep, cap, chars), i|
+          if sep
+            src << '\\/'
+          elsif cap
+            # Mirror the compiler: wrap in atomic group when the next token is a separator.
+            if tokens[i + 1]&.first
+              src << "(?<#{cap[1..]}>(?>[^/\\?#]+))"
+            else
+              src << "(?<#{cap[1..]}>[^/\\?#]+)"
+            end
+          else
+            chars.each_char { |c| src << ENCODED[c] }
+          end
+        end
+        Regexp.new(src)
+      end
+
+      def build_fast_ast
+        nodes = []
+        pos   = 0
+        @string.scan(SEGMENT_SCAN) do |sep, cap, chars|
+          if sep
+            node = Node::Separator.new('/')
+            node.start, node.stop = pos, pos + 1
+            nodes << node
+            pos += 1
+          elsif cap
+            node = Node::Capture.new(cap[1..])
+            node.start, node.stop = pos, pos + cap.length
+            nodes << node
+            pos += cap.length
+          else
+            chars.each_char do |c|
+              node = Node::Char.new(c)
+              node.start, node.stop = pos, pos + 1
+              nodes << node
+              pos += 1
+            end
+          end
+        end
+        root = Node::Root.new
+        root.payload = nodes
+        root.pattern = @string
+        root.start, root.stop = 0, @string.length
+        root
+      end
+    end
+  end
+end

data/lib/mustermann/ast/pattern.rb

@@ -23,6 +23,11 @@ module Mustermann
       instance_delegate %i[parser compiler transformer validation template_generator param_scanner boundaries] => 'self.class'
       instance_delegate parse: :parser, transform: :transformer, validate: :validation,
         generate_templates: :template_generator, scan_params: :param_scanner, set_boundaries: :boundaries
+      
+      # @api private
+      def self.ast_cache
+        @ast_cache ||= EqualityMap.new
+      end
 
       # @api private
       # @return [#parse] parser object for pattern
@@ -96,13 +101,14 @@ module Mustermann
       # Internal AST representation of pattern.
       # @!visibility private
       def to_ast
-        @ast_cache ||= EqualityMap.new
-        @ast_cache.fetch(@string) do
+        ast = self.class.ast_cache.fetch(@string) do
           ast   = parse(@string, pattern: self)
           ast &&= transform(ast)
           ast &&= set_boundaries(ast, string: @string)
           validate(ast)
         end
+        @param_converters ||= scan_params(ast) if ast
+        ast
       end
 
       # All AST-based pattern implementations support expanding.
@@ -140,6 +146,11 @@ module Mustermann
         @param_converters ||= scan_params(to_ast)
       end
 
+      # @api private
+      def identity_params?(params)
+        param_converters.empty? && super
+      end
+
       private :compile, :parse, :transform, :validate, :generate_templates, :param_converters, :scan_params, :set_boundaries
     end
   end

data/lib/mustermann/pattern.rb

@@ -358,6 +358,7 @@ module Mustermann
     # @!visibility private
     def unescape(string, decode = uri_decode)
       return string unless decode and string
+      return string unless string.include?('%')
       @@uri.unescape(string)
     end
 
@@ -369,6 +370,13 @@ module Mustermann
       ALWAYS_ARRAY.include? key
     end
 
+    # @api private
+    # Returns true if params can be used as-is without calling map_param.
+    # Used by Set::Trie to skip building a redundant copy of the params hash.
+    def identity_params?(params)
+      !params.any? { |k, v| v.is_a?(Array) || always_array?(k) || (v.respond_to?(:include?) && v.include?('%')) }
+    end
+
     private :unescape, :map_param, :respond_to_special?
     private_constant :ALWAYS_ARRAY
   end

data/lib/mustermann/rails.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require 'mustermann'
 require 'mustermann/ast/pattern'
+require 'mustermann/ast/fast_pattern'
 require 'mustermann/versions'
 
 module Mustermann
@@ -12,6 +13,7 @@ module Mustermann
   # @see Mustermann::Pattern
   # @see file:README.md#rails Syntax description in the README
   class Rails < AST::Pattern
+    include AST::FastPattern
     extend Versions
     register :rails
 

data/lib/mustermann/regexp_based.rb

@@ -19,6 +19,7 @@ module Mustermann
       regexp       = compile(**options)
       @peek_regexp = /\A#{regexp}/
       @regexp      = /\A#{regexp}\Z/
+      @simple_captures = @regexp.named_captures.none? { |name, positions| positions.size > 1 || always_array?(name) }
     end
 
     # @param (see Mustermann::Pattern#peek_size)
@@ -34,14 +35,10 @@ module Mustermann
     # @see (see Mustermann::Pattern#peek_match)
     def peek_match(string) = build_match(@peek_regexp.match(string))
 
-    def match(string) = build_match(@regexp.match(string))
-
-    # private
-
-    # def build_match(match)
-    #   return unless match
-    #   Match.new(self, match.string, match.named_captures, post_match: match.post_match, pre_match: match.pre_match)
-    # end
+    def match(string)
+      return unless match = @regexp.match(string)
+      Match.new(self, string, build_params(match))
+    end
 
     extend Forwardable
     def_delegators :regexp, :===, :=~, :names
@@ -50,12 +47,21 @@ module Mustermann
 
     def build_match(match)
       return unless match
-      params = match.regexp.named_captures.to_h do |name, positions|
-        value = positions.size < 2 && !always_array?(name) ? map_param(name, match[name]) :
-          positions.flat_map { |pos| map_param(name, match[pos]) }
-        [name, value]
+      Match.new(self, match.to_s, build_params(match), post_match: match.post_match, pre_match: match.pre_match)
+    end
+
+    def build_params(match)
+      if @simple_captures
+        params = match.named_captures
+        return params if params.empty? || identity_params?(params)
+        params.each_with_object({}) { |(k, v), h| h[k] = map_param(k, v) }
+      else
+        match.regexp.named_captures.to_h do |name, positions|
+          value = positions.size < 2 && !always_array?(name) ? map_param(name, match[name]) :
+            positions.flat_map { |pos| map_param(name, match[pos]) }
+          [name, value]
+        end
       end
-      Match.new(self, match.to_s, params, post_match: match.post_match, pre_match: match.pre_match)
     end
 
     def compile(**options) = raise NotImplementedError, 'subclass responsibility'

data/lib/mustermann/router.rb

@@ -11,11 +11,12 @@ module Mustermann
   #   router = Mustermann::Router.new do
   #     get "/hello/:name" do |env|
   #       name = env["mustermann.match"][:name]
-  #       [200, { "Content-Type" => "text/plain" }, ["Hello, #{name}!"]]
+  #       [200, { "content-type" => "text/plain" }, ["Hello, #{name}!"]]
   #     end
   #   end
   #
   #   # in config.ru
+  #   use Rack::Head
   #   run router
   #
   # @example Routing to other applications
@@ -30,7 +31,7 @@ module Mustermann
   #
   # @example As middleware
   #   use Mustermann::Router do
-  #     get("/up") { [200, { "Content-Type" => "text/plain" }, ["Up!"]] }
+  #     get("/up") { [200, { "content-type" => "text/plain" }, ["Up!"]] }
   #   end
   #
   #   run MyApp
@@ -38,8 +39,8 @@ module Mustermann
   # @see Mustermann::Set
   # @see https://rack.github.io/rack/
   class Router
-    NOT_FOUND = [404, { "Content-Type" => "text/plain", "X-Cascade" => "pass" }, ["Not found"]].freeze
-    VERBS     = %w[GET HEAD POST PUT PATCH DELETE OPTIONS LINK UNLINK].freeze
+    NOT_FOUND = [404, { "content-type" => "text/plain", "x-cascade" => "pass" }, ["Not found"]].freeze
+    VERBS     = %w[GET POST PUT PATCH DELETE OPTIONS LINK UNLINK].freeze
     private_constant :VERBS, :NOT_FOUND
 
     # Initializes a new router.
@@ -47,17 +48,22 @@ module Mustermann
     # @param options [Hash] Options to be passed to the Mustermann patterns.
     def initialize(fallback = nil, key: "mustermann.match", **options, &block)
       @key      = key
-      @sets     = VERBS.to_h { |verb| [verb, Set.new] }
-      @options  = options
-      @fallback = fallback || ->(env) { NOT_FOUND }
-      instance_exec(&block) if block_given?
+      @sets     = VERBS.to_h { |verb| [verb, Set.new(**options)] }
+      @fallback = fallback || ->(env) { NOT_FOUND.dup }
+
+      if block_given?
+        instance_exec(&block)
+        @sets.each_value(&:optimize!)
+      end
     end
 
     # @param env [Hash] The Rack environment hash for the request.
     # @return [Array] The Rack response array (status, headers, body).
     def call(env)
-      if routes = @sets[env["REQUEST_METHOD"]] and match = routes.match(env["PATH_INFO"] || "/")
-        env = env.merge(@key => match)
+      request_method = env["REQUEST_METHOD"] || "GET"
+      request_method = "GET" if request_method == "HEAD"
+      if routes = @sets[request_method] and match = routes.match(env["PATH_INFO"] || "/")
+        env[@key] = match
         return match.value.call(env)
       end
       @fallback.call(env)
@@ -78,7 +84,6 @@ module Mustermann
     def route(verb, pattern, target = nil, **options, &block)
       raise ArgumentError, "need to provide target, :to or a block" unless target || block
       raise ArgumentError, "unknown verb: #{verb}" unless VERBS.include?(verb)
-      pattern = Mustermann.new(pattern, **@options, **options)
       @sets[verb].add(pattern, target || block)
     end
 

data/lib/mustermann/set/cache.rb

@@ -5,24 +5,42 @@ module Mustermann
   class Set
     class Cache
       PLACEHOLDER = Object.new.freeze
+      EMPTY_ARRAY = [].freeze
 
       def self.new(matcher) = defined?(ObjectSpace::WeakKeyMap) ? super : matcher
 
       def initialize(matcher)
         @matcher = matcher
-        @caches = {}
+        reset_cache
       end
 
       def add(pattern)
         @matcher.add(pattern)
-        @caches.clear
+        reset_cache
       end
 
-      def match(string, **options)
-        cache  = @caches[options] ||= ObjectSpace::WeakKeyMap.new
-        result = cache[string]    ||= @matcher.match(string, **options) || PLACEHOLDER
-        result unless result.equal? PLACEHOLDER
+      def match(string, all: false, peek: false)
+        cache  = @match_cache[all][peek]
+        result = cache[string] ||= @matcher.match(string, all: all, peek: peek) || PLACEHOLDER
+        return result unless result.equal? PLACEHOLDER
+        all ? EMPTY_ARRAY : nil
       end
+
+      def reset_cache
+        @match_cache = {
+          true => {
+            true => ObjectSpace::WeakKeyMap.new,
+            false => ObjectSpace::WeakKeyMap.new
+          },
+          false => {
+            true => ObjectSpace::WeakKeyMap.new,
+            false => ObjectSpace::WeakKeyMap.new
+          }
+        }
+      end
+
+      def optimize! = @matcher.optimize!
+      def track(...) = @matcher.track(...)
     end
 
     private_constant :Cache

data/lib/mustermann/set/linear.rb

@@ -23,6 +23,8 @@ module Mustermann
         end
         result
       end
+
+      def optimize! = nil
     end
 
     private_constant :Linear

data/lib/mustermann/set/match.rb

@@ -1,15 +1,22 @@
 # frozen_string_literal: true
 require 'mustermann/match'
-require 'delegate'
 
 module Mustermann
   class Set
-    class Match < DelegateClass(Mustermann::Match)
+    class Match < Mustermann::Match
       attr_reader :value
 
-      def initialize(*args, value: nil, match: nil, **options)
+      def initialize(pattern = nil, string = nil, params = {}, value: nil, match: nil, post_match: '', pre_match: '')
         @value = value
-        super(match || Mustermann::Match.new(*args, **options))
+        if match
+          @pattern    = match.pattern
+          @string     = match.string
+          @params     = match.params
+          @post_match = match.post_match
+          @pre_match  = match.pre_match
+        else
+          super(pattern, string, params, post_match:, pre_match:)
+        end
       end
     end
   end

data/lib/mustermann/set/strict_order.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mustermann
+  class Set
+    class StrictOrder
+      def initialize(matcher)
+        @matcher = matcher
+        @order   = {}
+        @count   = 0
+      end
+
+      def add(...)  = @matcher.add(...)
+      def optimize! = @matcher.optimize!
+      
+      def match(string, all: false, peek: false)
+        possible = @matcher.match(string, all: true, peek: peek)
+        possible.sort_by! { |m| @order.dig(m.pattern, m.value) }
+        all ? possible : possible.first
+      end
+
+      def track(pattern, value)
+        @order[pattern] ||= {}
+        @order[pattern][value] = @count += 1
+      end
+    end
+
+    private_constant :StrictOrder
+  end
+end

data/lib/mustermann/set/trie.rb

@@ -20,11 +20,8 @@ module Mustermann
         end
 
         translate(:char) do |trie, **options|
-          strings = t.possible_strings(payload)
-          return trie if strings.empty?
-          primary_node = trie[strings.first]
-          strings[1..-1].each { |s| trie.wire(s, primary_node) }
-          primary_node
+          return trie if payload.empty?
+          trie[payload]
         end
 
         translate(:optional) do |trie, **options|
@@ -63,21 +60,21 @@ module Mustermann
           super()
         end
 
-        def compile(node, **options) = /\A#{@compiler.translate(node, **@options, **options)}/
-
-        def possible_strings(char)
-          return [] if char.empty?
-          @compiler.class.char_representations(char, **@options.slice(:uri_decode, :space_matches_plus))
-        end
+        # \G anchors to a position passed to String#match, avoiding substring allocation.
+        def compile(node, **options) = /\G#{@compiler.translate(node, **@options, **options)}/
       end
 
       attr_reader :patterns, :set, :static, :dynamic
 
       def initialize(set, patterns = [])
-        @set      = set
-        @patterns = []
-        @dynamic  = {}
-        @static   = {}
+        @set             = set
+        @patterns        = []
+        @dynamic         = {}
+        @static          = {}
+        @stride          = nil
+        @fast_static     = nil
+        @byte_lookup     = nil
+        @dynamic_entries = nil
         patterns.each { |pattern| add(pattern) }
       end
 
@@ -88,51 +85,70 @@ module Mustermann
         end
       end
 
-      def wire(string, target)
-        return if string.empty?
-        if string.size == 1
-          @static[string] ||= target
-        else
-          (@static[string[0]] ||= Trie.new(@set)).wire(string[1..-1], target)
-        end
-      end
-
       def match(string, all: false, peek: false, position: 0, params: {})
+        optimize! if @stride.nil?
         return build_matches(string, params, all:) if position >= string.size
         result = [] if all
 
-        if node = @static[string[position]]
-          if nested_result = node.match(string, all:, peek:, position: position + 1, params:)
-            return nested_result unless all
-            result.concat(nested_result)
+        if @fast_static
+          stride = @stride
+          if node = @fast_static[string[position, stride]]
+            if nested_result = node.match(string, all:, peek:, position: position + stride, params:)
+              return nested_result unless all
+              result.concat(nested_result)
+            end
+          end
+        elsif @byte_lookup
+          if node = @byte_lookup[string.getbyte(position)]
+            if nested_result = node.match(string, all:, peek:, position: position + 1, params:)
+              return nested_result unless all
+              result.concat(nested_result)
+            end
           end
         end
 
-        anchored = {}
-        @dynamic.each do |matcher, node|
-          remaining = string[position..-1]
-          regexp_match = matcher.match(remaining)
-          # Non-greedy patterns (e.g. splat .*?) can match 0 chars on non-empty input, making
-          # no progress. Retry with an end-of-string anchor so they consume the full remainder.
-          if regexp_match&.to_s&.empty? && !remaining.empty?
-            anchored_matcher = anchored[matcher] ||= Regexp.new(matcher.source + '\z')
-            regexp_match = anchored_matcher.match(remaining)
-          end
-          next unless regexp_match
+        unless @dynamic_entries.empty?
+          anchored    = nil
+          base_params = all ? params : nil
+          @dynamic_entries.each do |matcher, node, capture_names, fast_name|
+            if fast_name
+              # Fast path: unconstrained single-segment capture — no regex, no MatchData.
+              end_pos = string.index('/', position) || string.size
+              next if end_pos == position
+              edge_params = all ? base_params.dup : params
+              edge_params[fast_name] = string.byteslice(position, end_pos - position)
+              nested_result = node.match(string, all:, params: edge_params, peek:, position: end_pos)
+              return nested_result unless all
+              result.concat(nested_result)
+              next
+            end
 
-          regexp_match.named_captures.each do |name, value|
-            params = params.dup
-            params[name] = params[name]&.dup || []
-            params[name] << value
-          end
+            regexp_match = matcher.match(string, position)
+            # Non-greedy patterns (e.g. splat .*?) can match 0 chars on non-empty input, making
+            # no progress. Retry with an end-of-string anchor so they consume the full remainder.
+            if regexp_match && regexp_match.end(0) == position
+              anchored ||= {}
+              anchored_matcher = anchored[matcher] ||= Regexp.new(matcher.source + '\z')
+              regexp_match = anchored_matcher.match(string, position)
+            end
+            next unless regexp_match
+
+            edge_params = all ? base_params.dup : params
+            capture_names.each do |name|
+              value = regexp_match[name]
+              next unless value
+              existing = edge_params[name]
+              edge_params[name] = existing ? (existing.is_a?(Array) ? existing << value : [existing, value]) : value
+            end
 
-          nested_result = node.match(string, all:, params:, peek:, position: position + regexp_match.to_s.size)
-          return nested_result unless all
-          result.concat(nested_result)
+            nested_result = node.match(string, all:, params: edge_params, peek:, position: regexp_match.end(0))
+            return nested_result unless all
+            result.concat(nested_result)
+          end
         end
 
         if peek
-          matches = build_matches(string[0, position], params, all:, post_match: string[position..])
+          matches = build_matches(string[0, position], params, all:, post_match: string[position..], pre_match: '')
           return matches unless all
           result.concat(matches)
         end
@@ -140,21 +156,19 @@ module Mustermann
         result
       end
 
-      def build_matches(string, params, all: false, **options)
+      NIL_VALUES = [nil].freeze
+
+      def build_matches(string, params, all: false, post_match: '', pre_match: '')
         result = [] if all
 
         @patterns.each do |pattern|
           next if pattern.except_regexp&.match?(string)
 
-          pattern_params = params.to_h do |key, value|
-            value = value.flat_map { |v| pattern.map_param(key, v) }
-            value = value.first if value.size < 2 and not pattern.always_array?(key)
-            [key, value]
-          end
+          pattern_params = build_pattern_params(pattern, params)
 
-          values = @set.values_for_pattern(pattern) || [nil]
+          values = @set.values_for_pattern(pattern) || NIL_VALUES
           values.each do |value|
-            match = Set::Match.new(pattern, string, pattern_params, value:, **options)
+            match = Set::Match.new(pattern, string, pattern_params, value:, post_match:, pre_match:)
             return match unless all
             result << match
           end
@@ -163,9 +177,91 @@ module Mustermann
         result
       end
 
+      def build_pattern_params(pattern, params)
+        return params if pattern.identity_params?(params)
+
+        result = {}
+        params.each do |key, raw|
+          if raw.is_a?(Array)
+            val = raw.flat_map { |v| pattern.map_param(key, v) }
+            val = val.first if val.size < 2 && !pattern.always_array?(key)
+          else
+            val = pattern.map_param(key, raw)
+            val = [val] if pattern.always_array?(key)
+          end
+          result[key] = val
+        end
+        result
+      end
+
       def add(pattern)
+        @stride          = nil
+        @fast_static     = nil
+        @byte_lookup     = nil
+        @dynamic_entries = nil
         Translator.new(pattern).translate(pattern.to_ast, self)
       end
+
+      # Compacts the trie by replacing sequential single-char static lookups with a
+      # single stride-length hash lookup. The stride is the minimum number of static
+      # steps all paths from this node share before hitting a dynamic edge or branch.
+      def optimize!
+        depth = min_static_depth
+        if depth > 1
+          @fast_static = build_stride_hash(depth)
+          @byte_lookup = nil
+          @stride      = depth
+          @fast_static.each_value(&:optimize!)
+        elsif @static.empty?
+          @fast_static = nil
+          @byte_lookup = nil
+          @stride      = 1
+          # no children to recurse into
+        else
+          @fast_static = nil
+          @byte_lookup = Array.new(256)
+          @static.each { |k, v| @byte_lookup[k.getbyte(0)] = v }
+          @stride      = 1
+          @static.each_value(&:optimize!)
+        end
+        @dynamic.each_value(&:optimize!)
+        @dynamic_entries = @dynamic.map do |matcher, node|
+          names = matcher.names.each(&:freeze)
+          # Detect unconstrained single-segment captures: can use fast string.index instead of regex.
+          # Two conditions: (1) the edge is a bare capture (source starts with \G(?<name>), no leading
+          # static chars) and (2) the capture's character class excludes '/' (PATH_INFO never has '?' or '#').
+          fast = if names.size == 1
+            name = names.first
+            matcher.source.start_with?("\\G(?<#{name}>") && !matcher.match?('/') ? name : nil
+          end
+          [matcher, node, names, fast]
+        end
+      end
+
+      protected
+
+      # Returns the minimum number of guaranteed static steps from this node across
+      # all possible paths, before encountering a dynamic edge, a terminal pattern,
+      # or an empty node. Branching is allowed; only the minimum depth matters.
+      def min_static_depth
+        return 0 if @dynamic.any?
+        return 0 if @patterns.any?
+        return 0 if @static.empty?
+        1 + @static.values.map { |node| node.min_static_depth }.min
+      end
+
+      private
+
+      # Builds a hash whose keys are +stride+-character strings and whose values are
+      # the trie nodes reached after consuming exactly those characters.
+      def build_stride_hash(stride)
+        stride.times.reduce({ "" => self }) do |frontier, _|
+          frontier.each_with_object({}) do |(prefix, node), nxt|
+            node.static.each { |char, child| nxt[prefix + char] = child }
+          end
+        end
+      end
+
     end
 
     private_constant :Trie

data/lib/mustermann/set.rb

@@ -3,6 +3,7 @@ require 'mustermann'
 require 'mustermann/expander'
 require 'mustermann/set/cache'
 require 'mustermann/set/linear'
+require 'mustermann/set/strict_order'
 require 'mustermann/set/trie'
 
 module Mustermann
@@ -61,11 +62,27 @@ module Mustermann
     #   Mustermann::Set.new { { '/users/:id' => :users } }
     #
     # @param mapping [Array] initial patterns or mappings to add
-    # @param additional_values [:raise, :ignore, :append] behavior when extra keys are passed to {#expand};
-    #   defaults to +:raise+
-    # @param options [Hash] pattern options forwarded to {Mustermann.new} (e.g. +type: :rails+)
+    #
+    # @param additional_values [:raise, :ignore, :append] behavior when extra keys are passed to {#expand}.
+    #   Defaults to +:raise+
+    #
+    # @param use_trie [Boolean, Integer]
+    #   whether to use a trie for matching
+    #   If an Integer is given, it is the number of patterns at which to switch from linear to trie matching.
+    #   Defaults to 50
+    #
+    # @param use_cache [Boolean]
+    #   whether to cache matches not yet garbage collected. Defaults to +true+
+    #
+    # @param strict_order [Boolean]
+    #   whether to match patterns in strict insertion order rather than trie order. Defaults to +false+.
+    #   See {#use_strict_order?} for details
+    #
+    # @param options [Hash]
+    #   pattern options forwarded to {Mustermann.new} (e.g. +type: :rails+)
+    #
     # @raise [ArgumentError] if +additional_values+ is not a recognized behavior symbol
-    def initialize(*mapping, additional_values: :raise, use_trie: 50, use_cache: true, **options, &block)
+    def initialize(*mapping, additional_values: :raise, use_trie: 50, use_cache: true, strict_order: false, **options, &block)
       raise ArgumentError, "Illegal value %p for additional_values" % additional_values unless Expander::ADDITIONAL_VALUES.include? additional_values
       raise ArgumentError, "Illegal value %p for use_trie" % use_trie unless [true, false].include?(use_trie) or use_trie.is_a? Integer
 
@@ -77,6 +94,7 @@ module Mustermann
       @options           = {}
       @expanders         = {}
       @additional_values = additional_values
+      @strict_order      = strict_order
 
       options.each do |key, value|
         if key.is_a? Symbol
@@ -89,8 +107,66 @@ module Mustermann
       update(mapping)
 
       block.arity == 0 ? update(yield) : yield(self) if block
+
+      optimize!
     end
 
+    # A set can match patterns and values in loose or strict insertion order.
+    #
+    # You have the following guarantees without strict ordering:
+    # - Patterns with dynamic segments in the same position and equal static parts will always match in the order they were added.
+    # - Multiple values for the same pattern will retain their insertion order in regards to that pattern.
+    #
+    # Trade-offs without strict ordering:
+    # - Static segments may be favored over dynamic segments. If you want to guarantee this behavior, enable trie-mode proactively.
+    # - When a pattern has multiple values, these will follow each other directly when using {#match_all} or {#peek_match_all}.
+    # 
+    # Strict ordering comes with both a performance overhead and marginally increased memory usage.
+    # How big the performance overhead is depends on the number of patterns that overlap in the strings they successfully match against.
+    # It does use Ruby's built-in sorting, which on MRI is based on quicksort. The memory overhead grows linear with the number
+    # of pattern and value combinations, but is generally small compared to the memory used by the patterns and values themselves.
+    # 
+    # With strict ordering enabled, patterns and values are guaranteed to occur in insertion order.
+    #
+    # @example Without strict ordering, not using a trie
+    #   set = Mustermann::Set.new(use_trie: false)
+    # 
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #
+    #   set.match("/static").value             # => :first
+    #   set.match_all("/static").map(&:value)  # => [:first, :third, :second]
+    #
+    # @example Without strict ordering, using a trie
+    #   set = Mustermann::Set.new(use_trie: true)
+    #
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #   
+    #   set.match("/static").value             # => :second
+    #   set.match_all("/static").map(&:value)  # => [:second, :first, :third]
+    #
+    # @example With strict ordering
+    #   set = Mustermann::Set.new(strict_order: true)
+    #   
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #   
+    #   set.match("/static").value             # => :first
+    #   set.match_all("/static").map(&:value)  # => [:first, :second, :third]
+    #
+    # @return [Boolean] whether matching happens in strict pattern/value insertion order
+    def strict_order? = @strict_order
+    
+    # @return [Boolean] whether caching is enabled
+    def use_cache? = @use_cache
+    
+    # @return [Boolean] whether trie optimization is enabled
+    def use_trie? = @use_trie == true
+
     # Adds a pattern to the set, optionally associated with one or more values.
     #
     # If the pattern is given as a String it will be compiled via {Mustermann.new}
@@ -129,6 +205,7 @@ module Mustermann
         @reverse_mapping[value] ||= []
         @reverse_mapping[value] << pattern unless @reverse_mapping[value].include? pattern
         @expanders[value]&.add(pattern)
+        @matcher.track(pattern, value) if strict_order?
       end
 
       self
@@ -148,8 +225,8 @@ module Mustermann
     #   set['/users/42']  # => :users_show (or nil)
     #
     # @example Pattern lookup
-    #   pat = Mustermann.new('/users/:id')
-    #   set[pat]          # => :users_show (or nil)
+    #   pattern = Mustermann.new('/users/:id')
+    #   set[pattern] # => :users_show (or nil)
     #
     # @param pattern_or_string [String, Pattern]
     # @return [Object, nil] the associated value, or +nil+ if not found
@@ -300,6 +377,9 @@ module Mustermann
     # @!visibility private
     def values_for_pattern(pattern) = @mapping[pattern] # :nodoc:
 
+    # Runs trie optimizations pro-actively and explicitly rather than at match time.
+    def optimize! = @matcher&.optimize!
+
     protected
 
     attr_reader :mapping
@@ -307,21 +387,22 @@ module Mustermann
     private
 
     def add_pattern(pattern)
-      case @use_trie
-      when true
-        @matcher ||= Trie.new(self, @mapping.keys)
-      when Integer
-        if @mapping.size >= @use_trie
-          @matcher = Trie.new(self, @mapping.keys)
-          @use_trie = true
-        end
+      if @use_trie.is_a? Integer and @mapping.size >= @use_trie
+        @use_trie = true
+        @matcher = build_matcher
       end
 
-      @matcher ||= Linear.new(self, @mapping.keys)
-      @matcher = Cache.new(@matcher) if @use_cache and not @matcher.is_a? Cache
+      @matcher ||= build_matcher
       @matcher.add(pattern)
-
       @expanders[self]&.add(pattern)
     end
+
+    def build_matcher
+      factory = use_trie? ? Trie : Linear
+      matcher = factory.new(self, @mapping.keys)
+      matcher = StrictOrder.new(matcher) if strict_order?
+      matcher = Cache.new(matcher) if use_cache?
+      matcher
+    end
   end
 end

data/lib/mustermann/sinatra.rb

@@ -2,6 +2,7 @@
 require 'mustermann'
 require 'mustermann/identity'
 require 'mustermann/ast/pattern'
+require 'mustermann/ast/fast_pattern'
 require 'mustermann/sinatra/parser'
 require 'mustermann/sinatra/safe_renderer'
 require 'mustermann/sinatra/try_convert'
@@ -15,6 +16,7 @@ module Mustermann
   # @see Mustermann::Pattern
   # @see file:README.md#sinatra Syntax description in the README
   class Sinatra < AST::Pattern
+    include AST::FastPattern
     include Concat::Native
     register :sinatra
 

data/lib/mustermann/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Mustermann
-  VERSION ||= '4.0.0.alpha'
+  VERSION ||= '4.0.0.alpha3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mustermann
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha
+  version: 4.0.0.alpha3
 platform: ruby
 authors:
 - Konstantin Haase
@@ -30,6 +30,7 @@ files:
 - lib/mustermann/ast/boundaries.rb
 - lib/mustermann/ast/compiler.rb
 - lib/mustermann/ast/expander.rb
+- lib/mustermann/ast/fast_pattern.rb
 - lib/mustermann/ast/node.rb
 - lib/mustermann/ast/param_scanner.rb
 - lib/mustermann/ast/parser.rb
@@ -57,6 +58,7 @@ files:
 - lib/mustermann/set/cache.rb
 - lib/mustermann/set/linear.rb
 - lib/mustermann/set/match.rb
+- lib/mustermann/set/strict_order.rb
 - lib/mustermann/set/trie.rb
 - lib/mustermann/sinatra.rb
 - lib/mustermann/sinatra/parser.rb