otto 2.0.0.pre2 → 2.0.0.pre7

data/lib/otto.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 require 'logger'
@@ -11,29 +11,20 @@ require 'rack/request'
 require 'rack/response'
 require 'rack/utils'
 
-require_relative 'otto/security/authentication/strategy_result'
 require_relative 'otto/route_definition'
 require_relative 'otto/route'
 require_relative 'otto/static'
-require_relative 'otto/helpers/request'
-require_relative 'otto/helpers/response'
+require_relative 'otto/helpers'
 require_relative 'otto/response_handlers'
 require_relative 'otto/route_handlers'
-require_relative 'otto/version'
-require_relative 'otto/security/config'
-require_relative 'otto/security/middleware/csrf_middleware'
-require_relative 'otto/security/middleware/validation_middleware'
-require_relative 'otto/security/authentication/authentication_middleware'
-require_relative 'otto/security/middleware/rate_limit_middleware'
-require_relative 'otto/mcp/server'
-require_relative 'otto/core/router'
-require_relative 'otto/core/file_safety'
-require_relative 'otto/core/configuration'
-require_relative 'otto/core/error_handler'
-require_relative 'otto/core/uri_generator'
-require_relative 'otto/core/middleware_stack'
-require_relative 'otto/security/configurator'
+require_relative 'otto/locale'
+require_relative 'otto/mcp'
+require_relative 'otto/core'
+require_relative 'otto/privacy'
+require_relative 'otto/security'
 require_relative 'otto/utils'
+require_relative 'otto/version'
+require_relative 'otto/logging_helpers'
 
 # Otto is a simple Rack router that allows you to define routes in a file
 # with built-in security features including CSRF protection, input validation,
@@ -56,37 +47,6 @@ require_relative 'otto/utils'
 #   otto.enable_csp!
 #   otto.enable_frame_protection!
 #
-# Configuration Data class to replace OpenStruct
-# Configuration class to replace OpenStruct
-class ConfigData
-  def initialize(**kwargs)
-    @data = kwargs
-  end
-
-  # Dynamic attribute accessors
-  def method_missing(method_name, *args)
-    if method_name.to_s.end_with?('=')
-      # Setter
-      attr_name = method_name.to_s.chomp('=').to_sym
-      @data[attr_name] = args.first
-    elsif @data.key?(method_name)
-      # Getter
-      @data[method_name]
-    else
-      super
-    end
-  end
-
-  def respond_to_missing?(method_name, include_private = false)
-    method_name.to_s.end_with?('=') || @data.key?(method_name) || super
-  end
-
-  # Convert to hash for compatibility
-  def to_h
-    @data.dup
-  end
-end
-
 class Otto
   include Otto::Core::Router
   include Otto::Core::FileSafety
@@ -102,25 +62,12 @@ class Otto
            else
              defined?(Otto::Utils) ? Otto::Utils.yes?(ENV.fetch('OTTO_DEBUG', nil)) : false
            end
-  @logger        = Logger.new($stdout, Logger::INFO)
-  @global_config = nil
-
-  # Global configuration for all Otto instances (Ruby 3.2+ pattern matching)
-  def self.configure
-    config = case @global_config
-             in Hash => h
-               # Transform string keys to symbol keys for ConfigData compatibility
-               symbol_hash = h.transform_keys(&:to_sym)
-               ConfigData.new(**symbol_hash)
-             else
-               ConfigData.new
-             end
-    yield config
-    @global_config = config.to_h
-  end
+  @logger = Logger.new($stdout, Logger::INFO)
 
-  attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option, :static_route,
-              :security_config, :locale_config, :auth_config, :route_handler_factory, :mcp_server, :security, :middleware
+  attr_reader :routes, :routes_literal, :routes_static, :route_definitions, :option,
+              :static_route, :security_config, :locale_config, :auth_config,
+              :route_handler_factory, :mcp_server, :security, :middleware,
+              :error_handlers
   attr_accessor :not_found, :server_error
 
   def initialize(path = nil, opts = {})
@@ -131,27 +78,103 @@ class Otto
     Otto.logger.debug "new Otto: #{opts}" if Otto.debug
     load(path) unless path.nil?
     super()
