otto 1.3.0 → 1.5.0

data/lib/otto/helpers/base.rb

@@ -0,0 +1,27 @@
+# lib/otto/helpers/base.rb
+
+class Otto
+  module BaseHelpers
+    # Build application path by joining path segments
+    #
+    # This method safely joins multiple path segments, handling
+    # duplicate slashes and ensuring proper path formatting.
+    # Includes the script name (mount point) as the first segment.
+    #
+    # @param paths [Array<String>] Path segments to join
+    # @return [String] Properly formatted path
+    #
+    # @example
+    #   app_path('api', 'v1', 'users')
+    #   # => "/myapp/api/v1/users"
+    #
+    # @example
+    #   app_path(['admin', 'settings'])
+    #   # => "/myapp/admin/settings"
+    def app_path(*paths)
+      paths = paths.flatten.compact
+      paths.unshift(env['SCRIPT_NAME']) if env['SCRIPT_NAME']
+      paths.join('/').gsub('//', '/')
+    end
+  end
+end

data/lib/otto/helpers/request.rb

@@ -1,7 +1,11 @@
 # lib/otto/helpers/request.rb
 
+require_relative 'base'
+
 class Otto
   module RequestHelpers
+    include Otto::BaseHelpers
+
     def user_agent
       env['HTTP_USER_AGENT']
     end
@@ -70,7 +74,11 @@ class Otto
       ip = client_ipaddress
       return false unless ip
 
-      local_or_private_ip?(ip)
+      # Check both IP and server name for comprehensive localhost detection
+      server_name        = env['SERVER_NAME']
+      local_server_names = ['localhost', '127.0.0.1', '0.0.0.0']
+
+      local_or_private_ip?(ip) && local_server_names.include?(server_name)
     end
 
     def secure?
@@ -107,8 +115,6 @@ class Otto
       [prefix, http_host, request_path].join
     end
 
-    private
-
     def otto_security_config
       # Try to get security config from various sources
       if respond_to?(:otto) && otto.respond_to?(:security_config)
@@ -136,7 +142,7 @@ class Otto
 
       # Validate each octet
       octets = clean_ip.split('.')
-      return nil unless octets.all? { |octet| (0..255).include?(octet.to_i) }
+      return nil unless octets.all? { |octet| (0..255).cover?(octet.to_i) }
 
       clean_ip
     end
@@ -166,5 +172,218 @@ class Otto
       # Check for private IP ranges
       private_ip?(ip)
     end
