ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/constant.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'segments/base_segment'
 require_relative 'segments/dynamic_segment'
 require_relative 'segments/static_segment'
@@ -6,13 +8,47 @@ require_relative 'lru_strategies/hit_strategy'
 require_relative 'lru_strategies/miss_strategy'
 
 module RubyRoutes
+  # Constant
+  #
+  # Central registry for lightweight immutable structures and singleton
+  # strategy objects used across routing components. Centralization keeps
+  # hot path code free of repeated allocations and magic numbers.
+  #
+  # Responsibilities:
+  # - Map the first byte (ASCII) of a raw segment to its Segment subclass.
+  # - Provide lambda matchers for radix traversal (legacy/fallback).
+  # - Expose singleton LRU strategy objects (hit/miss).
+  # - Build compact Hash descriptors for parsed route path segments.
+  #
+  # Design Notes:
+  # - Numeric keys (42, 58) are ASCII codes for '*' and ':' allowing
+  #   O(1) dispatch without extra string comparisons.
+  # - Descriptor factories return frozen data to enable safe reuse.
+  #
+  # @api internal
   module Constant
+    # Shared, canonical root path constant (single source of truth).
+    ROOT_PATH = '/'.freeze
+
+    # Maps a segment's first byte (ASCII) to a Segment class.
+    #
+    # Keys:
+    # - 42 ('*')  -> Wildcard
+    # - 58 (':')  -> Dynamic
+    # - :default  -> Static
+    #
+    # @return [Hash{Integer, Symbol => Class}]
     SEGMENTS = {
       42 => RubyRoutes::Segments::WildcardSegment,   # '*'
       58 => RubyRoutes::Segments::DynamicSegment,    # ':'
       :default => RubyRoutes::Segments::StaticSegment
     }.freeze
 
+    # Legacy lambda-based segment matchers (kept for compatibility/fallback).
+    #
+    # Each lambda returns `[next_node, stop_traversal]` or `nil` when no match.
+    #
+    # @return [Hash{Symbol => Proc}]
     SEGMENT_MATCHERS = {
       static: lambda do |node, segment, _idx, _segments, _params|
         child = node.static_children[segment]
@@ -21,38 +57,121 @@ module RubyRoutes
 
       dynamic: lambda do |node, segment, _idx, _segments, params|
         return nil unless node.dynamic_child
-        nxt = node.dynamic_child
-        params[nxt.param_name.to_s] = segment if params && nxt.param_name
-        [nxt, false]
+
+        next_node = node.dynamic_child
+        params[next_node.param_name.to_s] = segment if params && next_node.param_name
+        [next_node, false]
       end,
 
       wildcard: lambda do |node, _segment, idx, segments, params|
         return nil unless node.wildcard_child
-        nxt = node.wildcard_child
-        params[nxt.param_name.to_s] = segments[idx..-1].join('/') if params && nxt.param_name
-        [nxt, true]
+
+        next_node = node.wildcard_child
+        params[next_node.param_name.to_s] = segments[idx..].join('/') if params && next_node.param_name
+        [next_node, true]
       end,
 
-      # default returns nil (no match). RadixTree#find will then return [nil, {}].
-      default: lambda { |_node, _segment, _idx, _segments, _params| nil }
+      default: ->(_node, _segment, _idx, _segments, _params) { nil }
     }.freeze
 
-    # singleton instances to avoid per-LRU allocations
-    LRU_HIT_STRATEGY = RubyRoutes::LruStrategies::HitStrategy.new.freeze
+    # Singleton instances to avoid per-cache strategy allocations.
+    #
+    # @return [RubyRoutes::LruStrategies::HitStrategy, RubyRoutes::LruStrategies::MissStrategy]
+    LRU_HIT_STRATEGY  = RubyRoutes::LruStrategies::HitStrategy.new.freeze
     LRU_MISS_STRATEGY = RubyRoutes::LruStrategies::MissStrategy.new.freeze
 
