otto 2.0.0.pre2 → 2.0.0.pre7

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
@@ -51,7 +66,7 @@ class Otto
       def handle_request(env)
         locale             = determine_locale env
         env['rack.locale'] = locale
-        env['otto.locale_config'] = @locale_config if @locale_config
+        env['otto.locale_config'] = @locale_config.to_h if @locale_config
         @static_route    ||= Rack::Files.new(option[:public]) if option[:public] && safe_dir?(option[:public])
         path_info          = Rack::Utils.unescape(env['PATH_INFO'])
         path_info          = '/' if path_info.to_s.empty?
@@ -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

@@ -0,0 +1,10 @@
+# lib/otto/core.rb
+#
+# frozen_string_literal: true
+
+require_relative 'core/router'
+require_relative 'core/file_safety'
+require_relative 'core/configuration'
+require_relative 'core/error_handler'
+require_relative 'core/uri_generator'
+require_relative 'core/middleware_stack'

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.
 #
@@ -36,22 +38,18 @@ class Otto
 
     # Authentication strategy result containing session/user state
     # Type: Otto::Security::Authentication::StrategyResult
-    # Set by: AuthenticationMiddleware
+    # Set by: RouteAuthWrapper (wraps all route handlers)
     # Used by: RouteHandlers, LogicClasses, Controllers
-    # Note: Always present (anonymous or authenticated)
+    # Guarantee: ALWAYS present - either authenticated or anonymous
+    # - Routes WITH auth requirement: Authenticated StrategyResult or 401/302
+    # - 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: AuthenticationMiddleware (from strategy_result.user)
-    # Used by: Controllers, RouteHandlers
-    USER = 'otto.user'
+    # REMOVED: Use strategy_result.user instead
+    # USER = 'otto.user'
 
-    # User-specific context (session, roles, permissions, etc.)
-    # Type: Hash
-    # Set by: AuthenticationMiddleware (from strategy_result.user_context)
-    # Used by: Controllers, Analytics
-    USER_CONTEXT = 'otto.user_context'
+    # REMOVED: Use strategy_result.metadata instead
+    # USER_CONTEXT = 'otto.user_context'
 
     # =========================================================================
     # SECURITY & CONFIGURATION
@@ -101,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,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/helpers/request.rb
+#
+# frozen_string_literal: true
 
 require_relative 'base'
 
@@ -13,6 +13,89 @@ class Otto
       env['HTTP_USER_AGENT']
     end
 
+    # NOTE: We do NOT override Rack::Request#ip
+    #
+    # IPPrivacyMiddleware masks both REMOTE_ADDR and X-Forwarded-For headers,
+    # so Rack's native ip resolution logic works correctly with masked values.
+    # This allows Rack to handle proxy scenarios (trusted proxies, header parsing)
+    # while still returning privacy-safe masked IPs.
+    #
+    # If you need the masked IP explicitly, use:
+    #   req.masked_ip  # => '192.168.1.0' or nil if privacy disabled
+    #
+    # If you need the geo country:
+    #   req.geo_country  # => 'US' or nil
+    #
+    # If you need the full privacy fingerprint:
+    #   req.redacted_fingerprint  # => RedactedFingerprint object or nil
+
+    # Get the privacy-safe fingerprint for this request
+    #
+    # Returns nil if IP privacy is disabled. The fingerprint contains
+    # anonymized request information suitable for logging and analytics.
+    #
+    # @return [Otto::Privacy::RedactedFingerprint, nil] Privacy-safe fingerprint
+    # @example
+    #   fingerprint = req.redacted_fingerprint
+    #   fingerprint.masked_ip    # => '192.168.1.0'
+    #   fingerprint.country      # => 'US'
+    def redacted_fingerprint
+      env['otto.redacted_fingerprint']
+    end
+
+    # Get the geo-location country code for the request
+    #
+    # Returns ISO 3166-1 alpha-2 country code or 'XX' for unknown.
+    # Only available when IP privacy is enabled (default).
+    #
+    # @return [String, nil] Country code or nil if privacy disabled
+    # @example
+    #   req.geo_country  # => 'US'
+    def geo_country
+      redacted_fingerprint&.country || env['otto.geo_country']
+    end
+
+    # Get anonymized user agent string
+    #
+    # Returns user agent with version numbers stripped for privacy.
+    # 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 (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
+      user_agent
+    end
+
+    # Get masked IP address
+    #
+    # Returns privacy-safe masked IP. When privacy is enabled (default),
+    # this returns the masked version. When disabled, returns original IP.
+    #
+    # @return [String, nil] Masked or original IP address
+    # @example
+    #   req.masked_ip  # => '192.168.1.0'
+    def masked_ip
+      env['otto.masked_ip'] || env['REMOTE_ADDR']
+    end
+
+    # Get hashed IP for session correlation
+    #
+    # Returns daily-rotating hash of the IP address, allowing session
+    # tracking without storing the original IP. Only available when
+    # IP privacy is enabled (default).
+    #
+    # @return [String, nil] Hexadecimal hash string or nil
+    # @example
+    #   req.hashed_ip  # => 'a3f8b2c4d5e6f7...'
+    def hashed_ip
+      redacted_fingerprint&.hashed_ip || env['otto.hashed_ip']
+    end
+
     def client_ipaddress
       remote_addr = env['REMOTE_ADDR']
 

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'
 