+
+    # Collect and format HTTP header details from the request environment
+    #
+    # This method extracts and formats specific HTTP headers, including
+    # Cloudflare and proxy-related headers, for logging and debugging purposes.
+    #
+    # @param header_prefix [String, nil] Custom header prefix to include (e.g. 'X_SECRET_')
+    # @param additional_keys [Array<String>] Additional header keys to collect
+    # @return [String] Formatted header details as "key: value" pairs
+    #
+    # @example Basic usage
+    #   collect_proxy_headers
+    #   # => "X-Forwarded-For: 203.0.113.195 Remote-Addr: 192.0.2.1"
+    #
+    #
+    # @example With custom prefix
+    #   collect_proxy_headers(header_prefix: 'X_CUSTOM_')
+    #   # => "X-Forwarded-For: 203.0.113.195 X-Custom-Token: abc123"
+    def collect_proxy_headers(header_prefix: nil, additional_keys: [])
+      keys = %w[
+        HTTP_FLY_REQUEST_ID
+        HTTP_VIA
+        HTTP_X_FORWARDED_PROTO
+        HTTP_X_FORWARDED_FOR
+        HTTP_X_FORWARDED_HOST
+        HTTP_X_FORWARDED_PORT
+        HTTP_X_SCHEME
+        HTTP_X_REAL_IP
+        HTTP_CF_IPCOUNTRY
+        HTTP_CF_RAY
+        REMOTE_ADDR
+      ]
+
+      # Add any header that begins with the specified prefix
+      if header_prefix
+        prefix_keys = env.keys.select { |key| key.upcase.start_with?("HTTP_#{header_prefix.upcase}") }
+        keys.concat(prefix_keys)
+      end
+
+      # Add any additional keys requested
+      keys.concat(additional_keys) if additional_keys.any?
+
+      keys.sort.filter_map do |key|
+        value = env[key]
+        next unless value
+
+        # Normalize the header name to look like browser dev console
+        # e.g. Content-Type instead of HTTP_CONTENT_TYPE
+        pretty_name = key.sub(/^HTTP_/, '').split('_').map(&:capitalize).join('-')
+        "#{pretty_name}: #{value}"
+      end.join(' ')
+    end
+
+    # Format request details as a single string for logging
+    #
+    # This method combines IP address, HTTP method, path, query parameters,
+    # and proxy header details into a single formatted string suitable for logging.
+    #
+    # @param header_prefix [String, nil] Custom header prefix for proxy headers
+    # @return [String] Formatted request details
+    #
+    # @example
+    #   format_request_details
+    #   # => "192.0.2.1; GET /path?query=string; Proxy[X-Forwarded-For: 203.0.113.195 Remote-Addr: 192.0.2.1]"
+    #
+    def format_request_details(header_prefix: nil)
+      header_details = collect_proxy_headers(header_prefix: header_prefix)
+
+      details = [
+        client_ipaddress,
+        "#{request_method} #{env['PATH_INFO']}?#{env['QUERY_STRING']}",
+        "Proxy[#{header_details}]",
+      ]
+
+      details.join('; ')
+    end
+
+    # Check if user agent matches blocked patterns
+    #
+    # This method checks if the current request's user agent string
+    # matches any of the provided blocked agent patterns.
+    #
+    # @param blocked_agents [Array<String, Symbol, Regexp>] Patterns to check against
+    # @return [Boolean] true if user agent is allowed, false if blocked
+    #
+    # @example
+    #   blocked_user_agent?([:bot, :crawler, 'BadAgent'])
+    #   # => false if user agent contains 'bot', 'crawler', or 'BadAgent'
+    def blocked_user_agent?(blocked_agents: [])
+      return true if blocked_agents.empty?
+
+      user_agent_string = user_agent.to_s.downcase
+      return true if user_agent_string.empty?
+
+      blocked_agents.flatten.any? do |agent|
+        case agent
+        when Regexp
+          user_agent_string.match?(agent)
+        else
+          user_agent_string.include?(agent.to_s.downcase)
+        end
+      end
+    end
+
+    # Build application path by joining path segments
+    #
+    # This method safely joins multiple path segments, handling
+    # duplicate slashes and ensuring proper path formatting.
+    # Includes the script name (mount point) as the first segment.
+    #
+    # @param paths [Array<String>] Path segments to join
+    # @return [String] Properly formatted path
+    #
+    # @example
+    #   app_path('api', 'v1', 'users')
+    #   # => "/myapp/api/v1/users"
+    #
+    # @example
+    #   app_path(['admin', 'settings'])
+    #   # => "/myapp/admin/settings"
+    def app_path(*paths)
+      paths = paths.flatten.compact
+      paths.unshift(env['SCRIPT_NAME']) if env['SCRIPT_NAME']
+      paths.join('/').gsub('//', '/')
+    end
+
+    # Set the locale for the request based on multiple sources
+    #
+    # This method determines the locale to be used for the request by checking
+    # the following sources in order of precedence:
+    # 1. The locale parameter passed to the method
+    # 2. The locale query parameter in the request
+    # 3. The user's saved locale preference (if provided)
+    # 4. The rack.locale environment variable
+    #
+    # If a valid locale is found, it's stored in the request environment.
+    # If no valid locale is found, the default locale is used.
+    #
+    # @param locale [String, nil] The locale to use, if specified
+    # @param opts [Hash] Configuration options
+    # @option opts [Hash] :available_locales Hash of available locales to validate against (required unless configured at Otto level)
+    # @option opts [String] :default_locale Default locale to use as fallback (required unless configured at Otto level)
+    # @option opts [String, nil] :preferred_locale User's saved locale preference
+    # @option opts [String] :locale_env_key Environment key to store the locale (default: 'locale')
+    # @option opts [Boolean] :debug Enable debug logging for locale selection
+    # @return [String] The selected locale
+    #
+    # @example Basic usage
+    #   check_locale!(
+    #     available_locales: { 'en' => 'English', 'es' => 'Spanish' },
+    #     default_locale: 'en'
+    #   )
+    #   # => 'en'
+    #
+    # @example With user preference
+    #   check_locale!(nil, {
+    #     available_locales: { 'en' => 'English', 'es' => 'Spanish' },
+    #     default_locale: 'en',
+    #     preferred_locale: 'es'
+    #   })
+    #   # => 'es'
+    #
+    # @example Using Otto-level configuration
+    #   # Otto configured with: Otto.new(routes, { locale_config: { available: {...}, default: 'en' } })
+    #   check_locale!('es')  # Uses Otto's config automatically
+    #   # => 'es'
+    #
+    def check_locale!(locale = nil, opts = {})
+      # Get configuration from options, Otto config, or environment (in that order)
+      otto_config = env['otto.locale_config']
+
+      available_locales = opts[:available_locales] ||
+                          otto_config&.dig(:available_locales) ||
+                          env['otto.available_locales']
+      default_locale    = opts[:default_locale] ||
+                          otto_config&.dig(:default_locale) ||
+                          env['otto.default_locale']
+      preferred_locale  = opts[:preferred_locale]
+      locale_env_key    = opts[:locale_env_key] || 'locale'
+      debug_enabled     = opts[:debug] || false
+
+      # Guard clause - required configuration must be present
+      unless available_locales && default_locale
+        raise ArgumentError, 'available_locales and default_locale are required (provide via opts or Otto configuration)'
+      end
+
+      # Check sources in order of precedence
+      locale ||= env['rack.request.query_hash'] && env['rack.request.query_hash']['locale']
+      locale ||= preferred_locale if preferred_locale
+      locale ||= (env['rack.locale'] || []).first
+
+      # Validate locale against available translations
+      have_translations = locale && available_locales.key?(locale.to_s)
+
+      # Debug logging if enabled
+      if debug_enabled && defined?(Otto.logger)
+        message = format(
+          '[check_locale!] sources[param=%s query=%s user=%s rack=%s] valid=%s',
+          locale,
+          env.dig('rack.request.query_hash', 'locale'),
+          preferred_locale,
+          (env['rack.locale'] || []).first,
+          have_translations
+        )
+        Otto.logger.debug message
+      end
+
+      # Set the locale in request environment
+      selected_locale = have_translations ? locale : default_locale
+      env[locale_env_key] = selected_locale
+
+      selected_locale
+    end
   end
 end

