ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/route.rb

@@ -1,552 +1,178 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'timeout'
-require 'set'
 require 'rack'
+require 'set'
+require_relative 'constant'
+require_relative 'node'
 require_relative 'route/small_lru'
-require_relative 'utility/path_utility'
 require_relative 'utility/key_builder_utility'
+require_relative 'utility/method_utility'
+require_relative 'utility/path_utility'
+require_relative 'utility/route_utility'
+require_relative 'route/param_support'
+require_relative 'route/segment_compiler'
+require_relative 'route/path_builder'
+require_relative 'route/constraint_validator'
+require_relative 'route/check_helpers'
+require_relative 'route/query_helpers'
+require_relative 'route/validation_helpers'
+require_relative 'route/path_generation'
 
 module RubyRoutes
+  # Route
+  #
+  # Immutable-ish representation of a single HTTP route plus optimized
+  # helpers for:
+  # - Path recognition (segment compilation + fast param extraction)
+  # - Path generation (low‑allocation caching + param merging)
+  # - Constraint validation (regexp / typed / hash rules)
+  #
+  # Performance Techniques:
+  # - Precompiled segment descriptors (static / param / splat)
+  # - Small LRU caches (path generation + query parsing)
+  # - Thread‑local reusable Hashes / String buffers
+  # - Minimal object allocation in hot paths
+  #
+  # Thread Safety:
+  # - Instance is effectively read‑only after initialization.
+  # - Internal caches (@query_cache, @gen_cache, @validation_cache) are protected
+  #   by a mutex for safe concurrent access across multiple threads.
+  # - Designed for "build during boot, read per request" usage pattern.
+  #
+  # Public API Surface (stable):
+  # - #match?
+  # - #extract_params
+  # - #generate_path
+  # - #named?
+  # - #resource? / #collection?
+  #
+  # @api public
   class Route
+    include ParamSupport
+    include SegmentCompiler
+    include PathBuilder
+    include RubyRoutes::Route::ConstraintValidator
+    include RubyRoutes::Route::ValidationHelpers
+    include RubyRoutes::Route::QueryHelpers
+    include RubyRoutes::Route::PathGeneration
+    include RubyRoutes::Utility::MethodUtility
     include RubyRoutes::Utility::PathUtility
     include RubyRoutes::Utility::KeyBuilderUtility
 
     attr_reader :path, :methods, :controller, :action, :name, :constraints, :defaults
 
-    EMPTY_ARRAY = [].freeze
-    EMPTY_PAIR  = [EMPTY_ARRAY, EMPTY_ARRAY].freeze
-    EMPTY_STRING = ''.freeze
-
+    public :extract_params, :parse_query_params, :query_params, :generate_path
+
+    # Create a new Route.
+    #
+    # @param path [String] The raw route path (may include `:params` or `*splat`).
+    # @param options [Hash] The options for the route.
+    # @option options [Symbol, String, Array<Symbol, String>] :via (:get) HTTP method(s).
+    # @option options [String] :to ("controller#action") The controller and action.
+    # @option options [String] :controller Explicit controller (overrides `:to`).
+    # @option options [String, Symbol] :action Explicit action (overrides part after `#`).
+    # @option options [Hash] :constraints Parameter constraints (Regexp / Symbol / Hash).
+    # @option options [Hash] :defaults Default parameter values.
+    # @option options [Symbol, String] :as The route name.
     def initialize(path, options = {})
       @path = normalize_path(path)
-      # Pre-normalize and freeze methods at creation time
-      raw_methods   = Array(options[:via] || :get)
-      @methods      = raw_methods.map { |m| normalize_method(m) }.freeze
-      @methods_set  = @methods.to_set.freeze
-      @controller   = extract_controller(options)
-      @action       = options[:action] || extract_action(options[:to])
-      @name         = options[:as]
-      @constraints  = options[:constraints] || {}
-      # Pre-normalize defaults to string keys and freeze
-      @defaults     = (options[:defaults] || {}).transform_keys(&:to_s).freeze
 
-      # Pre-compile everything at initialization
+      setup_methods(options)
+      setup_controller_and_action(options)
+
+      @name = options[:as]
+      @constraints = options[:constraints] || {}
+      @defaults = (options[:defaults] || {}).transform_keys(&:to_s).freeze
+      @param_key_slots = [[nil, nil], [nil, nil]]
+      @required_validated_once = false
+
       precompile_route_data
       validate_route!
     end
 
