ruby_routes 2.2.0 → 2.4.0

data/lib/ruby_routes/segments/wildcard_segment.rb

@@ -1,26 +1,72 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Segments
+    # WildcardSegment
+    #
+    # Represents a greedy (splat) segment in a route definition (e.g. "*path").
+    # Captures the remainder of the request path (including embedded slashes)
+    # starting at its position and stores it under the parameter name
+    # (text after the asterisk) or "splat" if none provided.
+    #
+    # Matching Behavior:
+    # - Succeeds only if the current radix node has a +wildcard_child+.
+    # - Consumes all remaining segments and stops traversal (second tuple true).
+    #
+    # Returned tuple from #match:
+    #   [next_node, stop_traversal_flag=true]
+    #
+    # @api internal
     class WildcardSegment < BaseSegment
-      def initialize(text)
-        @name = (text[1..-1] || 'splat')
+      # Correctly derive parameter name for wildcard splats.
+      #
+      # "*photos"  -> "photos"
+      # "*"        -> "splat"   (previous code produced "" and never fell back)
+      #
+      # Also ensures @raw_text is assigned by delegating to BaseSegment#initialize.
+      # @param raw_segment_text [String] raw token (e.g. "*path" or "*")
+      def initialize(raw_segment_text)
+        super(raw_segment_text)
+        tail = raw_segment_text && raw_segment_text[1..]
+        tail = nil if tail == '' # treat empty substring as absent
+        @param_name = tail || 'splat'
       end
 
-      def ensure_child(current)
-        current.wildcard_child ||= Node.new
-        current = current.wildcard_child
-        current.param_name = @name
-        current
+      # Ensure a wildcard child node on +parent_node+ and assign param name.
+      #
+      # @param parent_node [Object]
+      # @return [Object] wildcard child node
+      def ensure_child(parent_node)
+        parent_node.wildcard_child ||= Node.new
+        wildcard_child_node = parent_node.wildcard_child
+        if wildcard_child_node.param_name.nil?
+          wildcard_child_node.param_name = @param_name
+        end
+        wildcard_child_node
       end
 
+      # @return [Boolean] always true for wildcard segment
       def wildcard?
         true
       end
 
-      def match(node, _text, idx, segments, params)
-        return [nil, false] unless node.wildcard_child
-        nxt = node.wildcard_child
-        params[nxt.param_name.to_s] = segments[idx..-1].join('/') if params
-        [nxt, true]
+      # Attempt to match / consume remaining path.
+      #
+      # @param current_node [Object] current radix node
+      # @param _unused_literal [String] (unused)
+      # @param segment_index [Integer] index where wildcard appears
+      # @param all_path_segments [Array<String>] all request segments
+      # @param captured_params [Hash] params hash to populate
+      # @return [Array<(Object, Boolean)>] [wildcard_child_node_or_nil, stop_traversal_flag]
+      def match(current_node, _unused_literal, segment_index, all_path_segments, captured_params)
+        return [nil, false] unless current_node.wildcard_child
+
+        wildcard_child_node = current_node.wildcard_child
+        if captured_params
+          remaining_path = all_path_segments[segment_index..].join('/')
+          captured_params[wildcard_child_node.param_name.to_s] = remaining_path
+        end
+        [wildcard_child_node, true]
       end
     end
   end

data/lib/ruby_routes/string_extensions.rb

@@ -1,28 +1,65 @@
+# frozen_string_literal: true
+
+# Minimal String inflection helpers.
+#
+# @note This is a very small, intentionally naive English inflector
+# covering only a few common pluralization patterns used inside the
+# routing DSL (e.g., resources / resource helpers). It is NOT a full
+# replacement for ActiveSupport::Inflector and should not be relied on
+# for general linguistic correctness.
+#
+# @note Supported patterns:
+# - Singularize:
+#   * words ending in "ies" -> "y" (companies -> company)
+#   * words ending in "s"   -> strip trailing "s" (users -> user)
+# - Pluralize:
+#   * words ending in "y"   -> replace with "ies" (company -> companies)
+#   * words ending in sh/ch/x -> append "es" (box -> boxes)
+#   * words ending in "z"   -> append "zes" (quiz -> quizzes) (simplified)
+#   * words ending in "s"   -> unchanged
+#   * default -> append "s"
+#
+# @note Limitations:
+# - Does not handle irregular forms (person/people, child/children, etc.).
+# - Simplified handling of "z" endings (adds "zes" instead of "zzes").
+# - Case‑sensitive (expects lowercase ASCII).
+#
+# @api internal
 class String