+
+    # Auto-register AuthorizationError for 403 Forbidden responses
+    # This allows Logic classes to raise AuthorizationError for resource-level access control
+    register_error_handler(Otto::Security::AuthorizationError, status: 403, log_level: :warn)
+
+    # Build the middleware app once after all initialization is complete
+    build_app!
+
+    # Configuration freezing is deferred until first request to support
+    # multi-step initialization (e.g., multi-app architectures).
+    # This allows adding auth strategies, middleware, etc. after Otto.new
+    # but before processing requests.
+    @freeze_mutex = Mutex.new
+    @configuration_frozen = false
   end
   alias options option
 
   # Main Rack application interface
   def call(env)
-    # Apply middleware stack
-    base_app = ->(e) { handle_request(e) }
+    # Freeze configuration on first request (thread-safe)
+    # Skip in test environment to allow test flexibility
+    unless defined?(RSpec) || @configuration_frozen
+      Otto.logger.debug '[Otto] Lazy freezing check: configuration not yet frozen' if Otto.debug
+
+      @freeze_mutex.synchronize do
+        unless @configuration_frozen
+          Otto.logger.info '[Otto] Freezing configuration on first request (lazy freeze)'
+          freeze_configuration!
+          @configuration_frozen = true
+          Otto.logger.debug '[Otto] Configuration frozen successfully' if Otto.debug
+        end
+      end
+    end
 
-    # Use the middleware stack as the source of truth
-    app = @middleware.build_app(base_app, @security_config)
+    # Track request timing for lifecycle hooks
+    start_time = Otto::Utils.now_in_μs
+    request = Rack::Request.new(env)
+    response_raw = nil
 
     begin
-      app.call(env)
+      # Use pre-built middleware app (built once at initialization)
+      response_raw = @app.call(env)
     rescue StandardError => e
-      handle_error(e, env)
+      response_raw = handle_error(e, env)
+    ensure
+      # Execute request completion hooks if any are registered
+      unless @request_complete_callbacks.empty?
+        begin
+          duration = Otto::Utils.now_in_μs - start_time
+          # Wrap response tuple in Rack::Response for developer-friendly API
+          # Otto's hook API should provide nice abstractions like Rack::Request/Response
+          response = Rack::Response.new(response_raw[2], response_raw[0], response_raw[1])
+          @request_complete_callbacks.each do |callback|
+            callback.call(request, response, duration)
+          end
+        rescue StandardError => e
+          Otto.logger.error "[Otto] Request completion hook error: #{e.message}"
+          Otto.logger.debug "[Otto] Hook error backtrace: #{e.backtrace.join("\n")}" if Otto.debug
+        end
+      end
     end
+
+    response_raw
+  end
+
+  # Builds the middleware application chain
+  # Called once at initialization and whenever middleware stack changes
+  #
+  # IMPORTANT: If you have routes with auth requirements, you MUST add session
+  # middleware to your middleware stack BEFORE Otto processes requests.
+  #
+  # Session middleware is required for RouteAuthWrapper to correctly persist
+  # session changes during authentication. Common options include:
+  # - Rack::Session::Cookie (requires rack-session gem)
+  # - Rack::Session::Pool
+  # - Rack::Session::Memcache
+  # - Any Rack-compatible session middleware
+  #
+  # Example:
+  #   use Rack::Session::Cookie, secret: ENV['SESSION_SECRET']
+  #   otto = Otto.new('routes.txt')
+  #
+  def build_app!
+    base_app = method(:handle_request)
+    @app = @middleware.wrap(base_app, @security_config)
   end
 
   # Middleware Management
   def use(middleware, ...)
+    ensure_not_frozen!
     @middleware.add(middleware, ...)
+
+    # NOTE: If build_app! is triggered during a request (via use() or
+    # middleware_stack=), the @app instance variable could be swapped
+    # mid-request in a multi-threaded environment.
+
+    build_app! if @app # Rebuild app if already initialized
   end
 
   # Compatibility method for existing tests
@@ -163,6 +186,7 @@ class Otto
   def middleware_stack=(stack)
     @middleware.clear!
     Array(stack).each { |middleware| @middleware.add(middleware) }