-    # Descriptor factories for segment classification (O(1) dispatch by first byte).
+    # Factories producing compact immutable descriptors for segments used
+    # during route compilation (faster than instantiating many objects).
+    #
+    # @return [Hash{Integer, Symbol => Proc}]
     DESCRIPTOR_FACTORIES = {
-      42 => ->(s) { { type: :splat,  name: (s[1..-1] || 'splat').freeze } }, # '*'
-      58 => ->(s) { { type: :param,  name:   s[1..-1].freeze } },             # ':'
-      :default => ->(s) { { type: :static, value:  s.freeze } }  # Intern static values
+      42 => lambda { |s|
+        name = s[1..]
+        { type: :splat, name: (name.nil? || name.empty? ? 'splat' : name).freeze }
+      }, # '*'
+      58 => ->(s) { { type: :param, name: s[1..].freeze } }, # ':'
+      :default => ->(s) { { type: :static, value: s.freeze } }
+    }.freeze
+
+    # Regex for unreserved characters (RFC 3986 subset).
+    #
+    # @return [Regexp]
+    UNRESERVED_RE = /\A[a-zA-Z0-9\-._~]+\z/
+
+    # Maximum size of the query parameter cache.
+    #
+    # This constant defines the maximum number of query strings that can be
+    # cached for fast lookup. Once the cache reaches this size, the least
+    # recently used entries will be evicted.
+    #
+    # @return [Integer]
+    QUERY_CACHE_SIZE = 128
+
+    # HTTP method constants.
+    HTTP_GET     = 'GET'
+    HTTP_POST    = 'POST'
+    HTTP_PUT     = 'PUT'
+    HTTP_PATCH   = 'PATCH'
+    HTTP_DELETE  = 'DELETE'
+    HTTP_HEAD    = 'HEAD'
+    HTTP_OPTIONS = 'OPTIONS'
+
+    # Empty constants for reuse.
+    EMPTY_ARRAY  = [].freeze
+    EMPTY_PAIR   = [EMPTY_ARRAY, EMPTY_ARRAY].freeze
+    EMPTY_STRING = ''.freeze
+    EMPTY_HASH   = {}.freeze
+
+    # Maximum number of distinct (method, path) composite keys retained
+    # before the oldest are overwritten in ring order.
+    #
+    # @return [Integer]
+    REQUEST_KEY_CAPACITY = 4096
+
+    # Supported DSL methods for route recording.
+    #
+    # @return [Array<Symbol>]
+    RECORDED_METHODS = %i[
+      get post put patch delete match root
+      resources resource
+      namespace scope constraints defaults
+      mount concern concerns
+    ].freeze
+
+    # All supported HTTP verbs.
+    #
+    # @return [Array<Symbol>]
+    VERBS_ALL = %i[get post put patch delete head options].freeze
+
+    # Default result for no traversal match.
+    #
+    # @return [Array]
+    NO_TRAVERSAL_RESULT = [nil, false, {}].freeze
+
+    # Built-in validators for constraints.
+    #
+    # @return [Hash{Symbol => Symbol}]
+    BUILTIN_VALIDATORS = {
+      int: :validate_int_constraint,
+      uuid: :validate_uuid_constraint,
+      email: :validate_email_constraint,
+      slug: :validate_slug_constraint,
+      alpha: :validate_alpha_constraint,
+      alphanumeric: :validate_alphanumeric_constraint
     }.freeze
 
+    # Build a descriptor Hash for a raw segment string.
+    #
+    # @param raw [String, #to_s] The raw segment string.
+    # @return [Hash] A descriptor hash with frozen values.
+    #
+    # @example
+    #   Constant.segment_descriptor(":id") # => { type: :param, name: "id" }
     def self.segment_descriptor(raw)
-      s = raw.to_s
-      key = s.empty? ? :default : s.getbyte(0)
-      factory = DESCRIPTOR_FACTORIES[key] || DESCRIPTOR_FACTORIES[:default]
-      factory.call(s)
+      segment_string = raw.to_s
+      dispatch_key   = segment_string.empty? ? :default : segment_string.getbyte(0)
+      factory        = DESCRIPTOR_FACTORIES[dispatch_key] || DESCRIPTOR_FACTORIES[:default]
+      factory.call(segment_string)
     end
   end
 end

data/lib/ruby_routes/lru_strategies/hit_strategy.rb

@@ -1,12 +1,39 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module LruStrategies
+    # HitStrategy
+    #
+    # Strategy object invoked when a lookup in SmallLru succeeds.
+    # Responsibilities:
+    # - Increment the hit counter.
+    # - Reinsert the accessed key at the logical MRU position to
+    #   approximate LRU behavior using simple Hash order.
+    #
+    # Isolation of this logic allows the hot path in SmallLru#get
+    # to delegate without conditionals, and lets alternative
+    # eviction / promotion policies be swapped in tests or future
+    # tuning without rewriting cache code.
+    #
+    # @example (internal usage)
+    #   lru = SmallLru.new
+    #   RubyRoutes::LruStrategies::HitStrategy.new.call(lru, :k)
+    #
+    # @api internal
     class HitStrategy
