otto 2.0.0.pre3 → 2.0.0.pre7

data/lib/otto/privacy/geo_resolver.rb

@@ -1,4 +1,6 @@
 # lib/otto/privacy/geo_resolver.rb
+#
+# frozen_string_literal: true
 
 require 'ipaddr'
 
@@ -7,53 +9,221 @@ class Otto
     # Lightweight geo-location resolution for IP addresses
     #
     # Provides country-level geo-location without requiring external
-    # databases or API calls. Uses CloudFlare headers when available,
-    # with fallback to basic IP range detection.
+    # databases or API calls. Supports headers from major CDN/infrastructure
+    # providers (Cloudflare, AWS CloudFront, Fastly, Akamai, Azure) with
+    # fallback to basic IP range detection.
     #
-    # @example Resolve country from CloudFlare header
+    # Supported CDN/Infrastructure Headers:
+    # - Cloudflare: CF-IPCountry
+    # - AWS CloudFront: CloudFront-Viewer-Country
+    # - Fastly: Fastly-Client-IP-Country
+    # - Akamai: X-Akamai-Edgescape (country_code=XX format)
+    # - Azure Front Door: X-Azure-ClientIP-Country
+    # - Semi-standard: X-Geo-Country, X-Country-Code, Country-Code
+    #
+    # @example Resolve country from Cloudflare header
     #   env = { 'HTTP_CF_IPCOUNTRY' => 'US' }
     #   GeoResolver.resolve('1.2.3.4', env)
     #   # => 'US'
     #
-    # @example Resolve without CloudFlare
-    #   GeoResolver.resolve('9.9.9.9', {})
-    #   # => 'CH' (Quad9 in Switzerland)
+    # @example Resolve from AWS CloudFront
+    #   env = { 'HTTP_CLOUDFRONT_VIEWER_COUNTRY' => 'GB' }
+    #   GeoResolver.resolve('1.2.3.4', env)
+    #   # => 'GB'
+    #
+    # @example Resolve without CDN headers
+    #   GeoResolver.resolve('8.8.8.8', {})
+    #   # => 'US' (Google DNS via range detection)
+    #
+    # @example Using a custom resolver (MaxMind)
+    #   GeoResolver.custom_resolver = ->(ip, env) {
+    #     reader = MaxMind::DB.new('GeoLite2-Country.mmdb')
+    #     result = reader.get(ip)
+    #     result&.dig('country', 'iso_code')
+    #   }
+    #   GeoResolver.resolve('1.2.3.4', {})  # Uses custom resolver
+    #
+    # @example Extending via subclass
+    #   class MyGeoResolver < Otto::Privacy::GeoResolver
+    #     def self.detect_by_range(ip)
+    #       # Custom logic here
+    #       super  # Fall back to parent
+    #     end
+    #   end
+    #
+    #
+    # Resolution flow
+    #
+    #    Request → Has familiar HTTP Header?
+    #              ├─ Yes → Return country (Cloudflare, AWS, etc.)
+    #              └─ No → Custom Resolver?
+    #                      ├─ Configured → Call & validate
+    #                      │               ├─ Valid → Return country
+    #                      │               └─ Invalid/Error → Continue
+    #                      └─ Not configured → Built-in range detection
+    #                                          └─ Unknown ('**')
     #
     class GeoResolver
-      # Unknown country code (ISO 3166-1 alpha-2)
-      UNKNOWN = 'XX'
+      # Unknown country code (not ISO 3166-1 alpha-2, intentionally distinct)
+      UNKNOWN = '**'
+
+      # Custom resolver for extending geo-location capabilities
+      # Can be set to a proc/lambda or a class responding to .call(ip, env)
+      #
+      # @example Using a proc
+      #   GeoResolver.custom_resolver = ->(ip, env) {
+      #     return nil  # Return nil to continue with built-in resolution
+      #     # or return 'US' to provide custom country code
+      #   }
+      #
+      # @example Using MaxMind
+      #   GeoResolver.custom_resolver = ->(ip, env) {
+      #     reader = MaxMind::DB.new('path/to/GeoLite2-Country.mmdb')
+      #     result = reader.get(ip)
+      #     result&.dig('country', 'iso_code')
+      #   }
+      #
+      # Thread Safety Model:
+      # This follows Ruby's standard configuration pattern:
+      # - Set ONCE at boot time (single-threaded initialization)
+      # - Read many times during requests (multi-threaded reads)
+      # - No synchronization needed for this access pattern
+      #
+      # Runtime resolver switching is NOT supported. Changing the resolver
+      # while processing requests creates race conditions (write vs read).
+      # This is intentional - resolver configuration is boot-time only.
+      @custom_resolver = nil
+
+      class << self
+        attr_accessor :custom_resolver
+
+        # Set a custom resolver for geo-location
+        #
+        # MUST be called during single-threaded initialization (before
+        # accepting requests). Runtime changes while serving requests
+        # will cause race conditions.
+        #
+        # @param resolver [Proc, #call] A proc or callable object that takes (ip, env)
+        #   and returns a country code string or nil
+        # @raise [ArgumentError] if resolver doesn't respond to :call
+        def custom_resolver=(resolver)
+          unless resolver.nil? || resolver.respond_to?(:call)
+            raise ArgumentError, 'Custom resolver must respond to :call'
+          end
+          @custom_resolver = resolver
+        end
+      end
 
       # Resolve country code for an IP address
       #
       # Resolution priority:
-      # 1. CloudFlare CF-IPCountry header (most reliable)
+      # 1. CDN/infrastructure provider headers (Cloudflare, AWS, Fastly, etc.)
       # 2. Basic IP range detection for major countries/providers
-      # 3. Return 'XX' for unknown
+      # 3. Return '**' for unknown
       #
       # @param ip [String] IP address to resolve
-      # @param env [Hash] Rack environment (may contain CF headers)
-      # @return [String] ISO 3166-1 alpha-2 country code or 'XX'
+      # @param env [Hash] Rack environment (may contain geo headers)
+      # @return [String] ISO 3166-1 alpha-2 country code or '**'
       def self.resolve(ip, env = {})
         return UNKNOWN if ip.nil? || ip.empty?
 
-        # Priority 1: CloudFlare header (free, accurate, no database)
-        cf_country = env['HTTP_CF_IPCOUNTRY']
-        return cf_country if cf_country && valid_country_code?(cf_country)
+        # Check CDN/infrastructure headers in priority order
+        # Priority based on reliability and deployment frequency
+        country = check_geo_headers(env)
+        return country if country
+
+        # Try custom resolver if configured
+        if @custom_resolver
+          begin
+            country = @custom_resolver.call(ip, env)
+            return country if country && valid_country_code?(country)
+          rescue StandardError => e
+            # Log error but don't crash - fall through to built-in detection
+            warn "GeoResolver custom resolver error: #{e.message}" if $DEBUG
+          end
+        end
 
-        # Priority 2: Basic range detection
+        # Fallback: Basic range detection
         detect_by_range(ip)
       rescue IPAddr::InvalidAddressError
         UNKNOWN
       end
 
+      # Check CDN/infrastructure provider geo headers
+      #
+      # Headers are checked in order of reliability and deployment frequency:
+      # 1. Cloudflare (CF-IPCountry) - Most widely deployed
+      # 2. AWS CloudFront (CloudFront-Viewer-Country)
+      # 3. Fastly (Fastly-Client-IP-Country)
+      # 4. Akamai (X-Akamai-Edgescape) - Complex format, extract country
+      # 5. Azure Front Door (X-Azure-ClientIP-Country)
+      # 6. Semi-standard headers (X-Geo-Country, X-Country-Code, Country-Code)
+      #
+      # @param env [Hash] Rack environment
+      # @return [String, nil] ISO 3166-1 alpha-2 country code or nil
+      # @api private
+      def self.check_geo_headers(env)
+        # Cloudflare (most common)
+        country = env['HTTP_CF_IPCOUNTRY']
+        return country if valid_country_code?(country)
+
+        # AWS CloudFront
+        country = env['HTTP_CLOUDFRONT_VIEWER_COUNTRY']
+        return country if valid_country_code?(country)
+
+        # Fastly
+        country = env['HTTP_FASTLY_CLIENT_IP_COUNTRY']
+        return country if valid_country_code?(country)
+
+        # Akamai Edgescape (format: country_code=US,region_code=CA,...)
+        if (edgescape = env['HTTP_X_AKAMAI_EDGESCAPE'])
+          country = extract_akamai_country(edgescape)
+          return country if valid_country_code?(country)
+        end
+
+        # Azure Front Door
+        country = env['HTTP_X_AZURE_CLIENTIP_COUNTRY']
+        return country if valid_country_code?(country)
+
+        # Semi-standard headers (least reliable, check last)
+        country = env['HTTP_X_GEO_COUNTRY']
+        return country if valid_country_code?(country)
+
+        country = env['HTTP_X_COUNTRY_CODE']
+        return country if valid_country_code?(country)
+
+        country = env['HTTP_COUNTRY_CODE']
+        return country if valid_country_code?(country)
+
+        nil
+      end
+      private_class_method :check_geo_headers
+
+      # Extract country code from Akamai Edgescape header
+      #
+      # Edgescape format: "country_code=US,region_code=CA,city=LOSANGELES,..."
+      #
+      # @param edgescape [String] Akamai Edgescape header value
+      # @return [String, nil] Country code or nil
+      # @api private
+      def self.extract_akamai_country(edgescape)
+        return nil unless edgescape.is_a?(String)
+
+        # Extract country_code=XX (must be exactly 2 uppercase letters, bounded)
+        # Use word boundary or comma to ensure we don't match partial strings like "INVALID"
+        match = edgescape.match(/country_code=([A-Z]{2})(?:,|\z)/)
+        match ? match[1] : nil
+      end
+      private_class_method :extract_akamai_country
+
       # Detect country by IP range (basic implementation)
       #
       # Detects major cloud providers and well-known IP ranges.
       # This is intentionally limited - for comprehensive geo-location,
