otto 1.6.0 → 2.0.0.pre2

data/docs/migrating/v2.0.0-pre1.md

@@ -0,0 +1,276 @@
+# Migrating to Otto v2.0.0-pre1
+
+## What's New in v2.0.0-pre1
+
+This pre-release includes extensive test coverage improvements (76 new test cases), core module refactoring, middleware stack unification, and a major update to Logic class authentication patterns. See the [full changelog](../../CHANGELOG.rst#changelog-2.0.0-pre1) for complete details.
+
+The main breaking changes affect:
+1. Applications that directly manipulate the middleware stack
+2. Logic classes using the old authentication signature
+
+## Middleware Stack Unified API
+
+Otto v2.0.0-pre1 introduces a significant refactoring of the middleware stack management, providing a more consistent and efficient approach to middleware configuration.
+
+### Key Changes
+
+#### Unified Middleware Registration
+
+Previous versions had separate legacy and new middleware stacks. In v2.0.0-pre1, we've consolidated these into a single, more powerful middleware stack.
+
+**Before:**
+```ruby
+# Old approach with separate stacks
+otto.middleware_stack << SomeMiddleware
+otto.middleware.add(AnotherMiddleware)
+```
+
+**After:**
+```ruby
+# Unified middleware registration
+otto.use(SomeMiddleware)
+otto.use(AnotherMiddleware)
+```
+
+#### Performance Improvements
+
+- Middleware lookup is now O(1) using a Set
+- Memoized middleware list reduces repeated array creation
+- Prevent duplicate middleware registrations with identical configurations
+
+### Migration Steps
+
+1. Replace all `otto.middleware_stack <<` calls with `otto.use()`
+2. Remove any direct references to `otto.middleware_stack`
+3. Use `otto.middleware.includes?()` instead of manual stack checks
+
+### Authentication and Security Methods
+
+Authentication and security methods now consistently use the new unified middleware stack:
+
+```ruby
+# Before
+otto.middleware_stack << Otto::Security::CSRFMiddleware
+
+# After (no change needed)
+otto.enable_csrf_protection!
+```
+
+### Performance Considerations
+
+The new implementation is more memory-efficient and provides faster middleware lookups, especially for applications with many middleware components.
+
+### Potential Breaking Changes
+
+- Code relying on direct manipulation of `middleware_stack` will need updates
+- Method signatures for middleware configuration remain the same
+
+### Example Migration
+
+```ruby
+# Old code
+class MyApp
+  def initialize
+    @otto = Otto.new
+    @otto.middleware_stack << CustomMiddleware
+    @otto.middleware.add(AnotherMiddleware)
+  end
+end
+
+# New code
+class MyApp
+  def initialize
+    @otto = Otto.new
+    @otto.use(CustomMiddleware)
+    @otto.use(AnotherMiddleware)
+  end
+end
+```
+
+### Troubleshooting
+
+If you encounter any issues with middleware registration or configuration, please file an issue at [Otto GitHub Repository](https://github.com/delano/otto/issues).
+
+## Logic Class RequestContext Pattern
+
+Otto v2.0.0-pre1 introduces a major improvement to Logic class authentication with the new RequestContext pattern.
+
+### Key Changes
+
+#### New Constructor Signature
+
+Logic classes now use a cleaner, more powerful constructor signature that provides immutable context.
+
+**Before:**
+```ruby
+class MyLogic
+  attr_reader :session, :user, :params, :locale
+
+  def initialize(session, user, params, locale)
+    @session = session
+    @user = user
+    @params = params
+    @locale = locale
+  end
+
+  def process
+    return { error: 'not authenticated' } unless @user
+    { result: 'success', user_name: @user['name'] }
+  end
+end
+```
+
+**After:**
+```ruby
+class MyLogic
+  attr_reader :context, :params, :locale
+
+  def initialize(context, params, locale)
+    @context = context
+    @params = params
+    @locale = locale
+  end
+
+  def process
+    return { error: 'not authenticated' } unless @context.authenticated?
+    {
+      result: 'success',
+      user_name: @context.user_name,
+      roles: @context.roles,
+      permissions: @context.permissions
+    }
+  end
+end
+```
+
+#### RequestContext Benefits
+
+1. **Immutable Structure** - RequestContext is a Ruby Data class that can't be accidentally modified
+2. **Helper Methods** - Built-in methods like `authenticated?`, `has_role?`, `has_permission?`
+3. **Cleaner Interface** - Single context parameter instead of separate session/user parameters
+4. **Type Safety** - Better IDE support and documentation
+5. **Future-proof** - New authentication data automatically available
+
+#### RequestContext API
+
+```ruby
+# Authentication status
+context.authenticated?     # Boolean: has non-empty user data
+context.anonymous?         # Boolean: not authenticated
+
+# User information
+context.user_id           # User ID from various possible locations
+context.user_name         # User name/username
+context.session_id        # Session identifier
+
+# Role and permission checks
+context.has_role?('admin')              # Single role check
+context.has_permission?('write')        # Single permission check
+context.has_any_role?('admin', 'mod')   # Multiple role check
+context.roles                           # Array of all user roles
+context.permissions                     # Array of all user permissions
+
+# Raw data access
+context.session          # Session hash
+context.user            # User hash
+context.auth_method     # Authentication method used
+context.metadata        # Additional context data
+```
+
+### Migration Steps
+
+1. **Update Logic class constructor signatures** from 4 parameters to 3:
+   ```ruby
+   # Change this:
+   def initialize(session, user, params, locale)
+
+   # To this:
+   def initialize(context, params, locale)
+   ```
+
+2. **Update instance variables**:
+   ```ruby
+   # Change this:
+   @session = session
+   @user = user
+
+   # To this:
+   @context = context
+   ```
+
+3. **Update authentication checks**:
+   ```ruby
+   # Change this:
+   return error unless @user
+
+   # To this:
+   return error unless @context.authenticated?
+   ```
+
+4. **Update data access**:
+   ```ruby
+   # Change this:
+   user_name = @user&.dig('name')
+   user_role = @user&.dig('role')
+
+   # To this:
+   user_name = @context.user_name
+   user_role = @context.roles.first
+   ```
+
+### Example Migration
+
+**Before (v1.x):**
+```ruby
+class AdminPanel
+  attr_reader :session, :user, :params, :locale
+
+  def initialize(session, user, params, locale)
+    @session = session
+    @user = user
+    @params = params
+    @locale = locale
+  end
+
+  def raise_concerns
+    raise 'Access denied' unless @user&.dig('role') == 'admin'
+  end
+
+  def process
+    {
+      panel: 'admin',
+      user: @user&.dig('name') || 'unknown',
+      session_id: @session&.dig('id')
+    }
+  end
+end
+```
+
+**After (v2.0):**
+```ruby
+class AdminPanel
+  attr_reader :context, :params, :locale
+
+  def initialize(context, params, locale)
+    @context = context
+    @params = params
+    @locale = locale
+  end
+
+  def raise_concerns
+    raise 'Access denied' unless @context.has_role?('admin')
+  end
+
+  def process
+    {
+      panel: 'admin',
+      user: @context.user_name || 'unknown',
+      session_id: @context.session_id,
+      authenticated: @context.authenticated?,
+      permissions: @context.permissions
+    }
+  end
+end
+```
+
+This provides a cleaner, more maintainable interface while giving Logic classes access to rich authentication context.

data/docs/migrating/v2.0.0-pre2.md

@@ -0,0 +1,345 @@
+# Otto v2.0.0-pre2 Migration Guide
+
+## Overview
+
+This release resolves critical architectural issues with `StrategyResult` semantics and removes deprecated methods. The changes clarify the distinction between "request state" (user in session) and "authentication outcomes" (auth attempt just succeeded).
+
+## Breaking Changes
+
+### 1. StrategyResult Methods Removed
+
+**Removed Methods:**
+- `StrategyResult#success?` - Always returned `true`, meaningless
+- `StrategyResult#failure?` - Always returned `false`, meaningless
+- `FailureResult#success?` - Always returned `false`
+- `FailureResult#failure?` - Always returned `true`
+
+**Migration:**
+
+```ruby
+# Before - checking success/failure
+if strategy_result&.success?
+  # handle success
+end
+
+# After - type checking
+if strategy_result.is_a?(Otto::Security::Authentication::StrategyResult)
+  # handle success
+end
+
+# Or for middleware - FailureResult indicates failure
+if strategy_result.is_a?(Otto::Security::Authentication::FailureResult)
+  # handle failure
+else
+  # handle success
+end
+```
+
+### 2. New Semantic Distinction
+
+**New Method:**
+- `StrategyResult#auth_attempt_succeeded?` - Returns `true` only when auth strategy just executed successfully
+
+**Key Semantic Difference:**
+
+| Method | Meaning | Use Case |
+|--------|---------|----------|
+| `authenticated?` | User in session (request state) | Check if session has user |
+| `auth_attempt_succeeded?` | Auth strategy just succeeded (auth outcome) | Post-login redirects, analytics |
+
+**Migration Examples:**
+
+#### Registration Flow (IMPORTANT)
+
+```ruby
+# Before - BROKEN - blocks legitimate registration
+class CreateAccount < Logic::Base
+  def raise_concerns
+    # This was always true if user in session, blocking registration
+    raise OT::FormError, "Already signed up" if @strategy_result.success?
+  end
+end
+
+# After - CORRECT
+class CreateAccount < Logic::Base
+  def raise_concerns
+    # Check if user already in session
+    raise OT::FormError, "Already signed up" if @strategy_result.authenticated?
+  end
+end
+```
+
+#### Post-Login Redirect
+
+```ruby
+# Before - unreliable
+class AuthController
+  def authenticate
+    if @strategy_result.success?  # Always true, not helpful
+      redirect_to dashboard_path
+    end
+  end
+end
+
+# After - correct semantic
+class AuthController
+  def authenticate
+    if @strategy_result.auth_attempt_succeeded?
+      # Only redirect when auth route just succeeded
+      redirect_to dashboard_path
+    end
+  end
+end
+```
+
+## Non-Breaking Enhancements
+
+### 1. Comprehensive Documentation
+
+`StrategyResult` now includes extensive inline documentation:
+- Usage patterns and creation guidelines
+- Session contract for multi-app architectures
+- Examples for common scenarios
+- Clear distinction between request state and auth outcomes
+
+### 2. Session Contract (Multi-App Architectures)
+
+For shared session architectures (Auth app + Core app):
+
+**Required session keys for authenticated state:**
+```ruby
+session['authenticated']     # Boolean flag
+session['identity_id']       # User/customer ID
+session['authenticated_at']  # Timestamp
+```
+
+**Optional session keys:**
+```ruby
+session['email']            # User email
+session['ip_address']       # Client IP
+session['user_agent']       # Client UA
+session['locale']           # User locale
+```
+
+**Advanced mode adds:**
+```ruby
+session['account_external_id']  # Rodauth external_id
+session['advanced_account_id']  # Rodauth account ID
+```
+
+## Application Code Updates Required
+
+### 1. Remove Manual StrategyResult Creation
+
+**Anti-pattern identified:**
+```ruby
+# BAD - Bypasses Otto's auth_method tracking
+class Controller::Base
+  def _strategy_result
+    Otto::Security::Authentication::StrategyResult.new(
+      session: session,
+      user: cust,
+      auth_method: 'session',  # Hardcoded - loses semantic meaning
+      metadata: { ip: req.client_ipaddress }
+    )
+  end
+end
+```
+
+**Correct approach:**
+```ruby
+# GOOD - Use middleware-provided result
+class Controller::Base
+  def strategy_result
+    req.env['otto.strategy_result']  # Created by AuthenticationMiddleware
+  end
+end
+
+# Or for non-auth checks, use session directly
+class Controller::Base
+  def current_user
+    return nil unless session['authenticated']
+    Customer.find(session['identity_id'])
+  end
+end
+```
+
+### 2. Update Logic Classes
+
+**Pattern to check for:**
+```ruby
+# Search your codebase for these patterns:
+grep -r "@strategy_result.success?" apps/
+grep -r "@context.success?" apps/
+grep -r "strategy_result&.success?" apps/
+```
+
+**Update to:**
+- Use `authenticated?` for "user in session" checks (registration, profile access, etc.)
+- Use `auth_attempt_succeeded?` for "just logged in" checks (redirects, welcome messages, etc.)
+
+### 3. Test Updates
+
+**RSpec matchers:**
+```ruby
+# Before
+expect(result).to be_success
+expect(result).to be_failure
+
+# After
+expect(result).to be_a(Otto::Security::Authentication::StrategyResult)
+expect(result).to be_a(Otto::Security::Authentication::FailureResult)
+```
+
+## Architecture Clarifications
+
+### When StrategyResult is Created
+
+1. **Routes WITH `auth=...` requirement:**
+   - Strategy executes
+   - Returns `StrategyResult` (success) or `FailureResult` (failure)
+   - Middleware converts `FailureResult` to anonymous `StrategyResult` + 401 response
+
+2. **Routes WITHOUT `auth=...` requirement:**
+   - Middleware creates anonymous `StrategyResult`
+   - Sets `auth_method: 'anonymous'`
+
+3. **Auth app (Roda) routes:**
+   - Manually creates `StrategyResult` for Logic class compatibility
+   - Same interface as Otto controllers
+
+### Integration Boundaries
+
+**Multi-app setup (Auth + Core + API):**
+- **Shared:** Session middleware, Redis session, Logic classes, Customer model
+- **Auth app:** Creates StrategyResult manually, uses Roda routing
+- **Core/API apps:** StrategyResult from AuthenticationMiddleware
+- **Integration:** Pure session-based, no direct code calls between apps
+
+## Testing Your Migration
+
+### 1. Registration Flow Test
+
+```ruby
+describe "CreateAccount" do
+  it "blocks registration when user already authenticated" do
+    strategy_result = Otto::Security::Authentication::StrategyResult.new(
+      session: { user_id: 123 },
+      user: { id: 123 },
+      auth_method: 'anonymous',  # No auth route, but user in session
+      metadata: {}
+    )
+
+    logic = CreateAccount.new(strategy_result, params, 'en')
+
+    expect { logic.raise_concerns }.to raise_error(OT::FormError, /Already signed up/)
+  end
+end
+```
+
+### 2. Auth Attempt Test
+
+```ruby
+describe "LoginHandler" do
+  it "redirects after successful authentication" do
+    strategy_result = Otto::Security::Authentication::StrategyResult.new(
+      session: { user_id: 123 },
+      user: { id: 123 },
+      auth_method: 'session',  # Auth route succeeded
+      metadata: {}
+    )
+
+    expect(strategy_result.authenticated?).to be true
+    expect(strategy_result.auth_attempt_succeeded?).to be true
+  end
+end
+```
+
+## Checklist
+
+- [ ] Remove all usage of `success?` and `failure?` methods
+- [ ] Update registration flows to use `authenticated?`
+- [ ] Update post-login flows to use `auth_attempt_succeeded?` if needed
+- [ ] Remove manual `StrategyResult` creation in controllers
+- [ ] Update test matchers from `be_success`/`be_failure` to type checks
+- [ ] Verify session contract keys match across apps
+- [ ] Run full test suite: `bundle exec rspec`
+- [ ] Test registration while logged in (should be blocked)
+- [ ] Test login redirect flow (should work correctly)
+
+## Configuration Updates
+
+### Authentication Login Path Configuration
+
+When authentication fails for HTML requests, Otto redirects to a login page. You can configure this path:
+
+```ruby
+# Initialize with login_path configuration
+otto = Otto.new do
+  auth_config[:login_path] = '/auth/login'  # Default: '/signin'
+end
+
+# Or configure after initialization
+otto.auth_config[:login_path] = '/custom/login'
+```
+
+**Note:** If not configured, the default fallback is `/signin`. Ensure this route exists or configure your actual login path to avoid 404 errors on authentication failures.
+
+## Additional Improvements in v2.0.0-pre2
+
+### Middleware Architecture Enhancements
+
+**1. Renamed MCP ValidationMiddleware → SchemaValidationMiddleware**
+- Resolves naming collision with `Otto::Security::ValidationMiddleware`
+- `Otto::MCP::SchemaValidationMiddleware` now clearly indicates JSON schema validation
+- `Otto::Security::ValidationMiddleware` remains for input sanitization
+
+**Migration:**
+```ruby
+# File renamed: lib/otto/mcp/validation.rb → lib/otto/mcp/schema_validation.rb
+# Class renamed automatically if using Otto's MCP server
+# No action needed for most users
+```
+
+**2. Centralized Env Keys Documentation**
+- New file: `lib/otto/env_keys.rb`
+- Documents all `env['otto.*']` keys with types, setters, and users
+- Includes usage examples and multi-app integration patterns
+- Essential reference for custom middleware development
+
+**3. RateLimitMiddleware Clarity**
+- Added documentation clarifying it's a CONFIGURATOR, not enforcer
+- Actual rate limiting happens in Rack::Attack middleware
+- `call` method is explicitly a pass-through
+
+**4. Middleware Order Enforcement**
+- New method: `MiddlewareStack#validate_mcp_middleware_order`
+- New method: `MiddlewareStack#add_with_position` for explicit ordering
+- MCP Server uses explicit positioning: `position: :first` and `position: :last`
+- Validates middleware order and warns if suboptimal
+- Optimal: RateLimitMiddleware → TokenMiddleware → SchemaValidationMiddleware
+- Validation runs automatically when MCP is enabled
+
+**Usage Example:**
+```ruby
+# Explicit positioning for clarity
+middleware.add_with_position(
+  Otto::MCP::RateLimitMiddleware,
+  security_config,
+  position: :first  # Ensures rate limiting runs first
+)
+
+middleware.add_with_position(
+  Otto::MCP::SchemaValidationMiddleware,
+  position: :last  # Ensures validation runs last
+)
+```
+
+## Questions?
+
+Review the comprehensive inline documentation in:
+- `lib/otto/security/authentication/strategy_result.rb` (lines 1-90) - Auth semantics
+- `lib/otto/security/authentication/authentication_middleware.rb` - Auth middleware
+- `lib/otto/env_keys.rb` - Complete env key registry
+
+The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.

data/examples/.gitignore

@@ -0,0 +1 @@
+!**/README.md

data/examples/advanced_routes/README.md

@@ -0,0 +1,33 @@
+# Otto - Advanced Routes Example
+
+This example demonstrates the advanced routing syntax features available in Otto, such as response type negotiation, CSRF exemptions, and routing to logic classes.
+
+## Project Structure
+
+The example is structured to separate concerns, making it easier to navigate:
+
+-   `config.ru`: The main Rackup file that loads and runs the Otto application.
+-   `routes`: A comprehensive file demonstrating various advanced routing syntaxes. This file serves as a good reference.
+-   `app.rb`: A simple loader that requires all controller and logic files.
+-   `app/controllers/`: Contains the `RoutesApp` class and other namespaced controller modules that handle incoming requests.
+-   `app/logic/`: Contains various "Logic Classes". These are special classes that can be routed to directly, encapsulating business logic for a specific route. They are organized into namespaces to show how Otto handles complex class names.
+-   `run.rb`, `puma.rb`, `test.rb`: Alternative ways to run or test the application.
+
+## Key Features Demonstrated
+
+-   **Response Types:** Defining `response=json`, `response=view`, etc., directly in the `routes` file.
+-   **CSRF Exemption:** Using `csrf=exempt` for APIs or webhooks.
+-   **Logic Classes:** Routing directly to a class (e.g., `GET /logic/simple SimpleLogic`). Otto automatically instantiates it and calls its `process` method.
+-   **Namespaced Targets:** Routing to deeply namespaced classes and modules (e.g., `GET /logic/v2/dashboard V2::Logic::Dashboard`).
+-   **Custom Parameters:** Adding arbitrary key-value parameters to a route for custom logic.
+
+## Running the Example
+
+1.  Make sure you have the necessary gems installed (`bundle install`).
+2.  Run the application from the root of the `otto` project:
+
+    ```sh
+    rackup examples/advanced_routes/config.ru
+    ```
+
+3.  The application will be running at `http://localhost:9292`. You can use `curl` or your browser to test the various routes defined in the `routes` file.

data/examples/advanced_routes/app/controllers/handlers/async.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Handlers
+  class Async
+    def execute
+      [200, { 'content-type' => 'application/json' }, ['{"execution": "async", "csrf": "exempt"}']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/handlers/dynamic.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Handlers
+  class Dynamic
+    def process
+      [200, { 'content-type' => 'application/json' }, ['{"handler": "dynamic", "processed": true}']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/handlers/static.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Handlers
+  class Static
+    def self.serve
+      [200, { 'content-type' => 'text/html' }, ['<h1>Static Handler</h1><p>Static content served</p>']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/modules/auth.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Modules
+  class Auth
+    def process
+      [200, { 'content-type' => 'text/html' }, ['<h1>Auth Module</h1><p>Instance method implementation</p>']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/modules/transformer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Modules
+  class Transformer
+    def transform
+      [200, { 'content-type' => 'application/json' }, ['{"transformation": "complete", "csrf": "exempt"}']]
+    end
+  end
+end