ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/route_set/cache_helpers.rb

@@ -0,0 +1,76 @@
+# 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
+      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,125 @@
+# 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)
+        @named_routes[route.name] = route if route.named?
+        @radix_tree.add(route.path, route.methods, route)
+        return route if @routes.include?(route) # Prevent duplicate insertion
+
+        @routes << route
+        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)
+        add_to_collection(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] 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 clears
+      # the global request key cache.
+      #
+      # @return [void]
+      def clear!
+        @routes.clear
+        @named_routes.clear
+        @recognition_cache.clear
+        @cache_hits = 0
+        @cache_misses = 0
+        @radix_tree = RadixTree.new
+        RubyRoutes::Utility::KeyBuilderUtility.clear!
+      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,187 @@
+# frozen_string_literal: true
+
+require_relative 'radix_tree'
 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:
+  # - RouteSet instances are not fully thread-safe for modifications.
+  # - Build during boot/initialization, then use read-only per request.
+  # - Global caches (via KeyBuilderUtility) are thread-safe for concurrent reads.
+  # - Per-instance recognition cache is not protected (single-threaded usage assumed).
+  #
+  # @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
-      @radix_tree = RadixTree.new
+    # Replay recorded calls on the router instance.
+    #
+    # This method replays all the recorded route definitions and other
+    # configuration calls on the given router instance.
+    #
+    # @param router [Router] The router instance to replay calls on.
+    # @return [void]
+    def replay_recorded_calls(router)
+      # Placeholder for actual implementation
+      # Iterate over recorded calls and apply them to the router
     end
 
-    def size
-      @routes.size
-    end
+    private
 
-    def empty?
-      @routes.empty?
+    # Set up the radix tree for structural path matching.
+    #
+    # @return [void]
+    def setup_radix_tree
+      @radix_tree = RadixTree.new
     end
 
-    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
-      }
+    # 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)
-      @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
+
+      # Ensure we have a mutable hash for merging defaults / query params.
+      if extracted_params.nil?
+        extracted_params = {}
+      elsif extracted_params.frozen?
+        extracted_params = extracted_params.dup
+      end
 
-    def include?(route)
-      @routes.include?(route)
+      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
 
-    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] ||= []

data/lib/ruby_routes/router/build_helpers.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  class Router
+    # BuildHelpers
+    #
+    # Small, focused utilities used while constructing routes and routers.
+    module BuildHelpers
+      # Build the router from recorded calls.
+      #
+      # This method creates a new `Router` instance, validates the recorded calls,
+      # finalizes the router (making it immutable), and returns the frozen instance.
+      #
+      # @return [Router] The finalized router.
+      def build
+        router = Router.new
+        validate_calls(@recorded_calls)
+        router.finalize!
+        router
+      end
+
+      # Build route options.
+      #
+      # This method creates a copy of the base options and conditionally adds
+      # the `:via` and `:to` keys if they are not already present or need to be overridden.
+      #
+      # @param base_options [Hash] The base options for the route.
+      # @param via_sym [Symbol, nil] The HTTP method (e.g., `:get`, `:post`).
+      # @param to_string [String, nil] The controller#action string (e.g., `"users#index"`).
+      # @return [Hash] The updated route options.
+      def build_route_options(base_options, via_sym = nil, to_string = nil)
+        force_via = !via_sym.nil? && base_options[:via] != via_sym
+        add_to    = !to_string.nil? && !base_options.key?(:to)
+        return base_options unless force_via || add_to
+
+        options_copy = base_options.dup
+        options_copy[:via] = via_sym if force_via
+        options_copy[:to]  = to_string if add_to
+        options_copy
+      end
+
+      # Helper: Build collection routes inside a resource scope.
+      #
+      # This method defines routes for collection-level actions (e.g., `index`, `new`, `create`)
+      # within the scope of a resource.
+      #
+      # @param opts [Hash] The options to apply to the routes.
+      # @param to_index [String] The controller#action string for the `index` action.
+      # @param to_new [String] The controller#action string for the `new` action.
+      # @param to_create [String] The controller#action string for the `create` action.
+      # @return [void]
+      def build_collection_routes(opts, to_index, to_new, to_create)
+        add_route('',     build_route_options(opts, :get,  to_index))
+        add_route('/new', build_route_options(opts, :get,  to_new))
+        add_route('',     build_route_options(opts, :post, to_create))
+      end
+
+      # Helper: Build member routes inside a resource scope.
+      #
+      # This method defines routes for member-level actions (e.g., `show`, `edit`, `update`, `destroy`)
+      # within the scope of a resource.
+      #
+      # @param opts [Hash] The options to apply to the routes.
+      # @param to_show [String] The controller#action string for the `show` action.
+      # @param to_edit [String] The controller#action string for the `edit` action.
+      # @param to_update [String] The controller#action string for the `update` action.
+      # @param to_destroy [String] The controller#action string for the `destroy` action.
+      # @return [void]
+      def build_member_routes(opts, to_show, to_edit, to_update, to_destroy)
+        add_route('/:id',      build_route_options(opts, :get,    to_show))
+        add_route('/:id/edit', build_route_options(opts, :get,    to_edit))
+        add_route('/:id',      opts.merge(via: %i[put patch], to: to_update))
+        add_route('/:id',      build_route_options(opts, :delete, to_destroy))
+      end
+
+      private
+
+      # Validate the recorded calls.
+      #
+      # This method ensures that all recorded calls use valid router methods
+      # as defined in `RubyRoutes::Constant::RECORDED_METHODS`.
+      #
+      # @param recorded_calls [Array<Array(Symbol, Array, Proc|NilClass)>]
+      #   The recorded calls to validate.
+      # @raise [ArgumentError] If any recorded call uses an invalid method.
+      # @return [void]
+      def validate_calls(recorded_calls)
+        allowed_router_methods = RubyRoutes::Constant::RECORDED_METHODS
+        recorded_calls.each do |(router_method, _arguments, _definition_block)|
+          unless router_method.is_a?(Symbol) && allowed_router_methods.include?(router_method)
+            raise ArgumentError, "Invalid router method: #{router_method.inspect}"
+          end
+        end
+      end
+    end
+  end
+end