+  # Convert a plural form to a simplistic singular.
+  #
+  # @example Singularize a word
+  #   "companies".singularize # => "company"
+  #   "users".singularize     # => "user"
+  #   "box".singularize       # => "box" (unchanged)
+  #
+  # @return [String] Singularized form (may be the same object if no change is needed).
   def singularize
     case self
     when /ies$/
-      self.sub(/ies$/, 'y')
+      sub(/ies$/, 'y')
     when /s$/
-      self.sub(/s$/, '')
+      sub(/s$/, '')
     else
       self
     end
   end
 
+  # Convert a singular form to a simplistic plural.
+  #
+  # @example Pluralize a word
+  #   "company".pluralize # => "companies"
+  #   "box".pluralize     # => "boxes"
+  #   "quiz".pluralize    # => "quizzes"
+  #   "user".pluralize    # => "users"
+  #
+  # @return [String] Pluralized form.
   def pluralize
-    case self
-    when /y$/
-      self.sub(/y$/, 'ies')
-    when /sh$/, /ch$/, /x$/
-      self + 'es'
-    when /z$/
-      self + 'zes'
-    when /s$/
-      # Words ending in 's' are already plural
-      self
-    else
-      self + 's'
-    end
+    return self if end_with?('s')
+    return sub(/y$/, 'ies') if end_with?('y')
+    return "#{self}es" if match?(/sh$|ch$|x$/)
+    return "#{self}zes" if end_with?('z')
+
+    "#{self}s"
   end
 end

data/lib/ruby_routes/url_helpers.rb

@@ -1,17 +1,60 @@
+# frozen_string_literal: true
+
 require 'cgi'
 
 module RubyRoutes
+  # UrlHelpers
+  #
+  # Mixin that provides named route helper methods (e.g., `user_path`),
+  # HTML link/button helpers, and simple redirect data structures.
+  #
+  # Inclusion pattern:
+  #   class Application
+  #     include RubyRoutes::UrlHelpers
+  #     def route_set; ROUTES end
+  #   end
+  #
+  # When a Route is named, router code should call:
+  #   add_url_helper(:user_path, route_instance)
+  #
+  # This defines:
+  #   user_path(params = {}) -> "/users/1"
+  #
+  # Public instance methods:
+  # - `#path_to(name, params)` → String path
+  # - `#url_to(name, params)` → Absolute URL (host hard‑coded: localhost)
+  # - `#link_to(name, text, params)` → HTML anchor tag
+  # - `#button_to(name, text, params)` → HTML form button
+  # - `#redirect_to(name, params)` → { status:, location: }
+  #
+  # Requirements:
+  # - Including class must define `#route_set` returning a `RouteSet`.
+  #
+  # @api public
   module UrlHelpers
+    # Hook for when the module is included.
+    #
+    # @param base [Class] The class including the module.
+    # @return [void]
     def self.included(base)
       base.extend(ClassMethods)
       base.include(base.url_helpers)
     end
 
+    # Class‑level DSL for defining dynamic helper methods.
     module ClassMethods
+      # Module storing dynamically defined helper methods (memoized).
+      #
+      # @return [Module] The module containing dynamically defined helpers.
       def url_helpers
         @url_helpers ||= Module.new
       end
 
