ruby_routes 2.2.0 → 2.3.0

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,151 @@
+# 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 ensures that validation is performed only once per request.
+      #
+      # @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? || @required_validated_once
+
+        missing, nils = validate_required_params(params)
+        raise RouteNotFound, "Missing params: #{missing.join(', ')}" unless missing.empty?
+        raise RouteNotFound, "Missing or nil params: #{nils.join(', ')}" unless nils.empty?
+
+        @required_validated_once = true
+      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?
+
+        missing = []
+        nils = []
+        @required_params.each do |required_key|
+          process_required_key(required_key, params, missing, nils)
+        end
+        [missing, nils]
+      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?
+        elsif params.key?(symbol_key = required_key.to_sym)
+          nils << required_key if params[symbol_key].nil?
+        else
+          missing << required_key
+        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
+
+        @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)
+        @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,54 @@
+# frozen_string_literal: true
+
+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)
+        return if @proc_warnings_shown&.include?(param)
+
+        @proc_warnings_shown ||= Set.new
+        @proc_warnings_shown << param
+        warn_proc_warning(param)
+      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