ruby_routes 2.5.0 → 2.6.0

data/lib/ruby_routes/router.rb

@@ -6,6 +6,7 @@ require_relative 'router/http_helpers'
 require_relative 'router/resource_helpers'
 require_relative 'constant'
 require_relative 'route_set'
+
 module RubyRoutes
   # RubyRoutes::Router
   #
@@ -64,15 +65,28 @@ module RubyRoutes
 
     # Initialize the router.
     #
+    # @param strategy [Class] The matching strategy to use.
     # @param definition_block [Proc] The block to define routes.
-    def initialize(&definition_block)
-      @route_set   = RouteSet.new
+    def initialize(strategy: Strategies::HybridStrategy, &definition_block)
+      @route_set   = RouteSet.new(strategy: strategy)
       @route_utils = RubyRoutes::Utility::RouteUtility.new(@route_set)
       @scope_stack = []
       @concerns    = {}
+      @frozen      = false
       instance_eval(&definition_block) if definition_block
     end
 
+    # Add a route to the route set.
+    #
+    # @param path [String] The route path.
+    # @param options [Hash] The route options.
+    # @return [void]
+    def add_route(path, options = {})
+      ensure_unfrozen!
+      scoped_options = apply_scope(path, options)
+      @route_utils.define(scoped_options[:path], scoped_options.except(:path))
+    end
+
     # Build a finalized router.
     #
     # @param definition_block [Proc] The block to define routes.
@@ -88,12 +102,7 @@ module RubyRoutes
       return self if @frozen
 
       @frozen = true
-      if @route_set.respond_to?(:finalize!)
-        @route_set.finalize!
-      else
-        @route_set.freeze
-      end
-      @route_utils.freeze if @route_utils.respond_to?(:freeze)
+      @route_set.freeze
       @scope_stack.freeze
       @concerns.freeze
       self
@@ -155,9 +164,9 @@ module RubyRoutes
     # @return [Router] self.
     def namespace(namespace_name, options = {}, &block)
       ensure_unfrozen!
-      push_scope({ path: "/#{namespace_name}", module: namespace_name }.merge(options)) do
-        instance_eval(&block) if block
-      end
+      scoped_options = { path: "/#{namespace_name}", module: namespace_name }.merge(options)
+      scope(scoped_options, &block)
+      self
     end
 
     # Define a scope.
@@ -169,26 +178,16 @@ module RubyRoutes
       ensure_unfrozen!
       scope_entry = options_or_path.is_a?(String) ? { path: options_or_path } : options_or_path
       push_scope(scope_entry) { instance_eval(&block) if block }
+      self
     end
 
-    # Define constraints.
-    #
-    # @param constraints_hash [Hash] The constraints for the scope.
-    # @param block [Proc] The block for nested routes.
-    # @return [Router] self.
-    def constraints(constraints_hash = {}, &block)
-      ensure_unfrozen!
-      push_scope(constraints: constraints_hash) { instance_eval(&block) if block }
-    end
-
-    # Define defaults.
-    #
-    # @param defaults_hash [Hash] The default values for the scope.
-    # @param block [Proc] The block for nested routes.
-    # @return [Router] self.
-    def defaults(defaults_hash = {}, &block)
-      ensure_unfrozen!
-      push_scope(defaults: defaults_hash) { instance_eval(&block) if block }
+    # Metaprogram `constraints` and `defaults` for DRYness.
+    %i[constraints defaults].each do |scope_type|
+      define_method(scope_type) do |options_hash = {}, &block|
+        ensure_unfrozen!
+        push_scope(scope_type => options_hash) { instance_eval(&block) if block }
+        self
+      end
     end
 
     # ---- Concerns ----------------------------------------------------------

data/lib/ruby_routes/segment.rb

@@ -23,15 +23,15 @@ module RubyRoutes
   class Segment
     # Build an appropriate segment instance for the provided token.
     #
