otto 2.0.0.pre3 → 2.0.0.pre7

data/lib/otto/core/configuration.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/configuration.rb
+#
+# frozen_string_literal: true
 
 require_relative '../security/csrf'
 require_relative '../security/validator'
@@ -14,6 +14,7 @@ class Otto
     # Configuration module providing locale and application configuration methods
     module Configuration
       include Otto::Core::Freezable
+
       def configure_locale(opts)
         # Check if we have any locale configuration
         has_direct_options = opts[:available_locales] || opts[:default_locale]
@@ -68,9 +69,7 @@ class Otto
         @auth_config[:auth_strategies] = opts[:auth_strategies] if opts[:auth_strategies]
         @auth_config[:default_auth_strategy] = opts[:default_auth_strategy] if opts[:default_auth_strategy]
 
-        # Enable authentication middleware if strategies are configured
-        return unless opts[:auth_strategies] && !opts[:auth_strategies].empty?
-
+        # No-op: authentication strategies are configured via @auth_config above
       end
 
       def configure_mcp(opts)
@@ -143,7 +142,6 @@ class Otto
         # Update existing @auth_config rather than creating a new one
         @auth_config[:auth_strategies] = strategies
         @auth_config[:default_auth_strategy] = default_strategy
-
       end
 
       # Freeze the application configuration to prevent runtime modifications.
@@ -157,38 +155,36 @@ class Otto
       # @return [self]
       def freeze_configuration!
         if frozen_configuration?
-          Otto.logger.debug '[Otto::Configuration] Configuration already frozen, skipping' if Otto.debug
+          Otto.structured_log(:debug, 'Configuration already frozen', { status: 'skipped' }) if Otto.debug
           return self
         end
 
-        Otto.logger.debug '[Otto::Configuration] Starting configuration freeze process' if Otto.debug
+        start_time = Otto::Utils.now_in_μs
 
         # 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'
+
+        duration = Otto::Utils.now_in_μs - start_time
+        frozen_objects = %w[security_config locale_config middleware auth_config option routes]
+        Otto.structured_log(:info, 'Freezing completed',
+          {
+                  duration: duration,
+            frozen_objects: frozen_objects.join(','),
+          })
 
         self
       end
@@ -207,10 +203,9 @@ class Otto
         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
-        @middleware && @middleware.includes?(middleware_class)
+        @middleware&.includes?(middleware_class)
       end
     end
   end

data/lib/otto/core/error_handler.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/error_handler.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require 'json'
@@ -11,10 +11,30 @@ class Otto
     # Error handling module providing secure error reporting and logging functionality
     module ErrorHandler
       def handle_error(error, env)
+        # Check if this is a registered expected error
+        if handler_config = @error_handlers[error.class.name]
+          return handle_expected_error(error, env, handler_config)
+        end
+
         # Log error details internally but don't expose them
         error_id = SecureRandom.hex(8)
-        Otto.logger.error "[#{error_id}] #{error.class}: #{error.message}"
-        Otto.logger.debug "[#{error_id}] Backtrace: #{error.backtrace.join("\n")}" if Otto.debug
+
+        # Base context pattern: create once, reuse for correlation
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        # Include handler context if available (set by route handlers)
+        log_context = base_context.merge(
+          error: error.message,
+          error_class: error.class.name,
+          error_id: error_id
+        )
+        log_context[:handler] = env['otto.handler'] if env['otto.handler']
+        log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
+
+        Otto.structured_log(:error, 'Unhandled error in request', log_context)
+
+        Otto::LoggingHelpers.log_backtrace(error,
+          base_context.merge(error_id: error_id))
 
         # Parse request for content negotiation
         begin
@@ -30,7 +50,21 @@ class Otto
             env['otto.error_id'] = error_id
             return found_route.call(env)
           rescue StandardError => e