+    build_app! if @app # Rebuild app if already initialized
   end
 
   # Compatibility method for middleware detection
@@ -179,6 +203,7 @@ class Otto
   # @example
   #   otto.enable_csrf_protection!
   def enable_csrf_protection!
+    ensure_not_frozen!
     return if @middleware.includes?(Otto::Security::Middleware::CSRFMiddleware)
 
     @security_config.enable_csrf_protection!
@@ -191,6 +216,7 @@ class Otto
   # @example
   #   otto.enable_request_validation!
   def enable_request_validation!
+    ensure_not_frozen!
     return if @middleware.includes?(Otto::Security::Middleware::ValidationMiddleware)
 
     @security_config.input_validation = true
@@ -206,6 +232,7 @@ class Otto
   # @example
   #   otto.enable_rate_limiting!(requests_per_minute: 50)
   def enable_rate_limiting!(options = {})
+    ensure_not_frozen!
     return if @middleware.includes?(Otto::Security::Middleware::RateLimitMiddleware)
 
     @security.configure_rate_limiting(options)
@@ -222,7 +249,7 @@ class Otto
   # @example
   #   otto.add_rate_limit_rule('uploads', limit: 5, period: 300, condition: ->(req) { req.post? && req.path.include?('upload') })
   def add_rate_limit_rule(name, options)
-    @security_config.rate_limiting_config[:custom_rules] ||= {}
+    ensure_not_frozen!
     @security_config.rate_limiting_config[:custom_rules][name.to_s] = options
   end
 
@@ -234,6 +261,7 @@ class Otto
   #   otto.add_trusted_proxy('10.0.0.0/8')
   #   otto.add_trusted_proxy(/^172\.16\./)
   def add_trusted_proxy(proxy)
+    ensure_not_frozen!
     @security_config.add_trusted_proxy(proxy)
   end
 
@@ -247,6 +275,7 @@ class Otto
   #     'strict-transport-security' => 'max-age=31536000'
   #   })
   def set_security_headers(headers)
+    ensure_not_frozen!
     @security_config.security_headers.merge!(headers)
   end
 
@@ -259,6 +288,7 @@ class Otto
   # @example
   #   otto.enable_hsts!(max_age: 86400, include_subdomains: false)
   def enable_hsts!(max_age: 31_536_000, include_subdomains: true)
+    ensure_not_frozen!
     @security_config.enable_hsts!(max_age: max_age, include_subdomains: include_subdomains)
   end
 
@@ -269,6 +299,7 @@ class Otto
   # @example
   #   otto.enable_csp!("default-src 'self'; script-src 'self' 'unsafe-inline'")
   def enable_csp!(policy = "default-src 'self'")
+    ensure_not_frozen!
     @security_config.enable_csp!(policy)
   end
 
@@ -278,6 +309,7 @@ class Otto
   # @example
   #   otto.enable_frame_protection!('DENY')
   def enable_frame_protection!(option = 'SAMEORIGIN')
+    ensure_not_frozen!
     @security_config.enable_frame_protection!(option)
   end
 
@@ -288,33 +320,202 @@ class Otto
   # @example
   #   otto.enable_csp_with_nonce!(debug: true)
   def enable_csp_with_nonce!(debug: false)
+    ensure_not_frozen!
     @security_config.enable_csp_with_nonce!(debug: debug)
   end
 
-  # Enable authentication middleware for route-level access control.
-  # This will automatically check route auth parameters and enforce authentication.
-  #
-  # @example
-  #   otto.enable_authentication!
-  def enable_authentication!
-    return if @middleware.includes?(Otto::Security::Authentication::AuthenticationMiddleware)
-
-    use Otto::Security::Authentication::AuthenticationMiddleware, @auth_config
-  end
-
   # Add a single authentication strategy
   #
   # @param name [String] Strategy name
   # @param strategy [Otto::Security::Authentication::AuthStrategy] Strategy instance
   # @example
   #   otto.add_auth_strategy('custom', MyCustomStrategy.new)