data/lib/otto/helpers/response.rb

@@ -1,7 +1,11 @@
 # lib/otto/helpers/response.rb
 
+require_relative 'base'
+
 class Otto
   module ResponseHelpers
+    include Otto::BaseHelpers
+
     attr_accessor :request
 
     def send_secure_cookie(name, value, ttl, opts = {})
@@ -76,5 +80,76 @@ class Otto
 
       headers
     end
+
+    # Set Content Security Policy (CSP) headers with nonce support
+    #
+    # This method generates and sets CSP headers with the provided nonce value,
+    # following the same usage pattern as send_cookie methods. The CSP policy
+    # is generated dynamically based on the security configuration and environment.
+    #
+    # @param content_type [String] Content-Type header value to set
+    # @param nonce [String] Nonce value to include in CSP directives
+    # @param opts [Hash] Options for CSP generation
+    # @option opts [Otto::Security::Config] :security_config Security config to use
+    # @option opts [Boolean] :development_mode Use development-friendly CSP directives
+    # @option opts [Boolean] :debug Enable debug logging for this request
+    # @return [void]
+    #
+    # @example Basic usage
+    #   nonce = SecureRandom.base64(16)
+    #   res.send_csp_headers('text/html; charset=utf-8', nonce)
+    #
+    # @example With options
+    #   res.send_csp_headers('text/html; charset=utf-8', nonce, {
+    #     development_mode: Rails.env.development?,
+    #     debug: true
+    #   })
+    def send_csp_headers(content_type, nonce, opts = {})
+      # Set content type if not already set
+      headers['content-type'] ||= content_type
+
+      # Warn if CSP header already exists but don't skip
+      if headers['content-security-policy']
+        warn 'CSP header already set, overriding with nonce-based policy'
+      end
+
+      # Get security configuration
+      security_config = opts[:security_config] ||
+                        (request&.env && request.env['otto.security_config']) ||
+                        nil
+
+      # Skip if CSP nonce support is not enabled
+      return unless security_config&.csp_nonce_enabled?
+
+      # Generate CSP policy with nonce
+      development_mode = opts[:development_mode] || false
+      csp_policy       = security_config.generate_nonce_csp(nonce, development_mode: development_mode)
+
+      # Debug logging if enabled
+      debug_enabled = opts[:debug] || security_config.debug_csp?
+      if debug_enabled && defined?(Otto.logger)
+        Otto.logger.debug "[CSP] #{csp_policy}"
+      end
+
+      # Set the CSP header
+      headers['content-security-policy'] = csp_policy
+    end
+
+    # Set cache control headers to prevent caching
+    #
+    # This method sets comprehensive cache control headers to ensure that
+    # the response is not cached by browsers, proxies, or CDNs. This is
+    # particularly useful for sensitive pages or dynamic content that
+    # should always be fresh.
+    #
+    # @return [void]
+    #
+    # @example
+    #   res.no_cache!
+    def no_cache!
+      headers['cache-control'] = 'no-store, no-cache, must-revalidate, max-age=0'
+      headers['expires']       = 'Mon, 7 Nov 2011 00:00:00 UTC'
+      headers['pragma']        = 'no-cache'
+    end
   end
 end

