otto 1.6.0 → 2.0.0.pre2

data/lib/otto/env_keys.rb

@@ -0,0 +1,114 @@
+# lib/otto/env_keys.rb
+#
+# Central registry of all env['otto.*'] keys used throughout Otto framework.
+# This documentation helps prevent key conflicts and aids multi-app integration.
+#
+# DOCUMENTATION-ONLY MODULE: The constants defined here are intentionally NOT used
+# in the codebase. Otto uses string literals (e.g., env['otto.strategy_result'])
+# for readibility/simplicity. This module exists as reference documentation but
+# may be considered for future use if needed.
+#
+class Otto
+  # Rack environment keys used by Otto framework
+  #
+  # All Otto-specific keys are namespaced under 'otto.*' to avoid conflicts
+  # with other Rack middleware or applications.
+  module EnvKeys
+    # =========================================================================
+    # ROUTING & REQUEST FLOW
+    # =========================================================================
+
+    # Route definition parsed from routes file
+    # Type: Otto::RouteDefinition
+    # Set by: Otto::Core::Router#parse_routes
+    # Used by: AuthenticationMiddleware, RouteHandlers, LogicClassHandler
+    ROUTE_DEFINITION = 'otto.route_definition'
+
+    # Route-specific options parsed from route string
+    # Type: Hash (e.g., { response: 'json', csrf: 'exempt', auth: 'authenticated' })
+    # Set by: Otto::RouteDefinition#initialize
+    # Used by: CSRFMiddleware, RouteHandlers
+    ROUTE_OPTIONS = 'otto.route_options'
+
+    # =========================================================================
+    # AUTHENTICATION & AUTHORIZATION
+    # =========================================================================
+
+    # Authentication strategy result containing session/user state
+    # Type: Otto::Security::Authentication::StrategyResult
+    # Set by: AuthenticationMiddleware
+    # Used by: RouteHandlers, LogicClasses, Controllers
+    # Note: Always present (anonymous or authenticated)
+    STRATEGY_RESULT = 'otto.strategy_result'
+
+    # Authenticated user object (convenience accessor)
+    # Type: Hash, Custom User Object, or nil
+    # Set by: AuthenticationMiddleware (from strategy_result.user)
+    # Used by: Controllers, RouteHandlers
+    USER = 'otto.user'
+
+    # User-specific context (session, roles, permissions, etc.)
+    # Type: Hash
+    # Set by: AuthenticationMiddleware (from strategy_result.user_context)
+    # Used by: Controllers, Analytics
+    USER_CONTEXT = 'otto.user_context'
+
+    # =========================================================================
+    # SECURITY & CONFIGURATION
+    # =========================================================================
+
+    # Security configuration object
+    # Type: Otto::Security::Config
+    # Set by: Otto#initialize, SecurityConfig
+    # Used by: All security middleware (CSRF, Headers, Validation)
+    SECURITY_CONFIG = 'otto.security_config'
+
+    # =========================================================================
+    # LOCALIZATION (I18N)
+    # =========================================================================
+
+    # Resolved locale for current request
+    # Type: String (e.g., 'en', 'es', 'fr')
+    # Set by: LocaleMiddleware
+    # Used by: RouteHandlers, LogicClasses, Views
+    LOCALE = 'otto.locale'
+
+    # Locale configuration object
+    # Type: Otto::LocaleConfig
+    # Set by: LocaleMiddleware
+    # Used by: Locale resolution logic
+    LOCALE_CONFIG = 'otto.locale_config'
+
+    # Available locales for the application
+    # Type: Array<String>
+    # Set by: LocaleConfig
+    # Used by: Locale middleware, language switchers
+    AVAILABLE_LOCALES = 'otto.available_locales'
+
+    # Default/fallback locale
+    # Type: String
+    # Set by: LocaleConfig
+    # Used by: Locale middleware when resolution fails
+    DEFAULT_LOCALE = 'otto.default_locale'
+
+    # =========================================================================
+    # ERROR HANDLING
+    # =========================================================================
+
+    # Unique error ID for tracking/logging
+    # Type: String (hex format, e.g., '4ac47cb3a6d177ef')
+    # Set by: ErrorHandler, RouteHandlers
+    # Used by: Error responses, logging, support
+    ERROR_ID = 'otto.error_id'
+
+    # =========================================================================
+    # MCP (MODEL CONTEXT PROTOCOL)
+    # =========================================================================
+
+    # MCP HTTP endpoint path
+    # Type: String (default: '/_mcp')
+    # Set by: Otto::MCP::Server#enable!
+    # Used by: MCP middleware, SchemaValidationMiddleware
+    MCP_HTTP_ENDPOINT = 'otto.mcp_http_endpoint'
+  end
+end