+  # Add an authentication strategy with a registered name
+  #
+  # This is the primary public API for registering authentication strategies.
+  # The name you provide here will be available as `strategy_result.strategy_name`
+  # in your application code, making it easy to identify which strategy authenticated
+  # the current request.
+  #
+  # Also available via Otto::Security::Configurator for consolidated security config.
+  #
+  # @param name [String, Symbol] Strategy name (e.g., 'session', 'api_key', 'jwt')
+  # @param strategy [AuthStrategy] Strategy instance
+  # @example
+  #   otto.add_auth_strategy('session', SessionStrategy.new(session_key: 'user_id'))
+  #   otto.add_auth_strategy('api_key', APIKeyStrategy.new)
+  # @raise [ArgumentError] if strategy name already registered
   def add_auth_strategy(name, strategy)
+    ensure_not_frozen!
     # Ensure auth_config is initialized (handles edge case where it might be nil)
     @auth_config = { auth_strategies: {}, default_auth_strategy: 'noauth' } if @auth_config.nil?
 
+    # Strict mode: Detect strategy name collisions
+    if @auth_config[:auth_strategies].key?(name)
+      raise ArgumentError, "Authentication strategy '#{name}' is already registered"
+    end
+
     @auth_config[:auth_strategies][name] = strategy
+  end
 
