ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/route/segment_compiler.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative '../utility/path_utility'
+
+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 SegmentCompiler
+      include RubyRoutes::Utility::PathUtility
+
+      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) if name.is_a?(String))
+                                  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

data/lib/ruby_routes/route/small_lru.rb

@@ -1,47 +1,122 @@
+# frozen_string_literal: true
+
+#
+# RubyRoutes::Route::SmallLru
+#
+# A tiny fixed‑capacity Least Recently Used (LRU) cache optimized for:
+# - Very small memory footprint
+# - Low per‑operation overhead
+# - Predictable eviction (oldest key removed when capacity exceeded)
+#
+# Implementation notes:
+# - Backed by a Ruby Hash (insertion order preserves LRU ordering when we reinsert on hit)
+# - get promotes an entry by deleting + reinserting (handled by hit strategy)
+# - External pluggable strategies supply side effects for hit / miss (counters, promotions)
+# - Eviction uses Hash#shift (O(1) for Ruby >= 2.5)
+#
+# Thread safety: NOT thread‑safe. Wrap with a Mutex externally if sharing across threads.
+#
+# Public API surface kept intentionally small for hot path use in routing / path caching.
+#
 module RubyRoutes
   class Route
-    # small LRU used for path generation cache
+    # SmallLru
+    # @!visibility public
     class SmallLru
-      attr_reader :hits, :misses, :evictions
+      # @return [Integer] maximum number of entries retained
+      # @return [Integer] number of cache hits
+      # @return [Integer] number of cache misses
+      # @return [Integer] number of evictions (when capacity exceeded)
+      attr_reader :max_size, :hits, :misses, :evictions
 
-      # larger default to reduce eviction likelihood in benchmarks
+      # @param max_size [Integer] positive maximum size
+      # @raise [ArgumentError] if max_size < 1
       def initialize(max_size = 1024)
-        @max_size = max_size
-        @h = {}
-        @hits = 0
-        @misses = 0
-        @evictions = 0
+        max = Integer(max_size)
+        raise ArgumentError, 'max_size must be >= 1' if max < 1
 
-        @hit_strategy = RubyRoutes::Constant::LRU_HIT_STRATEGY
+        @max_size  = max
+        @hash      = {} # { key => value } (insertion order = LRU order)
+        @hits      = 0
+        @misses    = 0
+        @evictions = 0
+        # Strategy objects must respond_to?(:call). They receive (lru, key) or (lru, key, value).
+        @hit_strategy  = RubyRoutes::Constant::LRU_HIT_STRATEGY
         @miss_strategy = RubyRoutes::Constant::LRU_MISS_STRATEGY
       end
 
+      # Fetch a cached value.
+      #
+      # On hit:
+      # - Strategy updates hit count and reorders key (strategy expected to call increment_hits + promote)
+      # On miss:
+      # - Strategy updates miss count (strategy expected to call increment_misses)
+      #
+      # @param key [Object]
+      # @return [Object, nil] cached value or nil
       def get(key)
-        strategy = @h.key?(key) ? @hit_strategy : @miss_strategy
-        strategy.call(self, key)
+        lookup_strategy = @hash.key?(key) ? @hit_strategy : @miss_strategy
+        lookup_strategy.call(self, key)
       end
 
-      def set(key, val)
-        @h.delete(key) if @h.key?(key)
-        @h[key] = val
-        if @h.size > @max_size
-          @h.shift
+      # Insert or update an entry.
+      # Re-inserts key to become most recently used.
+      # Evicts least recently used (Hash#shift) if capacity exceeded.
+      #
+      # @param key [Object]
+      # @param value [Object]
+      # @return [Object] value
+      def set(key, value)
+        @hash.delete(key) if @hash.key?(key) # promote existing
+        @hash[key] = value
+        if @hash.size > @max_size
+          @hash.shift
           @evictions += 1
         end
-        val
+        value
       end
 
+      # @return [Integer] current number of entries
       def size
-        @h.size
+        @hash.size
       end
 