+      # Define a named route helper method.
+      #
+      # @param name [Symbol] The helper method name (e.g., `:user_path`).
+      # @param route [RubyRoutes::Route] The route instance.
+      # @return [void]
       def add_url_helper(name, route)
         url_helpers.define_method(name) do |*args|
           params = args.first || {}
@@ -20,56 +63,95 @@ module RubyRoutes
       end
     end
 
+    # Access the dynamically generated helpers module (instance side).
+    #
+    # @return [Module] The module containing dynamically defined helpers.
     def url_helpers
       self.class.url_helpers
     end
 
+    # Resolve a named route to a path.
+    #
+    # @param name [Symbol, String] The route name.
+    # @param params [Hash] The parameter substitutions.
+    # @return [String] The generated path.
     def path_to(name, params = {})
       route = route_set.find_named_route(name)
       route_set.generate_path_from_route(route, params)
     end
 
+    # Resolve a named route to a full (hard‑coded host) URL.
+    #
+    # @param name [Symbol, String] The route name.
+    # @param params [Hash] The parameter substitutions.
+    # @return [String] The absolute URL.
     def url_to(name, params = {})
       path = path_to(name, params)
       "http://localhost#{path}"
     end
 
+    # Build an HTML anchor tag for a named route.
+    #
+    # @param name [Symbol, String] The route name.
+    # @param text [String] The link text.
+    # @param params [Hash] The parameter substitutions.
+    # @return [String] The HTML-safe anchor tag.
     def link_to(name, text, params = {})
       path = path_to(name, params)
-      safe_path = CGI.escapeHTML(path.to_s)
-      safe_text = CGI.escapeHTML(text.to_s)
-      "<a href=\"#{safe_path}\">#{safe_text}</a>"
+      escaped_path = CGI.escapeHTML(path.to_s)
+      escaped_text = CGI.escapeHTML(text.to_s)
+      "<a href=\"#{escaped_path}\">#{escaped_text}</a>"
     end
 
+    # Build a minimal HTML form acting as a button submission to a named route.
+    #
+    # Supports non-GET/POST methods via a hidden `_method` field (Rails style).
+    #
+    # @param name [Symbol, String] The route name.
+    # @param text [String] The button label.
+    # @param params [Hash] The parameter substitutions, including optional `:method`.
+    # @option params [Symbol, String] :method (:post) The HTTP method.
+    # @return [String] The HTML form markup.
     def button_to(name, text, params = {})
-      local_params = params ? params.dup : {}
-      method = local_params.delete(:method) || :post
+      params_copy = params ? params.dup : {}
+      method = params_copy.delete(:method) || :post
       method = method.to_s.downcase
-      path = path_to(name, local_params)
+      path = path_to(name, params_copy)
+      form_method = method == 'get' ? 'get' : 'post'
+      build_form_html(path, form_method, method, text)
+    end
+
+    # Build a simple redirect structure (framework adapter can translate).
+    #
+    # @param name [Symbol, String] The route name.
+    # @param params [Hash] The parameter substitutions.
+    # @return [Hash] A hash containing the redirect status and location.
+    def redirect_to(name, params = {})
+      path = path_to(name, params)
+      { status: 302, location: path }
+    end
 
-      # HTML forms only support GET and POST
-      # For other methods, use POST with _method hidden field
-      form_method = (method == 'get') ? 'get' : 'post'
+    private
 
-      safe_path = CGI.escapeHTML(path.to_s)
-      safe_form_method = CGI.escapeHTML(form_method)
-      html = "<form action=\"#{safe_path}\" method=\"#{safe_form_method}\">"
+    # Build the form HTML.
+    #
+    # @param path [String] The form action path.
+    # @param form_method [String] The form method (e.g., "get" or "post").
+    # @param method [String] The HTTP method (e.g., "put" or "delete").
+    # @param text [String] The button label.
+    # @return [String] The HTML form markup.
+    def build_form_html(path, form_method, method, text)
+      escaped_path = CGI.escapeHTML(path.to_s)
+      escaped_form_method = CGI.escapeHTML(form_method)
+      form_html = "<form action=\"#{escaped_path}\" method=\"#{escaped_form_method}\">"
 
