otto 1.6.0 → 2.0.0.pre2

data/examples/advanced_routes/app/logic/v2/logic/processor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module V2
+  module Logic
+    class Processor
+      attr_reader :context, :params, :locale
+
+      def initialize(context, params, locale)
+        @context = context
+        @params = params
+        @locale = locale
+      end
+
+      def process
+        {
+          v2_processor: 'Complete',
+          csrf_exempt: true,
+          processing_time: 0.05,
+        }
+      end
+
+      def response_data
+        { v2_processor: process }
+      end
+    end
+  end
+end

data/examples/advanced_routes/app.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Application Loader
+
+# Controllers
+require_relative 'app/controllers/routes_app'
+require_relative 'app/controllers/handlers/async'
+require_relative 'app/controllers/handlers/dynamic'
+require_relative 'app/controllers/handlers/static'
+require_relative 'app/controllers/modules/auth'
+require_relative 'app/controllers/modules/transformer'
+require_relative 'app/controllers/modules/validator'
+require_relative 'app/controllers/v2/admin'
+require_relative 'app/controllers/v2/config'
+require_relative 'app/controllers/v2/settings'
+
+# Logic Classes
+require_relative 'app/logic/admin/logic/manager'
+require_relative 'app/logic/admin/panel'
+require_relative 'app/logic/analytics_processor'
+require_relative 'app/logic/complex/business/handler'
+require_relative 'app/logic/data_logic'
+require_relative 'app/logic/data_processor'
+require_relative 'app/logic/input_validator'
+require_relative 'app/logic/nested/feature/logic'
+require_relative 'app/logic/reports_generator'
+require_relative 'app/logic/simple_logic'
+require_relative 'app/logic/system/config/manager'
+require_relative 'app/logic/test_logic'
+require_relative 'app/logic/transform_logic'
+require_relative 'app/logic/upload_logic'
+require_relative 'app/logic/v2/logic/dashboard'
+require_relative 'app/logic/v2/logic/processor'

data/examples/advanced_routes/config.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative '../../lib/otto'
+require_relative 'app'
+
+# Simple Otto configuration demonstrating advanced routes syntax
+otto = Otto.new('routes')
+
+# Enable basic security features to demonstrate CSRF functionality
+otto.enable_csrf_protection!
+
+# Set error handlers
+otto.not_found = lambda do |_env|
+  RoutesApp.not_found
+end
+
+otto.server_error = lambda do |_env, _error|
+  RoutesApp.server_error
+end
+
+# Return the configured app. This allows runner scripts to use the same instance.
+otto

data/examples/advanced_routes/config.ru

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Load the app from our shared config file.
+# This returns a configured Otto instance.
+app = require_relative 'config'
+
+run app

data/examples/advanced_routes/puma.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'puma'
+
+# The shared config file returns the configured Otto app
+otto_app = require_relative 'config'
+
+# Configure Puma server
+Puma::Server.new(otto_app).tap do |server|
+  server.add_tcp_listener '127.0.0.1', 9292
+
+  puts "Otto Advanced Routes Example running on http://localhost:9292"
+  puts "Press Ctrl+C to stop"
+
+  # Handle Ctrl+C gracefully
+  trap('INT') { server.stop }
+
+  server.run
+end

data/examples/advanced_routes/routes

