otto 2.9.0 → 2.10.0

data/examples/authentication_strategies/README.md

@@ -1,225 +1,66 @@
-# Otto - Authentication Strategies Example
+# Otto Authentication Strategies Example
 
-This example demonstrates Otto's flexible authentication system with multiple strategies, token validation, and role-based access control.
+This source-checkout example shows four route-level authentication strategies:
 
-## What You'll Learn
+- `authenticated` accepts `demo_token`.
+- `role:admin` accepts `admin_token`.
+- `permission:write` accepts `demo_token` or `admin_token`.
+- `api_key` accepts `demo_api_key_123`.
 
-- 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
+The strategies are registered in `app/auth.rb` before the application handles its first request. The protected routes are defined in `routes`.
 
-## Structure
+## Prerequisites
 
-- `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
+Run this example from an Otto source checkout. Its `config.ru` loads Otto from `../../lib`, rather than from an installed gem.
 
-## 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)
+You need a supported Ruby version and Bundler. `rackup` is a development dependency in the root `Gemfile`, so enable the `development` group before installing dependencies:
 
 ```sh
-cd examples/authentication_strategies
-rackup config.ru
+# From the repository root
+bundle config set with development
+bundle install
 ```
 
-### Using alternative servers
+## Run the example
 
 ```sh
-thin -R config.ru -p 9292 start
-puma config.ru -p 9292
+# From the repository root
+cd examples/authentication_strategies
+bundle exec rackup config.ru
 ```
 
-Open your browser and navigate to `http://localhost:9292`.
-
-## Testing Authentication
-
-### Web Browser (Token-based)
+The server listens on `http://127.0.0.1:9292` by default. Leave it running and use a second terminal for the checks below.
 
-Click these links or visit them directly:
+## Verify the configured credentials
 
-- **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)
+The strategies read the token from the query string or the exact `Authorization` header value. The API-key strategy reads the key from the query string or `X-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"
+curl -i "http://127.0.0.1:9292/profile?token=demo_token"
+curl -i -H 'Authorization: demo_token' http://127.0.0.1:9292/profile
+curl -i "http://127.0.0.1:9292/api/data?api_key=demo_api_key_123"
+curl -i -H 'X-API-Key: demo_api_key_123' http://127.0.0.1:9292/api/data
 ```
 
-### Testing Invalid Credentials
-
-Try accessing protected routes without valid credentials:
+Use an omitted or invalid credential to exercise the authentication-failure path:
 
 ```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>
+curl -i http://127.0.0.1:9292/profile
+curl -i "http://127.0.0.1:9292/api/data?api_key=invalid"
 ```
 
-### 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
-
-To add your own authentication:
-
-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
-   ```
-
-2. **Register it in config.ru**:
-   ```ruby
-   app.add_auth_strategy('my_strategy', MyStrategy.new)
-   ```
+### Current limitation
 
-3. **Use it in routes**:
-   ```
-   GET  /protected  Controller#method  auth=my_strategy
-   ```
+In this checkout, `app/controllers/main_controller.rb` and `app/controllers/auth_controller.rb` define class methods, while Otto instantiates route handlers with a request and response. Requests that reach those handlers therefore fail with an argument error. The commands above document the configured credential inputs, but they cannot currently verify a successful protected response until the controllers are made compatible with the handler interface.
 
-## Next Steps
+## Files to inspect
 
-- Explore [Security Features](../security_features/) for CSRF, input validation, file uploads
-- Review [Advanced Routes](../advanced_routes/) for response types and logic classes
+- `config.ru` creates the Otto application, enables CSRF and request validation, and registers the strategies.
+- `app/auth.rb` contains the demo credentials and strategy callbacks.
+- `routes` associates each protected route with its `auth=` requirement.
+- `app/controllers/auth_controller.rb` supplies the protected responses.
 
-## Further Reading
+## Next steps
 
-- [CLAUDE.md](../../CLAUDE.md#authentication-architecture) - Detailed auth documentation
+- See the [security features example](../security_features/README.md) for CSRF and request-validation configuration.
+- Read the [authentication guide](../../docs/guides/authentication.md) for application authentication design.

data/examples/basic/README.md

@@ -7,67 +7,52 @@ This example demonstrates a basic Otto application with a single route that acce
 - 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
+- Running an Otto application with Rackup
+- Simple form handling and validation
 
-## How to Run
+## Run it
 
-### Using rackup (recommended)
+### Prerequisites
 
-```sh
-cd examples/basic
-rackup config.ru -p 10770
-```
-
-### Using thin
+Run this example from an Otto source checkout with Ruby 3.2 through 4.0 and Bundler. `rackup` is a development dependency in the root `Gemfile`, so enable that optional group before installing the bundle.
 
 ```sh