-    # @param text [String, Symbol, #to_s] raw segment token
+    # @param segment_token [String, Symbol, #to_s] raw segment token
     # @return [RubyRoutes::Segments::BaseSegment]
     #
     # @example
     #   Segment.for(":id")    # => DynamicSegment
     #   Segment.for("*files") # => WildcardSegment
     #   Segment.for("users")  # => StaticSegment
-    def self.for(text)
-      segment_text  = text.to_s
+    def self.for(segment_token)
+      segment_text  = segment_token.to_s
       segment_key   = segment_text.empty? ? :default : segment_text.getbyte(0)
       segment_class = RubyRoutes::Constant::SEGMENTS[segment_key] || RubyRoutes::Constant::SEGMENTS[:default]
       segment_class.new(segment_text)

data/lib/ruby_routes/segments/base_segment.rb

@@ -21,6 +21,14 @@ module RubyRoutes
       # @param raw_segment_text [String, Symbol, nil]
       def initialize(raw_segment_text = nil)
         @raw_text = raw_segment_text.to_s if raw_segment_text
+        @param_name = nil
+      end
+
+      # Get the parameter name for this segment (if any).
+      #
+      # @return [String, nil]
+      def param_name
+        @param_name
       end
 
       # Indicates whether this segment is a wildcard (greedy) segment.

data/lib/ruby_routes/segments/static_segment.rb

@@ -23,10 +23,12 @@ module RubyRoutes
     #
     # @api internal
     class StaticSegment < BaseSegment
+      attr_reader :literal_text
+
       # @param raw_segment_text [String] literal segment token
       def initialize(raw_segment_text)
         super(raw_segment_text)
-        @literal_text = raw_segment_text
+        @literal_text = raw_segment_text.freeze
       end
 
       # Ensure a static child node for this literal under +parent_node+.

data/lib/ruby_routes/strategies/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  module Strategies
+    # Base
+    #
+    # Defines the interface for matching strategies.
+    module Base
+      def add(route)
+        raise NotImplementedError, "#{self.class.name} must implement #add"
+      end
+
+      def find(path, http_method)
+        raise NotImplementedError, "#{self.class.name} must implement #find"
+      end
+    end
+  end
+end

data/lib/ruby_routes/strategies/hash_based_strategy.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module RubyRoutes
+  module Strategies
+    # HashBasedStrategy
+    #
+    # A simple hash-based lookup strategy for route matching.
+    class HashBasedStrategy
+      include Base
+
+      def initialize
+        @routes = {}
+      end
+
+      def add(route)
+        route.methods.each do |method|
+          key = "#{method.upcase}::#{route.path&.downcase}"
+          @routes[key] = route
+        end
+      end
+
+      def find(path, http_method)
+        key = "#{http_method.upcase}::#{path&.downcase}"
+        route = @routes[key]
+        return nil unless route
+
+        [route, {}]
+      end
+    end
+  end
+end

data/lib/ruby_routes/strategies/hybrid_strategy.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../radix_tree'
+
+module RubyRoutes
+  module Strategies
+    # HybridStrategy: Combines hash-based lookup for static routes with
+    # radix tree lookup for dynamic routes.
+    #
+    # Performance optimization:
+    # - Static routes: O(1) hash lookup
+    # - Dynamic routes: O(path length) radix tree traversal
+    # - Automatic classification based on route pattern
+    class HybridStrategy
+      include Base
+
+      def initialize
+        @static_routes = {}
+        @dynamic_routes = RadixTree.new
+      end
+
+      # Add a route to the appropriate storage based on whether it's static or dynamic
+      #
+      # @param route [Route] The route to add
+      def add(route)
+        if static_route?(route.path)
+          @static_routes[route.path] ||= {}
+          route.methods.each do |method|
+            @static_routes[route.path][method] = route
+          end
+        else
+          # Extract path, methods, and handler from route for RadixTree
+          @dynamic_routes.add(route.path, route.methods, route)
+        end
+      end
+
+      # Find a route for the given path and method
+      #
+      # @param path [String] The request path
+      # @param method [String] The HTTP method
+      # @return [Array<Route, Hash>, nil] [route, params] or nil if not found
+      def find(path, method)
+        # Try static routes first (fastest path)
+        if @static_routes.key?(path) && @static_routes[path].key?(method)
+          route = @static_routes[path][method]
+          return [route, {}]
+        end
+
+        # Fall back to dynamic routes
+        result = @dynamic_routes.find(path, method)
+
+        # RadixTree returns [nil, {}] when no route found, convert to nil
+        return nil if result && result.first.nil?
+
+        result
+      end
+
+      private
+
+      # Determine if a route path is static (no parameters)
+      #
+      # @param path [String] The route path
+      # @return [Boolean] true if static, false if dynamic
+      def static_route?(path)
+        !path.include?(':') && !path.include?('*')
+      end
+    end
+  end
+end

