otto 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e50cca678689db3e2447e76a8a1b12f3b709305d4f73908cb06dfe6883adc596
-  data.tar.gz: a6093388b74ffbd098c222a026c1f1cf439c8039c75a0d55b663a0874669c6ee
+  metadata.gz: de513e2f41fa9d2400937ac2ed577878bd124d5f760558bd12635bf8ad6f296a
+  data.tar.gz: 4a69f3741d3a6dbbe5a7387e2504446ce690927be12ccf90fa814db1a893d13d
 SHA512:
-  metadata.gz: ea5a8acda9a29c09d3a16a050050c2e9b9a1517c7f63e24bb7bc910801a7a07874fff1215550a740cef2c9c3698bc77378083b33f47794a7668b77feff9e6e67
-  data.tar.gz: 62cfbe824d5d0d9e159424a6d930217f05b8b01de7142108a6a80953207cca9037a3e63d6ae5c16585dda3ff7b8a9b2d070b593f748563c0a5a20ed852add37f
+  metadata.gz: 77ee1dda2b8b84e3848fb72fd737b88b6d6efca57cd0d4effe909451a310aee51ac207a3152848ebc838df52bd02c3153cb818e1bafdc1000282a374be965375
+  data.tar.gz: 8622e8974f115eee90940a157ea93180f2e4aaa05295f5362ca24f068b359b7d2a1396c42483e4d4fa37b9e8fbee7056460230eb68227033134eda09e5e4d8cc

data/.github/workflows/ruby-lint.yml

@@ -41,7 +41,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
 
       - uses: ruby/setup-ruby@v1
         with:

data/.github/workflows/yardoc.yml

@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
         with:
           fetch-depth: 0
 

data/CHANGELOG.rst

