otto 2.0.0.pre3 → 2.0.0.pre8

data/Gemfile

@@ -14,6 +14,7 @@ gem 'rackup'
 group :test do
   gem 'rack-test'
   gem 'rspec', '~> 3.13'
+  gem 'user_agent_parser', '~> 2.18' # Validate anonymized UAs preserve semantic info
 end
 
 # bundle config set with 'optional'
@@ -21,17 +22,18 @@ group :development, :test, optional: true do
   # Keep gems that need to be in both environments
   gem 'json_schemer'
   gem 'rack-attack'
+  gem 'reek', '~> 6.5'
 end
 
 group :development do
   gem 'benchmark'
   gem 'debug'
-  gem 'rubocop', '~> 1.81.1', require: false
+  gem 'rubocop', '~> 1.81.7', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'ruby-lsp', require: false
   gem 'stackprof', require: false
   gem 'syntax_tree', require: false
-  gem 'tryouts', '~> 3.6.1', require: false
+  gem 'tryouts', '~> 3.7.1', require: false
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre3)
+    otto (2.0.0.pre8)
       concurrent-ruby (~> 1.3, < 2.0)
       facets (~> 3.1)
       ipaddr (~> 1, < 2.0)
@@ -9,13 +9,13 @@ PATH
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
       rack-parser (~> 0.7)
-      rexml (>= 3.3.6)
+      rexml (~> 3.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    benchmark (0.4.1)
+    benchmark (0.5.0)
     bigdecimal (3.2.3)
     concurrent-ruby (1.3.5)
     crass (1.0.6)
@@ -24,6 +24,35 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
     erb (5.1.1)
     facets (3.1.0)
     hana (1.3.7)
@@ -33,7 +62,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.1)
+    json (2.15.2)
     json_schemer (2.4.0)
       bigdecimal
       hana (~> 1.3)
@@ -63,7 +92,7 @@ GEM
     nokogiri (1.18.10-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
@@ -72,13 +101,13 @@ GEM
       prettyprint
     prettier_print (1.2.1)
     prettyprint (0.2.0)
-    prism (1.5.2)
+    prism (1.6.0)
     psych (5.2.6)
       date
       stringio
     racc (1.8.1)
-    rack (3.2.3)
-    rack-attack (6.7.0)
+    rack (3.2.4)
+    rack-attack (6.8.0)
       rack (>= 1.0, < 4)
     rack-parser (0.7.0)
       rack
@@ -93,24 +122,30 @@ GEM
       erb
       psych (>= 4.0.0)
       tsort
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
     regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.81.1)
+    rubocop (1.81.7)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -124,10 +159,10 @@ GEM
     rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-performance (1.26.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rspec (3.7.0)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
@@ -135,7 +170,7 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.1)
+    ruby-lsp (0.26.2)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -145,8 +180,8 @@ GEM
     stringio (3.1.7)
     syntax_tree (6.3.0)
       prettier_print (>= 1.2.0)
-    tryouts (3.6.1)
-      concurrent-ruby (~> 1.0)
+    tryouts (3.7.1)
+      concurrent-ruby (~> 1.0, < 2)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
@@ -161,6 +196,8 @@ GEM
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
+    user_agent_parser (2.20.0)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -180,15 +217,17 @@ DEPENDENCIES
   rack-attack
   rack-test
   rackup
+  reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.81.1)
+  rubocop (~> 1.81.7)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety
   ruby-lsp
   stackprof
   syntax_tree
-  tryouts (~> 3.6.1)
+  tryouts (~> 3.7.1)
+  user_agent_parser (~> 2.18)
 
 BUNDLED WITH
    2.7.1

data/README.md

@@ -2,7 +2,7 @@
 
 **Define your rack-apps in plain-text with built-in security.**
 
-> **v2.0.0-pre1 Available**: This pre-release includes major improvements to middleware management and test coverage. See [changelog](CHANGELOG.rst) and [migration guide](docs/migrating/v2.0.0-pre1.md) for upgraders.
+> **v2.0.0-pre6 Available**: This pre-release includes major improvements to middleware management, logging, and request callback handling. See [changelog](CHANGELOG.rst) for details and upgrade notes.
 
 ![Otto mascot](public/img/otto.jpg "Otto - All Rack, no Pinion")
 
