Various fixes, addressed PR comments

gzigzigzeo · gzigzigzeo · commit 77cf5ae2ab9f · 2026-04-07T15:38:07.000+02:00
diff --git a/docs/cache/external.mdx b/docs/cache/external.mdx
@@ -14,7 +14,7 @@ Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache img
 
 * **Image optimization** - Disable CDN image optimization to avoid double-processing
 * **Compression** - In case your CDN supports conditional compression of SVG images, enable gzip/Brotli compression for bandwidth savings
-* **Include essential headers*** - It's strongly recommended to include `Accept` header in the cache key. If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers.
+* **Include essential headers*** - Include `Accept` header in the cache key if you're using [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection). If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers.
 * **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin if your CDN supports it.
 
 ## nginx caching
@@ -79,7 +79,7 @@ proxy_cache_key "$scheme$proxy_host$request_uri";
 proxy_cache_key "$scheme$proxy_host$request_uri$http_accept";
 ```
 
-3. Include Client Hints dimensions when width/DPR affects output:
+3. Include [Client Hints](../configuration/options.mdx#client-hints-support) dimensions when width/DPR affects output:
 
 ```nginx
 proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width";
@@ -89,7 +89,7 @@ Use the smallest key that still prevents collisions for your traffic profile.
 
 ### Key recommendations
 