-      # Add _method hidden field for non-GET/POST methods
       if method != 'get' && method != 'post'
-        safe_method = CGI.escapeHTML(method)
-        html += "<input type=\"hidden\" name=\"_method\" value=\"#{safe_method}\">"
+        escaped_method = CGI.escapeHTML(method)
+        form_html += "<input type=\"hidden\" name=\"_method\" value=\"#{escaped_method}\">"
       end
 
-      safe_text = CGI.escapeHTML(text.to_s)
-      html += "<button type=\"submit\">#{safe_text}</button>"
-      html += "</form>"
-      html
-    end
-
-    def redirect_to(name, params = {})
-      path = path_to(name, params)
-      { status: 302, location: path }
+      escaped_text = CGI.escapeHTML(text.to_s)
+      form_html + "<button type=\"submit\">#{escaped_text}</button></form>"
     end
   end
 end

data/lib/ruby_routes/utility/inflector_utility.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RubyRoutes
+  module Utility
+    # InflectorUtility
+    #
+    # Minimal internal pluralize/singularize (same logic as before).
+    # Not a full linguistic inflector; avoid exposing publicly.
+    module InflectorUtility
+      module_function
+
+      def singularize(str)
+        return '' if str.nil?
+
+        case str
+        when /ies$/ then str.sub(/ies$/, 'y')
+        when /s$/   then str.sub(/s$/, '')
+        else str
+        end
+      end
+
+      def pluralize(str)
+        return '' if str.nil?
+
+        case str
+        when /y$/          then str.sub(/y$/, 'ies')
+        when /(sh|ch|x)$/  then "#{str}es"
+        when /z$/          then "#{str}zes"
+        when /s$/          then str
+        else                    "#{str}s"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_routes/utility/key_builder_utility.rb

@@ -1,101 +1,195 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Utility
+    # KeyBuilderUtility
+    #
+    # High‑performance helpers for building and reusing cache keys:
+    # 1. Request recognition keys ("METHOD:PATH") via a per‑method nested
+    #    hash plus a fixed‑size ring buffer for eviction.
+    # 2. Parameter combination keys for path generation (ordered values of
+    #    required params, pipe + slash delimited) with thread‑local String
+    #    buffers to avoid intermediate allocations.
+    #
+    # Design goals:
+    # - Zero garbage on hot cache hits.
+    # - Bounded memory (REQUEST_KEY_CAPACITY ring).
+    # - Thread-safe for concurrent access across multiple threads.
     module KeyBuilderUtility
-      # ------------------------------------------------------------------
-      # Fast reusable key storage for "METHOD:PATH" strings.
-      # O(1) insert + O(1) eviction using a fixed-size ring buffer.
-      # Only allocates a new String on the *first* time a (method,path) pair appears.
-      # ------------------------------------------------------------------
-      REQUEST_KEY_CAPACITY = 4096
-
-      @pool      = {}                        # { method_string => { path_string => frozen_key_string } }
-      @ring      = Array.new(REQUEST_KEY_CAPACITY) # ring entries: [method_string, path_string]
-      @ring_pos  = 0
-      @entry_cnt = 0
+      # @!visibility private
+      # { "GET" => { "/users" => "GET:/users" } }
+      @request_key_pool = {}
+      # @!visibility private
+      # Circular buffer holding [method_string, path_string] tuples to evict.
+      @request_key_ring = Array.new(RubyRoutes::Constant::REQUEST_KEY_CAPACITY)
+      # @!visibility private
+      @ring_index  = 0
+      # @!visibility private
+      @entry_count = 0
+      # @!visibility private
+      @mutex = Mutex.new
 
       class << self
-        attr_reader :pool
-        def fetch_request_key(method, path)
-          # Method & path must be strings already (callers ensure)
-          if (paths = @pool[method])
-            if (key = paths[path])
-              return key
-            end
+        # Clear all cached request keys.
+        #
+        # @return [void]
+        def clear!
+          @mutex.synchronize do
+            @request_key_pool.clear
+            @request_key_ring.fill(nil)
+            @entry_count = 0
+            @ring_index = 0
           end