@@ -0,0 +1,167 @@
+# Advanced Routes Syntax - Otto v1.5.0+ Features
+# This file demonstrates the advanced routing syntax without complex authentication
+
+# ========================================
+# BASIC ROUTES (Original Otto Syntax)
+# ========================================
+
+GET   /                         RoutesApp#index
+POST  /feedback                 RoutesApp#receive_feedback
+
+# ========================================
+# RESPONSE TYPE ROUTES
+# ========================================
+
+# JSON response routes
+GET   /api/users                RoutesApp#list_users response=json
+POST  /api/users                RoutesApp#create_user response=json
+GET   /api/health               RoutesApp#health_check response=json
+PUT   /api/users/:id            RoutesApp#update_user response=json
+DELETE /api/users/:id           RoutesApp#delete_user response=json
+
+# View/HTML response routes
+GET   /dashboard                RoutesApp#dashboard response=view
+GET   /reports                  RoutesApp#reports response=view
+GET   /admin                    RoutesApp#admin_panel response=view
+
+# Redirect response routes
+GET   /login                    RoutesApp#login_redirect response=redirect
+GET   /logout                   RoutesApp#logout_redirect response=redirect
+GET   /home                     RoutesApp#home_redirect response=redirect
+
+# Auto response type (content negotiation)
+GET   /data                     RoutesApp#flexible_data response=auto
+GET   /content                  RoutesApp#flexible_content response=auto
+
+# ========================================
+# CSRF PROTECTION ROUTES
+# ========================================
+
+# CSRF exempt routes (useful for APIs and webhooks)
+POST  /api/webhook              RoutesApp#webhook_handler csrf=exempt
+PUT   /api/external             RoutesApp#external_update csrf=exempt
+DELETE /api/cleanup             RoutesApp#cleanup_data csrf=exempt
+PATCH /api/sync                 RoutesApp#sync_data csrf=exempt
+
+# Standard CSRF protected routes (default behavior)
+POST  /settings                 RoutesApp#update_settings
+PUT   /password                 RoutesApp#change_password
+DELETE /profile                 RoutesApp#delete_profile
+
+# ========================================
+# MULTIPLE PARAMETER COMBINATIONS
+# ========================================
+
+# API routes with response type and CSRF exemption
+GET   /api/v1/data              RoutesApp#api_data response=json
+POST  /api/v1/submit            RoutesApp#api_submit response=json csrf=exempt
+PUT   /api/v1/update            RoutesApp#api_update response=json csrf=exempt
+
+# View routes with multiple parameters
+GET   /admin/dashboard          RoutesApp#admin_dashboard response=view
+POST  /admin/settings           RoutesApp#admin_settings response=view
+
+# Mixed content routes
+GET   /mixed/endpoint           RoutesApp#mixed_content response=auto csrf=exempt
+
+# ========================================
+# LOGIC CLASS ROUTES (New in v1.5.0+)
+# ========================================
+
+# Simple Logic class (no . or # in target)
+GET   /logic/simple             SimpleLogic
+POST  /logic/process            DataProcessor
+PUT   /logic/validate           InputValidator
+
+# Namespaced Logic classes
+GET   /logic/admin              Admin::Panel
+GET   /logic/reports            Reports::Generator
+POST  /logic/analytics          Analytics::Processor
+
+# Logic classes with parameters
+GET   /logic/data               DataLogic response=json
+POST  /logic/upload             UploadLogic response=json csrf=exempt
+PUT   /logic/transform          TransformLogic response=json
+
+# Complex namespaced Logic routes
+GET   /logic/v2/dashboard       V2::Logic::Dashboard response=view
+POST  /logic/v2/process         V2::Logic::Processor response=json csrf=exempt
+GET   /logic/admin/manager      Admin::Logic::Manager response=json
+
+# Deeply nested Logic classes
+GET   /logic/nested/feature     Nested::Feature::Logic
+POST  /logic/complex/handler    Complex::Business::Handler response=json
+PUT   /logic/system/config      System::Config::Manager response=json csrf=exempt
+
+# ========================================
+# NAMESPACED CLASS ROUTES
+# ========================================
+
+# Class method routes with namespaces
+GET   /v2/admin                 V2::Admin.show response=view
+POST  /v2/config                V2::Config.update response=json
+PUT   /v2/settings              V2::Settings.modify response=json csrf=exempt
+
+# Instance method routes with namespaces
+GET   /modules/auth             Modules::Auth#process
+POST  /modules/validator        Modules::Validator#validate response=json
+PUT   /modules/transformer      Modules::Transformer#transform response=json csrf=exempt
+
+# Mixed class and instance methods
+GET   /handlers/static          Handlers::Static.serve
+POST  /handlers/dynamic         Handlers::Dynamic#process response=json
+PUT   /handlers/async           Handlers::Async#execute response=json csrf=exempt
+
+# ========================================
+# CUSTOM PARAMETERS
+# ========================================
+
+# Routes with custom configuration parameters
+GET   /config/env               RoutesApp#show_config env=production
+GET   /config/debug             RoutesApp#debug_info env=development debug=true
+POST  /config/update            RoutesApp#update_config env=production response=json
+
+# Routes with multiple custom parameters
+GET   /feature/flags            RoutesApp#feature_flags feature=advanced mode=enabled
+POST  /feature/toggle           RoutesApp#toggle_feature feature=beta mode=test response=json csrf=exempt
+
+# ========================================
+# PARAMETER VALUE VARIATIONS
+# ========================================
+
+# Parameters with special values
+GET   /api/v1                   RoutesApp#api_v1 version=1.0 response=json
+GET   /api/v2                   RoutesApp#api_v2 version=2.0 response=json
+POST  /api/legacy               RoutesApp#api_legacy version=legacy response=json csrf=exempt
+
+# Parameters with equals in values (edge case)
+GET   /query/complex            RoutesApp#complex_query filter=key=value response=json
+POST  /config/connection        RoutesApp#config_db connection=host=localhost csrf=exempt
+
+# ========================================
+# ERROR HANDLERS
+# ========================================
+
+GET   /404                      RoutesApp#not_found response=view
+GET   /500                      RoutesApp#server_error response=view
+
+# ========================================
+# TESTING ROUTES
+# ========================================
+
+# Routes for testing different parameter combinations
+GET   /test/json                RoutesApp#test_json response=json
+GET   /test/view                RoutesApp#test_view response=view
+GET   /test/redirect            RoutesApp#test_redirect response=redirect
+GET   /test/auto                RoutesApp#test_auto response=auto
+
+POST  /test/csrf                RoutesApp#test_csrf
+POST  /test/no-csrf             RoutesApp#test_no_csrf csrf=exempt
+
+GET   /test/logic               TestLogic
+POST  /test/logic-json          TestLogic response=json
+PUT   /test/logic-exempt        TestLogic response=json csrf=exempt
+
+# Complex test routes
+GET   /test/complex             TestLogic response=auto
+POST  /test/everything          RoutesApp#test_everything response=json csrf=exempt custom=value

