otto 2.10.0 → 2.12.0

data/lib/otto/utils.rb

@@ -45,6 +45,14 @@ class Otto
     # fallback scan cannot drift.
     RELAY_MARKER_HEADERS = (FORWARDED_FOR_HEADERS + FORWARDED_AUTHORITY_HEADERS).uniq.freeze
 
+    # Headers the client-IP resolver may read an address from: the
+    # forwarded-for family (the CIDR walk, and X-Forwarded-For in depth mode)
+    # and RFC 7239 Forwarded (depth mode with trusted_proxy_header 'Forwarded'
+    # or 'Both'). A header resolve_client_ip starts reading belongs here, so
+    # that IPPrivacyMiddleware deletes it when no client IP resolves and
+    # Otto::Testing.env_for refuses it in a request it builds as direct.
+    CLIENT_ADDRESS_HEADERS = (FORWARDED_FOR_HEADERS + %w[HTTP_FORWARDED]).freeze
+
     # Special-use IPv4/IPv6 ranges that IPAddr's #private?/#loopback?/#link_local?
     # predicates do not cover but that should still be treated as non-public
     # (e.g. when picking the real client out of a forwarded chain).
@@ -100,20 +108,21 @@ class Otto
     # scrub invalid/undefined bytes, and strip a single trailing slash.
     #
     # This is the SINGLE SOURCE OF TRUTH shared by the router
-    # (Otto::Core::Router#handle_request, which compares the result against its
-    # literal-route table) and Otto::CaddyTLS::LocalhostGuard (which compares it
-    # against the guarded endpoint). The two MUST normalize identically: if a
-    # crafted path — a trailing slash, a percent-encoded byte, an invalid UTF-8
-    # byte — normalized differently in the guard than in the router, the router
-    # could dispatch a request the guard let through, bypassing the loopback
-    # check. One implementation makes that drift impossible.
-    #
-    # Mirrors the empty-path handling and :replace scrubbing the router applies.
-    # Robust to invalid input: Rack::Utils.unescape raises ArgumentError on an
-    # already-invalid byte sequence (a raw \xFF in the path), so that is caught
-    # and the raw string is scrubbed instead — a percent-encoded invalid byte
-    # (%FF) decodes to the same invalid byte and is scrubbed identically, so the
-    # two crafted forms normalize alike. The method itself does not raise.
+    # (Otto::Core::Router#handle_request, through #routing_path) and every guard
+    # that compares a request path or a configured path against what the router
+    # dispatches (Otto::CaddyTLS::LocalhostGuard, Otto::MCP.endpoint_path?).
+    # For a request, call #routing_path rather than passing PATH_INFO here
+    # yourself. Guard and router MUST normalize identically: if a crafted
+    # path — a trailing slash, a percent-encoded byte, an invalid UTF-8 byte —
+    # normalized differently in the guard than in the router, the router could
+    # dispatch a request the guard let through. One implementation makes that
+    # drift impossible.
+    #
+    # Robust to invalid input. Rack::Utils.unescape raises ArgumentError on a
+    # malformed escape (%zz, a trailing %) and on an invalid byte in a
+    # UTF-8-tagged string (a raw \xFF); either way the raw string is kept.
+    # Invalid UTF-8 is scrubbed after that, so a raw \xFF and a percent-encoded
+    # %FF normalize alike. The method itself does not raise.
     #
     # @param raw_path [String, nil] a raw PATH_INFO or a configured endpoint
     # @return [String] normalized path suitable for exact literal comparison
@@ -131,6 +140,46 @@ class Otto
         .gsub(%r{/$}, '')
     end
 
+    # The path Otto's router matches for this request. Use it in any code that
+    # judges a request by its path before the router sees it: guards,
+    # throttles, session skips, audit filters.
+    #
+    # The router does not match raw PATH_INFO. It matches this value, and
+    # Otto::Core::Router#handle_request calls this method to get it, so a guard
+    # that reads routing_path sees the path the router dispatches on. A guard
+    # that reads anything else can see a different path, and when it matches
+    # less than the router does the difference is a bypass: GET /%63olonel is
+    # '/%63olonel' as raw PATH_INFO and '/colonel' to the router.
+    #
+    # By default the result is mount-relative. Rack::URLMap
+    # (`map '/api' { run otto }`) moves the mount prefix into SCRIPT_NAME and
+    # leaves the remainder in PATH_INFO, which is all the router sees; this is
+    # the form to compare against paths as written in a routes file.
+    #
+    # With +include_mount: true+ SCRIPT_NAME and PATH_INFO are joined and then
+    # normalized as one string, giving the request's full path. That is
+    # the form for middleware shared by several mounted apps and configured
+    # with external URLs: inside an app mounted at /api/v2, '/status' is the
+    # mount-relative path and '/api/v2/status' the mounted one, and matching
+    # the mount-relative form would also match every other app's /status.
+    #
+    # The value is normalize_path output, so root is '' (the router's literal
+    # table keys root the same way) and a configured path must go through
+    # normalize_path before an exact comparison. Never raises: a malformed
+    # escape such as %zz is kept as written.
+    #
+    # Not memoized: middleware may rewrite PATH_INFO or SCRIPT_NAME, and the
+    # router must see the value as it stands at dispatch.
+    #
+    # @param env [Hash] Rack environment
+    # @param include_mount [Boolean] prepend SCRIPT_NAME (the mount prefix)
+    # @return [String] normalized path
+    def routing_path(env, include_mount: false)
+      path = env['PATH_INFO']
+      path = "#{env['SCRIPT_NAME']}#{path}" if include_mount
+      normalize_path(path)
+    end
+
     # Validate and normalize an IP address (IPv4 and IPv6).
     #
     # Strips an optional port (IPv6-safe), validates with IPAddr, and returns

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.10.0'
+  VERSION = '2.12.0'
 end