-            Otto.logger.error "[#{error_id}] Error in custom error handler: #{e.message}"
+            # When the custom error handler itself fails, generate a new error ID
+            # to distinguish it from the original error, but link them.
+            custom_handler_error_id = SecureRandom.hex(8)
+            base_context = Otto::LoggingHelpers.request_context(env)
+
+            Otto.structured_log(:error, 'Error in custom error handler',
+              base_context.merge(
+                error: e.message,
+                error_class: e.class.name,
+                error_id: custom_handler_error_id,
+                original_error_id: error_id # Link to original error
+              ))
+
+            Otto::LoggingHelpers.log_backtrace(e,
+              base_context.merge(error_id: custom_handler_error_id, original_error_id: error_id))
           end
         end
 
@@ -44,6 +78,102 @@ class Otto
 
       private
 
+      # Handle expected business logic errors with custom status codes and logging
+      #
+      # @param error [Exception] The expected error to handle
+      # @param env [Hash] Rack environment hash
+      # @param handler_config [Hash] Configuration from error_handlers registry
+      # @return [Array] Rack response tuple [status, headers, body]
+      def handle_expected_error(error, env, handler_config)
+        # Generate error ID for correlation (even for expected errors)
+        error_id = SecureRandom.hex(8)
+
+        # Base context pattern: create once, reuse for correlation
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        # Include handler context if available
+        log_context = base_context.merge(
+          error: error.message,
+          error_class: error.class.name,
+          error_id: error_id,
+          expected: true  # Mark as expected error
+        )
+        log_context[:handler] = env['otto.handler'] if env['otto.handler']
+        log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
+
+        # Log at configured level (info/warn instead of error)
+        log_level = handler_config[:log_level] || :info
+        Otto.structured_log(log_level, 'Expected error in request', log_context)
+
+        # Build response body
+        response_body = if handler_config[:handler]
+                          # Use custom handler block if provided
+                          begin
+                            req = Rack::Request.new(env)
+                            result = handler_config[:handler].call(error, req)
+
+                            # Validate that custom handler returned a Hash
+                            unless result.is_a?(Hash)
+                              base_context = Otto::LoggingHelpers.request_context(env)
+                              Otto.structured_log(:warn, 'Custom error handler returned non-hash value',
+                                base_context.merge(
+                                  error_class: error.class.name,
+                                  handler_result_class: result.class.name,
+                                  error_id: error_id
+                                ))
+                              result = { error: error.class.name.split('::').last, message: error.message }
+                            end
+
+                            result
+                          rescue StandardError => e
+                            # If custom handler fails, fall back to default
+                            base_context = Otto::LoggingHelpers.request_context(env)
+                            Otto.structured_log(:warn, 'Error in custom error handler',
+                              base_context.merge(
+                                error: e.message,
+                                error_class: e.class.name,
+                                original_error_class: error.class.name,
+                                error_id: error_id
+                              ))
+                            { error: error.class.name.split('::').last, message: error.message }
+                          end
+                        else
+                          # Default response body
+                          { error: error.class.name.split('::').last, message: error.message }
+                        end
+
+        # Add error_id in development mode
+        response_body[:error_id] = error_id if Otto.env?(:dev, :development)
+
+        # Content negotiation
+        accept_header = env['HTTP_ACCEPT'].to_s
+        status = handler_config[:status] || 500
+
+        if accept_header.include?('application/json')
+          body = JSON.generate(response_body)
+          headers = {
+            'content-type' => 'application/json',
+            'content-length' => body.bytesize.to_s
+          }.merge(@security_config.security_headers)
+
+          [status, headers, [body]]
+        else
+          # Plain text response
+          body = if Otto.env?(:dev, :development)
+                   "#{response_body[:error]}: #{response_body[:message]} (ID: #{error_id})"
+                 else
+                   "#{response_body[:error]}: #{response_body[:message]}"
+                 end
+
+          headers = {
+            'content-type' => 'text/plain',
+            'content-length' => body.bytesize.to_s
+          }.merge(@security_config.security_headers)
+
+          [status, headers, [body]]
+        end
+      end
+
       def secure_error_response(error_id)
         body = if Otto.env?(:dev, :development)
                  "Server error (ID: #{error_id}). Check logs for details."