data/examples/advanced_routes/run.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'webrick'
+
+# The shared config file returns the configured Otto app
+otto_app = require_relative 'config'
+
+# Create a simple WEBrick server
+server = WEBrick::HTTPServer.new(
+  Port: 9292,
+  Logger: WEBrick::Log.new($stdout, WEBrick::Log::INFO)
+)
+
+# Mount the Otto app
+server.mount '/', WEBrick::HTTPServlet::ProcHandler.new(proc { |req, res|
+  env = req.meta_vars.merge({
+    'REQUEST_METHOD' => req.request_method,
+    'PATH_INFO' => req.path_info,
+    'QUERY_STRING' => req.query_string || '',
+    'rack.input' => StringIO.new(req.body || ''),
+    'CONTENT_TYPE' => req.content_type,
+    'CONTENT_LENGTH' => req.content_length&.to_s
+  })
+
+  status, headers, body = otto_app.call(env)
+
+  res.status = status
+  headers.each { |k, v| res[k] = v }
+  body.each { |chunk| res.body << chunk }
+})
+
+# Handle Ctrl+C gracefully
+trap('INT') { server.shutdown }
+
+puts "Otto Advanced Routes Example running on http://localhost:9292"
+puts "Press Ctrl+C to stop"
+
+server.start

data/examples/advanced_routes/test.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The shared config file returns the configured Otto app
+otto_app = require_relative 'config'
+
+# Simple test runner to demonstrate routes without a server
+def test_route(method, path, params = {})
+  query_string = params.map { |k, v| "#{k}=#{v}" }.join('&')
+
+  env = {
+    'REQUEST_METHOD' => method.to_s.upcase,
+    'PATH_INFO' => path,
+    'QUERY_STRING' => query_string,
+    'rack.input' => StringIO.new(''),
+    'HTTP_ACCEPT' => 'application/json',
+  }
+
+  status, headers, body = otto_app.call(env)
+
+  puts "#{method.to_s.upcase} #{path}#{query_string.empty? ? '' : '?' + query_string}"
+  puts "Status: #{status}"
+  puts "Content-Type: #{headers['content-type'] || headers['Content-Type']}"
+  puts "Body: #{body.join}"
+  puts "---"
+end
+
+puts "Otto Advanced Routes Syntax Test"
+puts "================================"
+
+# Test basic routes
+test_route(:get, '/')
+test_route(:post, '/feedback')
+
+# Test JSON routes
+test_route(:get, '/api/users')
+test_route(:get, '/api/health')
+
+# Test Logic classes
+test_route(:get, '/logic/simple')
+test_route(:post, '/logic/process')
+
+# Test namespaced Logic classes
+test_route(:get, '/logic/admin')
+test_route(:get, '/logic/v2/dashboard')
+
+# Test CSRF exempt routes
+test_route(:post, '/api/webhook')
+test_route(:put, '/api/external')
+
+# Test custom parameters
+test_route(:get, '/config/env')
+test_route(:get, '/api/v1')
+
+# Test complex routes
+test_route(:post, '/test/everything')
+
+puts "All tests completed!"

