otto 2.0.0.pre8 → 2.0.0.pre10

data/lib/otto/errors.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Base error classes for Otto framework
+#
+# These classes provide a foundation for HTTP error handling and can be
+# subclassed by implementing projects for consistent error handling.
+#
+# @example Subclassing in an application
+#   class MyApp::ResourceNotFound < Otto::NotFoundError; end
+#
+#   otto.register_error_handler(MyApp::ResourceNotFound, status: 404, log_level: :info)
+#
+class Otto
+  # Base class for all Otto HTTP errors
+  #
+  # Provides default_status and default_log_level class methods that
+  # define the HTTP status code and logging level for the error.
+  class HTTPError < StandardError
+    def self.default_status
+      500
+    end
+
+    def self.default_log_level
+      :error
+    end
+  end
+
+  # Bad Request (400) error
+  #
+  # Use for malformed requests, invalid parameters, or failed validation
+  class BadRequestError < HTTPError
+    def self.default_status
+      400
+    end
+
+    def self.default_log_level
+      :info
+    end
+  end
+
+  # Unauthorized (401) error
+  #
+  # Use when authentication is required but missing or invalid
+  class UnauthorizedError < HTTPError
+    def self.default_status
+      401
+    end
+
+    def self.default_log_level
+      :info
+    end
+  end
+
+  # Forbidden (403) error
+  #
+  # Use when the user is authenticated but lacks permission
+  class ForbiddenError < HTTPError
+    def self.default_status
+      403
+    end
+
+    def self.default_log_level
+      :warn
+    end
+  end
+
+  # Not Found (404) error
+  #
+  # Use when the requested resource does not exist
+  class NotFoundError < HTTPError
+    def self.default_status
+      404
+    end
+
+    def self.default_log_level
+      :info
+    end
+  end
+
+  # Payload Too Large (413) error
+  #
+  # Use when request body exceeds configured size limits
+  class PayloadTooLargeError < HTTPError
+    def self.default_status
+      413
+    end
+
+    def self.default_log_level
+      :warn
+    end
+  end
+end

data/lib/otto/helpers.rb

@@ -2,5 +2,5 @@
 #
 # frozen_string_literal: true
 
-require_relative 'helpers/request'
-require_relative 'helpers/response'
+# Request and response helpers are now defined directly in Otto::Request and Otto::Response
+# This file is kept for backward compatibility with require statements

data/lib/otto/locale/middleware.rb

@@ -68,7 +68,7 @@ class Otto
       # @return [String] Resolved locale code
       def detect_locale(env)
         # 1. Check URL parameter
-        req = Rack::Request.new(env)
+        req = Otto::Request.new(env)
         locale = req.params['locale']
         return locale if valid_locale?(locale)
 

data/lib/otto/mcp/core.rb

@@ -0,0 +1,33 @@
+# lib/otto/mcp/core.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module MCP
+    # Core MCP (Model Context Protocol) methods included in the Otto class.
+    # Provides the public API for enabling and querying MCP server support.
+    module Core
+      # Enable MCP (Model Context Protocol) server support
+      #
+      # @param options [Hash] MCP configuration options
+      # @option options [Boolean] :http Enable HTTP endpoint (default: true)
+      # @option options [Boolean] :stdio Enable STDIO communication (default: false)
+      # @option options [String] :endpoint HTTP endpoint path (default: '/_mcp')
+      # @example
+      #   otto.enable_mcp!(http: true, endpoint: '/api/mcp')
+      def enable_mcp!(options = {})
+        ensure_not_frozen!
+        @mcp_server ||= Otto::MCP::Server.new(self)
+
+        @mcp_server.enable!(options)
+        Otto.logger.info '[MCP] Enabled MCP server' if Otto.debug
+      end
+
+      # Check if MCP is enabled
+      # @return [Boolean]
+      def mcp_enabled?
+        @mcp_server&.enabled?
+      end
+    end
+  end
+end

data/lib/otto/mcp/protocol.rb

@@ -17,7 +17,7 @@ class Otto
       end
 
       def handle_request(env)