-    enable_authentication!
+  # Register an error handler for expected business logic errors
+  #
+  # This allows you to handle known error conditions (like missing resources,
+  # expired data, rate limits) without logging them as unhandled 500 errors.
+  #
+  # @param error_class [Class, String] The exception class or class name to handle
+  # @param status [Integer] HTTP status code to return (default: 500)
+  # @param log_level [Symbol] Log level for expected errors (:info, :warn, :error)
+  # @param handler [Proc] Optional block to customize error response
+  #
+  # @example Basic usage with status code
+  #   otto.register_error_handler(Onetime::MissingSecret, status: 404, log_level: :info)
+  #   otto.register_error_handler(Onetime::SecretExpired, status: 410, log_level: :info)
+  #
+  # @example With custom response handler
+  #   otto.register_error_handler(Onetime::RateLimited, status: 429, log_level: :warn) do |error, req|
+  #     {
+  #       error: 'Rate limit exceeded',
+  #       retry_after: error.retry_after,
+  #       message: error.message
+  #     }
+  #   end
+  #
+  # @example Using string class names (for lazy loading)
+  #   otto.register_error_handler('Onetime::MissingSecret', status: 404, log_level: :info)
+  #
+  def register_error_handler(error_class, status: 500, log_level: :info, &handler)
+    ensure_not_frozen!
+
+    # Normalize error class to string for consistent lookup
+    error_class_name = error_class.is_a?(String) ? error_class : error_class.name
+
+    @error_handlers[error_class_name] = {
+      status: status,
+      log_level: log_level,
+      handler: handler
+    }
+  end
+
+  # Disable IP privacy to access original IP addresses
+  #
+  # IMPORTANT: By default, Otto masks public IP addresses for privacy.
+  # Private/localhost IPs (127.0.0.0/8, 10.0.0.0/8, etc.) are never masked.
+  # Only disable this if you need access to original public IPs.
+  #
+  # When disabled:
+  # - env['REMOTE_ADDR'] contains the real IP address
+  # - env['otto.original_ip'] also contains the real IP
+  # - No PrivateFingerprint is created
+  #
+  # @example
+  #   otto.disable_ip_privacy!
+  def disable_ip_privacy!
+    ensure_not_frozen!
+    @security_config.ip_privacy_config.disable!
+  end
+
+  # Enable full IP privacy (mask ALL IPs including private/localhost)
+  #
+  # By default, Otto exempts private and localhost IPs from masking for
+  # better development experience. Call this method to mask ALL IPs
+  # regardless of type.
+  #
+  # @example Enable full privacy (mask all IPs)
+  #   otto = Otto.new(routes_file)
+  #   otto.enable_full_ip_privacy!
+  #   # Now 127.0.0.1 → 127.0.0.0, 192.168.1.100 → 192.168.1.0
+  #
+  # @return [void]
+  # @raise [FrozenError] if called after configuration is frozen
+  def enable_full_ip_privacy!
+    ensure_not_frozen!
+    @security_config.ip_privacy_config.mask_private_ips = true
+  end
+
+  # Register a callback to be executed after each request completes
+  #
+  # Instance-level request completion callbacks allow each Otto instance
+  # to have its own isolated set of callbacks, preventing duplicate
+  # invocations in multi-app architectures (e.g., Rack::URLMap).
+  #
+  # The callback receives three arguments:
+  # - request: Rack::Request object
+  # - response: Rack::Response object (wrapping the response tuple)
+  # - duration: Request processing duration in microseconds
+  #
+  # @example Basic usage
+  #   otto = Otto.new(routes_file)
+  #   otto.on_request_complete do |req, res, duration|
+  #     logger.info "Request completed", path: req.path, duration: duration
+  #   end
+  #
+  # @example Multi-app architecture
+  #   # App 1: Core Web Application
+  #   core_router = Otto.new
+  #   core_router.on_request_complete do |req, res, duration|
+  #     logger.info "Core app request", path: req.path
+  #   end
+  #
+  #   # App 2: API Application
+  #   api_router = Otto.new
+  #   api_router.on_request_complete do |req, res, duration|
+  #     logger.info "API request", path: req.path
+  #   end
+  #
+  #   # Each callback only fires for its respective Otto instance
+  #
+  # @yield [request, response, duration] Block to execute after each request
+  # @yieldparam request [Rack::Request] The request object
+  # @yieldparam response [Rack::Response] The response object
+  # @yieldparam duration [Integer] Duration in microseconds
+  # @return [self] Returns self for method chaining
+  # @raise [FrozenError] if called after configuration is frozen
+  def on_request_complete(&block)
+    ensure_not_frozen!
+    @request_complete_callbacks << block if block_given?
+    self
+  end
+
+  # Get registered request completion callbacks (for internal use)
+  #
+  # @api private
+  # @return [Array<Proc>] Array of registered callback blocks
+  attr_reader :request_complete_callbacks
+
+  # Configure IP privacy settings
+  #
+  # Privacy is enabled by default. Use this method to customize privacy
+  # behavior without disabling it entirely.
+  #
+  # @param octet_precision [Integer] Number of octets to mask (1 or 2, default: 1)
+  # @param hash_rotation [Integer] Seconds between key rotation (default: 86400)
+  # @param geo [Boolean] Enable geo-location resolution (default: true)
+  # @param redis [Redis] Redis connection for multi-server atomic key generation
+  #
+  # @example Mask 2 octets instead of 1
+  #   otto.configure_ip_privacy(octet_precision: 2)
+  #
+  # @example Disable geo-location
+  #   otto.configure_ip_privacy(geo: false)
+  #
+  # @example Custom hash rotation
+  #   otto.configure_ip_privacy(hash_rotation: 24.hours)
+  #
+  # @example Multi-server with Redis
+  #   redis = Redis.new(url: ENV['REDIS_URL'])
+  #   otto.configure_ip_privacy(redis: redis)
+  def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil)
+    ensure_not_frozen!
+    config = @security_config.ip_privacy_config
+
+    config.octet_precision = octet_precision if octet_precision
+    config.hash_rotation_period = hash_rotation if hash_rotation
+    config.geo_enabled = geo unless geo.nil?
+    config.instance_variable_set(:@redis, redis) if redis
+
+    # Validate configuration
+    config.validate!
   end
 
   # Enable MCP (Model Context Protocol) server support
@@ -326,6 +527,7 @@ class Otto
   # @example
   #   otto.enable_mcp!(http: true, endpoint: '/api/mcp')
   def enable_mcp!(options = {})
+    ensure_not_frozen!
     @mcp_server ||= Otto::MCP::Server.new(self)
 
     @mcp_server.enable!(options)