data/lib/otto/helpers/base.rb

@@ -1,27 +1,11 @@
+# frozen_string_literal: true
+
 # lib/otto/helpers/base.rb
 
 class Otto
+  # Base helper methods providing core functionality for Otto applications
   module BaseHelpers
-    # Build application path by joining path segments
-    #
-    # This method safely joins multiple path segments, handling
-    # duplicate slashes and ensuring proper path formatting.
-    # Includes the script name (mount point) as the first segment.
-    #
-    # @param paths [Array<String>] Path segments to join
-    # @return [String] Properly formatted path
-    #
-    # @example
-    #   app_path('api', 'v1', 'users')
-    #   # => "/myapp/api/v1/users"
-    #
-    # @example
-    #   app_path(['admin', 'settings'])
-    #   # => "/myapp/admin/settings"
-    def app_path(*paths)
-      paths = paths.flatten.compact
-      paths.unshift(env['SCRIPT_NAME']) if env['SCRIPT_NAME']
-      paths.join('/').gsub('//', '/')
-    end
+    # Keep only truly context-independent shared functionality here
+    # Methods requiring env access should be implemented in the specific helper modules
   end
 end

data/lib/otto/helpers/request.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 # lib/otto/helpers/request.rb
 
 require_relative 'base'
 
 class Otto
+  # Request helper methods providing HTTP request handling utilities
   module RequestHelpers
     include Otto::BaseHelpers
 
@@ -14,9 +17,7 @@ class Otto
       remote_addr = env['REMOTE_ADDR']
 
       # If we don't have a security config or trusted proxies, use direct connection
