ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/route/constraint_validator.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require_relative '../constant'
+
+module RubyRoutes
+  class Route
+    # ConstraintValidator: extracted constraint logic.
+    #
+    # This module provides methods for validating route constraints, including
+    # support for regular expressions, procs, hash-based constraints, and built-in
+    # validation rules. It also handles timeouts and raises appropriate exceptions
+    # for constraint violations.
+    module ConstraintValidator
+      # Validate all constraints for the given parameters.
+      #
+      # This method iterates through all constraints and validates each parameter
+      # against its corresponding rule.
+      #
+      # @param params [Hash] The parameters to validate.
+      # @return [void]
+      def validate_constraints_fast!(params)
+        @constraints.each do |key, rule|
+          param_key = key.to_s
+          next unless params.key?(param_key)
+
+          validate_constraint_for(rule, key, params[param_key])
+        end
+        nil
+      end
+
+      # Dispatch a single constraint check.
+      #
+      # This method validates a single parameter against its constraint rule.
+      #
+      # @param rule [Object] The constraint rule (Regexp, Proc, Symbol, Hash).
+      # @param key [String, Symbol] The parameter key.
+      # @param value [Object] The value to validate.
+      # @return [void]
+      def validate_constraint_for(rule, key, value)
+        case rule
+        when Regexp then validate_regexp_constraint(rule, value)
+        when Proc then validate_proc_constraint(key, rule, value)
+        when Hash then validate_hash_constraint!(rule, value.to_s)
+        else
+          validate_builtin_constraint(rule, value)
+        end
+      end
+
+      # Handle built-in symbol/string rules via a simple lookup.
+      #
+      # @param rule [Symbol, String] The built-in constraint rule.
+      # @param value [Object] The value to validate.
+      # @return [void]
+      def validate_builtin_constraint(rule, value)
+        case rule.to_s
+        when 'int'
+          validate_int_constraint(value)
+        when 'uuid'
+          validate_uuid_constraint(value)
+        when 'email'
+          validate_email_constraint(value)
+        when 'slug'
+          validate_slug_constraint(value)
+        when 'alpha'
+          validate_alpha_constraint(value)
+        when 'alphanumeric'
+          validate_alphanumeric_constraint(value)
+        end
+      end
+
+      # Validate a regexp constraint.
+      #
+      # This method validates a value against a regular expression constraint.
+      # It raises a timeout error if the validation takes too long.
+      #
+      # @param regexp [Regexp] The regular expression to match.
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value does not match the regexp.
+      def validate_regexp_constraint(regexp, value)
+        Timeout.timeout(0.1) { invalid! unless regexp.match?(value.to_s) }
+      rescue Timeout::Error
+        raise RubyRoutes::ConstraintViolation, 'Regex constraint timed out'
+      end
+
+      # Validate a proc constraint.
+      #
+      # This method validates a value using a proc constraint. It emits a
+      # deprecation warning for proc constraints and handles timeouts and errors.
+      #
+      # @param key [String, Symbol] The parameter key.
+      # @param proc [Proc] The proc to call.
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the proc constraint fails or times out.
+      def validate_proc_constraint(key, proc, value)
+        warn_proc_constraint_deprecation(key)
+        Timeout.timeout(0.05) { invalid! unless proc.call(value.to_s) }
+      rescue Timeout::Error
+        raise RubyRoutes::ConstraintViolation, 'Proc constraint timed out'
+      rescue StandardError => e
+        raise RubyRoutes::ConstraintViolation, "Proc constraint failed: #{e.message}"
+      end
+
+      # Validate an integer constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not an integer.
+      def validate_int_constraint(value)
+        invalid! unless value.to_s.match?(/\A\d+\z/)
+      end
+
+      # Validate a UUID constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid UUID.
+      def validate_uuid_constraint(value)
+        validate_uuid!(value)
+      end
+
+      # Validate an email constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid email.
+      def validate_email_constraint(value)
+        invalid! unless value.to_s.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
+      end
+
+      # Validate a slug constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid slug.
+      def validate_slug_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
+      end
+
+      # Validate an alpha constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not alphabetic.
+      def validate_alpha_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-zA-Z]+\z/)
+      end
+
+      # Validate an alphanumeric constraint.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not alphanumeric.
+      def validate_alphanumeric_constraint(value)
+        invalid! unless value.to_s.match?(/\A[a-zA-Z0-9]+\z/)
+      end
+
+      # Validate a UUID.
+      #
+      # This method validates that a value is a properly formatted UUID.
+      #
+      # @param value [Object] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value is not a valid UUID.
+      def validate_uuid!(value)
+        string = value.to_s
+        unless string.length == 36 && string.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+          invalid!
+        end
+      end
+
+      # Raise a constraint violation.
+      #
+      # @raise [RubyRoutes::ConstraintViolation] Always raises this exception.
+      def invalid!
+        raise RubyRoutes::ConstraintViolation
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/param_support.rb

@@ -0,0 +1,200 @@
+# 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 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.dup
+      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,84 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class Route
+    # PathBuilder: generation + segment encoding
+    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,87 @@
+# 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 = @cache_mutex.synchronize { @gen_cache.get(generation_cache_key) })
+          return cached_path
+        end
+
+        generated_path = generate_path_string(merged_params)
+        frozen_path = generated_path.frozen? ? generated_path : generated_path.dup.freeze
+        @cache_mutex.synchronize { @gen_cache.set(generation_cache_key, frozen_path) }
+        frozen_path
+      end
+
+      # Build a generation cache key for merged params.
+      #
+      # This method creates a cache key from all dynamic path parameters
+      # (required + optional, including splats) present 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)
+        names = @required_params.empty? ? @param_names : @required_params
+        names.empty? ? RubyRoutes::Constant::EMPTY_STRING : cache_key_for_params(names, merged_params)
+      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/utils'
+
+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 = @cache_mutex.synchronize { @query_cache.get(query_part) })
+          return cached_result
+        end
+
+        parsed_result = Rack::Utils.parse_query(query_part)
+        @cache_mutex.synchronize { @query_cache.set(query_part, parsed_result) }
+        parsed_result
+      end
+    end
+  end
+end