data/lib/otto.rb

@@ -55,6 +55,7 @@ require_relative 'otto/logging_helpers'
 class Otto
   include Otto::Core::Router
   include Otto::Core::FileSafety
+  include Otto::Core::StaticMounts
   include Otto::Core::Configuration
   include Otto::Core::ErrorHandler
   include Otto::Core::UriGenerator
@@ -68,6 +69,10 @@ class Otto
 
   LIB_HOME = __dir__ unless defined?(Otto::LIB_HOME)
 
+  # Parameter types (from Proc#parameters / Method#parameters) that consume
+  # one positional argument each. See {#fallback_call_args}.
+  POSITIONAL_PARAMETER_TYPES = %i[req opt].freeze
+
   @debug = case ENV.fetch('OTTO_DEBUG', nil)
            in 'true' | '1' | 'yes' | 'on'
              true
@@ -80,8 +85,54 @@ class Otto
               :routes_by_definition, :option,
               :static_route, :security_config, :locale_config, :auth_config,
               :route_handler_factory, :mcp_server, :caddy_tls_server, :security, :middleware,
-              :error_handlers, :request_class, :response_class
-  attr_accessor :not_found, :server_error
+              :error_handlers, :request_class, :response_class,
+              :not_found, :server_error
+
+  # Configure the response returned when no route (and no +/404+ route) matches.
+  #
+  # Accepts either a Rack triple +[status, headers, body]+ (the body must
+  # respond to +each+, or +call+ for a streaming body) or anything that
+  # responds to +call(env)+ and returns one. A static triple is never handed
+  # back to the Rack stack by reference: Otto returns a per-request copy whose
+  # headers (and Array-valued header entries, and Array body) are fresh
+  # containers, so cookie middleware such as rack-session or Otto's own CSRF
+  # middleware cannot accumulate +Set-Cookie+ values on the configured object
+  # and replay them to later clients. Prefer the callable form when the
+  # response should vary per request.
+  #
+  # @param response [Array, #call, nil] a Rack triple, a callable, or nil to
+  #   restore the built-in {Otto::Static.not_found} response
+  # @raise [ArgumentError] when +response+ is neither a Rack triple nor callable
+  #
+  # @example Static triple (copied per request)
+  #   otto.not_found = [404, { 'content-type' => 'application/json' }, ['{"error":"Not Found"}']]
+  #
+  # @example Callable, built fresh on every miss
+  #   otto.not_found = ->(env) { [404, { 'content-type' => 'text/plain' }, ["No #{env['PATH_INFO']}"]] }
+  def not_found=(response)
+    @not_found = validate_fallback_response!(:not_found, response)
+  end
+
+  # Configure the response returned for an unhandled error when no +/500+
+  # route is configured and the client does not prefer JSON.
+  #
+  # Accepts either a Rack triple or anything that responds to +call(env, error)+
+  # and returns one; a callable declaring a single positional parameter (or
+  # none) receives only what it declares. +env['otto.error_id']+ carries the
+  # logged correlation id. As with {#not_found=}, a static triple is copied
+  # per request so header writes by cookie middleware never touch the
+  # configured object. A callable that raises is logged and replaced by the
+  # built-in secure error response.
+  #
+  # @param response [Array, #call, nil] a Rack triple, a callable, or nil to
+  #   restore the built-in secure error response
+  # @raise [ArgumentError] when +response+ is neither a Rack triple nor callable
+  #
+  # @example Callable receiving the error
+  #   otto.server_error = ->(env, error) { [500, { 'content-type' => 'text/plain' }, ['Oops']] }
+  def server_error=(response)
+    @server_error = validate_fallback_response!(:server_error, response)
+  end
 
   def initialize(path = nil, opts = {})
     constructed = false
