otto 2.0.0.pre2 → 2.0.0.pre7

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

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

data/lib/otto/privacy/config.rb

@@ -0,0 +1,201 @@
+# lib/otto/privacy/config.rb
+#
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'securerandom'
+require 'digest'
+
+require 'concurrent'
+
+require_relative '../core/freezable'
+
+class Otto
+  module Privacy
+    # Configuration for IP privacy features
+    #
+    # Privacy is ENABLED by default for public IPs. Private/localhost IPs are not masked.
+    #
+    # @example Default configuration (privacy enabled)
+    #   config = Otto::Privacy::Config.new
+    #   config.enabled? # => true
+    #
+    # @example Configure masking level
+    #   config = Otto::Privacy::Config.new
+    #   config.octet_precision = 2  # Mask 2 octets instead of 1
+    #
+    class Config
+      include Otto::Core::Freezable
+
+      attr_accessor :octet_precision, :hash_rotation_period, :geo_enabled, :mask_private_ips
+      attr_reader :disabled
+
+      # Class-level rotation key storage (mutable, not frozen with instances)
+      # This is stored at the class level so it persists across frozen config instances
+      @rotation_keys_store = nil
+
+      class << self
+        # Get the class-level rotation keys store
+        # @return [Concurrent::Map] Thread-safe map for rotation keys
+        def rotation_keys_store
+          @rotation_keys_store = Concurrent::Map.new unless defined?(@rotation_keys_store) && @rotation_keys_store
+          @rotation_keys_store
+        end
+      end
+
+      # Initialize privacy configuration
+      #
+      # @param options [Hash] Configuration options
+      # @option options [Integer] :octet_precision Number of trailing octets to mask (1 or 2, default: 1)
+      # @option options [Integer] :hash_rotation_period Seconds between key rotation (default: 86400)
+      # @option options [Boolean] :geo_enabled Enable geo-location resolution (default: true)
+      # @option options [Boolean] :disabled Disable privacy entirely (default: false)
+      # @option options [Boolean] :mask_private_ips Mask private/localhost IPs (default: false)
+      # @option options [Redis] :redis Optional Redis connection for multi-server environments
+      def initialize(options = {})
+        @octet_precision = options.fetch(:octet_precision, 1)
+        @hash_rotation_period = options.fetch(:hash_rotation_period, 86_400) # 24 hours
+        @geo_enabled = options.fetch(:geo_enabled, true)
+        @disabled = options.fetch(:disabled, false) # Enabled by default (privacy-by-default)
+        @mask_private_ips = options.fetch(:mask_private_ips, false) # Don't mask private/localhost by default
+        @redis = options[:redis] # Optional Redis connection for multi-server environments
+      end
+
+      # Check if privacy is enabled
+      #
+      # @return [Boolean] true if privacy is enabled (default)
+      def enabled?
+        !@disabled
+      end
+
+      # Check if privacy is disabled
+      #
+      # @return [Boolean] true if privacy was explicitly disabled
+      def disabled?
+        @disabled
+      end
+
+      # Disable privacy (allows access to original IPs)
+      #
+      # IMPORTANT: This should only be used when you have a specific
+      # requirement to access original IP addresses. By default, Otto
+      # provides privacy-safe masked IPs.
+      #
+      # @return [self]
+      def disable!
+        @disabled = true
+        self
+      end
+
+      # Enable privacy (default state)
+      #
+      # @return [self]
+      def enable!
+        @disabled = false
+        self
+      end
+
+      # Get the current rotation key for IP hashing
+      #
+      # Keys rotate at fixed intervals based on hash_rotation_period (default: 24 hours).
+      # Each rotation period gets a unique key, ensuring IP addresses hash differently
+      # across periods while remaining consistent within.
+      #
+      # Multi-server support:
+      # - With Redis: Uses SET NX GET EX for atomic key generation across all servers
+      # - Without Redis: Falls back to in-memory Concurrent::Hash (single-server only)
+      #
+      # Redis keys:
+      #   - rotation_key:{timestamp} - Stores the rotation key with TTL
+      #
+      # @return [String] Current rotation key for hashing
+      def rotation_key
+        if @redis
+          rotation_key_redis
+        else
+          rotation_key_memory
+        end
+      end
+
+      # Validate configuration settings
+      #
+      # @raise [ArgumentError] if configuration is invalid
+      def validate!
+        raise ArgumentError, "octet_precision must be 1 or 2, got: #{@octet_precision}" unless [1,
+                                                                                                2].include?(@octet_precision)
+
+        return unless @hash_rotation_period < 60
+
+        raise ArgumentError, 'hash_rotation_period must be at least 60 seconds'
+      end
+
+      private
+
+      # Redis-based rotation key (atomic across multiple servers)
+      #
+      # Uses SET NX GET EX to atomically:
+      # 1. Check if key exists
+      # 2. Set new key only if missing
+      # 3. Return existing or newly set key
+      # 4. Auto-expire with TTL
+      #
+      # @return [String] Current rotation key
+      # @api private
+      def rotation_key_redis
+        now_seconds = Time.now.utc.to_i
+
+        # Quantize to rotation period boundary
+        rotation_timestamp = (now_seconds / @hash_rotation_period) * @hash_rotation_period
+
+        redis_key = "rotation_key:#{rotation_timestamp}"
+        ttl = (@hash_rotation_period * 1.2).to_i # Auto-cleanup with 20% buffer
+
+        key = SecureRandom.hex(32)
+
+        # SET NX GET returns old value if key exists, nil if we set it
+        # @see https://valkey.io/commands/set/
+        existing_key = @redis.set(redis_key, key, nx: true, get: true, ex: ttl)
+
+        existing_key || key
+      end
+
+      # In-memory rotation key (single-server fallback)
+      #
+      # Uses class-level Concurrent::Hash for thread-safety within a single process.
+      # NOT atomic across multiple servers.
+      #
+      # The rotation keys are stored at the class level so they remain mutable
+      # even when config instances are frozen.
+      #
+      # @return [String] Current rotation key
+      # @api private
+      def rotation_key_memory
+        rotation_keys = self.class.rotation_keys_store
+
+        now_seconds = Time.now.utc.to_i
+
+        # Quantize to rotation period boundary (e.g., midnight UTC for 24-hour period)
+        seconds_since_epoch = now_seconds % @hash_rotation_period
+        rotation_timestamp = now_seconds - seconds_since_epoch
+
+        # Atomically get or create key for this rotation period
+        # Use compute_if_absent for thread-safe atomic operation
+        key = rotation_keys.compute_if_absent(rotation_timestamp) do
+          # Generate new key atomically
+          # IMPORTANT: Don't modify the map inside this block to avoid deadlock
+          SecureRandom.hex(32)
+        end
+
+        # Clean up old keys after atomic operation completes
+        # This runs outside compute_if_absent to avoid deadlock
+        if rotation_keys.size > 1
+          rotation_keys.each_key do |ts|
+            rotation_keys.delete(ts) if ts != rotation_timestamp
+          end
+        end
+
+        key
+      end
+    end
+  end
+end