-      if !otto_security_config || !trusted_proxy?(remote_addr)
-        return validate_ip_address(remote_addr)
-      end
+      return validate_ip_address(remote_addr) if !otto_security_config || !trusted_proxy?(remote_addr)
 
       # Check forwarded headers from trusted proxies
       forwarded_ips = [
@@ -152,12 +153,12 @@ class Otto
 
       # RFC 1918 private ranges and loopback
       private_ranges = [
-        /\A10\./,                    # 10.0.0.0/8
+        /\A10\./, # 10.0.0.0/8
         /\A172\.(1[6-9]|2[0-9]|3[01])\./, # 172.16.0.0/12
         /\A192\.168\./,              # 192.168.0.0/16
         /\A169\.254\./,              # 169.254.0.0/16 (link-local)
         /\A224\./,                   # 224.0.0.0/4 (multicast)
-        /\A0\./,                      # 0.0.0.0/8
+        /\A0\./, # 0.0.0.0/8
       ]
 
       private_ranges.any? { |range| ip.match?(range) }
@@ -207,7 +208,7 @@ class Otto
 
       # Add any header that begins with the specified prefix
       if header_prefix
-        prefix_keys = env.keys.select { |key| key.upcase.start_with?("HTTP_#{header_prefix.upcase}") }
+        prefix_keys = env.keys.select { _1.upcase.start_with?("HTTP_#{header_prefix.upcase}") }
         keys.concat(prefix_keys)
       end
 
@@ -354,8 +355,9 @@ class Otto
       debug_enabled     = opts[:debug] || false
 
       # Guard clause - required configuration must be present
-      unless available_locales && default_locale
-        raise ArgumentError, 'available_locales and default_locale are required (provide via opts or Otto configuration)'
+      unless available_locales.is_a?(Hash) && !available_locales.empty? && default_locale && available_locales.key?(default_locale)
+        raise ArgumentError,
+              'available_locales must be a non-empty Hash and include default_locale (provide via opts or Otto configuration)'
       end
 
       # Check sources in order of precedence

data/lib/otto/helpers/response.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 # lib/otto/helpers/response.rb
 
 require_relative 'base'
 
 class Otto
+  # Response helper methods providing HTTP response handling utilities
   module ResponseHelpers
     include Otto::BaseHelpers
 
@@ -48,7 +51,7 @@ class Otto
       session_opts = opts.merge(
         secure: true,
         httponly: true,
-        samesite: :strict,
+        samesite: :strict
       )
 
       # Remove expiration-related options for session cookies
@@ -109,9 +112,7 @@ class Otto
       headers['content-type'] ||= content_type
 
       # Warn if CSP header already exists but don't skip
-      if headers['content-security-policy']
-        warn 'CSP header already set, overriding with nonce-based policy'
-      end
+      warn 'CSP header already set, overriding with nonce-based policy' if headers['content-security-policy']
 
       # Get security configuration
       security_config = opts[:security_config] ||
@@ -151,5 +152,27 @@ class Otto
       headers['expires']       = 'Mon, 7 Nov 2011 00:00:00 UTC'
       headers['pragma']        = 'no-cache'
     end
+
+    # Build application path by joining path segments
+    #
+    # This method safely joins multiple path segments, handling
+    # duplicate slashes and ensuring proper path formatting.
+    # Includes the script name (mount point) as the first segment.
+    #
+    # @param paths [Array<String>] Path segments to join
+    # @return [String] Properly formatted path
+    #
+    # @example
+    #   app_path('api', 'v1', 'users')
+    #   # => "/myapp/api/v1/users"
+    #
+    # @example
+    #   app_path(['admin', 'settings'])
+    #   # => "/myapp/admin/settings"
+    def app_path(*paths)
+      paths = paths.flatten.compact
+      paths.unshift(request.env['SCRIPT_NAME']) if request.env['SCRIPT_NAME']
+      paths.join('/').gsub('//', '/')
+    end
   end
 end

data/lib/otto/helpers/validation.rb

@@ -1,7 +1,13 @@
+# frozen_string_literal: true
+
 # lib/otto/helpers/validation.rb
 
+require 'loofah'
+require 'facets/file'
+
 class Otto
   module Security
+    # Validation helper methods providing input validation and sanitization
     module ValidationHelpers
       def validate_input(input, max_length: 1000, allow_html: false)
         return input if input.nil?
@@ -17,9 +23,7 @@ class Otto
         # Use Loofah for HTML sanitization and validation
         unless allow_html
           # Check for script injection first (these should always be rejected)
-          if looks_like_script_injection?(input_str)
-            raise Otto::Security::ValidationError, 'Dangerous content detected'
-          end
+          raise Otto::Security::ValidationError, 'Dangerous content detected' if looks_like_script_injection?(input_str)
 
           # Use Loofah to sanitize less dangerous HTML content
           sanitized_input = Loofah.fragment(input_str).scrub!(:whitewash).to_s
@@ -28,9 +32,7 @@ class Otto
 
         # Always check for SQL injection
         ValidationMiddleware::SQL_INJECTION_PATTERNS.each do |pattern|
-          if input_str.match?(pattern)
-            raise Otto::Security::ValidationError, 'Potential SQL injection detected'
-          end
+          raise Otto::Security::ValidationError, 'Potential SQL injection detected' if input_str.match?(pattern)
         end
 
         input_str
@@ -71,7 +73,7 @@ class Otto
         dangerous_patterns = [
           /javascript:/i,
           /<script[^>]*>/i,
-          /on\w+\s*=/i,  # event handlers like onclick=
+          /on\w+\s*=/i, # event handlers like onclick=
           /expression\s*\(/i,
           /data:.*base64/i,
         ]

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

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/auth/token.rb
+
 require 'json'
 
 class Otto
   module MCP
     module Auth
+      # Token-based authentication for MCP protocol endpoints
       class TokenAuth
         def initialize(tokens)
           @tokens = Array(tokens).to_set
@@ -20,15 +25,14 @@ class Otto
         def extract_token(env)
           # Try Authorization header first (Bearer token)
           auth_header = env['HTTP_AUTHORIZATION']
-          if auth_header&.start_with?('Bearer ')
-            return auth_header[7..]
-          end
+          return auth_header[7..] if auth_header&.start_with?('Bearer ')
 
           # Try X-MCP-Token header
           env['HTTP_X_MCP_TOKEN']
         end
       end
 
+      # Middleware for token authentication in MCP protocol
       class TokenMiddleware
         def initialize(app, security_config = nil)
           @app             = app
@@ -41,9 +45,7 @@ class Otto
 
           # Get auth instance from security config
           auth = @security_config&.mcp_auth
-          if auth && !auth.authenticate(env)
-            return unauthorized_response
-          end
+          return unauthorized_response if auth && !auth.authenticate(env)
 
           @app.call(env)
         end
@@ -58,15 +60,14 @@ class Otto
 
         def unauthorized_response
           body = JSON.generate({
-            jsonrpc: '2.0',
+                                 jsonrpc: '2.0',
             id: nil,
             error: {
               code: -32_000,
               message: 'Unauthorized',
               data: 'Valid token required',
             },
-          },
-                              )
+                               })
 
           [401, { 'content-type' => 'application/json' }, [body]]
         end