@@ -7,6 +7,141 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.6.0:
+
+2.6.0 — 2026-07-10
+==================
+
+Added
+-----
+
+- ``Otto::Privacy::UserAgentPrivacy.anonymize(ua, max_length:)`` — public
+  User-Agent anonymization, mirroring ``Otto::Privacy::IPPrivacy``. Strips
+  build/version identifiers while preserving browser/OS family; idempotent.
+  (delano/otto#194)
+
+- Stable-keyed IP correlation hash: ``req.ip_correlation_hash`` /
+  ``env['otto.privacy.correlation_hash']``, keyed via
+  ``configure_ip_privacy(correlation_secret:)`` so the same host correlates
+  across days without exposing the raw IP. (#192)
+
+- CSP nonce policies can now be customized per-directive via
+  ``enable_csp_with_nonce!(directives:)`` and ``#csp_directive_overrides=`` /
+  ``#merge_csp_directives``, not just ``report-uri``/``report-to``. (#201)
+
+Changed
+-------
+
+- ``RedactedFingerprint#anonymize_user_agent`` now delegates to
+  ``UserAgentPrivacy.anonymize``; behavior is unchanged. (delano/otto#194)
+
+- Default CSP ``worker-src`` now emits ``'self' blob:`` instead of
+  ``'self' data:``. Restore the old value with
+  ``directives: { worker_src: "'self' data: blob:" }``. (#201)
+
+Fixed
+-----
+
+- ``Otto#uri`` no longer corrupts when the same handler is mounted at
+  multiple paths — all routes per definition are kept, and ``uri()`` matches
+  on the params given. (#190)
+
+- ``Route#call`` no longer builds a duplicate, discarded request/response
+  pair when a route handler factory is present. (#189)
+
+- Dynamic static-file serving no longer raises ``FrozenError`` in production
+  on the first request for an uncached asset. (delano/otto#185)
+
+Security
+--------
+
+- Route loading now fails closed on malformed input: unparseable options
+  warn, and malformed or mismatched-case ``auth``/``role``/``csrf`` tokens
+  raise ``Otto::RouteDefinitionError`` at load instead of silently serving
+  an unprotected route. (#191)
+
+- ``klass.otto`` is no longer a shared mutable class accessor — it's now
+  fiber-local, preventing concurrent requests across ``Otto`` instances from
+  racing and observing the wrong security config. (#188)
+
+- Dynamic-route and static-file dispatch now normalize request paths the
+  same way literal routing does, closing a trailing-slash and
+  invalid-UTF-8 divergence. (#187)
+
+- ``csrf=exempt`` is now actually enforced at the handler layer; previously
+  it was a silent no-op. **Behavior change**: ``CSRFMiddleware`` used
+  standalone no longer blocks unsafe requests on its own. (#186)
+
+.. _changelog-2.5.0:
+
+2.5.0 — 2026-07-02
+==================
+
+Added
+-----
+
+- ``Otto::Security::CSP::Writer.apply(headers, nonce, config:, mode:,
+  development_mode:)`` — the single structural apply core for nonce-based CSP
+  emission. Writes are in-place and key-scoped (case-variant keys are corrected
+  to Rack 3's lowercase in the caller's hash; a frozen headers hash fails loud).
+  Returns a ``Result`` (``applied?``, ``policy``, ``skip_reason`` of
+  ``:disabled`` / ``:blank_nonce`` / ``:non_html`` / ``:existing_csp``). Named
+  modes ``:override`` (deliberate, replaces) and ``:backstop`` (passive,
+  defers). (delano/otto#180)
+
+- Framework-owned lazy nonce: ``Otto::Request#csp_nonce`` /
+  ``Otto::Security::CSP.nonce(env)`` generate on first access and memoize into
+  ``env['otto.nonce']`` (registered as ``Otto::EnvKeys::NONCE``), so views and
+  the header read one value. Configurable env key via
+  ``Otto::Security::Config#csp_nonce_key`` for apps with an existing convention.
+
+- ``Otto::Security::CSP::EmitMiddleware`` and ``Otto#enable_csp_emission!`` — a
+  passive backstop that emits a nonce CSP for HTML responses whose request
+  consumed a nonce (emit-if-consumed default), never clobbering an existing
+  policy. Optional ``eager:`` mode and a per-request ``development_mode:``
+  callable.
+
+- ``Otto::Response#apply_csp(nonce, mode: :override)`` — the one emission helper,
+  routed through the apply core.
+
+- ``Otto::Security::CSP::Policy`` — CSP policy building (directive sets,
+  report-uri/report-to assembly) extracted from ``Otto::Security::Config`` into
+  its own home beside the parser and middlewares; ``Config`` delegates with
+  byte-identical output.
+
+Deprecated
+----------
+
+- ``Otto::Response#send_csp_headers`` — use ``#apply_csp`` or
+  ``#enable_csp_emission!``. Retained as a thin shim over the apply core (logs a
+  one-time ``Otto.logger`` deprecation notice).
+
+Fixed
+-----
+
+- ``#send_csp_headers`` no longer emits a broken ``script-src 'nonce-'`` for a
+  blank/nil nonce (it skips) and no longer emits a CSP for non-HTML responses —
+  both via the shared apply core. Its bare ``warn`` to stderr when overwriting an
+  existing CSP is also gone: replacement is deliberate in ``:override`` mode, and
+  the shim instead logs a one-time deprecation notice through ``Otto.logger``.
+
+Security
+--------
+
+- Nonce-CSP emission now detects and normalizes CSP / Content-Type headers
+  case-insensitively, so a canonical-/mixed-cased header from a downstream layer
+  is recognized (and the CSP key rewritten to lowercase) rather than silently
+  duplicated — de-duplicating the hand-rolled, case-sensitive guards adopters
+  previously re-implemented at each raw-tuple boundary. (delano/otto#180)
+
+AI Assistance
+-------------
+
+- The nonce-CSP emission redesign — the ``Writer`` apply core, the
+  framework-owned lazy nonce, the ``EmitMiddleware`` backstop, and the
+  ``Policy`` extraction — was designed and implemented with AI assistance.
+  (delano/otto#180)
+
 .. _changelog-2.4.0:
 
 2.4.0 — 2026-07-01

data/Gemfile

@@ -28,7 +28,7 @@ group :development do
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
   gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.88.0', require: false
+  gem 'rubocop', '~> 1.88.1', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.4.0)
+    otto (2.6.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -59,7 +59,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.9)
+    json (2.20.0)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -67,7 +67,7 @@ GEM
       simpleidn (~> 0.2)
     kramdown (2.5.2)
       rexml (>= 3.4.4)
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     loofah (2.25.1)
@@ -147,7 +147,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.0)
+    rubocop (1.88.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -225,7 +225,7 @@ DEPENDENCIES
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.88.0)
+  rubocop (~> 1.88.1)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/README.md

@@ -84,6 +84,60 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+### Content Security Policy (nonce-based emission)
+
+Otto owns the nonce lifecycle so the header and your views can never drift. A
+request-scoped nonce is minted lazily on first access and memoized in the env;
+your views read it to stamp `<script>`/`<link>` tags, and the framework reads
+the *same* value to emit the `script-src 'nonce-…'` header.
+
+```ruby
+app = Otto.new("./routes")
+app.enable_csp_with_nonce!    # turn on nonce-based CSP
+app.enable_csp_emission!      # mount the backstop that writes the header
+
+# In a view/handler:
+def show(req, res)
+  res['content-type'] = 'text/html; charset=utf-8'
+  res.write(%(<script nonce="#{req.csp_nonce}">/* inline */</script>))
+end
+```
+
+`enable_csp_emission!` mounts `Otto::Security::CSP::EmitMiddleware`, a passive
+**backstop**:
+
+- **Emit-if-consumed** (default): it emits a policy only for a response whose
+  request actually consumed a nonce (a view called `req.csp_nonce`). A nonce-only
+  `script-src` on an HTML page that never stamped the nonce would block every
+  script, so "CSP responses whose request consumed a nonce" is the only safe
+  blanket default. Pass `eager: true` to mint-and-emit for every eligible HTML
+  response (see the caveat in the middleware docs).
+- **Never clobbers**: it defers to any CSP a route already set.
+- **HTML only**, and inert unless `enable_csp_with_nonce!` is on.
+- `development_mode:` accepts a per-request callable, e.g.
+  `->(env) { ENV['RACK_ENV'] == 'development' }`, to switch directive sets.
+
+To set a policy explicitly from a handler instead, use the one emission helper —
+it routes through the same apply core:
+
+```ruby
+res['content-type'] = 'text/html; charset=utf-8'
+result = res.apply_csp(req.csp_nonce)          # mode: :override by default
+result.applied?        # => true
+result.skip_reason     # => nil (or :disabled / :blank_nonce / :non_html / :existing_csp)
+```
+
+Apps with an existing nonce env-key convention can point the accessor at it with
+`app.security_config.csp_nonce_key = 'onetime.nonce'` — the views and the header
+still share one value.
+
+> [!NOTE]
+> `res.send_csp_headers(content_type, nonce)` is **deprecated** in favour of
+> `res.apply_csp` / `enable_csp_emission!`. It remains as a thin shim over the
+> same apply core (so its old quirks — a broken `'nonce-'` on a blank nonce, a
+> CSP on non-HTML responses, a `warn` to stderr — are now fixed) and logs a
+> one-time deprecation notice.
+
 ### CSP Violation Reporting
 
 Otto can both emit Content-Security-Policy headers and receive the violation

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
 # ========================================

data/examples/lambda_handlers/README.md

@@ -0,0 +1,128 @@
+# Otto - Lambda / Inline Route Handlers
+
+This example demonstrates Otto's fourth route-handler kind (issue #41):
+**lambda handlers**. A lambda handler is a plain proc, pre-registered by name,
+that a route can target with an `&` prefix.
+
+## What You'll Learn
+
+- Registering lambda handlers at `Otto.new` construction time
+- The `&handler_name` route syntax
+- Returning strings, Hashes (JSON), and mutating the response directly
+- Applying route options (`response=json`, `csrf=exempt`) to lambdas
+- Why this is safe: no `eval`, no dynamic code from route files
+
+## The Four Handler Kinds
+
+| Route target    | Kind        | Resolves to             |
+|-----------------|-------------|-------------------------|
+| `App.index`     | `:class`    | class method            |
+| `App#index`     | `:instance` | instance method         |
+| `BareClass`     | `:logic`    | Logic object            |
+| `&health_check` | `:lambda`   | pre-registered proc     |
+
+## Registration
+
+Lambdas are supplied to Otto as a `name => callable` Hash. Otto validates each
+entry (must respond to `#call`, must accept 3 arguments) and freezes the
+registry:
+
+```ruby
+require_relative '../../lib/otto'
+require_relative 'handlers'
+
+app = Otto.new('routes', {
+  lambda_handlers: LambdaHandlers::REGISTRY,
+})
+```
+
+Each handler receives `(req, res, extra_params)`:
+
+```ruby
+HEALTH_CHECK = lambda do |req, res, extra_params|
+  res.headers['content-type'] = 'text/plain; charset=utf-8'
+  res.body = 'OK'
+end
+```
+
+## Route Syntax
+
+Prefix the target with `&` and give the registered name. Everything after the
+`&` is the exact registry key. The target comes first; route options follow it:
+
+```
+GET   /ping           &health_check
+GET   /status         &status    response=json
+GET   /greet/:name    &greet     response=json
+POST  /webhook        &webhook   csrf=exempt response=json
+```
+
+## Response Types
+
+Lambdas participate in Otto's normal response-type dispatch, the same way a
+class/instance/logic handler does:
+
+- **Default** (no `response=`): the handler mutates `res` directly — set
+  `res.status` / `res.headers` / `res.body`. The return value is ignored, so
+  writing `res.body` is what produces output.
+- **`response=json`**: the returned Hash is serialized as JSON and the JSON
+  content-type is set for you.
+
+## Route Options
+
+Route options apply to lambdas just like any other handler:
+
+- `response=json` — serialize the returned Hash as JSON.
+- `csrf=exempt` — parsed and exposed on the route definition (intended to mark
+  the webhook, which external callers reach without a browser token). Note:
+  `CSRFMiddleware` does not yet consult per-route options, so this option is
+  currently recorded but not enforced — see issue #186.
+- `auth=` / `role=` — authentication and authorization (when `auth_config`
+  is configured on the Otto instance).
+
+## Security
+
+The `&` syntax performs an O(1) lookup of a **pre-registered** proc by name.
+Route files never contain Ruby code and are never `eval`'d. A route naming a
+handler that was not registered raises a clear error instead of executing
+anything.
+
+## How to Run
+
+```sh
+cd examples/lambda_handlers
+rackup config.ru -p 10780
+```
+
+Then, from another terminal:
+
+```sh
+curl localhost:10780/ping
+# OK
+
+curl localhost:10780/status
+# {"service":"otto-lambda-demo","status":"healthy","time":"..."}
+
+curl localhost:10780/greet/otto
+# {"greeting":"Hello, otto!"}
+
+curl -X POST --data 'hello' localhost:10780/webhook
+# {"received":true,"bytes":5}
+```
+
+## File Structure
+
+- `README.md`: This file.
+- `handlers.rb`: Defines the lambda procs and the `REGISTRY` Hash.
+- `routes`: Maps URLs to lambdas using the `&` syntax.
+- `config.ru`: Rack config that registers the lambdas with `Otto.new`.
+
+## Next Steps
+
+- Explore [Advanced Routes](../advanced_routes/) for class/instance/logic
+  handlers and response-type negotiation.
+- See [Security Features](../security_features/) for CSRF and input validation.
+
+## Further Reading
+
+- [docs/ADVANCED_ROUTES.txt](../../docs/ADVANCED_ROUTES.txt)

data/examples/lambda_handlers/config.ru

@@ -0,0 +1,26 @@
+# examples/lambda_handlers/config.ru
+#
+# Usage:
+#
+#     $ rackup config.ru -p 10780
+#
+# then, in another terminal:
+#
+#     $ curl localhost:10780/ping
+#     $ curl localhost:10780/status
+#     $ curl localhost:10780/greet/otto
+#     $ curl -X POST --data 'hello' localhost:10780/webhook
+
+require_relative '../../lib/otto'
+require_relative 'handlers'
+
+# Register the lambda handlers at construction time. Only names present in
+# this Hash can be referenced from the routes file's '&' syntax. Otto
+# validates every entry here (must respond to #call, arity of 3) and freezes
+# the registry — a route naming an unknown handler fails loudly rather than
+# executing anything.
+app = Otto.new('routes', {
+  lambda_handlers: LambdaHandlers::REGISTRY,
+})
+
+run app

data/examples/lambda_handlers/handlers.rb

@@ -0,0 +1,75 @@
+# examples/lambda_handlers/handlers.rb
+#
+# frozen_string_literal: true
+
+# Pre-registered lambda route handlers (Otto issue #41).
+#
+# A lambda handler is any object responding to #call that accepts exactly
+# three arguments: (req, res, extra_params).
+#
+#   * req          - the Rack::Request for this request
+#   * res          - the Rack::Response to populate
+#   * extra_params - a Hash of route/path params merged by Otto
+#
+# These procs are handed to Otto at construction time via the
+# `lambda_handlers:` option (see config.ru). Each is looked up O(1) by name
+# from the route file's `&handler_name` syntax. Nothing in the route file is
+# ever eval'd — only names present in this registry can be invoked, and an
+# unknown name fails loudly instead of executing arbitrary code.
+#
+# How the response is produced depends on the route's `response=` option,
+# exactly like the class/instance/logic handler kinds:
+#
+#   * default (no `response=`) -> the handler mutates `res` directly
+#     (status/headers/body); the return value is ignored.
+#   * `response=json`          -> the returned Hash is serialized to JSON.
+module LambdaHandlers
+  # A minimal string responder. With no `response=` option the default response
+  # handler leaves the body alone, so (like a class handler) we write it here.
+  HEALTH_CHECK = lambda do |_req, res, _extra|
+    res.headers['content-type'] = 'text/plain; charset=utf-8'
+    res.body = 'OK'
+  end
+
+  # A Hash responder. Pair it with `response=json` on the route and Otto's
+  # JSON response handler serializes the Hash and sets the JSON content-type.
+  STATUS = lambda do |_req, _res, _extra|
+    {
+      service: 'otto-lambda-demo',
+      status: 'healthy',
+      time: Time.now.utc.iso8601,
+    }
+  end
+
+  # A handler that reads merged params. Path/query params arrive in
+  # `extra_params`; request params are available through `req`.
+  GREET = lambda do |req, _res, extra|
+    name = extra['name'] || req.params['name'] || 'world'
+    { greeting: "Hello, #{name}!" }
+  end
+
+  # A webhook-style POST handler. The matching route declares `csrf=exempt`,
+  # intended to let external callers (which cannot present a CSRF token) reach
+  # it. Note: CSRFMiddleware does not yet honor per-route csrf=exempt (issue
+  # #186), so the option is currently advisory. When enforcement lands, exempt
+  # CSRF only for endpoints authenticated another way (signature header, shared
+  # secret, etc.).
+  WEBHOOK = lambda do |req, _res, _extra|
+    # Rewind first: upstream middleware may already have read the input stream.
+    req.body.rewind if req.body.respond_to?(:rewind)
+    payload = req.body.read.to_s
+    # NOTE: this route uses `response=json`, so Otto's JSON response handler
+    # owns the status (200) and content-type. Setting them here would be
+    # overridden, so we only return the Hash to be serialized.
+    { received: true, bytes: payload.bytesize }
+  end
+
+  # The registry passed to Otto.new(lambda_handlers: ...). Keys are the names
+  # referenced after '&' in the routes file.
+  REGISTRY = {
+    'health_check' => HEALTH_CHECK,
+    'status'       => STATUS,
+    'greet'        => GREET,
+    'webhook'      => WEBHOOK,
+  }.freeze
+end

data/examples/lambda_handlers/routes

@@ -0,0 +1,28 @@
+# examples/lambda_handlers/routes
+
+# OTTO - LAMBDA / INLINE ROUTE HANDLERS (issue #41)
+#
+# A route target prefixed with '&' names a pre-registered lambda handler
+# instead of a class/method. The name after '&' is looked up O(1) from the
+# lambda_handlers registry supplied to Otto.new -- never eval'd.
+#
+# The target comes first; route options follow it.
+#
+# Compare the four handler kinds:
+#   App.index      -> :class    (class method)
+#   App#index      -> :instance (instance method)
+#   BareClass      -> :logic    (Logic object)
+#   &health_check  -> :lambda   (pre-registered proc)   <-- this file
+
+# Plain-text string responder (default response handler).
+GET   /ping           &health_check
+
+# Hash responder serialized as JSON.
+GET   /status         &status    response=json
+
+# Reads a path param, returned as JSON.
+GET   /greet/:name    &greet     response=json
+
+# Webhook receiver: marked csrf=exempt (option is parsed/exposed but not yet
+# enforced by CSRFMiddleware -- see issue #186).
+POST  /webhook        &webhook   csrf=exempt response=json