+    # Test if this route matches an HTTP method + path string.
+    #
+    # @param request_method [String, Symbol] The HTTP method.
+    # @param request_path [String] The request path.
+    # @return [Boolean] `true` if the route matches, `false` otherwise.
     def match?(request_method, request_path)
-      # Fast method check: use frozen Set for O(1) lookup
-      return false unless @methods_set.include?(request_method.to_s.upcase)
-      !!extract_path_params_fast(request_path)
-    end
-
-    def extract_params(request_path, parsed_qp = nil)
-      path_params = extract_path_params_fast(request_path)
+      normalized_method = normalize_http_method(request_method)
+      return false unless @methods_set.include?(normalized_method)
 
-      return EMPTY_HASH unless path_params
-
-      # Use optimized param building
-      build_params_hash(path_params, request_path, parsed_qp)
+      !!extract_path_params_fast(request_path)
     end
 
+    # @return [Boolean] Whether this route has a name.
     def named?
       !@name.nil?
     end
 
+    # @return [Boolean] Heuristic: path contains `:id` implying a resource member.
     def resource?
       @is_resource
     end
 
+    # @return [Boolean] Inverse of `#resource?`.
     def collection?
       !@is_resource
     end
 
-    def parse_query_params(path)
-      query_params_fast(path)
-    end
-
-    # Optimized path generation with better caching and fewer allocations
-    def generate_path(params = {})
-      return @static_path if @static_path && (params.nil? || params.empty?)
-      params ||= {}
-      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?
-
-      merged = build_merged_params(params)
-      cache_key = cache_key_for_params(@required_params, merged)
-      if (cached = @gen_cache.get(cache_key))
-        return cached
-      end
-      path_str = generate_path_string(merged)
-      @gen_cache.set(cache_key, path_str)
-      path_str
-    end
-
-    # Fast query params method (cached and optimized)
-    def query_params(request_path)
-      query_params_fast(request_path)
-    end
-
     private
 
