When should Active Storage serve files in proxy mode instead of redirect mode, and what does the proxy controller do differently?
answer
- resolve_model_to_route = :rails_storage_proxy
- rails_storage_proxy_path for one link
- app streams bytes with send_stream
- http_cache_forever public: true
- one byte range per request
basics
~20 sIn 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 sSet `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# config/initializers/active_storage.rb
Rails.application.config.active_storage.resolve_model_to_route = :rails_storage_proxygo deeper
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.
Explain the proxy controller's streaming, cache headers, disabled session and range handling, and contrast them with the redirect controller.
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.
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).