ruby_routes 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02d39aae113654256dae0905438ac98a540854a5d131dea6c4b2b606b51bf4ba
-  data.tar.gz: ba01a85fc21713387e76c183a41e786106f1a053e2485d294895ac36027d94a5
+  metadata.gz: 4017abab11dd0945bcfe1659b2ed1456c2cf82a8993db55d094d283c48c8ebd0
+  data.tar.gz: 07f0aba728bf81cdfdc245e20a212f1775b2314a826c88f0e25b8ff2b608c195
 SHA512:
-  metadata.gz: c3b230ef35186d4f96714ba708b933cf7897166a74b7162949a3144aa21dc79aab2446a0b14d1e0504ea30f941146a7e0f1841d5908e6a6175d771a9b4a658ad
-  data.tar.gz: 9d476bdbaf46cef516cd51adb218097137863fb12976e98d87a7c8d7f77e3609421d81ba14ed77d67cd59054d4356690d088b619e8e089964cd4fdd6055225ac
+  metadata.gz: a4aa77ba441b9e87cdcb31cae5b5f12babaf93396e400723d5f845392ac132520c4398e19d49d0755e05fc305791b54a3676a460ba8c73cd4b5ee55647fb2589
+  data.tar.gz: a3b883c253731dfad5eaf34a28fb89684d0f9fa921127f6e428225743a93d87934508e49f59c3710964cc8a444b729f9278872aa8d991c4302abbb7ff8645b66

data/README.md

@@ -8,7 +8,7 @@ A lightweight, flexible routing system for Ruby that provides a Rails-like DSL f
 - **HTTP Method Support**: GET, POST, PUT, PATCH, DELETE, and custom methods
 - **RESTful Resources**: Automatic generation of RESTful routes
 - **Nested Routes**: Support for nested resources and namespaces
-- **Route Constraints**: Add constraints to routes (regex, etc.)
+- **Secure Route Constraints**: Powerful constraint system with built-in security ([see CONSTRAINTS.md](CONSTRAINTS.md))
 - **Named Routes**: Generate URLs from route names
 - **Path Generation**: Build URLs with parameters
 - **Scope Support**: Group routes with common options
@@ -62,7 +62,6 @@ end
 ```
 
 This creates the following routes:
-
 - `GET /users` → `users#index`
 - `GET /users/new` → `users#new`
 - `POST /users` → `users#create`
@@ -117,14 +116,91 @@ end
 # etc.
 ```
 
-### Scopes and Constraints
+### Route Constraints
+
+Ruby Routes provides a powerful and secure constraint system to validate route parameters. **For security reasons, Proc constraints are deprecated** - use the secure alternatives below.
+
+#### Built-in Constraint Types
 
 ```ruby
 router = RubyRoutes.draw do
-  scope constraints: { id: /\d+/ } do
-    get '/users/:id', to: 'users#show'
-  end
+  # Integer validation
+  get '/users/:id', to: 'users#show', constraints: { id: :int }
+  
+  # UUID validation
+  get '/resources/:uuid', to: 'resources#show', constraints: { uuid: :uuid }
   
