ruby_routes 2.2.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,179 +1,166 @@
+# 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
 
     include RubyRoutes::Utility::KeyBuilderUtility
-
+    include RubyRoutes::Utility::MethodUtility
+    include RubyRoutes::RouteSet::CacheHelpers
+    include RubyRoutes::Route::ParamSupport
+    include RubyRoutes::RouteSet::CollectionHelpers
+
+    # Initialize empty collection and caches.
+    #
+    # @return [void]
     def initialize
-      @routes = []
-      @named_routes = {}
-      @recognition_cache = {}
-      @recognition_cache_max = 2048
-      @cache_hits = 0
-      @cache_misses = 0
-      @radix_tree = RadixTree.new
-    end
-
-    def add_to_collection(route)
-      @routes << route
-      @radix_tree.add(route.path, route.methods, route)
-      @named_routes[route.name] = route if route.named?
-    end
-
-    alias_method :add_route, :add_to_collection
-
-    def find_route(method, path)
-      route, _ = @radix_tree.find(path, method)
-      route
-    end
-
-    def find_named_route(name)
-      route = @named_routes[name]
-      raise RouteNotFound.new("No route named '#{name}'") unless route
-      route
-    end
-
-    FAST_METHOD_MAP = {
-      get: 'GET', post: 'POST', put: 'PUT', patch: 'PATCH',
-      delete: 'DELETE', head: 'HEAD', options: 'OPTIONS'
-    }.freeze
-
-    def normalize_method_input(method)
-      case method
-      when Symbol
-        FAST_METHOD_MAP[method] || method.to_s.upcase
-      when String
-        # Fast path: assume already correct; fallback only for common lowercase
-        return method if method.length <= 6 && method == method.upcase
-        FAST_METHOD_MAP[method.downcase.to_sym] || method.upcase
-      else
-        s = method.to_s
-        FAST_METHOD_MAP[s.downcase.to_sym] || s.upcase
-      end
-    end
-    private :normalize_method_input
-
-    def match(method, path)
-      m = normalize_method_input(method)
-      raw = path.to_s
-      cache_key = cache_key_for_request(m, raw)
-
-      # Single cache lookup with proper hit accounting
-      if (hit = @recognition_cache[cache_key])
-        @cache_hits += 1
-        return hit
-      end
-
-      @cache_misses += 1
-
-      path_without_query, _qs = raw.split('?', 2)
-
-      # Use normalized method (m) for trie lookup
-      route, params = @radix_tree.find(path_without_query, m)
-      return nil unless route
-
-      merge_query_params(route, raw, params)
-
-      if route.respond_to?(:defaults) && route.defaults
-        route.defaults.each { |k,v| params[k.to_s] = v unless params.key?(k.to_s) }
+      setup_caches
+      setup_radix_tree
+    end
+
+    # 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)
+
+      if (cached_result = fetch_cached_recognition(lookup_key))
+        return cached_result
       end
 
-      result = {
-        route: route,
-        params: params,
-        controller: route.controller,
-        action: route.action
-      }
-
-      insert_cache_entry(cache_key, result)
+      result = perform_match(normalized_method, raw_path)
+      insert_cache_entry(lookup_key, result) if result
       result
     end
 
+    # 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 = 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
-      @cache_hits = 0
-      @cache_misses = 0
-      # Create a new radix tree since we can't clear it
+    private
+
+    # Set up the radix tree for structural path matching.
+    #
+    # @return [void]
+    def setup_radix_tree
       @radix_tree = RadixTree.new
     end
 
-    def size
-      @routes.size
+    # 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 empty?
-      @routes.empty?
-    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 cache_stats
-      lookups = @cache_hits + @cache_misses
-      {
-        hits: @cache_hits,
-        misses: @cache_misses,
-        hit_rate: lookups.zero? ? 0.0 : (@cache_hits.to_f / lookups * 100.0),
-        size: @recognition_cache.size
-      }
-    end
+      # Ensure we have a mutable hash for merging defaults / query params.
+      extracted_params = extracted_params.dup if extracted_params&.frozen?
 
-    def each(&block)
-      @routes.each(&block)
+      merge_query_params(matched_route, raw_path, extracted_params)
+      merge_defaults(matched_route, extracted_params)
+      build_match_result(matched_route, extracted_params)
     end
 
-    def include?(route)
-      @routes.include?(route)
-    end
+    # 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
 
-    private
-
-    def insert_cache_entry(key, value)
-      # unchanged cache insert (key already frozen & reusable)
-      if @recognition_cache.size >= @recognition_cache_max
-        @recognition_cache.keys.first(@recognition_cache_max / 4).each { |k| @recognition_cache.delete(k) }
-      end
-      @recognition_cache[key] = value
+      matched_route.defaults.each { |key, value| extracted_params[key] = value unless extracted_params.key?(key) }
     end
 
-    # Add the missing method for merging query params
-    def merge_query_params(route, path, params)
-      # Check for query string
-      if path.to_s.include?('?')
-        if route.respond_to?(:parse_query_params)
-          query_params = route.parse_query_params(path)
-          params.merge!(query_params) if query_params
-        elsif route.respond_to?(:query_params)
-          query_params = route.query_params(path)
-          params.merge!(query_params) if query_params
-        end
-      end
+    # 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
 
-    # Add thread-local params pool methods
-    def get_thread_local_params
+    # 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] ||= []
-      if thread_params.empty?
-        {}
-      else
-        thread_params.pop.clear
-      end
+      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)
       params.clear
       thread_pool = Thread.current[:ruby_routes_params_pool] ||= []