-      # use CloudFlare or a dedicated GeoIP database.
+      # use CDN headers or configure a custom resolver.
       #
       # @param ip [String] IP address
-      # @return [String] Country code or 'XX'
+      # @return [String] Country code or '**'
       # @api private
       def self.detect_by_range(ip)
         addr = IPAddr.new(ip)
@@ -70,18 +240,8 @@ class Otto
       end
       private_class_method :detect_by_range
 
-      # Validate country code format
-      #
-      # @param code [String] Country code to validate
-      # @return [Boolean] true if valid ISO 3166-1 alpha-2 code
-      # @api private
-      def self.valid_country_code?(code)
-        code.is_a?(String) && code.length == 2 && code.match?(/^[A-Z]{2}$/)
-      end
-      private_class_method :valid_country_code?
-
       # Known IP ranges for major providers (limited set for basic detection)
-      # For comprehensive geo-location, use CloudFlare or GeoIP database
+      # For comprehensive geo-location, use CDN headers or custom resolver
       KNOWN_RANGES = {
         # Google Public DNS
         IPAddr.new('8.8.8.0/24') => 'US',
@@ -110,6 +270,16 @@ class Otto
         IPAddr.new('208.67.222.0/24') => 'US',
         IPAddr.new('208.67.220.0/24') => 'US',
       }.freeze
+
+      # Validate country code format
+      #
+      # @param code [String] Country code to validate
+      # @return [Boolean] true if valid ISO 3166-1 alpha-2 code
+      # @api private
+      def self.valid_country_code?(code)
+        code.is_a?(String) && code.length == 2 && code.match?(/^[A-Z]{2}$/)
+      end
+      private_class_method :valid_country_code?
     end
   end
 end

data/lib/otto/privacy/ip_privacy.rb

@@ -1,4 +1,6 @@
 # lib/otto/privacy/ip_privacy.rb
+#
+# frozen_string_literal: true
 
 require 'ipaddr'
 require 'digest'

data/lib/otto/privacy/redacted_fingerprint.rb

@@ -1,4 +1,6 @@
 # lib/otto/privacy/redacted_fingerprint.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require 'time'
@@ -88,21 +90,29 @@ class Otto
 
       private
 
-      # Anonymize user agent string by removing version numbers
+      # Anonymize user agent string by removing version numbers and build identifiers
       #
-      # Removes specific version numbers (X.X.X pattern) to reduce
-      # fingerprinting granularity while maintaining browser/OS info.
+      # Removes specific version numbers (*.*.* pattern) and build identifiers
+      # (e.g., Build/MRA58N) to reduce fingerprinting granularity while maintaining
+      # browser/OS info.
       #
       # @param ua [String, nil] User agent string
       # @return [String, nil] Anonymized user agent or nil
       def anonymize_user_agent(ua)
         return nil if ua.nil? || ua.empty?
 
