Update docs and changelog

CHANGELOG.md

@@ -3,6 +3,9 @@
 ## [Unreleased]
 ### Add
 - Add `IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION` config.
+- Add [Amazon CloudWatch](https://docs.imgproxy.net/latest/cloud_watch) support.
+- (pro) Add [`best` resultig image format](https://docs.imgproxy.net/latest/best_format).
+- (pro) Add `IMGPROXY_WEBP_COMPRESSION` config and [webp_options](https://docs.imgproxy.net/latest/generating_the_url?id=webp-options) processing option.
 
 ### Change
 - Change `IMGPROXY_FORMAT_QUALITY` default value to `avif=65`.
@@ -11,6 +14,9 @@
 - Set `Cache-Control: no-cache` header to the health check responses.
 - Allow replacing line breaks with `\n` in `IMGPROXY_OPEN_TELEMETRY_SERVER_CERT`, `IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT`, and`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`.
 
+### Fix
+- Fix 3GP video format detection.
+
 ## [3.11.0] - 2022-11-17
 ### Add
 - Add `IMGPROXY_OPEN_TELEMETRY_GRPC_INSECURE` config.
@@ -722,7 +728,7 @@ All-You-Ever-Wanted release! :tada:
 - [New advanced URL format](./docs/generating_the_url.md). Unleash the full power of imgproxy v2.0.
 - [Presets](./docs/presets.md). Shorten your urls by reusing processing options.
 - [Serving images from Amazon S3](./docs/serving_files_from_s3.md). Thanks to [@crohr](https://github.com/crohr), now we have a way to serve files from private S3 buckets.
-- [Autoconverting to WebP when supported by browser](./docs/configuration.md#webp-support-detection) (disabled by default). Use WebP as resulting format when browser supports it.
+- [Autoconverting to WebP when supported by browser](./docs/configuration.md#avifwebp-support-detection) (disabled by default). Use WebP as resulting format when browser supports it.
 - [Gaussian blur](./docs/generating_the_url.md#blur) and [sharpen](./docs/generating_the_url.md#sharpen) filters. Make your images look better than before.
 - [Focus point gravity](./docs/generating_the_url.md#gravity). Tell imgproxy what point will be the center of the image.
 - [Background color](./docs/generating_the_url.md#background). Control the color of background when converting PNG with alpha-channel to JPEG.

NOTICE

@@ -5043,6 +5043,36 @@ libpng
 
 ================================================================================
 
+libspng
+
+  BSD 2-Clause License
+
+  Copyright (c) 2018-2022, Randy <randy408@protonmail.com>
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================================
+
 zlib
 
   zlib.h -- interface of the 'zlib' general purpose compression library

docs/_sidebar.md

@@ -12,6 +12,7 @@
   * [Watermark](watermark)
   * [Object detection<img title="imgproxy Pro feature" src="/assets/pro.svg">](object_detection)
   * [Autoquality<img title="imgproxy Pro feature" src="/assets/pro.svg">](autoquality)
+  * [Best format<img title="imgproxy Pro feature" src="/assets/pro.svg">](best_format)
   * [Chained pipelines<img title="imgproxy Pro feature" src="/assets/pro.svg">](chained_pipelines)
 * Image sources
   * [Local files](serving_local_files)
@@ -24,6 +25,7 @@
   * [Prometheus](prometheus)
   * [Datadog](datadog)
   * [OpenTelemetry](open_telemetry)
+  * [Amazon CloudWatch](cloud_watch)
 * Miscellaneous
   * [Image formats support](image_formats_support)
   * [About processing pipeline](about_processing_pipeline)

docs/assets/docsify-init.js

@@ -43,7 +43,7 @@ window.$docsify = {
   repo: 'https://github.com/imgproxy',
   loadSidebar: true,
   relativePath: true,
-  subMaxLevel: 2,
+  subMaxLevel: 3,
   auto2top: true,
   routerMode: window.DOCSIFY_ROUTER_MODE || "hash",
   noEmoji: true,

docs/best_format.md

@@ -0,0 +1,18 @@
+# Best format![pro](/assets/pro.svg)
+
+You can use the `best` value for the [format](generating_the_url#format) option or the [extension](generating_the_url#extension) to make imgproxy pick the best format for the resultant image.
+
+imgproxy measures the complexity of the image to choose when it should use a lossless or near-lossless encoding. Then imgproxy tries to save the image in multiple formats to pick one with the smallest resulting size.
+
+**📝Note:** imgproxy uses only the formats listed as [preferred](configuration#preferred-formats) when choosing the best format. It may also use AVIF or WebP if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
+
+**📝Note:** imgproxy will use AVIF or WebP _only_ if [AVIF/WebP support detection](configuration#avifwebp-support-detection) is enabled.
+
+**📝Note:** imgproxy may change your quality and autoquality settings if the `best` format is used.
+
+## Configuration
+
+* `IMGPROXY_BEST_FORMAT_COMPLEXITY_THRESHOLD `: the image complexity threshold. imgproxy will use a lossless or near-lossless encoding for images with low complexity. Default: `5.5`
+* `IMGPROXY_BEST_FORMAT_MAX_RESOLUTION`: when greater than `0` and the image's resolution (in megapixels) is larger than the provided value, imgproxy won't try all the applicable formats and will just pick one that seems the best for the image
+* `IMGPROXY_BEST_FORMAT_BY_DEFAULT`: when `true` and the resulting image format is not specified explicitly, imgproxy will use the `best` format instead of the source image format
+* `IMGPROXY_BEST_FORMAT_ALLOW_SKIPS`: when `true` and the `best` format is used, imgproxy will skip processing of SVG and formats [listed to skip processing](configuration#skip-processing)

docs/cloud_watch.md

@@ -0,0 +1,55 @@
+# Amazon CloudWatch
+
+imgproxy can send its metrics to AmazonCloudFront. To use this feature, do the following:
+
+1. Set the `IMGPROXY_CLOUD_WATCH_SERVICE_NAME` environment variable. imgproxy will use the value of this variable as a value for the `ServiceName` dimension.
+2. [Set up the necessary credentials](#set-up-credentials) to grant access to CloudWatch.
+3. _(optional)_ Specify the AWS region with `IMGPROXY_CLOUD_WATCH_REGION` or `AWS_REGION`. Default: `us-west-1`
+4. _(optional)_ Set the `IMGPROXY_CLOUD_WATCH_NAMESPACE` environment variable to be the desired CloudWatch namespace. Default: `imgproxy`
+
+imgproxy sends the following metrics to CloudWatch:
+
+* `RequestsInProgress`: the number of requests currently in progress
+* `ImagesInProgress`: the number of images currently in progress
+* `ConcurrencyUtilization`: the percentage of imgproxy's concurrency utilization. Calculated as `RequestsInProgress / IMGPROXY_CONCURRENCY * 100`
+* `BufferSize`: a summary of the download buffers sizes (in bytes)
+* `BufferDefaultSize`: calibrated default buffer size (in bytes)
+* `BufferMaxSize`: calibrated maximum buffer size (in bytes)
+* `VipsMemory`: libvips memory usage (in bytes)
+* `VipsMaxMemory`: libvips maximum memory usage (in bytes)
+* `VipsAllocs`: the number of active vips allocations
+
+### Set up credentials
+
+There are three ways to specify your AWS credentials. The credentials need to have rights to write metrics to CloudWatch:
+
+#### IAM Roles
+
+If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to make calls to AWS CloudWatch.
+
+**Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html).
+**Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html).
+**Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html).
+
+#### Environment variables
+
+You can specify an AWS Access Key ID and a Secret Access Key by setting the standard `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.
+
+``` bash
+AWS_ACCESS_KEY_ID=my_access_key AWS_SECRET_ACCESS_KEY=my_secret_key imgproxy
+
+# same for Docker
+docker run -e AWS_ACCESS_KEY_ID=my_access_key -e AWS_SECRET_ACCESS_KEY=my_secret_key -it darthsim/imgproxy
+```
+
+This is the recommended method when using dockerized imgproxy.
+
+#### Shared credentials file
+
+Alternatively, you can create the `.aws/credentials` file in your home directory with the following content:
+
+```ini
+[default]
+aws_access_key_id = %access_key_id
+aws_secret_access_key = %secret_access_key
+```

docs/configuration.md

@@ -156,6 +156,10 @@ When cookie forwarding is activated, by default, imgproxy assumes the scope of t
 * `IMGPROXY_GIF_OPTIMIZE_FRAMES`: ![pro](/assets/pro.svg) when true, enables GIF frame optimization. This may produce a smaller result, but may increase compression time.
 * `IMGPROXY_GIF_OPTIMIZE_TRANSPARENCY`: ![pro](/assets/pro.svg) when true, enables GIF transparency optimization. This may produce a smaller result, but may also increase compression time. -->
 
+### Advanced WebP compression
+
+* `IMGPROXY_WEBP_COMPRESSION`: ![pro](/assets/pro.svg) the compression method to use. Supported values are `lossy`, `near_lossless`, and `lossless`. Default: `lossy`
+
 ### Advanced AVIF compression
 
 * `IMGPROXY_AVIF_SPEED`: controls the CPU effort spent improving compression. The lowest speed is at 0 and the fastest is at 8. Default: `8`
@@ -195,6 +199,43 @@ imgproxy can use the `Accept` HTTP header to detect if the browser supports AVIF
 
 **⚠️Warning:** Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the `Accept` HTTP headers. Keep this in mind when configuring your production caching setup.
 
+## Preferred formats
+
+When the resulting image format is not explicitly specified in the imgproxy URL via the extension or the `format` processing option, imgproxy will choose one of the preferred formats:
+
+* `IMGPROXY_PREFERRED_FORMATS`: a list of preferred formats, comma divided. Default: `jpeg,png,gif`
+
+imgproxy is guided by the following rules when choosing the resulting format:
+
+1. If the preferred formats list contains the source image format, it will be used
+2. If the resulting image is animated, the resulting image format should support animations
+3. If the resulting image contains transparency, the resulting image format should support transparency
+4. imgproxy chooses the first preferred format that meets those requirements
+5. If none of the preferred formats meet the requirements, the first preferred format is used
+
+**📝Note:** When AVIF/WebP support detection is enabled and the browser supports AVIF/WebP, it may be used as the resultant format even if the preferred formats list doesn't contain it.
+
+## Skip processing
+
+You can configure imgproxy to skip processing of some formats:
+
+* `IMGPROXY_SKIP_PROCESSING_FORMATS`: a list of formats that imgproxy shouldn't process, comma divided.
+
+**📝Note:** Processing can only be skipped when the requested format is the same as the source format.
+
+**📝Note:** Video thumbnail processing can't be skipped.
+
+## Best format
+
+You can use the `best` value for the [format](generating_the_url#format) option or the [extension](generating_the_url#extension) to make imgproxy pick the best format for the resultant image.
+
+* `IMGPROXY_BEST_FORMAT_COMPLEXITY_THRESHOLD `: ![pro](/assets/pro.svg) the image complexity threshold. imgproxy will use a lossless or near-lossless encoding for images with low complexity. Default: `5.5`
+* `IMGPROXY_BEST_FORMAT_MAX_RESOLUTION`: ![pro](/assets/pro.svg) when greater than `0` and the image's resolution (in megapixels) is larger than the provided value, imgproxy won't try all the applicable formats and will just pick one that seems the best for the image
+* `IMGPROXY_BEST_FORMAT_BY_DEFAULT`: ![pro](/assets/pro.svg) when `true` and the resulting image format is not specified explicitly, imgproxy will use the `best` format instead of the source image format
+* `IMGPROXY_BEST_FORMAT_ALLOW_SKIPS`: ![pro](/assets/pro.svg) when `true` and the `best` format is used, imgproxy will skip processing of SVG and formats [listed to skip processing](configuration#skip-processing)
+
+Check out the [Best format](best_format) guide to learn more.
+
 ## Client Hints support
 
 imgproxy can use the `Width`, `Viewport-Width` or `DPR` HTTP headers to determine default width and DPR options using Client Hints. This feature is disabled by default and can be enabled by the following option:
@@ -257,32 +298,6 @@ You can set up a fallback image that will be used in case imgproxy is unable to
 * `IMGPROXY_FALLBACK_IMAGE_TTL`: a duration (in seconds) sent via the `Expires` and `Cache-Control: max-age` HTTP headers when a fallback image was used. When blank or `0`, the value from `IMGPROXY_TTL` is used.
 * `IMGPROXY_FALLBACK_IMAGES_CACHE_SIZE`: ![pro](/assets/pro.svg) the size of custom fallback images cache. When set to `0`, the fallback image cache is disabled. 256 fallback images are cached by default.
 
-## Preferred formats
-
-When the resulting image format is not explicitly specified in the imgproxy URL via the extension or the `format` processing option, imgproxy will choose one of the preferred formats:
-
-* `IMGPROXY_PREFERRED_FORMATS`: a list of preferred formats, comma divided. Default: `jpeg,png,gif`
-
-imgproxy is guided by the following rules when choosing the resulting format:
-
-1. If the preferred formats list contains the source image format, it will be used
-2. If the resulting image is animated, the resulting image format should support animations
-3. If the resulting image contains transparency, the resulting image format should support transparency
-4. imgproxy chooses the first preferred format that meets those requirements
-5. If none of the preferred formats meet the requirements, the first preferred format is used
-
-**📝Note:** When AVIF/WebP support detection is enabled and the browser supports AVIF/WebP, it may be used as the resultant format even if the preferred formats list doesn't contain it.
-
-## Skip processing
-
-You can configure imgproxy to skip processing of some formats:
-
-* `IMGPROXY_SKIP_PROCESSING_FORMATS`: a list of formats that imgproxy shouldn't process, comma divided.
-
-**📝Note:** Processing can only be skipped when the requested format is the same as the source format.
-
-**📝Note:** Video thumbnail processing can't be skipped.
-
 ## Presets
 
 Read more about imgproxy presets in the [Presets](presets.md) guide.
@@ -317,7 +332,9 @@ imgproxy can be switched into "presets-only mode". In this mode, imgproxy accept
 
 * `IMGPROXY_ONLY_PRESETS`: disables all URL formats and enables presets-only mode.
 
-## Serving local files
+## Image sources
+
+### Local files :id=serving-local-files
 
 imgproxy can serve your local images, but this feature is disabled by default. To enable it, specify your local filesystem root:
 
@@ -325,7 +342,7 @@ imgproxy can serve your local images, but this feature is disabled by default. T
 
 Check out the [Serving local files](serving_local_files.md) guide to learn more.
 
-## Serving files from Amazon S3
+### Amazon S3 :id=serving-files-from-amazon-s3
 
 imgproxy can process files from Amazon S3 buckets, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_S3` to `true`:
 
@@ -334,7 +351,7 @@ imgproxy can process files from Amazon S3 buckets, but this feature is disabled
 
 Check out the [Serving files from S3](serving_files_from_s3.md) guide to learn more.
 
-## Serving files from Google Cloud Storage
+### Google Cloud Storage :id=serving-files-from-google-cloud-storage
 
 imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set the value of `IMGPROXY_USE_GCS` to `true`:
 
@@ -344,7 +361,7 @@ imgproxy can process files from Google Cloud Storage buckets, but this feature i
 
 Check out the [Serving files from Google Cloud Storage](serving_files_from_google_cloud_storage.md) guide to learn more.
 
-## Serving files from Azure Blob Storage
+### Azure Blob Storage :id=serving-files-from-azure-blob-storage
 
 imgproxy can process files from Azure Blob Storage containers, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_ABS` to `true`:
 
@@ -355,7 +372,8 @@ imgproxy can process files from Azure Blob Storage containers, but this feature
 
 Check out the [Serving files from Azure Blob Storage](serving_files_from_azure_blob_storage.md) guide to learn more.
 
-## Serving files from OpenStack Object Storage ("Swift")
+### OpenStack Object Storage ("Swift") :id=serving-files-from-openstack-object-storage-swift
+
 imgproxy can process files from OpenStack Object Storage, but this feature is disabled by default. To enable it, set `IMGPROXY_USE_SWIFT` to `true`.
 * `IMGPROXY_USE_SWIFT`: when `true`, enables image fetching from OpenStack Swift Object Storage. Default: `false`
 * `IMGPROXY_SWIFT_USERNAME`: the username for Swift API access. Default: blank
@@ -367,8 +385,11 @@ imgproxy can process files from OpenStack Object Storage, but this feature is di
 * `IMGRPOXY_SWIFT_TIMEOUT_SECONDS`: the data channel timeout in seconds. Default: 60
 * `IMGRPOXY_SWIFT_CONNECT_TIMEOUT_SECONDS`: the connect channel timeout in seconds. Default: 10
 
+Check out the [Serving files from OpenStack Object Storage](serving_files_from_openstack_swift.md) guide to learn more.
 
-## New Relic metrics
+## Metrics
+
+### New Relic :id=new-relic-metrics
 
 imgproxy can send its metrics to New Relic. Specify your New Relic license key to activate this feature:
 
@@ -378,7 +399,7 @@ imgproxy can send its metrics to New Relic. Specify your New Relic license key t
 
 Check out the [New Relic](new_relic.md) guide to learn more.
 
-## Prometheus metrics
+### Prometheus :id=prometheus-metrics
 
 imgproxy can collect its metrics for Prometheus. Specify a binding for Prometheus metrics server to activate this feature:
 
@@ -387,7 +408,7 @@ imgproxy can collect its metrics for Prometheus. Specify a binding for Prometheu
 
 Check out the [Prometheus](prometheus.md) guide to learn more.
 
-## Datadog metrics
+### Datadog :id=datadog-metrics
 
 imgproxy can send its metrics to Datadog:
 
@@ -398,7 +419,7 @@ imgproxy can send its metrics to Datadog:
 
 Check out the [Datadog](datadog.md) guide to learn more.
 
-## OpenTelemetry metrics
+### OpenTelemetry :id=opentelemetry-metrics
 
 imgproxy can send request traces to an OpenTelemetry collector:
 
@@ -416,21 +437,43 @@ imgproxy can send request traces to an OpenTelemetry collector:
 
 Check out the [OpenTelemetry](open_telemetry.md) guide to learn more.
 
+### Amazon CloudWatch metrics :id=amazon-cloudwatch-metrics
+
+imgproxy can send its metrics to Amazon CloudWatch. Specify a desired `ServiceName` dimesion value to activate this feature:
+
+* `IMGPROXY_CLOUD_WATCH_SERVICE_NAME`: the value of the `ServiceName` dimension which will be used in the metrics. Default: blank
+* `IMGPROXY_CLOUD_WATCH_NAMESPACE`: the CloudWatch namespace for the metrics
+* `IMGPROXY_CLOUD_WATCH_REGION`: the code of the AWS region to which the metrics should be sent
+
+Check out the [CloudWatch](cloud_watch.md) guide to learn more.
+
 ## Error reporting
 
 imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:
 
+* `IMGPROXY_REPORT_DOWNLOADING_ERRORS`: when `true`, imgproxy will report downloading errors. Default: `true`
+
+### Bugsnag
+
 * `IMGPROXY_BUGSNAG_KEY`: Bugsnag API key. When provided, enables error reporting to Bugsnag.
 * `IMGPROXY_BUGSNAG_STAGE`: the Bugsnag stage to report to. Default: `production`
+
+### Honeybadger
+
 * `IMGPROXY_HONEYBADGER_KEY`: the Honeybadger API key. When provided, enables error reporting to Honeybadger.
 * `IMGPROXY_HONEYBADGER_ENV`: the Honeybadger env to report to. Default: `production`
+
+### Sentry
+
 * `IMGPROXY_SENTRY_DSN`: Sentry project DSN. When provided, enables error reporting to Sentry.
 * `IMGPROXY_SENTRY_ENVIRONMENT`: the Sentry environment to report to. Default: `production`
 * `IMGPROXY_SENTRY_RELEASE`: the Sentry release to report to. Default: `imgproxy@{imgproxy version}`
+
+### Airbrake
+
 * `IMGPROXY_AIRBRAKE_PROJECT_ID`: an Airbrake project id
 * `IMGPROXY_AIRBRAKE_PROJECT_KEY`: an Airbrake project key
 * `IMGPROXY_AIRBRAKE_ENVIRONMENT`: the Airbrake environment to report to. Default: `production`
-* `IMGPROXY_REPORT_DOWNLOADING_ERRORS`: when `true`, imgproxy will report downloading errors. Default: `true`
 
 ## Log
 
@@ -456,7 +499,6 @@ imgproxy can send logs to syslog, but this feature is disabled by default. To en
 **⚠️Warning:** We highly recommended reading the [Memory usage tweaks](memory_usage_tweaks.md) guide before changing these settings.
 
 * `IMGPROXY_DOWNLOAD_BUFFER_SIZE`: the initial size (in bytes) of a single download buffer. When set to zero, initializes empty download buffers. Default: `0`
-* `IMGPROXY_GZIP_BUFFER_SIZE`: the initial size (in bytes) of a single GZip buffer. When zero, initializes empty GZip buffers. This makess sense only when GZip compression is enabled. Default: `0`
 * `IMGPROXY_FREE_MEMORY_INTERVAL`: the interval (in seconds) at which unused memory will be returned to the OS. Default: `10`
 * `IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD`: the number of buffers that should be returned to a pool before calibration. Default: `1024`
 

docs/datadog.md

@@ -34,7 +34,7 @@ When the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable is se
 
 * `imgproxy.requests_in_progress`: the number of requests currently in progress
 * `imgproxy.images_in_progress`: the number of images currently in progress
-* `imgproxy.buffer.size`: a histogram of the download/gzip buffers sizes (in bytes)
+* `imgproxy.buffer.size`: a histogram of the download buffers sizes (in bytes)
 * `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes)
 * `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes)
 * `imgproxy.vips.memory`: libvips memory usage (in bytes)

docs/generating_the_url.md

@@ -630,6 +630,15 @@ gifo:%optimize_frames:%optimize_transparency
 
 Allows redefining GIF saving options. All arguments have the same meaning as with the [Advanced GIF compression](configuration.md#advanced-gif-compression) configs. All arguments are optional and can be omitted. -->
 
+### WebP options![pro](/assets/pro.svg) :id=webp-options
+
+```
+webp_options:%compression
+webpo:%compression
+```
+
+Allows redefining WebP saving options. All arguments have the same meaning as with the [Advanced WebP compression](configuration.md#advanced-webp-compression) configs. All arguments are optional and can be omitted.
+
 ### Format
 
 ```
@@ -822,7 +831,11 @@ When using an encrypted source URL, you can specify the [extension](#extension)
 
 Extension specifies the format of the resulting image. Read more about image formats support [here](image_formats_support.md).
 
-The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use `jpg`. You also can [enable WebP support detection](configuration.md#webp-support-detection) to use it as the default resulting format when possible.
+The extension can be omitted. In this case, imgproxy will use the source image format as resulting one. If the source image format is not supported as the resulting image, imgproxy will use `jpg`. You also can [enable WebP support detection](configuration.md#avifwebp-support-detection) to use it as the default resulting format when possible.
+
+### Best format![pro](/assets/pro.svg)
+
+You can use the `best` value for the [format](generating_the_url#format) option or the [extension](generating_the_url#extension) to make imgproxy pick the best format for the resultant image. Check out the [Best format](best_format) guide to learn more.
 
 ## Example
 

docs/new_relic.md

@@ -20,7 +20,7 @@ Additionally, imgproxy sends the following metrics over [Metrics API](https://do
 
 * `imgproxy.requests_in_progress`: the number of requests currently in progress
 * `imgproxy.images_in_progress`: the number of images currently in progress
-* `imgproxy.buffer.size`: a summary of the download/gzip buffers sizes (in bytes)
+* `imgproxy.buffer.size`: a summary of the download buffers sizes (in bytes)
 * `imgproxy.buffer.default_size`: calibrated default buffer size (in bytes)
 * `imgproxy.buffer.max_size`: calibrated maximum buffer size (in bytes)
 * `imgproxy.vips.memory`: libvips memory usage (in bytes)

docs/prometheus.md

@@ -14,7 +14,7 @@ imgproxy will collect the following metrics:
 * `request_span_duration_seconds`: a histogram of the request latency (in seconds) separated by span (queue, downloading, processing)
 * `requests_in_progress`: the number of requests currently in progress
 * `images_in_progress`: the number of images currently in progress
-* `buffer_size_bytes`: a histogram of the download/gzip buffers sizes (in bytes)
+* `buffer_size_bytes`: a histogram of the download buffers sizes (in bytes)
 * `buffer_default_size_bytes`: calibrated default buffer size (in bytes)
 * `buffer_max_size_bytes`: calibrated maximum buffer size (in bytes)
 * `vips_memory_bytes`: libvips memory usage

docs/serving_files_from_s3.md

@@ -3,7 +3,7 @@
 imgproxy can process images from S3 buckets. To use this feature, do the following:
 
 1. Set the `IMGPROXY_USE_S3` environment variable to be `true`.
-2. [Set up the necessary credentials](#setup-credentials) to grant access to your bucket.
+2. [Set up the necessary credentials](#set-up-credentials) to grant access to your bucket.
 3. _(optional)_ Specify the AWS region with `IMGPROXY_S3_REGION` or `AWS_REGION`. Default: `us-west-1`
 4. _(optional)_ Specify the S3 endpoint with `IMGPROXY_S3_ENDPOINT`.
 5. Use `s3://%bucket_name/%file_key` as the source image URL.
@@ -16,7 +16,15 @@ s3://%bucket_name/%file_key?%version_id
 
 ### Set up credentials
 
-There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs.
+There are three ways to specify your AWS credentials. The credentials need to have read rights for all of the buckets given in the source URLs:
+
+#### IAM Roles
+
+If you're running imgproxy on an Amazon Web Services platform, you can use IAM roles to to get the security credentials to make calls to AWS S3.
+
+**Elastic Container Service (ECS):** Assign an [IAM role to a task](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html).
+**Elastic Kubernetes Service (EKS):** Assign a [service account to a pod](https://docs.aws.amazon.com/eks/latest/userguide/pod-configuration.html).
+**Elastic Beanstalk:** Assign an [IAM role to an instance](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/iam-instanceprofile.html).
 
 #### Environment variables
 
@@ -41,12 +49,6 @@ aws_access_key_id = %access_key_id
 aws_secret_access_key = %secret_access_key
 ```
 
-#### IAM Roles for Amazon EC2 Instances
-
-If you're running imgproxy on an Amazon EC2 instance, you can use the instance's [IAM role](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to get the security credentials to make calls to AWS S3.
-
-You can learn about credentials in the [Configuring the AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) guide.
-
 ## Minio
 
 [Minio](https://github.com/minio/minio) is an object storage server released under Apache License v2.0. It is compatible with Amazon S3, so it can be used with imgproxy.