-        request = Rack::Request.new(env)
+        request = @otto.request_class.new(env)
 
         unless request.post? && request.content_type&.include?('application/json')
           return error_response(nil, -32_600, 'Invalid Request', 'Only JSON-RPC POST requests supported')

data/lib/otto/mcp/rate_limiting.rb

@@ -87,8 +87,12 @@ class Otto
             [429, headers, [JSON.generate(error_response)]]
           else
             # Use the general rate limiting response for non-MCP requests
-            accept_header = request.env['HTTP_ACCEPT'].to_s
-            if accept_header.include?('application/json')
+            # Route's response_type takes precedence over Accept header
+            route_def = request.env['otto.route_definition']
+            wants_json = (route_def&.response_type == 'json') ||
+                         request.env['HTTP_ACCEPT'].to_s.include?('application/json')
+
+            if wants_json
               error_response = {
                 error: 'Rate limit exceeded',
                 message: 'Too many requests',

data/lib/otto/mcp/schema_validation.rb

@@ -12,7 +12,7 @@ end
 
 class Otto
   module MCP
-    class ValidationError < StandardError; end
+    class ValidationError < Otto::BadRequestError; end
 
     # JSON Schema validator for MCP protocol requests
     class Validator
@@ -78,7 +78,7 @@ class Otto
         # Only validate MCP endpoints
         return @app.call(env) unless mcp_endpoint?(env)
 
-        request = Rack::Request.new(env)
+        request = Otto::Request.new(env)
 
         if request.post? && request.content_type&.include?('application/json')
           begin

data/lib/otto/mcp.rb

@@ -2,4 +2,5 @@
 #
 # frozen_string_literal: true
 
+require_relative 'mcp/core'
 require_relative 'mcp/server'

data/lib/otto/privacy/core.rb

@@ -0,0 +1,82 @@
+# lib/otto/privacy/core.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Privacy
+    # Core privacy configuration methods included in the Otto class.
+    # Provides the public API for configuring IP privacy features.
+    module Core
+      # Disable IP privacy to access original IP addresses
+      #
+      # IMPORTANT: By default, Otto masks public IP addresses for privacy.
+      # Private/localhost IPs (127.0.0.0/8, 10.0.0.0/8, etc.) are never masked.
+      # Only disable this if you need access to original public IPs.
+      #
+      # When disabled:
+      # - env['REMOTE_ADDR'] contains the real IP address
+      # - env['otto.original_ip'] also contains the real IP
+      # - No PrivateFingerprint is created
+      #
+      # @example
+      #   otto.disable_ip_privacy!
+      def disable_ip_privacy!
+        ensure_not_frozen!
+        @security_config.ip_privacy_config.disable!
+      end
+
+      # Enable full IP privacy (mask ALL IPs including private/localhost)
+      #
+      # By default, Otto exempts private and localhost IPs from masking for
+      # better development experience. Call this method to mask ALL IPs
+      # regardless of type.
+      #
+      # @example Enable full privacy (mask all IPs)
+      #   otto = Otto.new(routes_file)
+      #   otto.enable_full_ip_privacy!
+      #   # Now 127.0.0.1 → 127.0.0.0, 192.168.1.100 → 192.168.1.0
+      #
+      # @return [void]
+      # @raise [FrozenError] if called after configuration is frozen
+      def enable_full_ip_privacy!
+        ensure_not_frozen!
+        @security_config.ip_privacy_config.mask_private_ips = true
+      end
+
+      # Configure IP privacy settings
+      #
+      # Privacy is enabled by default. Use this method to customize privacy
+      # behavior without disabling it entirely.
+      #
+      # @param octet_precision [Integer] Number of octets to mask (1 or 2, default: 1)
+      # @param hash_rotation [Integer] Seconds between key rotation (default: 86400)
+      # @param geo [Boolean] Enable geo-location resolution (default: true)
+      # @param redis [Redis] Redis connection for multi-server atomic key generation
+      #
+      # @example Mask 2 octets instead of 1
+      #   otto.configure_ip_privacy(octet_precision: 2)
+      #
+      # @example Disable geo-location
+      #   otto.configure_ip_privacy(geo: false)
+      #
+      # @example Custom hash rotation
+      #   otto.configure_ip_privacy(hash_rotation: 24.hours)
+      #
+      # @example Multi-server with Redis
+      #   redis = Redis.new(url: ENV['REDIS_URL'])
+      #   otto.configure_ip_privacy(redis: redis)
+      def configure_ip_privacy(octet_precision: nil, hash_rotation: nil, geo: nil, redis: nil)
+        ensure_not_frozen!
+        config = @security_config.ip_privacy_config
+
+        config.octet_precision = octet_precision if octet_precision
+        config.hash_rotation_period = hash_rotation if hash_rotation
+        config.geo_enabled = geo unless geo.nil?
+        config.instance_variable_set(:@redis, redis) if redis
+
+        # Validate configuration
+        config.validate!
+      end
+    end
+  end
+end

data/lib/otto/privacy.rb

@@ -2,6 +2,7 @@
 #
 # frozen_string_literal: true
 
+require_relative 'privacy/core'
 require_relative 'privacy/config'
 require_relative 'privacy/ip_privacy'
 require_relative 'privacy/geo_resolver'

data/lib/otto/{helpers/request.rb → request.rb}

@@ -1,14 +1,25 @@
-# lib/otto/helpers/request.rb
+# lib/otto/request.rb
 #
 # frozen_string_literal: true
 
-require_relative 'base'
+require 'rack/request'
 
 class Otto
-  # Request helper methods providing HTTP request handling utilities
-  module RequestHelpers
-    include Otto::BaseHelpers
-
+  # Otto's enhanced Rack::Request class with built-in helpers
+  #
+  # This class extends Rack::Request with Otto's framework helpers for
+  # HTTP request handling, privacy, security, and locale management.
+  # Projects can register additional helpers via Otto#register_request_helpers.
+  #
+  # @example Using Otto's request in route handlers
+  #   def show(req, res)
+  #     req.masked_ip      # Privacy-safe masked IP
+  #     req.geo_country    # ISO country code
+  #     req.check_locale!  # Set locale for request
+  #   end
+  #
+  # @see Otto#register_request_helpers
+  class Request < Rack::Request
     def user_agent
       env['HTTP_USER_AGENT']
     end

data/lib/otto/{helpers/response.rb → response.rb}

@@ -1,14 +1,27 @@
-# lib/otto/helpers/response.rb
+# lib/otto/response.rb
 #
 # frozen_string_literal: true
 
-require_relative 'base'
+require 'rack/response'
 
 class Otto
-  # Response helper methods providing HTTP response handling utilities
-  module ResponseHelpers
-    include Otto::BaseHelpers
-
+  # Otto's enhanced Rack::Response class with built-in helpers
+  #
+  # This class extends Rack::Response with Otto's framework helpers for
+  # HTTP response handling, cookie management, CSP headers, and security.
+  # Projects can register additional helpers via Otto#register_response_helpers.
+  #
+  # @example Using Otto's response in route handlers
+  #   def show(req, res)
+  #     res.send_secure_cookie('session_id', token, 3600)
+  #     res.send_csp_headers('text/html', nonce)
+  #     res.no_cache!
+  #   end
+  #
+  # @see Otto#register_response_helpers
+  class Response < Rack::Response
+    # Reference to the request object (needed by some response helpers)
+    # @return [Otto::Request]
     attr_accessor :request
 
     def send_secure_cookie(name, value, ttl, opts = {})
@@ -171,7 +184,7 @@ class Otto
     #   # => "/myapp/admin/settings"
     def app_path(*paths)
       paths = paths.flatten.compact
-      paths.unshift(request.env['SCRIPT_NAME']) if request.env['SCRIPT_NAME']
+      paths.unshift(request.env['SCRIPT_NAME']) if request&.env&.[]('SCRIPT_NAME')
       paths.join('/').gsub('//', '/')
     end
   end

data/lib/otto/response_handlers/json.rb

@@ -11,9 +11,7 @@ class Otto
       def self.handle(result, response, context = {})
         # If a redirect has already been set, don't override with JSON
         # This allows controllers to conditionally redirect based on Accept header
-        if response.status&.between?(300, 399) && response['Location']
-          return
-        end
+        return if response.status&.between?(300, 399) && response['Location']
 
         response['Content-Type'] = 'application/json'
 

data/lib/otto/response_handlers/view.rb

@@ -9,7 +9,7 @@ class Otto
     # Handler for view/template responses
     class ViewHandler < BaseHandler
       def self.handle(result, response, context = {})
-        if context[:logic_instance]&.respond_to?(:view)
+        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)