+      # Promote a key on cache hit.
+      #
+      # @param lru [SmallLru] the owning LRU cache
+      # @param key [Object] the key that was found
+      # @return [Object] the cached value
       def call(lru, key)
         lru.increment_hits
-        h = lru.instance_variable_get(:@h)
-        val = h.delete(key)
-        h[key] = val
-        val
+        # Internal storage name (@hash) is intentionally accessed reflectively
+        # to keep strategy decoupled from public API surface.
+        store = lru.instance_variable_get(:@hash)
+        value = store.delete(key)
+        store[key] = value
+        value
       end
     end
   end

data/lib/ruby_routes/lru_strategies/miss_strategy.rb

@@ -1,6 +1,27 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module LruStrategies
+    # MissStrategy
+    #
+    # Implements the behavior executed when a key lookup in SmallLru
+    # does not exist. It increments miss counters and returns nil.
+    #
+    # This object-oriented strategy form allows swapping behaviors
+    # without adding conditionals in the hot LRU path.
+    #
+    # @example Basic usage (internal)
+    #   lru = SmallLru.new
+    #   strategy = RubyRoutes::LruStrategies::MissStrategy.new
+    #   strategy.call(lru, :unknown) # => nil (and increments lru.misses)
+    #
+    # @api internal
     class MissStrategy
+      # Execute miss handling.
+      #
+      # @param lru [SmallLru] the LRU cache instance
+      # @param _key [Object] the missed key (unused)
+      # @return [nil] always nil to signal absence
       def call(lru, _key)
         lru.increment_misses
         nil

data/lib/ruby_routes/node.rb

@@ -1,64 +1,114 @@
+# frozen_string_literal: true
+
 require_relative 'segment'
+require_relative 'utility/path_utility'
+require_relative 'utility/method_utility'
 
 module RubyRoutes
-  # Node represents a single node in the radix tree structure.
-  # Each node can have static children (exact matches), one dynamic child (parameter capture),
-  # and one wildcard child (consumes remaining path segments).
+  # Node
+  #
+  # A single vertex in the routing radix tree.
+  #
+  # Structure:
+  # - static_children: Hash<String, Node> exact literal matches.
+  # - dynamic_child:   Node (":param") matches any single segment, captures value.
+  # - wildcard_child:  Node ("*splat") matches remaining segments (greedy).
+  #
+  # Handlers:
+  # - @handlers maps canonical HTTP method strings (e.g. "GET") to Route objects (or callable handlers).
+  # - @is_endpoint marks that at least one handler is attached (terminal path).
+  #
+  # Matching precedence (most → least specific):
+  #   static → dynamic → wildcard
+  #
+  # Thread safety: not thread-safe (build during boot).
+  #
+  # @api internal
   class Node
     attr_accessor :param_name, :is_endpoint, :dynamic_child, :wildcard_child
     attr_reader :handlers, :static_children
 
+    include RubyRoutes::Utility::PathUtility
+    include RubyRoutes::Utility::MethodUtility
+
     def initialize
-      @is_endpoint = false
-      @handlers = {}
+      @is_endpoint     = false
+      @handlers        = {}
       @static_children = {}
-      @dynamic_child = nil
-      @wildcard_child = nil
-      @param_name = nil
+      @dynamic_child   = nil
+      @wildcard_child  = nil
+      @param_name      = nil
     end
 
+    # Register a handler under an HTTP method.
+    #
+    # @param method [String, Symbol]
+    # @param handler [Object] route or callable
+    # @return [Object] handler
     def add_handler(method, handler)
-      method_str = normalize_method(method)
-      @handlers[method_str] = handler
+      method_key = normalize_http_method(method)
+      @handlers[method_key] = handler
       @is_endpoint = true
+      handler
     end
 
+    # Fetch a handler for a method.
+    #
+    # @param method [String, Symbol]
+    # @return [Object, nil]
     def get_handler(method)
-      @handlers[method]
+      @handlers[normalize_http_method(method)]
     end
 
-    # Fast traversal method with minimal allocations and streamlined branching.
-    # Matching order: static (most specific) → dynamic → wildcard (least specific)
-    # Returns [next_node_or_nil, should_break_bool] where should_break indicates
-    # wildcard capture that consumes remaining path segments.
+    # Traverses from this node using a single path segment.
+    # Returns [next_node_or_nil, stop_traversal(Boolean), captured_params(Hash)].
+    #
+    # Optimized + simplified (cyclomatic / perceived complexity, length).
+    #
+    # @param segment [String] the path segment to match
+    # @param index [Integer] the segment index in the full path
+    # @param segments [Array<String>] all path segments
+    # @param params [Hash] (unused in this method; mutation deferred)
+    # @return [Array] [next_node, stop, captured] or NO_TRAVERSAL_RESULT
     def traverse_for(segment, index, segments, params)