data/lib/otto/mcp/protocol.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/protocol.rb
+
 require 'json'
 require_relative 'registry'
 
 class Otto
   module MCP
+    # MCP protocol handler providing Model Context Protocol functionality
     class Protocol
       attr_reader :registry
 
@@ -64,14 +69,13 @@ class Otto
         }
 
         success_response(data['id'], {
-          protocolVersion: '2024-11-05',
+                           protocolVersion: '2024-11-05',
           capabilities: capabilities,
           serverInfo: {
             name: 'Otto MCP Server',
             version: Otto::VERSION,
           },
-        }
-        )
+                         })
       end
 
       def handle_resources_list(data)
@@ -83,9 +87,7 @@ class Otto
         params = data['params'] || {}
         uri    = params['uri']
 
-        unless uri
-          return error_response(data['id'], -32_602, 'Invalid params', 'Missing uri parameter')
-        end
+        return error_response(data['id'], -32_602, 'Invalid params', 'Missing uri parameter') unless uri
 
         resource = @registry.read_resource(uri)
         if resource
@@ -105,26 +107,23 @@ class Otto
         name      = params['name']
         arguments = params['arguments'] || {}
 
-        unless name
-          return error_response(data['id'], -32_602, 'Invalid params', 'Missing name parameter')
-        end
+        return error_response(data['id'], -32_602, 'Invalid params', 'Missing name parameter') unless name
 
         begin
           result = @registry.call_tool(name, arguments, env)
           success_response(data['id'], result)
-        rescue StandardError => ex
-          Otto.logger.error "[MCP] Tool call error: #{ex.message}"
-          error_response(data['id'], -32_603, 'Internal error', ex.message)
+        rescue StandardError => e
+          Otto.logger.error "[MCP] Tool call error: #{e.message}"
+          error_response(data['id'], -32_603, 'Internal error', e.message)
         end
       end
 
       def success_response(id, result)
         body = JSON.generate({
-          jsonrpc: '2.0',
+                               jsonrpc: '2.0',
           id: id,
           result: result,
-        },
-                            )
+                             })
 
         [200, { 'content-type' => 'application/json' }, [body]]
       end