data/lib/otto/route.rb

@@ -100,10 +100,8 @@ class Otto
     # @return [Array] Rack response array [status, headers, body]
     def call(env, extra_params = {})
       extra_params ||= {}
-      req            = Rack::Request.new(env)
-      res            = Rack::Response.new
-      req.extend Otto::RequestHelpers
-      res.extend Otto::ResponseHelpers
+      req            = otto.request_class.new(env)
+      res            = otto.response_class.new
       res.request = req
 
       # Make security config available to response helpers

data/lib/otto/route_handlers/base.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'securerandom'
 
 class Otto
   module RouteHandlers
@@ -21,7 +22,20 @@ class Otto
       # @param extra_params [Hash] Additional parameters
       # @return [Array] Rack response array
       def call(env, extra_params = {})
-        raise NotImplementedError, 'Subclasses must implement #call'
+        @start_time = Otto::Utils.now_in_μs
+        req = otto_instance ? otto_instance.request_class.new(env) : Otto::Request.new(env)
+        res = otto_instance ? otto_instance.response_class.new : Otto::Response.new
+
+        begin
+          setup_request_response(req, res, env, extra_params)
+          result, context = invoke_target(req, res)
+
+          handle_response(result, res, context) if route_definition.response_type != 'default'
+        rescue StandardError => e
+          handle_execution_error(e, env, req, res, @start_time)
+        end
+
+        finalize_response(res)
       end
 
       protected