+        end
 
-            # MISS: build & freeze once
-          key = "#{method}:#{path}".freeze
-          if paths
-            paths[path] = key
-          else
-            @pool[method] = { path => key }
-          end
+        # Fetch (or create) a frozen "METHOD:PATH" composite key.
+        #
+        # On miss:
+        # - Builds the String once.
+        # - Records it in the nested pool.
+        # - Tracks insertion in a fixed ring; when full, overwrites oldest.
+        #
+        # @param http_method [String] The HTTP method (e.g., "GET").
+        # @param request_path [String] The request path (e.g., "/users").
+        # @return [String] A frozen canonical key.
+        def fetch_request_key(http_method, request_path)
+          @mutex.synchronize do
+            method_key, path_key = prepare_keys(http_method, request_path)
 
-          # Evict if ring full (overwrite oldest slot)
-          if @entry_cnt < REQUEST_KEY_CAPACITY
-            @ring[@entry_cnt] = [method, path]
-            @entry_cnt += 1
-          else
-            ev_m, ev_p = @ring[@ring_pos]
-            bucket = @pool[ev_m]
-            if bucket&.delete(ev_p) && bucket.empty?
-              @pool.delete(ev_m)
-            end
-            @ring[@ring_pos] = [method, path]
-            @ring_pos += 1
-            @ring_pos = 0 if @ring_pos == REQUEST_KEY_CAPACITY
+            bucket = @request_key_pool[method_key] ||= {}
+            return bucket[path_key] if bucket[path_key]
+
+            handle_cache_miss(bucket, method_key, path_key)
           end
+        end
 
-          key
+        private
+
+        # Prepare keys by freezing them if necessary.
+        #
+        # @param http_method [String] The HTTP method.
+        # @param request_path [String] The request path.
+        # @return [Array<String>] An array containing the frozen method and path keys.
+        def prepare_keys(http_method, request_path)
+          method_key = http_method.frozen? ? http_method : http_method.dup.freeze
+          path_key = request_path.frozen? ? request_path : request_path.dup.freeze
+          [method_key, path_key]
+        end
+
+        # Handle a cache miss by creating a composite key and updating the ring buffer.
+        #
+        # @param bucket [Hash] The bucket for the method key.
+        # @param method_key [String] The HTTP method key.
+        # @param path_key [String] The path key.
+        # @return [String] The composite key.
+        def handle_cache_miss(bucket, method_key, path_key)
+          composite = "#{method_key}:#{path_key}".freeze
+          bucket[path_key] = composite
+          handle_ring_buffer(method_key, path_key)
+          composite
+        end
+
+        # Handle the ring buffer for eviction.
+        #
+        # @param method_key [String] The HTTP method key.
+        # @param path_key [String] The path key.
+        # @return [void]
+        def handle_ring_buffer(method_key, path_key)
+          evict_old_entry if @entry_count >= RubyRoutes::Constant::REQUEST_KEY_CAPACITY
+          add_to_ring_buffer(method_key, path_key)
         end
-      end
 
-      # ------------------------------------------------------------------
-      # Public helpers mixed into instances
-      # ------------------------------------------------------------------
-
-      # Generic key (rarely hot): joins parts with delim; single allocation.
-      def build_key(parts, delim = ':')
-        return ''.freeze if parts.empty?
-        buf = Thread.current[:ruby_routes_key_buf] ||= String.new
-        buf.clear
-        i = 0
-        while i < parts.length
-          buf << delim unless i.zero?
-          buf << parts[i].to_s
-          i += 1
+        # Add a key to the ring buffer.
+        #
+        # @param method_key [String] The HTTP method key.
+        # @param path_key [String] The path key.
+        # @return [void]
+        def add_to_ring_buffer(method_key, path_key)
+          @request_key_ring[@ring_index] = [method_key, path_key]
+          @ring_index = (@ring_index + 1) % RubyRoutes::Constant::REQUEST_KEY_CAPACITY
+          @entry_count += 1 if @entry_count < RubyRoutes::Constant::REQUEST_KEY_CAPACITY
         end
