otto 2.0.0.pre8 → 2.0.0.pre10

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']
@@ -38,7 +38,7 @@ class Otto
 
         # Parse request for content negotiation
         begin
-          Rack::Request.new(env)
+          Otto::Request.new(env)
         rescue StandardError
           nil
         end
@@ -69,13 +69,95 @@ 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)
       end
 
+      # Register an error handler for expected business logic errors
+      #
+      # This allows you to handle known error conditions (like missing resources,
+      # expired data, rate limits) without logging them as unhandled 500 errors.
+      #
+      # @param error_class [Class, String] The exception class or class name to handle
+      # @param status [Integer] HTTP status code to return (default: 500)
+      # @param log_level [Symbol] Log level for expected errors (:info, :warn, :error)
+      # @param handler [Proc] Optional block to customize error response
+      #
+      # @example Basic usage with status code
+      #   otto.register_error_handler(Onetime::MissingSecret, status: 404, log_level: :info)
+      #   otto.register_error_handler(Onetime::SecretExpired, status: 410, log_level: :info)
+      #
+      # @example With custom response handler
+      #   otto.register_error_handler(Onetime::RateLimited, status: 429, log_level: :warn) do |error, req|
+      #     {
+      #       error: 'Rate limit exceeded',
+      #       retry_after: error.retry_after,
+      #       message: error.message
+      #     }
+      #   end
+      #
+      # @example Using string class names (for lazy loading)
+      #   otto.register_error_handler('Onetime::MissingSecret', status: 404, log_level: :info)
+      #
+      def register_error_handler(error_class, status: 500, log_level: :info, &handler)
+        ensure_not_frozen!
+
+        # Normalize error class to string for consistent lookup
+        error_class_name = error_class.is_a?(String) ? error_class : error_class.name
+
+        @error_handlers[error_class_name] = {
+          status: status,
+          log_level: log_level,
+          handler: handler
+        }
+      end
+
+      private
+
+      # Register all Otto framework error classes with appropriate status codes
+      #
+      # This method auto-registers base HTTP error classes and all framework-specific
+      # error classes (Security, MCP) so that raising them automatically returns the
+      # correct HTTP status code instead of 500.
+      #
+      # Users can override these registrations by calling register_error_handler
+      # after Otto.new with custom status codes or log levels.
+      #
+      # @return [void]
+      # @api private
+      def register_framework_errors
+        # Base HTTP errors (for direct use or subclassing by implementing projects)
+        register_error_from_class(Otto::NotFoundError)
+        register_error_from_class(Otto::BadRequestError)
+        register_error_from_class(Otto::UnauthorizedError)
+        register_error_from_class(Otto::ForbiddenError)
+        register_error_from_class(Otto::PayloadTooLargeError)
+
+        # Security module errors
+        register_error_from_class(Otto::Security::AuthorizationError)
+        register_error_from_class(Otto::Security::CSRFError)
+        register_error_from_class(Otto::Security::RequestTooLargeError)
+        register_error_from_class(Otto::Security::ValidationError)
+
+        # MCP module errors
+        register_error_from_class(Otto::MCP::ValidationError)
+      end
+
+      # Register an error handler using the error class as the single source of truth
+      #
+      # @param error_class [Class] Error class that responds to default_status and default_log_level
+      # @return [void]
+      # @api private
+      def register_error_from_class(error_class)
+        register_error_handler(
+          error_class,
+          status: error_class.default_status,
+          log_level: error_class.default_log_level
+        )
+      end
+
       private
 
       # Handle expected business logic errors with custom status codes and logging
@@ -96,7 +178,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']
@@ -109,7 +191,7 @@ class Otto
         response_body = if handler_config[:handler]
                           # Use custom handler block if provided
                           begin
-                            req = Rack::Request.new(env)
+                            req = @request_class.new(env)
                             result = handler_config[:handler].call(error, req)
 
                             # Validate that custom handler returned a Hash
@@ -146,14 +228,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 +248,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 +292,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/helper_registry.rb