@@ -32,15 +46,84 @@ class Otto
         @target_class ||= safe_const_get(route_definition.klass_name)
       end
 
-      # Setup request and response with the same extensions and processing as Route#call
+      # Template method for subclasses to implement their invocation logic
+      # @param req [Rack::Request] Request object
+      # @param res [Rack::Response] Response object
+      # @return [Array] [result, context] where context is a hash for handle_response
+      def invoke_target(req, res)
+        raise NotImplementedError, 'Subclasses must implement #invoke_target'
+      end
+
+      # Handle errors during route execution
+      # @param error [StandardError] The error that occurred
+      # @param env [Hash] Rack environment
       # @param req [Rack::Request] Request object
       # @param res [Rack::Response] Response object
+      # @param start_time [Integer] Start time in microseconds
+      def handle_execution_error(error, env, _req, res, start_time)
+        if otto_instance
+          # Integrated context - let centralized error handler manage
+          env['otto.handler'] = handler_name
+          env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
+          raise error
+        else
+          # Direct testing context - handle locally
+          handle_local_error(error, env, res)
+        end
+      end
+
+      # Handle errors locally for testing context
+      # @param error [StandardError] The error that occurred
+      # @param env [Hash] Rack environment
+      # @param res [Rack::Response] Response object
+      def handle_local_error(error, env, res)
+        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
+
+        res.status = 500
+
+        # Content negotiation for error response
+        # Route's response_type takes precedence over Accept header
+        route_def = env['otto.route_definition']
+        wants_json = (route_def&.response_type == 'json') ||
+                     env['HTTP_ACCEPT'].to_s.include?('application/json')
+
+        if wants_json
+          res.headers['content-type'] = 'application/json'
+          error_data = {
+               error: 'Internal Server Error',
+             message: 'Server error occurred. Check logs for details.',
+            error_id: error_id,
+          }
+          res.write JSON.generate(error_data)
+        else
+          res.headers['content-type'] = 'text/plain'
+          if Otto.env?(:dev, :development)
+            res.write "Server error (ID: #{error_id}). Check logs for details."
+          else
+            res.write 'An error occurred. Please try again later.'
+          end
+        end
+
+        # Security headers are not available without an otto_instance
+        # (testing/local context). The RouteAuthWrapper handles security
+        # headers when otto_instance is present.
+      end
+
+      # Format the handler name for logging
+      # @return [String] Handler name in format "ClassName#method_name"
+      def handler_name
+        "#{target_class.name}##{route_definition.method_name}"
+      end
+
+      # Setup request and response with the same extensions and processing as Route#call
+      # @param req [Otto::Request] Request object
+      # @param res [Otto::Response] Response object
       # @param env [Hash] Rack environment
       # @param extra_params [Hash] Additional parameters
       def setup_request_response(req, res, env, extra_params)
