otto 2.5.0 → 2.7.0

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

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

data/lib/otto/caddy_tls/localhost_guard.rb

@@ -2,8 +2,6 @@
 #
 # frozen_string_literal: true
 
-require 'ipaddr'
-
 require_relative '../utils'
 
 class Otto
@@ -22,11 +20,15 @@ class Otto
     #
     # == Security: authenticate the RAW peer, not the resolved client IP
     #
-    # The guard reads the ORIGINAL +env['REMOTE_ADDR']+ — the TCP socket peer —
-    # and MUST run before +IPPrivacyMiddleware+ rewrites +REMOTE_ADDR+ from
-    # forwarded headers. Installed via +Otto#use+ (appended, hence outermost in
-    # the reduce-built stack) it always executes ahead of +IPPrivacyMiddleware+
-    # (which is pinned innermost), so it inspects the true socket peer.
+    # The guard authenticates the TCP socket peer as it arrived, before
+    # +IPPrivacyMiddleware+ rewrites +REMOTE_ADDR+ from forwarded headers.
+    # +IPPrivacyMiddleware+ is pinned OUTERMOST (issue #219), so it runs ahead
+    # of this guard and records its verdict on the untouched peer as
+    # +env['otto.peer_loopback']+ — a boolean, never an address. The guard reads
+    # that record when present and falls back to evaluating +REMOTE_ADDR+
+    # itself when it is not (no Otto privacy middleware in the stack, or the
+    # guard mounted outside Otto). Either way the decision is made on the raw
+    # peer.
     #
     # Reading Otto's resolved +otto.client_ip+ (or the rewritten +REMOTE_ADDR+)
     # would be exploitable: a co-located reverse proxy on loopback is itself a
@@ -92,11 +94,28 @@ class Otto
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def direct_local_call?(env)
-        loopback_peer?(env['REMOTE_ADDR']) && !relayed?(env)
+        loopback_peer?(env) && !relayed?(env)
       end
 
       # Whether any forwarding header is present (request came via a proxy).
       #
+      # Unlike the peer check, this reads header STATE, which IPPrivacyMiddleware
+      # has already touched by the time the guard runs. That is safe in both of
+      # its paths, but only for a reason worth writing down:
+      #
+      # - Masking REWRITES a forwarded header to the masked IP rather than
+      #   removing it, so a relayed request still looks relayed. Correct — it was.
+      # - The no-resolvable-client-IP path DELETES them, which would make a
+      #   relayed request look direct. That path is reached only when REMOTE_ADDR
+      #   is absent or blank, which forces otto.peer_loopback to false, so
+      #   #direct_local_call? denies on the peer check before this one matters.
+      #
+      # So header deletion upstream cannot turn a deny into an allow — but that
+      # rests on the peer check failing closed for a blank address. Anything that
+      # makes an unresolvable-IP request keep a loopback peer verdict would need
+      # to record the relay state pre-scrub too (an otto.peer_relayed sibling to
+      # otto.peer_loopback).
+      #
       # @param env [Hash] Rack environment
       # @return [Boolean]
       def relayed?(env)
@@ -125,28 +144,27 @@ class Otto
         Otto::Utils.normalize_path(path)
       end
 
-      # Whether the connecting peer is a loopback address. Fails closed: a
-      # blank or otherwise unparseable value is treated as non-loopback
-      # (denied) rather than raising on the hot path.
+      # Whether the connecting peer is a loopback address.
       #
-      # +.native+ folds IPv4-mapped IPv6 (+::ffff:127.0.0.1+, which dual-stack
-      # servers commonly present) so it is correctly recognized as loopback;
-      # plain +IPAddr#loopback?+ returns false for the mapped form.
+      # Prefers +env['otto.peer_loopback']+ — IPPrivacyMiddleware's verdict on
+      # the ORIGINAL peer, recorded before it rewrites +REMOTE_ADDR+ (it runs
+      # outermost, so by the time this guard sees the env the address may
+      # already be the resolved-and-masked client IP). Only a real Boolean is
+      # honored; anything else falls through to evaluating +REMOTE_ADDR+, which
+      # is the correct source when no privacy middleware ran.
       #
-      # A conforming Rack server sets +REMOTE_ADDR+ to a bare IP (the peer's
-      # port lives in +REMOTE_PORT+). We deliberately do NOT strip a +:port+
-      # suffix here: an unexpected format is a signal something upstream is
-      # non-standard, so denying (fail-closed) is safer than coercing it.
+      # Both paths share +Otto::Utils.loopback_address?+, so the recorded
+      # verdict and the fallback cannot disagree. It fails closed: a blank,
+      # ported, or unparseable value is treated as non-loopback (denied) rather
+      # than raising on the hot path.
       #
-      # @param remote_addr [String, nil] the raw socket peer address
+      # @param env [Hash] Rack environment
       # @return [Boolean]
-      def loopback_peer?(remote_addr)
-        addr = remote_addr.to_s.strip
-        return false if addr.empty?
+      def loopback_peer?(env)
+        recorded = env['otto.peer_loopback']
+        return recorded if [true, false].include?(recorded)
 