data/examples/authentication_strategies/README.md

@@ -0,0 +1,32 @@
+# Otto - Authentication Strategies Example
+
+This example demonstrates how to use Otto's powerful authentication features.
+
+## 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.
+
+## Running the Demo
+
+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/authentication_strategies/config.ru
+    ```
+
+3.  Open your browser and navigate to `http://localhost:9292`.
+
+## Trying the Authentication Strategies
+
+You can test the different authentication strategies by providing a `token` or `api_key` parameter in the URL.
+
+*   **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)
+
+If you try to access a protected route without the correct token, you'll get an authentication error.

data/examples/authentication_strategies/app/auth.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Authentication result data class to contain the session, user and anything
+# else we want to make available to the route handlers/controllers/logic classes.
+AuthResultData = Data.define(:session, :user) do
+  def initialize(session: {}, user: {})
+    super(session: session, user: user)
+  end
+
+  # Provide user_context method for compatibility with existing AuthResult
+  def user_context
+    { session: session, user: user }
+  end
+end
+
+module AuthenticationSetup
+  def self.configure(otto)
+    # Simple auth strategy that checks for a token parameter or header
+    otto.add_auth_strategy('authenticated', lambda do |req|
+      token = req.params['token'] || req.get_header('HTTP_AUTHORIZATION')
+      if token == 'demo_token'
+        AuthResultData.new(
+          session: { session_id: 'demo_session_123', user_id: 1 },
+          user: { name: 'Demo User', role: 'user', permissions: %w[read write] }
+        )
+      end
+    end)
+
+    # Role-based auth strategy
+    otto.add_auth_strategy('role:admin', lambda do |req|
+      token = req.params['token'] || req.get_header('HTTP_AUTHORIZATION')
+      if token == 'admin_token'
+        AuthResultData.new(
+          session: { session_id: 'admin_session_456', user_id: 2 },
+          user: { name: 'Admin User', role: 'admin', permissions: %w[read write admin delete] }
+        )
+      end
+    end)
+
+    # Permission-based auth strategy
+    otto.add_auth_strategy('permission:write', lambda do |req|
+      token = req.params['token'] || req.get_header('HTTP_AUTHORIZATION')
+      case token
+      when 'demo_token'
+        AuthResultData.new(
+          session: { session_id: 'demo_session_123', user_id: 1 },
+          user: { name: 'Demo User', role: 'user', permissions: %w[read write] }
+        )
+      when 'admin_token'
+        AuthResultData.new(
+          session: { session_id: 'admin_session_456', user_id: 2 },
+          user: { name: 'Admin User', role: 'admin', permissions: %w[read write admin delete] }
+        )
+      end
+    end)
+
+    # API key auth strategy
+    otto.add_auth_strategy('api_key', lambda do |req|
+      api_key = req.params['api_key'] || req.get_header('HTTP_X_API_KEY')
+      if api_key == 'demo_api_key_123'
+        AuthResultData.new(
+          session: { api_session: 'api_session_abc' },
+          user: { name: 'API Client', type: 'api', permissions: ['api_access'] }
+        )
+      end
+    end)
+  end
+end

data/examples/authentication_strategies/app/controllers/auth_controller.rb

