otto 2.0.0.pre3 → 2.0.0.pre8

data/examples/authentication_strategies/README.md

@@ -1,32 +1,225 @@
 # Otto - Authentication Strategies Example
 
-This example demonstrates how to use Otto's powerful authentication features.
+This example demonstrates Otto's flexible authentication system with multiple strategies, token validation, and role-based access control.
+
+## What You'll Learn
+
+- How to configure multiple authentication strategies
+- Token-based authentication with session validation
+- API key authentication for programmatic access
+- Role and permission-based access control
+- How to protect routes with authentication requirements
+- Handling authentication failures and redirects
 
 ## Structure
 
-*   `config.ru`: The Rackup file. It initializes Otto and loads the authentication strategies.
-*   `routes`: Defines the application's routes and the authentication required for each.
-*   `app/auth.rb`: Contains the definitions for all authentication strategies. This is where you would add your own.
-*   `app/controllers/`: Contains the controller classes that handle requests.
+- `config.ru`: Rack configuration that initializes Otto and loads auth strategies
+- `routes`: Application routes with authentication requirements
+- `app/auth.rb`: Authentication strategy definitions and token setup
+- `app/controllers/`: Handler classes for protected and public routes
+
+## Authentication Strategies in This Example
+
+### Token-Based Auth
+Validates user tokens for web applications:
+```
+GET  /profile  HomeController#profile  auth=token
+```
+Requires: `?token=demo_token`
+
+### Admin Role Auth
+Validates admin-level access:
+```
+GET  /admin    AdminController#dashboard  auth=admin
+```
+Requires: `?token=admin_token`
+
+### Permission-Based Auth
+Validates specific permissions:
+```
+POST /edit     ArticleController#update  auth=can_write
+```
+Requires: `?token=demo_token` (with write permission)
+
+### API Key Auth
+Validates API keys for programmatic access:
+```
+GET  /api/data  ApiController#show  auth=api_key
+```
+Requires: `?api_key=demo_api_key_123`
+
+## How to Run
+
+### Using rackup (recommended)
+
+```sh
+cd examples/authentication_strategies
+rackup config.ru
+```
+
+### Using alternative servers
+
+```sh
+thin -R config.ru -p 9292 start
+puma config.ru -p 9292
+```
+
+Open your browser and navigate to `http://localhost:9292`.
+
+## Testing Authentication
+
+### Web Browser (Token-based)
+
+Click these links or visit them directly:
+
+- **Public page**: [http://localhost:9292/](http://localhost:9292/)
+- **Authenticated user**: [http://localhost:9292/profile?token=demo_token](http://localhost:9292/profile?token=demo_token)
+- **Admin user**: [http://localhost:9292/admin?token=admin_token](http://localhost:9292/admin?token=admin_token)
+- **User with write permission**: [http://localhost:9292/edit?token=demo_token](http://localhost:9292/edit?token=demo_token)
+
+### curl Commands (API Key)
+
+```sh
+# Without API key (fails)
+curl http://localhost:9292/api/data
+
+# With API key (succeeds)
+curl "http://localhost:9292/api/data?api_key=demo_api_key_123"
+```
+
+### Testing Invalid Credentials
+
+Try accessing protected routes without valid credentials:
+
+```sh
+# No token - redirects to login or returns 401
+curl http://localhost:9292/profile
+
+# Invalid token - returns 401
+curl "http://localhost:9292/profile?token=invalid"
+
+# Wrong token type - returns 401
+curl "http://localhost:9292/admin?api_key=demo_api_key_123"
+```
+
+## Expected Output
+
+### Successful Authentication
+```
+HTTP/1.1 200 OK
+Content-Type: text/html
+
+<h1>Welcome, alice!</h1>
+<p>This is your profile.</p>
+```
+
+### Failed Authentication
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: text/plain
+
+Unauthorized
+```
+
+### Redirect to Login
+```
+HTTP/1.1 302 Found
+Location: http://localhost:9292/?login=required
+```
+
+## File Structure Details
+
+### Routes File
+- Public routes (no `auth=` requirement)
+- Protected routes with different auth strategies
+- Admin-only routes
+- API routes with API key authentication
+
+### Auth Strategies (`app/auth.rb`)
+- Token validation logic with demo tokens
+- Admin role checking
+- Permission validation (read, write, admin)
+- API key validation for programmatic access
+
+### Controllers (`app/controllers/`)
+- Welcome controller for public pages
+- Profile controller for authenticated users
+- Admin controller for admin-only pages
+- Article controller for permission-based access
+- API controller for programmatic access
+
+## Key Concepts
+
+### Strategy Registration
+Strategies are registered in `config.ru` before the first request:
+
+```ruby
+app.add_auth_strategy('token', TokenStrategy.new)
+app.add_auth_strategy('admin', AdminStrategy.new)
+app.add_auth_strategy('api_key', APIKeyStrategy.new)
+```
+
+### Route Protection
+Routes specify their auth requirement in the routes file:
+
+```
+GET  /protected  Controller#method  auth=token
+POST /admin      Controller#admin   auth=admin
+```
+
+### User Context
+After successful authentication, `req.user_context` contains user info:
+
+```ruby
+def profile
+  user_id = @req.user_context[:user_id]
+  @res.body = "Welcome, #{user_id}!"
+end
+```
+
+## Demo Credentials
+
+### Tokens
+- `demo_token` - Regular user (Alice)
+  - Permissions: read, write
+  - Roles: user
+- `admin_token` - Administrator
+  - Permissions: read, write, admin
+  - Roles: admin, user
+
+### API Keys
+- `demo_api_key_123` - Demo API access
+- Additional keys can be added to `app/auth.rb`
+
+## Customizing Authentication
 
-## Running the Demo
+To add your own authentication:
 
-1.  Make sure you have the necessary gems installed (`bundle install`).
-2.  Run the application from the root of the `otto` project:
+1. **Create a strategy class**:
+   ```ruby
+   class MyStrategy < Otto::Security::Authentication::AuthStrategy
+     def authenticate(env, requirement)
+       # Validate credentials
+       success_result(user_id: 'alice')  # or failure_result
+     end
+   end
+   ```
 
-    ```sh
-    rackup examples/authentication_strategies/config.ru
-    ```
+2. **Register it in config.ru**:
+   ```ruby
+   app.add_auth_strategy('my_strategy', MyStrategy.new)
+   ```
 
-3.  Open your browser and navigate to `http://localhost:9292`.
+3. **Use it in routes**:
+   ```
+   GET  /protected  Controller#method  auth=my_strategy
+   ```
 
-## Trying the Authentication Strategies
+## Next Steps
 
-You can test the different authentication strategies by providing a `token` or `api_key` parameter in the URL.
+- Explore [Security Features](../security_features/) for CSRF, input validation, file uploads
+- Review [Advanced Routes](../advanced_routes/) for response types and logic classes
 
-*   **Authenticated User:** [http://localhost:9292/profile?token=demo_token](http://localhost:9292/profile?token=demo_token)
-*   **Admin User:** [http://localhost:9292/admin?token=admin_token](http://localhost:9292/admin?token=admin_token)
-*   **User with 'write' permission:** [http://localhost:9292/edit?token=demo_token](http://localhost:9292/edit?token=demo_token)
-*   **API Key:** [http://localhost:9292/api/data?api_key=demo_api_key_123](http://localhost:9292/api/data?api_key=demo_api_key_123)
+## Further Reading
 
-If you try to access a protected route without the correct token, you'll get an authentication error.
+- [CLAUDE.md](../../CLAUDE.md#authentication-architecture) - Detailed auth documentation

data/examples/backtrace_sanitization_demo.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo script showing Otto's automatic backtrace sanitization in structured_log
+#
+# This demonstrates that Otto now automatically sanitizes backtraces when they
+# appear in structured log data, eliminating the need for monkey patches.
+
+require_relative '../lib/otto'
+require 'logger'
+
+# Set up Otto with a logger to see the output
+Otto.logger = Logger.new($stdout)
+Otto.logger.level = Logger::DEBUG
+Otto.debug = true
+
+puts "=== Otto Backtrace Sanitization Demo ==="
+puts
+
+# Example 1: Raw backtrace with sensitive paths
+puts "1. Raw backtrace with sensitive system paths:"
+raw_backtrace = [
+  '/Users/admin/secret-project/app/controllers/users_controller.rb:42:in `create\'',
+  '/home/deploy/.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0/gems/rack-3.1.8/lib/rack/builder.rb:310:in `call\'',
+  '/usr/local/ruby/3.2.0/lib/ruby/3.2.0/logger.rb:310:in `add\'',
+  '/opt/bundler/gems/custom-gem-abc123def456/lib/custom.rb:50:in `process\'',
+  '/some/unknown/external/path/mystery.rb:100:in `mystery_method\''
+]
+
+Otto.structured_log(:error, 'Exception backtrace', {
+  error_id: 'demo123',
+  error: 'User creation failed',
+  backtrace: raw_backtrace
+})
+
+puts
+
+# Example 2: Non-backtrace data remains unchanged
+puts "2. Non-backtrace arrays are not affected:"
+Otto.structured_log(:info, 'Request processed', {
+  method: 'POST',
+  path: '/users',
+  tags: ['important', 'user-creation', 'api'],
+  middleware_stack: ['CSRF', 'Auth', 'RateLimit']
+})
+
+puts
+
+# Example 3: Mixed data with backtrace
+puts "3. Mixed data with backtrace gets selectively sanitized:"
+Otto.structured_log(:warn, 'Validation warning with context', {
+  user_id: 'user_456',
+  validation_errors: ['email_invalid', 'password_too_short'],
+  backtrace: [
+    '/Users/developer/my-app/lib/validators/email.rb:25:in `validate_format\'',
+    '/home/app/.bundle/gems/activemodel-7.0.0/lib/active_model/validator.rb:155:in `validate\''
+  ],
+  request_id: 'req_789'
+})
+
+puts
+
+# Example 4: Empty or nil backtrace handling
+puts "4. Handles edge cases gracefully:"
+Otto.structured_log(:debug, 'Debug with empty backtrace', {
+  event: 'method_entry',
+  backtrace: [],
+  timestamp: Time.now.to_f
+})
+
+Otto.structured_log(:info, 'Info with nil backtrace', {
+  event: 'cache_hit',
+  backtrace: nil,
+  cache_key: 'user:123'
+})
+
+puts
+puts "=== Demo Complete ==="
+puts
+puts "Notice how:"
+puts "• Project paths become relative: 'app/controllers/users_controller.rb:42'"
+puts "• Gem paths get [GEM] prefix with versions removed: '[GEM] rack/lib/rack/builder.rb:310'"
+puts "• Ruby stdlib gets [RUBY] prefix: '[RUBY] logger.rb:310'"
+puts "• Unknown paths get [EXTERNAL] prefix: '[EXTERNAL] mystery.rb:100'"
+puts "• Non-backtrace arrays remain unchanged"
+puts "• This happens automatically in Otto.structured_log - no monkey patching needed!"

data/examples/basic/README.md

@@ -2,28 +2,79 @@
 
 This example demonstrates a basic Otto application with a single route that accepts both GET and POST requests.
 
+## What You'll Learn
+
+- How to define routes in plain-text format
+- Creating a basic request handler class
+- Working with Rack request and response objects
+- Running an Otto application with different servers
+- Simple form handling and redirects
+
 ## How to Run
 
-1.  Make sure you have `bundler` and `thin` installed:
+### Using rackup (recommended)
+
 ```sh
-  gem install bundler thin
+cd examples/basic
+rackup config.ru -p 10770
 ```
 
-2.  Install the dependencies from the root of the project:
+### Using thin
+
 ```sh
-  bundle install
+cd examples/basic
+thin -e dev -R config.ru -p 10770 start
 ```
 
-3.  Start the server from this directory (`examples/basic`):
+### Using puma
+
 ```sh
-  thin -e dev -R config.ru -p 10770 start
+cd examples/basic
+puma config.ru -p 10770
+```
+
+Open your browser and navigate to `http://localhost:10770`.
+
+## Expected Output
+
 ```
+Puma starting in single threaded mode...
+* Version 3.12.0 (ruby 3.2.0-p0), codename: Llama Litter Box
+* Min threads: 0, max threads: 32
+* Environment: development
+* Listening on tcp://127.0.0.1:10770
 
-4.  Open your browser and navigate to `http://localhost:10770`.
+[GET request to /]
+GET /  200 OK
+
+[Submitting feedback form]
+POST /feedback  302 Found
+Location: http://localhost:10770/
+```
+
+Then visit `http://localhost:10770` and submit feedback to see it in action.
 
 ## File Structure
 
 * `README.md`: This file.
-* `app.rb`: Contains the application logic. It has two methods: `index` to display the main page and `receive_feedback` to handle form submissions.
-* `config.ru`: The Rack configuration file that loads the Otto framework and the application.
-* `routes`: Defines the URL routes and maps them to methods in the `App` class.
+* `app.rb`: Contains the application logic with two methods:
+  - `index`: Displays the main page with a feedback form
+  - `receive_feedback`: Handles form submissions and redirects back home
+* `config.ru`: The Rack configuration file that loads Otto and the application.
+* `routes`: Defines the URL routes mapping to methods in the `App` class.
+
+## Trying It Out
+
+1. **View the home page**: Open `http://localhost:10770` in your browser
+2. **Submit feedback**: Enter text in the feedback form and click Submit
+3. **Check the redirect**: You should be redirected back to the home page
+
+## Next Steps
+
+- Explore [Advanced Routes](../advanced_routes/) to learn about response type negotiation
+- Check out [Authentication](../authentication_strategies/) for protecting routes
+- See [Security Features](../security_features/) for CSRF, input validation, and more
+
+## Further Reading
+
+- [CLAUDE.md](../../CLAUDE.md) - Developer guidance and patterns

data/examples/error_handler_registration.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Error Handler Registration
+#
+# This example demonstrates how to register custom error handlers for expected
+# business logic errors, preventing them from being logged as unhandled 500 errors.
+
+require_relative '../lib/otto'
+
+# Define some business logic error classes
+module MyApp
+  class MissingResourceError < StandardError; end
+  class ExpiredResourceError < StandardError; end
+
+  class RateLimitError < StandardError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: 60)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
+end
+
+# Create routes file
+routes_content = <<~ROUTES
+  GET /resource/:id  ResourceHandler.show
+  POST /action       ActionHandler.process
+ROUTES
+
+File.write('/tmp/otto_error_routes.txt', routes_content)
+
+# Define handlers that might raise expected errors
+class ResourceHandler
+  def self.show(req, res)
+    resource_id = req.params[:id]
+
+    # Simulate resource lookup
+    raise MyApp::MissingResourceError, "Resource #{resource_id} not found" if resource_id == 'missing'
+    raise MyApp::ExpiredResourceError, "Resource #{resource_id} expired" if resource_id == 'expired'
+
+    res.status = 200
+    res.headers['Content-Type'] = 'application/json'
+    res.write(JSON.generate({ id: resource_id, name: "Resource #{resource_id}" }))
+  end
+end
+
+class ActionHandler
+  def self.process(req, res)
+    # Simulate rate limiting
+    raise MyApp::RateLimitError.new('Too many requests', retry_after: 120)
+  end
+end
+
+# Create Otto app
+otto = Otto.new('/tmp/otto_error_routes.txt')
+
+# Register error handlers BEFORE first request
+puts "Registering error handlers..."
+
+# Basic registration with status code and log level
+otto.register_error_handler(MyApp::MissingResourceError, status: 404, log_level: :info)
+otto.register_error_handler(MyApp::ExpiredResourceError, status: 410, log_level: :info)
+
+# Advanced registration with custom response handler
+otto.register_error_handler(MyApp::RateLimitError, status: 429, log_level: :warn) do |error, req|
+  {
+    error: 'RateLimited',
+    message: error.message,
+    retry_after: error.retry_after,
+    path: req.path
+  }
+end
+
+puts "\n=== Test 1: Missing Resource (404) ==="
+env = {
+  'REQUEST_METHOD' => 'GET',
+  'PATH_INFO' => '/resource/missing',
+  'HTTP_ACCEPT' => 'application/json',
+  'REMOTE_ADDR' => '127.0.0.1'
+}
+
+status, headers, body = otto.call(env)
+puts "Status: #{status}"
+puts "Content-Type: #{headers['content-type']}"
+puts "Body: #{body.first}"
+puts "Log level: INFO (not ERROR)"
+
+puts "\n=== Test 2: Expired Resource (410) ==="
+env['PATH_INFO'] = '/resource/expired'
+
+status, headers, body = otto.call(env)
+puts "Status: #{status}"
+puts "Content-Type: #{headers['content-type']}"
+puts "Body: #{body.first}"
+puts "Log level: INFO (not ERROR)"
+
+puts "\n=== Test 3: Rate Limited (429) with custom handler ==="
+env = {
+  'REQUEST_METHOD' => 'POST',
+  'PATH_INFO' => '/action',
+  'HTTP_ACCEPT' => 'application/json',
+  'REMOTE_ADDR' => '127.0.0.1'
+}
+
+status, headers, body = otto.call(env)
+puts "Status: #{status}"
+puts "Content-Type: #{headers['content-type']}"
+puts "Body: #{body.first}"
+puts "Log level: WARN (not ERROR)"
+puts "Custom fields: retry_after included"
+
+puts "\n=== Test 4: Successful Request ==="
+env = {
+  'REQUEST_METHOD' => 'GET',
+  'PATH_INFO' => '/resource/123',
+  'HTTP_ACCEPT' => 'application/json',
+  'REMOTE_ADDR' => '127.0.0.1'
+}
+
+status, headers, body = otto.call(env)
+puts "Status: #{status}"
+puts "Content-Type: #{headers['content-type']}"
+puts "Body: #{body.first}"
+
+puts "\n=== Benefits ==="
+puts "✓ Expected errors return proper HTTP status codes (not 500)"
+puts "✓ Logged at INFO/WARN level (not ERROR)"
+puts "✓ No backtrace spam for expected conditions"
+puts "✓ Still generates error IDs for correlation"
+puts "✓ Custom response handlers for complex error data"
+puts "✓ Content negotiation (JSON/plain text) automatic"
+
+# Cleanup
+File.delete('/tmp/otto_error_routes.txt') if File.exist?('/tmp/otto_error_routes.txt')

data/examples/logging_improvements.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating Otto's enhanced logging capabilities
+# Inspired by structured logging patterns with timing
+
+require_relative '../lib/otto'
+
+# Set up Otto with structured logging
+Otto.logger = Logger.new(STDOUT)
+Otto.debug = true
+
+# Create a simple Otto app
+otto = Otto.new do |routes|
+  routes << "GET /example App#handle_request"
+  routes << "GET /timed App#timed_operation"
+end
+
+# Example handler class demonstrating the new logging patterns
+class App
+  def self.handle_request(req, res)
+    # Example of structured logging with request context
+    Otto.structured_log(:info, "Request processed",
+      Otto::LoggingHelpers.request_context(req.env).merge(
+        user_id: req.params['user_id'],
+        cached: false,
+        response_size_bytes: 1024
+      )
+    )
+
+    res.write("Hello World")
+    res
+  end
+
+  def self.timed_operation(req, res)
+    # Example of the log_timed_operation helper
+    result = Otto::LoggingHelpers.log_timed_operation(:info, "Template rendered", req.env,
+      template: 'example_template',
+      layout: 'application',
+      partials: ['header', 'footer']
+    ) do
+      # Simulate some work
+      sleep(0.01)
+      "Rendered content"
+    end
+
+    # Alternative: Manual timing with structured_log
+    Otto.structured_log(:debug, "Cache lookup",
+      Otto::LoggingHelpers.request_context(req.env).merge(
+        cache_key: 'template:example',
+        cache_hit: true,
+        cache_ttl: 3600
+      )
+    )
+
+    res.write(result)
+    res
+  end
+end
+
+# Test the logging
+puts "\n=== Testing Enhanced Logging ==="
+puts "\n1. Standard request (uses structured_log):"
+env1 = { 'REQUEST_METHOD' => 'GET', 'PATH_INFO' => '/example', 'QUERY_STRING' => 'user_id=123' }
+otto.call(env1)
+
+puts "\n2. Timed operation (uses log_timed_operation):"
+env2 = { 'REQUEST_METHOD' => 'GET', 'PATH_INFO' => '/timed' }
+otto.call(env2)
+
+puts "\n=== Expected Output Format ==="
+puts "Standard logger (structured_log):"
+puts "I, [timestamp] INFO -- : [Otto] Request processed -- {method: \"GET\", path: \"/example\", ip: \"127.0.0.1\", user_id: \"123\", cached: false, response_size_bytes: 1024}"
+
+puts "\nStructured logging with timing (log_timed_operation):"
+puts "I, [timestamp] INFO -- : [Otto] Template rendered -- {method: \"GET\", path: \"/timed\", ip: \"127.0.0.1\", template: \"example_template\", layout: \"application\", partials: [\"header\", \"footer\"], duration: 10123}"