+      # @return [Boolean]
+      def empty?
+        @hash.empty?
+      end
+
+      # @return [Array<Object>] keys in LRU order (oldest first)
+      def keys
+        @hash.keys
+      end
+
+      # Debug / spec helper (avoid exposing internal Hash directly).
+      # @return [Hash] shallow copy of internal store
+      def inspect_hash
+        @hash.dup
+      end
+
+      # Increment hit counter (intended for strategy objects).
+      # @return [void]
       def increment_hits
         @hits += 1
       end
 
+      # Increment miss counter (intended for strategy objects).
+      # @return [void]
       def increment_misses
         @misses += 1
       end
+
+      # Internal helper used by hit strategy to promote key.
+      # @param key [Object]
+      # @return [void]
+      def promote(key)
+        val = @hash.delete(key)
+        @hash[key] = val if val
+      end
+      private :promote
     end
   end
 end

data/lib/ruby_routes/route/validation_helpers.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative 'check_helpers'
+
+module RubyRoutes
+  class Route
+    # ValidationHelpers: extracted validation and defaults logic.
+    #
+    # This module provides methods for validating routes, required parameters,
+    # and hash-form constraints. It also includes caching mechanisms for
+    # validation results and utilities for managing hash pools.
+    module ValidationHelpers
+      include RubyRoutes::Route::CheckHelpers
+
+      # Initialize validation result cache.
+      #
+      # This method initializes an LRU (Least Recently Used) cache for storing
+      # validation results, with a maximum size of 64 entries.
+      #
+      # @return [void]
+      def initialize_validation_cache
+        @validation_cache = SmallLru.new(64)
+      end
+
+      # Validate fundamental route shape.
+      #
+      # This method ensures that the route has a valid controller, action, and
+      # HTTP method. If any of these are invalid, an `InvalidRoute` exception
+      # is raised.
+      #
+      # @raise [InvalidRoute] If the route is invalid.
+      # @return [void]
+      def validate_route!
+        raise InvalidRoute, 'Controller is required' if @controller.nil?
+        raise InvalidRoute, 'Action is required' if @action.nil?
+        raise InvalidRoute, "Invalid HTTP method: #{@methods}" if @methods.empty?
+      end
+
+      # Validate required parameters once.
+      #
+      # This method validates that all required parameters are present and not
+      # nil. It uses per-params caching to avoid re-validation for the same
+      # frozen params.
+      #
+      # @param params [Hash] The parameters to validate.
+      # @raise [RouteNotFound] If required parameters are missing or nil.
+      # @return [void]
+      def validate_required_once(params)
+        return if @required_params.empty?
+
+        # Check cache for existing validation result
+        cached_result = get_cached_validation(params)
+        if cached_result
+          missing, nils = cached_result
+        else
+          # Perform validation
+          missing, nils = validate_required_params(params)
+          # Cache the result only if params are frozen
+          if params.frozen?
+            cache_validation_result(params, [missing, nils])
+          end
+        end
+
+        # Raise if invalid
+        raise RouteNotFound, "Missing params: #{missing.join(', ')}" unless missing.empty?
+        raise RouteNotFound, "Missing or nil params: #{nils.join(', ')}" unless nils.empty?
+      end
+
+      # Validate required parameters.
+      #
+      # This method checks for missing or nil required parameters.
+      #
+      # @param params [Hash] The parameters to validate.
+      # @return [Array<Array>] An array containing two arrays:
+      #   - `missing` [Array<String>] The keys of missing parameters.
+      #   - `nils` [Array<String>] The keys of parameters that are nil.
+      def validate_required_params(params)
+        return RubyRoutes::Constant::EMPTY_PAIR if @required_params.empty?
+        params ||= {}
+
+        if (cached = get_cached_validation(params))
+          return cached
+        end
+
+        missing = []
+        nils = []
+        @required_params.each do |required_key|
+          process_required_key(required_key, params, missing, nils)
+        end
+        result = [missing, nils]
+        cache_validation_result(params, result)
+        result
+      end
+
+      # Per-key validation helper used by `validate_required_params`.
+      #
+      # This method checks if a specific required key is present and not nil.
+      #
+      # @param required_key [String] The required parameter key.
+      # @param params [Hash] The parameters to validate.
+      # @param missing [Array<String>] The array to store missing keys.
+      # @param nils [Array<String>] The array to store keys with nil values.
+      # @return [void]
+      def process_required_key(required_key, params, missing, nils)
+        if params.key?(required_key)
+          nils << required_key if params[required_key].nil?
+        else
+          symbol_key = required_key.to_sym
+          if params.key?(symbol_key)
+            nils << required_key if params[symbol_key].nil?
+          else
+            missing << required_key
+          end
+        end
+      end
+
+      # Cache validation result.
+      #
+      # This method stores the validation result in the cache if the parameters
+      # are frozen and the cache is not full.
+      #
+      # @param params [Hash] The parameters used for validation.
+      # @param result [Object] The validation result to cache.
+      # @return [void]
+      def cache_validation_result(params, result)
+        return unless params.frozen?
+        return unless @validation_cache && @validation_cache.size < 64
+
+        @cache_mutex.synchronize { @validation_cache.set(params.hash, result) }
+      end
+
+      # Fetch cached validation result.
+      #
+      # This method retrieves a cached validation result for the given parameters.
+      #
+      # @param params [Hash] The parameters used for validation.
+      # @return [Object, nil] The cached validation result, or `nil` if not found.
+      def get_cached_validation(params)
+        return nil unless params && @validation_cache
+        @cache_mutex.synchronize { @validation_cache.get(params.hash) }
+      end
+
+      # Return hash to pool.
+      #
+      # This method returns a hash to the thread-local hash pool for reuse.
+      #
+      # @param hash [Hash] The hash to return to the pool.
+      # @return [void]
+      def return_hash_to_pool(hash)
+        pool = Thread.current[:ruby_routes_hash_pool] ||= []
+        pool.push(hash) if pool.size < 5
+      end
+
+      # Validate hash-form constraint rules.
+      #
+      # This method validates a value against a set of hash-form constraints,
+      # such as minimum length, maximum length, format, inclusion, exclusion,
+      # and range.
+      #
+      # @param constraint [Hash] The constraint rules.
+      # @param value [String] The value to validate.
+      # @raise [RubyRoutes::ConstraintViolation] If the value violates any constraint.
+      # @return [void]
+      def validate_hash_constraint!(constraint, value)
+        check_min_length(constraint, value)
+        check_max_length(constraint, value)
+        check_format(constraint, value)
+        check_in_list(constraint, value)
+        check_not_in_list(constraint, value)
+        check_range(constraint, value)
+      end
+    end
+  end
+end