@@ -0,0 +1,29 @@
+require 'json'
+
+class AuthController
+  def self.login_form
+    [200, { 'content-type' => 'text/html' }, ['<h1>Login</h1><p>Use ?token=demo_token, ?token=admin_token, or ?api_key=demo_api_key_123</p>']]
+  end
+
+  def self.login
+    # In a real app, you'd handle login logic here.
+    # For this demo, we redirect to the profile.
+    [302, { 'location' => '/profile' }, ['']]
+  end
+
+  def self.show_profile
+    [200, { 'content-type' => 'text/html' }, ['<h1>User Profile</h1><p>You are authenticated.</p>']]
+  end
+
+  def self.admin_panel
+    [200, { 'content-type' => 'text/html' }, ['<h1>Admin Panel</h1><p>Role: admin required</p>']]
+  end
+
+  def self.edit_content
+    [200, { 'content-type' => 'text/html' }, ['<h1>Edit Content</h1><p>Permission: write required</p>']]
+  end
+
+  def self.api_data
+    [200, { 'content-type' => 'application/json' }, ['{"data": "This is some secret API data."}']]
+  end
+end

data/examples/authentication_strategies/app/controllers/main_controller.rb

@@ -0,0 +1,28 @@
+require 'json'
+require 'time'
+
+class MainController
+  def self.index
+    [200, { 'content-type' => 'text/html' }, ['<h1>Authentication Strategies Example</h1>']]
+  end
+
+  def self.receive_feedback
+    [200, { 'content-type' => 'text/plain' }, ['Feedback received']]
+  end
+
+  def self.dashboard
+    [200, { 'content-type' => 'text/html' }, ['<h1>Dashboard</h1><p>Welcome to your dashboard!</p>']]
+  end
+
+  def self.reports
+    [200, { 'content-type' => 'text/html' }, ['<h1>Reports</h1><p>Admin-only reports section</p>']]
+  end
+
+  def self.not_found
+    [404, { 'content-type' => 'text/html' }, ['<h1>404 - Page Not Found</h1><p>Advanced routes example</p>']]
+  end
+
+  def self.server_error
+    [500, { 'content-type' => 'text/html' }, ['<h1>500 - Server Error</h1><p>Something went wrong</p>']]
+  end
+end

data/examples/authentication_strategies/config.ru

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'rack'
+require_relative '../../lib/otto'
+require_relative 'app/auth'
+require_relative 'app/controllers/main_controller'
+require_relative 'app/controllers/auth_controller'
+
+# Configure Otto with advanced features
+otto = Otto.new('routes')
+
+# Enable security features to demonstrate advanced route parameters
+otto.enable_csrf_protection!
+otto.enable_request_validation!
+otto.enable_authentication!
+
+# Load and configure authentication strategies
+AuthenticationSetup.configure(otto)
+
+# Set error handlers
+otto.not_found = ->(_env) { MainController.not_found }
+otto.server_error = ->(_env, _error) { MainController.server_error }
+
+run otto

data/examples/authentication_strategies/routes

@@ -0,0 +1,37 @@
+# Authentication Strategies Example
+
+# ========================================
+# PUBLIC ROUTES
+# ========================================
+
+GET   /                         MainController#index
+GET   /login                    AuthController#login_form
+POST  /login                    AuthController#login
+
+# ========================================
+# AUTHENTICATED ROUTES
+# ========================================
+
+# Requires a user to be logged in.
+# Try: /profile?token=demo_token
+GET   /profile                  AuthController#show_profile auth=authenticated
+
+# Requires the 'admin' role.
+# Try: /admin?token=admin_token
+GET   /admin                    AuthController#admin_panel auth=role:admin
+
+# Requires the 'write' permission.
+# A user with the 'user' role has this.
+# Try: /edit?token=demo_token
+GET   /edit                     AuthController#edit_content auth=permission:write
+
+# A route protected by an API key
+# Try: /api/data?api_key=demo_api_key_123
+GET   /api/data                 AuthController#api_data auth=api_key response=json
+
+# ========================================
+# ERROR HANDLERS
+# ========================================
+
+GET   /404                      MainController#not_found response=view
+GET   /500                      MainController#server_error response=view

data/examples/basic/README.md

@@ -0,0 +1,29 @@
+# Otto - Basic Example
+
+This example demonstrates a basic Otto application with a single route that accepts both GET and POST requests.
+
+## How to Run
+
+1.  Make sure you have `bundler` and `thin` installed:
+```sh
+  gem install bundler thin
+```
+
+2.  Install the dependencies from the root of the project:
+```sh
+  bundle install
+```
+
+3.  Start the server from this directory (`examples/basic`):
+```sh
+  thin -e dev -R config.ru -p 10770 start
+```
+
+4.  Open your browser and navigate to `http://localhost:10770`.
+
+## 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.