data/lib/ruby_routes/strategies/radix_tree_strategy.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../radix_tree'
+
+module RubyRoutes
+  module Strategies
+    # RadixTreeStrategy
+    #
+    # Encapsulates RadixTree-based route matching.
+    class RadixTreeStrategy
+      def initialize
+        @radix_tree = RadixTree.new
+      end
+
+      def add(route)
+        @radix_tree.add(route.path, route.methods, route)
+      end
+
+      def find(path, http_method)
+        @radix_tree.find(path, http_method)
+      end
+    end
+  end
+end

data/lib/ruby_routes/strategies.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'strategies/base'
+require_relative 'strategies/radix_tree_strategy'
+require_relative 'strategies/hash_based_strategy'

data/lib/ruby_routes/utility/key_builder_utility.rb

@@ -49,40 +49,18 @@ module RubyRoutes
         # - Records it in the nested pool.
         # - Tracks insertion in a fixed ring; when full, overwrites oldest.
         #
-        # @param http_method [String] The HTTP method (e.g., "GET").
         # @param request_path [String] The request path (e.g., "/users").
         # @return [String] A frozen canonical key.
         def fetch_request_key(http_method, request_path)
           @mutex.synchronize do
-            method_key, path_key = prepare_keys(http_method, request_path)
-
+            method_key = http_method.freeze
+            path_key = request_path.to_s.freeze
             bucket = @request_key_pool[method_key] ||= {}
-            return bucket[path_key] if bucket[path_key]
-
-            handle_cache_miss(bucket, method_key, path_key)
+            bucket[path_key] || create_and_cache_key(bucket, method_key, path_key)
           end
         end
 
-        private
-
-        # Prepare keys by freezing them if necessary.
-        #
-        # @param http_method [String] The HTTP method.
-        # @param request_path [String] The request path.
-        # @return [Array<String>] An array containing the frozen method and path keys.
-        def prepare_keys(http_method, request_path)
-          method_key = http_method.frozen? ? http_method : http_method.dup.freeze
-          path_key = request_path.frozen? ? request_path : request_path.dup.freeze
-          [method_key, path_key]
-        end
-
-        # Handle a cache miss by creating a composite key and updating the ring buffer.
-        #
-        # @param bucket [Hash] The bucket for the method key.
-        # @param method_key [String] The HTTP method key.
-        # @param path_key [String] The path key.
-        # @return [String] The composite key.
-        def handle_cache_miss(bucket, method_key, path_key)
+        def create_and_cache_key(bucket, method_key, path_key)
           composite = "#{method_key}:#{path_key}".freeze
           bucket[path_key] = composite
           handle_ring_buffer(method_key, path_key)

data/lib/ruby_routes/utility/method_utility.rb

@@ -42,7 +42,7 @@ module RubyRoutes
       # Now uses SmallLru for LRU eviction instead of simple clearing.
       #
       # @return [SmallLru]
-      METHOD_CACHE = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::METHOD_CACHE_MAX_SIZE)
+      METHOD_CACHE = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
 
       # Normalize an HTTP method‑like input to a canonical uppercase `String`.
       #
@@ -69,16 +69,20 @@ module RubyRoutes
 
       private
 