data/lib/ruby_routes/route/warning_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module RubyRoutes
+  class Route
+    # WarningHelpers: encapsulate deprecation / warning helpers.
+    #
+    # This module provides methods for emitting deprecation warnings for
+    # deprecated features, such as `Proc` constraints, and suggests secure
+    # alternatives.
+    module WarningHelpers
+      # 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)
+        key = param.to_sym
+        return if @proc_warnings_shown&.include?(key)
+
+        @proc_warnings_shown ||= Set.new
+        @proc_warnings_shown << key
+        warn_proc_warning(key)
+      end
+
+      # Warn about `Proc` constraint deprecation.
+      #
+      # This method emits a detailed deprecation warning for `Proc` constraints,
+      # explaining the security risks and suggesting secure alternatives.
+      #
+      # @param param [String, Symbol] The parameter name for which the warning
+      #   is being emitted.
+      # @return [void]
+      def warn_proc_warning(param)
+        warn <<~WARNING
+          [DEPRECATION] Proc constraints are deprecated due to security risks.
+
+          Parameter: #{param}; Route: #{@path}
+
+          Secure alternatives:
+          - Use regex: constraints: { #{param}: /\\A\\d+\\z/ }
+          - Use built-in types: constraints: { #{param}: :int }
+          - Use hash constraints: constraints: { #{param}: { min_length: 3, format: /\\A[a-z]+\\z/ } }
+
+          Available built-in types: :int, :uuid, :email, :slug, :alpha, :alphanumeric
+
+          This warning will become an error in a future version.
+        WARNING
+      end
+    end
+  end
+end