+git clone https://github.com/delano/otto.git
+cd otto
+bundle config set with development
+bundle install
 cd examples/basic
-thin -e dev -R config.ru -p 10770 start
+bundle exec rackup config.ru -p 10770
 ```
 
-### Using puma
+The server listens on `http://localhost:10770`.
 
-```sh
-cd examples/basic
-puma config.ru -p 10770
-```
+> **Current limitation:** The checked-in app starts, but `GET /` currently returns `500` because `App#index` calls the undefined `otto_form_wrapper` helper. Until that source issue is fixed, the browser workflow below cannot be completed.
 
-Open your browser and navigate to `http://localhost:10770`.
+### Verify after fixing the source issue
 
-## Expected Output
+In another terminal, confirm that the home page responds with HTML:
 
-```
-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
-
-[GET request to /]
-GET /  200 OK
-
-[Submitting feedback form]
-POST /feedback  302 Found
-Location: http://localhost:10770/
+```sh
+curl -i http://localhost:10770/
 ```
 
-Then visit `http://localhost:10770` and submit feedback to see it in action.
+Expect `HTTP/1.1 200` and an HTML page containing `Otto Framework`. Open the same URL in a browser, enter a message, and submit the form. The form posts to `/` (not `/feedback`) and displays either the submitted message or the validation message for an empty submission.
 
 ## File Structure
 
 * `README.md`: This file.
 * `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
+  - `receive_feedback`: Handles form submissions and renders the result
 * `config.ru`: The Rack configuration file that loads Otto and the application.
-* `routes`: Defines the URL routes mapping to methods in the `App` class.
+- `routes`: Maps `GET /` to `App#index` and `POST /` to `App#receive_feedback`.
 
-## Trying It Out
+## Trying it out after resolving the limitation
 
-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
+1. **View the home page**: Open `http://localhost:10770` in your browser.
+2. **Submit feedback**: Enter text in the feedback form and click **Send Feedback**.
+3. **Check the result**: The response shows the submitted message and a link back to the home page.
 
 ## Next Steps
 
@@ -77,4 +62,4 @@ Then visit `http://localhost:10770` and submit feedback to see it in action.
 
 ## Further Reading
 
-- [CLAUDE.md](../../CLAUDE.md) - Developer guidance and patterns
+- [Project README](../../README.md) - Installation and framework overview

data/examples/basic/config.ru

@@ -20,7 +20,6 @@ if Otto.env?(:dev)
     use Rack::CommonLogger
     use Rack::Reloader, 0
     app.option[:public] = public_path
-    app.add_static_path '/favicon.ico'
     run app
   end
 

data/examples/caddy_tls_demo/README.md

@@ -19,9 +19,15 @@ config-only on Caddy's side.
 
 ## Run it
 
+This is a source-checkout example: its Rackup file loads Otto from `../../lib`.
+From the repository root, install the optional development dependencies (which
+include `rackup`) and start the app:
+
 ```sh
+bundle config set with development
+bundle install
 cd examples/caddy_tls_demo
-rackup config.ru        # serves on http://localhost:9292
+bundle exec rackup config.ru        # serves on http://localhost:9292
 ```
 
 ## Try it
@@ -97,4 +103,4 @@ your real data over whatever channel your app already trusts. Two more defenses:
   respond @tls_permission 404
   ```
 
-See [`docs/reverse-proxy-network-services.md`](../../docs/reverse-proxy-network-services.md).
+See [ADR-003: Caddy TLS route-based integration](../../docs/adr/adr-003-caddy-tls-route-based-integration.md).

data/examples/lambda_handlers/README.md

@@ -89,11 +89,20 @@ anything.
 
 ## How to Run
 
+Run this example from an Otto source checkout. It requires Ruby 3.2 through
+4.0, Bundler, and the development dependencies: `rackup` is a development
+dependency in the root `Gemfile` and is not installed with the released `otto`
+gem.
+
 ```sh
+cd /path/to/otto
+bundle config set with development
+bundle install
 cd examples/lambda_handlers
-rackup config.ru -p 10780
+bundle exec rackup config.ru -p 10780
 ```
 
+
 Then, from another terminal:
 
 ```sh
@@ -125,4 +134,4 @@ curl -X POST --data 'hello' localhost:10780/webhook
 
 ## Further Reading
 
-- [docs/ADVANCED_ROUTES.txt](../../docs/ADVANCED_ROUTES.txt)
+- [Route syntax reference](../../docs/reference/route-syntax.md)