@@ -350,6 +552,16 @@ class Otto
     # Initialize @auth_config first so it can be shared with the configurator
     @auth_config       = { auth_strategies: {}, default_auth_strategy: 'noauth' }
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
+    @app               = nil # Pre-built middleware app (built after initialization)
+    @request_complete_callbacks = [] # Instance-level request completion callbacks
+    @error_handlers    = {} # Registered error handlers for expected errors
+
+    # Add IP Privacy middleware first in stack (privacy by default for public IPs)
+    # Private/localhost IPs are automatically exempted from masking
+    @middleware.add_with_position(
+      Otto::Security::Middleware::IPPrivacyMiddleware,
+      position: :first
+    )
   end
 
   def initialize_options(_path, opts)
@@ -375,7 +587,30 @@ class Otto
   end
 
   class << self
-    attr_accessor :debug, :logger, :global_config # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+    attr_accessor :debug, :logger # rubocop:disable ThreadSafety/ClassAndModuleAttributes
+
+    # Helper method for structured logging that works with both standard Logger and structured loggers
+    def structured_log(level, message, data = {})
+      return unless logger
+
+      # Skip debug logging when Otto.debug is false
+      return if level == :debug && !debug
+
+      # Sanitize backtrace if present
+      if data.is_a?(Hash) && data[:backtrace].is_a?(Array)
+        data = data.dup
+        data[:backtrace] = Otto::LoggingHelpers.sanitize_backtrace(data[:backtrace])
+      end
+
+      # Try structured logging first (SemanticLogger, etc.)
+      if logger.respond_to?(level) && logger.method(level).arity > 1
+        logger.send(level, message, data)
+      else
+        # Fallback to standard logger with formatted string
+        formatted_data = data.empty? ? '' : " -- #{data.inspect}"
+        logger.send(level, "[Otto] #{message}#{formatted_data}")
+      end
+    end
   end
 
   # Class methods for Otto framework providing singleton access and configuration
@@ -398,7 +633,27 @@ class Otto
     end
 
     def env? *guesses
-      !guesses.flatten.select { |n| ENV['RACK_ENV'].to_s == n.to_s }.empty?
+      guesses.flatten.any? { |n| ENV['RACK_ENV'].to_s == n.to_s }
+    end
+
+    # Test-only method to unfreeze Otto configuration
+    #
+    # This method resets the @configuration_frozen flag, allowing tests
+    # to bypass the ensure_not_frozen! check. It does NOT actually unfreeze
+    # Ruby objects (which is impossible once frozen).
+    #
+    # IMPORTANT: Only works when RSpec is defined. Raises an error otherwise
+    # to prevent accidental use in production.
+    #
+    # @param otto [Otto] The Otto instance to unfreeze
+    # @return [Otto] The unfrozen Otto instance
+    # @raise [RuntimeError] if RSpec is not defined (not in test environment)
+    # @api private
+    def unfreeze_for_testing(otto)
+      raise 'Otto.unfreeze_for_testing is only available in RSpec test environment' unless defined?(RSpec)
+
+      otto.instance_variable_set(:@configuration_frozen, false)
+      otto
     end
   end
   extend ClassMethods

data/otto.gemspec

@@ -10,18 +10,25 @@ Gem::Specification.new do |spec|
   spec.email         = 'gems@solutious.com'
   spec.authors       = ['Delano Mandelbaum']
   spec.license       = 'MIT'
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = if File.directory?('.git') && system('git --version > /dev/null 2>&1')
+                         `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+                       else
+                         Dir['**/*'].select { |f| File.file?(f) }.reject { |f| f.match(%r{^(test|spec|features)/}) }
+                       end
   spec.homepage      = 'https://github.com/delano/otto'
   spec.require_paths = ['lib']
 
   spec.required_ruby_version = ['>= 3.2', '< 4.0']
 
+  spec.add_dependency 'concurrent-ruby', '~> 1.3', '< 2.0'
+  spec.add_dependency 'ipaddr', '~> 1', '< 2.0'
+
   # Logger is not part of the default gems as of Ruby 3.5.0
   spec.add_dependency 'logger', '~> 1', '< 2.0'
 
   spec.add_dependency 'rack', '~> 3.1', '< 4.0'
   spec.add_dependency 'rack-parser', '~> 0.7'
-  spec.add_dependency 'rexml', '>= 3.3.6'
+  spec.add_dependency 'rexml', '~> 3.4'
 
   # Security dependencies
   spec.add_dependency 'facets', '~> 3.1'