ruby_routes 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33b60562a702b7d2def6960af7e255d460b17e508367563aefd9ef85856abe52
-  data.tar.gz: be3560f98947dd313afeef38603a9f97bb6a39917d471db9a26b4dcdbb42d2bc
+  metadata.gz: e0df861aa54b895a91e6d525f227a6c470b2d66e89e39407dded8c017f30b995
+  data.tar.gz: 25d99af8abfd7962e6ac6cf154ed07c2315605192b30db78a7707bf792afd1cc
 SHA512:
-  metadata.gz: 87b6d61fda5213a0db9e5fba0ad35a3158341e3df9af8e708c38aee60524c3b1c4d2ca85051a4578c3caa57dcfc5fc01d3c37c833652fcb69bd23b6c35580a2e
-  data.tar.gz: 2378650e65113fc8d29c2062dbfb85127629f18d7f82a4dc00a98f5453b9c933c3fce20cbcc27e6a25b9d07313fec4c03778015ab0a55cf2e55abd4fb251029b
+  metadata.gz: 6b7f2af4f6bcffd3238e69ade25876abc785c03c601a0a91db06eb75fce14684c73f21abaf6bf2aa55b0c7f496ca682a6c5393426e802d325a740658ee9c1b1b
+  data.tar.gz: e11dbd0208c20b72954f1b750c475740c7678f465d2ab441bbae01a2f87d1415b2d5219ef2fdfada2f728c43e0212918bf3cc23be4ca665f9e8acbde900f6eb5

data/README.md

