mustermann 3.0.4 → 4.0.1

data/lib/mustermann/regexp_based.rb

@@ -11,14 +11,37 @@ module Mustermann
     attr_reader :regexp
     alias_method :to_regexp, :regexp
 
+    # @api private
+    supported_options :cache
+
     # @param (see Mustermann::Pattern#initialize)
     # @return (see Mustermann::Pattern#initialize)
     # @see (see Mustermann::Pattern#initialize)
     def initialize(string, **options)
+      cache = options.delete(:cache) { true }
+
       super
-      regexp       = compile(**options)
-      @peek_regexp = /\A#{regexp}/
-      @regexp      = /\A#{regexp}\Z/
+      regexp           = compile(**options)
+      @peek_regexp     = Mustermann.dedup(/\A#{regexp}/)
+      @regexp          = Mustermann.dedup(/\A#{regexp}\Z/)
+      @simple_captures = @regexp.named_captures.none? { |name, positions| positions.size > 1 || always_array?(name) }
+
+      cache_class = ObjectSpace::WeakKeyMap if defined?(ObjectSpace::WeakKeyMap)
+
+      case cache
+      when true
+        @match_cache = cache_class&.new || false
+        @peek_cache  = cache_class&.new || false
+      when false
+        @match_cache = false
+        @peek_cache  = false
+      when Hash
+        @match_cache = cache[:match] || cache_class&.new || false
+        @peek_cache  = cache[:peek]  || cache_class&.new || false
+      else
+        @match_cache = cache.new
+        @peek_cache  = cache.new
+      end
     end
 
     # @param (see Mustermann::Pattern#peek_size)
@@ -32,17 +55,55 @@ module Mustermann
     # @param (see Mustermann::Pattern#peek_match)
     # @return (see Mustermann::Pattern#peek_match)
     # @see (see Mustermann::Pattern#peek_match)
-    def peek_match(string)
-      @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) = 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, :===, :=~, :match, :names, :named_captures
+    def_delegators :regexp, :===, :=~, :names
+
+    private
+
+    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
 
-    def compile(**options)
-      raise NotImplementedError, 'subclass responsibility'
+    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
     end
 
-    private :compile
+    def compile(**options) = raise NotImplementedError, 'subclass responsibility'
   end
 end

data/lib/mustermann/regular.rb

@@ -21,7 +21,7 @@ module Mustermann
     # @see (see Mustermann::Pattern#initialize)
     def initialize(string, check_anchors: true, **options)
       string = $1 if string.to_s =~ /\A\(\?\-mix\:(.*)\)\Z/ && string.inspect == "/#$1/"
-      string = string.source.gsub!(/(?<!\\)(?:\s|#.*$)/, '') if extended_regexp?(string)
+      string = string.source.gsub!(/(?<!\\)(?:\s|#.*$)/, EMPTY_STRING) if extended_regexp?(string)
       @check_anchors = check_anchors
       super(string, **options)
     end

data/lib/mustermann/router.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/set'
+
+module Mustermann
+  # An extremely simple, Rack-compatible router implementation using {Mustermann::Set} for pattern matching.
+  #
+  # @example Basic usage
+  #   require 'mustermann/router'
+  #
+  #   router = Mustermann::Router.new do
+  #     get "/hello/:name" do |env|
+  #       name = env["mustermann.match"][:name]
+  #       [200, { "content-type" => "text/plain" }, ["Hello, #{name}!"]]
+  #     end
+  #   end
+  #
+  #   # in config.ru
+  #   use Rack::Head
+  #   run router
+  #
+  # @example Routing to other applications
+  #   router = Mustermann::Router.new do
+  #     get  "/users",     MyApp::Users::Index
+  #     get  "/users/:id", MyApp::Users::Show
+  #     post "/users",     MyApp::Users::Create
+  #     fallback           MyApp::NotFound
+  #   end
+  #
+  #   router.path_for(MyApp::Users::Show, id: 42) # => "/users/42"
+  #
+  # @example As middleware
+  #   use Mustermann::Router do
+  #     get("/up") { [200, { "content-type" => "text/plain" }, ["Up!"]] }
+  #   end
+  #
+  #   run MyApp
+  #
+  # @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 POST PUT PATCH DELETE OPTIONS LINK UNLINK].freeze
+    private_constant :VERBS, :NOT_FOUND
+
+    # Initializes a new router.
+    # @param key [String] The key under which the route match will be stored in the Rack environment hash (default: "mustermann.match").
+    # @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)] }
+      @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)
+      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)
+    end
+
+    def fallback(fallback = nil, &block) = @fallback = fallback || block || @fallback
+
+    # Adds a route for the given verb and pattern, with the given target.
+    #
+    # @note Shorthand methods, like `get`, `post`, etc. dynamically are defined for all supported verbs.
+    #
+    # @param verb [String] HTTP verb (e.g. "GET", "POST")
+    # @param pattern [String, Mustermann::Pattern] Pattern string or Mustermann pattern (e.g. "/users/:id")
+    # @param target [#call, nil] The Rack application or middleware to call when the route matches. Can be passed a block as well.
+    # @yield [env] Block to be used as the target if no explicit target is given.
+    # @yieldparam env [Hash] The Rack environment hash for the request.
+    # @return [void]
+    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)
+      @sets[verb].add(pattern, target || block)
+    end
+
+    # Helps generate links
+    #
+    # @param app [#call] The Rack application or middleware for which to generate the path.
+    # @param (see Mustermann::Expander#expand)
+    # @return [String] The generated path.
+    def path_for(app, behavior = nil, params = EMPTY_HASH)
+      set = @sets.values.find { |s| s.has_value?(app) } || @sets[VERBS.first]
+      set.expand(app, behavior, params)
+    end
+
+    VERBS.each do |verb|
+      define_method(verb.downcase) { |*args, **opts, &block| route(verb, *args, **opts, &block) }
+    end
+  end
+end

data/lib/mustermann/set/cache.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+require 'mustermann/equality_map'
+
+module Mustermann
+  class Set
+    class Cache
+      PLACEHOLDER = Object.new.freeze
+
+      def self.new(matcher) = defined?(ObjectSpace::WeakKeyMap) ? super : matcher
+
+      def initialize(matcher)
+        @matcher = matcher
+        reset_cache
+      end
+
+      def add(pattern)
+        @matcher.add(pattern)
+        reset_cache
+      end
+
+      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
+  end
+end

data/lib/mustermann/set/linear.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+require 'mustermann/set/match'
+
+module Mustermann
+  class Set
+    class Linear
+      def initialize(set, patterns = [])
+        @set      = set
+        @patterns = patterns
+      end
+
+      def add(pattern)
+        @patterns << pattern
+      end
+
+      def match(string, all: false, peek: false)
+        result = [] if all
+        @patterns.each do |pattern|
+          next unless match = peek ? pattern.peek_match(string) : pattern.match(string)
+          return Match.new(match, value: @set.values_for_pattern(pattern)&.first) unless all
+          values = @set.values_for_pattern(pattern) || [nil]
+          values.each { |value| result << Match.new(match, value:) }
+        end
+        result
+      end
+
+      def optimize! = nil
+    end
+
+    private_constant :Linear
+  end
+end

data/lib/mustermann/set/match.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require 'mustermann/match'
+
+module Mustermann
+  class Set
+
+    # Subclass of {Mustermann::Match} that also includes the value associated with the pattern that produced the match.
+    class Match < Mustermann::Match
+      # @return the value associated with the pattern that produced the match, if any
+      attr_reader :value
+
+      # (see Mustermann::Match#initialize)
+      # @option options [Object] :value the value associated with the pattern that produced the match, if any
+      def initialize(*, value: nil, **)
+        @value = value
+        super(*, **)
+      end
+
+      # @see Mustermann::Match#eql?
+      def eql?(other) = super && value == other.value
+    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

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+require 'mustermann/ast/translator'
+require 'mustermann/set/match'
+
+module Mustermann
+  class Set
+    class Trie
+      class Translator < AST::Translator
+        translate(:node) { |trie, **o| trie[t.compile(node)] }
+        translate(:separator) { |trie, **options| trie[payload] }
+
+        translate(:root) do |trie, **options|
+          leaves = t(payload, trie, **options)
+          if leaves.is_a? Array
+            leaves.each do |leaf|
+              leaf.patterns ||= []
+              leaf.patterns << t.pattern
+            end
+          else
+            leaves.patterns ||= []
+            leaves.patterns << t.pattern
+          end
+          leaves
+        end
+
+        translate(:char) do |trie, **options|
+          return trie if payload.empty?
+          trie[payload]
+        end
+
+        translate(:optional) do |trie, **options|
+          [*t(payload, trie, **options), trie]
+        end
+
+        translate(Array) do |trie, **options|
+          i = 0
+          while i < size
+            element = self[i]
+            if element.is_a? :char or element.is_a? :separator
+              trie = t(element, trie, **options)
+              i += 1
+            elsif element.is_a? :splat and self[i + 1]&.is_a? :separator
+              # Compile splat+separator together so the splat is bounded by the separator,
+              # then continue building the trie for the remaining elements.
+              trie = trie[t.compile(self[i..i + 1])]
+              i += 2
+            elsif element.is_a? :splat or !self[i + 1]&.is_a? :separator
+              return trie[t.compile(self[i..-1])]
+            else
+              trie = t(element, trie, **options)
+              return trie.flat_map { |node| t(self[i + 1..-1], node, **options) } if trie.is_a? Array
+              i += 1
+            end
+          end
+          trie
+        end
+
+        attr_reader :pattern
+
+        def initialize(pattern)
+          @pattern  = pattern
+          @compiler = pattern.compiler.new
+          @options  = pattern.options
+          super()
+        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_accessor :patterns, :set, :static, :dynamic
+
+      def initialize(set, patterns = nil)
+        @set             = set
+        @patterns        = nil
+        @dynamic         = nil
+        @static          = nil
+        @stride          = nil
+        @fast_static     = nil
+        @byte_lookup     = nil
+        @dynamic_entries = nil
+        patterns&.each { |pattern| add(pattern) }
+      end
+
+      def [](key)
+        case key = Mustermann.dedup(key)
+        when String
+          @static      ||= {}
+          @static[key] ||= Trie.new(@set)
+        when Regexp
+          @dynamic      ||= {}
+          @dynamic[key] ||= Trie.new(@set)
+        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 @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
+
+        if @dynamic_entries&.any?
+          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 = 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] ||= Mustermann.dedup(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: 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, params, all:, matched_length: position, post_match: string[position..], pre_match: EMPTY_STRING)
+          return matches unless all
+          result.concat(matches)
+        end
+
+        result
+      end
+
+      NIL_VALUES = [nil].freeze
+
+      def build_matches(string, params, all: false, matched_length: string.size, post_match: EMPTY_STRING, pre_match: EMPTY_STRING)
+        result = [] if all
+        matched = string[0, matched_length]
+
+        @patterns&.each do |pattern|
+          next if pattern.except_regexp&.match?(matched)
+
+          pattern_params = build_pattern_params(pattern, params)
+
+          values = @set.values_for_pattern(pattern) || NIL_VALUES
+          values.each do |value|
+            match = Set::Match.new(pattern, string, matched:, params: pattern_params, value:, post_match:, pre_match:)
+            return match unless all
+            result << match
+          end
+        end
+
+        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&.any?
+          @fast_static = nil
+          @byte_lookup = nil
+          @stride      = 1
+          # no children to recurse into
+        else
+          @fast_static = nil
+          @byte_lookup = Array.new(256)
+          @stride      = 1
+          @static&.each { |k, v| @byte_lookup[k.getbyte(0)] = v }
+          @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
+
+        @fast_static     = Mustermann.dedup(@fast_static)
+        @dynamic_entries = Mustermann.dedup(@dynamic_entries)
+        @byte_lookup     = Mustermann.dedup(@byte_lookup)
+      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({ EMPTY_STRING => 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
+  end
+end