-    # Constants for performance
-    EMPTY_HASH = {}.freeze
-    ROOT_PATH = '/'.freeze
-    UNRESERVED_RE = /\A[a-zA-Z0-9\-._~]+\z/.freeze
-    QUERY_CACHE_SIZE = 128
-
-    # Common HTTP methods - interned for performance
-    HTTP_GET = 'GET'.freeze
-    HTTP_POST = 'POST'.freeze
-    HTTP_PUT = 'PUT'.freeze
-    HTTP_PATCH = 'PATCH'.freeze
-    HTTP_DELETE = 'DELETE'.freeze
-    HTTP_HEAD = 'HEAD'.freeze
-    HTTP_OPTIONS = 'OPTIONS'.freeze
-
-    # Fast method normalization using interned constants
-    def normalize_method(method)
-      case method
-      when :get then HTTP_GET
-      when :post then HTTP_POST
-      when :put then HTTP_PUT
-      when :patch then HTTP_PATCH
-      when :delete then HTTP_DELETE
-      when :head then HTTP_HEAD
-      when :options then HTTP_OPTIONS
-      else method.to_s.upcase.freeze
-      end
-    end
-
-    # Pre-compile all route data at initialization
-    def precompile_route_data
-      @is_resource = @path.match?(/\/:id(?:$|\.)/)
-      @gen_cache = SmallLru.new(512)  # larger cache
-      @query_cache = SmallLru.new(QUERY_CACHE_SIZE)
-      initialize_validation_cache
-
-      compile_segments
-      compile_required_params
-      check_static_path
-    end
-
-    def compile_segments
-      @compiled_segments = if @path == ROOT_PATH
-                             EMPTY_ARRAY
-                           else
-                             @path.split('/').reject(&:empty?).map do |seg|
-                               RubyRoutes::Constant.segment_descriptor(seg)
-                             end.freeze
-                           end
-    end
-
-    def compile_required_params
-      param_names = @compiled_segments.filter_map { |s| s[:name] if s[:type] != :static }
-      @param_names = param_names.freeze
-      @required_params = param_names.reject { |n| @defaults.key?(n) }.freeze
-      @required_params_set = @required_params.to_set.freeze
-    end
-
-    def check_static_path
-      # Pre-generate static paths (no params)
-      if @required_params.empty?
-        @static_path = generate_static_path
-      end
-    end
-
-    def generate_static_path
-      return ROOT_PATH if @compiled_segments.empty?
-
-      parts = @compiled_segments.map { |seg| seg[:value] }
-      "/#{parts.join('/')}"
-    end
-
-    # Optimized param building
-    def build_params_hash(path_params, request_path, parsed_qp)
-      # Use pre-allocated hash when possible
-      result = get_thread_local_hash
-
-      # Path params first (highest priority)
-      result.update(path_params)
-
-      # Query params (if needed)
-      if parsed_qp
-        result.merge!(parsed_qp)
-      elsif request_path.include?('?')
-        qp = query_params_fast(request_path)
-        result.merge!(qp) unless qp.empty?
-      end
-
-      # Defaults (lowest priority)
-      merge_defaults_fast(result) unless @defaults.empty?
-
-      # Validate constraints efficiently
-      validate_constraints_fast!(result) unless @constraints.empty?
-
-      result
-    end
-
-    def get_thread_local_hash
-      # Use a pool of hashes to reduce allocations
-      pool = Thread.current[:ruby_routes_hash_pool] ||= []
-      if pool.empty?
-        {}
-      else
-        hash = pool.pop
-        hash.clear
-        hash
-      end
-    end
-
-    def return_hash_to_pool(hash)
-      pool = Thread.current[:ruby_routes_hash_pool] ||= []
-      pool.push(hash) if pool.size < 5  # Keep pool small to avoid memory bloat
-    end
-
-    def merge_defaults_fast(result)
-      @defaults.each { |k, v| result[k] = v unless result.key?(k) }
-    end
-
-    # Fast path parameter extraction
-    def extract_path_params_fast(request_path)
-      return EMPTY_HASH if @compiled_segments.empty? && request_path == ROOT_PATH
-      return nil if @compiled_segments.empty?
-
-      path_parts = split_path(request_path)
-
-      # Check for wildcard/splat segment
-      has_splat = @compiled_segments.any? { |seg| seg[:type] == :splat }
-
-      if has_splat
-        return nil if path_parts.size < @compiled_segments.size - 1
-      else
-        return nil if @compiled_segments.size != path_parts.size
-      end
-
-      extract_params_from_parts(path_parts)
-    end
-
-    def extract_params_from_parts(path_parts)
-      params = {}
-
-      @compiled_segments.each_with_index do |seg, idx|
-        case seg[:type]
-        when :static
-          return nil unless seg[:value] == path_parts[idx]
-        when :param
-          params[seg[:name]] = path_parts[idx]
-        when :splat
-          params[seg[:name]] = path_parts[idx..-1].join('/')
-          break
-        end
-      end
-
-      params
-    end
-
-    # Optimized merged params building
-    def build_merged_params(params)
-      return @defaults if params.nil? || params.empty?
-      h = Thread.current[:ruby_routes_merge_hash] ||= {}
-      h.clear
-      @defaults.each { |k,v| h[k] = v }
-      params.each do |k,v|
-        next if v.nil?
-        ks = k.is_a?(String) ? k : k.to_s
-        h[ks] = v
-      end
-      h
-    end
-
-    def get_thread_local_merged_hash
-      hash = Thread.current[:ruby_routes_merged] ||= {}
-      hash.clear
-      hash
-    end
-
-    # Optimized path generation
-    def generate_path_string(merged)
-      return ROOT_PATH if @compiled_segments.empty?
-
-      # Estimate final path length to avoid resizing
-      estimated_size = 1 # For leading slash
-      @compiled_segments.each do |seg|
-        case seg[:type]
-        when :static
-          estimated_size += seg[:value].length + 1 # +1 for slash
-        when :param, :splat
-          estimated_size += 20 # Average param length estimate
-        end
-      end
-
-      # Use string buffer with pre-allocated capacity
-      path = String.new(capacity: estimated_size)
-      path << '/'
-
-      # Generate path directly into buffer
-      last_idx = @compiled_segments.size - 1
-      @compiled_segments.each_with_index do |seg, i|
-        case seg[:type]
-        when :static
-          path << seg[:value]
-        when :param
-          value = merged.fetch(seg[:name]).to_s
-          path << encode_segment_fast(value)
-        when :splat
-          value = merged.fetch(seg[:name], '')
-          path << format_splat_value(value)
-        end
-
-        path << '/' unless i == last_idx
-      end
-
-      path
-    end
-
-    def format_splat_value(value)
-      case value
-      when Array
-        value.map { |part| encode_segment_fast(part.to_s) }.join('/')
-      when String
-        value.split('/').map { |part| encode_segment_fast(part) }.join('/')
-      else
-        encode_segment_fast(value.to_s)
-      end
-    end
-
-    # Fast segment encoding with caching for common values
-    def encode_segment_fast(str)
-      return str if UNRESERVED_RE.match?(str)
-
-      # Cache encoded segments to avoid repeated encoding
-      @encoding_cache ||= {}
-      @encoding_cache[str] ||= begin
-        # Use URI.encode_www_form_component but replace + with %20 for path segments
-        URI.encode_www_form_component(str).gsub('+', '%20')
-      end
-    end
-
-    # Optimized query params with caching
-    def query_params_fast(path)
-      query_start = path.index('?')
-      return EMPTY_HASH unless query_start
-
-      query_string = path[(query_start + 1)..-1]
-      return EMPTY_HASH if query_string.empty? || query_string.match?(/^\?+$/)
-
-      # Cache query param parsing
-      if (cached = @query_cache.get(query_string))
-        return cached
-      end
-
-      result = Rack::Utils.parse_query(query_string)
-      @query_cache.set(query_string, result)
-      result
-    end
-
+    # Set up HTTP methods from options.
+    #
+    # @param options [Hash] The options for the route.
+    # @return [void]
+    def setup_methods(options)
+      raw_http_methods = Array(options[:via] || :get)
+      @methods = raw_http_methods.map { |method| normalize_http_method(method) }.freeze
+      @methods_set = @methods.to_set.freeze
+    end
+
+    # Set up controller and action from options.
+    #
+    # @param options [Hash] The options for the route.
+    # @return [void]
+    def setup_controller_and_action(options)
+      @controller = extract_controller(options)
+      @action = options[:action] || extract_action(options[:to])
+    end
+
+    # Infer controller name from options or `:to`.
+    #
+    # @param options [Hash] The options for the route.
+    # @return [String, nil] The inferred controller name.
     def extract_controller(options)
       to = options[:to]
       return options[:controller] unless to
