otto 2.0.0.pre3 → 2.0.0.pre7

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

data/lib/otto/logging_helpers.rb

@@ -0,0 +1,273 @@
+# lib/otto/logging_helpers.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  # LoggingHelpers provides utility methods for consistent structured logging
+  # across the Otto framework. Centralizes common request context extraction
+  # to eliminate duplication while keeping logging calls simple and explicit.
+  module LoggingHelpers
+    # Structured logging helpers for Otto framework.
+    #
+    # BASE CONTEXT PATTERN (recommended for downstream projects):
+    #
+    # Create base context once per error/event, then merge event-specific fields.
+    #
+    # THREAD SAFETY: This pattern is thread-safe for concurrent requests. Each
+    # request has its own `env` hash, so `request_context(env)` creates isolated
+    # context hashes per request. The pattern extracts immutable values (strings,
+    # symbols) from `env`, and `.merge()` creates new hashes rather than mutating
+    # shared state. Safe for use in multi-threaded Rack servers (Puma, Falcon).
+    #
+    #   base_context = Otto::LoggingHelpers.request_context(env)
+    #
+    #   Otto.structured_log(:error, "Handler failed",
+    #     base_context.merge(
+    #       error: error.message,
+    #       error_class: error.class.name,
+    #       error_id: error_id,
+    #       duration: duration
+    #     )
+    #   )
+    #
+    #   Otto::LoggingHelpers.log_backtrace(error,
+    #     base_context.merge(error_id: error_id, handler: 'Controller#action')
+    #   )
+    #
+    # DOWNSTREAM EXTENSIBILITY:
+    #
+    # Large projects can inject custom shared fields:
+    #
+    #   custom_base = Otto::LoggingHelpers.request_context(env).merge(
+    #     transaction_id: Thread.current[:transaction_id],
+    #     user_id: env['otto.user']&.id,
+    #     tenant_id: env['tenant_id']
+    #   )
+    #
+    #   Otto.structured_log(:error, "Business operation failed",
+    #     custom_base.merge(
+    #       error: error.message,
+    #       error_class: error.class.name,
+    #       account_id: account.id,
+    #       operation: :withdrawal
+    #     )
+    #   )
+    #
+
+    # Extract common request context for structured logging
+    #
+    # Returns a hash containing privacy-aware request metadata suitable
+    # for merging with event-specific data in Otto.structured_log calls.
+    #
+    # @param env [Hash] Rack environment hash
+    # @return [Hash] Request context with method, path, ip, country, user_agent
+    #
+    # @example Basic usage
+    #   Otto.structured_log(:info, "Route matched",
+    #     Otto::LoggingHelpers.request_context(env).merge(
+    #       type: 'literal',
+    #       handler: 'App#index'
+    #     )
+    #   )
+    #
+    # @note IP addresses are already masked by IPPrivacyMiddleware (public IPs only)
+    # @note User agents are truncated to 100 chars to prevent log bloat
+    def self.request_context(env)
+      {
+            method: env['REQUEST_METHOD'],
+              path: env['PATH_INFO'],
+                ip: env['REMOTE_ADDR'], # Already masked by IPPrivacyMiddleware for public IPs
+           country: env['otto.geo_country'],
+        user_agent: env['HTTP_USER_AGENT']&.slice(0, 100), # Already anonymized by IPPrivacyMiddleware
+      }.compact
+    end
+
+    # Log a timed operation with consistent timing and error handling
+    #
+    # @param level [Symbol] The log level (:debug, :info, :warn, :error)
+    # @param message [String] The log message
+    # @param env [Hash] Rack environment for request context
+    # @param metadata [Hash] Additional metadata to include in the log
+    # @yield The block to execute and time
+    # @return The result of the block
+    #
+    # @example
+    #   Otto::LoggingHelpers.log_timed_operation(:info, "Template compiled", env,
+    #     template_type: 'handlebars', cached: false
+    #   ) do
+    #     compile_template(template)
+    #   end
+    #
+    def self.log_timed_operation(level, message, env, **metadata)
+      start_time = Otto::Utils.now_in_μs
+      result = yield
+      duration = Otto::Utils.now_in_μs - start_time
+
+      Otto.structured_log(level, message,
+        request_context(env).merge(metadata).merge(duration: duration))
+
+      result
+    rescue StandardError => e
+      duration = Otto::Utils.now_in_μs - start_time
+      Otto.structured_log(:error, "#{message} failed",
+        request_context(env).merge(metadata).merge(
+          duration: duration,
+          error: e.message,
+          error_class: e.class.name
+        ))
+      raise
+    end
+
+    # Detect project root directory for path sanitization
+    # @return [String] Absolute path to project root
+    def self.detect_project_root
+      @project_root ||= begin
+        if defined?(Bundler)
+          Bundler.root.to_s
+        else
+          Dir.pwd
+        end
+      end
+    end
+
+    # Sanitize a single backtrace line to remove sensitive path information
+    #
+    # Transforms absolute paths into relative or categorized paths:
+    # - Project files: relative path from project root
+    # - Gem files: [GEM] gem-name-version/relative/path
+    # - Ruby stdlib: [RUBY] filename
+    # - Unknown: [EXTERNAL] filename
+    #
+    # @param line [String] Raw backtrace line
+    # @param project_root [String] Project root path (auto-detected if nil)
+    # @return [String] Sanitized backtrace line
+    #
+    # @example
+    #   sanitize_backtrace_line("/Users/admin/app/lib/user.rb:42:in `save'")
+    #   # => "lib/user.rb:42:in `save'"
+    #
+    #   sanitize_backtrace_line("/usr/local/gems/rack-3.1.8/lib/rack.rb:10")
+    #   # => "[GEM] rack-3.1.8/lib/rack.rb:10"
+    #
+    def self.sanitize_backtrace_line(line, project_root = nil)
+      return line if line.nil? || line.empty?
+
+      project_root ||= detect_project_root
+      expanded_root = File.expand_path(project_root)
+
+      # Extract file path from backtrace line (format: "path:line:in `method'" or "path:line")
+      if line =~ /^(.+?):\d+(?::in `.+')?$/
+        file_path = ::Regexp.last_match(1)
+        suffix = line[file_path.length..]
+
+        begin
+          expanded_path = File.expand_path(file_path)
+        rescue ArgumentError
+          # Handle malformed paths (e.g., containing null bytes)
+          # File.basename also raises ArgumentError for null bytes, so use simple string manipulation
+          basename = file_path.split('/').last || file_path
+          return "[EXTERNAL] #{basename}#{suffix}"
+        end
+
+        # Try project-relative path first
+        if expanded_path.start_with?(expanded_root + File::SEPARATOR)
+          relative_path = expanded_path.delete_prefix(expanded_root + File::SEPARATOR)
+          return relative_path + suffix
+        end
+
+        # Check for bundler gems specifically (e.g., /bundler/gems/otto-abc123/lib/...)
+        # Must check BEFORE regular gems pattern to handle /gems/3.4.0/bundler/gems/...
+        if expanded_path =~ %r{/bundler/gems/([^/]+)/(.+)$}
+          gem_name = ::Regexp.last_match(1)
+          gem_relative = ::Regexp.last_match(2)
+          # Strip git hash suffix for cleaner output (otto-abc123def456 → otto)
+          gem_name = gem_name.sub(/-[a-f0-9]{7,}$/, '') if gem_name =~ /-[a-f0-9]{7,}$/i
+          return "[GEM] #{gem_name}/#{gem_relative}#{suffix}"
+        end
+
+        # Check for regular gem path (e.g., /path/to/gems/rack-3.1.8/lib/rack.rb)
+        # Handle version directories: /gems/3.4.0/gems/rack-3.1.8/... by looking for last /gems/
+        if expanded_path =~ %r{/gems/([^/]+)/(.+)$}
+          gem_name = ::Regexp.last_match(1)
+          gem_relative = ::Regexp.last_match(2)
+
+          # Skip version-only directory names (e.g., 3.4.0)
+          # Look deeper if gem_name is just a version number
+          if gem_name =~ /^[\d.]+$/ && gem_relative =~ %r{^(?:bundler/)?gems/([^/]+)/(.+)$}
+            # Found nested gem path, use that instead
+            gem_name = ::Regexp.last_match(1)
+            gem_relative = ::Regexp.last_match(2)
+          end
+
+          # Strip version suffix for cleaner output (rack-3.1.8 → rack)
+          base_gem_name = gem_name.split('-')[0..-2].join('-')
+          base_gem_name = gem_name if base_gem_name.empty?
+
+          return "[GEM] #{base_gem_name}/#{gem_relative}#{suffix}"
+        end
+
+        # Check for Ruby stdlib (e.g., /path/to/ruby/3.4.0/logger.rb)
+        if expanded_path =~ %r{/ruby/[\d.]+/(.+)$}
+          stdlib_file = ::Regexp.last_match(1)
+          return "[RUBY] #{stdlib_file}#{suffix}"
+        end
+
+        # Unknown/external path - show filename only
+        filename = File.basename(file_path)
+        return "[EXTERNAL] #{filename}#{suffix}"
+      end
+
+      # Couldn't parse - return as-is (better than failing)
+      line
+    end
+
+    # Sanitize an array of backtrace lines
+    #
+    # @param backtrace [Array<String>] Raw backtrace lines
+    # @param project_root [String] Project root path (auto-detected if nil)
+    # @return [Array<String>] Sanitized backtrace lines
+    def self.sanitize_backtrace(backtrace, project_root: nil)
+      return [] if backtrace.nil? || backtrace.empty?
+
+      project_root ||= detect_project_root
+      backtrace.map { |line| sanitize_backtrace_line(line, project_root) }
+    end
+
+    # Log exception backtrace with correlation fields for debugging.
+    # Always logs for unhandled errors at ERROR level with sanitized paths.
+    # Limits to first 20 lines for critical errors.
+    #
+    # SECURITY: Paths are sanitized to prevent exposing sensitive system information:
+    # - Project files: Show relative paths only
+    # - Gem files: Show gem name and relative path within gem
+    # - Ruby stdlib: Show filename only
+    # - External files: Show filename only
+    #
+    # Expects caller to provide correlation context (error_id, handler, etc).
+    # Does NOT duplicate error/error_class fields - those belong in main error log.
+    #
+    # @param error [Exception] The exception to log backtrace for
+    # @param context [Hash] Correlation fields (error_id, method, path, ip, handler, etc)
+    #
+    # @example Basic usage
+    #   Otto::LoggingHelpers.log_backtrace(error,
+    #     base_context.merge(error_id: error_id, handler: 'UserController#create')
+    #   )
+    #
+    # @example Downstream extensibility
+    #   custom_context = Otto::LoggingHelpers.request_context(env).merge(
+    #     error_id: error_id,
+    #     transaction_id: Thread.current[:transaction_id],
+    #     tenant_id: env['tenant_id']
+    #   )
+    #   Otto::LoggingHelpers.log_backtrace(error, custom_context)
+    #
+    def self.log_backtrace(error, context = {})
+      raw_backtrace = error.backtrace&.first(20) || []
+      sanitized = sanitize_backtrace(raw_backtrace)
+
+      Otto.structured_log(:error, 'Exception backtrace',
+        context.merge(backtrace: sanitized))
+    end
+  end
+end

data/lib/otto/mcp/auth/token.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/auth/token.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/otto/mcp/protocol.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/protocol.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 require_relative 'registry'

data/lib/otto/mcp/rate_limiting.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/rate_limiting.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/otto/mcp/registry.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/registry.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module MCP

data/lib/otto/mcp/route_parser.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/route_parser.rb
+#
+# frozen_string_literal: true
 
 class Otto
   module MCP

data/lib/otto/mcp/schema_validation.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/schema_validation.rb
+#
+# frozen_string_literal: true
 
 require 'json'
 

data/lib/otto/mcp/server.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: true
-
 # lib/otto/mcp/server.rb
+#
+# frozen_string_literal: true
 
 require_relative 'protocol'
 require_relative 'registry'

data/lib/otto/mcp.rb

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

data/lib/otto/privacy/config.rb

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