-      # Try static child first (most specific) - O(1) hash lookup
-      if @static_children.key?(segment)
-        return [@static_children[segment], false]
-      # Try dynamic child (parameter capture) - less specific than static
-      elsif @dynamic_child
-        # Capture parameter if params hash provided and param_name is set
-        params[@dynamic_child.param_name] = segment if params && @dynamic_child.param_name
-        return [@dynamic_child, false]
-      # Try wildcard child (consumes remaining segments) - least specific
-      elsif @wildcard_child
-        # Capture remaining path segments for wildcard parameter
-        if params && @wildcard_child.param_name
-          remaining = segments[index..-1]
-          params[@wildcard_child.param_name] = remaining.join('/')
-        end
-        return [@wildcard_child, true] # true signals to stop traversal
+      return [@static_children[segment], false, {}] if @static_children[segment]
+
+      if @dynamic_child
+        captured = capture_dynamic_param(@dynamic_child, segment)
+        return [@dynamic_child, false, captured]
+      end
+
+      if @wildcard_child
+        captured = capture_wildcard_param(@wildcard_child, segments, index)
+        return [@wildcard_child, true, captured]
       end
 
-      # No match found at this node
-      [nil, false]
+      RubyRoutes::Constant::NO_TRAVERSAL_RESULT
     end
 
     private
 
-    # Fast method normalization - converts method to uppercase string
-    def normalize_method(method)
-      method.to_s.upcase
+    # Captures a dynamic parameter value and returns it for later assignment.
+    #
+    # @param dynamic_node [Node] the dynamic child node
+    # @param value [String] the segment value to capture
+    # @return [Hash] captured parameter hash or empty hash if no param
+    def capture_dynamic_param(dynamic_node, value)
+      return {} unless dynamic_node.param_name
+
+      { dynamic_node.param_name => value }
+    end
+
+    # Captures a wildcard parameter value and returns it for later assignment.
+    #
+    # @param wc_node [Node] the wildcard child node
+    # @param segments [Array<String>] the full path segments
+    # @param index [Integer] the current segment index
+    # @return [Hash] captured parameter hash or empty hash if no param
+    def capture_wildcard_param(wildcard_node, segments, index)
+      return {} unless wildcard_node.param_name
+
+      { wildcard_node.param_name => segments[index..].join('/') }
     end
   end
 end

