otto 2.0.0.pre8 → 2.0.0.pre9

data/lib/otto/core/error_handler.rb

@@ -26,7 +26,7 @@ class Otto
         log_context = base_context.merge(
           error: error.message,
           error_class: error.class.name,
-          error_id: error_id
+          error_id: error_id,
         )
         log_context[:handler] = env['otto.handler'] if env['otto.handler']
         log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
@@ -69,8 +69,7 @@ class Otto
         end
 
         # Content negotiation for built-in error response
-        accept_header = env['HTTP_ACCEPT'].to_s
-        return json_error_response(error_id) if accept_header.include?('application/json')
+        return json_error_response(error_id) if wants_json_response?(env)
 
         # Fallback to built-in error response
         @server_error || secure_error_response(error_id)
@@ -96,7 +95,7 @@ class Otto
           error: error.message,
           error_class: error.class.name,
           error_id: error_id,
-          expected: true  # Mark as expected error
+          expected: true # Mark as expected error
         )
         log_context[:handler] = env['otto.handler'] if env['otto.handler']
         log_context[:duration] = env['otto.handler_duration'] if env['otto.handler_duration']
@@ -146,14 +145,13 @@ class Otto
         response_body[:error_id] = error_id if Otto.env?(:dev, :development)
 
         # Content negotiation
-        accept_header = env['HTTP_ACCEPT'].to_s
         status = handler_config[:status] || 500
 
-        if accept_header.include?('application/json')
+        if wants_json_response?(env)
           body = JSON.generate(response_body)
           headers = {
             'content-type' => 'application/json',
-            'content-length' => body.bytesize.to_s
+            'content-length' => body.bytesize.to_s,
           }.merge(@security_config.security_headers)
 
           [status, headers, [body]]
@@ -167,7 +165,7 @@ class Otto
 
           headers = {
             'content-type' => 'text/plain',
-            'content-length' => body.bytesize.to_s
+            'content-length' => body.bytesize.to_s,
           }.merge(@security_config.security_headers)
 
           [status, headers, [body]]
@@ -211,6 +209,19 @@ class Otto
 
         [500, headers, [body]]
       end
+
+      private
+
+      # Determine if the client wants a JSON response
+      # Route's response_type declaration takes precedence over Accept header
+      #
+      # @param env [Hash] Rack environment
+      # @return [Boolean] true if JSON response is preferred
+      def wants_json_response?(env)
+        route_definition = env['otto.route_definition']
+        (route_definition&.response_type == 'json') ||
+          env['HTTP_ACCEPT'].to_s.include?('application/json')
+      end
     end
   end
 end

data/lib/otto/core/freezable.rb

@@ -2,8 +2,6 @@
 #
 # frozen_string_literal: true
 
-require 'set'
-
 class Otto
   module Core
     # Provides deep freezing capability for configuration objects

data/lib/otto/core/middleware_stack.rb

@@ -73,7 +73,7 @@ class Otto
         when :last
           @stack << entry
         else
-          @stack << entry  # Default append
+          @stack << entry # Default append
         end
 
         @middleware_set.add(middleware_class)
@@ -114,15 +114,21 @@ class Otto
 
         # Check optimal order: rate_limit < auth < validation
         if rate_limit_pos && auth_pos && rate_limit_pos > auth_pos
-          warnings << '[MCP Middleware] RateLimitMiddleware should come before TokenMiddleware for optimal performance'
+          warnings << <<~MSG.chomp
+            [MCP Middleware] RateLimitMiddleware should come before TokenMiddleware
+          MSG
         end
 
         if auth_pos && validation_pos && auth_pos > validation_pos
-          warnings << '[MCP Middleware] TokenMiddleware should come before SchemaValidationMiddleware for optimal performance'
+          warnings << <<~MSG.chomp
+            [MCP Middleware] TokenMiddleware should come before SchemaValidationMiddleware
+          MSG
         end
 
         if rate_limit_pos && validation_pos && rate_limit_pos > validation_pos
-          warnings << '[MCP Middleware] RateLimitMiddleware should come before SchemaValidationMiddleware for optimal performance'
+          warnings << <<~MSG.chomp
+            [MCP Middleware] RateLimitMiddleware should come before SchemaValidationMiddleware
+          MSG
         end
 
         warnings
@@ -198,8 +204,8 @@ class Otto
         @stack.map do |entry|
           {
             middleware: entry[:middleware],
-            args: entry[:args],
-            options: entry[:options],
+                  args: entry[:args],
+               options: entry[:options],
           }
         end
       end
@@ -225,8 +231,6 @@ class Otto
         @stack.reverse_each(&)
       end
 
-
-
       private
 
       def middleware_needs_config?(middleware_class)

data/lib/otto/core/router.rb

@@ -36,28 +36,28 @@ class Otto
           route.otto                              = self
           path_clean                              = path.gsub(%r{/$}, '')
           @route_definitions[route.definition]    = route
-          Otto.structured_log(:debug, "Route loaded",
-            {
-              pattern: route.pattern.source,
-              verb: route.verb,
-              definition: route.definition,
-              type: 'pattern'
-            }
-          ) if Otto.debug
+          if Otto.debug
+            Otto.structured_log(:debug, 'Route loaded',
+              {
+                   pattern: route.pattern.source,
+                verb: route.verb,
+                definition: route.definition,
+                type: 'pattern',
+              })
+          end
           @routes[route.verb] ||= []
           @routes[route.verb] << route
           @routes_literal[route.verb]           ||= {}
           @routes_literal[route.verb][path_clean] = route
         rescue StandardError => e
-          Otto.structured_log(:error, "Route load failed",
+          Otto.structured_log(:error, 'Route load failed',
             {
-              path: path,
+                     path: path,
               verb: verb,
               definition: definition,
               error: e.message,
-              error_class: e.class.name
-            }
-          )
+              error_class: e.class.name,
+            })
           Otto.logger.debug e.backtrace.join("\n") if Otto.debug
         end
         self
@@ -96,30 +96,27 @@ 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.structured_log(:debug, "Route matched",
+          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.structured_log(:debug, "Route matched",
+          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.structured_log(:debug, "Route matched",
+          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
@@ -165,14 +162,13 @@ class Otto
           found_route  = route
 
           # Log successful route match
-          Otto.structured_log(:debug, "Route matched",
+          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
 
@@ -180,19 +176,17 @@ class Otto
         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.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.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/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/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

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_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 = Rack::Request.new(env)
+        res = Rack::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,6 +46,77 @@ class Otto
         @target_class ||= safe_const_get(route_definition.klass_name)
       end
 
+      # 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 [Rack::Request] Request object
       # @param res [Rack::Response] Response object

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

data/lib/otto/route_handlers/instance_method.rb

@@ -1,7 +1,6 @@
 # lib/otto/route_handlers/instance_method.rb
 #
 # frozen_string_literal: true
-require 'securerandom'
 
 require_relative 'base'
 
@@ -17,62 +16,16 @@ class Otto
     # Use this handler for endpoints requiring request-level control (logout,
     # session management, cookie manipulation, custom header handling).
     class InstanceMethodHandler < 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)
-
-          # Create instance and call method (existing Otto behavior)
-          instance = target_class.new(req, res)
-          result   = instance.send(route_definition.method_name)
-
-          # Only handle response if response_type is not default
-          if route_definition.response_type != 'default'
-            handle_response(result, res, {
-                              instance: instance,
-                              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}##{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
-            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
-
-            # 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 instance 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)
+        instance = target_class.new(req, res)
+        result = instance.send(route_definition.method_name)
+        [result, { instance: instance, request: req }]
       end
     end
   end