otto 1.5.0 → 2.0.0.pre1

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.

data/examples/basic/app.rb

@@ -1,7 +1,8 @@
-# examples/basic/app.rb (Streamlined with Design System)
+# examples/basic/app.rb
 
 require_relative '../../lib/otto/design_system'
 
+# Basic example application demonstrating Otto framework features.
 class App
   include Otto::DesignSystem
 
@@ -37,42 +38,13 @@ class App
     message = req.params['msg']&.strip
 
     content = if message.nil? || message.empty?
-      otto_alert('error', 'Empty Message', 'Please enter a message before submitting.')
-    else
-      otto_alert('success', 'Feedback Received', 'Thanks for your message!') +
-        otto_card('Your Message') { otto_code_block(message, 'text') }
-    end
+                otto_alert('error', 'Empty Message', 'Please enter a message before submitting.')
+              else
+                otto_alert('success', 'Feedback Received', 'Thanks for your message!') +
+                  otto_card('Your Message') { otto_code_block(message, 'text') }
+              end
 
     content += "<p>#{otto_link('← Back', '/')}</p>"
     res.body = otto_page(content, 'Feedback')
   end
-
-  def redirect
-    res.redirect '/robots.txt'
-  end
-
-  def robots_text
-    res.headers['content-type'] = 'text/plain'
-    res.body                    = ['User-agent: *', 'Disallow: /private'].join($/)
-  end
-
-  def display_product
-    res.headers['content-type'] = 'application/json; charset=utf-8'
-    prodid                      = req.params[:prodid]
-    res.body                    = format('{"product":%s,"msg":"Hint: try another value"}', prodid)
-  end
-
-  def not_found
-    res.status = 404
-    content    = otto_alert('error', 'Not Found', 'The requested page could not be found.')
-    content   += "<p>#{otto_link('← Home', '/')}</p>"
-    res.body   = otto_page(content, '404')
-  end
-
-  def server_error
-    res.status = 500
-    content    = otto_alert('error', 'Server Error', 'An internal server error occurred.')
-    content   += "<p>#{otto_link('← Home', '/')}</p>"
-    res.body   = otto_page(content, '500')
-  end
 end

data/examples/basic/routes

@@ -9,12 +9,3 @@
 
 GET   /                         App#index
 POST  /                         App#receive_feedback
-GET   /redirect                 App#redirect
-GET   /robots.txt               App#robots_text
-
-GET   /bogus                    App#no_such_method
-
-# You can also define these handlers when no
-# route can be found or there's a server error. (optional)
-GET   /404                      App#not_found
-GET   /500                      App#server_error

data/examples/mcp_demo/README.md

@@ -0,0 +1,87 @@
+# Otto MCP Demo
+
+This example demonstrates Otto's Model-Controller-Protocol (MCP) feature. MCP provides a standardized JSON-RPC 2.0 endpoint (`/_mcp`) that allows you to expose application resources and tools securely.
+
+This is useful for building CLIs, admin interfaces, or allowing other services to interact with your application programmatically.
+
+## Features Demonstrated
+
+*   **MCP Endpoint:** A single `POST /_mcp` endpoint for all API interactions.
+*   **Authentication:** Requests to the MCP endpoint are protected by bearer token authentication.
+*   **Rate Limiting:** The endpoint has its own rate limiting to prevent abuse.
+*   **Resources:** Read-only data exposed via `MCP` routes (e.g., listing users).
+*   **Tools:** Actions or operations exposed via `TOOL` routes (e.g., creating a user).
+
+## 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/mcp_demo`):
+    ```sh
+    thin -R config.ru -p 9292 start
+    ```
+    *Note: This demo uses port 9292 as is conventional for Rack apps.*
+
+4.  Open your browser and navigate to `http://localhost:9292` to see the welcome page.
+
+## Interacting with the MCP Endpoint
+
+All interactions happen via `POST` requests to `http://localhost:9292/_mcp`. You must provide an `Authorization: Bearer <token>` header and a `Content-Type: application/json` header.
+
+Valid tokens are `demo-token-123` and `another-token-456`.
+
+### MCP: Initialize
+
+The `initialize` method is a built-in MCP method that returns information about the available resources and tools.
+
+```sh
+curl -X POST http://localhost:9292/_mcp \
+     -H 'Authorization: Bearer demo-token-123' \
+     -H 'Content-Type: application/json' \
+     -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}'
+```
+
+### Resource: List Users
+
+This calls the `UserAPI.mcp_list_users` method defined as an `MCP` route. The method name for the JSON-RPC call is derived from the route path (`/users` -> `users/list`).
+
+```sh
+curl -X POST http://localhost:9292/_mcp \
+     -H 'Authorization: Bearer demo-token-123' \
+     -H 'Content-Type: application/json' \
+     -d '{"jsonrpc":"2.0","method":"users/list","id":2}'
+```
+
+### Tool: Create User
+
+This calls the `UserAPI.mcp_create_user` method defined as a `TOOL` route. The method name is derived from the route path (`/create_user` -> `create_user`).
+
+```sh
+curl -X POST http://localhost:9292/_mcp \
+     -H 'Authorization: Bearer demo-token-123' \
+     -H 'Content-Type: application/json' \
+     -d '{
+          "jsonrpc": "2.0",
+          "method": "create_user",
+          "id": 3,
+          "params": {
+            "name": "Charlie",
+            "email": "charlie@example.com"
+          }
+        }'
+```
+
+## File Structure
+
+*   `README.md`: This file.
+*   `app.rb`: Contains the application logic, including the `DemoApp` for web pages and the `UserAPI` for MCP handlers.
+*   `config.ru`: The Rack configuration file. It loads the Otto framework, enables MCP, and runs the application.
+*   `routes`: Defines the standard web routes as well as the `MCP` and `TOOL` routes for the MCP endpoint.