@@ -62,13 +192,13 @@ class Otto
       def json_error_response(error_id)
         error_data = if Otto.env?(:dev, :development)
                        {
-                         error: 'Internal Server Error',
-                         message: 'Server error occurred. Check logs for details.',
+                            error: 'Internal Server Error',
+                          message: 'Server error occurred. Check logs for details.',
                          error_id: error_id,
                        }
                      else
                        {
-                         error: 'Internal Server Error',
+                           error: 'Internal Server Error',
                          message: 'An error occurred. Please try again later.',
                        }
                      end

data/lib/otto/core/file_safety.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/file_safety.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module Core

data/lib/otto/core/freezable.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/freezable.rb
+#
+# frozen_string_literal: true
 
 require 'set'
 

data/lib/otto/core/middleware_stack.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/middleware_stack.rb
+#
+# frozen_string_literal: true
 
 require_relative 'freezable'
 

data/lib/otto/core/router.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/router.rb
+#
+# frozen_string_literal: true
 
 require_relative '../mcp/route_parser'
 
@@ -36,13 +36,28 @@ class Otto
           route.otto                              = self
           path_clean                              = path.gsub(%r{/$}, '')
           @route_definitions[route.definition]    = route
-          Otto.logger.debug "route: #{route.pattern}" if Otto.debug
+          Otto.structured_log(:debug, "Route loaded",
+            {
+              pattern: route.pattern.source,
+              verb: route.verb,
+              definition: route.definition,
+              type: 'pattern'
+            }
+          ) if Otto.debug
           @routes[route.verb] ||= []
           @routes[route.verb] << route
           @routes_literal[route.verb]           ||= {}
           @routes_literal[route.verb][path_clean] = route
         rescue StandardError => e
-          Otto.logger.error "Error for route #{path}: #{e.message}"
+          Otto.structured_log(:error, "Route load failed",
+            {
+              path: path,
+              verb: verb,
+              definition: definition,
+              error: e.message,
+              error_class: e.class.name
+            }
+          )
           Otto.logger.debug e.backtrace.join("\n") if Otto.debug
         end
         self
@@ -81,14 +96,30 @@ class Otto
         literal_routes.merge! routes_literal[:GET] if http_verb == :HEAD
 
         if static_route && http_verb == :GET && routes_static[:GET].member?(base_path)
-          # Otto.logger.debug " request: #{path_info} (static)"
+          Otto.structured_log(:debug, "Route matched",
+            Otto::LoggingHelpers.request_context(env).merge(
+              type: 'static_cached',
+              base_path: base_path
+            )
+          )
           static_route.call(env)
         elsif literal_routes.has_key?(path_info_clean)
           route = literal_routes[path_info_clean]
-          # Otto.logger.debug " request: #{http_verb} #{path_info} (literal route: #{route.verb} #{route.path})"
+          Otto.structured_log(:debug, "Route matched",
+            Otto::LoggingHelpers.request_context(env).merge(
+              type: 'literal',
+              handler: route.route_definition.definition,
+              auth_strategy: route.route_definition.auth_requirement || 'none'
+            )
+          )
           route.call(env)
         elsif static_route && http_verb == :GET && safe_file?(path_info)
-          Otto.logger.debug " new static route: #{base_path} (#{path_info})" if Otto.debug
+          Otto.structured_log(:debug, "Route matched",
+            Otto::LoggingHelpers.request_context(env).merge(
+              type: 'static_new',
+              base_path: base_path
+            )
+          )
           routes_static[:GET][base_path] = base_path
           static_route.call(env)
         else
@@ -123,7 +154,6 @@ class Otto
         valid_routes.push(*routes[:GET]) if http_verb == :HEAD
 
         valid_routes.each do |route|
