otto 2.6.0 → 2.7.0

data/docs/1108-STREAMING_SUPPORT_SUMMARY.md

@@ -0,0 +1,376 @@
+# Otto Streaming Support: Executive Summary
+
+**Investigation Date**: 2025-11-08
+**Question**: Should Otto support Server-Sent Events (SSE) and WebSockets?
+**Answer**: **No** - Use separate services or long-polling instead
+
+> **Note**: The Ruby snippets below illustrate the recommended architecture. They
+> are written against the current Otto Logic-class contract
+> (`initialize(context, params, locale)` + `process`), but have not been executed
+> end-to-end. Runnable examples are tracked separately.
+
+---
+
+## Quick Recommendation
+
+| Use Case | Solution | Complexity | Otto Compatible? |
+|----------|----------|------------|------------------|
+| **Low-frequency updates (<1/min)** | Long-polling | ⭐ Simple | ✅ Yes |
+| **Medium-frequency updates (1-10/sec)** | Separate SSE service | ⭐⭐ Moderate | ✅ Via integration |
+| **High-frequency updates (>10/sec)** | Separate WebSocket service | ⭐⭐⭐ Complex | ✅ Via integration |
+| **Bidirectional communication** | Separate WebSocket service | ⭐⭐⭐ Complex | ✅ Via integration |
+
+---
+
+## Key Findings
+
+### 1. **Otto's Architecture is Fundamentally Incompatible with Streaming**
+
+Otto is designed as a **stateless, synchronous, request/response** framework:
+
+```
+Request → Middleware → Route → Handler → Response → Close Connection
+```
+
+SSE/WebSocket require **stateful, long-lived connections**:
+
+```
+Request → Upgrade → Keep Open → Stream Data (minutes/hours) → Close
+```
+
+**Incompatibilities**:
+- ❌ Response handlers expect complete responses (not streaming enumerators)
+- ❌ Middleware stack can't unwind during long-lived connections
+- ❌ Configuration freezing prevents runtime streaming adjustments
+- ❌ Requires async servers (Falcon, Iodine) - breaks server-agnostic design
+- ❌ Stateful routing complicates horizontal scaling
+
+### 2. **Industry Best Practice: Separate Services**
+
+Modern frameworks separate real-time communication from REST APIs:
+
+**Rails (ActionCable)**:
+```
+Rails App (Puma) → Redis Pub/Sub ← ActionCable (Separate Process)
+```
+
+**Node.js (Express + Socket.IO)**:
+```
+Express (HTTP Routes) + Socket.IO (Separate Layer)
+```
+
+**Benefits**:
+- ✅ Independent scaling (scale WebSocket separately from API)
+- ✅ Technology choice (use best tool for each job)
+- ✅ Fault isolation (WebSocket crash doesn't affect API)
+- ✅ Clear architectural boundaries
+
+### 3. **Long-Polling Works Perfectly with Otto**
+
+For low-to-medium frequency updates, long-polling is **simple and effective**:
+
+```ruby
+# Otto route (works with any Rack server)
+GET /api/notifications/poll NotificationPollLogic response=json auth=session
+
+class NotificationPollLogic
+  attr_reader :context, :params, :locale
+
+  def initialize(context, params, locale)
+    @context = context
+    @params  = params
+    @locale  = locale
+  end
+
+  def process
+    # Logic-class params are string-keyed (LogicClassHandler does not apply
+    # Otto::Static.indifferent_params).
+    timeout    = params['timeout'].to_i.clamp(1, 30)
+    last_id    = params['last_id'].to_i
+    start_time = Time.now
+
+    # Identity comes from the StrategyResult, never from request params.
+    user_id = context.user_id
+
+    loop do
+      notifications = fetch_new(user_id, last_id)
+      return { notifications: notifications } if notifications.any?
+
+      break if Time.now - start_time > timeout
+
+      sleep 0.5
+    end
+
+    { notifications: [] }
+  end
+end
+```
+
+**Benefits**:
+- ✅ HTTP-based (cacheable, proxy-friendly, standard tooling)
+- ✅ Works with Otto's synchronous model
+- ✅ Compatible with any Rack server (Puma, Unicorn, Passenger)
+- ✅ Simple debugging (standard HTTP requests/responses)
+- ✅ No external dependencies
+
+---
+
+## Recommended Solutions
+
+### Option 1: Long-Polling (SIMPLEST)
+
+**When to use**:
+- Updates less than 1 per minute
+- Moderate concurrency (<10,000 clients)
+- Simple deployment preferred
+
+**Example**: see the `NotificationPollLogic` sketch above.
+
+**Complexity**: ⭐ Simple
+**Otto Integration**: ✅ Native support (no changes needed)
+
+---
+
+### Option 2: Separate SSE Service (RECOMMENDED FOR REAL-TIME)
+
+**When to use**:
+- Updates 1-10 per second
+- High concurrency (>10,000 clients)
+- Near-instant updates required (<100ms latency)
+
+**Architecture**:
+```
+┌─────────────────┐
+│   Otto API      │  ← Stateless HTTP (authentication, business logic)
+│   (Puma)        │
+└─────────────────┘
+         ↓
+    ┌─────────┐
+    │  Redis  │  ← Message queue (pub/sub)
+    │ Pub/Sub │
+    └─────────┘
+         ↓
+┌─────────────────┐
+│  SSE Service    │  ← Stateful streaming (Falcon/Iodine)
+│  (Falcon)       │
+└─────────────────┘
+```
+
+**Example**: see "Otto + Falcon SSE Integration" in
+`docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`.
+
+**Complexity**: ⭐⭐ Moderate
+**Otto Integration**: ✅ Via Redis pub/sub
+
+---
+
+### Option 3: Third-Party Service (COMMERCIAL)
+
+**When to use**:
+- Don't want to manage WebSocket infrastructure
+- Need global CDN distribution
+- Require guaranteed SLA
+
+**Options**:
+- **Mercure**: Open-source SSE hub (self-hosted or managed)
+- **Ably**: Commercial real-time messaging platform
+- **Pusher**: Commercial WebSocket/SSE service
+
+**Complexity**: ⭐⭐ Moderate (integration)
+**Otto Integration**: ✅ Via HTTP API
+
+---
+
+## Documentation Created
+
+### **docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md** (15,000+ words)
+Comprehensive technical analysis covering:
+- Otto's current architecture (detailed lifecycle analysis)
+- Technical requirements for SSE/WebSocket (Rack 3, hijacking, etc.)
+- Industry patterns (Rails, Sinatra, Roda, Go, Node.js)
+- Compatibility analysis (why it doesn't fit)
+- Best practices and anti-patterns
+- Detailed recommendations with code examples
+
+### Runnable examples: not yet published
+
+Draft `examples/otto_falcon_sse_integration.rb` and
+`examples/long_polling_example.rb` were written alongside this analysis but
+targeted an Otto API surface that does not exist (`Otto::RequestContext`,
+`enable_sessions!`, `raise_concern`, a `session` helper, `Rack::Handler::Puma`
+under the Rack 3 pin) and used symbol-keyed params that Logic routes never
+populate. They were withheld rather than shipped as copy-paste material; the
+architecture they demonstrated is preserved in the snippets here and in the
+analysis document.
+
+---
+
+## Key Insights
+
+### The Real Question
+
+**Not**: "Can Otto support SSE/WebSocket?"
+(Technically possible with massive refactoring)
+
+**But**: "Should Otto support SSE/WebSocket?"
+(Architecturally inadvisable)
+
+### Answer: **No**
+
+Otto should remain focused on its core strengths:
+- ✅ **Stateless** HTTP APIs
+- ✅ **Security-first** design (CSRF, rate limiting, validation)
+- ✅ **Privacy by default** (IP masking, geo-location)
+- ✅ **Server-agnostic** (works with any Rack server)
+- ✅ **Simple** and predictable architecture
+
+Adding SSE/WebSocket would:
+- ❌ Compromise architectural integrity
+- ❌ Force specific async servers (Falcon, Iodine)
+- ❌ Complicate security guarantees (middleware assumptions broken)
+- ❌ Add significant complexity for niche use case
+- ❌ Go against industry best practices (separation of concerns)
+
+---
+
+## What Otto SHOULD Do
+
+### 1. ✅ Document Integration Patterns
+
+Add official guide: "Integrating Otto with Real-Time Services"
+- Long-polling patterns (built-in support)
+- Separate SSE service pattern (Otto + Falcon + Redis)
+- Third-party service integration (Mercure, Ably, Pusher)
+
+### 2. ✅ Provide Example Code
+
+Add to `examples/` directory, written against the real Logic-class contract and
+verified to boot:
+- `long_polling_example.rb`
+- `otto_falcon_sse_integration.rb`
+- `otto_mercure_integration.rb`
+
+### 3. ⚠️ Consider Plugin System (If Community Demands)
+
+**Only if there's strong demand**, create experimental plugin:
+- Clearly marked "experimental" and "unsupported"
+- Requires Falcon/Iodine (documented)
+- Security implications documented
+- No core changes required
+
+### 4. ❌ Do NOT Add to Core
+
+Preserve Otto's architectural integrity by:
+- Keeping core stateless and synchronous
+- Maintaining server-agnostic design
+- Focusing on security and simplicity
+- Following industry best practices (separation of concerns)
+
+---
+
+## Migration Guide for Existing Users
+
+If you currently need real-time updates:
+
+### Step 1: Assess Your Use Case
+
+**Low-frequency updates (<1/min)**:
+→ Use long-polling (Otto native support)
+
+**Medium-frequency updates (1-10/sec)**:
+→ Use separate SSE service (Otto + Falcon + Redis)
+
+**High-frequency or bidirectional**:
+→ Use separate WebSocket service or commercial solution
+
+### Step 2: Implementation Path
+
+#### For Long-Polling:
+1. Create Otto route with long-polling logic
+2. Use `sleep` loop with timeout
+3. Client polls with timeout parameter
+4. No external dependencies needed
+
+See the `NotificationPollLogic` sketch above.
+
+#### For Separate SSE Service:
+1. Otto API handles authentication and publishes to Redis
+2. Separate Falcon app subscribes to Redis and streams SSE
+3. Client connects to SSE service with JWT token from Otto
+4. Scale Otto and SSE services independently
+
+See "Otto + Falcon SSE Integration" in
+`docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`.
+
+### Step 3: Deployment
+
+**Long-Polling**:
+- Deploy with existing Otto setup (Puma, Unicorn, Passenger)
+- Increase thread pool size for long-polling routes
+- Monitor connection pool (ensure enough threads)
+
+**Separate SSE Service**:
+- Deploy Otto API with Puma (standard)
+- Deploy Falcon SSE service separately (dedicated servers)
+- Use Redis for pub/sub (cluster-ready)
+- Configure Nginx with sticky sessions for SSE
+- Scale services independently based on load
+
+---
+
+## Performance Guidance
+
+### Long-Polling Capacity
+
+**Example**: Puma with 5 workers × 32 threads = 160 concurrent requests
+
+If long-polling uses 30s timeout:
+- 160 concurrent connections
+- ~320 clients with 50% utilization
+- Up to 10,000 clients with proper thread tuning
+
+**Good for**: Dashboard metrics, low-volume notifications
+
+### SSE/WebSocket Capacity
+
+**Example**: Falcon with 4 workers (async)
+
+Each worker handles thousands of concurrent connections via fibers:
+- 10,000+ concurrent SSE connections per server
+- Horizontal scaling via Redis pub/sub
+- Near-instant message delivery
+
+**Good for**: Chat, multiplayer, high-frequency updates
+
+---
+
+## Conclusion
+
+**Otto should NOT integrate SSE/WebSocket support** because:
+
+1. **Architectural mismatch**: Stateless vs stateful paradigms
+2. **Industry consensus**: Separate services is best practice
+3. **Complexity cost**: Massive refactoring for niche use case
+4. **Better alternatives**: Long-polling (simple) or separate services (powerful)
+
+**Instead, Otto should**:
+
+1. ✅ Document long-polling patterns (works today)
+2. ✅ Provide integration examples (Otto + Falcon + Redis)
+3. ✅ Recommend third-party solutions (Mercure, Ably, Pusher)
+4. ✅ Stay focused on stateless HTTP APIs
+
+**This preserves Otto's core strengths** while enabling users who need real-time functionality to integrate appropriate solutions.
+
+---
+
+## Further Reading
+
+- **Technical Analysis**: `docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md`
+- **Rack 3 Streaming**: https://github.com/rack/rack/issues/1600
+- **ActionCable Architecture**: https://guides.rubyonrails.org/action_cable_overview.html
+- **SSE vs WebSocket**: https://ably.com/blog/websockets-vs-sse
+
+---
+
+**End of Summary**

data/docs/geo-country.md

@@ -0,0 +1,172 @@
+# Geo-country resolution
+
+Otto resolves a country-level ISO 3166-1 alpha-2 code for each request and
+exposes it as `req.geo_country` / `env['otto.privacy.geo_country']`. Resolution
+is country-only by design — that is the privacy posture; there is no city or
+region lookup.
+
+## Resolution order
+
+`Otto::Privacy::GeoResolver.resolve` returns the first hit from:
+
+1. **Application-configured header** (`geo_header:`) — e.g. `X-Client-Country`.
+2. **Known provider headers** — Cloudflare (`CF-IPCountry`), AWS CloudFront,
+   Fastly, Akamai Edgescape, Azure Front Door, **Vercel**
+   (`X-Vercel-IP-Country`), and a few semi-standard names
+   (`X-Geo-Country`, `X-Country-Code`, `Country-Code`).
+3. **Custom resolver** (`GeoResolver.custom_resolver`) — your own callable.
+   Unlike the other geo settings, this is **class-level** (see
+   [Configuration](#configuration)).
+4. **Local MMDB database** (`geo_db_path:` / `geo_db_reader:`) — a MaxMind-DB
+   country database.
+5. **`'**'`** — the unknown sentinel, when nothing else matches.
+
+Steps 1 and 2 are **only consulted when geo headers can be trusted** (see
+[Header trust](#header-trust-and-spoofing) below).
+
+Resolution is **honest**: Otto does not guess from a hardcoded IP-range table.
+When no header, custom resolver, or database resolves a country, the result is
+`'**'`.
+
+### Privacy: masked IP and masked env
+
+The database lookup in step 4 runs on the request's **masked** IP
+(e.g. `203.0.113.0`), never the real address. `check_geo_database` masks the IP
+internally with the config's `octet_precision` before the lookup, so even a
+direct `GeoResolver.resolve` caller passing a real IP does not expose it to the
+database. Country-level MMDB networks are almost always ≥ /24, so the default
+/24-masked value (`octet_precision: 1`) resolves to the same country.
+
+In the middleware path Otto additionally hands `resolve` a **masked env view**:
+`REMOTE_ADDR`, `X-Forwarded-For`, `X-Real-IP`, `X-Client-IP`, and the RFC 7239
+`Forwarded` header are masked. So a `custom_resolver` cannot read the raw client
+IP out of `env` either — use the `ip` argument (already masked), not `env`.
+
+> **`octet_precision: 2`** masks two octets (a /16). That is coarser than most
+> country networks, so it can reduce database hit rate for the small share of
+> countries whose ranges are finer than /16 — those requests fall through to
+> `'**'`. Header and custom-resolver sources are unaffected (they ignore the
+> IP). Keep the default precision if you rely on the MMDB fallback.
+
+## Configuration
+
+All geo configuration is **boot-time only** (set once during single-threaded
+initialization, before serving requests), matching `custom_resolver`'s
+contract. `geo_header`, `geo_db_path`, and `geo_db_reader` are stored on the
+instance's `Otto::Privacy::Config`, so separate Otto instances hold independent
+geo configuration.
+
+> **`custom_resolver` is the exception — it is class-level, not per-instance.**
+> `GeoResolver.custom_resolver=` sets a singleton on the `GeoResolver` class, so
+> it is **shared across every Otto instance in the process** (last write wins).
+> If you run multiple Otto instances that need different resolver strategies,
+> the custom resolver cannot distinguish them — branch inside a single resolver
+> on `env`, or use per-instance `geo_db_reader` instead.
+
+```ruby
+otto.configure_ip_privacy(
+  geo:           true,                                # default; false disables geo entirely
+  geo_header:    'X-Client-Country',                 # trusted app header (optional)
+  geo_db_path:   'data/geo-whois-asn-country.mmdb',  # local MMDB fallback (optional)
+  # geo_db_reader: MaxMind::DB.new(path),            # or bring your own reader (optional)
+)
+```
+
+- **`geo: false`** short-circuits everything: no header reads, and any loaded
+  database is unloaded from memory (`req.geo_country` becomes `nil`).
+- **`geo_header:`** accepts either the HTTP header name (`X-Client-Country`) or
+  the Rack CGI env key (`HTTP_X_CLIENT_COUNTRY`), in any case, and is
+  canonicalized to the env-key form. Pass `''` to clear.
+- **`geo_db_path:`** is loaded once at boot in `MODE_MEMORY`. An unreadable
+  path, a corrupt/non-MMDB file, or a missing `maxmind-db` gem raises
+  `ArgumentError` **at configuration time**, not per-request. Pass `''` to
+  unload.
+- **`geo_db_reader:`** injects any object responding to `#get(ip)` (a
+  preconfigured `MaxMind::DB` reader or a test double), keeping the reader and
+  data-source choice independent of Otto. It **overrides** `geo_db_path` when
+  both are given in the same call; supplying `geo_db_path` alone in a later call
+  clears a prior reader override.
+
+Each keyword follows a `nil` = "leave unchanged" contract; pass `''` to a header
+or path to clear it. Any geo-affecting change triggers the boot-time database
+(re)load, so a bad `geo_db_path` fails at the `configure_ip_privacy` call.
+
+## The database: gem and datafile
+
+The reader and the data file are independent — the MMDB format is the interop
+point.
+
+### Reader gem (`maxmind-db`)
+
+The [`maxmind-db`](https://rubygems.org/gems/maxmind-db) gem (official MaxMind
+reader, Apache-2.0, pure Ruby, zero runtime deps) is an **optional**
+dependency. Otto only `require`s it when a database is configured. Add it to
+your app when you use the database fallback:
+
+```ruby
+# Gemfile
+gem 'maxmind-db', '~> 1.4'
+```
+
+### Data file (`geo-whois-asn-country`)
+
+The recommended data file is
+[`geo-whois-asn-country`](https://github.com/sapics/ip-location-db) from
+sapics/ip-location-db: **PDDL v1.0 (public domain, no attribution required)**,
+rebuilt daily, shipped as MMDB. Otto vendors no database — country data goes
+stale, and a public-domain file you refresh on your own schedule keeps
+licensing and freshness in your control.
+
+Download it (IPv4+IPv6) into a path of your choosing:
+
+```bash
+mkdir -p data
+curl -fsSL -o data/geo-whois-asn-country.mmdb \
+  https://github.com/sapics/ip-location-db/releases/download/latest/geo-whois-asn-country.mmdb
+```
+
+Refresh it on your own schedule (e.g. a daily cron job running the same curl).
+Any MMDB country database works — GeoLite2-Country, DB-IP Country Lite,
+iplocate, etc. — since `GeoResolver` tolerates the record shapes country
+databases actually use: nested `country.iso_code` (GeoLite2-Country style), a
+flat `country_code` string, and a bare-string `country`.
+
+> **Note on GeoLite2:** its EULA requires a MaxMind account/license key and
+> obliges consumers to refresh within 30 days of each release. A PDDL dataset
+> avoids both obligations.
+
+## Header trust and spoofing
+
+Every geo header is trivially client-spoofable unless the request actually
+arrived through the CDN that sets it. Otto trusts geo headers — both the
+configured `geo_header` and the provider headers — **only** for a request that
+demonstrably arrived via a configured **CIDR trusted proxy**
+(`env['otto.via_trusted_proxy']` with `trusted_proxies` configured). A spoofed
+header on a direct connection is ignored, and resolution falls through to the
+custom resolver / database.
+
+Origins Otto cannot verify are **not** trusted:
+
+- **No trusted-proxy configuration.** A direct internet client could otherwise
+  pick its own country by sending `CF-IPCountry` / `X-Client-Country`, so with
+  no `trusted_proxies` configured, header steps are skipped and resolution falls
+  to the resolver / database (`'**'` if neither is set).
+- **Count-based `trusted_proxy_depth` mode.** The header-setting hop cannot be
+  verified as a geo-CDN, so depth mode does not enable header trust.
+
+**Migration:** to keep header-based geo, configure `trusted_proxies` (CIDR
+matchers) so Otto can verify the proxy origin. Depth-mode and header-only
+deployments should set `geo_db_path` for a local database instead; otherwise
+resolution returns `'**'`.
+
+## Acceptance behavior summary
+
+| Scenario | Result |
+| --- | --- |
+| Configured `geo_header` present and trusted | wins over provider headers |
+| Request not via a verified CIDR trusted proxy | geo headers skipped |
+| No `trusted_proxies` configured | geo headers skipped (not trusted) |
+| Database lookup | uses the masked IP only |
+| `geo: false` | `nil`, no database in memory |
+| Bad `geo_db_path` | raises at boot, not per-request |
+| Nothing matches | `'**'` |

data/docs/reverse-proxy-network-services.md

@@ -177,12 +177,25 @@ deny). Everything fails closed.
 This is the load-bearing decision, and it corrects the obvious-but-wrong first
 instinct (which every initial design in the panel made).
 
-`Otto::CaddyTLS::LocalhostGuard` reads the **original `env['REMOTE_ADDR']`** — the
-TCP socket peer — and runs **before** `IPPrivacyMiddleware` rewrites `REMOTE_ADDR`
-from forwarded headers. Because the guard is installed via `Otto#use` (appended,
-therefore *outermost* in Otto's `reduce`-built stack) and `IPPrivacyMiddleware` is
-pinned *innermost*, the guard provably inspects the true socket peer regardless of
-when `enable_caddy_tls!` is called.
+`Otto::CaddyTLS::LocalhostGuard` authenticates the **original TCP socket peer**,
+never the address left in `REMOTE_ADDR` after `IPPrivacyMiddleware` rewrites it
+from forwarded headers.
+
+Otto originally guaranteed that by ordering: the guard is installed via `Otto#use`
+(appended, therefore *outermost* in Otto's `reduce`-built stack) and
+`IPPrivacyMiddleware` was pinned *innermost*, so the guard ran first and read a
+pristine `REMOTE_ADDR`. Issue #219 inverted that: masking innermost meant every
+*other* middleware saw raw IPs, so `IPPrivacyMiddleware` is now pinned **outermost**
+(the `:entrypoint` tier) and runs *ahead* of the guard.
+
+The guarantee is preserved by a record rather than by order.
+`IPPrivacyMiddleware` evaluates the untouched peer before masking and stores the
+verdict as `env['otto.peer_loopback']` — a boolean, never an address, so it leaks
+nothing. The guard reads that record when present and evaluates `REMOTE_ADDR`
+itself when it is not (guard mounted outside Otto, or no privacy middleware in the
+stack). Both paths share `Otto::Utils.loopback_address?`, so they cannot drift, and
+the decision is made on the raw peer either way — regardless of when
+`enable_caddy_tls!` is called.
 
 Reading Otto's resolved `otto.client_ip` (or the rewritten `REMOTE_ADDR`) would be
 **exploitable**: `Otto::Utils.resolve_client_ip` honors `X-Forwarded-For` when the

data/examples/simple_geo_resolver.rb

@@ -3,15 +3,46 @@
 
 # Otto GeoResolver Extension Guide
 #
-# This guide shows two approaches to extend Otto's IP geolocation:
-# 1. Configuration-based (simple, inline)
-# 2. Subclass-based (full control)
+# Otto resolves a country code in this order (first hit wins):
+#   1. App-configured trusted header  (configure_ip_privacy(geo_header:))
+#   2. Built-in CDN/provider headers  (Cloudflare, AWS, Vercel, ...)
+#   3. Custom resolver hook           (GeoResolver.custom_resolver = ...)
+#   4. Local MMDB database            (configure_ip_privacy(geo_db_path:/geo_db_reader:))
+#   5. '**' (unknown)                 Otto does not guess from a hardcoded table
+#
+# This guide shows the extension points:
+# A. Built-in configuration (trusted header + local database) — no code
+# B. Custom resolver hook (inline or a callable object)
+# C. Subclass-based (full control)
 
 require 'bundler/setup'
 require 'otto'
 
 # =============================================================================
-# Quick Start: Configuration-based Extension
+# A. Built-in configuration: trusted header + local country database
+# =============================================================================
+#
+# No custom code needed — just configure the Otto instance. The database is
+# looked up on the already-MASKED IP, and a bad geo_db_path fails at boot.
+#
+#   otto = Otto.new('routes.txt')
+#   otto.configure_ip_privacy(
+#     geo_header: 'X-Client-Country',   # trusted header checked before CDN headers
+#     geo_db_path: 'data/country.mmdb'  # offline fallback (needs the maxmind-db gem)
+#   )
+#
+# Prefer to bring your own reader (any object responding to #get)? Inject it —
+# this keeps the reader/data-source choice independent of Otto:
+#
+#   reader = MaxMind::DB.new('data/country.mmdb', mode: MaxMind::DB::MODE_MEMORY)
+#   otto.configure_ip_privacy(geo_db_reader: reader)
+#
+# Security note: geo headers are only trusted for requests that arrive via a
+# configured trusted proxy (add_trusted_proxy), since they are client-spoofable
+# otherwise. configure_ip_privacy(geo: false) disables geo entirely.
+
+# =============================================================================
+# B. Quick Start: Custom resolver hook
 # =============================================================================
 
 puts 'Simple Custom Geo Resolution'
@@ -31,7 +62,9 @@ Otto::Privacy::GeoResolver.custom_resolver = custom_resolver
 
 # Step 3: Test it
 puts "1.2.3.4 -> #{Otto::Privacy::GeoResolver.resolve('1.2.3.4', {})}"
-puts "8.8.8.8 -> #{Otto::Privacy::GeoResolver.resolve('8.8.8.8', {})} (fallback)"
+# Resolver returns nil for 8.8.8.8, and there is no header or database, so the
+# honest answer is '**' (unknown) — Otto does not guess.
+puts "8.8.8.8 -> #{Otto::Privacy::GeoResolver.resolve('8.8.8.8', {})} (unknown)"
 
 # Reset for next example
 Otto::Privacy::GeoResolver.custom_resolver = nil