otto 2.10.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebb9d40d464e54cb0a25d0014dfa6868905e833c400701739d61463ae56b7265
-  data.tar.gz: f111ef655d58256cece33215fe05a7711c5f1bd0e06925c41e58b0e492f6dfb5
+  metadata.gz: d60f9cd87b0c935f8c79ecc1aae11f4b9880794d57b0ee5309c53baafcb84dcf
+  data.tar.gz: d92225f2ab02c1fbbd9c6ab745c27373aa6f11608f27067ec4485ca4f81878b2
 SHA512:
-  metadata.gz: c1381ef06000d127d7411f50e797dbf14720821873bc8f9b70e1e01a3a232fb7a8f2ebaee7e0ec4ed8a9d61dfc8cf8d67753de21702ef253dd42b4e1736949ea
-  data.tar.gz: 7105c5561be5e5f3cfe771b41cc1d576c0ede262cecc92347cc518cbdd0c57deaefca50a923a535661a47ac6a977a1171a6dab9cb3f9ff59ca993c5a1a2d326a
+  metadata.gz: cf10b7fdf1245e1dd64140ef3a57fc69f2a42197ede66812f02a89f80f291ff3759a7b5245487fd0e7948e4da6534534dbe9d753e0d15cf0ea57366da2c928da
+  data.tar.gz: cba8ac893ef636d0e978061304704018907bba315160405561f41592613a250a762ac1a0ebad7de675984101f711f44aabec8693ac3445e4e1e6d9b8f7ffd788

data/.github/workflows/ci.yml

@@ -74,7 +74,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         continue-on-error: ${{ matrix.experimental }}
         with:
           ruby-version: ${{ matrix.ruby }}

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@7b0b255830a1fab6e602658672acad11c12d841d # v1.0.226
         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@7b0b255830a1fab6e602658672acad11c12d841d # v1.0.226
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

data/.github/workflows/code-smells.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: 3.4
 
@@ -91,7 +91,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: 3.4
           bundler-cache: true

data/.github/workflows/release-gem.yml

@@ -139,7 +139,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           bundler-cache: true
           # Pinned to 3.3 (oldest non-experimental Ruby in the CI matrix).

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

@@ -46,7 +46,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+      - uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

data/.github/workflows/yardoc.yml

@@ -47,7 +47,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Ruby environment
-        uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0
+        uses: ruby/setup-ruby@984c0c890880bbf811283d6f09c4607c62d210a4 # v1.323.0
         with:
           ruby-version: '3.4'
           bundler-cache: true

data/.rubocop_todo.yml

@@ -412,10 +412,10 @@ Metrics/ModuleLength:
   Exclude:
     - 'lib/otto/design_system.rb'
 
-# Offense count: 4
+# Offense count: 6
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 11
+  Max: 7
 
 # Offense count: 46
 # Configuration parameters: AllowedMethods, AllowedPatterns.
