ruby_routes 2.2.0 → 2.3.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 = '/'
+
+    # 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 = ''
+    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,106 @@
+# frozen_string_literal: true
+
 require_relative 'segment'
+require_relative 'utility/path_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
+
     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
       @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_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)].
+    #
+    # Optimized + simplified (cyclomatic / perceived complexity, length).
     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 [@static_children[segment], false] if @static_children[segment]
+
+      if @dynamic_child
+        capture_dynamic_param(params, @dynamic_child, segment)
         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
       end
 
-      # No match found at this node
-      [nil, false]
+      if @wildcard_child
+        capture_wildcard_param(params, @wildcard_child, segments, index)
+        return [@wildcard_child, true]
+      end
+
+      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 into the params hash if applicable.
+    #
+    # @param params [Hash, nil] the parameters hash to update
+    # @param dyn_node [Node] the dynamic child node
+    # @param value [String] the segment value to capture
+    def capture_dynamic_param(params, dyn_node, value)
+      return unless params && dyn_node.param_name
+
+      params[dyn_node.param_name] = value
+    end
+
+    # Captures a wildcard parameter value into the params hash if applicable.
+    #
+    # @param params [Hash, nil] the parameters hash to update
+    # @param wc_node [Node] the wildcard child node
+    # @param segments [Array<String>] the full path segments
+    # @param index [Integer] the current segment index
+    def capture_wildcard_param(params, wc_node, segments, index)
+      return unless params && wc_node.param_name
+
+      params[wc_node.param_name] = segments[index..].join('/')
     end
   end
 end

data/lib/ruby_routes/radix_tree/finder.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  class RadixTree
+    # Finder module for traversing the RadixTree and matching routes.
+    # Handles path normalization, segment traversal, and parameter extraction.
+    #
+    # @module RubyRoutes::RadixTree::Finder
+    module Finder
+      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 = {})
+        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
+
+        perform_traversal(segments, state, method, params)
+
+        finalize_success(state, method, params)
+      end
+
+      # Initializes the traversal state for route matching.
+      #
+      # @return [Hash] state hash with :current, :best_node, :best_params, :matched
+      def traversal_state
+        {
+          current: @root_node,
+          best_node: nil,
+          best_params: 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
+      def perform_traversal(segments, state, method, params)
+        segments.each_with_index do |segment, index|
+          next_node, stop = traverse_for_segment(state[:current], segment, index, segments, params)
+          return finalize_on_fail(state, method, 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) if endpoint_with_method?(state[:current], method)
+          break if stop
+        end
+      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
+      # @return [Array] [next_node, stop_traversal]
+      def traverse_for_segment(node, segment, index, segments, params)
+        node.traverse_for(segment, index, segments, params)
+      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
+      def record_candidate(state, _method, params)
+        state[:best_node] = state[:current]
+        state[:best_params] = 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
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_on_fail(state, method, params)
+        if state[:best_node]
+          handler = state[:best_node].handlers[method]
+          return constraints_pass?(handler, state[:best_params]) ? [handler, state[:best_params]] : [nil, params]
+        end
+        [nil, params]
+      end
+
+      # Finalizes the result after successful traversal.
+      #
+      # @param state [Hash] traversal state
+      # @param method [String] HTTP method
+      # @param params [Hash] parameters hash
+      # @return [Array] [handler, params] or [nil, params]
+      def finalize_success(state, method, params)
+        node = state[:current]
+        if endpoint_with_method?(node, method) && state[:matched]
+          handler = node.handlers[method]
+          return [handler, params] if constraints_pass?(handler, params)
+        end
+        # For non-matching paths, return nil
+        [nil, params]
+      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
+      # @return [Array] [handler, params] or [nil, params]
+      def fallback_candidate(state, method, params)
+        if state[:best_node] && state[:best_node] != @root_node
+          handler = state[:best_node].handlers[method]
+          return [handler, state[:best_params]] if handler && constraints_pass?(handler, state[:best_params])
+        end
+        [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_node.is_endpoint && (handler = @root_node.handlers[method])
+          [handler, params_out || {}]
+        else
+          [nil, params_out || {}]
+        end
+      end
+
+      # Checks if constraints pass for the handler.
+      #
+      # @param handler [Object] the route handler
+      # @param params [Hash] parameters hash
+      # @return [Boolean] true if constraints pass
+      def constraints_pass?(handler, params)
+        check_constraints(handler, params&.dup || {})
+      end
+    end
+  end
+end

data/lib/ruby_routes/radix_tree/inserter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  class RadixTree
+    # Inserter module for adding routes to the RadixTree.
+    # Handles tokenization, node advancement, and endpoint finalization.
+    #
+    # @module RubyRoutes::RadixTree::Inserter
+    module Inserter
+      private
+
+      # Inserts a route into the RadixTree for the given path and HTTP methods.
+      #
+      # @param path_string [String] the path to insert
+      # @param http_methods [Array<String>] the HTTP methods for the route
+      # @param route_handler [Object] the handler for the route
+      # @return [Object] the route handler
+      def insert_route(path_string, http_methods, route_handler)
+        return route_handler if path_string.nil? || path_string.empty?
+
+        tokens = split_path(path_string)
+        current_node = @root_node
+        tokens.each { |token| current_node = advance_node(current_node, token) }
+        finalize_endpoint(current_node, http_methods, route_handler)
+        route_handler
+      end
+
+      # Advances to the next node based on the token type.
+      #
+      # @param current_node [Node] the current node in the tree
+      # @param token [String] the token to process
+      # @return [Node] the next node
+      def advance_node(current_node, token)
+        case token[0]
+        when ':'
+          handle_dynamic(current_node, token)
+        when '*'
+          handle_wildcard(current_node, token)
+        else
+          handle_static(current_node, token)
+        end
+      end
+
+      # Handles dynamic parameter tokens (e.g., :id).
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the dynamic token
+      # @return [Node] the dynamic child node
+      def handle_dynamic(current_node, token)
+        param_name = token[1..]
+        current_node.dynamic_child ||= build_param_node(param_name)
+        current_node.dynamic_child
+      end
+
+      # Handles wildcard tokens (e.g., *splat).
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the wildcard token
+      # @return [Node] the wildcard child node
+      def handle_wildcard(current_node, token)
+        param_name = token[1..]
+        param_name = 'splat' if param_name.nil? || param_name.empty?
+        current_node.wildcard_child ||= build_param_node(param_name)
+        current_node.wildcard_child
+      end
+
+      # Handles static literal tokens.
+      #
+      # @param current_node [Node] the current node
+      # @param token [String] the static token
+      # @return [Node] the static child node
+      def handle_static(current_node, token)
+        literal_token = token.freeze
+        current_node.static_children[literal_token] ||= Node.new
+        current_node.static_children[literal_token]
+      end
+
+      # Builds a new node for parameter capture.
+      #
+      # @param param_name [String] the parameter name
+      # @return [Node] the new parameter node
+      def build_param_node(param_name)
+        node = Node.new
+        node.param_name = param_name
+        node
+      end
+
+      # Finalizes the endpoint by adding handlers for HTTP methods.
+      #
+      # @param node [Node] the endpoint node
+      # @param http_methods [Array<String>] the HTTP methods
+      # @param route_handler [Object] the route handler
+      def finalize_endpoint(node, http_methods, route_handler)
+        http_methods.each { |http_method| node.add_handler(http_method, route_handler) }
+      end
+    end
+  end
+end