otto 2.5.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/advanced_routes/README.md

@@ -58,6 +58,55 @@ Add arbitrary key-value pairs for flexible routing:
 GET  /admin            AdminPanel#dashboard     role=admin
 ```
 
+### Lambda / Inline Route Handlers (Issue #41)
+Route to a proc that you **pre-register** by name, using the `&` prefix:
+```
+GET  /ping             &health_check            response=json
+POST /webhook          &receive_webhook         response=json csrf=exempt
+GET  /go               &to_dashboard            response=redirect
+```
+
+The `&name` token is a plain string key looked up (O(1)) in a registry you
+supply at construction — the entire token after `&` is the key (dots, `#`, and
+`::` are inert). Register the procs when you build Otto:
+```ruby
+otto = Otto.new('routes', lambda_handlers: {
+  'health_check'   => ->(req, res, extra_params) {
+    { status: 'ok', at: Time.now.to_i }        # response=json serializes this Hash
+  },
+  'receive_webhook' => ->(req, res, extra_params) {
+    { received: true }
+  },
+  'to_dashboard'   => ->(req, res, extra_params) {
+    '/dashboard'                                 # response=redirect uses this path
+  },
+})
+```
+
+The handler contract:
+
+- Each proc is called with **`(req, res, extra_params)`** — `extra_params` is the
+  hash of path captures (e.g. `:id` from `/users/:id`).
+- The proc must accept 3 arguments (fixed arity `3`, or a splat/optional form).
+  An invalid arity raises `ArgumentError` at construction.
+- **All response types work** exactly as for controller routes:
+  `response=json` (serializes a returned Hash), `response=view` (`to_s` as HTML),
+  `response=redirect` (returned String is the `Location`), `response=auto`
+  (content negotiation). With the default response type the proc must write to
+  `res` directly, just like the other handler kinds.
+- **Route options apply**: `csrf=exempt` (parse/expose parity with controllers),
+  `auth=`, `role=`, and custom path params all flow through unchanged.
+
+Security guarantee (the point of this feature): route files never carry code.
+`&name` is only ever a name; there is **no `eval` and no dynamic constant
+loading**. A route naming an unregistered handler fails with a clear
+`ArgumentError` ("Lambda handler '...' is not registered or not callable")
+instead of executing anything. The registered procs are, of course, trusted
+code that you wrote.
+
+Note: `csrf=exempt` is parse-and-expose parity with controller routes — the CSRF
+middleware does not enforce it for any handler kind.
+
 ## How to Run
 
 ### Using rackup (recommended)

data/examples/advanced_routes/config.rb

@@ -4,8 +4,21 @@ require 'rack'
 require_relative '../../lib/otto'
 require_relative 'app'
 
-# Simple Otto configuration demonstrating advanced routes syntax
-otto = Otto.new('routes')
+# Simple Otto configuration demonstrating advanced routes syntax.
+#
+# Lambda / inline route handlers (issue #41): procs are pre-registered by name
+# and referenced from the routes file with the '&name' prefix. Lookup is O(1)
+# by exact string — no eval, no dynamic code from the route file.
+otto = Otto.new('routes', lambda_handlers: {
+  # GET /ping &health_check response=json
+  'health_check'    => ->(_req, _res, _extra_params) { { status: 'ok', at: Time.now.to_i } },
+
+  # POST /hooks/receive &receive_webhook response=json csrf=exempt
+  'receive_webhook' => ->(req, _res, _extra_params) { { received: true, method: req.request_method } },
+
+  # GET /go/dashboard &to_dashboard response=redirect (returned String is the Location)
+  'to_dashboard'    => ->(_req, _res, _extra_params) { '/dashboard' },
+})
 
 # Enable basic security features to demonstrate CSRF functionality
 otto.enable_csrf_protection!

data/examples/advanced_routes/routes

@@ -93,6 +93,18 @@ GET   /logic/nested/feature     Nested::Feature::Logic
 POST  /logic/complex/handler    Complex::Business::Handler response=json
 PUT   /logic/system/config      System::Config::Manager response=json csrf=exempt
 
+# ========================================
+# LAMBDA / INLINE ROUTE HANDLERS (Issue #41)
+# ========================================
+
+# The '&name' prefix references a proc pre-registered via
+#   Otto.new('routes', lambda_handlers: { 'name' => ->(req,res,extra){ ... } })
+# Lookup is O(1) by exact string name — no eval, no dynamic constants.
+# An unregistered name fails with a clear error, never executes code.
+GET   /ping                     &health_check response=json
+POST  /hooks/receive            &receive_webhook response=json csrf=exempt
+GET   /go/dashboard             &to_dashboard response=redirect
+
 # ========================================
 # NAMESPACED CLASS ROUTES
 # ========================================