data/lib/ruby_routes/radix_tree/finder.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  class RadixTree
+    # Finder module for traversing the RadixTree and finding routes.
+    # Handles path normalization, segment traversal, and parameter extraction.
+    module Finder
+
+      # Evaluate constraint rules for a candidate route.
+      #
+      # @param route_handler [Object]
+      # @param captured_params [Hash]
+      # @return [Boolean]
+      def check_constraints(route_handler, captured_params)
+        return true unless route_handler.respond_to?(:validate_constraints_fast!)
+
+        begin
+          # Use a duplicate to avoid unintended mutation by validators.
+          route_handler.validate_constraints_fast!(captured_params)
+          true
+        rescue RubyRoutes::ConstraintViolation
+          false
+        end
+      end
+
+      private
+
+      # Finds a route handler for the given path and HTTP method.
+      #
+      # @param path_input [String] the input path to match
+      # @param method_input [String, Symbol] the HTTP method
+      # @param params_out [Hash] optional output hash for captured parameters
+      # @return [Array] [handler, params] or [nil, params] if no match
+      def find(path_input, method_input, params_out = nil)
+        path = path_input.to_s
+        method = normalize_http_method(method_input)
+        return root_match(method, params_out) if path.empty? || path == RubyRoutes::Constant::ROOT_PATH
+
+        segments = split_path_cached(path)
+        return [nil, params_out || {}] if segments.empty?
+
+        params = params_out || {}
+        state = traversal_state
+        captured_params = {}
+
+        result = perform_traversal(segments, state, method, params, captured_params)
+        return result unless result.nil?
+
+        finalize_success(state, method, params, captured_params)
+      end
+
+      # Initializes the traversal state for route matching.
+      #
+      # @return [Hash] state hash with :current, :best_node, :best_params, :best_captured, :matched
+      def traversal_state
+        {
+          current: @root,
+          best_node: nil,
+          best_params: nil,
+          best_captured: nil,
+          matched: false # Track if any segment was successfully matched
+        }
+      end
+
+      # Performs traversal through path segments to find a matching route.
+      #
+      # @param segments [Array<String>] path segments
+      # @param state [Hash] traversal state
+      # @param method [String] normalized HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] hash to collect captured parameters
+      # @return [nil, Array] nil if traversal succeeds, Array from finalize_on_fail if traversal fails
+      def perform_traversal(segments, state, method, params, captured_params)
+        segments.each_with_index do |segment, index|
+          next_node, stop = traverse_for_segment(state[:current], segment, index, segments, params, captured_params)
+          return finalize_on_fail(state, method, params, captured_params) unless next_node
+
+          state[:current] = next_node
+          state[:matched] = true # Set matched to true if at least one segment matched
+          record_candidate(state, method, params, captured_params) if endpoint_with_method?(state[:current], method)
+          break if stop
+        end
+        nil # Return nil to indicate successful traversal
+      end
+
+      # Traverses to the next node for a given segment.
+      #
+      # @param node [Node] current node
+      # @param segment [String] current segment
+      # @param index [Integer] segment index
+      # @param segments [Array<String>] all segments
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] hash to collect captured parameters
+      # @return [Array] [next_node, stop_traversal, segment_captured]
+      def traverse_for_segment(node, segment, index, segments, params, captured_params)
+        next_node, stop, segment_captured = node.traverse_for(segment, index, segments, params)
+        captured_params.merge!(segment_captured) if segment_captured
+        [next_node, stop]
+      end
+
+      # Records the current node as a candidate match.
+      #
+      # @param state [Hash] traversal state
+      # @param _method [String] HTTP method (unused)
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      def record_candidate(state, _method, params, captured_params)
+        state[:best_node] = state[:current]
+        state[:best_params] = params.dup
+        state[:best_captured] = captured_params.dup
+      end
+
+      # Checks if the node is an endpoint with a handler for the method.
+      #
+      # @param node [Node] the node to check
+      # @param method [String] HTTP method
+      # @return [Boolean] true if endpoint and handler exists
+      def endpoint_with_method?(node, method)
+        node.is_endpoint && node.handlers[method]
+      end
+
+      # Finalizes the result when traversal fails mid-path.
+      #
+      # @param state [Hash] traversal state
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_on_fail(state, method, params, captured_params)
+        best_params = state[:best_params] || params
+        best_captured = state[:best_captured] || captured_params
+        finalize_match(state[:best_node], method, best_params, best_captured)
+      end
+
+      # Finalizes the result after successful traversal.
+      #
+      # @param state [Hash] traversal state
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_success(state, method, params, captured_params)
+        result = finalize_match(state[:current], method, params, captured_params)
+        return result if result[0]
+
+        # Try best candidate if current failed
+        if state[:best_node]
+          best_params = state[:best_params] || params
+          best_captured = state[:best_captured] || captured_params
+          finalize_match(state[:best_node], method, best_params, best_captured)
+        else
+          result
+        end
+      end
+
+      # Falls back to the best candidate if no exact match.
+      #
+      # @param state [Hash] traversal state
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      # @return [Array] [handler, params] or [nil, params]
+      def fallback_candidate(state, method, params, captured_params)
+        finalize_match(state[:best_node], method, state[:best_params], state[:best_captured])
+      end
+
+      # Common method to finalize a match attempt.
+      # Assumes the node is already validated as an endpoint.
+      #
+      # @param node [Node] the node to check for a handler
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_match(node, method, params, captured_params)
+        if node && endpoint_with_method?(node, method)
+          handler = node.handlers[method]
+          # Apply captured params before constraint validation
+          apply_captured_params(params, captured_params)
+          if check_constraints(handler, params)
+            return [handler, params]
+          end
+        end
+        # For non-matching paths, return nil
+        apply_captured_params(params, captured_params)
+        [nil, params]
+      end
+
+      # Handles matching for the root path.
+      #
+      # @param method [String] HTTP method
+      # @param params_out [Hash] parameters hash
+      # @return [Array] [handler, params] or [nil, params]
+      def root_match(method, params_out)
+        if @root.is_endpoint && (handler = @root.handlers[method])
+          [handler, params_out || {}]
+        else
+          [nil, params_out || {}]
+        end
+      end
+
+      # Applies captured parameters to the final params hash.
+      #
+      # @param params [Hash] the final parameters hash
+      # @param captured_params [Hash] captured parameters from traversal
+      def apply_captured_params(params, captured_params)
+        params.merge!(captured_params) if captured_params && !captured_params.empty?
+      end
+    end
+  end
+end