otto 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb9d40d464e54cb0a25d0014dfa6868905e833c400701739d61463ae56b7265
-  data.tar.gz: f111ef655d58256cece33215fe05a7711c5f1bd0e06925c41e58b0e492f6dfb5
+  metadata.gz: b8303453d265fcf2d5b0fa0754aafdbdb3e24eb89be9dc5a7b5611b4f2bcc699
+  data.tar.gz: 2081706f65a3475f95555d96547841691f906b015f8b012739abc7804923fc76
 SHA512:
-  metadata.gz: c1381ef06000d127d7411f50e797dbf14720821873bc8f9b70e1e01a3a232fb7a8f2ebaee7e0ec4ed8a9d61dfc8cf8d67753de21702ef253dd42b4e1736949ea
-  data.tar.gz: 7105c5561be5e5f3cfe771b41cc1d576c0ede262cecc92347cc518cbdd0c57deaefca50a923a535661a47ac6a977a1171a6dab9cb3f9ff59ca993c5a1a2d326a
+  metadata.gz: 75c496ee29c9c4ec0b05a8effda77e4e1dafc02080fb341a2320313011437f2b0bc0511ad6ca7d1b53928d6f75130693c974c72ed053aa35e5c6d16f60af0a5e
+  data.tar.gz: 9d9615efa73c7ebafafe7f7e1eb3e098f8c07f3200ac62882c52c39954087c73053fc9574beda1b1e11ecc836e0b9bacb70fe267c90fa92600531ef14fca1b63

data/.github/workflows/claude-code-review.yml

@@ -61,7 +61,7 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@d75b94d5ad426cb8546e6628b6f5f19b84e5cce1 # v1.0.216
+        uses: anthropics/claude-code-action@19dda84776b3518d98b8798e591daee763049ed3 # v1.0.220
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

data/.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@d75b94d5ad426cb8546e6628b6f5f19b84e5cce1 # v1.0.216
+        uses: anthropics/claude-code-action@19dda84776b3518d98b8798e591daee763049ed3 # v1.0.220
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

data/.rubocop_todo.yml

@@ -859,6 +859,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/otto/enhanced_routing_spec.rb'
     - 'spec/otto/error_handler_registration_spec.rb'
     - 'spec/otto/error_handling_spec.rb'
+    - 'spec/otto/fallback_response_isolation_spec.rb'
     - 'spec/otto/file_safety_spec.rb'
     - 'spec/otto/locale_config_spec.rb'
     - 'spec/otto/mcp/rate_limiting_spec.rb'

data/AGENTS.md

@@ -69,6 +69,24 @@ Helper modules should avoid overriding these methods inherited from Rack::Reques
 
 No runtime validation is performed for performance reasons. Overriding these methods will cause undefined behavior.
 
+## Static File Registration
+
+Files under the `public:` directory are served without registration. Use
+`mount_static` to bind a URL prefix to a directory outside it, or to verify a
+required asset directory at boot:
+
+```ruby
+otto = Otto.new('routes.txt', public: 'public')
+otto.mount_static('/assets', root: 'build/assets')
+```
+
+- Roots are canonicalized at registration; a missing or unsafe root raises `ArgumentError`
+- Precedence is fixed: literal routes, then mounts (longest prefix first), then `public:`, then dynamic routes
+- Must be registered before first request (before configuration freezing)
+- `add_static_path` was removed in v2.10.0 and has no shim
+
+See `docs/guides/routing.md` for the full contract.
+
 ## Authentication Architecture
 
 Authentication is handled by `RouteAuthWrapper` at the handler level, NOT by middleware.

data/CHANGELOG.rst