+
       to.to_s.split('#', 2).first
     end
 
+    # Infer action from `:to` string.
+    #
+    # @param to [String, nil] The `:to` string.
+    # @return [String, nil] The inferred action name.
     def extract_action(to)
       return nil unless to
-      to.to_s.split('#', 2).last
-    end
-
-
-    def validate_required_params(params)
-      return EMPTY_PAIR if @required_params.empty?
-      missing = nil
-      nils    = nil
-      @required_params.each do |rk|
-        if params.key?(rk)
-          (nils ||= []) << rk if params[rk].nil?
-        elsif params.key?(sym = rk.to_sym)
-          (nils ||= []) << rk if params[sym].nil?
-        else
-          (missing ||= []) << rk
-        end
-      end
-      [missing || EMPTY_ARRAY, nils || EMPTY_ARRAY]
-    end
-
-    # Add this validation cache management
-    def initialize_validation_cache
-      @validation_cache = SmallLru.new(64)
-    end
-
-    def cache_validation_result(params, result)
-      # Only cache immutable params to prevent subtle bugs
-      if params.frozen? && @validation_cache && @validation_cache.size < 64
-        @validation_cache.set(params.hash, result)
-      end
-    end
-
-    def get_cached_validation(params)
-      return nil unless @validation_cache
-      @validation_cache.get(params.hash)
-    end
 