-        # Remove version patterns (X.X.X.X, X.X.X, X.X)
-        anonymized = ua
-                     .gsub(/\d+\.\d+\.\d+\.\d+/, 'X.X.X.X')
-                     .gsub(/\d+\.\d+\.\d+/, 'X.X.X')
-                     .gsub(/\d+\.\d+/, 'X.X')
+        # Remove build identifiers (e.g., Build/MRA58N, Build/MPJ24.139-64)
+        # This must run BEFORE version stripping to avoid partial matches.
+        # If we strip versions first, Build/MPJ24.139-64 becomes Build/MPJ*.*-64,
+        # and the regex won't match properly (asterisks not in [\w.-] class).
+        anonymized = ua.gsub(/Build\/[\w.-]+/, 'Build/*')
+
+        # Remove version patterns (*.*.*.*, *.*.*, *.*)
+        # Support both dot and underscore separators (e.g., 10.15.7 and 10_15_7)
+        anonymized = anonymized
+                     .gsub(/\d+[._]\d+[._]\d+[._]\d+/, '*.*.*.*')
+                     .gsub(/\d+[._]\d+[._]\d+/, '*.*.*')
+                     .gsub(/\d+[._]\d+/, '*.*')
 
         # Truncate if too long (prevent DoS via huge UA strings)
         anonymized.length > 500 ? anonymized[0..499] : anonymized

data/lib/otto/privacy.rb

@@ -1,3 +1,5 @@
+# lib/otto/privacy.rb
+#
 # frozen_string_literal: true
 
 require_relative 'privacy/config'

data/lib/otto/response_handlers/auto.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/auto.rb
+#
 # frozen_string_literal: true
 
 require_relative 'base'

data/lib/otto/response_handlers/base.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/base.rb
+#
 # frozen_string_literal: true
 
 class Otto

data/lib/otto/response_handlers/default.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/default.rb
+#
 # frozen_string_literal: true
 
 require_relative 'base'

data/lib/otto/response_handlers/factory.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/factory.rb
+#
 # frozen_string_literal: true
 
 require_relative 'json'

data/lib/otto/response_handlers/json.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/json.rb
+#
 # frozen_string_literal: true
 
 require_relative 'base'

data/lib/otto/response_handlers/redirect.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/redirect.rb
+#
 # frozen_string_literal: true
 
 require_relative 'base'

data/lib/otto/response_handlers/view.rb

@@ -1,3 +1,5 @@
+# lib/otto/response_handlers/view.rb
+#
 # frozen_string_literal: true
 
 require_relative 'base'

data/lib/otto/response_handlers.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/response_handlers.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module ResponseHandlers

data/lib/otto/route.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Otto::Route
@@ -158,8 +158,8 @@ class Otto
         if response_type != 'default'
           context = {
             logic_instance: (kind == :instance ? inst : nil),
-            status_code: nil,
-            redirect_path: nil,
+               status_code: nil,
+             redirect_path: nil,
           }
 
           Otto::ResponseHandlers::HandlerFactory.handle_response(result, res, response_type, context)

data/lib/otto/route_definition.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_definition.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Immutable data class representing a complete route definition
@@ -73,10 +73,37 @@ class Otto
       @options.fetch(key.to_sym, default)
     end
 
-    # Get authentication requirement
+    # Get authentication requirement (backward compatibility - returns first requirement)
     # @return [String, nil] The auth requirement or nil
     def auth_requirement
-      option(:auth)
+      auth_requirements.first
+    end
+
+    # Get all authentication requirements as an array
+    # Supports multiple strategies: auth=session,apikey,oauth
+    # @return [Array<String>] Array of auth requirement strings
+    def auth_requirements
+      auth = option(:auth)
+      return [] unless auth
+
+      auth.split(',').map(&:strip).reject(&:empty?)
+    end
+
+    # Get role requirement for route-level authorization
+    # Supports single role or comma-separated roles (OR logic): role=admin,editor
+    # @return [String, nil] The role requirement or nil
+    def role_requirement
+      option(:role)
+    end
+
+    # Get all role requirements as an array
+    # Supports multiple roles with OR logic: role=admin,editor
+    # @return [Array<String>] Array of role requirement strings
+    def role_requirements
+      role = option(:role)
+      return [] unless role
+
+      role.split(',').map(&:strip).reject(&:empty?)
     end
 
     # Get response type
@@ -111,16 +138,16 @@ class Otto
     # @return [Hash]
     def to_h
       {
-        verb: @verb,
-        path: @path,
-        definition: @definition,
-        target: @target,
-        klass_name: @klass_name,
+               verb: @verb,
+               path: @path,
+         definition: @definition,
+             target: @target,
+         klass_name: @klass_name,
         method_name: @method_name,
-        kind: @kind,
-        options: @options,
-        pattern: @pattern,
-        keys: @keys,
+               kind: @kind,
+            options: @options,
+            pattern: @pattern,
+               keys: @keys,
       }
     end
 
@@ -166,11 +193,11 @@ class Otto
       case target
       when /^(.+)\.(.+)$/
         # Class.method - call class method directly
