ruby_routes 2.2.0 → 2.3.0

data/lib/ruby_routes/utility/method_utility.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative '../constant'
+
+module RubyRoutes
+  module Utility
+    # MethodUtility
+    #
+    # High‑performance HTTP method normalization avoiding core
+    # `String#upcase` allocations. Supports `String`, `Symbol`, and
+    # arbitrary objects (coerced via `#to_s`).
+    #
+    # Features:
+    # - Zero cost for already‑uppercase ASCII strings (fast scan).
+    # - Manual ASCII uppercasing (single pass) for `a–z` only.
+    # - Symbol fast path via interned constant map (`SYMBOL_MAP`).
+    # - Cache (`METHOD_CACHE`) for uncommon verbs or dynamic inputs.
+    #
+    # Thread Safety:
+    # - `METHOD_CACHE` is a shared `Hash`; occasional benign race
+    #   (double compute of the same key) is acceptable. If strict
+    #   thread safety is required, wrap in a `Mutex` (not done to
+    #   preserve performance).
+    #
+    # @api internal
+    module MethodUtility
+      # Pre‑interned canonical uppercase strings for common verbs.
+      #
+      # @return [Hash{Symbol => String}]
+      SYMBOL_MAP = {
+        get: RubyRoutes::Constant::HTTP_GET,
+        post: RubyRoutes::Constant::HTTP_POST,
+        put: RubyRoutes::Constant::HTTP_PUT,
+        patch: RubyRoutes::Constant::HTTP_PATCH,
+        delete: RubyRoutes::Constant::HTTP_DELETE,
+        head: RubyRoutes::Constant::HTTP_HEAD,
+        options: RubyRoutes::Constant::HTTP_OPTIONS
+      }.freeze
+
+      # Cache for non‑predefined or previously seen method tokens.
+      # Keys: original `String` or `Symbol`
+      # Values: frozen uppercase `String`
+      #
+      # Note: This is intentionally mutable for caching purposes.
+      #
+      # @return [Hash{(String,Symbol) => String}]
+      # rubocop:disable Style/MutableConstant
+      METHOD_CACHE = {} # Intentionally mutable for caching
+      # rubocop:enable Style/MutableConstant
+
+      # Normalize an HTTP method‑like input to a canonical uppercase `String`.
+      #
+      # Fast paths:
+      # - Uppercase ASCII `String`: returned as‑is (no dup/freeze).
+      # - `Symbol` in `SYMBOL_MAP`: constant returned.
+      #
+      # Slow path:
+      # - Manual ASCII uppercasing (only `a–z`) + cached.
+      #
+      # @param method_input [String, Symbol, #to_s] The HTTP method input.
+      # @return [String] Canonical uppercase representation.
+      #   (Cached/transformed values are frozen; uppercase fast-path may return the original `String`.)
+      def normalize_http_method(method_input)
+        case method_input
+        when String
+          normalize_string_method(method_input)
+        when Symbol
+          normalize_symbol_method(method_input)
+        else
+          normalize_other_method(method_input)
+        end
+      end
+
+      private
+
+      # Normalize a `String` HTTP method.
+      #
+      # @param method_input [String] The HTTP method input.
+      # @return [String] The normalized HTTP method.
+      def normalize_string_method(method_input)
+        key = method_input
+        return key if already_upper_ascii?(key)
+
+        METHOD_CACHE[key] ||= ascii_upcase(key).freeze
+      end
+
+      # Normalize a `Symbol` HTTP method.
+      #
+      # @param method_input [Symbol] The HTTP method input.
+      # @return [String] The normalized HTTP method.
+      def normalize_symbol_method(method_input)
+        SYMBOL_MAP[method_input] || (METHOD_CACHE[method_input] ||= ascii_upcase(method_input.to_s).freeze)
+      end
+
+      # Normalize an arbitrary HTTP method input.
+      #
+      # @param method_input [#to_s] The HTTP method input.
+      # @return [String] The normalized HTTP method.
+      def normalize_other_method(method_input)
+        coerced = method_input.to_s
+        key = coerced
+        return key if already_upper_ascii?(key)
+
+        METHOD_CACHE[key] ||= ascii_upcase(key).freeze
+      end
+
+      # Determine if a `String` consists solely of uppercase ASCII (`A–Z`) or non‑letters.
+      #
+      # @param candidate [String] The string to check.
+      # @return [Boolean] `true` if the string is already uppercase ASCII, `false` otherwise.
+      def already_upper_ascii?(candidate)
+        candidate.each_byte { |char_code| return false if char_code >= 97 && char_code <= 122 } # a-z
+        true
+      end
+
+      # Convert only ASCII lowercase letters (`a–z`) to uppercase in a single pass.
+      #
+      # Returns the original `String` when no changes are needed to avoid allocation.
+      #
+      # @param original [String] The original string.
+      # @return [String] Either the original or a newly packed transformed string.
+      def ascii_upcase(original)
+        byte_array = original.bytes
+        any_lowercase_transformed = false
+        byte_array.each_with_index do |char_code, idx|
+          if char_code >= 97 && char_code <= 122
+            byte_array[idx] = char_code - 32
+            any_lowercase_transformed = true
+          end
+        end
+        return original unless any_lowercase_transformed
+
+        byte_array.pack('C*')
+      end
+    end
+  end
+end