@@ -188,6 +239,10 @@ class Otto
     # so reverse lookups (Otto#uri) consult this index instead of the
     # single-route @route_definitions entry (issue #190).
     @routes_by_definition = {}
+    # Explicit static mounts (Core::StaticMounts#mount_static). Always a
+    # frozen snapshot, replaced wholesale on registration; dispatch reads it
+    # without locking.
+    @static_mounts     = [].freeze
     @security_config   = Otto::Security::Config.new
     @middleware        = Otto::Core::MiddlewareStack.new
     # Initialize @auth_config first so it can be shared with the configurator
@@ -301,6 +356,75 @@ class Otto
     end
   end
 
+  # Validate a value assigned to {#not_found=} or {#server_error=}.
+  #
+  # @param name [Symbol] the setting name, for the error message
+  # @param response [Object] the assigned value
+  # @return [Array, #call, nil] the value, when acceptable
+  # @raise [ArgumentError] otherwise
+  def validate_fallback_response!(name, response)
+    return response if response.nil? || response.respond_to?(:call)
+    return response if rack_triple?(response)
+
+    raise ArgumentError,
+      "#{name} must be a Rack triple [status, headers, body] or respond to #call, got #{response.inspect}"
+  end
+
+  # A Rack triple: an Integer-like status, Hash-like headers, and a body that
+  # responds to +each+ (or +call+, for a streaming body).
+  def rack_triple?(response)
+    return false unless response.is_a?(Array) && response.length == 3
+
+    status, headers, body = response
+    status.respond_to?(:to_int) && headers.respond_to?(:each_pair) &&
+      (body.respond_to?(:each) || body.respond_to?(:call))
+  end
+
+  # Resolve a configured fallback into a fresh Rack triple for one request.
+  #
+  # A callable is invoked with as many of +args+ as it accepts (see
+  # {#fallback_call_args}); a static triple is used as-is. Either way the
+  # result is copied (see {Otto::Static.copy_response}) so the Rack stack
+  # never receives a container shared with the configuration or with another
+  # request. Configured security headers then fill any fields the fallback did
+  # not set explicitly.
+  #
+  # @param name [Symbol] the setting name, for the error message
+  # @param fallback [Array, #call] the configured value
+  # @param args [Array] positional arguments offered to a callable fallback
+  # @return [Array] a new Rack triple
+  # @raise [TypeError] when a callable returns something other than a Rack triple
+  def resolve_fallback_response(name, fallback, *args)
+    response = fallback.respond_to?(:call) ? fallback.call(*fallback_call_args(fallback, args)) : fallback
+    unless rack_triple?(response)
+      raise TypeError,
+        "#{name} callable must return a Rack triple [status, headers, body], got #{response.inspect}"
+    end
+
+    copied = Otto::Static.copy_response(response)
+    @security_config.security_headers.each_pair do |header, value|
+      copied[1][header] = value unless copied[1].key?(header)
+    end
+    copied
+  end
+
+  # Trim +args+ to the positional parameters +callable+ declares, so a lambda
+  # or Method that takes fewer (or optional) parameters is never handed an
+  # argument it would reject. A splat parameter receives everything. Arity
+  # alone cannot express this: +->(env = nil) {}+ has arity -1, the same as
+  # +proc { |*a| }+, yet accepts at most one argument.
+  #
+  # @param callable [#call]
+  # @param args [Array] the arguments on offer, in order
+  # @return [Array] the leading subset of +args+ the callable accepts
+  def fallback_call_args(callable, args)
+    params = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+    return args if params.any? { |type, _name| type == :rest }
+
+    args.first(params.count { |type, _name| POSITIONAL_PARAMETER_TYPES.include?(type) })
+  end
+  private :validate_fallback_response!, :rack_triple?, :resolve_fallback_response, :fallback_call_args
+
   # Class methods for Otto framework providing singleton access and configuration
   module ClassMethods
     def default

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.12.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -223,6 +223,7 @@ files:
 - lib/otto/core/middleware_management.rb
 - lib/otto/core/middleware_stack.rb
 - lib/otto/core/router.rb
+- lib/otto/core/static_mounts.rb
 - lib/otto/core/uri_generator.rb
 - lib/otto/design_system.rb
 - lib/otto/env_keys.rb
@@ -313,8 +314,10 @@ files:
 - lib/otto/security/middleware/validation_middleware.rb
 - lib/otto/security/rate_limiter.rb
 - lib/otto/security/rate_limiting.rb
+- lib/otto/security/trusted_proxy_config.rb
 - lib/otto/security/validator.rb
 - lib/otto/static.rb
+- lib/otto/testing.rb
 - lib/otto/utils.rb
 - lib/otto/version.rb
 - otto.gemspec