@@ -14,10 +14,10 @@ class Otto
     def send_secure_cookie(name, value, ttl, opts = {})
       # Default security options
       defaults = {
-        secure: true,
-        httponly: true,
+           secure: true,
+         httponly: true,
         same_site: :strict,
-        path: '/',
+             path: '/',
       }
 
       # Merge with provided options

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

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

data/lib/otto/locale/config.rb

@@ -0,0 +1,56 @@
+# lib/otto/locale/config.rb
+#
+# frozen_string_literal: true
+
+require_relative '../core/freezable'
+
+class Otto
+  module Locale
+    # Locale configuration for Otto applications
+    #
+    # This class manages locale-related settings including available locales
+    # and default locale selection.
+    #
+    # @example Basic usage
+    #   config = Otto::Locale::Config.new
+    #   config.available_locales = { 'en' => 'English', 'es' => 'Spanish' }
+    #   config.default_locale = 'en'
+    #
+    # @example With initialization
+    #   config = Otto::Locale::Config.new(
+    #     available_locales: { 'en' => 'English', 'fr' => 'French' },
+    #     default_locale: 'en'
+    #   )
+    class Config
+      include Otto::Core::Freezable
+
+      attr_accessor :available_locales, :default_locale
+
+      # Initialize locale configuration
+      #
+      # @param available_locales [Hash, nil] Hash of locale codes to names
+      # @param default_locale [String, nil] Default locale code
+      def initialize(available_locales: nil, default_locale: nil)
+        @available_locales = available_locales
+        @default_locale = default_locale
+      end
+
+      # Convert to hash for compatibility with existing code
+      #
+      # @return [Hash] Hash representation of configuration
+      def to_h
+        {
+          available_locales: @available_locales,
+          default_locale: @default_locale,
+        }.compact
+      end
+
+      # Check if locale configuration is present
+      #
+      # @return [Boolean] true if either available_locales or default_locale is set
+      def configured?
+        !@available_locales.nil? || !@default_locale.nil?
+      end
+    end
+  end
+end

data/lib/otto/locale/middleware.rb

