otto 2.9.0 → 2.11.0

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
@@ -76,14 +81,61 @@ class Otto
            end
   @logger = Logger.new($stdout, Logger::INFO)
 
-  attr_reader :routes, :routes_literal, :routes_static, :route_definitions,
+  attr_reader :routes, :routes_literal, :route_definitions,
               :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
     initialize_core_state
     initialize_options(path, opts)
     initialize_configurations(opts)
@@ -106,6 +158,13 @@ class Otto
     # but before processing requests.
     @freeze_mutex = Mutex.new
     @configuration_frozen = false
+    constructed = true
+  ensure
+    # A config that committed to a forwarding family during configure_security
+    # is held process-wide; withdraw it if construction failed afterwards
+    # (e.g. a bad routes path), or the dead app would keep vetoing other
+    # families for the life of the process.
+    Otto::Security::Config.release_rack_forwarding_family!(@security_config) if @security_config && !constructed
   end
   alias options option
 
@@ -172,16 +231,6 @@ class Otto
   private
 
   def initialize_core_state
-    # The GET cache is a Concurrent::Map, not a plain Hash: lazy static-file
-    # discovery (Core::Router#handle_request, Core::FileSafety#add_static_path)
-    # writes into it at request time, after freeze_configuration! has already
-    # deep-frozen the rest of the routing state. Deep-freezing this cache too
-    # would turn every as-yet-uncached static file request into a 500
-    # (FrozenError) in production (issue #185), so it is intentionally excluded
-    # from deep_freeze_value in Configuration#freeze_configuration! and kept as
-    # a structure that is both mutable post-freeze and safe under concurrent
-    # request threads.
-    @routes_static     = { GET: Concurrent::Map.new }
     @routes            = { GET: [] }
     @routes_literal    = { GET: {} }
     @route_definitions = {}
@@ -190,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
@@ -303,6 +356,70 @@ 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.
+  #
+  # @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
+
+    Otto::Static.copy_response(response)
+  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

data/otto.gemspec

@@ -34,8 +34,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'logger', '~> 1', '< 2.0'
 
   spec.add_dependency 'rack', '~> 3.1', '< 4.0'
-  spec.add_dependency 'rack-parser', '~> 0.7'
-  spec.add_dependency 'rexml', '~> 3.4'
 
   # Security dependencies
   spec.add_dependency 'loofah', '~> 2.20'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -70,34 +70,6 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: rack-parser
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: rexml
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: loofah
   requirement: !ruby/object:Gem::Requirement
@@ -144,18 +116,32 @@ files:
 - bin/rspec
 - changelog.d/README.md
 - changelog.d/scriv.ini
-- docs/.gitignore
-- docs/1108-STREAMING_ARCHITECTURE_ANALYSIS.md
-- docs/1108-STREAMING_SUPPORT_SUMMARY.md
-- docs/enrichment.md
-- docs/geo-country.md
-- docs/ipaddr-encoding-quirk.md
-- docs/migrating/v2.0.0-pre1.md
-- docs/migrating/v2.0.0-pre2.md
+- docs/README.md
+- docs/adr/README.md
+- docs/adr/adr-001-route-authentication-at-handler-boundary.md
+- docs/adr/adr-002-multi-strategy-authentication-and-authorization.md
+- docs/adr/adr-003-caddy-tls-route-based-integration.md
+- docs/adr/adr-004-separate-compatibility-from-security-maintenance.md
+- docs/guides/authentication.md
+- docs/guides/caddy-tls.md
+- docs/guides/configuration_freezing.md
+- docs/guides/enrichment.md
+- docs/guides/forwarded-authority.md
+- docs/guides/geo-country.md
+- docs/guides/ip_privacy.md
+- docs/guides/ipaddr-encoding-quirk.md
+- docs/guides/mcp.md
+- docs/guides/privacy.md
+- docs/guides/routing.md
+- docs/guides/structured_logging.md
+- docs/guides/testing-guide.md
+- docs/maintainers/github-actions.md
+- docs/maintainers/investigations/.gitignore
+- docs/migrating/v2.0.0.md
 - docs/migrating/v2.3.0.md
-- docs/modern-authentication-authorization-landscape.md
-- docs/multi-strategy-authentication-design.md
-- docs/reverse-proxy-network-services.md
+- docs/reference/authentication.md
+- docs/reference/route-syntax.md
+- docs/reference/runtime-and-dependency-security.md
 - examples/.gitignore
 - examples/advanced_routes/README.md
 - examples/advanced_routes/app.rb
@@ -237,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
@@ -251,12 +238,16 @@ files:
 - lib/otto/mcp.rb
 - lib/otto/mcp/auth/token.rb
 - lib/otto/mcp/core.rb
+- lib/otto/mcp/endpoint.rb
+- lib/otto/mcp/errors.rb
+- lib/otto/mcp/options.rb
 - lib/otto/mcp/protocol.rb
 - lib/otto/mcp/rate_limiting.rb
 - lib/otto/mcp/registry.rb
 - lib/otto/mcp/route_parser.rb
 - lib/otto/mcp/schema_validation.rb
 - lib/otto/mcp/server.rb
+- lib/otto/optional_dependency.rb
 - lib/otto/privacy.rb
 - lib/otto/privacy/anonymizer_resolver.rb
 - lib/otto/privacy/asn_resolver.rb

data/docs/.gitignore

@@ -1,10 +0,0 @@
-*
-!.gitignore
-!migrating/
-!migrating/*.md
-!ipaddr-encoding-quirk.md
-!enrichment.md
-!geo-country.md
-!modern-authentication-authorization-landscape.md
-!multi-strategy-authentication-design.md
-!reverse-proxy-network-services.md