+      def cache_normalized_method(input_string)
+        return input_string if already_upper_ascii?(input_string)
+
+        # Use SmallLru for LRU eviction, freeze key to prevent mutation
+        key = input_string.dup.freeze
+        METHOD_CACHE.get(key) || METHOD_CACHE.set(key, ascii_upcase(input_string.dup).freeze)
+      end
+
       # Normalize a `String` HTTP method.
       #
       # @param method_input [String] The HTTP method input.
       # @return [String] The normalized HTTP method.
       def normalize_string_method(method_input)
-        return method_input if already_upper_ascii?(method_input)
-
-        # Use SmallLru for LRU eviction, freeze key to prevent mutation
-        key = method_input.dup.freeze
-        METHOD_CACHE.get(key) || METHOD_CACHE.set(key, ascii_upcase(method_input.dup).freeze)
+        cache_normalized_method(method_input)
       end
 
       # Normalize a `Symbol` HTTP method.
@@ -98,11 +102,7 @@ module RubyRoutes
       # @return [String] The normalized HTTP method.
       def normalize_other_method(method_input)
         coerced = method_input.to_s
-        return coerced if already_upper_ascii?(coerced)
-
-        # Use SmallLru for LRU eviction, freeze key to prevent mutation
-        key = coerced.dup.freeze
-        METHOD_CACHE.get(key) || METHOD_CACHE.set(key, ascii_upcase(coerced.dup).freeze)
+        cache_normalized_method(coerced)
       end
 
       # Determine if a `String` consists solely of uppercase ASCII (`A–Z`) or non‑letters.

data/lib/ruby_routes/utility/path_utility.rb

@@ -32,10 +32,11 @@ module RubyRoutes
       #   normalize_path('/users')   # => "/users"
       #   normalize_path('/')        # => "/"
       def normalize_path(raw_path)
-        normalized_path = raw_path.to_s
-        normalized_path = "/#{normalized_path}" unless normalized_path.start_with?('/')
-        normalized_path = normalized_path[0..-2] if normalized_path.length > 1 && normalized_path.end_with?('/')
-        normalized_path
+        return '/' if raw_path.nil? || raw_path.empty?
+
+        path = raw_path.start_with?('/') ? raw_path : "/#{raw_path}"
+        path = path.chomp('/') unless path == '/'
+        path
       end
 
       # Normalize HTTP method to uppercase String (fast path).
@@ -56,10 +57,20 @@ module RubyRoutes
       #   split_path('/users/123?x=1') # => ["users", "123"]
       #   split_path('/')              # => []
       def split_path(raw_path)