-    # Fast parameter type detection with result caching
-    def params_type(params)
-      # Cache parameter type detection results
-      @params_type_cache ||= {}
-      param_obj_id = params.object_id
-
-      # Return cached type if available
-      return @params_type_cache[param_obj_id] if @params_type_cache.key?(param_obj_id)
-
-      # Type detection with explicit checks
-      type = if params.is_a?(Hash)
-        # Further refine hash type for optimization
-        refine_hash_type(params)
-      elsif params.respond_to?(:each) && params.respond_to?(:[])
-        # Hash-like enumerable
-        :enumerable
-      else
-        # Last resort - may
-        :mehod_missing
-      end
-
-      # Keep cache small
-      if @params_type_cache.size > 100
-        @params_type_cache.clear
-      end
-
-      # Cache result
-      @params_type_cache[param_obj_id] = type
-    end
-
-    # Further refine hash type for potential optimization
-    def refine_hash_type(params)
-      # Only sample a few keys to determine type tendency
-      key_samples = params.keys.take(3)
-
-      if key_samples.all? { |k| k.is_a?(String) }
-        :string_keyed_hash
-      elsif key_samples.all? { |k| k.is_a?(Symbol) }
-        :symbol_keyed_hash
-      else
-        :hash # Mixed keys
-      end
-    end
-
-    # Optimized constraint validation
-    def validate_constraints_fast!(params)
-      @constraints.each do |param, constraint|
-        value = params[param.to_s]
-        # Only skip validation if the parameter is completely missing from params
-        # Empty strings and nil values should still be validated
-        next unless params.key?(param.to_s)
-
-        case constraint
-        when Regexp
-          # Protect against ReDoS attacks with timeout
-          begin
-            Timeout.timeout(0.1) do
-              raise RubyRoutes::ConstraintViolation unless constraint.match?(value.to_s)
-            end
-          rescue Timeout::Error
-            raise RubyRoutes::ConstraintViolation, "Regex constraint timed out (potential ReDoS attack)"
-          end
-        when Proc
-          # DEPRECATED: Proc constraints are deprecated due to security risks
-          warn_proc_constraint_deprecation(param)
-
-          # For backward compatibility, still execute but with strict timeout
-          begin
-            Timeout.timeout(0.05) do  # Reduced timeout for security
-              raise RubyRoutes::ConstraintViolation unless constraint.call(value.to_s)
-            end
-          rescue Timeout::Error
-            raise RubyRoutes::ConstraintViolation, "Proc constraint timed out (consider using secure alternatives)"
-          rescue => e
-            raise RubyRoutes::ConstraintViolation, "Proc constraint failed: #{e.message}"
-          end
-        when :int
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.match?(/\A\d+\z/)
-        when :uuid
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.length == 36 &&
-                 value_str.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
-        when :email
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.match?(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/)
-        when :slug
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
-        when :alpha
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.match?(/\A[a-zA-Z]+\z/)
-        when :alphanumeric
-          value_str = value.to_s
-          raise RubyRoutes::ConstraintViolation unless value_str.match?(/\A[a-zA-Z0-9]+\z/)
-        when Hash
-          # Secure hash-based constraints for common patterns
-          validate_hash_constraint!(constraint, value_str = value.to_s)
-        end
-      end
-    end
-
-    def warn_proc_constraint_deprecation(param)
-      return if @proc_warnings_shown&.include?(param)
-
-      @proc_warnings_shown ||= Set.new
-      @proc_warnings_shown << 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
-
-    def validate_hash_constraint!(constraint, value)
-      # Secure hash-based constraints
-      if constraint[:min_length] && value.length < constraint[:min_length]
-        raise RubyRoutes::ConstraintViolation, "Value too short (minimum #{constraint[:min_length]} characters)"
-      end
-
-      if constraint[:max_length] && value.length > constraint[:max_length]
-        raise RubyRoutes::ConstraintViolation, "Value too long (maximum #{constraint[:max_length]} characters)"
-      end
-
-      if constraint[:format] && !value.match?(constraint[:format])
-        raise RubyRoutes::ConstraintViolation, "Value does not match required format"
-      end
-
-      if constraint[:in] && !constraint[:in].include?(value)
-        raise RubyRoutes::ConstraintViolation, "Value not in allowed list"
-      end
-
-      if constraint[:not_in] && constraint[:not_in].include?(value)
-        raise RubyRoutes::ConstraintViolation, "Value in forbidden list"
-      end
-
-      if constraint[:range] && !constraint[:range].cover?(value.to_i)
-        raise RubyRoutes::ConstraintViolation, "Value not in allowed range"
-      end
+      to.to_s.split('#', 2).last
     end
 
-    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?
+    # Precompile route data for performance.
+    #
+    # @return [void]
+    def precompile_route_data
+      @is_resource = @path.match?(%r{/:id(?:$|\.)})
+      @gen_cache = SmallLru.new(512)
+      @query_cache = SmallLru.new(RubyRoutes::Constant::QUERY_CACHE_SIZE)
+      @cache_mutex = Mutex.new  # Thread-safe access to caches
+      initialize_validation_cache
+      compile_segments
+      compile_required_params
+      check_static_path
     end
   end
- end
+end