-        # Apply the same extensions as original Route#call
-        req.extend Otto::RequestHelpers
-        res.extend Otto::ResponseHelpers
+        # Set request reference (helpers are already included in class)
         res.request = req
 
         # Make security config available to response helpers

data/lib/otto/route_handlers/class_method.rb

@@ -2,9 +2,6 @@
 #
 # frozen_string_literal: true
 
-require 'json'
-require 'securerandom'
-
 require_relative 'base'
 
 class Otto
@@ -19,70 +16,15 @@ class Otto
     # Use this handler for endpoints requiring request-level control (logout,
     # session management, cookie manipulation, custom header handling).
     class ClassMethodHandler < BaseHandler
-      def call(env, extra_params = {})
-        start_time = Otto::Utils.now_in_μs
-        req = Rack::Request.new(env)
-        res = Rack::Response.new
-
-        begin
-          # Apply the same extensions and processing as original Route#call
-          setup_request_response(req, res, env, extra_params)
-
-          # Call class method directly (existing Otto behavior)
-          result = target_class.send(route_definition.method_name, req, res)
-
-          # Only handle response if response_type is not default
-          if route_definition.response_type != 'default'
-            handle_response(result, res,
-            {
-                class: target_class,
-              request: req,
-            })
-          end
-        rescue StandardError => e
-          # Check if we're being called through Otto's integrated context (vs direct handler testing)
-          # In integrated context, let Otto's centralized error handler manage the response
-          # In direct testing context, handle errors locally for unit testing
-          if otto_instance
-            # Store handler context in env for centralized error handler
-            handler_name = "#{target_class.name}##{route_definition.method_name}"
-            env['otto.handler'] = handler_name
-            env['otto.handler_duration'] = Otto::Utils.now_in_μs - start_time
-
-            raise e # Re-raise to let Otto's centralized error handler manage the response
-          else
-            # Direct handler testing context - handle errors locally with security improvements
-            error_id = SecureRandom.hex(8)
-            Otto.logger.error "[#{error_id}] #{e.class}: #{e.message}"
-            Otto.logger.debug "[#{error_id}] Backtrace: #{e.backtrace.join("\n")}" if Otto.debug
-
-            res.status = 500
-
-            # Content negotiation for error response
-            accept_header = env['HTTP_ACCEPT'].to_s
-            if accept_header.include?('application/json')
-              res.headers['content-type'] = 'application/json'
-              error_data                  = {
-                   error: 'Internal Server Error',
-                 message: 'Server error occurred. Check logs for details.',
-                error_id: error_id,
-              }
-              res.write JSON.generate(error_data)
-            else
-              res.headers['content-type'] = 'text/plain'
-              res.write "Server error (ID: #{error_id}). Check logs for details."
-            end
-
-            # Add security headers if available
-            if otto_instance.respond_to?(:security_config) && otto_instance.security_config
-              otto_instance.security_config.security_headers.each do |header, value|
-                res.headers[header] = value
-              end
-            end
-          end
-        end
-
-        finalize_response(res)
+      protected
+
+      # Invoke the class method on the target class
+      # @param req [Rack::Request] Request object
+      # @param res [Rack::Response] Response object
+      # @return [Array] [result, context] for handle_response
+      def invoke_target(req, res)
+        result = target_class.send(route_definition.method_name, req, res)
+        [result, { class: target_class, request: req }]
       end
     end
   end