-          # Otto.logger.debug " request: #{http_verb} #{path_info} (trying route: #{route.verb} #{route.pattern})"
           next unless (match = route.pattern.match(path_info))
 
           values = match.captures.to_a
@@ -133,13 +163,36 @@ class Otto
           values.shift
           extra_params = build_route_params(route, values)
           found_route  = route
+
+          # Log successful route match
+          Otto.structured_log(:debug, "Route matched",
+            Otto::LoggingHelpers.request_context(env).merge(
+              pattern: route.pattern.source,
+              handler: route.route_definition.definition,
+              auth_strategy: route.route_definition.auth_requirement || 'none',
+              route_params: extra_params
+            )
+          )
           break
         end
 
         found_route ||= literal_routes['/404']
         if found_route
+          # Log 404 route usage if we fell back to it
+          if found_route == literal_routes['/404']
+            Otto.structured_log(:info, "Route not found",
+              Otto::LoggingHelpers.request_context(env).merge(
+                fallback_to: '404_route'
+              )
+            )
+          end
           found_route.call env, extra_params
         else
+          Otto.structured_log(:info, "Route not found",
+            Otto::LoggingHelpers.request_context(env).merge(
+              fallback_to: 'default_not_found'
+            )
+          )
           @not_found || Otto::Static.not_found
         end
       end

data/lib/otto/core/uri_generator.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/core/uri_generator.rb
+#
+# frozen_string_literal: true
 
 require 'uri'
 

data/lib/otto/core.rb

@@ -1,4 +1,6 @@
 # lib/otto/core.rb
+#
+# frozen_string_literal: true
 
 require_relative 'core/router'
 require_relative 'core/file_safety'

data/lib/otto/design_system.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/design_system.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Shared design system for Otto framework examples

data/lib/otto/env_keys.rb

@@ -1,5 +1,7 @@
 # lib/otto/env_keys.rb
 #
+# frozen_string_literal: true
+#
 # Central registry of all env['otto.*'] keys used throughout Otto framework.
 # This documentation helps prevent key conflicts and aids multi-app integration.
 #
@@ -43,19 +45,11 @@ class Otto
     # - Routes WITHOUT auth requirement: Anonymous StrategyResult
     STRATEGY_RESULT = 'otto.strategy_result'
 
-    # Authenticated user object (convenience accessor)
-    # Type: Hash, Custom User Object, or nil
-    # Set by: RouteAuthWrapper (from strategy_result.user)
-    # Used by: Controllers, RouteHandlers
-    # Note: nil for anonymous/unauthenticated requests
-    USER = 'otto.user'
+    # REMOVED: Use strategy_result.user instead
+    # USER = 'otto.user'
 
-    # User-specific context (session, roles, permissions, etc.)
-    # Type: Hash
-    # Set by: RouteAuthWrapper (from strategy_result.user_context)
-    # Used by: Controllers, Analytics
-    # Note: Empty hash {} for anonymous requests
-    USER_CONTEXT = 'otto.user_context'
+    # REMOVED: Use strategy_result.metadata instead
+    # USER_CONTEXT = 'otto.user_context'
 
     # =========================================================================
     # SECURITY & CONFIGURATION
@@ -105,6 +99,61 @@ class Otto
     # Used by: Error responses, logging, support
     ERROR_ID = 'otto.error_id'
 
