ruby_routes 2.1.0 → 2.3.0

data/lib/ruby_routes/route/param_support.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative 'path_generation'
+require_relative 'warning_helpers'
+
+module RubyRoutes
+  class Route
+    # ParamSupport: helpers for parameter merging and cache key generation.
+    #
+    # This module provides methods for efficiently merging parameters, generating
+    # cache keys, and extracting parameters from request paths. It uses thread-local
+    # hashes for performance and includes a 2-slot LRU cache for param key generation.
+    #
+    # Thread-safety: Thread-local storage is used to avoid allocation and cross-thread mutation.
+    #
+    # @module RubyRoutes::Route::ParamSupport
+    module ParamSupport
+      include RubyRoutes::Route::WarningHelpers
+
+      private
+
+      # Merge incoming params with route defaults.
+      #
+      # This method merges user-provided parameters with route defaults and returns
+      # a thread-local hash for performance.
+      #
+      # @param params [Hash] The user-provided parameters.
+      # @return [Hash] The merged parameters.
+      def build_merged_params(params)
+        return @defaults if params.nil? || params.empty?
+
+        merged_hash = acquire_merge_hash
+        merge_defaults_into(merged_hash)
+        merge_user_params_into(merged_hash, params)
+        merged_hash
+      end
+
+      # Acquire a thread-local hash for merging.
+      #
+      # @return [Hash] A cleared thread-local hash for merging.
+      def acquire_merge_hash
+        merged_hash = Thread.current[:ruby_routes_merge_hash] ||= {}
+        merged_hash.clear
+        merged_hash
+      end
+
+      # Merge defaults into the hash.
+      #
+      # @param merged_hash [Hash] The hash to merge defaults into.
+      # @return [void]
+      def merge_defaults_into(merged_hash)
+        @defaults.each { |key, value| merged_hash[key] = value } unless @defaults.empty?
+      end
+
+      # Merge user params into the hash.
+      #
+      # This method converts keys to strings and skips nil values.
+      #
+      # @param merged_hash [Hash] The hash to merge user parameters into.
+      # @param params [Hash] The user-provided parameters.
+      # @return [void]
+      def merge_user_params_into(merged_hash, params)
+        params.each do |key, value|
+          next if value.nil?
+
+          merged_hash[key.is_a?(String) ? key : key.to_s] = value
+        end
+      end
+
+      # Build a frozen cache key for the merged params and update the 2-slot cache.
+      #
+      # @param merged_params [Hash] The merged parameters.
+      # @return [String] The frozen cache key.
+      def build_param_cache_key(merged_params)
+        param_cache_key = cache_key_for_params(@required_params, merged_params)
+        cache_key_hash = param_cache_key.hash
+
+        if (cache_slot = @param_key_slots[0])[0] == cache_key_hash && cache_slot[1] == param_cache_key
+          return cache_slot[1]
+        elsif (cache_slot = @param_key_slots[1])[0] == cache_key_hash && cache_slot[1] == param_cache_key
+          return cache_slot[1]
+        end
+
+        store_param_key_slot(cache_key_hash, param_cache_key)
+      end
+
+      # Store the param cache key in the 2-slot LRU.
+      #
+      # @param cache_key_hash [Integer] The hash of the cache key.
+      # @param param_cache_key [String] The cache key to store.
+      # @return [String] The stored cache key.
+      def store_param_key_slot(cache_key_hash, param_cache_key)
+        if @param_key_slots[0][0].nil?
+          @param_key_slots[0] = [cache_key_hash, param_cache_key]
+        elsif @param_key_slots[1][0].nil?
+          @param_key_slots[1] = [cache_key_hash, param_cache_key]
+        else
+          @param_key_slots[0] = @param_key_slots[1]
+          @param_key_slots[1] = [cache_key_hash, param_cache_key]
+        end
+        param_cache_key
+      end
+
+      # Extract parameters from a request path (and optionally pre-parsed query).
+      #
+      # @param request_path [String] The request path.
+      # @param parsed_qp [Hash, nil] Pre-parsed query parameters to merge (optional).
+      # @return [Hash] The extracted parameters, with defaults merged in.
+      def extract_params(request_path, parsed_qp = nil)
+        extracted_path_params = extract_path_params_fast(request_path)
+        return RubyRoutes::Constant::EMPTY_HASH unless extracted_path_params
+
+        build_params_hash(extracted_path_params, request_path, parsed_qp)
+      end
+
+      # Build full params hash (path + query + defaults + constraints).
+      #
+      # @param path_params [Hash] The extracted path parameters.
+      # @param request_path [String] The request path.
+      # @param parsed_qp [Hash, nil] Pre-parsed query parameters.
+      # @return [Hash] The full parameters hash.
+      def build_params_hash(path_params, request_path, parsed_qp)
+        params_hash = get_thread_local_hash
+        params_hash.update(path_params)
+
+        merge_query_params_into_hash(params_hash, request_path, parsed_qp)
+
+        merge_defaults_fast(params_hash) unless @defaults.empty?
+        validate_constraints_fast!(params_hash) unless @constraints.empty?
+        params_hash
+      end
+
+      # Merge query parameters (if any) from full path into param hash.
+      #
+      # @param route_obj [Route]
+      # @param full_path [String]
+      # @param param_hash [Hash]
+      # @return [void]
+      def merge_query_params(route_obj, full_path, param_hash)
+        return unless full_path.to_s.include?('?')
+
+        if route_obj.respond_to?(:parse_query_params)
+          qp = route_obj.parse_query_params(full_path)
+          param_hash.merge!(qp) if qp
+        elsif route_obj.respond_to?(:query_params)
+          qp = route_obj.query_params(full_path)
+          param_hash.merge!(qp) if qp
+        end
+      end
+
+      # Acquire thread-local hash.
+      #
+      # @return [Hash]
+      def acquire_thread_local_hash
+        pool = Thread.current[:ruby_routes_hash_pool] ||= []
+        return {} if pool.empty?
+
+        hash = pool.pop
+        hash.clear
+        hash
+      end
+
+      alias get_thread_local_hash acquire_thread_local_hash # backward compatibility if referenced elsewhere
+
+      # Merge query params into the hash.
+      #
+      # @param params_hash [Hash] The hash to merge query parameters into.
+      # @param request_path [String] The request path.
+      # @param parsed_qp [Hash, nil] Pre-parsed query parameters.
+      # @return [void]
+      def merge_query_params_into_hash(params_hash, request_path, parsed_qp)
+        if parsed_qp
+          params_hash.merge!(parsed_qp)
+        elsif request_path.include?('?')
+          query_params = query_params_fast(request_path)
+          params_hash.merge!(query_params) unless query_params.empty?
+        end
+      end
+
+      # Merge defaults where absent.
+      #
+      # @param result [Hash] The hash to merge defaults into.
+      # @return [void]
+      def merge_defaults_fast(result)
+        @defaults.each { |key, value| result[key] = value unless result.key?(key) }
+      end
+
+      # Retrieve query params from route object via supported method.
+      #
+      # @param route_obj [Route] The route object.
+      # @param full_path [String] The full path containing the query string.
+      # @return [Hash, nil] The query parameters, or `nil` if none are found.
+      def retrieve_query_params(route_obj, full_path)
+        if route_obj.respond_to?(:parse_query_params)
+          route_obj.parse_query_params(full_path)
+        elsif route_obj.respond_to?(:query_params)
+          route_obj.query_params(full_path)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/path_builder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Route
+    # PathBuilder: generation + segment encoding
+    #
+    # @module RubyRoutes::Route::PathBuilder
+    module PathBuilder
+      private
+
+      # Generate the path string from merged parameters.
+      #
+      # @param merged [Hash] the merged parameters
+      # @return [String] the generated path
+      def generate_path_string(merged)
+        return RubyRoutes::Constant::ROOT_PATH if @compiled_segments.empty?
+
+        buffer = String.new(capacity: estimate_length)
+        buffer << '/'
+        last_index = @compiled_segments.length - 1
+        @compiled_segments.each_with_index do |segment, index|
+          append_segment(buffer, segment, merged, index, last_index)
+        end
+        buffer
+      end
+
+      # Append a segment to the buffer.
+      #
+      # @param buffer [String] the buffer to append to
+      # @param segment [Hash] the segment to append
+      # @param merged [Hash] the merged parameters
+      # @param index [Integer] the current index
+      # @param last_index [Integer] the last index
+      def append_segment(buffer, segment, merged, index, last_index)
+        case segment[:type]
+        when :static
+          buffer << segment[:value]
+        when :param
+          buffer << encode_segment_fast(merged.fetch(segment[:name]).to_s)
+        when :splat
+          buffer << format_splat_value(merged.fetch(segment[:name], ''))
+        end
+        buffer << '/' unless index == last_index
+      end
+
+      # Estimate the length of the path.
+      #
+      # @return [Integer] the estimated length
+      def estimate_length
+        # Rough heuristic (static sizes + average dynamic)
+        base = 1
+        @compiled_segments.each do |segment|
+          base += case segment[:type]
+                  when :static then segment[:value].length + 1
+                  else 20
+                  end
+        end
+        base
+      end
+
+      # Format a splat value.
+      #
+      # @param value [Object] the value to format
+      # @return [String] the formatted value
+      def format_splat_value(value)
+        case value
+        when Array  then value.map { |part| encode_segment_fast(part.to_s) }.join('/')
+        when String then value.split('/').map { |part| encode_segment_fast(part) }.join('/')
+        else encode_segment_fast(value.to_s)
+        end
+      end
+
+      # Encode a segment fast.
+      #
+      # @param string [String] the string to encode
+      # @return [String] the encoded string
+      def encode_segment_fast(string)
+        return string if RubyRoutes::Constant::UNRESERVED_RE.match?(string)
+
+        @encoding_cache ||= {}
+        # Use gsub instead of tr for proper replacement of + with %20
+        @encoding_cache[string] ||= URI.encode_www_form_component(string).gsub('+', '%20')
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/path_generation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'warning_helpers'
+
+module RubyRoutes
+  class Route
+    # PathGeneration:
+    # Small focused helpers related to building generated paths and emitting
+    # route-related warnings (kept separate to reduce parent module size).
+    module PathGeneration
+      include RubyRoutes::Route::WarningHelpers
+
+      private
+
+      # Generate a path string from supplied params.
+      #
+      # Rules:
+      # - Required params must be present and non‑nil (unless defaulted).
+      # - Caches the result keyed on ordered required param values.
+      #
+      # @param params [Hash] The parameters for path generation (String/Symbol keys).
+      # @return [String] The generated path string.
+      # @raise [RouteNotFound] If required params are missing or nil.
+      def generate_path(params = {})
+        return @static_path if static_short_circuit?(params)
+        return @static_path || RubyRoutes::Constant::ROOT_PATH if trivial_route?
+
+        validate_required_once(params)
+        merged_params = build_merged_params(params)
+
+        build_or_fetch_generated_path(merged_params)
+      end
+
+      # Build or fetch a generated path from the cache.
+      #
+      # This method generates a path string from the merged parameters or fetches
+      # it from the cache if it already exists.
+      #
+      # @param merged_params [Hash] The merged parameters for path generation.
+      # @return [String] The generated or cached path string.
+      def build_or_fetch_generated_path(merged_params)
+        generation_cache_key = build_generation_cache_key(merged_params)
+        if (cached_path = @gen_cache.get(generation_cache_key))
+          return cached_path
+        end
+
+        generated_path = generate_path_string(merged_params)
+        @gen_cache.set(generation_cache_key, generated_path)
+        generated_path
+      end
+
+      # Build a generation cache key for merged params.
+      #
+      # This method creates a cache key based on the required parameters and
+      # their values in the merged parameters.
+      #
+      # @param merged_params [Hash] The merged parameters for path generation.
+      # @return [String] The cache key for the generation cache.
+      def build_generation_cache_key(merged_params)
+        @required_params.empty? ? RubyRoutes::Constant::EMPTY_STRING : build_param_cache_key(merged_params)
+      end
+
+      # Emit deprecation warning for `Proc` constraints once per parameter.
+      #
+      # This method ensures that a deprecation warning for a `Proc` constraint
+      # is only emitted once per parameter. It tracks parameters for which
+      # warnings have already been shown.
+      #
+      # @param param [String, Symbol] The parameter name for which the warning
+      #   is being emitted.
+      # @return [void]
+      def warn_proc_constraint_deprecation(param)
+        return if @proc_warnings_shown&.include?(param)
+
+        @proc_warnings_shown ||= Set.new
+        @proc_warnings_shown << param
+        warn_proc_warning(param)
+      end
+
+      # Determine if the route can short-circuit to a static path.
+      #
+      # This method checks if the route is static and the provided parameters
+      # are empty or nil, allowing the static path to be returned directly.
+      #
+      # @param params [Hash] The parameters for path generation.
+      # @return [Boolean] `true` if the route can short-circuit, `false` otherwise.
+      def static_short_circuit?(params)
+        @static_path && (params.nil? || params.empty?)
+      end
+
+      # Determine if the route is trivial.
+      #
+      # A route is considered trivial if it has no dynamic segments, no required
+      # parameters, and no constraints, meaning it can resolve to a static path.
+      #
+      # @return [Boolean] `true` if the route is trivial, `false` otherwise.
+      def trivial_route?
+        @compiled_segments.empty? && @required_params.empty? && @constraints.empty?
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/query_helpers.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'rack'
+
+module RubyRoutes
+  class Route
+    # QueryHelpers: encapsulate query parsing/caching for Route instances.
+    #
+    # This module provides methods for parsing query parameters from a URL path
+    # and caching the results for improved performance. It includes a wrapper
+    # for cached parsing and a low-level implementation with an LRU cache.
+    #
+    # Provides:
+    # - `parse_query_params(path)` -> Hash (public): Cached parsing wrapper.
+    # - `query_params_fast(path)` -> Hash (public): Low-level parsing with LRU caching.
+    module QueryHelpers
+      # Parse query params (wrapper for internal caching).
+      #
+      # This method parses the query parameters from the given path and caches
+      # the result for future lookups. It is a wrapper around the low-level
+      # `query_params_fast` method.
+      #
+      # @param path [String] The URL path containing the query string.
+      # @return [Hash] A hash of parsed query parameters.
+      def parse_query_params(path)
+        query_params_fast(path)
+      end
+      alias query_params parse_query_params
+
+      # Query param parsing with simple LRU caching.
+      #
+      # This method parses the query parameters from the given path and caches
+      # the result using a Least Recently Used (LRU) cache. If the query string
+      # is already cached, the cached result is returned.
+      #
+      # @param path [String] The URL path containing the query string.
+      # @return [Hash] A hash of parsed query parameters, or an empty hash if
+      #   the path does not contain a valid query string.
+      def query_params_fast(path)
+        query_index = path.index('?')
+        return RubyRoutes::Constant::EMPTY_HASH unless query_index
+
+        query_part = path[(query_index + 1)..]
+        return RubyRoutes::Constant::EMPTY_HASH if query_part.empty? || query_part.match?(/^\?+$/)
+
+        if (cached_result = @query_cache.get(query_part))
+          return cached_result
+        end
+
+        parsed_result = Rack::Utils.parse_query(query_part)
+        @query_cache.set(query_part, parsed_result)
+        parsed_result
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/segment_compiler.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Route
+    # SegmentCompiler: path analysis + extraction
+    #
+    # This module provides methods for analyzing and extracting segments from
+    # a route path. It includes utilities for compiling path segments, required
+    # parameters, and static paths, as well as extracting parameters from a
+    # request path.
+    #
+    # @module RubyRoutes::Route::SegmentCompiler
+    module SegmentCompiler
+      private
+
+      # Compile the segments from the path.
+      #
+      # This method splits the path into segments, analyzes each segment, and
+      # compiles metadata for static and dynamic segments.
+      #
+      # @return [void]
+      def compile_segments
+        @compiled_segments =
+          if @path == RubyRoutes::Constant::ROOT_PATH
+            RubyRoutes::Constant::EMPTY_ARRAY
+          else
+            @path.split('/').reject(&:empty?)
+                 .map { |segment| RubyRoutes::Constant.segment_descriptor(segment) }
+                 .freeze
+          end
+      end
+
+      # Compile the required parameters.
+      #
+      # This method identifies dynamic parameters in the path and determines
+      # which parameters are required based on the defaults provided.
+      #
+      # @return [void]
+      def compile_required_params
+        dynamic_param_names   = @compiled_segments.filter_map { |segment| segment[:name] if segment[:type] != :static }
+        @param_names          = dynamic_param_names.freeze
+        @required_params      = if @defaults.empty?
+                                  dynamic_param_names.freeze
+                                else
+                                  dynamic_param_names.reject do |name|
+                                    @defaults.key?(name) || @defaults.key?(name.to_sym)
+                                  end.freeze
+                                end
+        @required_params_set  = @required_params.to_set.freeze
+      end
+
+      # Check if the path is static.
+      #
+      # This method determines if the path contains only static segments. If so,
+      # it generates the static path.
+      #
+      # @return [void]
+      def check_static_path
+        return unless @compiled_segments.all? { |segment| segment[:type] == :static }
+
+        @static_path = generate_static_path
+      end
+
+      # Generate the static path.
+      #
+      # This method constructs the static path from the compiled segments.
+      #
+      # @return [String] The generated static path.
+      def generate_static_path
+        return RubyRoutes::Constant::ROOT_PATH if @compiled_segments.empty?
+
+        "/#{@compiled_segments.map { |segment| segment[:value] }.join('/')}"
+      end
+
+      # Extract path parameters fast.
+      #
+      # This method extracts parameters from a request path based on the compiled
+      # segments. It performs validation and handles dynamic, static, and splat
+      # segments.
+      #
+      # @param request_path [String] The request path.
+      # @return [Hash, nil] The extracted parameters, or `nil` if extraction fails.
+      def extract_path_params_fast(request_path)
+        return RubyRoutes::Constant::EMPTY_HASH if root_path_and_empty_segments?(request_path)
+
+        return nil if @compiled_segments.empty?
+
+        path_parts = split_path(request_path)
+        return nil unless valid_parts_count?(path_parts)
+
+        extract_params_from_parts(path_parts)
+      end
+
+      # Check if it's a root path with empty segments.
+      #
+      # This method checks if the request path is the root path and the compiled
+      # segments are empty.
+      #
+      # @param request_path [String] The request path.
+      # @return [Boolean] `true` if the path is the root path with empty segments, `false` otherwise.
+      def root_path_and_empty_segments?(request_path)
+        @compiled_segments.empty? && request_path == RubyRoutes::Constant::ROOT_PATH
+      end
+
+      # Validate the parts count.
+      #
+      # This method checks if the number of parts in the request path matches
+      # the expected number of segments, accounting for splat segments.
+      #
+      # @param path_parts [Array<String>] The path parts.
+      # @return [Boolean] `true` if the parts count is valid, `false` otherwise.
+      def valid_parts_count?(path_parts)
+        has_splat = @compiled_segments.any? { |segment| segment[:type] == :splat }
+        (!has_splat && path_parts.size == @compiled_segments.size) ||
+          (has_splat && path_parts.size >= (@compiled_segments.size - 1))
+      end
+
+      # Extract parameters from parts.
+      #
+      # This method processes each segment and extracts parameters from the
+      # corresponding parts of the request path.
+      #
+      # @param path_parts [Array<String>] The path parts.
+      # @return [Hash, nil] The extracted parameters, or `nil` if extraction fails.
+      def extract_params_from_parts(path_parts)
+        params_hash = {}
+        @compiled_segments.each_with_index do |segment, index|
+          result = process_segment(segment, index, path_parts, params_hash)
+          return nil if result == false
+          break if result == :break
+        end
+        params_hash
+      end
+
+      # Process a segment.
+      #
+      # This method processes a single segment, extracting parameters or
+      # validating static segments.
+      #
+      # @param segment [Hash] The segment metadata.
+      # @param index [Integer] The index of the segment.
+      # @param path_parts [Array<String>] The path parts.
+      # @param params_hash [Hash] The parameters hash.
+      # @return [Boolean, Symbol] `true` if processed successfully,
+      # `false` if validation fails, `:break` for splat segments.
+      def process_segment(segment, index, path_parts, params_hash)
+        case segment[:type]
+        when :static
+          segment[:value] == path_parts[index]
+        when :param
+          params_hash[segment[:name]] = path_parts[index]
+          true
+        when :splat
+          params_hash[segment[:name]] = path_parts[index..].join('/')
+          :break
+        end
+      end
+
+      # Expose for testing / external callers that need fast path extraction.
+      public :extract_path_params_fast
+    end
+  end
+end