otto 2.0.0.pre2 → 2.0.0.pre3

data/Gemfile.lock

@@ -1,8 +1,10 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre2)
+    otto (2.0.0.pre3)
+      concurrent-ruby (~> 1.3, < 2.0)
       facets (~> 3.1)
+      ipaddr (~> 1, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
@@ -13,6 +15,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    benchmark (0.4.1)
     bigdecimal (3.2.3)
     concurrent-ruby (1.3.5)
     crass (1.0.6)
@@ -21,10 +24,11 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    erb (5.0.2)
+    erb (5.1.1)
     facets (3.1.0)
     hana (1.3.7)
     io-console (0.8.1)
+    ipaddr (1.2.7)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
@@ -41,7 +45,7 @@ GEM
     loofah (2.24.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    minitest (5.25.5)
+    minitest (5.26.0)
     nokogiri (1.18.10-aarch64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.18.10-aarch64-linux-musl)
@@ -64,7 +68,7 @@ GEM
       racc
     pastel (0.8.0)
       tty-color (~> 0.5)
-    pp (0.6.2)
+    pp (0.6.3)
       prettyprint
     prettier_print (1.2.1)
     prettyprint (0.2.0)
@@ -73,7 +77,7 @@ GEM
       date
       stringio
     racc (1.8.1)
-    rack (3.2.2)
+    rack (3.2.3)
     rack-attack (6.7.0)
       rack (>= 1.0, < 4)
     rack-parser (0.7.0)
@@ -85,9 +89,10 @@ GEM
     rainbow (3.1.1)
     rbs (3.9.5)
       logger
-    rdoc (6.14.2)
+    rdoc (6.15.0)
       erb
       psych (>= 4.0.0)
+      tsort
     regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
@@ -104,7 +109,7 @@ GEM
     rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.5)
+    rspec-support (3.13.6)
     rubocop (1.81.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
@@ -140,15 +145,16 @@ GEM
     stringio (3.1.7)
     syntax_tree (6.3.0)
       prettier_print (>= 1.2.0)
-    tryouts (3.6.0)
+    tryouts (3.6.1)
       concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
       prism (~> 1.0)
-      rspec (~> 3.0)
+      rspec (>= 3.0, < 5.0)
       tty-cursor (~> 0.7)
       tty-screen (~> 0.8)
+    tsort (0.2.0)
     tty-color (0.6.0)
     tty-cursor (0.7.1)
     tty-screen (0.8.2)
@@ -167,6 +173,7 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  benchmark
   debug
   json_schemer
   otto!
@@ -181,7 +188,7 @@ DEPENDENCIES
   ruby-lsp
   stackprof
   syntax_tree
-  tryouts (~> 3.6.0)
+  tryouts (~> 3.6.1)
 
 BUNDLED WITH
    2.7.1

data/benchmark_middleware_wrap.rb

@@ -0,0 +1,163 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Benchmark to measure real-world Otto performance with actual routes and middleware
+# Usage: ruby benchmark_middleware_wrap.rb
+
+require 'bundler/setup'
+require 'benchmark'
+require 'stringio'
+require 'tempfile'
+
+require_relative 'lib/otto'
+
+REQUEST_COUNT = 50_000
+MIDDLEWARE_COUNT = 40
+
+# Create a temporary routes file
+routes_content = <<~ROUTES
+  GET / TestApp.index
+  GET /users/:id TestApp.show
+  POST /users TestApp.create
+  GET /health TestApp.health
+ROUTES
+
+routes_file = Tempfile.new(['routes', '.txt'])
+routes_file.write(routes_content)
+routes_file.close
+
+# Define test application
+class TestApp
+  def self.index(_env, _params = {})
+    [200, { 'Content-Type' => 'text/html' }, ['Welcome']]
+  end
+
+  def self.show(env, params = {})
+    user_id = params[:id] || env.dig('otto.params', :id) || '123'
+    [200, { 'Content-Type' => 'text/html' }, ["User #{user_id}"]]
+  end
+
+  def self.create(_env, _params = {})
+    [201, { 'Content-Type' => 'application/json' }, ['{"id": 123}']]
+  end
+
+  def self.health(_env, _params = {})
+    [200, { 'Content-Type' => 'text/plain' }, ['OK']]
+  end
+end
+
+# Create real Rack middleware
+class BenchmarkMiddleware
+  def initialize(app, _config = nil)
+    @app = app
+  end
+
+  def call(env)
+    @app.call(env)
+  end
+end
+
+# Create Otto instance with real configuration
+otto = Otto.new(routes_file.path)
+
+# Add real Otto security middleware
+otto.enable_csrf_protection!
+otto.enable_request_validation!
+
+# Add custom middleware to reach target count
+current_count = otto.middleware.size
+(MIDDLEWARE_COUNT - current_count).times do
+  otto.use(Class.new(BenchmarkMiddleware))
+end
+
+# Suppress error logging for benchmark
+Otto.logger.level = Logger::FATAL
+
+puts "\n" + ("=" * 70)
+puts "Otto Performance Benchmark"
+puts ("=" * 70)
+puts "Configuration:"
+puts "  Routes:     #{otto.instance_variable_get(:@route_definitions).size}"
+actual_app = otto.instance_variable_get(:@app)
+puts "  Middleware: #{otto.middleware.size} (#{MIDDLEWARE_COUNT} total in stack, app built: #{!actual_app.nil?})"
+puts "  Requests:   #{REQUEST_COUNT.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}"
+puts ("=" * 70)
+
+# Create realistic Rack environments for different routes
+def make_env(method, path)
+  {
+    'REQUEST_METHOD' => method,
+    'PATH_INFO' => path,
+    'QUERY_STRING' => '',
+    'SERVER_NAME' => 'example.com',
+    'SERVER_PORT' => '80',
+    'rack.version' => [1, 3],
+    'rack.url_scheme' => 'http',
+    'rack.input' => StringIO.new,
+    'rack.errors' => StringIO.new,
+    'rack.multithread' => false,
+    'rack.multiprocess' => true,
+    'rack.run_once' => false,
+    'REMOTE_ADDR' => '192.168.1.100',
+    'HTTP_USER_AGENT' => 'Benchmark/1.0',
+    'rack.session' => {}
+  }
+end
+
+# Test different routes
+routes = [
+  ['GET', '/'],
+  ['GET', '/users/123'],
+  ['POST', '/users'],
+  ['GET', '/health']
+]
+
+# Warmup
+puts "\nWarming up (1,000 requests)..."
+1_000.times do |i|
+  method, path = routes[i % routes.size]
+  env = make_env(method, path)
+  otto.call(env)
+end
+
+puts "\n" + ("=" * 70)
+puts "Running benchmark..."
+puts ("=" * 70)
+
+# Benchmark
+result = Benchmark.measure do
+  REQUEST_COUNT.times do |i|
+    method, path = routes[i % routes.size]
+    env = make_env(method, path)
+    otto.call(env)
+  end
+end
+
+total_time = result.real
+per_request = (total_time / REQUEST_COUNT * 1_000_000).round(2)
+requests_per_sec = (REQUEST_COUNT / total_time).round(0)
+
+puts "\nResults:"
+puts ("=" * 70)
+puts "  Total time:        #{(total_time * 1000).round(2)}ms"
+puts "  Time per request:  #{per_request}µs"
+puts "  Requests/sec:      #{requests_per_sec.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse}"
+puts ("=" * 70)
+
+# Performance analysis
+puts "\nPerformance Analysis:"
+if per_request < 20
+  puts "  ✓ Excellent performance (< 20µs per request)"
+elsif per_request < 50
+  puts "  ✓ Good performance (< 50µs per request)"
+elsif per_request < 100
+  puts "  ~ Acceptable performance (< 100µs per request)"
+else
+  puts "  ⚠ May need optimization (#{per_request}µs per request)"
+end
+
+puts "\nMiddleware overhead: ~#{((per_request - 2.5) / MIDDLEWARE_COUNT).round(3)}µs per middleware"
+puts
+
+# Cleanup
+routes_file.unlink

data/changelog.d/20251014_144317_delano_54_thats_a_wrapper.rst

@@ -0,0 +1,36 @@
+Changed
+-------
+
+- Authentication now handled by RouteAuthWrapper at handler level instead of middleware
+- RouteAuthWrapper enhanced with session persistence, security headers, strategy caching, and sophisticated pattern matching
+- env['otto.strategy_result'] now GUARANTEED to be present on all routes (authenticated or anonymous)
+- RouteAuthWrapper now wraps all route handlers, not just routes with auth requirements
+
+Removed
+-------
+
+- Removed AuthenticationMiddleware (architecturally broken - executed before routing)
+- Removed enable_authentication! (no longer needed - RouteAuthWrapper handles auth automatically)
+- Removed defensive nil fallback from LogicClassHandler (no longer needed)
+
+Fixed
+-----
+
+- Session persistence now works correctly (env['rack.session'] references same object as strategy_result.session)
+- Security headers now included on all authentication failure responses (401/302)
+- Strategy lookups now cached for performance
+- env['otto.strategy_result'] is now guaranteed to be present (anonymous StrategyResult for public routes)
+- Routes without auth requirements now get anonymous StrategyResult with IP metadata
+
+Security
+--------
+
+- Authentication strategies now execute after routing when route_definition is available
+- Supports exact match, prefix match (role:admin), and fallback patterns for strategies
+
+Documentation
+-------------
+
+- Updated CLAUDE.md with RouteAuthWrapper architecture overview
+- Updated env_keys.rb to document guaranteed presence of strategy_result
+- Added comprehensive tests for anonymous route handling

data/changelog.d/20251014_161526_delano_54_thats_a_wrapper.rst

@@ -0,0 +1,5 @@
+Changed
+-------
+
+- Renamed MiddlewareStack#build_app to #wrap to better reflect per-request behavior
+  (wraps base app in middleware layers on each request, not a one-time initialization)

data/docs/.gitignore

@@ -2,3 +2,4 @@
 !.gitignore
 !migrating/
 !migrating/*.md
+!ipaddr-encoding-quirk.md

data/docs/ipaddr-encoding-quirk.md

@@ -0,0 +1,34 @@
+# IPAddr#to_s Encoding Quirk in Ruby 3
+
+Ruby's `IPAddr#to_s` returns inconsistent encodings: IPv4 addresses use US-ASCII, IPv6 addresses use UTF-8.
+
+## Behavior
+
+```ruby
+IPAddr.new('192.168.1.1').to_s.encoding  # => #<Encoding:US-ASCII>
+IPAddr.new('::1').to_s.encoding          # => #<Encoding:UTF-8>
+```
+
+## Cause
+
+Different string construction in IPAddr's `_to_string` method:
+
+- **IPv4**: `Array#join('.')` → US-ASCII optimization
+- **IPv6**: `String#%` → UTF-8 default
+
+## Impact
+
+- Rack expects UTF-8 strings
+- Mixed encodings cause `Encoding::CompatibilityError`
+- String operations fail on encoding mismatches
+
+## Solution
+
+Use `force_encoding('UTF-8')` instead of `encode('UTF-8')`:
+
+- IP addresses contain only ASCII characters
+- ASCII bytes are identical in US-ASCII and UTF-8
+- `force_encoding` changes label only (O(1))
+- `encode` creates new string (O(n))
+
+This ensures consistent UTF-8 encoding across all IP strings.

data/docs/migrating/v2.0.0-pre2.md

@@ -27,12 +27,6 @@ if strategy_result.is_a?(Otto::Security::Authentication::StrategyResult)
   # handle success
 end
 
-# Or for middleware - FailureResult indicates failure
-if strategy_result.is_a?(Otto::Security::Authentication::FailureResult)
-  # handle failure
-else
-  # handle success
-end
 ```
 
 ### 2. New Semantic Distinction
@@ -116,7 +110,7 @@ session['authenticated_at']  # Timestamp
 **Optional session keys:**
 ```ruby
 session['email']            # User email
-session['ip_address']       # Client IP
+session['ip_address']       # Client IP (masked by default via IPPrivacyMiddleware)
 session['user_agent']       # Client UA
 session['locale']           # User locale
 ```
@@ -140,7 +134,7 @@ class Controller::Base
       session: session,
       user: cust,
       auth_method: 'session',  # Hardcoded - loses semantic meaning
-      metadata: { ip: req.client_ipaddress }
+      metadata: { ip: req.masked_ip }  # Uses masked IP (privacy by default)
     )
   end
 end
@@ -148,10 +142,10 @@ end
 
 **Correct approach:**
 ```ruby
-# GOOD - Use middleware-provided result
+# GOOD - Use RouteAuthWrapper-provided result
 class Controller::Base
   def strategy_result
-    req.env['otto.strategy_result']  # Created by AuthenticationMiddleware
+    req.env['otto.strategy_result']  # Created by RouteAuthWrapper
   end
 end
 
@@ -188,7 +182,6 @@ expect(result).to be_failure
 
 # After
 expect(result).to be_a(Otto::Security::Authentication::StrategyResult)
-expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 ```
 
 ## Architecture Clarifications
@@ -196,13 +189,13 @@ expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 ### When StrategyResult is Created
 
 1. **Routes WITH `auth=...` requirement:**
-   - Strategy executes
-   - Returns `StrategyResult` (success) or `FailureResult` (failure)
-   - Middleware converts `FailureResult` to anonymous `StrategyResult` + 401 response
+   - RouteAuthWrapper executes strategy
+   - Always returns `StrategyResult` (success or failure)
+   - RouteAuthWrapper returns 401/302 response on `AuthFailure`
 
 2. **Routes WITHOUT `auth=...` requirement:**
-   - Middleware creates anonymous `StrategyResult`
-   - Sets `auth_method: 'anonymous'`
+   - No RouteAuthWrapper wrapping
+   - No `StrategyResult` created (routes without auth don't need it)
 
 3. **Auth app (Roda) routes:**
    - Manually creates `StrategyResult` for Logic class compatibility
@@ -213,7 +206,7 @@ expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 **Multi-app setup (Auth + Core + API):**
 - **Shared:** Session middleware, Redis session, Logic classes, Customer model
 - **Auth app:** Creates StrategyResult manually, uses Roda routing
-- **Core/API apps:** StrategyResult from AuthenticationMiddleware
+- **Core/API apps:** StrategyResult from RouteAuthWrapper
 - **Integration:** Pure session-based, no direct code calls between apps
 
 ## Testing Your Migration
@@ -339,7 +332,7 @@ middleware.add_with_position(
 
 Review the comprehensive inline documentation in:
 - `lib/otto/security/authentication/strategy_result.rb` (lines 1-90) - Auth semantics
-- `lib/otto/security/authentication/authentication_middleware.rb` - Auth middleware
+- `lib/otto/security/authentication/route_auth_wrapper.rb` - Auth handler wrapper
 - `lib/otto/env_keys.rb` - Complete env key registry
 
 The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.

data/examples/authentication_strategies/config.ru

@@ -12,7 +12,6 @@ otto = Otto.new('routes')
 # Enable security features to demonstrate advanced route parameters
 otto.enable_csrf_protection!
 otto.enable_request_validation!
-otto.enable_authentication!
 
 # Load and configure authentication strategies
 AuthenticationSetup.configure(otto)

data/lib/otto/core/configuration.rb

@@ -7,52 +7,37 @@ require_relative '../security/validator'
 require_relative '../security/authentication'
 require_relative '../security/rate_limiting'
 require_relative '../mcp/server'
+require_relative 'freezable'
 
 class Otto
   module Core
     # Configuration module providing locale and application configuration methods
     module Configuration
+      include Otto::Core::Freezable
       def configure_locale(opts)
-        # Start with global configuration
-        global_config = self.class.global_config
-        @locale_config = nil
-
-        # Check if we have any locale configuration from any source
-        has_global_locale = global_config && (global_config[:available_locales] || global_config[:default_locale])
+        # Check if we have any locale configuration
         has_direct_options = opts[:available_locales] || opts[:default_locale]
         has_legacy_config = opts[:locale_config]
 
-        # Only create locale_config if we have configuration from somewhere
-        return unless has_global_locale || has_direct_options || has_legacy_config
+        # Only create locale_config if we have configuration
+        return unless has_direct_options || has_legacy_config
 
-        @locale_config = {}
+        # Initialize with direct options
+        available_locales = opts[:available_locales]
+        default_locale = opts[:default_locale]
 
-        # Apply global configuration first
-        if global_config && global_config[:available_locales]
-          @locale_config[:available_locales] =
-            global_config[:available_locales]
-        end
-        if global_config && global_config[:default_locale]
-          @locale_config[:default_locale] =
-            global_config[:default_locale]
+        # Legacy support: Configure locale if provided via locale_config hash
+        if opts[:locale_config]
+          locale_opts = opts[:locale_config]
+          available_locales ||= locale_opts[:available_locales] || locale_opts[:available]
+          default_locale ||= locale_opts[:default_locale] || locale_opts[:default]
         end
 
-        # Apply direct instance options (these override global config)
-        @locale_config[:available_locales] = opts[:available_locales] if opts[:available_locales]
-        @locale_config[:default_locale] = opts[:default_locale] if opts[:default_locale]
-
-        # Legacy support: Configure locale if provided in initialization options via locale_config hash
-        return unless opts[:locale_config]
-
-        locale_opts = opts[:locale_config]
-        if locale_opts[:available_locales] || locale_opts[:available]
-          @locale_config[:available_locales] =
-            locale_opts[:available_locales] || locale_opts[:available]
-        end
-        return unless locale_opts[:default_locale] || locale_opts[:default]
-
-        @locale_config[:default_locale] =
-          locale_opts[:default_locale] || locale_opts[:default]
+        # Create Otto::Locale::Config instance
+        @locale_config = Otto::Locale::Config.new(
+          available_locales: available_locales,
+          default_locale: default_locale
+        )
       end
 
       def configure_security(opts)
@@ -86,7 +71,6 @@ class Otto
         # Enable authentication middleware if strategies are configured
         return unless opts[:auth_strategies] && !opts[:auth_strategies].empty?
 
-        enable_authentication!
       end
 
       def configure_mcp(opts)
@@ -115,9 +99,14 @@ class Otto
       #     default_locale: 'en'
       #   )
       def configure(available_locales: nil, default_locale: nil)
-        @locale_config ||= {}
-        @locale_config[:available_locales] = available_locales if available_locales
-        @locale_config[:default_locale] = default_locale if default_locale
+        ensure_not_frozen!
+
+        # Initialize locale_config if not already set
+        @locale_config ||= Otto::Locale::Config.new
+
+        # Update configuration
+        @locale_config.available_locales = available_locales if available_locales
+        @locale_config.default_locale = default_locale if default_locale
       end
 
       # Configure rate limiting settings.
@@ -134,6 +123,7 @@ class Otto
       #     }
       #   })
       def configure_rate_limiting(config)
+        ensure_not_frozen!
         @security_config.rate_limiting_config.merge!(config)
       end
 
@@ -149,14 +139,74 @@ class Otto
       #     'api_key' => Otto::Security::Authentication::Strategies::APIKeyStrategy.new(api_keys: ['secret123'])
       #   })
       def configure_auth_strategies(strategies, default_strategy: 'noauth')
+        ensure_not_frozen!
         # Update existing @auth_config rather than creating a new one
         @auth_config[:auth_strategies] = strategies
         @auth_config[:default_auth_strategy] = default_strategy
 
-        enable_authentication! unless strategies.empty?
       end
 
-      private
+      # Freeze the application configuration to prevent runtime modifications.
+      # Called automatically at the end of initialization to ensure immutability.
+      #
+      # This prevents security-critical configuration from being modified after
+      # the application begins handling requests. Uses deep freezing to prevent
+      # both direct modification and modification through nested structures.
+      #
+      # @raise [RuntimeError] if configuration is already frozen
+      # @return [self]
+      def freeze_configuration!
+        if frozen_configuration?
+          Otto.logger.debug '[Otto::Configuration] Configuration already frozen, skipping' if Otto.debug
+          return self
+        end
+
+        Otto.logger.debug '[Otto::Configuration] Starting configuration freeze process' if Otto.debug
+
+        # Deep freeze configuration objects with memoization support
+        Otto.logger.debug '[Otto::Configuration] Freezing security_config' if Otto.debug
+        @security_config.deep_freeze! if @security_config.respond_to?(:deep_freeze!)
+
+        Otto.logger.debug '[Otto::Configuration] Freezing locale_config' if Otto.debug
+        @locale_config.deep_freeze! if @locale_config.respond_to?(:deep_freeze!)
+
+        Otto.logger.debug '[Otto::Configuration] Freezing middleware stack' if Otto.debug
+        @middleware.deep_freeze! if @middleware.respond_to?(:deep_freeze!)
+
+        # Deep freeze configuration hashes (recursively freezes nested structures)
+        Otto.logger.debug '[Otto::Configuration] Freezing auth_config hash' if Otto.debug
+        deep_freeze_value(@auth_config) if @auth_config
+
+        Otto.logger.debug '[Otto::Configuration] Freezing option hash' if Otto.debug
+        deep_freeze_value(@option) if @option
+
+        # Deep freeze route structures (prevent modification of nested hashes/arrays)
+        Otto.logger.debug '[Otto::Configuration] Freezing route structures' if Otto.debug
+        deep_freeze_value(@routes) if @routes
+        deep_freeze_value(@routes_literal) if @routes_literal
+        deep_freeze_value(@routes_static) if @routes_static
+        deep_freeze_value(@route_definitions) if @route_definitions
+
+        @configuration_frozen = true
+        Otto.logger.info '[Otto::Configuration] Configuration freeze completed successfully'
+
+        self
+      end
+
+      # Check if configuration is frozen
+      #
+      # @return [Boolean] true if configuration is frozen
+      def frozen_configuration?
+        @configuration_frozen == true
+      end
+
+      # Ensure configuration is not frozen before allowing mutations
+      #
+      # @raise [FrozenError] if configuration is frozen
+      def ensure_not_frozen!
+        raise FrozenError, 'Cannot modify frozen configuration' if frozen_configuration?
+      end
+
 
       def middleware_enabled?(middleware_class)
         # Only check the new middleware stack as the single source of truth