@@ -134,30 +133,28 @@ class Otto
         error[:data] = data if data
 
         body = JSON.generate({
-          jsonrpc: '2.0',
+                               jsonrpc: '2.0',
           id: id,
           error: error,
-        },
-                            )
+                             })
 
         # Map JSON-RPC error codes to appropriate HTTP status codes
         http_status = case code
-                      when -32700..-32600 # Parse error, Invalid Request, Method not found
+                      when -32_700..-32_600 # Parse error, Invalid Request, Method not found
                         400
-                      when -32000         # Server error (generic)
+                      when -32_603, -32_000..-32_099 # Internal error and all server error range (-32000..-32099)
                         500
-                      when -32001         # Resource not found
+                      when -32_001         # Resource not found
                         404
-                      when -32002         # Tool not found
+                      when -32_002         # Tool not found
                         404
-                      when -32601         # Method not found
+                      when -32_601         # Method not found
                         404
-                      when -32602         # Invalid params
+                      when -32_602         # Invalid params
                         400
-                      when -32603         # Internal error
-                        500
                       else
-                        400 # Default to 400 for other client errors
+                        # Default client error for unknown non-server codes; treat server-range as 500
+                        (-32_099..-32_000).cover?(code) ? 500 : 400
                       end
 
         [http_status, { 'content-type' => 'application/json' }, [body]]

data/lib/otto/mcp/rate_limiting.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/rate_limiting.rb
+
 require 'json'
 
 require_relative '../security/rate_limiting'
@@ -10,6 +14,7 @@ end
 
 class Otto
   module MCP
+    # Rate limiter for MCP protocol endpoints
     class RateLimiter < Otto::Security::RateLimiting
       def self.configure_rack_attack!(config = {})
         return unless defined?(Rack::Attack)
@@ -117,6 +122,7 @@ class Otto
       end
     end
 
+    # Middleware for applying rate limits to MCP protocol endpoints
     class RateLimitMiddleware < Otto::Security::RateLimitMiddleware
       def initialize(app, security_config = nil)
         @app                    = app
@@ -138,10 +144,9 @@ class Otto
 
         # Add MCP-specific defaults
         mcp_config = base_config.merge({
-          mcp_requests_per_minute: 60,
+                                         mcp_requests_per_minute: 60,
           tool_calls_per_minute: 20,
-        },
-                                      )
+                                       })
 
         RateLimiter.configure_rack_attack!(mcp_config)
       end

data/lib/otto/mcp/registry.rb

@@ -1,5 +1,10 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/registry.rb
+
 class Otto
   module MCP
+    # Registry for managing MCP resources and tools
     class Registry
       def initialize
         @resources = {}
@@ -59,8 +64,8 @@ class Otto
               text: content.to_s,
             }],
           }
-        rescue StandardError => ex
-          Otto.logger.error "[MCP] Resource read error for #{uri}: #{ex.message}"
+        rescue StandardError => e
+          Otto.logger.error "[MCP] Resource read error for #{uri}: #{e.message}"
           nil
         end
       end

data/lib/otto/mcp/route_parser.rb

@@ -1,21 +1,22 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/route_parser.rb
+
 class Otto
   module MCP
+    # Parser for MCP route definitions and resource URIs
     class RouteParser
       def self.parse_mcp_route(_verb, _path, definition)
         # MCP route format: MCP resource_uri HandlerClass.method_name
         # Note: The path parameter is ignored for MCP routes - resource_uri comes from definition
         parts = definition.split(/\s+/, 3)
 