data/lib/ruby_routes/utility/path_utility.rb

@@ -1,41 +1,88 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Utility
+    # PathUtility
+    #
+    # Low‑allocation helpers for normalizing and manipulating URL path
+    # strings used during route definition, recognition, and generation.
+    #
+    # @note Design goals:
+    #   - Idempotent normalization: ensure a single leading slash and trim one
+    #     trailing slash (except for root).
+    #   - Internal duplicate slashes are tolerated by `normalize_path`; `split_path`
+    #     collapses empty segments; `join_path_parts` never produces duplicate
+    #     separators
+    #
+    # @note Thread safety: stateless (all methods pure).
+    #
+    # @api internal
     module PathUtility
-      ROOT_PATH = '/'.freeze
-
-      def normalize_path(path)
-        path = path.to_s
-        # Add leading slash if missing
-        path = '/' + path unless path.start_with?('/')
-        # Remove trailing slash if present (unless root)
-        path = path[0..-2] if path.length > 1 && path.end_with?('/')
-        path
+      # Normalize a raw path string.
+      #
+      # Rules:
+      # - Ensures a leading slash.
+      # - Removes a trailing slash (except when the path is exactly "/").
+      #
+      # @param raw_path [String, #to_s]
+      # @return [String] normalized path (may be the same object if unchanged)
+      #
+      # @example
+      #   normalize_path('users/')   # => "/users"
+      #   normalize_path('/users')   # => "/users"
+      #   normalize_path('/')        # => "/"
+      def normalize_path(raw_path)
+        normalized_path = raw_path.to_s
+        normalized_path = "/#{normalized_path}" unless normalized_path.start_with?('/')
+        normalized_path = normalized_path[0..-2] if normalized_path.length > 1 && normalized_path.end_with?('/')
+        normalized_path
       end
 
-      def split_path(path)
-        # Remove query string before splitting
-        path = path.split('?', 2).first
-        path = path[1..-1] if path.start_with?('/')
-        path = path[0...-1] if path.end_with?('/') && path != ROOT_PATH
-        path.empty? ? [] : path.split('/')
+      # Normalize HTTP method to uppercase String (fast path).
+      #
+      # @param method [String, Symbol]
+      # @return [String]
+      def normalize_method(method)
+        method.to_s.upcase
       end
 