-        { klass_name: $1, method_name: $2, kind: :class }
+        { klass_name: ::Regexp.last_match(1), method_name: ::Regexp.last_match(2), kind: :class }
 
       when /^(.+)#(.+)$/
         # Class#method - instantiate then call instance method
-        { klass_name: $1, method_name: $2, kind: :instance }
+        { klass_name: ::Regexp.last_match(1), method_name: ::Regexp.last_match(2), kind: :instance }
 
       when /^[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*$/
         # Bare class name - instantiate the class

data/lib/otto/route_handlers/base.rb

@@ -1,4 +1,6 @@
 # lib/otto/route_handlers/base.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/otto/route_handlers/class_method.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/class_method.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 require 'securerandom'
@@ -13,6 +13,7 @@ class Otto
     # Maintains backward compatibility for Controller.action patterns
     class ClassMethodHandler < BaseHandler
       def call(env, extra_params = {})
+        start_time = Otto::Utils.now_in_μs
         req = Rack::Request.new(env)
         res = Rack::Response.new
 
@@ -25,19 +26,22 @@ class Otto
 
           # Only handle response if response_type is not default
           if route_definition.response_type != 'default'
-            handle_response(result, res, {
-                              class: target_class,
+            handle_response(result, res,
+            {
+                class: target_class,
               request: req,
-                            })
+            })
           end
         rescue StandardError => e
           # Check if we're being called through Otto's integrated context (vs direct handler testing)
           # In integrated context, let Otto's centralized error handler manage the response
           # In direct testing context, handle errors locally for unit testing
           if otto_instance
-            # Log error for handler-specific context but let Otto's centralized error handler manage the response
-            Otto.logger.error "[ClassMethodHandler] #{e.class}: #{e.message}"
-            Otto.logger.debug "[ClassMethodHandler] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
+            # Store handler context in env for centralized error handler
+            handler_name = "#{target_class.name}##{route_definition.method_name}"
+            env['otto.handler'] = handler_name
+            env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
+
             raise e # Re-raise to let Otto's centralized error handler manage the response
           else
             # Direct handler testing context - handle errors locally with security improvements
@@ -51,26 +55,15 @@ class Otto
             accept_header = env['HTTP_ACCEPT'].to_s
             if accept_header.include?('application/json')
               res.headers['content-type'] = 'application/json'
-              error_data                  = if Otto.env?(:dev, :development)
-                                              {
-                                                error: 'Internal Server Error',
-                                                message: 'Server error occurred. Check logs for details.',
-                                                error_id: error_id,
-                                              }
-                                            else
-                                              {
-                                                error: 'Internal Server Error',
-                                                message: 'An error occurred. Please try again later.',
-                                              }
-                                            end
+              error_data                  = {
+                   error: 'Internal Server Error',
+                 message: 'Server error occurred. Check logs for details.',
+                error_id: error_id,
+              }
               res.write JSON.generate(error_data)
             else
               res.headers['content-type'] = 'text/plain'
-              if Otto.env?(:dev, :development)
-                res.write "Server error (ID: #{error_id}). Check logs for details."
-              else
-                res.write 'An error occurred. Please try again later.'
-              end
+              res.write "Server error (ID: #{error_id}). Check logs for details."
             end
 
             # Add security headers if available

data/lib/otto/route_handlers/factory.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/factory.rb
+#
+# frozen_string_literal: true
 
 require_relative 'base'
 require_relative '../security/authentication/route_auth_wrapper'

data/lib/otto/route_handlers/instance_method.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/route_handlers/instance_method.rb
+#
+# frozen_string_literal: true
 require 'securerandom'
 
 require_relative 'base'
@@ -11,6 +11,7 @@ class Otto
     # Maintains backward compatibility for Controller#action patterns
     class InstanceMethodHandler < BaseHandler
       def call(env, extra_params = {})
+        start_time = Otto::Utils.now_in_μs
         req = Rack::Request.new(env)
         res = Rack::Response.new
 
@@ -34,9 +35,11 @@ class Otto
           # In integrated context, let Otto's centralized error handler manage the response
           # In direct testing context, handle errors locally for unit testing
           if otto_instance
-            # Log error for handler-specific context but let the centralized error handler manage the response
-            Otto.logger.error "[InstanceMethodHandler] #{e.class}: #{e.message}"
-            Otto.logger.debug "[InstanceMethodHandler] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
+            # Store handler context in env for centralized error handler
+            handler_name = "#{target_class}##{route_definition.method_name}"
+            env['otto.handler'] = handler_name
+            env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
+
             raise e # Re-raise to let Otto's centralized error handler manage the response
           else
             # Direct handler testing context - handle errors locally with security improvements