@@ -36,7 +36,7 @@ A high-performance, lightweight routing system for Ruby applications providing a
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'ruby_routes', '~> 2.3.0'
+gem 'ruby_routes', '~> 2.7.0'
 ```
 
 And then execute:
@@ -447,6 +447,29 @@ This gem is available as open source under the terms of the [MIT License](LICENS
 
 This gem was inspired by Rails routing and aims to provide a lightweight alternative for Ruby applications that need flexible routing without the full Rails framework.
 
+## Thread-safe Build (Isolated Builder)
+
+Use the builder to accumulate routes without mutating a live router:
+
+```ruby
+router = RubyRoutes::Router.build do
+  resources :users
+  namespace :admin do
+    resources :posts
+  end
+end
+# router is now finalized (immutable)
+```
+
+If you need manual steps:
+
+```ruby
+builder = RubyRoutes::Router::Builder.new do
+  get '/health', to: 'system#health'
+end
+router = builder.build  # finalized
+```
+
 ## Fluent Method Chaining
 
 For a more concise style, the routing DSL supports method chaining:

data/lib/ruby_routes/cache_setup.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'route/small_lru'
+require_relative 'constant'
+
+module RubyRoutes
+  # CacheSetup: shared module for initializing caches across Route and RouteSet.
+  #
+  # This module provides common cache setup methods to reduce duplication
+  # and ensure consistency in cache initialization.
+  module CacheSetup
+    attr_reader :named_routes, :small_lru, :gen_cache, :query_cache, :validation_cache,
+                :cache_hits, :cache_misses
+
+    # Initialize recognition caches for RouteSet.
+    #
+    # @return [void]
+    def setup_caches
+      @routes                 = []
+      @named_routes           = {}
+      @recognition_cache      = {}
+      @cache_mutex            = Mutex.new
+      @cache_hits             = 0
+      @cache_misses           = 0
+      @recognition_cache_max  = RubyRoutes::Constant::CACHE_SIZE
+      @small_lru              = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
+      @gen_cache              = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
+      @query_cache            = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
+      @validation_cache       = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
+    end
+  end
+end

data/lib/ruby_routes/lru_strategies/hit_strategy.rb

@@ -28,12 +28,7 @@ module RubyRoutes
       # @return [Object] the cached value
       def call(lru, key)
         lru.increment_hits
-        # Internal storage name (@hash) is intentionally accessed reflectively
-        # to keep strategy decoupled from public API surface.
-        store = lru.hash
-        value = store.delete(key)
-        store[key] = value
-        value
+        lru.promote(key)
       end
     end
   end

data/lib/ruby_routes/radix_tree/finder.rb

@@ -24,6 +24,16 @@ module RubyRoutes
       CAPTURED_PARAMS_BUFFER_KEY = :ruby_routes_finder_captured_params_buffer
       STATE_BUFFER_KEY = :ruby_routes_finder_state_buffer
 
+      # Clears a thread-local buffer hash.
+      #
+      # @param buffer_key [Symbol] The thread-local key for the buffer.
+      # @return [Hash] The cleared buffer.
+      def clear_buffer(buffer_key)
+        buffer = Thread.current[buffer_key] ||= {}
+        buffer.clear
+        buffer
+      end
+
       # Evaluate constraint rules for a candidate route.
       #
       # @param route_handler [Object]
@@ -57,10 +67,11 @@ module RubyRoutes
         segments = split_path_cached(path_input)
         return [nil, EMPTY_PARAMS] if segments.empty?
 
-        # Use thread-local, reusable hashes to avoid allocations
-        params = acquire_params_buffer(params_out)
-        state = acquire_state_buffer
-        captured_params = acquire_captured_params_buffer
+        # Clear and acquire thread-local buffers to avoid new hash creation
+        params = clear_buffer(PARAMS_BUFFER_KEY)
+        params.merge!(params_out) if params_out
+        captured_params = clear_buffer(CAPTURED_PARAMS_BUFFER_KEY)
+        state = acquire_state_buffer  # Already clears internally
 
         result = perform_traversal(segments, state, method, params, captured_params)
         return result unless result.nil?
@@ -72,9 +83,12 @@ module RubyRoutes
       #
       # @return [Hash] state hash with :current, :best_node, :best_params, :best_captured, :matched
       def acquire_state_buffer
-        state = Thread.current[STATE_BUFFER_KEY] ||= {}
-        state.clear
+        state = clear_buffer(STATE_BUFFER_KEY)  # Use clear_buffer for consistency
         state[:current] = @root
+        state[:best_node] = nil
+        state[:best_params] = nil
+        state[:best_captured] = nil
+        state[:matched] = false
         state
       end
 
@@ -127,7 +141,7 @@ module RubyRoutes
       # @param captured_params [Hash] captured parameters from traversal
       def record_candidate(state, _method, params, captured_params)
         state[:best_node] = state[:current]
-        state[:best_params] = params
+        state[:best_params] = params.dup
         state[:best_captured] = captured_params.dup
       end
 

data/lib/ruby_routes/radix_tree/traversal_strategy/unrolled.rb

@@ -14,14 +14,23 @@ module RubyRoutes
           # this strategy is only used for these lengths.
           case segments.size
           when 1
-            traverse_segment(0, segments, state, method, params, captured_params)
+            outcome = traverse_segment(0, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
           when 2
-            traverse_segment(0, segments, state, method, params, captured_params)
-            traverse_segment(1, segments, state, method, params, captured_params)
+            outcome = traverse_segment(0, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
+            return nil if outcome == true  # stop
+            outcome = traverse_segment(1, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
           when 3
-            traverse_segment(0, segments, state, method, params, captured_params)
-            traverse_segment(1, segments, state, method, params, captured_params)
-            traverse_segment(2, segments, state, method, params, captured_params)
+            outcome = traverse_segment(0, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
+            return nil if outcome == true  # stop
+            outcome = traverse_segment(1, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
+            return nil if outcome == true  # stop
+            outcome = traverse_segment(2, segments, state, method, params, captured_params)
+            return @finder.finalize_on_fail(state, method, params, captured_params) if outcome == :fail
           end
           nil # Return nil to indicate successful traversal
         end
@@ -32,7 +41,7 @@ module RubyRoutes
         # Returns true if traversal should stop (e.g., due to wildcard), false otherwise.
         def traverse_segment(index, segments, state, method, params, captured_params)
           next_node, stop = @finder.traverse_for_segment(state[:current], segments[index], index, segments, params, captured_params)
-          return false unless next_node
+          return :fail unless next_node
 
           state[:current] = next_node
           state[:matched] = true

data/lib/ruby_routes/route/check_helpers.rb

@@ -52,7 +52,7 @@ module RubyRoutes
       # @raise [RubyRoutes::ConstraintViolation] If the value does not match the required format.
       # @return [void]
       def check_format(constraint, value)
-        return unless (format = constraint[:format]) && !value&.match?(format)
+        return unless (format = constraint[:format]) && value && !value.match?(format)
 
         raise RubyRoutes::ConstraintViolation, 'Value does not match required format'
       end

data/lib/ruby_routes/route/constraint_validator.rb

@@ -3,6 +3,7 @@
 require 'timeout'
 require_relative '../constant'
 require_relative 'warning_helpers'
+require_relative 'check_helpers'
 
 module RubyRoutes
   class Route
@@ -14,6 +15,7 @@ module RubyRoutes
     # for constraint violations.
     module ConstraintValidator
       include RubyRoutes::Route::WarningHelpers
+      include RubyRoutes::Route::CheckHelpers
       # Validate all constraints for the given parameters.
       #
       # This method iterates through all constraints and validates each parameter

data/lib/ruby_routes/route/small_lru.rb

@@ -152,11 +152,16 @@ module RubyRoutes
       end
 
       # Internal helper used by hit strategy to promote key.
-      # @param key [Object]
-      # @return [void]
+      # Moves the key-value pair to the end of the hash (most recently used position).
+      #
+      # @param key [Object] The key to promote
+      # @return [Object, nil] The value associated with the key, or nil if not found
       def promote(key)
+        return nil unless @hash.key?(key)
+
         val = @hash.delete(key)
-        @hash[key] = val if val
+        @hash[key] = val
+        val
       end
     end
   end

data/lib/ruby_routes/route/validation_helpers.rb

@@ -12,16 +12,6 @@ module RubyRoutes
     module ValidationHelpers
       include RubyRoutes::Route::CheckHelpers
 
-      # Initialize validation result cache.
-      #
-      # This method initializes an LRU (Least Recently Used) cache for storing
-      # validation results, with a maximum size of 64 entries.
-      #
-      # @return [void]
-      def initialize_validation_cache
-        @validation_cache = SmallLru.new(64)
-      end
-
       # Validate fundamental route shape.
       #
       # This method ensures that the route has a valid controller, action, and

data/lib/ruby_routes/route.rb

@@ -6,6 +6,8 @@ require 'rack'
 require 'set'
 require_relative 'constant'
 require_relative 'node'
+require_relative 'cache_setup'
+require_relative 'route_set/cache_helpers'
 require_relative 'route/small_lru'
 require_relative 'utility/key_builder_utility'
 require_relative 'utility/method_utility'
@@ -20,7 +22,6 @@ require_relative 'route/query_helpers'
 require_relative 'route/validation_helpers'
 require_relative 'route/segment_compiler'
 require_relative 'route/path_generation'
-require_relative 'route_set/cache_helpers'
 
 module RubyRoutes
   # Route
@@ -63,6 +64,7 @@ module RubyRoutes
     include RubyRoutes::Utility::PathUtility
     include RubyRoutes::Utility::KeyBuilderUtility
     include RubyRoutes::RouteSet::CacheHelpers
+    include RubyRoutes::CacheSetup
 
     attr_reader :path, :methods, :controller, :action, :name, :constraints, :defaults
 
@@ -123,14 +125,6 @@ module RubyRoutes
 
     private
 
-    # Split path into parts.
-    #
-    # @param path [String] The path to split.
-    # @return [Array<String>]
-    def split_path(path)
-      path.split('/').reject(&:empty?)
-    end
-
     # Expose for testing / external callers.
     public :extract_path_params_fast
 
@@ -149,7 +143,7 @@ module RubyRoutes
 
       @is_resource = @path.match?(%r{/:id(?:$|\.)})
 
-      initialize_validation_cache
+      setup_caches
       compile_segments
       compile_required_params
       check_static_path

data/lib/ruby_routes/route_set/cache_helpers.rb

@@ -11,7 +11,7 @@ module RubyRoutes
     # implementing eviction policies for route recognition.
     module CacheHelpers
 
-      attr_reader :named_routes, :small_lru
+      attr_reader :small_lru
       # Recognition cache statistics.
       #
       # @return [Hash] A hash containing:
@@ -31,23 +31,6 @@ module RubyRoutes
 
       private
 
-      # Set up caches and request-key ring.
-      #
-      # Initializes the internal data structures for managing routes, named routes,
-      # recognition cache, and request-key ring buffer.
-      #
-      # @return [void]
-      def setup_caches
-        @routes = []
-        @named_routes = {}
-        @recognition_cache = {}
-        @recognition_cache_max = RubyRoutes::Constant::CACHE_SIZE
-        @small_lru = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
-        @gen_cache = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
-        @query_cache = RubyRoutes::Route::SmallLru.new(RubyRoutes::Constant::CACHE_SIZE)
-        @cache_mutex = Mutex.new
-      end
-
       # Fetch cached recognition entry while updating hit counter.
       #
       # @param lookup_key [String] The cache lookup key.
@@ -73,7 +56,7 @@ module RubyRoutes
         @cache_mutex.synchronize do
           if @recognition_cache.size >= @recognition_cache_max
             # Calculate how many to keep (3/4 of max, rounded down)
-            keep_count = (@recognition_cache_max * 3 / 4).to_i
+            keep_count = @recognition_cache_max / 4
 
             # Get the keys to keep (newest 75%, assuming insertion order)
             keys_to_keep = @recognition_cache.keys.last(keep_count)

data/lib/ruby_routes/route_set/collection_helpers.rb

@@ -74,14 +74,7 @@ module RubyRoutes
       #
       # @return [void]
       def clear_routes_and_caches!
-        @cache_mutex.synchronize do
-          @routes.clear
-          @named_routes.clear
-          @recognition_cache.clear
-          @small_lru.clear_counters!
-          @strategy = @strategy_class.new
-          RubyRoutes::Utility::KeyBuilderUtility.clear!
-        end
+        setup_caches
       end
 
       # Get the number of routes.

data/lib/ruby_routes/route_set.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'cache_setup'
 require_relative 'strategies'
 require_relative 'utility/key_builder_utility'
 require_relative 'utility/method_utility'
@@ -36,6 +37,7 @@ module RubyRoutes
     include RubyRoutes::Route::ParamSupport
     include RubyRoutes::Route::PathGeneration
     include RubyRoutes::RouteSet::CollectionHelpers
+    include RubyRoutes::CacheSetup
 
     # Initialize empty collection and caches.
     #

data/lib/ruby_routes/segments/dynamic_segment.rb

@@ -35,7 +35,7 @@ module RubyRoutes
       def ensure_child(parent_node)
         parent_node.dynamic_child ||= Node.new
         dynamic_child_node = parent_node.dynamic_child
-        dynamic_child_node.param_name = @param_name
+        dynamic_child_node.param_name ||= @param_name
         dynamic_child_node
       end
 

data/lib/ruby_routes/strategies/hash_based_strategy.rb

@@ -16,13 +16,13 @@ module RubyRoutes
 
       def add(route)
         route.methods.each do |method|
-          key = "#{method.upcase}::#{route.path&.downcase}"
+          key = "#{normalize_http_method(method)}::#{route.path}"
           @routes[key] = route
         end
       end
 
       def find(path, http_method)
-        key = "#{http_method.upcase}::#{path&.downcase}"
+        key = "#{normalize_http_method(method)}::#{route.path}"
         route = @routes[key]
         return nil unless route
 

data/lib/ruby_routes/utility/path_utility.rb

@@ -32,9 +32,10 @@ module RubyRoutes
       #   normalize_path('/users')   # => "/users"
       #   normalize_path('/')        # => "/"
       def normalize_path(raw_path)
-        return '/' if raw_path.nil? || raw_path.empty?
+        path_string = raw_path.to_s
+        return '/' if path_string.empty?
 
-        path = raw_path.start_with?('/') ? raw_path : "/#{raw_path}"
+        path = path_string.start_with?('/') ? path_string : "/#{path_string}"
         path = path.chomp('/') unless path == '/'
         path
       end

data/lib/ruby_routes/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_routes
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Yosef Benny Widyokarsono
@@ -76,6 +76,7 @@ files:
 - LICENSE
 - README.md
 - lib/ruby_routes.rb
+- lib/ruby_routes/cache_setup.rb
 - lib/ruby_routes/constant.rb
 - lib/ruby_routes/lru_strategies/hit_strategy.rb
 - lib/ruby_routes/lru_strategies/miss_strategy.rb