otto 2.9.0 → 2.10.0

data/docs/1108-STREAMING_SUPPORT_SUMMARY.md

@@ -1,376 +0,0 @@
-# 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/enrichment.md

@@ -1,128 +0,0 @@
-# ASN and anonymizer enrichment
-
-Two opt-in, country-adjacent signals layered on the same privacy pipeline as
-[geo-country](geo-country.md):
-
-- **ASN** — the network operator an address belongs to, as `req.asn` /
-  `env['otto.privacy.asn']`: `'AS15169'`.
-- **Anonymizer** — whether the address is a known anonymizing egress, as
-  `req.anonymizer` / `env['otto.privacy.anonymizer']`: `'tor'`, `'proxy'`,
-  `'vpn'`, `'residential_proxy'`, `'hosting'`, `'anonymous'`, `'none'`, `'**'`.
-
-Both are **off by default** (unlike geo) and **database-only**: no CDN
-publishes a client-ASN or anonymizer header with meaningful deployment, so
-there is no header tier and none of geo's header-trust machinery applies —
-including the `geo_header`/`trusted_proxy_depth` boot conflict.
-
-Every signal keeps the same three-state contract:
-
-| Value | Meaning |
-| --- | --- |
-| `nil` | the signal is switched off |
-| `'**'` | switched on, but nothing resolved (no database, or lookup failed) |
-| a label | a real answer |
-
-## Configuration
-
-```ruby
-otto.configure_ip_privacy(
-  asn: true,
-  asn_db_path: 'data/origin-asn.mmdb',
-  anonymizer: true,
-  anonymizer_db_path: 'data/anonymizer.mmdb',
-)
-```
-
-Both accept the same bring-your-own-reader seam as geo (`asn_db_reader:` /
-`anonymizer_db_reader:` — any object responding to `#get(ip)`; a reader
-supplied in the same call wins over a path). Bad paths raise at boot, not
-per-request. The [`maxmind-db`](https://rubygems.org/gems/maxmind-db) gem is
-required only when a `*_db_path` is configured.
-
-## ASN: which address is looked up, and why that's safe
-
-The ASN lookup uses the **masked** IP, same as geo. This is not a compromise:
-IPv4 BGP routes are not announced longer than /24, so a /24-masked address
-falls inside the same announced prefix — and therefore the same ASN — as the
-real one. (IPv6 is coarser: at `octet_precision: 1` Otto zeroes the last 80
-bits, wider than many IPv6 announcements, so treat IPv6 ASN as best-effort.)
-
-### Data file
-
-> **Naming caution:** the country database this project recommends,
-> `geo-whois-asn-country`, does **not** contain ASN data. In
-> sapics/ip-location-db naming, `geo-whois-asn` describes the *sources* the
-> country data was derived from; the final token (`-country`) is what the
-> records contain. ASN data is a separate file type in that project.
-
-The recommended ASN file is
-[`origin-asn`](https://github.com/sapics/ip-location-db/tree/main/origin-asn/)
-from sapics/ip-location-db — like `geo-whois-asn-country` it is **PDDL v1.0
-(public domain)** and rebuilt daily, so the licensing/freshness posture
-matches the geo guidance:
-
-```bash
-curl -fsSL -o data/origin-asn.mmdb \
-  https://github.com/sapics/ip-location-db/releases/download/latest/origin-asn.mmdb
-```
-
-Its records carry a flat `autonomous_system_number` (verified against the
-published file), which is the primary key `AsnResolver` reads. GeoLite2-ASN
-and DB-IP ASN Lite MMDBs work too (same key; GeoLite2's EULA caveats from the
-geo doc apply). Reserved ASNs (0 per RFC 7607, the AS_TRANS placeholder 23456
-per RFC 6793) resolve to `'**'` rather than being reported as operators.
-
-## Anonymizer: the one unmasked lookup
-
-Anonymizer classification reads the **unmasked** address. This is deliberate
-and documented in `AnonymizerResolver` itself: anonymizer databases list
-individual egress nodes at or near /32, so the /24 equivalence that justifies
-masked geo and ASN lookups does not hold. A masked lookup would flag a whole
-/24 because one host in it runs a Tor exit, and miss the exit node itself —
-wrong in both directions.
-
-The privacy containment is the same one Otto already relies on for
-`hash_ip` and `env['otto.ip_match']`, which also consume the full IP: **only
-the derived value leaves**. The resolver returns a label; the address is
-never persisted, serialized, or handed downstream.
-
-### Reading the labels
-
-When several database flags are set at once (a Tor exit hosted at a cloud
-provider), the **most specific** label wins: `tor` > `proxy` > `vpn` >
-`residential_proxy` > `hosting` > `anonymous`.
-
-Two labels deserve care:
-
-- **`'none'`** means the database was consulted and does not list the
-  address. For an anonymizer database that is a real answer (these files
-  record only flagged addresses), but it is *not* a positive assertion the
-  visitor is residential — it is only as fresh as your database file.
-- **`'**'`** means no database answered at all. Do not collapse it into
-  `'none'`: `'none'` is evidence, `'**'` is the absence of evidence. A
-  "block anonymizers" rule that treats `'**'` as `'none'` fails open when
-  the database file goes missing.
-
-### Data file
-
-There is no public-domain anonymizer dataset of `origin-asn`'s quality; this
-signal is bring-your-own-database. `AnonymizerResolver` reads the MaxMind
-GeoIP2 Anonymous-IP flag schema (`is_tor_exit_node`, `is_public_proxy`,
-`is_anonymous_vpn`, `is_residential_proxy`, `is_hosting_provider`,
-`is_anonymous`), which commercial and self-built MMDBs alike use. A workable
-self-built option: compile the [Tor bulk exit
-list](https://check.torproject.org/torbulkexitlist) into an MMDB with
-`is_tor_exit_node` set — that covers the highest-signal label with fully
-public data.
-
-## Acceptance behavior summary
-
-| Scenario | Result |
-| --- | --- |
-| Signal not enabled | `nil` everywhere (env key absent for exempt IPs) |
-| Enabled, no database configured | `'**'` |
-| Database read raises | `'**'` (a lookup must never crash a request) |
-| ASN lookup | masked IP only (re-masked defensively in the resolver) |
-| Anonymizer lookup | unmasked IP in, label out, nothing else retained |
-| Private/localhost client (privacy-exempt) | no enrichment keys in env |
-| Bad `*_db_path` | raises at boot, not per-request |

data/docs/geo-country.md

@@ -1,181 +0,0 @@
-# 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. (Two opt-in, database-only companion signals — ASN and
-anonymizer classification — are covered in [enrichment](enrichment.md).)
-
-## 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. This
-  conflict fails loud: configuring a `geo_header` together with a
-  `trusted_proxy_depth` raises `ArgumentError` at configuration time (in
-  either order) instead of silently ignoring the header per-request.
-  Database-backed geo remains fully supported under depth. The built-in
-  provider headers stay legal (there is nothing to configure, so nothing
-  can raise) but are equally inert — header trust requires CIDR-verified
-  proxies — so only an explicitly configured `geo_header` is rejected, and
-  depth deployments that want geo should set `geo_db_path`.
-
-**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 | `'**'` |