data/lib/otto/response_handlers.rb

@@ -0,0 +1,141 @@
+# lib/otto/response_handlers.rb
+
+class Otto
+  module ResponseHandlers
+    # Base response handler class
+    class BaseHandler
+      def self.handle(result, response, context = {})
+        raise NotImplementedError, "Subclasses must implement handle method"
+      end
+
+      protected
+
+      def self.ensure_status_set(response, default_status = 200)
+        response.status = default_status unless response.status && response.status != 0
+      end
+    end
+
+    # Handler for JSON responses
+    class JSONHandler < BaseHandler
+      def self.handle(result, response, context = {})
+        response['Content-Type'] = 'application/json'
+
+        # Determine the data to serialize
+        data = if context[:logic_instance]&.respond_to?(:response_data)
+                 context[:logic_instance].response_data
+               elsif result.is_a?(Hash)
+                 result
+               elsif result.nil?
+                 { success: true }
+               else
+                 { success: true, data: result }
+               end
+
+        response.body = [JSON.generate(data)]
+        ensure_status_set(response, context[:status_code] || 200)
+      end
+    end
+
+    # Handler for redirect responses
+    class RedirectHandler < BaseHandler
+      def self.handle(result, response, context = {})
+        # Determine redirect path
+        path = if context[:redirect_path]
+                 context[:redirect_path]
+               elsif context[:logic_instance]&.respond_to?(:redirect_path)
+                 context[:logic_instance].redirect_path
+               elsif result.is_a?(String)
+                 result
+               else
+                 '/'
+               end
+
+        response.redirect(path)
+      end
+    end
+
+    # Handler for view/template responses
+    class ViewHandler < BaseHandler
+      def self.handle(result, response, context = {})
+        if context[:logic_instance]&.respond_to?(:view)
+          response.body = [context[:logic_instance].view.render]
+          response['Content-Type'] = 'text/html' unless response['Content-Type']
+        elsif result.respond_to?(:to_s)
+          response.body = [result.to_s]
+          response['Content-Type'] = 'text/html' unless response['Content-Type']
+        else
+          response.body = ['']
+        end
+
+        ensure_status_set(response, context[:status_code] || 200)
+      end
+    end
+
+    # Default handler that preserves existing Otto behavior
+    class DefaultHandler < BaseHandler
+      def self.handle(result, response, context = {})
+        # Otto's default behavior - let the route handler manage the response
+        # This handler does nothing, preserving existing behavior
+        ensure_status_set(response, 200)
+      end
+    end
+
+    # Auto-detection handler that chooses appropriate handler based on context
+    class AutoHandler < BaseHandler
+      def self.handle(result, response, context = {})
+        # Auto-detect based on result type and request context
+        handler_class = detect_handler_type(result, response, context)
+        handler_class.handle(result, response, context)
+      end
+
+      private
+
+      def self.detect_handler_type(result, response, context)
+        # Check if response type was already set by the handler
+        content_type = response['Content-Type']
+
+        if content_type&.include?('application/json')
+          JSONHandler
+        elsif (context[:logic_instance]&.respond_to?(:redirect_path) && context[:logic_instance]&.redirect_path) ||
+              (result.is_a?(String) && result.match?(%r{^/}))
+          # Logic instance has redirect path or result is a string path
+          RedirectHandler
+        elsif result.is_a?(Hash)
+          JSONHandler
+        elsif context[:logic_instance]&.respond_to?(:view)
+          ViewHandler
+        else
+          DefaultHandler
+        end
+      end
+    end
+
+    # Factory for creating response handlers
+    class HandlerFactory
+      # Map of response type names to handler classes
+      HANDLER_MAP = {
+        'json' => JSONHandler,
+        'redirect' => RedirectHandler,
+        'view' => ViewHandler,
+        'auto' => AutoHandler,
+        'default' => DefaultHandler
+      }.freeze
+
+      def self.create_handler(response_type)
+        handler_class = HANDLER_MAP[response_type.to_s.downcase]
+
+        unless handler_class
+          Otto.logger.warn "Unknown response type: #{response_type}, falling back to default" if Otto.debug
+          handler_class = DefaultHandler
+        end
+
+        handler_class
+      end
+
+      def self.handle_response(result, response, response_type, context = {})
+        handler = create_handler(response_type)
+        handler.handle(result, response, context)
+      end
+    end
+  end
+end