-        path_without_query = raw_path.to_s.split(/[?#]/, 2).first
-        return [] if path_without_query.nil? || path_without_query.empty?
+        return [] if raw_path == '/' || raw_path.empty?
+
+        # Strip query strings and fragments
+        path = raw_path.split(/[?#]/).first
 
-        path_without_query.split('/').reject(&:empty?)
+        # Optimized trimming: avoid string allocations when possible
+        start_idx = path.start_with?('/') ? 1 : 0
+        end_idx = path.end_with?('/') ? -2 : -1
+
+        if start_idx == 0 && end_idx == -1
+          path.split('/').reject(&:empty?)
+        else
+          path[start_idx..end_idx].split('/').reject(&:empty?)
+        end
       end
 
       # Join path parts into a normalized absolute path.

data/lib/ruby_routes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyRoutes
-  VERSION = '2.5.0'
+  VERSION = '2.6.0'
 end

data/lib/ruby_routes.rb

@@ -2,7 +2,6 @@
 
 require_relative 'ruby_routes/version'
 require_relative 'ruby_routes/constant'
-require_relative 'ruby_routes/string_extensions'
 require_relative 'ruby_routes/route'
 require_relative 'ruby_routes/route_set'
 require_relative 'ruby_routes/url_helpers'
@@ -10,6 +9,9 @@ require_relative 'ruby_routes/router'
 require_relative 'ruby_routes/radix_tree'
 require_relative 'ruby_routes/node'
 require_relative 'ruby_routes/router/builder'
+require_relative 'ruby_routes/strategies/base'
+require_relative 'ruby_routes/strategies/hash_based_strategy'
+require_relative 'ruby_routes/strategies/hybrid_strategy'
 
 # RubyRoutes
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_routes
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Yosef Benny Widyokarsono
@@ -83,9 +83,14 @@ files:
 - lib/ruby_routes/radix_tree.rb
 - lib/ruby_routes/radix_tree/finder.rb
 - lib/ruby_routes/radix_tree/inserter.rb
+- lib/ruby_routes/radix_tree/traversal_strategy.rb
+- lib/ruby_routes/radix_tree/traversal_strategy/base.rb
+- lib/ruby_routes/radix_tree/traversal_strategy/generic_loop.rb
+- lib/ruby_routes/radix_tree/traversal_strategy/unrolled.rb
 - lib/ruby_routes/route.rb
 - lib/ruby_routes/route/check_helpers.rb
 - lib/ruby_routes/route/constraint_validator.rb
+- lib/ruby_routes/route/matcher.rb
 - lib/ruby_routes/route/param_support.rb
 - lib/ruby_routes/route/path_builder.rb
 - lib/ruby_routes/route/path_generation.rb
@@ -108,7 +113,11 @@ files:
 - lib/ruby_routes/segments/dynamic_segment.rb
 - lib/ruby_routes/segments/static_segment.rb
 - lib/ruby_routes/segments/wildcard_segment.rb
-- lib/ruby_routes/string_extensions.rb
+- lib/ruby_routes/strategies.rb
+- lib/ruby_routes/strategies/base.rb
+- lib/ruby_routes/strategies/hash_based_strategy.rb
+- lib/ruby_routes/strategies/hybrid_strategy.rb
+- lib/ruby_routes/strategies/radix_tree_strategy.rb
 - lib/ruby_routes/url_helpers.rb
 - lib/ruby_routes/utility/inflector_utility.rb
 - lib/ruby_routes/utility/key_builder_utility.rb

data/lib/ruby_routes/string_extensions.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-# Minimal String inflection helpers.
-#
-# @note This is a very small, intentionally naive English inflector
-# covering only a few common pluralization patterns used inside the
-# routing DSL (e.g., resources / resource helpers). It is NOT a full
-# replacement for ActiveSupport::Inflector and should not be relied on
-# for general linguistic correctness.
-#
-# @note Supported patterns:
-# - Singularize:
-#   * words ending in "ies" -> "y" (companies -> company)
-#   * words ending in "s"   -> strip trailing "s" (users -> user)
-# - Pluralize:
-#   * words ending in "y"   -> replace with "ies" (company -> companies)
-#   * words ending in sh/ch/x -> append "es" (box -> boxes)
-#   * words ending in "z"   -> append "zes" (quiz -> quizzes) (simplified)
-#   * words ending in "s"   -> unchanged
-#   * default -> append "s"
-#
-# @note Limitations:
-# - Does not handle irregular forms (person/people, child/children, etc.).
-# - Simplified handling of "z" endings (adds "zes" instead of "zzes").
-# - Case‑sensitive (expects lowercase ASCII).
-#
-# @api internal
-class String
-  # Convert a plural form to a simplistic singular.
-  #
-  # @example Singularize a word
-  #   "companies".singularize # => "company"
-  #   "users".singularize     # => "user"
-  #   "box".singularize       # => "box" (unchanged)
-  #
-  # @return [String] Singularized form (may be the same object if no change is needed).
-  def singularize
-    case self
-    when /ies$/
-      sub(/ies$/, 'y')
-    when /s$/
-      sub(/s$/, '')
-    else
-      self
-    end
-  end
-
-  # Convert a singular form to a simplistic plural.
-  #
-  # @example Pluralize a word
-  #   "company".pluralize # => "companies"
-  #   "box".pluralize     # => "boxes"
-  #   "quiz".pluralize    # => "quizzes"
-  #   "user".pluralize    # => "users"
-  #
-  # @return [String] Pluralized form.
-  def pluralize
-    return self if end_with?('s')
-    return sub(/y$/, 'ies') if end_with?('y')
-    return "#{self}es" if match?(/sh$|ch$|x$/)
-    return "#{self}zes" if end_with?('z')
-
-    "#{self}s"
-  end
-end