@@ -7,6 +7,38 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.11.0:
+
+2.11.0 — 2026-09-12
+===================
+
+Added
+-----
+
+- ``Otto#mount_static(prefix, root:)`` serves an explicit directory at a URL
+  prefix. See ``docs/guides/routing.md`` for configuration, dispatch
+  precedence, and migration from ``add_static_path``. (#267)
+
+- ``Otto#not_found=`` and ``Otto#server_error=`` now accept callables for
+  per-request fallback responses. A server-error callable can receive the
+  exception; see ``docs/guides/routing.md`` for the callback contract. (#272)
+
+Security
+--------
+
+- Static Rack triples configured with ``Otto#not_found=`` or
+  ``Otto#server_error=`` are now copied for each request, preventing in-place
+  header changes, including ``Set-Cookie``, from being shared between fallback
+  responses. (#272)
+
+Documentation
+-------------
+
+- Documented static-file dispatch precedence and migration from the removed
+  ``add_static_path`` API in ``docs/guides/routing.md``. Corrected stale
+  ``routes_static`` cache guidance in ``docs/guides/configuration_freezing.md``.
+  (#267)
+
 .. _changelog-2.10.0:
 
 2.10.0 — 2026-09-04

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.10.0)
+    otto (2.11.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)

data/docs/guides/configuration_freezing.md

@@ -51,15 +51,17 @@ otto.add_auth_strategy('other', MyApp::OtherStrategy.new)
 - the middleware stack;
 - authentication configuration and instance options;
 - dynamic and literal route tables;
-- route definitions and reverse-route indexes.
+- route definitions and reverse-route indexes;
+- the explicit static mount table (`mount_static`).
 
 Hashes and arrays inside those structures are recursively frozen. Configuration
 objects that implement `deep_freeze!` can prepare memoized values before they
 are frozen.
 
-The static-file route structure is an intentional exception. Its outer hash is
-frozen, but the `routes_static[:GET]` `Concurrent::Map` remains writable because
-Otto caches newly discovered static paths during requests.
+Static-file dispatch keeps no mutable routing state. Files under the implicit
+`public:` directory are resolved on each request against the current canonical
+root, and explicit mounts are an immutable snapshot from the moment they are
+registered; `mount_static` raises `FrozenError` after the freeze boundary.
 
 ## Scope and current limitations
 
@@ -69,8 +71,12 @@ some state that is not included in `freeze_configuration!`:
 
 - `error_handlers` remains a mutable Hash, although
   `register_error_handler` rejects calls after freezing;
-- the `not_found` and `server_error` fallback response writers remain available;
-- the inner static-file cache remains mutable by design.
+- the `not_found` and `server_error` fallback response writers remain
+  available. A configured static triple is never returned by reference:
+  Otto copies it per request, so header writes by cookie middleware do not
+  reach the configured object even though it is not frozen;
+- the `Rack::Files` instance for the implicit `public:` directory is rebuilt
+  when that directory is repointed between requests.
 
 Application code should not mutate those objects directly after boot. Do not
 state or depend on a guarantee that every object reachable from an Otto instance
@@ -86,6 +92,9 @@ otto.security_config.disable_csrf_protection!
 otto.add_trusted_proxy('192.0.2.10')
 otto.add_rate_limit_rule('uploads', limit: 5, period: 60)
 
+# Static mounts
+otto.mount_static('/assets', root: 'public/assets')
+
 # Middleware and authentication
 otto.use MyApp::OtherMiddleware
 otto.add_auth_strategy('other', MyApp::OtherStrategy.new)
@@ -144,3 +153,5 @@ first requests therefore do not run the freeze operation concurrently.
   freezing behavior.
 - [Configuration-freezing specs](../../spec/otto/configuration_freezing_spec.rb).
 - [Static-file freezing specs](../../spec/otto/static_file_freezing_spec.rb).
+- [Static mount specs](../../spec/otto/core/static_mounts_spec.rb) — registration
+  after the freeze boundary and serving from a frozen mount table.

data/docs/guides/routing.md

@@ -163,6 +163,118 @@ silently weakening the route. Do not use `csrf=exempt` as a general API switch;
 choose an independent request-authentication and replay-protection model for
 webhooks or other non-browser endpoints.
 
+## Static files
+
+Otto serves static files in two ways. Both apply the same safety policy: the
+requested path is joined to a canonical root, resolved with `File.realpath`
+(which follows every `..`, `.`, and symlink component), and served only when
+the result is still inside that root and is a regular, readable file owned by
+the process user or group. Anything else, including a symlink that points
+outside the root, is treated as not found.
+
+### Implicit public directory
+
+Passing `public:` serves every file under that directory at its relative path.
+Nothing needs registering; a file added after boot is served on the next
+request, and a symlinked public directory that is repointed by a deploy is
+re-resolved on every request.
+
+```ruby
+otto = Otto.new('routes', public: File.expand_path('public', __dir__))
+# public/css/site.css is served at GET /css/site.css
+```
+
+### Explicit static mounts
+
+`mount_static` binds one URL prefix to one directory. Use it when the files do
+not live under a single public directory, when a URL prefix should map to a
+different directory name, or when a required asset directory must be verified
+at boot.
+
+```ruby
+otto = Otto.new('routes')
+otto.mount_static('/assets', root: 'public/assets')
+otto.mount_static('/vendor', root: File.join(Gem.loaded_specs['some-ui-kit'].full_gem_path, 'dist'))
+otto.mount_static('/', root: 'public/root-files') # favicon.ico, robots.txt
+```
+
+- The prefix must start with `/`. A trailing slash is ignored, and `/`
+  mounts the root at the top level. Empty, `.`, and `..` segments are
+  rejected.
+- The root is expanded and canonicalized once, at registration. A root that
+  is missing, unreadable, not a directory, not owned by the process user or
+  group, or a symlink that cannot be resolved raises `ArgumentError`, so a
+  misconfigured application does not boot. Because the root is fixed at
+  registration, a deploy that repoints a symlinked root takes effect at the
+  next restart.
+- A mount authorizes only files inside its own root. It never exposes the
+  root's parent or siblings, and it does not widen the implicit public
+  directory. Registering the same prefix twice on one instance raises
+  `ArgumentError`; different Otto instances are fully independent.
+- Requests are matched on the decoded, trailing-slash-stripped path, the same
+  normalization every other dispatch stage uses. Only `GET` is served, the
+  prefix itself is not (mounts serve files, not directory listings), and a
+  request for a file the root does not contain falls through to the next
+  dispatch stage.
+- `mount_static` must be called before the first request. After configuration
+  freezing it raises `FrozenError`, and `otto.static_mounts` is a frozen,
+  read-only table.
+
+### Dispatch precedence
+
+Precedence is fixed and does not depend on request history:
+
+1. literal routes, such as `GET /assets/app.css Assets#show`;
+2. explicit static mounts, consulted longest prefix first; when the longest
+   matching mount does not contain the file, shorter matching mounts are tried
+   in turn;
+3. the implicit `public:` directory;
+4. dynamic routes, such as `GET /assets/:name Assets#show`.
+
+So a literal route at a mounted path always wins, a mounted file always beats
+a file at the same URL in the public directory, and a dynamic route only sees
+requests that no static source could serve.
+
+### Migrating from `add_static_path`
+
+`add_static_path` was removed in v2.10.0. It only populated a request-time
+cache; it never registered or restricted anything. Callers that used it to
+"register" files under the public directory can delete the call, because the
+public directory is served without registration. Callers that used it to reach
+files outside the public directory should replace it with `mount_static` and
+an explicit root. There is no compatibility shim: calling the removed method
+raises `NoMethodError` at boot.
+
+## Fallback 404 and 500 responses
+
+A `GET /404` or `GET /500` route in the routes file handles misses and
+unhandled errors like any other route. Without one, Otto uses `not_found=` and
+`server_error=`, which accept either a Rack triple or a callable:
+
+```ruby
+otto.not_found = [404, { 'content-type' => 'application/json' }, ['{"error":"Not Found"}']]
+
+otto.server_error = lambda do |env, error|
+  [500, { 'content-type' => 'text/plain' }, ["Error #{env['otto.error_id']}"]]
+end
+```
+
+A callable is invoked on every request with `env` (`not_found`) or `env` and
+the exception (`server_error`), trimmed to the positional parameters it
+declares, so `->(env) { ... }` and `->(env = nil) { ... }` both work for
+`server_error`. It must return a Rack triple: an Integer status, Hash-like
+headers, and a body that responds to `each` (a bare String is rejected, at
+assignment time for a static triple). A static triple is copied per request
+before it is returned, so middleware that writes response headers in place
+(rack-session, Otto's CSRF middleware, anything calling
+`Rack::Utils.set_cookie_header!`) never mutates the configured object or
+leaks one client's `Set-Cookie` into another's response. Do not rely on
+mutating the configured triple after boot; assign a new value or use the
+callable form instead.
+
+For JSON clients, an unhandled error returns Otto's built-in JSON error body
+regardless of `server_error`; a `/500` route applies to every client.
+
 ## Configuration timing
 
 Construct and configure the Otto instance before the first request:

data/lib/otto/core/configuration.rb

@@ -308,11 +308,14 @@ class Otto
         deep_freeze_value(@routes_literal) if @routes_literal
         deep_freeze_value(@route_definitions) if @route_definitions
         deep_freeze_value(@routes_by_definition) if @routes_by_definition
+        # Explicit static mounts are already immutable snapshots; freezing the
+        # array here records that fact and makes any in-place mutation raise.
+        deep_freeze_value(@static_mounts) if @static_mounts
 
         @configuration_frozen = true
 
         duration = Otto::Utils.now_in_μs - start_time
-        frozen_objects = %w[security_config locale_config middleware auth_config option routes]
+        frozen_objects = %w[security_config locale_config middleware auth_config option routes static_mounts]
         Otto.structured_log(:info, 'Freezing completed',
           {
                   duration: duration,

data/lib/otto/core/error_handler.rb

@@ -71,8 +71,8 @@ class Otto
         # Content negotiation for built-in error response
         return json_error_response(error_id) if wants_json_response?(env)
 
-        # Fallback to built-in error response
-        @server_error || secure_error_response(error_id)
+        # Fallback to the configured server_error response, else the built-in one
+        server_error_response(env, error, error_id)
       end
 
       # Register an error handler for expected business logic errors
@@ -268,6 +268,44 @@ class Otto
         end
       end
 
+      # Build the fallback 500 response for an unhandled error.
+      #
+      # A configured +server_error+ callable is invoked per request with
+      # +env+ and the original +error+, trimmed to the positional parameters
+      # it declares; +env+ carries +otto.error_id+ so the response can
+      # reference the logged error. A configured static triple is copied per
+      # request (see {Otto::Static.copy_response}) so header writes by cookie
+      # middleware cannot accumulate on the shared object. A callable that
+      # raises is logged and replaced by the built-in secure response,
+      # mirroring how a failing custom +/500+ route is handled.
+      #
+      # @param env [Hash] Rack environment
+      # @param error [Exception] the unhandled error
+      # @param error_id [String] correlation id already logged for +error+
+      # @return [Array] a fresh Rack triple
+      def server_error_response(env, error, error_id)
+        fallback = @server_error
+        return secure_error_response(error_id) if fallback.nil?
+
+        env['otto.error_id'] = error_id
+        resolve_fallback_response(:server_error, fallback, env, error)
+      rescue StandardError => e
+        fallback_error_id = SecureRandom.hex(8)
+        base_context = Otto::LoggingHelpers.request_context(env)
+
+        Otto.structured_log(:error, 'Error in server_error fallback',
+          base_context.merge(
+            error: e.message,
+            error_class: e.class.name,
+            error_id: fallback_error_id,
+            original_error_id: error_id
+          ))
+        Otto::LoggingHelpers.log_backtrace(e,
+          base_context.merge(error_id: fallback_error_id, original_error_id: error_id))
+
+        secure_error_response(error_id)
+      end
+
       def secure_error_response(error_id)
         body = if Otto.env?(:dev, :development)
                  "Server error (ID: #{error_id}). Check logs for details."

data/lib/otto/core/file_safety.rb

@@ -36,16 +36,32 @@ class Otto
       # callers never have to re-run realpath (one resolution per request).
       StaticFile = Struct.new(:root, :path, :relative)
 
-      # Resolve a request path to a canonical, contained, servable file.
+      # Resolve a request path to a canonical, contained, servable file under
+      # the implicit +public:+ directory.
       #
       # @param path [String, nil] request-relative path (may start with '/')
       # @return [StaticFile, nil] the validated file, or nil when unsafe
       def resolve_static_file(path)
         return nil if option[:public].nil? || option[:public].empty?
-        return nil if path.nil? || path.empty?
 
-        public_dir = canonical_public_dir
-        return nil if public_dir.nil?
+        resolve_file_under(canonical_public_dir, path)
+      end
+
+      # Resolve +path+ against an already-canonical +root+ and return it only
+      # when it is a contained, readable, owned regular file.
+      #
+      # Shared by the implicit public directory and explicit static mounts
+      # (Otto::Core::StaticMounts) so both apply one containment policy.
+      # +root+ must be a File.realpath result: containment compares canonical
+      # strings on a separator boundary, so a non-canonical root would never
+      # match the canonicalized candidate.
+      #
+      # @param root [String, nil] canonical directory
+      # @param path [String, nil] root-relative path (may start with '/')
+      # @return [StaticFile, nil] the validated file, or nil when unsafe
+      def resolve_file_under(root, path)
+        return nil if root.nil? || root.empty?
+        return nil if path.nil? || path.empty?
 
         # A NUL byte in a request path is never legitimate; it is a truncation
         # attack on downstream C string handling. Reject it rather than
@@ -57,18 +73,18 @@ class Otto
 
         # Join, then canonicalize: realpath resolves '..', '.' AND every
         # symlink component, so the containment check below cannot be fooled
-        # by a link that points outside the public directory.
-        candidate = File.join(public_dir, clean_path)
+        # by a link that points outside the root.
+        candidate = File.join(root, clean_path)
         real_path = safe_realpath(candidate)
         return nil if real_path.nil?
 
-        return nil unless contained?(real_path, public_dir)
+        return nil unless contained?(real_path, root)
 
         # Second gate: it must be a readable regular file we (or our group) own.
         return nil unless File.file?(real_path) && File.readable?(real_path)
         return nil unless File.owned?(real_path) || File.grpowned?(real_path)
 
-        StaticFile.new(public_dir, real_path, real_path.delete_prefix(public_dir + File::SEPARATOR))
+        StaticFile.new(root, real_path, real_path.delete_prefix(root + File::SEPARATOR))
       end
 
       def safe_file?(path)

data/lib/otto/core/router.rb

@@ -142,9 +142,12 @@ class Otto
 
         static_candidate = !static_route.nil? && http_verb == :GET
 
-        # Dispatch precedence is fixed: literal routes, then static files, then
-        # dynamic routes. Static-file requests always pass through containment
-        # validation before they are served (issues #257 and #260).
+        # Dispatch precedence is fixed: literal routes, then explicit static
+        # mounts (longest prefix first), then the implicit public directory,
+        # then dynamic routes. Every static-file request passes through
+        # containment validation before it is served (issues #257, #260 and
+        # #267). A mount or the public directory claims files, not paths: when
+        # the file is absent the request falls through to the next stage.
         if literal_routes.has_key?(path_info_clean)
           route = literal_routes[path_info_clean]
           Otto.structured_log(:debug, 'Route matched',
@@ -158,6 +161,13 @@ class Otto
             @route_matched_callbacks.each { |cb| cb.call(env, route.route_definition) }
           end
           route.call(env)
+        elsif http_verb == :GET && (mounted = resolve_mounted_file(dispatch_path))
+          mount, static_file = mounted
+          Otto.structured_log(:debug, 'Route matched',
+            Otto::LoggingHelpers.request_context(env).merge(
+              type: 'static_mount', prefix: mount.display_prefix
+            ))
+          serve_static_file(env, static_file, mount.files)
         elsif static_candidate && (static_file = resolve_static_file(dispatch_path))
           Otto.structured_log(:debug, 'Route matched',
             Otto::LoggingHelpers.request_context(env).merge(type: 'static'))
@@ -201,12 +211,16 @@ class Otto
       # Rack::Files could still redirect the open. Closing that requires an
       # O_NOFOLLOW-per-component or fd-based serve, i.e. replacing
       # Rack::Files. Accepted for now; see issue #257.
-      def serve_static_file(env, static_file)
+      #
+      # +files+ is the Rack::Files instance rooted at +static_file.root+: a
+      # mount's own frozen instance, or (by default) the public-directory one
+      # that #static_route_for keeps in step with the current root.
+      def serve_static_file(env, static_file, files = static_route_for(static_file.root))
         static_env = env.dup
         # Rack::Files unescapes PATH_INFO, so escape the canonical path to
         # survive the round trip (escape_path preserves '/').
         static_env['PATH_INFO'] = "/#{Rack::Utils.escape_path(static_file.relative)}"
-        static_route_for(static_file.root).call(static_env)
+        files.call(static_env)
       end
 
       # Rack::Files rooted at the root +static_file+ was validated against.
@@ -287,10 +301,29 @@ class Otto
             Otto::LoggingHelpers.request_context(env).merge(
               fallback_to: 'default_not_found'
             ))
-          @not_found || Otto::Static.not_found
+          not_found_response(env)
         end
       end
 
+      # Build the response for a request that matched no route and has no
+      # +/404+ route configured.
+      #
+      # A configured +not_found+ callable is invoked with +env+ on every miss.
+      # A configured static triple is copied per request (see
+      # {Otto::Static.copy_response}) so header writes by cookie middleware
+      # cannot accumulate on, or leak between requests through, the shared
+      # object. With nothing configured the built-in {Otto::Static.not_found}
+      # response is used.
+      #
+      # @param env [Hash] Rack environment
+      # @return [Array] a fresh Rack triple
+      def not_found_response(env)
+        fallback = @not_found
+        return Otto::Static.not_found if fallback.nil?
+
+        resolve_fallback_response(:not_found, fallback, env)
+      end
+
       def build_route_params(route, values)
         if route.keys.any?
           route.keys.zip(values).each_with_object({}) do |(k, v), hash|

data/lib/otto/core/static_mounts.rb

@@ -0,0 +1,172 @@
+# lib/otto/core/static_mounts.rb
+#
+# frozen_string_literal: true
+
+require 'rack/files'
+
+class Otto
+  module Core
+    # Explicit static-file registration (issue #267).
+    #
+    # A static mount binds a URL prefix to one directory on disk:
+    #
+    #   otto.mount_static('/assets', root: 'public/assets')
+    #
+    # Requests for GET /assets/<rest> are then resolved against
+    # public/assets/<rest> using the same containment policy as the implicit
+    # +public:+ directory (Otto::Core::FileSafety): the candidate is
+    # canonicalized with File.realpath and must land inside the mount's
+    # canonical root, be a regular readable file, and be owned by the process
+    # user or group. A mount never authorizes anything outside its own root,
+    # so several mounts can point into unrelated directories without exposing
+    # their parents or siblings.
+    #
+    # Registration is a boot-time operation. The root is canonicalized once,
+    # when the mount is registered, and every failure mode (missing,
+    # unreadable, not a directory, escaping symlink, malformed prefix,
+    # duplicate prefix) raises ArgumentError immediately so a misconfigured
+    # application does not start. Mounts participate in configuration
+    # freezing: mount_static raises FrozenError after freeze_configuration!,
+    # and the mount table is an immutable, sorted snapshot that dispatch reads
+    # without any per-request mutation.
+    #
+    # Dispatch precedence is fixed: literal routes, then static mounts (longest
+    # prefix first), then the implicit +public:+ directory, then dynamic
+    # routes. A mount claims files, not the prefix: when no mount root
+    # contains the requested file the request falls through to the next
+    # stage exactly as an unregistered path would. See Otto::Core::Router.
+    module StaticMounts
+      # One registered mount. +prefix+ is the normalized URL prefix ('' for a
+      # root mount), +root+ the canonical directory, +files+ the Rack::Files
+      # instance rooted there. Instances are frozen at construction.
+      StaticMount = Struct.new(:prefix, :root, :files) do
+        # Request-relative path under this mount, or nil when +path+ is not
+        # beneath the prefix. The prefix itself (the directory) never matches:
+        # a mount serves files, not directory listings.
+        #
+        # @param path [String] normalized dispatch path (leading '/')
+        # @return [String, nil]
+        def relative_path_for(path)
+          if prefix.empty?
+            path
+          elsif path.start_with?("#{prefix}/")
+            path[(prefix.length + 1)..]
+          end
+        end
+
+        # Prefix as an operator would write it ('/' for a root mount).
+        def display_prefix
+          prefix.empty? ? '/' : prefix
+        end
+      end
+
+      # Registered mounts, longest prefix first. Frozen snapshot; a new array
+      # replaces it on every registration so readers never observe a partial
+      # update.
+      #
+      # @return [Array<StaticMount>]
+      def static_mounts
+        @static_mounts
+      end
+
+      # Serve the files under +root+ at URLs beneath +prefix+.
+      #
+      # @param prefix [String] URL prefix starting with '/'. A trailing slash
+      #   is ignored; '/' mounts the root at the top level.
+      # @param root [String] directory path; relative paths resolve against
+      #   the process working directory and are canonicalized immediately.
+      # @return [StaticMount] the registered mount
+      # @raise [ArgumentError] on a malformed prefix, a duplicate prefix, or a
+      #   root that is missing, unreadable, not a directory, not owned by the
+      #   process user or group, or that cannot be canonicalized.
+      # @raise [FrozenError] after configuration freezing
+      def mount_static(prefix, root:)
+        ensure_not_frozen!
+
+        clean_prefix = normalize_mount_prefix(prefix)
+        if @static_mounts.any? { |mount| mount.prefix == clean_prefix }
+          raise ArgumentError,
+                "Static mount prefix #{display_mount_prefix(clean_prefix).inspect} is already registered"
+        end
+
+        canonical_root = canonicalize_mount_root(clean_prefix, root)
+        mount = StaticMount.new(clean_prefix, canonical_root, Rack::Files.new(canonical_root).freeze).freeze
+
+        # Longest prefix first so an overlay ('/assets/vendor') is consulted
+        # before the mount that contains it ('/assets'). Ties cannot happen:
+        # prefixes are unique. Rebuild rather than mutate so in-flight readers
+        # keep their snapshot.
+        @static_mounts = (@static_mounts + [mount]).sort_by { |m| -m.prefix.length }.freeze
+
+        Otto.structured_log(:debug, 'Static mount registered',
+          { prefix: mount.display_prefix, root: mount.root })
+        mount
+      end
+
+      private
+
+      # Resolve +path+ through the registered mounts, longest prefix first.
+      # Read-only: safe to call from concurrent request threads.
+      #
+      # @param path [String] normalized dispatch path (leading '/')
+      # @return [Array(StaticMount, Otto::Core::FileSafety::StaticFile), nil]
+      def resolve_mounted_file(path)
+        @static_mounts.each do |mount|
+          relative = mount.relative_path_for(path)
+          next if relative.nil?
+
+          static_file = resolve_file_under(mount.root, relative)
+          return [mount, static_file] if static_file
+        end
+        nil
+      end
+
+      # Validate and normalize a mount prefix. Returns '' for the root mount
+      # and a leading-slash, no-trailing-slash prefix otherwise, matching the
+      # normalized request path the router compares against.
+      def normalize_mount_prefix(prefix)
+        raise ArgumentError, "Static mount prefix must be a String, got #{prefix.class}" unless prefix.is_a?(String)
+        raise ArgumentError, "Static mount prefix #{prefix.inspect} contains a NUL byte" if prefix.include?("\0")
+        raise ArgumentError, "Static mount prefix #{prefix.inspect} must start with '/'" unless prefix.start_with?('/')
+
+        clean = prefix.sub(%r{/+\z}, '')
+        return '' if clean.empty?
+
+        segments = clean.split('/', -1).drop(1)
+        if segments.any? { |segment| segment.empty? || segment == '.' || segment == '..' }
+          raise ArgumentError,
+                "Static mount prefix #{prefix.inspect} must not contain empty, '.', or '..' segments"
+        end
+
+        clean.freeze
+      end
+
+      # Canonicalize a mount root under Otto's static-file safety policy and
+      # fail loudly on anything that could not be served safely.
+      def canonicalize_mount_root(prefix, root)
+        label = "Static mount #{display_mount_prefix(prefix).inspect}"
+        raise ArgumentError, "#{label} root must be a String, got #{root.class}" unless root.is_a?(String)
+        raise ArgumentError, "#{label} root must not be empty" if root.strip.empty?
+        raise ArgumentError, "#{label} root #{root.inspect} contains a NUL byte" if root.include?("\0")
+
+        real = safe_realpath(File.expand_path(root))
+        if real.nil?
+          raise ArgumentError,
+                "#{label} root #{root.inspect} cannot be resolved " \
+                '(missing, unreadable component, or symlink loop)'
+        end
+        raise ArgumentError, "#{label} root #{root.inspect} is not a directory" unless File.directory?(real)
+        raise ArgumentError, "#{label} root #{root.inspect} is not readable" unless File.readable?(real)
+
+        owned = File.owned?(real) || File.grpowned?(real)
+        raise ArgumentError, "#{label} root #{root.inspect} is not owned by the process user or group" unless owned
+
+        real.freeze
+      end
+
+      def display_mount_prefix(prefix)
+        prefix.empty? ? '/' : prefix
+      end
+    end
+  end
+end

data/lib/otto/core.rb

@@ -4,6 +4,7 @@
 
 require_relative 'core/router'
 require_relative 'core/file_safety'
+require_relative 'core/static_mounts'
 require_relative 'core/configuration'
 require_relative 'core/error_handler'
 require_relative 'core/uri_generator'

data/lib/otto/static.rb

@@ -15,6 +15,44 @@ class Otto
       [404, security_headers.merge({ 'content-type' => 'text/plain' }), ['Not Found']]
     end
 
+    # Return a per-request copy of a Rack triple so callers can never hand a
+    # shared object back to the Rack stack.
+    #
+    # Middleware above Otto (rack-session, Otto's own CSRF middleware, anything
+    # that calls +Rack::Utils.set_cookie_header!+) writes response headers in
+    # place. Returning a configured triple by reference lets those writes
+    # accumulate on the shared object for the life of the process, so every
+    # subsequent 404/500 replays every Set-Cookie any earlier one committed.
+    #
+    # The copy is intentionally shallow-plus-one: the headers container keeps
+    # its class (a +Rack::Headers+ stays case-insensitive), each Array-valued
+    # header (Rack 3's representation of a repeated header) is copied so an
+    # append cannot reach the shared Array, and an Array body is copied so a
+    # middleware appending chunks cannot grow the shared body. A frozen
+    # configured triple yields an unfrozen copy, so cookie middleware works
+    # after configuration freezing as well.
+    #
+    # @param response [Array] a Rack triple +[status, headers, body]+
+    # @return [Array] a new triple that shares no mutable container with +response+
+    def copy_response(response)
+      status, headers, body = response
+      [status, copy_headers(headers), body.is_a?(Array) ? body.dup : body]
+    end
+
+    # Copy a Rack headers container, keeping its class and copying Array values.
+    #
+    # @param headers [Hash, Rack::Headers, nil] the headers to copy
+    # @return [Hash, Rack::Headers] a new container of the same class
+    def copy_headers(headers)
+      return {} if headers.nil?
+
+      copied = headers.dup
+      copied.each_pair do |key, value|
+        copied[key] = value.dup if value.is_a?(Array)
+      end
+      copied
+    end
+
     def security_headers
       {
         'x-frame-options' => 'DENY',

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.10.0'
+  VERSION = '2.11.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,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Delano Mandelbaum
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-12 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