+  # Email validation
+  get '/users/:email', to: 'users#show', constraints: { email: :email }
+  
+  # URL-friendly slug validation
+  get '/posts/:slug', to: 'posts#show', constraints: { slug: :slug }
+  
+  # Alphabetic characters only
+  get '/categories/:name', to: 'categories#show', constraints: { name: :alpha }
+  
+  # Alphanumeric characters only
+  get '/codes/:code', to: 'codes#show', constraints: { code: :alphanumeric }
+end
+```
+
+#### Hash-based Constraints (Recommended)
+
+```ruby
+router = RubyRoutes.draw do
+  # Length constraints
+  get '/users/:username', to: 'users#show',
+      constraints: { 
+        username: { 
+          min_length: 3, 
+          max_length: 20,
+          format: /\A[a-zA-Z0-9_]+\z/
+        } 
+      }
+
+  # Allowed values (whitelist)
+  get '/posts/:status', to: 'posts#show',
+      constraints: { 
+        status: { in: %w[draft published archived] }
+      }
+
+  # Numeric ranges
+  get '/products/:price', to: 'products#show',
+      constraints: { 
+        price: { range: 1..10000 }
+      }
+end
+```
+
+#### Regular Expression Constraints
+
+```ruby
+router = RubyRoutes.draw do
+  # Custom regex pattern (with ReDoS protection)
+  get '/products/:sku', to: 'products#show', 
+      constraints: { sku: /\A[A-Z]{2}\d{4}\z/ }
+end
+```
+
+#### ⚠️ Security Notice: Proc Constraints Deprecated
+
+```ruby
+# ❌ DEPRECATED - Security risk!
+get '/users/:id', to: 'users#show',
+    constraints: { id: ->(value) { value.to_i > 0 } }
+
+# ✅ Use secure alternatives instead:
+get '/users/:id', to: 'users#show',
+    constraints: { id: { range: 1..Float::INFINITY } }
+```
+
+**📚 For complete constraint documentation, see [CONSTRAINTS.md](CONSTRAINTS.md)**  
+**🔄 For migration help, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)**
+
+### Scopes
+
+```ruby
+router = RubyRoutes.draw do
   scope defaults: { format: 'html' } do
     get '/posts', to: 'posts#index'
   end
@@ -274,13 +350,38 @@ Creates a new router instance and yields to the block for route definition.
 - `find_route(method, path)` - Finds a specific route
 - `find_named_route(name)` - Finds a named route
 
-## Examples
+## Documentation
+
+### Core Documentation
+- **[CONSTRAINTS.md](CONSTRAINTS.md)** - Complete guide to route constraints and security best practices
+- **[MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)** - Step-by-step guide for migrating from deprecated Proc constraints
+
+### Examples
 
 See the `examples/` directory for more detailed examples:
 
 - `examples/basic_usage.rb` - Basic routing examples
 - `examples/rack_integration.rb` - Full Rack application example
 
+## Security
+
+Ruby Routes prioritizes security and has implemented several protections:
+
+### 🔒 Security Features
+- **XSS Protection**: All HTML output is properly escaped
+- **ReDoS Protection**: Regular expression constraints have timeout protection
+- **Secure Constraints**: Deprecated dangerous Proc constraints in favor of secure alternatives
+- **Thread Safety**: All caching and shared resources are thread-safe
+- **Input Validation**: Comprehensive parameter validation before reaching application code
+
+### ⚠️ Important Security Notice
+**Proc constraints are deprecated due to security risks** and will be removed in a future version. They allow arbitrary code execution which can be exploited for:
+- Code injection attacks
+- Denial of service attacks
+- System compromise
+
+**Migration Required**: If you're using Proc constraints, please migrate to secure alternatives using our [Migration Guide](MIGRATION_GUIDE.md).
+
 ## Testing
 
 Run the test suite:
@@ -289,6 +390,8 @@ Run the test suite:
 bundle exec rspec
 ```
 
+The test suite includes comprehensive security tests to ensure all protections are working correctly.
+
 ## Contributing
 
 1. Fork the repository

data/lib/ruby_routes/constant.rb

@@ -42,9 +42,9 @@ module RubyRoutes
 
     # Descriptor factories for segment classification (O(1) dispatch by first byte).
     DESCRIPTOR_FACTORIES = {
-      42 => ->(s) { { type: :splat,  name: (s[1..-1] || 'splat') } }, # '*'
-      58 => ->(s) { { type: :param,  name:   s[1..-1] } },             # ':'
-      :default => ->(s) { { type: :static, value:  s } }
+      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
     }.freeze
 
     def self.segment_descriptor(raw)

data/lib/ruby_routes/node.rb

@@ -14,43 +14,52 @@ module RubyRoutes
       @is_endpoint = false
     end
 
-    # Traverse for a single segment using the matcher registry.
+    # Fast traversal: minimal allocations, streamlined branching
     # Returns [next_node_or_nil, should_break_bool] or [nil, false] if no match.
     def traverse_for(segment, index, segments, params)
-      # Prefer static children first (exact match).
-      if @static_children.key?(segment)
-        return [@static_children[segment], false]
-      end
+      # Static match: O(1) hash lookup
+      child = @static_children[segment]
+      return [child, false] if child
 
-      # Then dynamic param child (single segment)
-      if @dynamic_child
-        next_node = @dynamic_child
-        if params
-          params[next_node.param_name.to_s] = segment
-        end
-        return [next_node, false]
+      # Dynamic match: single segment capture
+      if (dyn = @dynamic_child)
+        params[dyn.param_name] = segment if params
+        return [dyn, false]
       end
 
-      # Then wildcard child (consume remainder)
-      if @wildcard_child
-        next_node = @wildcard_child
+      # Wildcard match: consume remainder (last resort)
+      if (wild = @wildcard_child)
         if params
-          params[next_node.param_name.to_s] = segments[index..-1].join('/')
+          # Build remainder path without intermediate array allocation
+          remainder = segments[index..-1]
+          params[wild.param_name] = remainder.size == 1 ? remainder[0] : remainder.join('/')
         end
-        return [next_node, true]
+        return [wild, true]
       end
 
-      # No match at this node
+      # No match
       [nil, false]
     end
 
+    # Pre-cache param names as strings to avoid repeated .to_s calls
+    def param_name
+      @param_name_str ||= @param_name&.to_s
+    end
+
+    def param_name=(name)
+      @param_name = name
+      @param_name_str = nil  # invalidate cache
+    end
+
+    # Normalize method once and cache string keys
     def add_handler(method, handler)
-      @handlers[method.to_s] = handler
+      method_key = method.to_s.upcase
+      @handlers[method_key] = handler
       @is_endpoint = true
     end
 
     def get_handler(method)
-      @handlers[method.to_s]
+      @handlers[method]  # assume already normalized upstream
     end
   end
 end

data/lib/ruby_routes/radix_tree.rb

@@ -4,12 +4,8 @@ module RubyRoutes
   class RadixTree
     class << self
       # Allow RadixTree.new(path, options...) to act as a convenience factory
-      # returning a Route (this matches test usage where specs call
-      # RadixTree.new('/path', to: 'controller#action')).
-      # Calling RadixTree.new with no arguments returns an actual RadixTree instance.
       def new(*args, &block)
         if args.any?
-          # Delegate to Route initializer when args are provided
           RubyRoutes::Route.new(*args, &block)
         else
           super()
@@ -19,47 +15,85 @@ module RubyRoutes
 
     def initialize
       @root = Node.new
-      @_split_cache = {}           # simple LRU: key -> [value, age]
-      @split_cache_order = []      # track order for eviction
-      @split_cache_max = 1024
+      @split_cache = {}
+      @split_cache_order = []
+      @split_cache_max = 2048      # larger cache for better hit rates
+      @empty_segments = [].freeze  # reuse for root path
     end
 
     def add(path, methods, handler)
       current = @root
-      parse_segments(path).each do |seg|
+      segments = split_path_raw(path)
+
+      segments.each do |raw_seg|
+        seg = RubyRoutes::Segment.for(raw_seg)
         current = seg.ensure_child(current)
         break if seg.wildcard?
       end
 
-      methods.each { |method| current.add_handler(method, handler) }
-    end
-
-    def parse_segments(path)
-      split_path(path).map { |s| RubyRoutes::Segment.for(s) }
+      # Normalize methods once during registration
+      Array(methods).each { |method| current.add_handler(method.to_s.upcase, handler) }
     end
 
     def find(path, method, params_out = nil)
-      segments = split_path(path)
+      # Fast path: root route
+      if path == '/' || path.empty?
+        handler = @root.get_handler(method)
+        if @root.is_endpoint && handler
+          return [handler, params_out || {}]
+        else
+          return [nil, {}]
+        end
+      end
+
+      segments = split_path_cached(path)
       current = @root
       params = params_out || {}
       params.clear if params_out
 
-      segments.each_with_index do |text, idx|
-        next_node, should_break = current.traverse_for(text, idx, segments, params)
+      # Unrolled traversal for common case (1-3 segments)
+      case segments.size
+      when 1
+        next_node, _ = current.traverse_for(segments[0], 0, segments, params)
+        current = next_node
+      when 2
+        next_node, should_break = current.traverse_for(segments[0], 0, segments, params)
+        return [nil, {}] unless next_node
+        current = next_node
+        unless should_break
+          next_node, _ = current.traverse_for(segments[1], 1, segments, params)
+          current = next_node
+        end
+      when 3
+        next_node, should_break = current.traverse_for(segments[0], 0, segments, params)
         return [nil, {}] unless next_node
         current = next_node
-        break if should_break
+        unless should_break
+          next_node, should_break = current.traverse_for(segments[1], 1, segments, params)
+          return [nil, {}] unless next_node
+          current = next_node
+          unless should_break
+            next_node, _ = current.traverse_for(segments[2], 2, segments, params)
+            current = next_node
+          end
+        end
+      else
+        # General case for longer paths
+        segments.each_with_index do |text, idx|
+          next_node, should_break = current.traverse_for(text, idx, segments, params)
+          return [nil, {}] unless next_node
+          current = next_node
+          break if should_break
+        end
       end
 
+      return [nil, {}] unless current
       handler = current.get_handler(method)
       return [nil, {}] unless current.is_endpoint && handler
 
-      # lightweight constraint checks: reject early if route constraints don't match
-      route = handler
-      if route.respond_to?(:constraints) && route.constraints.any?
-        unless constraints_match?(route.constraints, params)
-          return [nil, {}]
-        end
+      # Fast constraint check
+      if handler.respond_to?(:constraints) && !handler.constraints.empty?
+        return [nil, {}] unless constraints_match_fast(handler.constraints, params)
       end
 
       [handler, params]
@@ -67,34 +101,48 @@ module RubyRoutes
 
     private
 
-    # faster, lower-allocation trim + split
-    def split_path(path)
-      @split_cache ||= {}
-      return [''] if path == '/'
+    # Cached path splitting with optimized common cases
+    def split_path_cached(path)
+      return @empty_segments if path == '/' || path.empty?
+
       if (cached = @split_cache[path])
         return cached
       end
 
-      p = path
-      p = p[1..-1] if p.start_with?('/')
-      p = p[0...-1] if p.end_with?('/')
-      segs = p.split('/')
+      result = split_path_raw(path)
 
-      # simple LRU insert
-      @split_cache[path] = segs
+      # Cache with simple LRU eviction
+      @split_cache[path] = result
       @split_cache_order << path
       if @split_cache_order.size > @split_cache_max
         oldest = @split_cache_order.shift
         @split_cache.delete(oldest)
       end
 
-      segs
+      result
+    end
+
+    # Raw path splitting without caching (for registration)
+    def split_path_raw(path)
+      return [] if path == '/' || path.empty?
+
+      # Optimized trimming: avoid string allocations when possible
+      start_idx = path.start_with?('/') ? 1 : 0
+      end_idx = path.end_with?('/') ? -2 : -1
+
+      if start_idx == 0 && end_idx == -1
+        path.split('/')
+      else
+        path[start_idx..end_idx].split('/')
+      end
     end
 
-    # constraints match helper (non-raising, lightweight)
-    def constraints_match?(constraints, params)
+    # Optimized constraint matching with fast paths
+    def constraints_match_fast(constraints, params)
       constraints.each do |param, constraint|
-        value = params[param.to_s] || params[param]
+        # Try both string and symbol keys (common pattern)
+        value = params[param.to_s]
+        value ||= params[param] if param.respond_to?(:to_s)
         next unless value
 
         case constraint
@@ -102,15 +150,16 @@ module RubyRoutes
           return false unless constraint.match?(value)
         when Proc
           return false unless constraint.call(value)
+        when :int
+          # Fast integer check without regex
+          return false unless value.is_a?(String) && value.match?(/\A\d+\z/)
+        when :uuid
+          # Fast UUID check
+          return false unless value.is_a?(String) && value.length == 36 &&
+                             value.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 Symbol
-          case constraint
-          when :int then return false unless value.match?(/^\d+$/)
-          when :uuid then return false unless value.match?(/^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/i)
-          else
-            # unknown symbol constraint — be conservative and allow
-          end
-        else
-          # unknown constraint type — allow (Route will validate later if needed)
+          # Handle other symbolic constraints
+          next  # unknown symbol constraint — allow
         end
       end
       true