skip to content

When should Active Storage serve files in proxy mode instead of redirect mode, and what does the proxy controller do differently?

level: middleimportance: should knowfreq 38%

answer

  1. resolve_model_to_route = :rails_storage_proxy
  2. rails_storage_proxy_path for one link
  3. app streams bytes with send_stream
  4. http_cache_forever public: true
  5. one byte range per request

basics

~20 s

In proxy mode the Rails app streams each file from storage to the browser under your own domain, with public cache-forever headers. Use it for a CDN in front of files; it costs app-server time per download.

solid answer

~40 s

Set `config.active_storage.resolve_model_to_route = :rails_storage_proxy` to make every `url_for`/`image_tag` use proxy routes, or call `rails_storage_proxy_path(photo)` for one link. Requests then hit `ActiveStorage::Blobs::ProxyController` (or `Representations::ProxyController` for variants), which streams the blob from the service through `send_stream` using `ActionController::Live`, sets `Cache-Control` to public, immutable and about 100 years via `http_cache_forever public: true`, skips the session cookie, and answers a single `Range` request with 206. You choose it when files must come from your own origin (a CDN in front, same-origin rules, a bucket you do not want exposed). The cost: each uncached download holds a Puma thread and an outbound connection for the whole transfer, so large or popular files need a CDN in front or redirect mode instead.

code

ruby · 2 lines
ruby
# config/initializers/active_storage.rb
Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxy

go deeper

for a junior

Recall that proxy mode serves files through the Rails app instead of redirecting to the storage service, and the setting or helper that turns it on.

for a middle

Explain the proxy controller's streaming, cache headers, disabled session and range handling, and contrast them with the redirect controller.

for a senior

Size the cost of proxying on Puma threads and bandwidth, decide which files to proxy, and keep public cache headers away from files that need authorization.

for a principal

Decide where file delivery belongs in the architecture (app, CDN or object store) given traffic, privacy requirements and operating cost.

## Two delivery modes Active Storage can deliver a file in two ways, and `config.active_storage.resolve_model_to_route` picks the default for every route helper: | | Redirect (`:rails_storage_redirect`, default) | Proxy (`:rails_storage_proxy`) | |---|---|---| | Route | `/rails/active_storage/blobs/redirect/...` | `/rails/active_storage/blobs/proxy/...` | | Controller | `ActiveStorage::Blobs::RedirectController` | `ActiveStorage::Blobs::ProxyController` | | Bytes travel | service to browser | service to Rails to browser | | Browser sees | your URL, then the bucket's URL | only your URL | | Response cache | `Cache-Control` for `service_urls_expire_in` (5 min) on the redirect | public, immutable, ~100 years on the file | | App cost per download | one short request | the whole transfer | Per-link helpers override the default: `rails_storage_proxy_path(photo)` / `rails_storage_proxy_url` and `rails_storage_redirect_path` / `rails_storage_redirect_url`. Variants have matching representation proxy and redirect routes. ## What the proxy controller does `ActiveStorage::Blobs::ProxyController#show`, in Rails 8.1: 1. Resolves the blob from the signed id (404 for a bad signature). 2. If the request has a `Range` header, reads just that chunk with `download_chunk` and answers **206 Partial Content**. Since the 8.1.2.1 security release only one range per request is accepted (`streaming_max_ranges` is 1) and the range must stay under `streaming_chunk_max_size`, 100 MB by default; anything else gets **416**. 3. Otherwise wraps the response in **`http_cache_forever public: true`**: `Cache-Control: max-age` of 100 years, `public`, `immutable`, plus an ETag from the request path, so a conditional request can be answered with 304. 4. Sets `Accept-Ranges` and `Content-Length`, then calls `send_blob_stream`, which uses `send_stream` from `ActionController::Live` to write chunks as `blob.download` yields them. The controller also includes `ActiveStorage::DisableSession`, so no session cookie is set on the response; a response carrying `Set-Cookie` would not be cached by most shared caches. Variants go through `ActiveStorage::Representations::ProxyController`, which first processes the variant if needed and then streams it with the same caching headers. ## When proxy mode is the right call - **A CDN in front of files.** The guide's recommended way to cache attachments on a CDN is proxy mode with URLs on the CDN host; the long public cache header means the CDN keeps the file and the app is hit once per URL. - **One origin.** Images used in a canvas, fetched by service workers or loaded where the bucket's domain is blocked are simpler from your own domain. - **Hiding storage details.** The bucket name and presigned URLs never reach the browser. - **Byte ranges from your origin.** Video seeking works through the single-range support. ## What it costs - **Thread time.** Each uncached request holds a Puma thread for the full download. A burst of large property-inspection photo downloads can exhaust a server with three threads per process. - **Bandwidth twice.** Bytes leave the bucket to the app server and then to the client. - **Public caching of private files.** The response says `public` for every proxied blob; without a CDN that respects your access rules, anyone who obtains the URL, or any shared cache on the path, may keep and serve the file. - **Timeouts.** Slow clients keep the stream open; front proxies and Puma timeouts must allow it. ## Choosing per file Many apps keep redirect mode as the default and proxy only selected files: ```erb <%= image_tag rails_storage_proxy_path(inspection.cover_photo.variant(resize_to_limit: [600, 400])) %> <%= link_to "Full report (PDF)", rails_blob_path(inspection.report, disposition: "attachment") %> ``` Small, frequently viewed images behind a CDN go through proxy URLs; large downloads, read once, go straight from the bucket via redirect. For files that need authorization on every access, neither built-in controller is enough; that calls for your own controller.

  • Why does a proxied response not set a session cookie?
    `ActiveStorage::Blobs::ProxyController` includes `ActiveStorage::DisableSession`, which turns off the session for the request. A response with `Set-Cookie` is usually not stored by shared caches, so skipping it lets a CDN cache the file, and it avoids leaking one user's session cookie into a cached response.
  • A video player sends Range: bytes=0-1000,5000-6000 to a proxy URL. What happens in Rails 8.1.4?
    The proxy controller answers 416 Range Not Satisfiable, because `streaming_max_ranges` allows one range per request since the 8.1.2.1 security release. A single range such as `bytes=5000-` is served with 206 and a `Content-Range` header, as long as it stays below `streaming_chunk_max_size`.

  • Proxy mode stores a copy of every file on the app server's disk
  • Proxy responses are private, so CDNs will not cache them without extra headers
  • Proxy mode is free for the app because files stream from storage in the background
  • Switching resolve_model_to_route moves files to a different storage service
  • In proxy mode the browser still receives a redirect to the bucket

Assumes Rails 8.1.4: since the 8.1.2.1 security release the proxy controller accepts one byte range per request, capped by streaming_chunk_max_size (100 MB).