@@ -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,138 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.12.0:
+
+2.12.0 — 2026-09-26
+===================
+
+Added
+-----
+
+- ``referrer_policy`` sets the Referrer-Policy header on routed responses,
+  static files, built-in 404 and 500 responses, and authentication failures.
+  Pass one W3C policy token to ``Otto.new`` or assign it before the first
+  request. A value a route handler sets on its own response is kept. See
+  ``docs/guides/testing-guide.md``. (#281)
+
+- Logic classes can declare a ``route_params:`` keyword on ``initialize`` to
+  receive the router's path captures separately from caller-supplied
+  parameters. (#285)
+
+- ``Otto::Utils.routing_path(env)`` returns the normalized path the router
+  matches, so middleware can judge a request by the same path the router
+  dispatches. ``include_mount: true`` includes ``SCRIPT_NAME``. See
+  ``docs/guides/routing.md``. (#288)
+
+- ``require 'otto/testing'`` adds test support for any test framework.
+  ``Otto::Testing.reset!`` clears Otto's process-global forwarding state
+  between tests. ``Otto::Testing.env_for`` and ``resolve_client_ip!`` build a
+  Rack env whose ``otto.client_ip`` and ``otto.ip_match`` are resolved by
+  ``IPPrivacyMiddleware``. See ``docs/guides/testing-guide.md``. (#287)
+
+- ``Otto::Security::Config#trusted_proxy_mode`` returns ``:filter``,
+  ``:depth``, ``:none``, or nil. (#148)
+
+Changed
+-------
+
+- A ``referrer-policy`` value set through ``security_headers`` is now
+  validated like ``referrer_policy``. An unknown token or a comma-separated
+  fallback list raises ``ArgumentError`` at configuration time, and the header
+  can no longer be removed from ``security_headers``. (#281)
+
+- Trusted-proxy state moved into a private
+  ``Otto::Security::TrustedProxyConfig``, and
+  ``Security::Configurator#configure`` now takes ``**options``. Public
+  methods, accepted keys, and behavior are unchanged. (#148)
+
+- The forwarding-family conflict error and the warning for a hand-set
+  ``otto.client_ip`` now name the ``Otto::Testing`` helper that addresses
+  each. ``Otto::Security::Config.reset_rack_forwarding_family_for_testing!``
+  remains for existing RSpec callers. (#287)
+
+Fixed
+-----
+
+- Requests whose ``PATH_INFO`` contains a malformed percent-escape (``%zz``)
+  or a raw invalid byte are now routed instead of answering 500. (#288)
+
+- The general rate-limit throttle now skips internal paths by the path the
+  router dispatches, so ``/%5Fmcp`` is skipped like ``/_mcp``. (#288)
+
+- ``Otto::Privacy::Config#profile=`` now sets both ``disabled`` and
+  ``mask_private_ips`` for every profile. Switching to ``:audit`` previously
+  left ``mask_private_ips`` unchanged, so a later ``enable!`` could restore
+  ``:anonymous`` instead of ``:masked``. (#286)
+
+- CSP violation reports now reach the receiver when Otto is mounted under a
+  sub-path. The receiver matches ``csp_report_uri`` against ``SCRIPT_NAME`` +
+  ``PATH_INFO``, so configure the site-absolute path including the mount
+  prefix, such as ``/api/csp-report`` under ``map '/api'``. A mount-relative
+  value no longer matches. Trailing-slash and percent-encoded spellings of
+  the report path are also matched. (#289)
+
+Security
+--------
+
+- JSON request bodies can no longer override path captures, query
+  parameters, or form fields in Logic class parameters; JSON keys now merge
+  below them. JSON bodies are no longer parsed for ``GET`` or ``HEAD``
+  requests. Before upgrading, check Logic classes that read a JSON body on
+  ``GET`` or expect a JSON key to replace a query or path value. (#285)
+
+Documentation
+-------------
+
+- ``docs/guides/routing.md`` covers matching request paths in middleware,
+  including apps mounted under a sub-path. ``docs/guides/testing-guide.md``
+  covers ``Otto::Testing`` and Referrer-Policy configuration. (#281, #287,
+  #288)
+
+AI Assistance
+-------------
+
+- The ``TrustedProxyConfig`` refactor was implemented with AI assistance and
+  checked against the previous release by a differential run of 1,620
+  trusted-proxy operation sequences and 29 ``configure`` calls, with no
+  difference in outcome. (#148)
+
+- ``Otto::Testing`` helpers, specs, and guide updates were written with AI
+  assistance. The reset was also exercised without RSpec, under Tryouts and
+  Minitest. (#287)
+
+.. _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

@@ -19,7 +19,7 @@ end
 group :development, :test, optional: true do
   # Keep gems that need to be in both environments
   gem 'json_schemer', '~> 2.0'
-  gem 'maxmind-db', '~> 1.2' # Optional geo DB reader; exercised by geo specs
+  gem 'maxmind-db', '~> 1.5' # Optional geo DB reader; exercised by geo specs
   gem 'rack-attack', '~> 6.7'
   gem 'reek', '~> 6.5'
 end
@@ -29,7 +29,7 @@ group :development do
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
   gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.90.0', require: false
+  gem 'rubocop', '~> 1.91.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.10.0)
+    otto (2.12.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -57,7 +57,7 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.21.2)
+    json (3.0.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -71,7 +71,7 @@ GEM
     loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    maxmind-db (1.4.0)
+    maxmind-db (1.5.0)
     minitest (5.26.0)
     nokogiri (1.19.4-aarch64-linux-gnu)
       racc (~> 1.4)
@@ -144,7 +144,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.90.0)
+    rubocop (1.91.0)
       json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -166,9 +166,9 @@ GEM
       lint_roller (~> 1.1)
       regexp_parser (>= 2.0)
       rubocop (~> 1.86, >= 1.86.2)
-    rubocop-thread_safety (0.7.3)
+    rubocop-thread_safety (0.8.0)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (~> 1.89)
       rubocop-ast (>= 1.44.0, < 2.0)
     ruby-lsp (0.26.11)
       language_server-protocol (~> 3.17.0)
@@ -215,7 +215,7 @@ DEPENDENCIES
   debug
   json_schemer (~> 2.0)
   kramdown
-  maxmind-db (~> 1.2)
+  maxmind-db (~> 1.5)
   otto!
   rack-attack (~> 6.7)
   rack-test
@@ -223,7 +223,7 @@ DEPENDENCIES
   rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.90.0)
+  rubocop (~> 1.91.0)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/README.md

@@ -278,6 +278,12 @@ middleware, so browsers can POST reports without a CSRF token — regardless of
 order you enable security features in. A throwing callback can never break the
 receiver; it still answers `204`.
 
+The report path is the site-absolute path the browser POSTs to. When Otto is
+mounted under a sub-path (`map '/api' { run otto }`), include the prefix:
+`enable_csp_reporting!("/api/_/csp-report")`. The receiver matches it against
+`SCRIPT_NAME` + `PATH_INFO`, so the same value works in the header and in the
+receiver.
+
 Modern browsers (Chrome) have deprecated `report-uri` in favour of the Reporting
 API. Pass `endpoint_url:` — an **absolute** URL whose path is the report path —
 to also emit a `report-to` directive and a `Reporting-Endpoints` response header,

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/forwarded-authority.md

@@ -190,10 +190,14 @@ process that both resolve proxied requests must agree. The later one raises:
 Cannot use forwarding family %s (trusted_proxy_header) because another Otto
 application in this process already uses %s. Rack's forwarded host, port,
 scheme, and IP policy is process-global, so every Otto application in one
-process that resolves proxied requests must use the same forwarding family.
+process that resolves proxied requests must use the same forwarding family. A
+test suite that builds applications with different families must clear this
+between tests: require 'otto/testing' and call Otto::Testing.reset!.
 ```
 
 The two placeholders are the requested family and the already committed one.
+See [Testing Otto applications](testing-guide.md#reset-ottos-process-global-state-between-tests)
+for the reset.
 
 An application that configures no proxy trust, and one that asserts
 `trusted_proxies: :none`, read no forwarded chain and therefore stake no claim

data/docs/guides/privacy.md

@@ -154,6 +154,11 @@ the closure.
 allowed = req.env.fetch('otto.ip_match').call(['192.0.2.0/24', '2001:db8::/32'])
 ```
 
+In tests, build the env with `Otto::Testing.env_for` rather than writing
+`otto.client_ip` by hand; a hand-written value leaves `otto.ip_match` denying
+every range. See
+[Testing Otto applications](testing-guide.md#hand-a-harness-a-resolved-client-ip).
+
 ## Middleware placement
 
 When building a larger Rack stack, put privacy before components that log or

data/docs/guides/routing.md

@@ -142,11 +142,31 @@ GET /products/:id  Products::Show
 
 A handler can read `req.params[:id]` or a Logic class can read `params[:id]`.
 Request query and body parameters are merged according to the handler's request
-contract. JSON bodies are parsed for Logic-class parameters when the content
-type is JSON and the body is a JSON object. A valid non-object JSON body is
-ignored. Malformed JSON is logged and the Logic class still runs with its other
-parameters; perform application validation when malformed JSON must return a
-client error.
+contract. Path captures are merged on top, so a caller cannot replace the value
+the router matched by repeating the key in the query string or body. Between
+the query string and a form body, Rack's own order applies (the form body
+wins). For Logic classes a JSON body sits below all of those.
+
+A Logic class that must not confuse a path value with a caller-supplied one
+can take the captures separately by declaring a `route_params:` keyword:
+
+```ruby
+class Receipts::Show
+  def initialize(strategy_result, params, locale, route_params: {})
+    @identifier = route_params[:identifier] # only ever the path value
+    @params = params
+  end
+end
+```
+
+The keyword is optional; the three-argument constructor keeps working. The same
+values remain in `params` for classes that do not declare it.
+
+JSON bodies are parsed for Logic-class parameters when the request method
+carries a body (never `GET` or `HEAD`), the content type is JSON, and the body
+is a JSON object. A valid non-object JSON body is ignored. Malformed JSON is
+logged and the Logic class still runs with its other parameters; perform
+application validation when malformed JSON must return a client error.
 
 ## Security options in routes
 
@@ -163,6 +183,161 @@ 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.
+
+## Matching request paths before the router
+
+The router does not match raw `PATH_INFO`. It percent-decodes it, scrubs
+invalid UTF-8, and strips one trailing slash, so `GET /%63olonel/` reaches the
+`/colonel` route. Middleware that decides on a request by its path (an access
+guard, a throttle, a session skip) must compare the same value. Otherwise a
+request can match a route without matching the guard in front of it, which
+on an access guard is a bypass.
+
+`Otto::Utils.routing_path(env)` returns that value. The router gets its path
+from the same method, so the two cannot drift:
+
+```ruby
+class AdminGuard
+  ADMIN = Otto::Utils.normalize_path('/colonel')
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    path = Otto::Utils.routing_path(env)
+    admin_path = path == ADMIN || path.start_with?("#{ADMIN}/")
+    return [404, {}, []] if admin_path && !allowed?(env) # allowed? is yours
+
+    @app.call(env)
+  end
+end
+```
+
+The result is mount-relative. When the app is mounted under a sub-path
+(`map '/api' { run otto }`), Rack moves the prefix into `SCRIPT_NAME` and the
+router sees only the rest. Compare that form against paths as written in the
+routes file. For middleware shared by several mounted apps and configured
+with external URLs, pass `include_mount: true` to get `SCRIPT_NAME` and
+`PATH_INFO` joined and normalized as one path: inside an app mounted at
+`/api/v2`, the router's `/status` is `/api/v2/status`, and matching the
+mount-relative form would also match every other app's `/status`.
+
+The value uses `normalize_path` conventions: root is `''`, and a configured
+path must go through `Otto::Utils.normalize_path` before an exact comparison.
+A malformed escape such as `%zz` is kept as written; the method never raises.
+
+## 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: