ruby_routes 2.1.0 → 2.3.0

data/lib/ruby_routes/route_set/cache_helpers.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class RouteSet
+    # CacheHelpers: extracted cache, request-key, and eviction logic to reduce
+    # the size of the main RouteSet class.
+    #
+    # This module provides methods for managing caches, request keys, and
+    # implementing eviction policies for route recognition.
+    module CacheHelpers
+      # Recognition cache statistics.
+      #
+      # @return [Hash] A hash containing:
+      #   - `:hits` [Integer] The number of cache hits.
+      #   - `:misses` [Integer] The number of cache misses.
+      #   - `:hit_rate` [Float] The cache hit rate as a percentage.
+      #   - `:size` [Integer] The current size of the recognition cache.
+      def cache_stats
+        total_requests = @cache_hits + @cache_misses
+        {
+          hits: @cache_hits,
+          misses: @cache_misses,
+          hit_rate: total_requests.zero? ? 0.0 : (@cache_hits.to_f / total_requests * 100.0),
+          size: @recognition_cache.size
+        }
+      end
+
+      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 = 2048
+        @cache_hits = 0
+        @cache_misses = 0
+        @request_key_pool = {}
+        @request_key_ring = Array.new(RubyRoutes::Constant::REQUEST_KEY_CAPACITY)
+        @entry_count = 0
+        @ring_index = 0
+      end
+
+      # Fetch (or build) a composite request cache key with ring-buffer eviction.
+      #
+      # Ensures consistent use of frozen method/path keys to avoid mixed key space bugs.
+      #
+      # @param http_method [String, Symbol] The HTTP method (e.g., `:get`, `:post`).
+      # @param request_path [String] The request path.
+      # @return [String] The composite request key.
+      def fetch_request_key(http_method, request_path)
+        method_key, path_key = normalize_keys(http_method, request_path)
+        composite_key = build_composite_key(method_key, path_key)
+
+        return composite_key if handle_cache_hit(method_key, path_key, composite_key)
+
+        handle_cache_miss(method_key, path_key, composite_key)
+        composite_key
+      end
+
+      # Normalize keys.
+      #
+      # Converts the HTTP method and request path into frozen strings for consistent
+      # key usage.
+      #
+      # @param http_method [String, Symbol] The HTTP method.
+      # @param request_path [String] The request path.
+      # @return [Array<String>] An array containing the normalized method and path keys.
+      def normalize_keys(http_method, request_path)
+        method_key = http_method.is_a?(String) ? http_method.upcase.freeze : http_method.to_s.upcase.freeze
+        path_key = request_path.is_a?(String) ? request_path.freeze : request_path.to_s.freeze
+        [method_key, path_key]
+      end
+
+      # Build composite key.
+      #
+      # Combines the HTTP method and path into a single composite key.
+      #
+      # @param method_key [String] The normalized HTTP method key.
+      # @param path_key [String] The normalized path key.
+      # @return [String] The composite key.
+      def build_composite_key(method_key, path_key)
+        "#{method_key}:#{path_key}".freeze
+      end
+
+      # Handle cache hit.
+      #
+      # Checks if the composite key already exists in the request key pool.
+      #
+      # @param method_key [String] The normalized HTTP method key.
+      # @param path_key [String] The normalized path key.
+      # @param _composite_key [String] The composite key (unused).
+      # @return [Boolean] `true` if the key exists, `false` otherwise.
+      def handle_cache_hit(method_key, path_key, _composite_key)
+        return true if @request_key_pool[method_key]&.key?(path_key)
+
+        false
+      end
+
+      # Handle cache miss.
+      #
+      # Adds the composite key to the request key pool and manages the ring buffer
+      # for eviction.
+      #
+      # @param method_key [String] The normalized HTTP method key.
+      # @param path_key [String] The normalized path key.
+      # @param composite_key [String] The composite key.
+      # @return [void]
+      def handle_cache_miss(method_key, path_key, composite_key)
+        @request_key_pool[method_key][path_key] = composite_key if @request_key_pool[method_key]
+        @request_key_pool[method_key] = { path_key => composite_key } unless @request_key_pool[method_key]
+
+        if @entry_count < RubyRoutes::Constant::REQUEST_KEY_CAPACITY
+          @request_key_ring[@entry_count] = [method_key, path_key]
+          @entry_count += 1
+        else
+          evict_old_entry(method_key, path_key)
+        end
+      end
+
+      # Evict old entry.
+      #
+      # Removes the oldest entry from the request key pool and updates the ring buffer.
+      #
+      # @param method_key [String] The normalized HTTP method key.
+      # @param path_key [String] The normalized path key.
+      # @return [void]
+      def evict_old_entry(method_key, path_key)
+        evict_method, evict_path = @request_key_ring[@ring_index]
+        if (evict_bucket = @request_key_pool[evict_method]) && evict_bucket.delete(evict_path) && evict_bucket.empty?
+          @request_key_pool.delete(evict_method)
+        end
+        @request_key_ring[@ring_index] = [method_key, path_key]
+        @ring_index += 1
+        @ring_index = 0 if @ring_index == RubyRoutes::Constant::REQUEST_KEY_CAPACITY
+      end
+
+      # Fetch cached recognition entry while updating hit counter.
+      #
+      # @param lookup_key [String] The cache lookup key.
+      # @return [Hash, nil] The cached recognition entry, or `nil` if not found.
+      def fetch_cached_recognition(lookup_key)
+        if (cached_result = @recognition_cache[lookup_key])
+          @cache_hits += 1
+          return cached_result
+        end
+        @cache_misses += 1
+        nil
+      end
+
+      # Cache insertion with simple segment eviction (25% oldest).
+      #
+      # Adds a new entry to the recognition cache, evicting the oldest 25% of entries
+      # if the cache exceeds its maximum size.
+      #
+      # @param cache_key [String] The cache key.
+      # @param entry [Hash] The cache entry.
+      # @return [void]
+      def insert_cache_entry(cache_key, entry)
+        if @recognition_cache.size >= @recognition_cache_max
+          @recognition_cache.keys.first(@recognition_cache_max / 4).each do |evict_key|
+            @recognition_cache.delete(evict_key)
+          end
+        end
+        @recognition_cache[cache_key] = entry
+      end
+    end
+  end
+end

data/lib/ruby_routes/route_set/collection_helpers.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class RouteSet
+    # CollectionHelpers: extracted route collection and enumeration helpers
+    # to keep RouteSet implementation small.
+    #
+    # This module provides methods for managing and querying routes within a
+    # `RouteSet`. It includes functionality for adding, finding, clearing, and
+    # enumerating routes, as well as managing named routes and caches.
+    module CollectionHelpers
+      # Add a route object to internal structures.
+      #
+      # This method adds a route to the internal route collection, updates the
+      # radix tree for fast path/method lookups, and registers the route in the
+      # named routes collection if it has a name.
+      #
+      # @param route [Route] The route to add.
+      # @return [Route] The added route.
+      def add_to_collection(route)
+        @routes << route
+        @radix_tree.add(route.path, route.methods, route)
+        @named_routes[route.name] = route if route.named?
+        route
+      end
+      alias add_route add_to_collection
+
+      # Register a newly created Route (called from RouteUtility#define).
+      #
+      # This method initializes the route collection if it is not already set
+      # and adds the given route to the collection.
+      #
+      # @param route [Route] The route to register.
+      # @return [Route] The registered route.
+      def register(route)
+        (@routes ||= []) << route
+        route
+      end
+
+      # Find any route (no params) for a method/path.
+      #
+      # This method searches the radix tree for a route matching the given HTTP
+      # method and path.
+      #
+      # @param http_method [String, Symbol] The HTTP method (e.g., `:get`, `:post`).
+      # @param path [String] The path to match.
+      # @return [Route, nil] The matching route, or `nil` if no match is found.
+      def find_route(http_method, path)
+        route, _params = @radix_tree.find(path, http_method)
+        route
+      end
+
+      # Retrieve a named route.
+      #
+      # This method retrieves a route by its name from the named routes collection.
+      # If no route is found, it raises a `RouteNotFound` error.
+      #
+      # @param name [Symbol, String] The name of the route.
+      # @return [Route] The named route.
+      # @raise [RouteNotFound] If no route with the given name is found.
+      def find_named_route(name)
+        route = @named_routes[name]
+        raise RouteNotFound, "No route named '#{name}'" unless route
+
+        route
+      end
+
+      # Clear all routes and caches.
+      #
+      # This method clears the internal route collection, named routes, recognition
+      # cache, and radix tree. It also resets cache hit/miss counters and the
+      # request key pool.
+      #
+      # @return [void]
+      def clear!
+        @routes.clear
+        @named_routes.clear
+        @recognition_cache.clear
+        @cache_hits = 0
+        @cache_misses = 0
+        @radix_tree = RadixTree.new
+        @request_key_pool.clear
+        @request_key_ring.fill(nil)
+        @entry_count = 0
+        @ring_index = 0
+      end
+
+      # Get the number of routes.
+      #
+      # @return [Integer] The number of routes in the collection.
+      def size
+        @routes.size
+      end
+
+      # Check if the route collection is empty.
+      #
+      # @return [Boolean] `true` if the collection is empty, `false` otherwise.
+      def empty?
+        @routes.empty?
+      end
+
+      # Enumerate routes.
+      #
+      # This method yields each route in the collection to the given block. If no
+      # block is provided, it returns an enumerator.
+      #
+      # @yield [route] Yields each route in the collection.
+      # @return [Enumerator, self] An enumerator if no block is given, or `self`.
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @routes.each(&block)
+        self
+      end
+
+      # Test membership.
+      #
+      # This method checks if the given route is included in the route collection.
+      #
+      # @param route [Route] The route to check.
+      # @return [Boolean] `true` if the route is in the collection, `false` otherwise.
+      def include?(route)
+        @routes.include?(route)
+      end
+    end
+  end
+end

data/lib/ruby_routes/route_set.rb

@@ -1,192 +1,170 @@
+# frozen_string_literal: true
+
+require_relative 'utility/key_builder_utility'
+require_relative 'utility/method_utility'
+require_relative 'route_set/cache_helpers'
+require_relative 'route_set/collection_helpers'
+require_relative 'route/param_support'
+
 module RubyRoutes
+  # RouteSet
+  #
+  # Collection + lookup facade for Route instances.
+  #
+  # Responsibilities:
+  # - Hold all defined routes (ordered).
+  # - Index named routes.
+  # - Provide fast recognition (method + path → route, params) with
+  #   a small in‑memory recognition cache.
+  # - Delegate structural path matching to an internal RadixTree.
+  #
+  # Thread safety: not thread‑safe; build during boot, read per request.
+  #
+  # @api public (primary integration surface)
   class RouteSet
     attr_reader :routes
 
-    def initialize
-      @tree = RubyRoutes::RadixTree.new
-      @named_routes = {}
-      @routes = []
-      # Optimized recognition cache with better data structures
-      @recognition_cache = {}
-      @cache_hits = 0
-      @cache_misses = 0
-      @recognition_cache_max = 8192  # larger for better hit rates
-    end
-
-    def add_route(route)
-      @routes << route
-      @tree.add(route.path, route.methods, route)
-      @named_routes[route.name] = route if route.named?
-      # Clear recognition cache when routes change
-      @recognition_cache.clear if @recognition_cache.size > 100
-      route
-    end
+    include RubyRoutes::Utility::KeyBuilderUtility
+    include RubyRoutes::Utility::MethodUtility
+    include RubyRoutes::RouteSet::CacheHelpers
+    include RubyRoutes::Route::ParamSupport
+    include RubyRoutes::RouteSet::CollectionHelpers
 
-    def find_route(request_method, request_path)
-      # Optimized: avoid repeated string allocation
-      method_up = request_method.to_s.upcase
-      handler, _params = @tree.find(request_path, method_up)
-      handler
-    end
-
-    def find_named_route(name)
-      route = @named_routes[name]
-      return route if route
-      raise RouteNotFound, "No route named '#{name}'"
+    # Initialize empty collection and caches.
+    #
+    # @return [void]
+    def initialize
+      setup_caches
+      setup_radix_tree
     end
 
-    def match(request_method, request_path)
-      # Fast path: normalize method once
-      method_up = method_lookup(request_method)
+    # Recognize a request (method + path) returning route + params.
+    #
+    # @param http_method [String, Symbol] The HTTP method (e.g., "GET").
+    # @param path [String] The request path.
+    # @return [Hash, nil] A hash containing the matched route and parameters, or `nil` if no match is found.
+    def match(http_method, path)
+      normalized_method = normalize_method_for_match(http_method)
+      raw_path = path.to_s
+      lookup_key = cache_key_for_request(normalized_method, raw_path)
 
-      # Optimized cache key: avoid string interpolation when possible
-      cache_key = build_cache_key(method_up, request_path)
-
-      # Cache hit: return immediately (cached result includes full structure)
-      if (cached_result = @recognition_cache[cache_key])
-        @cache_hits += 1
+      if (cached_result = fetch_cached_recognition(lookup_key))
         return cached_result
       end
 
-      @cache_misses += 1
-
-      # Use thread-local params to avoid allocations
-      params = get_thread_local_params
-      handler, _ = @tree.find(request_path, method_up, params)
-      return nil unless handler
-
-      route = handler
-
-      # Fast path: merge defaults only if they exist
-      merge_defaults(route, params) if route.defaults && !route.defaults.empty?
-
-      # Fast path: parse query params only if needed
-      if request_path.include?('?')
-        merge_query_params(route, request_path, params)
-      end
-
-      # Create return hash and cache the complete result
-      result_params = params.dup
-      result = {
-        route: route,
-        params: result_params,
-        controller: route.controller,
-        action: route.action
-      }.freeze
-
-      insert_cache_entry(cache_key, result)
+      result = perform_match(normalized_method, raw_path)
+      insert_cache_entry(lookup_key, result) if result
       result
     end
 
-    def recognize_path(path, method = :get)
+    # Convenience alias for Rack‑style recognizer.
+    #
+    # @param path [String] The request path.
+    # @param method [String, Symbol] The HTTP method (default: "GET").
+    # @return [Hash, nil] A hash containing the matched route and parameters, or `nil` if no match is found.
+    def recognize_path(path, method = 'GET')
       match(method, path)
     end
 
+    # Generate path via named route.
+    #
+    # @param name [Symbol, String] The name of the route.
+    # @param params [Hash] The parameters for path generation.
+    # @return [String] The generated path.
     def generate_path(name, params = {})
-      route = @named_routes[name]
-      if route
-        route.generate_path(params)
-      else
-        raise RouteNotFound, "No route named '#{name}'"
-      end
+      route = find_named_route(name)
+      route.generate_path(params)
     end
 
+    # Generate path from a direct route reference.
+    #
+    # @param route [Route] The route instance.
+    # @param params [Hash] The parameters for path generation.
+    # @return [String] The generated path.
     def generate_path_from_route(route, params = {})
       route.generate_path(params)
     end
 
-    def clear!
-      @routes.clear
-      @named_routes.clear
-      @recognition_cache.clear
-      @tree = RadixTree.new
-      @cache_hits = @cache_misses = 0
-    end
+    private
 
-    def size
-      @routes.size
+    # Set up the radix tree for structural path matching.
+    #
+    # @return [void]
+    def setup_radix_tree
+      @radix_tree = RadixTree.new
     end
-    alias_method :length, :size
 
-    def empty?
-      @routes.empty?
+    # Normalize the HTTP method for matching.
+    #
+    # @param http_method [String, Symbol] The HTTP method.
+    # @return [String] The normalized HTTP method.
+    def normalize_method_for_match(http_method)
+      if http_method.is_a?(String) && normalize_http_method(http_method).equal?(http_method)
+        http_method
+      else
+        normalize_http_method(http_method)
+      end
     end
 
-    def each(&block)
-      return enum_for(:each) unless block_given?
-      @routes.each(&block)
-    end
+    # Perform the route matching process.
+    #
+    # @param normalized_method [String] The normalized HTTP method.
+    # @param raw_path [String] The raw request path.
+    # @return [Hash, nil] A hash containing the matched route and parameters, or `nil` if no match is found.
+    def perform_match(normalized_method, raw_path)
+      path_without_query, _query = raw_path.split('?', 2)
+      matched_route, extracted_params = @radix_tree.find(path_without_query, normalized_method)
+      return nil unless matched_route
 
-    def include?(route)
-      @routes.include?(route)
-    end
+      # Ensure we have a mutable hash for merging defaults / query params.
+      extracted_params = extracted_params.dup if extracted_params&.frozen?
 
-    # Performance monitoring
-    def cache_stats
-      total = @cache_hits + @cache_misses
-      hit_rate = total > 0 ? (@cache_hits.to_f / total * 100).round(2) : 0
-      {
-        hits: @cache_hits,
-        misses: @cache_misses,
-        hit_rate: "#{hit_rate}%",
-        size: @recognition_cache.size
-      }
+      merge_query_params(matched_route, raw_path, extracted_params)
+      merge_defaults(matched_route, extracted_params)
+      build_match_result(matched_route, extracted_params)
     end
 
-    private
+    # Merge default parameters into the extracted parameters.
+    #
+    # @param matched_route [Route] The matched route.
+    # @param extracted_params [Hash] The extracted parameters.
+    # @return [void]
+    def merge_defaults(matched_route, extracted_params)
+      return unless matched_route.respond_to?(:defaults) && matched_route.defaults
 
-    # Method lookup table to avoid repeated upcasing with interned strings
-    def method_lookup(method)
-      @method_cache ||= Hash.new { |h, k| h[k] = k.to_s.upcase.freeze }
-      @method_cache[method]
+      matched_route.defaults.each { |key, value| extracted_params[key] = value unless extracted_params.key?(key) }
     end
 
-    # Optimized cache key building - avoid string interpolation
-    def build_cache_key(method, path)
-      # String interpolation creates a new string directly without intermediate allocations
-      "#{method}:#{path}"
+    # Build the match result hash.
+    #
+    # @param matched_route [Route] The matched route.
+    # @param extracted_params [Hash] The extracted parameters.
+    # @return [Hash] A hash containing the matched route, parameters, controller, and action.
+    def build_match_result(matched_route, extracted_params)
+      {
+        route: matched_route,
+        params: extracted_params,
+        controller: matched_route.controller,
+        action: matched_route.action
+      }
     end
 
-    # Get thread-local params hash, reusing when possible
-    def get_thread_local_params
-      # Use single thread-local hash that gets cleared, avoiding pool management overhead
-      hash = Thread.current[:ruby_routes_params_hash] ||= {}
-      hash.clear
-      hash
+    # Obtain a pooled hash for temporary parameters.
+    #
+    # @return [Hash] A thread-local hash for temporary parameter storage.
+    def thread_local_params
+      thread_params = Thread.current[:ruby_routes_params_pool] ||= []
+      thread_params.empty? ? {} : thread_params.pop.clear
     end
 
+    # Return a parameters hash to the thread-local pool.
+    #
+    # @param params [Hash] The parameters hash to return.
+    # @return [void]
     def return_params_to_pool(params)
-      # No-op since we're using a single reusable hash per thread
-    end
-
-    # Fast defaults merging
-    def merge_defaults(route, params)
-      route.defaults.each do |key, value|
-        params[key] = value unless params.key?(key)
-      end
-    end
-
-    # Fast query params merging
-    def merge_query_params(route, request_path, params)
-      if route.respond_to?(:parse_query_params)
-        qp = route.parse_query_params(request_path)
-        params.merge!(qp) unless qp.empty?
-      elsif route.respond_to?(:query_params)
-        qp = route.query_params(request_path)
-        params.merge!(qp) unless qp.empty?
-      end
-    end
-
-    # Efficient cache insertion with LRU eviction
-    def insert_cache_entry(cache_key, cache_entry)
-      @recognition_cache[cache_key] = cache_entry
-
-      # Simple eviction: clear cache when it gets too large
-      if @recognition_cache.size > @recognition_cache_max
-        # Keep most recently used half
-        keys_to_delete = @recognition_cache.keys[0...(@recognition_cache_max / 2)]
-        keys_to_delete.each { |k| @recognition_cache.delete(k) }
-      end
+      params.clear
+      thread_pool = Thread.current[:ruby_routes_params_pool] ||= []
+      thread_pool << params if thread_pool.size < 10 # Limit pool size
     end
   end
 end