@@ -13,6 +13,14 @@ $ cd myapp && ls
 config.ru app.rb routes
 ```
 
+## Why Otto?
+
+- **Security by Default**: Automatic IP masking for public addresses, user agent anonymization, CSRF protection, and input validation
+- **Privacy First**: Masks public IPs, strips user agent versions, provides country-level geo-location only—no external APIs needed
+- **Simple Routing**: Define routes in plain-text files with zero configuration overhead
+- **Built-in Authentication**: Multiple strategies including API keys, tokens, role-based access, and custom implementations
+- **Developer Friendly**: Works with any Rack server, minimal dependencies, easy testing and debugging
+
 ## Routes File
 ```
 # routes
@@ -76,6 +84,22 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+## Privacy by Default
+
+Otto automatically masks public IP addresses and anonymizes user agents to comply with GDPR, CCPA, and other privacy regulations:
+
+```ruby
+# Public IPs are automatically masked (203.0.113.9 → 203.0.113.0)
+# Private IPs are NOT masked by default (127.0.0.1, 192.168.x.x, 10.x.x.x)
+app = Otto.new("./routes")
+
+# User agents: versions stripped for privacy
+# Geo-location: country-level only, no external APIs or databases
+# IP hashing: daily-rotating hashes enable analytics without tracking
+```
+
+Private and localhost IPs are exempted by default for development convenience, but this behavior can be customized via `configure_ip_privacy()` method. Geolocation uses CDN headers (Cloudflare, AWS, etc.) with fallback to IP ranges—no external services required. See [CLAUDE.md](CLAUDE.md) for detailed configuration options.
+
 ## Internationalization Support
 
 Otto provides built-in locale detection and management:
@@ -132,6 +156,24 @@ end
 
 The locale helper checks multiple sources in order of precedence and validates against your configured locales.
 
+## Examples
+
+Otto includes comprehensive examples demonstrating different features:
+
+- **[Basic Example](examples/basic/)** - Get your first Otto app running in minutes
+- **[Advanced Routes](examples/advanced_routes/)** - Response types, CSRF exemption, logic classes, and namespaced routing
+- **[Authentication Strategies](examples/authentication_strategies/)** - Token, API key, and role-based authentication
+- **[Security Features](examples/security_features/)** - CSRF protection, input validation, file uploads, and security headers
+- **[MCP Demo](examples/mcp_demo/)** - JSON-RPC 2.0 endpoints for CLI automation and integrations
+
+### Standalone Tutorials
+
+- **[Error Handler Registration](examples/error_handler_registration.rb)** - Prevent 500 errors for expected business exceptions
+- **[Logging Improvements](examples/logging_improvements.rb)** - Structured logging with automatic timing
+- **[Geo-location Extension](examples/simple_geo_resolver.rb)** - Extending geo-location with custom resolvers
+
+See the [examples/](examples/) directory for more.
+
 ## Requirements
 
 - Ruby 3.2+
@@ -143,6 +185,12 @@ The locale helper checks multiple sources in order of precedence and validates a
 gem install otto
 ```
 
+## Documentation
+
+- **[CLAUDE.md](CLAUDE.md)** - Comprehensive developer guidance covering authentication architecture, configuration freezing, IP privacy, structured logging, and multi-app patterns
+- **[docs/](docs/)** - Technical guides and migration guides
+- **[CHANGELOG.rst](CHANGELOG.rst)** - Version history, breaking changes, and upgrade notes
+
 ## AI Development Assistance
 
 Version 1.2.0's security features were developed with AI assistance:

data/examples/advanced_routes/README.md

@@ -1,33 +1,150 @@
 # 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.
+This example demonstrates advanced routing features in Otto, including response type negotiation, CSRF exemptions, logic classes, and namespaced routing.
+
+## What You'll Learn
+
+- How to define response types (JSON, view, redirect) in routes
+- Using logic classes to encapsulate business logic
+- CSRF exemption for APIs and webhooks
+- Routing to namespaced classes with complex hierarchies
+- Custom route parameters for flexible routing
+- How Otto handles multiple controllers and modules
 
 ## Project Structure
 
-The example is structured to separate concerns, making it easier to navigate:
+The example is organized to separate concerns:
 
--   `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.
+- `config.ru`: Rack configuration that loads and runs the Otto application
+- `routes`: Comprehensive reference for advanced routing syntax
+- `app.rb`: Loader that requires all controller and logic files
+- `app/controllers/`: Handler classes (`RoutesApp`, namespaced controllers)
+- `app/logic/`: Business logic classes (simple, nested, namespaced)
+- `run.rb`, `puma.rb`, `test.rb`: Alternative server/test runners
 
 ## 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.