-* Include `Accept` in the cache key if format negotiation is used.
+* Include `Accept` in the cache key if [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) is used.
 * Include DPR/width-related hints in the cache key if [Client Hints](../configuration/options.mdx#client-hints-support) are used to vary output.
 * Set long `inactive` timeout (30d) to keep popular images in cache.
 * Configure `proxy_cache_use_stale` for graceful degradation during origin issues.
@@ -200,8 +200,8 @@ sub vcl_deliver {
 ### Key recommendations
 
 * Use `sub vcl_hash` to customize cache key behavior.
-* Include `Accept` for format negotiation.
-* Include DPR/width-related headers when they can affect output (`DPR`, `Width`, `Sec-CH-DPR`, `Sec-CH-Width`).
+* Include `Accept` for [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection).
+* Include DPR/width-related headers when [Client Hints](../configuration/options.mdx#client-hints-support) support is enabled (`DPR`, `Width`, `Sec-CH-DPR`, `Sec-CH-Width`).
 * Set grace period (`beresp.grace`) for graceful error handling.
 * Monitor Varnish statistics with `varnishstat`.
 * Use tags for efficient cache purging: add `set beresp.http.Surrogate-Key = "images:product:123"` in `vcl_backend_response`.
diff --git a/docs/cache/internal.mdx b/docs/cache/internal.mdx
@@ -13,7 +13,7 @@ While putting a CDN in front of imgproxy is and will always be a best practice,
 
 ## Why use internal cache?
 
-The internal cache provides long-term persistent storage for processed images, unlike CDNs which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand.
+The internal cache provides long-term persistent storage for processed images, unlike CDNs, which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand by default.
 
 The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure.
 
diff --git a/docs/cache/internal/amazon_s3.mdx b/docs/cache/internal/amazon_s3.mdx
@@ -2,7 +2,7 @@
 description: Learn about how to configure Amazon S3 cache in imgproxy
 ---
 
-# Cache storage: Amazon S3
+# Internal cache: Amazon S3
 
 imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, do the following:
 
diff --git a/docs/cache/internal/azure_blob_storage.mdx b/docs/cache/internal/azure_blob_storage.mdx
@@ -2,7 +2,7 @@
 description: Learn about how to configure Azure Blob Storage cache in imgproxy
 ---
 
-# Cache storage: Azure Blob Storage
+# Internal cache: Azure Blob Storage
 
 imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, do the following:
 
diff --git a/docs/cache/internal/google_cloud_storage.mdx b/docs/cache/internal/google_cloud_storage.mdx
@@ -2,7 +2,7 @@
 description: Learn about how to configure Google Cloud Storage cache in imgproxy
 ---
 
-# Cache storage: Google Cloud Storage
+# Internal cache: Google Cloud Storage
 
 imgproxy can store cached images in Google Cloud Storage buckets. To use the GCS cache, do the following:
 
diff --git a/docs/cache/internal/local_filesystem.mdx b/docs/cache/internal/local_filesystem.mdx
@@ -2,7 +2,7 @@
 description: Learn about how to configure the local filesystem cache in imgproxy
 ---
 
-# Cache storage: Local filesystem
+# Internal cache: Local filesystem
 
 imgproxy can store cached images on the local filesystem. To use filesystem cache, do the following:
 
diff --git a/docs/cache/internal/openstack_swift.mdx b/docs/cache/internal/openstack_swift.mdx
@@ -2,7 +2,7 @@
 description: Learn about how to configure OpenStack Object Storage cache in imgproxy
 ---
 
-# Cache storage: OpenStack Object Storage ("Swift")
+# Internal cache: OpenStack Object Storage ("Swift")
 
 imgproxy can store cached images in OpenStack Object Storage, also known as Swift. To use Swift cache, do the following:
 
diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx
@@ -48,7 +48,7 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
 * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank
 * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version`
 * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false`
-* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank
+* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update the configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank
 * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false`
 * [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. By setting it to a specific datetime, you can make imgproxy treat all the images as if they were modified at least at that datetime. Default: blank
 * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum`
@@ -435,8 +435,8 @@ imgproxy can classify images by assigning them to predefined categories based on
   * `full`: normalize to [-1, 1] range
   * `imagenet`: normalize using ImageNet mean and standard deviation
 * [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are:
-  * `nchw`: channels first (PyTorch default)
   * `nhwc`: _(default)_ channels last (TensorFlow default)
+  * `nchw`: channels first (PyTorch default)
 
 Read the [Classification guide](../features/classification.mdx) for more info.
 
@@ -726,7 +726,7 @@ Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more.
 imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:
 
 * [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true`
-* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. Default: `false`
+* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. If the client does not `Accept: text/html`, imgproxy reponds with plain text error. Default: `false`
 
 ### Bugsnag
 
diff --git a/docs/features/classification.mdx b/docs/features/classification.mdx
@@ -596,8 +596,8 @@ You need to define the following config variables to enable object classificatio
   Default: `none`
 
 * [`IMGPROXY_CLASSIFICATION_LAYOUT`]: the data layout of the neural network input. Possible values:
-  * `nchw`: channels first (PyTorch default)
   * `nhwc`: channels last (TensorFlow default)
+  * `nchw`: channels first (PyTorch default)
 
   Default: `nhwc`
 
@@ -615,7 +615,7 @@ car
 
 ## Getting classification info
 
-Object classification is available via the info handler using the `co` (classify objects) endpoint. Fetch classification results by specifying the number of top classes to return:
+Object classification is available via the info handler using the `cl` (classify) endpoint. Fetch classification results by specifying the number of top classes to return:
 
 ```imgproxy_url
 .../info/cl:5/...
diff --git a/docs/image_formats_support.mdx b/docs/image_formats_support.mdx
@@ -104,5 +104,5 @@ The bit depth handling depends on the [IMGPROXY_PRESERVE_HDR](configuration/opti
 
 **When `IMGPROXY_PRESERVE_HDR` is disabled (default):**
 
-* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB)
+* High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB, RGB16 and scRGB become sRGB)
 * 8-bit images remain 8-bit
diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx
@@ -21,17 +21,15 @@ imgproxy will send the following info to New Relic:
 * Image processing time
 * Errors that occurred while downloading and processing an image
 
-Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales:
+Additionally, imgproxy sends the following metrics over [Metrics API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) as timescales (all metric names are prefixed with Custom/imgproxy/):
 
 * `workers`: the configured number of imgproxy workers
 * `requests_in_progress`: the number of requests currently in progress
 * `images_in_progress`: the number of images currently in progress
-* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `Custom/imgproxy/requests_in_progress / Custom/imgproxy/workers * 100`
+* `workers_utilization`: the percentage of imgproxy's workers utilization. Calculated as `requests_in_progress / workers * 100`
 * `buffer/size`: a summary of the download buffers sizes (in bytes)
 * `buffer/default_size`: calibrated default buffer size (in bytes)
 * `buffer/max_size`: calibrated maximum buffer size (in bytes)
 * `vips/memory`: libvips memory usage (in bytes)
 * `vips/max_memory`: libvips maximum memory usage (in bytes)
 * `vips/allocs`: the number of active vips allocations
-
-All metrics names are prefixed with `Custom/imgproxy/`.