-        buf.dup
+
+        # Evict the oldest entry from the ring buffer.
+        #
+        # @return [void]
+        def evict_old_entry
+          old_method, old_path = @request_key_ring[@ring_index]
+          old_method_bucket = @request_key_pool[old_method]
+          return unless old_method_bucket
+
+          old_method_bucket.delete(old_path)
+          @request_key_pool.delete(old_method) if old_method_bucket.empty?
+        end
+      end
+
+      # Build a generic delimited key from components (non‑hot path).
+      #
+      # Simple join; acceptable for non‑hot paths.
+      #
+      # @param components [Array<#to_s>] The components to join into a key.
+      # @param delimiter [String] The separator (default is ':').
+      # @return [String] A frozen key string.
+      def build_key(components, delimiter = ':')
+        return RubyRoutes::Constant::EMPTY_STRING if components.empty?
+
+        components.map(&:to_s).join(delimiter).freeze
       end
 
-      # HOT: request cache key (reused frozen interned string)
-      def cache_key_for_request(method, path)
-        KeyBuilderUtility.fetch_request_key(method, path.to_s)
+      # Return (intern/reuse) a composite request key.
+      #
+      # @param http_method [String] The HTTP method.
+      # @param path [String] The request path.
+      # @return [String] A frozen "METHOD:PATH" key.
+      def cache_key_for_request(http_method, path)
+        KeyBuilderUtility.fetch_request_key(http_method, path.to_s)
       end
 
-      # HOT: params key – produces a short-lived String (dup, not re-frozen each time).
-      # Callers usually put it into an LRU that duplicates again, so keep it lean.
+      # Build a cache key from required params and a merged hash in order.
+      #
+      # Format: "val1|val2/subA/subB|val3".
+      #
+      # @param required_params [Array<String>] The required parameter keys.
+      # @param merged [Hash{String=>Object}] The merged parameters.
+      # @return [String] A frozen key (empty if none required).
       def cache_key_for_params(required_params, merged)
-        return ''.freeze if required_params.nil? || required_params.empty?
-        buf = Thread.current[:ruby_routes_param_key_buf] ||= String.new
-        buf.clear
-        i = 0
-        while i < required_params.length
-          buf << '|' unless i.zero?
-          v = merged[required_params[i]]
-          if v.is_a?(Array)
-            j = 0
-            while j < v.length
-              buf << '/' unless j.zero?
-              buf << v[j].to_s
-              j += 1
-            end
+        return RubyRoutes::Constant::EMPTY_STRING if required_params.nil? || required_params.empty?
+
+        buffer = Thread.current[:ruby_routes_param_key_buf] ||= String.new
+        buffer.clear
+        build_param_key_buffer(required_params, merged, buffer)
+        buffer.dup.freeze
+      end
+
+      # Build the parameter key buffer.
+      #
+      # @param required_params [Array<String>] The required parameter keys.
+      # @param merged [Hash] The merged parameters.
+      # @param buffer [String] The buffer to build the key into.
+      # @return [void]
+      def build_param_key_buffer(required_params, merged, buffer)
+        first = true
+        required_params.each do |param|
+          value = format_param_value(merged[param])
+          if first
+            buffer << value
+            first = false
           else
-            buf << v.to_s
+            buffer << '|' << value
           end
-          i += 1
         end
-        buf.dup
+      end
+
+      # Format a parameter value for inclusion in the key.
+      #
+      # @param param_value [Object] The parameter value.
+      # @return [String] The formatted parameter value.
+      def format_param_value(param_value)
+        if param_value.is_a?(Array)
+          param_value.join('/')
+        else
+          param_value.to_s
+        end
       end
     end
   end