+    # =========================================================================
+    # PRIVACY (IP MASKING)
+    # =========================================================================
+
+    # Privacy-safe masked IP address
+    # Type: String (e.g., '192.168.1.0')
+    # Set by: IPPrivacyMiddleware
+    # Used by: Rate limiting, analytics, logging
+    module Privacy
+      MASKED_IP = 'otto.privacy.masked_ip'
+
+      # Geo-location country code
+      # Type: String (ISO 3166-1 alpha-2)
+      # Set by: IPPrivacyMiddleware
+      # Used by: Analytics, localization
+      GEO_COUNTRY = 'otto.privacy.geo_country'
+
+      # Daily-rotating IP hash for session correlation
+      # Type: String (hexadecimal)
+      # Set by: IPPrivacyMiddleware
+      # Used by: Session correlation without storing IPs
+      HASHED_IP = 'otto.privacy.hashed_ip'
+
+      # Privacy fingerprint object
+      # Type: Otto::Privacy::RedactedFingerprint
+      # Set by: IPPrivacyMiddleware
+      # Used by: Full privacy context access
+      FINGERPRINT = 'otto.privacy.fingerprint'
+    end
+
+    # =========================================================================
+    # ORIGINAL VALUES (Privacy Disabled)
+    # =========================================================================
+
+    # Original client IP address (only when privacy disabled)
+    # Type: String
+    # Set by: IPPrivacyMiddleware (when privacy disabled)
+    # Used by: Debugging, legitimate use cases requiring real IP
+    # NOTE: Not available when privacy is enabled (intentional)
+    ORIGINAL_IP = 'otto.original_ip'
+
+    # Original User-Agent string (only when privacy disabled)
+    # Type: String
+    # Set by: IPPrivacyMiddleware (when privacy disabled)
+    # Used by: Bot detection, browser feature detection
+    # NOTE: Not available when privacy is enabled (intentional)
+    ORIGINAL_USER_AGENT = 'otto.original_user_agent'
+
+    # Original Referer URL (only when privacy disabled)
+    # Type: String
+    # Set by: IPPrivacyMiddleware (when privacy disabled)
+    # Used by: Analytics, debugging
+    # NOTE: Not available when privacy is enabled (intentional)
+    ORIGINAL_REFERER = 'otto.original_referer'
+
     # =========================================================================
     # MCP (MODEL CONTEXT PROTOCOL)
     # =========================================================================

data/lib/otto/helpers/base.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/base.rb
+#
+# frozen_string_literal: true
 
 class Otto
   # Base helper methods providing core functionality for Otto applications

data/lib/otto/helpers/request.rb

@@ -1,4 +1,6 @@
 # lib/otto/helpers/request.rb
+#
+# frozen_string_literal: true
 
 require_relative 'base'
 
@@ -56,14 +58,17 @@ class Otto
     # Get anonymized user agent string
     #
     # Returns user agent with version numbers stripped for privacy.
-    # Only available when IP privacy is enabled (default).
+    # When privacy is enabled (default), env['HTTP_USER_AGENT'] is already
+    # anonymized by IPPrivacyMiddleware, so this just returns that value.
+    # When privacy is disabled, returns the raw user agent.
     #
-    # @return [String, nil] Anonymized user agent or nil
+    # @return [String, nil] Anonymized (or raw if privacy disabled) user agent
     # @example
     #   req.anonymized_user_agent
     #   # => 'Mozilla/X.X (Windows NT X.X; Win64; x64) AppleWebKit/X.X'
+    # @deprecated Use env['HTTP_USER_AGENT'] directly (already anonymized when privacy enabled)
     def anonymized_user_agent
-      redacted_fingerprint&.anonymized_ua
+      user_agent
     end
 
     # Get masked IP address

data/lib/otto/helpers/response.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/response.rb
+#
+# frozen_string_literal: true
 
 require_relative 'base'
 

data/lib/otto/helpers/validation.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/validation.rb
+#
+# frozen_string_literal: true
 
 require 'loofah'
 require 'facets/file'

data/lib/otto/helpers.rb

@@ -1,4 +1,6 @@
 # lib/otto/helpers.rb
+#
+# frozen_string_literal: true
 
 require_relative 'helpers/request'
 require_relative 'helpers/response'

data/lib/otto/locale/config.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/locale/config.rb
+#
+# frozen_string_literal: true
 
 require_relative '../core/freezable'