@@ -0,0 +1,135 @@
+# lib/otto/core/helper_registry.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Core
+    # Helper registration module for extending Otto's Request and Response classes.
+    # Provides the public API for registering custom helper modules.
+    module HelperRegistry
+      # Register request helper modules
+      #
+      # Registered modules are included in Otto::Request at the class level,
+      # making custom helpers available alongside Otto's built-in helpers.
+      # Must be called before first request (before configuration freezing).
+      #
+      # This is the official integration point for application-specific helpers
+      # that work with Otto internals (strategy_result, privacy features, etc.).
+      #
+      # @param modules [Module, Array<Module>] Module(s) containing helper methods
+      # @example
+      #   module Onetime::RequestHelpers
+      #     def current_customer
+      #       user.is_a?(Onetime::Customer) ? user : Onetime::Customer.anonymous
+      #     end
+      #
+      #     def organization
+      #       @organization ||= strategy_result&.metadata.dig(:organization_context, :organization)
+      #     end
+      #   end
+      #
+      #   otto.register_request_helpers(Onetime::RequestHelpers)
+      #
+      # @raise [ArgumentError] if module is not a Module
+      # @raise [FrozenError] if called after configuration is frozen
+      def register_request_helpers(*modules)
+        begin
+          ensure_not_frozen!
+        rescue FrozenError
+          raise FrozenError, 'Cannot register request helpers after first request'
+        end
+
+        modules.each do |mod|
+          unless mod.is_a?(Module)
+            raise ArgumentError, "Expected Module, got #{mod.class}"
+          end
+          @request_helper_modules << mod unless @request_helper_modules.include?(mod)
+        end
+
+        # Re-finalize to include newly registered helpers
+        finalize_request_response_classes
+      end
+
+      # Register response helper modules
+      #
+      # Registered modules are included in Otto::Response at the class level,
+      # making custom helpers available alongside Otto's built-in helpers.
+      # Must be called before first request (before configuration freezing).
+      #
+      # @param modules [Module, Array<Module>] Module(s) containing helper methods
+      # @example
+      #   module Onetime::ResponseHelpers
+      #     def json_success(data, status: 200)
+      #       headers['content-type'] = 'application/json'
+      #       self.status = status
+      #       write JSON.generate({ success: true, data: data })
+      #     end
+      #   end
+      #
+      #   otto.register_response_helpers(Onetime::ResponseHelpers)
+      #
+      # @raise [ArgumentError] if module is not a Module
+      # @raise [FrozenError] if called after configuration is frozen
+      def register_response_helpers(*modules)
+        begin
+          ensure_not_frozen!
+        rescue FrozenError
+          raise FrozenError, 'Cannot register response helpers after first request'
+        end
+
+        modules.each do |mod|
+          unless mod.is_a?(Module)
+            raise ArgumentError, "Expected Module, got #{mod.class}"
+          end
+          @response_helper_modules << mod unless @response_helper_modules.include?(mod)
+        end
+
+        # Re-finalize to include newly registered helpers
+        finalize_request_response_classes
+      end
+
+      # Get registered request helper modules (for debugging)
+      #
+      # @return [Array<Module>] Array of registered request helper modules
+      # @api private
+      def registered_request_helpers
+        @request_helper_modules.dup
+      end
+
+      # Get registered response helper modules (for debugging)
+      #
+      # @return [Array<Module>] Array of registered response helper modules
+      # @api private
+      def registered_response_helpers
+        @response_helper_modules.dup
+      end
+
+      private
+
+      # Finalize request and response classes with framework and custom helpers
+      #
+      # This method creates Otto's request and response classes by:
+      # 1. Subclassing Otto::Request/Response (which have framework helpers built-in)
+      # 2. Including any registered custom helper modules
+      #
+      # Called during initialization and can be called again if helpers are registered
+      # after initialization (before first request).
+      #
+      # @return [void]
+      # @api private
+      def finalize_request_response_classes
+        # Create request class with framework helpers
+        # Otto::Request has all framework helpers as instance methods
+        @request_class = Class.new(Otto::Request)
+
+        # Create response class with framework helpers
+        # Otto::Response has all framework helpers as instance methods
+        @response_class = Class.new(Otto::Response)
+
+        # Apply registered custom helpers (framework helpers always come first)
+        @request_helper_modules&.each { |mod| @request_class.include(mod) }
+        @response_helper_modules&.each { |mod| @response_class.include(mod) }
+      end
+    end
+  end
+end

data/lib/otto/core/lifecycle_hooks.rb