-        IPAddr.new(addr).native.loopback?
-      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
-        false
+        Otto::Utils.loopback_address?(env['REMOTE_ADDR'])
       end
 
       # @return [Array] 401 Rack response tuple

data/lib/otto/core/configuration.rb

@@ -100,6 +100,98 @@ class Otto
         @mcp_server.enable!(mcp_options)
       end
 
+      # Validate and freeze the lambda handler registry supplied at construction
+      # (issue #41, AC#3). Security: only pre-registered callables are accepted;
+      # nothing from route files reaches here, so no eval / dynamic code (AC#8).
+      def configure_lambda_handlers(opts)
+        @option[:lambda_handlers] = validate_lambda_handlers!(opts[:lambda_handlers])
+      end
+
+      # @raise [ArgumentError] naming the offending handler on any invalid entry
+      # @return [Hash] frozen registry ({}.freeze when none supplied)
+      #
+      # Keys are normalized to Strings so lookups from +&name+ routes (whose
+      # target is always a String parsed from the route file) resolve regardless
+      # of whether the caller registered handlers under Symbol or String keys.
+      # A fresh Hash is built and frozen so the caller's input object is never
+      # mutated in place.
+      def validate_lambda_handlers!(handlers)
+        return {}.freeze if handlers.nil?
+
+        unless handlers.is_a?(Hash)
+          raise ArgumentError,
+                "Otto :lambda_handlers must be a Hash of name => callable, got #{handlers.class}"
+        end
+
+        registry = {}
+
+        handlers.each do |name, handler|
+          key = name.to_s
+          if key.strip.empty?
+            raise ArgumentError,
+                  "Lambda handler name #{name.inspect} is blank " \
+                  '(expected a non-empty name matching the &handler_name route target)'
+          end
+
+          if registry.key?(key)
+            raise ArgumentError,
+                  "Lambda handler name #{key.inspect} is registered more than once " \
+                  '(String and Symbol keys collide once normalized to a String)'
+          end
+
+          unless handler.respond_to?(:call)
+            raise ArgumentError,
+                  "Lambda handler '#{key}' is not callable (expected an object " \
+                  "responding to #call, got #{handler.class})"
+          end
+
+          unless lambda_handler_accepts_three?(handler)
+            raise ArgumentError,
+                  "Lambda handler '#{key}' has invalid arity " \
+                  '(must accept 3 arguments: req, res, extra_params)'
+          end
+
+          registry[key] = handler
+        end
+
+        registry.freeze
+      end
+
+      # True if +handler+ can be invoked with exactly three positional arguments.
+      #
+      # Reflects on the callable's #parameters rather than #arity so that:
+      #   * non-Proc/Method callables (a plain object with #call) are supported
+      #     without ever calling #arity, which they need not define (BUG A); and
+      #   * optional-arg forms that cannot actually take 3 positional args are
+      #     rejected instead of blanket-accepted by a negative arity (BUG B) --
+      #     e.g. ->(a=1){} (accepts 0..1) and ->(a,b=1){} (accepts 1..2).
+      #
+      # Accepts req/opt/rest combinations that admit 3 positionals; rejects
+      # anything requiring more than 3 or unable to reach 3.
+      #
+      # @api private
+      # @return [Boolean]
+      def lambda_handler_accepts_three?(handler)
+        callable =
+          if handler.is_a?(Proc) || handler.is_a?(Method)
+            handler
+          else
+            handler.method(:call)
+          end
+        params   = callable.parameters
+        required = params.count { |(type, _)| type == :req }
+        optional = params.count { |(type, _)| type == :opt }
+        has_rest = params.any?  { |(type, _)| type == :rest }
+
+        return false if required > 3
+
+        has_rest || (required + optional) >= 3
+      rescue NameError, NoMethodError
+        # A pathological callable whose #method(:call) reflection blows up still
+        # yields a clean, handler-named ArgumentError from the caller.
+        false
+      end
+
       # Configure locale settings for the application
       #
       # @param available_locales [Hash] Hash of available locales (e.g., { 'en' => 'English', 'es' => 'Spanish' })
@@ -190,8 +282,18 @@ class Otto
         # Deep freeze route structures (prevent modification of nested hashes/arrays)
         deep_freeze_value(@routes) if @routes
         deep_freeze_value(@routes_literal) if @routes_literal
-        deep_freeze_value(@routes_static) if @routes_static
+        # @routes_static is intentionally NOT deep-frozen: its :GET entry is a
+        # Concurrent::Map that lazy static-file discovery writes into at
+        # request time (Core::Router#handle_request, Core::FileSafety#add_static_path),
+        # after this method has already run. Deep-freezing it would turn the
+        # first request for any as-yet-uncached static file into a
+        # FrozenError / 500 in production (issue #185). The outer hash is
+        # still shallow-frozen so its verb-key structure (currently just
+        # :GET) can't be altered post-freeze, while the Concurrent::Map value
+        # stays writable.
+        @routes_static.freeze if @routes_static && !@routes_static.frozen?
         deep_freeze_value(@route_definitions) if @route_definitions
+        deep_freeze_value(@routes_by_definition) if @routes_by_definition
 
         @configuration_frozen = true