otto 1.6.0 → 2.0.0.pre1

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/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

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Modules
+  class Validator
+    def validate
+      [200, { 'content-type' => 'application/json' }, ['{"validation": "passed", "module": "Validator"}']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/routes_app.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+# Main application class demonstrating advanced routes syntax
+class RoutesApp
+  # ========================================
+  # BASIC ROUTES
+  # ========================================
+
+  def self.index
+    [200, { 'content-type' => 'text/html' }, ['<h1>Advanced Routes Syntax Example</h1><p>Otto v1.5.0+ Features</p>']]
+  end
+
+  def self.receive_feedback
+    [200, { 'content-type' => 'text/plain' }, ['Feedback received']]
+  end
+
+  # ========================================
+  # RESPONSE TYPE ROUTES
+  # ========================================
+
+  def self.list_users
+    users = [
+      { id: 1, name: 'Alice', role: 'admin' },
+      { id: 2, name: 'Bob', role: 'user' },
+    ]
+    [200, { 'content-type' => 'application/json' }, [users.to_json]]
+  end
+
+  def self.create_user
+    [201, { 'content-type' => 'application/json' }, ['{"message": "User created", "id": 3}']]
+  end
+
+  def self.health_check
+    [200, { 'content-type' => 'application/json' }, ['{"status": "healthy", "timestamp": "' + Time.now.iso8601 + '"}']]
+  end
+
+  def self.update_user
+    [200, { 'content-type' => 'application/json' }, ['{"message": "User updated"}']]
+  end
+
+  def self.delete_user
+    [204, {}, ['']]
+  end
+
+  def self.dashboard
+    [200, { 'content-type' => 'text/html' }, ['<h1>Dashboard</h1><p>HTML view response</p>']]
+  end
+
+  def self.reports
+    [200, { 'content-type' => 'text/html' }, ['<h1>Reports</h1><p>View response type demonstration</p>']]
+  end
+
+  def self.admin_panel
+    [200, { 'content-type' => 'text/html' }, ['<h1>Admin Panel</h1><p>Administrative interface</p>']]
+  end
+
+  def self.login_redirect
+    [302, { 'location' => '/dashboard' }, ['']]
+  end
+
+  def self.logout_redirect
+    [302, { 'location' => '/' }, ['']]
+  end
+
+  def self.home_redirect
+    [302, { 'location' => '/dashboard' }, ['']]
+  end
+
+  def self.flexible_data
+    data = { message: 'This is flexible data', timestamp: Time.now.iso8601 }
+    [200, { 'content-type' => 'application/json' }, [data.to_json]]
+  end
+
+  def self.flexible_content
+    [200, { 'content-type' => 'application/json' }, ['{"content": "Auto response type", "format": "negotiated"}']]
+  end
+
+  # ========================================
+  # CSRF ROUTES
+  # ========================================
+
+  def self.webhook_handler
+    [200, { 'content-type' => 'application/json' }, ['{"message": "Webhook processed (CSRF exempt)"}']]
+  end
+
+  def self.external_update
+    [200, { 'content-type' => 'application/json' }, ['{"message": "External update processed"}']]
+  end
+
+  def self.cleanup_data
+    [200, { 'content-type' => 'application/json' }, ['{"message": "Data cleanup completed"}']]
+  end
+
+  def self.sync_data
+    [200, { 'content-type' => 'application/json' }, ['{"message": "Data sync completed"}']]
+  end
+
+  def self.update_settings
+    [200, { 'content-type' => 'text/plain' }, ['Settings updated (CSRF protected)']]
+  end
+
+  def self.change_password
+    [200, { 'content-type' => 'text/plain' }, ['Password changed (CSRF protected)']]
+  end
+
+  def self.delete_profile
+    [204, {}, ['']]
+  end
+
+  # ========================================
+  # MULTIPLE PARAMETER COMBINATIONS
+  # ========================================
+
+  def self.api_data
+    [200, { 'content-type' => 'application/json' }, ['{"api": "v1", "data": "response"}']]
+  end
+
+  def self.api_submit
+    [201, { 'content-type' => 'application/json' }, ['{"message": "API submission processed"}']]
+  end
+
+  def self.api_update
+    [200, { 'content-type' => 'application/json' }, ['{"message": "API update completed"}']]
+  end
+
+  def self.admin_dashboard
+    [200, { 'content-type' => 'text/html' }, ['<h1>Admin Dashboard</h1><p>Administrative view</p>']]
+  end
+
+  def self.admin_settings
+    [200, { 'content-type' => 'text/html' }, ['<h1>Admin Settings</h1><p>Settings updated</p>']]
+  end
+
+  def self.mixed_content
+    [200, { 'content-type' => 'application/json' }, ['{"type": "mixed", "csrf": "exempt", "response": "auto"}']]
+  end
+
+  # ========================================
+  # CUSTOM PARAMETERS
+  # ========================================
+
+  def self.show_config
+    [200, { 'content-type' => 'application/json' }, ['{"environment": "production", "config": "displayed"}']]
+  end
+
+  def self.debug_info
+    [200, { 'content-type' => 'application/json' }, ['{"environment": "development", "debug": true}']]
+  end
+
+  def self.update_config
+    [200, { 'content-type' => 'application/json' }, ['{"message": "Config updated", "environment": "production"}']]
+  end
+
+  def self.feature_flags
+    [200, { 'content-type' => 'application/json' }, ['{"feature": "advanced", "mode": "enabled", "flags": []}']]
+  end
+
+  def self.toggle_feature
+    [200, { 'content-type' => 'application/json' }, ['{"feature": "beta", "mode": "test", "toggled": true}']]
+  end
+
+  # ========================================
+  # PARAMETER VALUE VARIATIONS
+  # ========================================
+
+  def self.api_v1
+    [200, { 'content-type' => 'application/json' }, ['{"version": "1.0", "api": "v1"}']]
+  end
+
+  def self.api_v2
+    [200, { 'content-type' => 'application/json' }, ['{"version": "2.0", "api": "v2"}']]
+  end
+
+  def self.api_legacy
+    [200, { 'content-type' => 'application/json' }, ['{"version": "legacy", "deprecated": true}']]
+  end
+
+  def self.complex_query
+    [200, { 'content-type' => 'application/json' }, ['{"query": "complex", "filter": "key=value"}']]
+  end
+
+  def self.config_db
+    [200, { 'content-type' => 'application/json' }, ['{"connection": "host=localhost", "configured": true}']]
+  end
+
+  # ========================================
+  # ERROR HANDLERS
+  # ========================================
+
+  def self.not_found
+    [404, { 'content-type' => 'text/html' }, ['<h1>404 - Page Not Found</h1><p>Advanced routes syntax example</p>']]
+  end
+
+  def self.server_error
+    [500, { 'content-type' => 'text/html' }, ['<h1>500 - Server Error</h1><p>Something went wrong</p>']]
+  end
+
+  # ========================================
+  # TESTING ROUTES
+  # ========================================
+
+  def self.test_json
+    [200, { 'content-type' => 'application/json' }, ['{"test": "json", "response_type": "json"}']]
+  end
+
+  def self.test_view
+    [200, { 'content-type' => 'text/html' }, ['<h1>Test View</h1><p>HTML view response</p>']]
+  end
+
+  def self.test_redirect
+    [302, { 'location' => '/' }, ['']]
+  end
+
+  def self.test_auto
+    [200, { 'content-type' => 'application/json' }, ['{"test": "auto", "response_type": "auto"}']]
+  end
+
+  def self.test_csrf
+    [200, { 'content-type' => 'text/html' }, ['<h1>CSRF Test</h1><p>POST request (CSRF protected)</p>']]
+  end
+
+  def self.test_no_csrf
+    [200, { 'content-type' => 'text/html' }, ['<h1>No CSRF Test</h1><p>POST request (CSRF exempt)</p>']]
+  end
+
+  def self.test_everything
+    [200, { 'content-type' => 'application/json' }, ['{"message": "All parameters tested", "csrf": "exempt", "custom": "value"}']]
+  end
+end

data/examples/advanced_routes/app/controllers/v2/admin.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module V2
+  class Admin
+    def self.show
+      [200, { 'content-type' => 'text/html' }, ['<h1>V2 Admin</h1><p>Class method implementation</p>']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/v2/config.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module V2
+  class Config
+    def self.update
+      [200, { 'content-type' => 'application/json' }, ['{"message": "V2 config updated"}']]
+    end
+  end
+end

data/examples/advanced_routes/app/controllers/v2/settings.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module V2
+  class Settings
+    def self.modify
+      [200, { 'content-type' => 'application/json' }, ['{"message": "V2 settings modified", "csrf": "exempt"}']]
+    end
+  end
+end

data/examples/advanced_routes/app/logic/admin/logic/manager.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Admin
+  module Logic
+    class Manager
+      attr_reader :context, :params, :locale
+
+      def initialize(context, params, locale)
+        @context = context
+        @params = params
+        @locale = locale
+      end
+
+      def process
+        {
+          admin_manager: 'Active',
+          namespace: 'Admin::Logic',
+          management_tools: ['users', 'settings', 'logs'],
+        }
+      end
+
+      def response_data
+        { admin_logic_manager: process }
+      end
+    end
+  end
+end