@@ -0,0 +1,63 @@
+# lib/otto/core/lifecycle_hooks.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Core
+    # Lifecycle hooks module for registering callbacks at various points in request processing.
+    # Provides the public API for request completion callbacks.
+    module LifecycleHooks
+      # Register a callback to be executed after each request completes
+      #
+      # Instance-level request completion callbacks allow each Otto instance
+      # to have its own isolated set of callbacks, preventing duplicate
+      # invocations in multi-app architectures (e.g., Rack::URLMap).
+      #
+      # The callback receives three arguments:
+      # - request: Rack::Request object
+      # - response: Rack::Response object (wrapping the response tuple)
+      # - duration: Request processing duration in microseconds
+      #
+      # @example Basic usage
+      #   otto = Otto.new(routes_file)
+      #   otto.on_request_complete do |req, res, duration|
+      #     logger.info "Request completed", path: req.path, duration: duration
+      #   end
+      #
+      # @example Multi-app architecture
+      #   # App 1: Core Web Application
+      #   core_router = Otto.new
+      #   core_router.on_request_complete do |req, res, duration|
+      #     logger.info "Core app request", path: req.path
+      #   end
+      #
+      #   # App 2: API Application
+      #   api_router = Otto.new
+      #   api_router.on_request_complete do |req, res, duration|
+      #     logger.info "API request", path: req.path
+      #   end
+      #
+      #   # Each callback only fires for its respective Otto instance
+      #
+      # @yield [request, response, duration] Block to execute after each request
+      # @yieldparam request [Rack::Request] The request object
+      # @yieldparam response [Rack::Response] The response object
+      # @yieldparam duration [Integer] Duration in microseconds
+      # @return [self] Returns self for method chaining
+      # @raise [FrozenError] if called after configuration is frozen
+      def on_request_complete(&block)
+        ensure_not_frozen!
+        @request_complete_callbacks << block if block_given?
+        self
+      end
+
+      # Get registered request completion callbacks (for internal use)
+      #
+      # @api private
+      # @return [Array<Proc>] Array of registered callback blocks
+      def request_complete_callbacks
+        @request_complete_callbacks
+      end
+    end
+  end
+end

data/lib/otto/core/middleware_management.rb

@@ -0,0 +1,70 @@
+# lib/otto/core/middleware_management.rb
+#
+# frozen_string_literal: true
+
+class Otto
+  module Core
+    # Middleware management module for building and configuring the Rack middleware stack.
+    # Provides the public API for adding middleware and building the application.
+    module MiddlewareManagement
+      # Builds the middleware application chain
+      # Called once at initialization and whenever middleware stack changes
+      #
+      # IMPORTANT: If you have routes with auth requirements, you MUST add session
+      # middleware to your middleware stack BEFORE Otto processes requests.
+      #
+      # Session middleware is required for RouteAuthWrapper to correctly persist
+      # session changes during authentication. Common options include:
+      # - Rack::Session::Cookie (requires rack-session gem)
+      # - Rack::Session::Pool
+      # - Rack::Session::Memcache
+      # - Any Rack-compatible session middleware
+      #
+      # Example:
+      #   use Rack::Session::Cookie, secret: ENV['SESSION_SECRET']
+      #   otto = Otto.new('routes.txt')
+      #
+      def build_app!
+        base_app = method(:handle_request)
+        @app = @middleware.wrap(base_app, @security_config)
+      end
+
+      # Add middleware to the stack
+      #
+      # @param middleware [Class] Middleware class to add
+      # @param args Additional arguments passed to middleware constructor
+      def use(middleware, ...)
+        ensure_not_frozen!
+        @middleware.add(middleware, ...)
+
+        # NOTE: If build_app! is triggered during a request (via use() or
+        # middleware_stack=), the @app instance variable could be swapped
+        # mid-request in a multi-threaded environment.
+
+        build_app! if @app # Rebuild app if already initialized
+      end
+
+      # Compatibility method for existing tests
+      # @return [Array] List of middleware classes
+      def middleware_stack
+        @middleware.middleware_list
+      end
+
+      # Compatibility method for existing tests
+      # @param stack [Array] Array of middleware classes
+      def middleware_stack=(stack)
+        @middleware.clear!
+        Array(stack).each { |middleware| @middleware.add(middleware) }
+        build_app! if @app # Rebuild app if already initialized
+      end
+
+      # Check if a specific middleware is enabled
+      #
+      # @param middleware_class [Class] Middleware class to check
+      # @return [Boolean] true if middleware is in the stack
+      def middleware_enabled?(middleware_class)
+        @middleware.includes?(middleware_class)
+      end
+    end
+  end
+end

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/core.rb

@@ -8,3 +8,6 @@ require_relative 'core/configuration'
 require_relative 'core/error_handler'
 require_relative 'core/uri_generator'
 require_relative 'core/middleware_stack'
+require_relative 'core/helper_registry'
+require_relative 'core/middleware_management'
+require_relative 'core/lifecycle_hooks'