data/examples/mcp_demo/app.rb

@@ -0,0 +1,51 @@
+# examples/mcp_demo/app.rb
+require 'json'
+require 'time'
+
+# DemoApp provides basic HTML pages for the demo.
+class DemoApp
+  def self.index(_req, res)
+    res.headers['content-type'] = 'text/html; charset=utf-8'
+    res.body = <<~HTML
+      <h1>Otto MCP Demo</h1>
+      <p>This example demonstrates Otto's Model-Controller-Protocol (MCP) feature, which provides a JSON-RPC 2.0 endpoint for interacting with your application.</p>
+      <p>The MCP endpoint is available at: <code>POST /_mcp</code></p>
+      <p>See the <code>README.md</code> file for detailed `curl` commands to test the API.</p>
+    HTML
+  end
+
+  def self.health(_req, res)
+    res.headers['content-type'] = 'text/plain'
+    res.body = 'OK'
+  end
+end
+
+# UserAPI provides handlers for the MCP tool and resource routes.
+class UserAPI
+  # MCP Resource: mcp_list_users
+  # Accessible via JSON-RPC method "users/list"
+  def self.mcp_list_users
+    {
+      users: [
+        { id: 1, name: 'Alice', email: 'alice@example.com' },
+        { id: 2, name: 'Bob', email: 'bob@example.com' },
+      ],
+    }.to_json
+  end
+
+  # MCP Tool: mcp_create_user
+  # Accessible via JSON-RPC method "create_user"
+  def self.mcp_create_user(arguments, _env)
+    name = arguments['name'] || 'Anonymous'
+    email = arguments['email'] || "#{name.downcase}@example.com"
+
+    new_user = {
+      id: rand(1000..9999),
+      name: name,
+      email: email,
+      created_at: Time.now.iso8601,
+    }
+
+    "Created user: #{new_user.to_json}"
+  end
+end

data/examples/mcp_demo/config.ru

@@ -0,0 +1,17 @@
+# examples/mcp_demo/config.ru
+
+require_relative '../../lib/otto'
+require_relative 'app'
+
+# Initialize Otto with MCP support
+app = Otto.new('routes', {
+  mcp_enabled: true,
+  auth_tokens: ['demo-token-123', 'another-token-456'],
+  requests_per_minute: 60, # Rate limiting for the MCP endpoint
+  tools_per_minute: 20,
+})
+
+# The `mcp_enabled: true` flag automatically sets up the /_mcp endpoint.
+# The routes file maps MCP and TOOL methods to classes.
+
+run app

data/examples/mcp_demo/routes

@@ -0,0 +1,9 @@
+# Basic HTTP routes
+GET     /           DemoApp.index
+GET     /health     DemoApp.health
+
+# MCP Resources - provide read-only data
+MCP     /users       UserAPI.mcp_list_users
+
+# MCP Tools - provide actions/operations
+TOOL    /create_user UserAPI.mcp_create_user

data/examples/security_features/README.md

@@ -0,0 +1,46 @@
+# Otto Security Features Example
+
+This example application demonstrates the built-in security features of the Otto framework. It is configured to be secure by default and provides a showcase of best practices.
+
+## Security Features Demonstrated
+
+*   **CSRF Protection:** All POST forms are protected with a CSRF token to prevent cross-site request forgery attacks.
+*   **Input Validation:** All user-submitted data is validated on the server-side for length and content, preventing common injection attacks.
+*   **XSS Prevention:** All output is properly escaped to prevent cross-site scripting (XSS). You can test this by submitting `<script>alert('XSS')</script>` in any form.
+*   **Secure File Uploads:** File uploads are validated, and filenames are sanitized to prevent directory traversal and other file-based attacks.
+*   **Security Headers:** The application sends important security headers like `Content-Security-Policy`, `Strict-Transport-Security`, and `X-Frame-Options`.
+*   **Request Limiting:** The application is configured to limit the maximum request size, parameter depth, and number of parameter keys to prevent denial-of-service attacks.
+*   **Trusted Proxies:** The configuration includes a list of trusted proxy servers, ensuring that `X-Forwarded-*` headers are handled correctly and securely.
+
+## 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/security_features`):
+    ```sh
+    thin -e dev -R config.ru -p 10770 start
+    ```
+
+4.  Open your browser and navigate to `http://localhost:10770`.
+
+## What to Test
+
+*   **XSS Protection:** Try entering `<script>alert("XSS")</script>` into any of the form fields. You will see that the input is safely displayed as text instead of being executed as a script.
+*   **Input Validation:** Try submitting a very long message in the feedback form to see the length validation in action.
+*   **File Uploads:** Try uploading different types of files. The application will show you how it sanitizes the filename.
+*   **Security Headers:** Open your browser's developer tools and inspect the network requests. You will see the security headers in the response. You can also visit the `/headers` path to see a JSON representation of the request headers your browser is sending.
+
+## File Structure
+
+*   `README.md`: This file.
+*   `app.rb`: The main application logic, demonstrating how to handle forms, file uploads, and user input in a secure way.
+*   `config.ru`: The Rack configuration file. This is where the security features are enabled and configured for the Otto application.
+*   `routes`: Defines the URL routes and maps them to methods in the `SecureApp` class.