-      def join_path_parts(parts)
-        # Pre-calculate the size to avoid buffer resizing
-        size = parts.sum { |p| p.length + 1 } # +1 for slash
+      # Split a path into its component segments (excluding leading/trailing slash
+      # and any query string). Returns an empty Array for root.
+      #
+      # @param raw_path [String]
+      # @return [Array<String>] segments without empty elements
+      #
+      # @example
+      #   split_path('/users/123?x=1') # => ["users", "123"]
+      #   split_path('/')              # => []
+      def split_path(raw_path)
+        path_without_query = raw_path.to_s.split(/[?#]/, 2).first
+        return [] if path_without_query.nil? || path_without_query.empty?
 
-        # Use string buffer for better performance
-        result = String.new(capacity: size)
-        result << '/'
+        path_without_query.split('/').reject(&:empty?)
+      end
 
-        # Join with explicit concatenation rather than array join
-        last_idx = parts.size - 1
-        parts.each_with_index do |part, i|
-          result << part
-          result << '/' unless i == last_idx
+      # Join path parts into a normalized absolute path.
+      #
+      # Allocation minimization:
+      # - Precomputes total size to preallocate destination String.
+      # - Appends with manual slash insertion.
+      #
+      # @param path_parts [Array<String>]
+      # @return [String] absolute path beginning with '/'
+      #
+      # @example
+      #   join_path_parts(%w[users 123]) # => "/users/123"
+      def join_path_parts(path_parts)
+        estimated_path_size = path_parts.sum { |path_part| path_part.length + 1 } # +1 per slash
+        path_buffer = String.new(capacity: estimated_path_size)
+        path_buffer << '/'
+        last_part_index = path_parts.size - 1
+        path_parts.each_with_index do |path_part, part_index|
+          path_buffer << path_part
+          path_buffer << '/' unless part_index == last_part_index
         end
-
-        result
+        path_buffer
       end
     end
   end

data/lib/ruby_routes/utility/route_utility.rb

@@ -1,17 +1,45 @@
+# frozen_string_literal: true
+
 module RubyRoutes
   module Utility
+    # RouteUtility
+    #
+    # Internal DSL helper used by Router / RouteSet to construct and
+    # register Route objects. It abstracts the two primary entry points:
+    #
+    # - #define: Build a new Route from a path + options hash and add it.
+    # - #register: Add an already-instantiated Route.
+    #
+    # This separation lets higher-level DSL code remain concise while
+    # keeping RouteSet mutation logic centralized.
+    #
+    # Thread safety: Not thread-safe; expected to be called during
+    # application boot / configuration phase.
+    #
+    # @api internal
     class RouteUtility
+      # @param route_set [RubyRoutes::RouteSet]
       def initialize(route_set)
         @route_set = route_set
       end
 
-      # DSL wants to merge scope, RouteSet wants to add a pre‐built Route,
-      # so we offer two entry points:
+      # Build and register a new Route.
+      #
+      # @param path [String]
+      # @param options [Hash] route definition options
+      # @return [RubyRoutes::Route]
+      #
+      # @example
+      #   util.define('/users/:id', via: :get, to: 'users#show', as: :user)
       def define(path, options = {})
         route = Route.new(path, options)
         register(route)
       end
 
+      # Register an existing Route instance with the RouteSet.
+      #
+      # @param route [RubyRoutes::Route]
+      # @return [RubyRoutes::Route] the same route (for chaining)
       def register(route)
         @route_set.add_to_collection(route)
         route

data/lib/ruby_routes/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module RubyRoutes
-  VERSION = "2.2.0"
+  VERSION = '2.3.0'
 end

data/lib/ruby_routes.rb

@@ -1,25 +1,82 @@
-require_relative "ruby_routes/version"
-require_relative "ruby_routes/string_extensions"
-require_relative "ruby_routes/route"
-require_relative "ruby_routes/route_set"
-require_relative "ruby_routes/url_helpers"
-require_relative "ruby_routes/router"
-require_relative "ruby_routes/radix_tree"
-require_relative "ruby_routes/node"
+# frozen_string_literal: true
 
+require_relative 'ruby_routes/version'
+require_relative 'ruby_routes/constant'
+require_relative 'ruby_routes/string_extensions'
+require_relative 'ruby_routes/route'
+require_relative 'ruby_routes/route_set'
+require_relative 'ruby_routes/url_helpers'
+require_relative 'ruby_routes/router'
+require_relative 'ruby_routes/radix_tree'
+require_relative 'ruby_routes/node'
+require_relative 'ruby_routes/router/builder'
+
+# RubyRoutes
+#
+# RubyRoutes: High-performance, thread-safe routing DSL for Ruby applications.
+# Provides Rails-like route definitions, RESTful resources, constraints, path generation, and advanced caching.
+#
+# See README.md for usage, API, migration, and security notes.
+#
+# Responsibilities:
+# - Autoload and require all core components:
+#   - version, string_extensions, route, route_set, url_helpers, router, radix_tree, node, router/builder
+# - Provide `.draw` helper to build a finalized, immutable router.
+# - Expose version and convenience APIs for router creation.
+#
+# Thread-safety & Immutability:
+# - All loaded structures (constants, frozen route sets, caches) are safe for concurrent use.
+# - Modifications (route additions) are not thread-safe; always use `RubyRoutes.draw` in an initializer or at boot.
+# - After build/finalize, all internals are deeply frozen for safety.
+#
+# Security & Migration:
+# - Proc constraints are deprecated; see `MIGRATION_GUIDE.md` for secure alternatives.
+# - `RouteSet#match` returns frozen params; callers must `.dup` if mutation is needed.
+# - See `SECURITY_FIXES.md` for details on security improvements.
+#
+# Performance:
+# - Optimized for low memory usage, high cache hit rates, and zero memory leaks.
+# - See `README.md` for benchmark results.
+#
+# @api public
 module RubyRoutes
+  # Base error class for RubyRoutes-specific exceptions.
   class Error < StandardError; end
+
+  # Raised when a route cannot be found.
   class RouteNotFound < Error; end
+
+  # Raised when a route is invalid.
   class InvalidRoute < Error; end
+
+  # Raised when a constraint validation fails.
   class ConstraintViolation < Error; end
 
-  # Create a new router instance
+  # Create a new router instance.
+  #
+  # @example Define routes using a block
+  #   router = RubyRoutes.new do
+  #     get '/health', to: 'system#health'
+  #     resources :users
+  #   end
+  #
+  # @param block [Proc] The block defining the routes.
+  # @return [RubyRoutes::Router] A new router instance.
   def self.new(&block)
     RubyRoutes::Router.new(&block)
   end
 
-  # Define the routes using a block
+  # Define the routes using a block and return a finalized router.
+  #
+  # @example Define and finalize routes
+  #   router = RubyRoutes.draw do
+  #     get '/health', to: 'system#health'
+  #     resources :users
+  #   end
+  #
+  # @param block [Proc] The block defining the routes.
+  # @return [RubyRoutes::Router] A finalized router instance.
   def self.draw(&block)
-    RubyRoutes::Router.new(&block)
+    RubyRoutes::Router.build(&block)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_routes
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Yosef Benny Widyokarsono
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,19 +38,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rack
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -81,10 +81,28 @@ files:
 - lib/ruby_routes/lru_strategies/miss_strategy.rb
 - lib/ruby_routes/node.rb
 - lib/ruby_routes/radix_tree.rb
+- lib/ruby_routes/radix_tree/finder.rb
+- lib/ruby_routes/radix_tree/inserter.rb
 - lib/ruby_routes/route.rb
+- lib/ruby_routes/route/check_helpers.rb
+- lib/ruby_routes/route/constraint_validator.rb
+- lib/ruby_routes/route/param_support.rb
+- lib/ruby_routes/route/path_builder.rb
+- lib/ruby_routes/route/path_generation.rb
+- lib/ruby_routes/route/query_helpers.rb
+- lib/ruby_routes/route/segment_compiler.rb
 - lib/ruby_routes/route/small_lru.rb
+- lib/ruby_routes/route/validation_helpers.rb
+- lib/ruby_routes/route/warning_helpers.rb
 - lib/ruby_routes/route_set.rb
+- lib/ruby_routes/route_set/cache_helpers.rb
+- lib/ruby_routes/route_set/collection_helpers.rb
 - lib/ruby_routes/router.rb
+- lib/ruby_routes/router/build_helpers.rb
+- lib/ruby_routes/router/builder.rb
+- lib/ruby_routes/router/http_helpers.rb
+- lib/ruby_routes/router/resource_helpers.rb
+- lib/ruby_routes/router/scope_helpers.rb
 - lib/ruby_routes/segment.rb
 - lib/ruby_routes/segments/base_segment.rb
 - lib/ruby_routes/segments/dynamic_segment.rb
@@ -92,7 +110,9 @@ files:
 - lib/ruby_routes/segments/wildcard_segment.rb
 - lib/ruby_routes/string_extensions.rb
 - lib/ruby_routes/url_helpers.rb
+- lib/ruby_routes/utility/inflector_utility.rb
 - lib/ruby_routes/utility/key_builder_utility.rb
+- lib/ruby_routes/utility/method_utility.rb
 - lib/ruby_routes/utility/path_utility.rb
 - lib/ruby_routes/utility/route_utility.rb
 - lib/ruby_routes/version.rb