@@ -0,0 +1,160 @@
+# lib/otto/locale/middleware.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Locale
+    # Locale detection and resolution middleware
+    #
+    # Sets env['otto.locale'] based on:
+    # 1. URL parameter (?locale=es)
+    # 2. Session preference (session['locale'])
+    # 3. HTTP Accept-Language header
+    # 4. Default locale
+    #
+    # Configuration:
+    #   use Otto::Locale::Middleware,
+    #     available_locales: { 'en' => 'English', 'es' => 'Spanish' },
+    #     default_locale: 'en',
+    #     debug: false
+    #
+    # @example Basic usage
+    #   use Otto::Locale::Middleware,
+    #     available_locales: { 'en' => 'English', 'es' => 'Español', 'fr' => 'Français' },
+    #     default_locale: 'en'
+    #
+    # @example With session persistence
+    #   use Rack::Session::Cookie, secret: 'secret'
+    #   use Otto::Locale::Middleware,
+    #     available_locales: { 'en' => 'English', 'es' => 'Español' },
+    #     default_locale: 'en'
+    #
+    class Middleware
+      attr_reader :available_locales, :default_locale
+
+      # Initialize locale middleware
+      #
+      # @param app [#call] Rack application
+      # @param available_locales [Hash<String, String>] Hash of locale codes to language names
+      # @param default_locale [String] Default locale code
+      # @param debug [Boolean] Enable debug logging
+      def initialize(app, available_locales:, default_locale:, debug: false)
+        @app = app
+        @available_locales = available_locales
+        @default_locale = default_locale
+        @debug = debug
+
+        validate_config!
+      end
+
+      # Process request and set locale
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] Rack response tuple [status, headers, body]
+      def call(env)
+        locale = detect_locale(env)
+        env['otto.locale'] = locale
+
+        debug_log(env, locale) if @debug
+
+        @app.call(env)
+      end
+
+      private
+
+      # Detect locale using priority chain
+      #
+      # @param env [Hash] Rack environment
+      # @return [String] Resolved locale code
+      def detect_locale(env)
+        # 1. Check URL parameter
+        req = Rack::Request.new(env)
+        locale = req.params['locale']
+        return locale if valid_locale?(locale)
+
+        # 2. Check session
+        session = env['rack.session']
+        locale = session['locale'] if session
+        return locale if valid_locale?(locale)
+
+        # 3. Parse Accept-Language header
+        locale = parse_accept_language(env['HTTP_ACCEPT_LANGUAGE'])
+        return locale if valid_locale?(locale)
+
+        # 4. Default
+        @default_locale
+      end
+
+      # Parse Accept-Language header with RFC 2616 quality value support
+      #
+      # Handles formats like:
+      # - "en-US,en;q=0.9,fr;q=0.8" → finds first available from [en, en, fr]
+      # - "es,en;q=0.9" → returns "en" if "es" unavailable but "en" is
+      # - "fr-CA" → "fr"
+      #
+      # Respects q-values (quality factors) and returns the highest-priority
+      # available locale instead of just the first language tag.
+      #
+      # @param header [String, nil] Accept-Language header value
+      # @return [String, nil] Best matching available locale code or nil
+      def parse_accept_language(header)
+        return nil unless header
+
+        # Parse all language tags with their q-values
+        # Format: "en-US,en;q=0.9,fr;q=0.8" → [[en-US, 1.0], [en, 0.9], [fr, 0.8]]
+        languages = header.split(',').map do |tag|
+          # Split on semicolon and extract q-value
+          parts = tag.strip.split(/\s*;\s*q\s*=\s*/)
+          locale_str = parts[0]
+          q_value = parts[1] ? parts[1].to_f : 1.0
+          [locale_str, q_value]
+        end
+
+        # Sort by q-value descending (highest preference first)
+        # and find the first locale that matches available_locales
+        languages.sort_by { |_, q| -q }.each do |lang_tag, _|
+          # Extract primary language code: "en-US" → "en", "fr" → "fr"
+          locale_code = lang_tag.split('-').first.downcase
+          return locale_code if valid_locale?(locale_code)
+        end
+
+        nil # No matching locale found
+      rescue StandardError => ex
+        Otto.logger&.warn "[Otto::Locale] Failed to parse Accept-Language: #{ex.message}"
+        nil
+      end
+
+      # Check if locale is valid
+      #
+      # @param locale [String, nil] Locale code to validate
+      # @return [Boolean] true if locale is in available_locales
+      def valid_locale?(locale)
+        return false unless locale
+        @available_locales.key?(locale.to_s)
+      end
+
+      # Validate middleware configuration
+      #
+      # @raise [ArgumentError] if configuration is invalid
+      def validate_config!
+        raise ArgumentError, 'available_locales must be a Hash' unless @available_locales.is_a?(Hash)
+        raise ArgumentError, 'available_locales cannot be empty' if @available_locales.empty?
+        raise ArgumentError, 'default_locale must be in available_locales' unless @available_locales.key?(@default_locale)
+      end
+
+      # Log debug information about locale detection
+      #
+      # @param env [Hash] Rack environment
+      # @param locale [String] Resolved locale
+      def debug_log(env, locale)
+        Otto.logger&.debug format(
+          '[Otto::Locale] Selected locale=%s (param=%s session=%s header=%s)',
+          locale,
+          Rack::Request.new(env).params['locale'] || 'nil',
+          env['rack.session']&.dig('locale') || 'nil',
+          env['HTTP_ACCEPT_LANGUAGE']&.split(',')&.first || 'nil'
+        )
+      end
+    end
+  end
+end

data/lib/otto/locale.rb

@@ -0,0 +1,10 @@
+# lib/otto/locale.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Locale
+    autoload :Config, 'otto/locale/config'
+    autoload :Middleware, 'otto/locale/middleware'
+  end
+end