+### Response Types
+Define how responses are formatted directly in routes:
+```
+GET  /api/users        UserController#list      response=json
+GET  /page             PageController#show      response=view
+GET  /old-url          PageController#new-url   response=redirect
+```
+
+### Logic Classes
+Route to specialized classes that encapsulate business logic:
+```
+GET  /calculate        DataProcessor   # Otto auto-instantiates and calls #process
+GET  /report           ReportGenerator # Same pattern
+```
+
+### CSRF Exemption
+Mark routes that don't need CSRF tokens (APIs, webhooks):
+```
+POST /api/webhook      WebhookHandler#receive   csrf=exempt
+```
+
+### Namespaced Routing
+Handle complex class hierarchies naturally:
+```
+GET  /v2/dashboard     V2::Logic::Dashboard
+GET  /admin/panel      Admin::Panel#dashboard
+```
+
+### Custom Parameters
+Add arbitrary key-value pairs for flexible routing:
+```
+GET  /admin            AdminPanel#dashboard     role=admin
+```
+
+## How to Run
+
+### Using rackup (recommended)
+
+```sh
+cd examples/advanced_routes
+rackup config.ru
+```
+
+### Using alternative runners
+
+```sh
+ruby run.rb   # Basic rackup
+ruby puma.rb  # Using puma server
+ruby test.rb  # For testing
+```
+
+The application will be running at `http://localhost:9292`.
+
+## Testing Routes
+
+Use curl to test the different routes:
+
+```sh
+# JSON response
+curl http://localhost:9292/json/test
+
+# View response
+curl http://localhost:9292/view/test
+
+# Logic class routing
+curl http://localhost:9292/logic/simple
+
+# Namespaced routing
+curl http://localhost:9292/logic/v2/dashboard
+
+# Custom parameters
+curl "http://localhost:9292/custom?role=admin"
+```
+
+## Expected Output
+
+```
+Listening on 127.0.0.1:9292, CTRL+C to stop
+
+[JSON response]
+GET /json/test 200 OK
+Content-Type: application/json
+{"status": "success", "data": {...}}
+
+[Logic class routing]
+GET /logic/simple 200 OK
+{"processed": true, "input": "test"}
+
+[Namespaced routing]
+GET /logic/v2/dashboard 200 OK
+{"version": "2.0", "dashboard": {...}}
+```
+
+## File Structure Details
+
+### Routes File
+The `routes` file is extensively commented to explain each feature:
+- Response type specification
+- CSRF exemption for APIs
+- Logic class routing syntax
+- Namespaced class resolution
+- Custom parameter examples
+
+### Controllers (`app/controllers/`)
+- `RoutesApp`: Main controller with basic handlers
+- Namespaced modules: Demonstrate complex class hierarchies
+- Handlers return appropriate responses (JSON, HTML, redirects)
+
+### Logic Classes (`app/logic/`)
+- Simple classes: Basic business logic
+- Nested classes: Show how Otto handles namespace resolution
+- Parameterized logic: Demonstrate custom route parameters
 
-## Running the Example
+## Next Steps
 
-1.  Make sure you have the necessary gems installed (`bundle install`).
-2.  Run the application from the root of the `otto` project:
+- Review the `routes` file for syntax reference
+- Examine handler methods to see request/response patterns
+- Check logic classes for business logic encapsulation patterns
+- Explore [Authentication](../authentication_strategies/) for protecting routes
+- See [Security Features](../security_features/) for CSRF, validation, file uploads
 
-    ```sh
-    rackup examples/advanced_routes/config.ru
-    ```
+## Further Reading
 
-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.
+- [CLAUDE.md](../../CLAUDE.md) - Comprehensive developer guidance