-        if parts[0] != 'MCP'
-          raise ArgumentError, "Expected MCP keyword, got: #{parts[0]}"
-        end
+        raise ArgumentError, "Expected MCP keyword, got: #{parts[0]}" if parts[0] != 'MCP'
 
         resource_uri       = parts[1]
         handler_definition = parts[2]
 
-        unless resource_uri && handler_definition
-          raise ArgumentError, "Invalid MCP route format: #{definition}"
-        end
+        raise ArgumentError, "Invalid MCP route format: #{definition}" unless resource_uri && handler_definition
 
         # Clean up URI - remove leading slash if present since MCP URIs are relative
         resource_uri = resource_uri.sub(%r{^/}, '')
@@ -33,16 +34,12 @@ class Otto
         # Note: The path parameter is ignored for TOOL routes - tool_name comes from definition
         parts = definition.split(/\s+/, 3)
 
-        if parts[0] != 'TOOL'
-          raise ArgumentError, "Expected TOOL keyword, got: #{parts[0]}"
-        end
+        raise ArgumentError, "Expected TOOL keyword, got: #{parts[0]}" if parts[0] != 'TOOL'
 
         tool_name          = parts[1]
         handler_definition = parts[2]
 
-        unless tool_name && handler_definition
-          raise ArgumentError, "Invalid TOOL route format: #{definition}"
-        end
+        raise ArgumentError, "Invalid TOOL route format: #{definition}" unless tool_name && handler_definition
 
         # Clean up tool name - remove leading slash if present
         tool_name = tool_name.sub(%r{^/}, '')
@@ -70,9 +67,7 @@ class Otto
         # First part is the handler class.method
         parts[1..-1]&.each do |part|
           key, value = part.split('=', 2)
-          if key && value
-            options[key.to_sym] = value
-          end
+          options[key.to_sym] = value if key && value
         end
 
         options

data/lib/otto/mcp/{validation.rb → schema_validation.rb}

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+# lib/otto/mcp/schema_validation.rb
+
 require 'json'
 
 begin
@@ -10,6 +14,7 @@ class Otto
   module MCP
     class ValidationError < StandardError; end
 
+    # JSON Schema validator for MCP protocol requests
     class Validator
       def initialize
         @schemas                = {}
@@ -48,7 +53,7 @@ class Otto
 
       def mcp_request_schema
         @schemas[:mcp_request] ||= JSONSchemer.schema({
-          type: 'object',
+                                                        type: 'object',
           required: %w[jsonrpc method id],
           properties: {
             jsonrpc: { const: '2.0' },
@@ -57,12 +62,13 @@ class Otto
             params: { type: 'object' },
           },
           additionalProperties: false,
-        },
-                                                     )
+                                                      })
       end
     end
 
-    class ValidationMiddleware
+    # Middleware for validating MCP protocol requests using JSON schema
+    # Validates JSON-RPC 2.0 structure and tool argument schemas
+    class SchemaValidationMiddleware
       def initialize(app, _security_config = nil)
         @app       = app
         @validator = Validator.new
@@ -82,10 +88,10 @@ class Otto
 
             # Reset body for downstream middleware
             request.body.rewind if request.body.respond_to?(:rewind)
-          rescue JSON::ParserError => ex
-            return validation_error_response(nil, "Invalid JSON: #{ex.message}")
-          rescue ValidationError => ex
-            return validation_error_response(data&.dig('id'), ex.message)
+          rescue JSON::ParserError => e
+            return validation_error_response(nil, "Invalid JSON: #{e.message}")
+          rescue ValidationError => e
+            return validation_error_response(data&.dig('id'), e.message)
           end
         end
 
@@ -102,15 +108,14 @@ class Otto
 
       def validation_error_response(id, message)
         body = JSON.generate({
-          jsonrpc: '2.0',
+                               jsonrpc: '2.0',
           id: id,
           error: {
             code: -32_600,
             message: 'Invalid Request',
             data: message,
           },
-        },
-                            )
+                             })
 
         [400, { 'content-type' => 'application/json' }, [body]]
       end