diff --git a/docs/cache/internal.mdx b/docs/cache/internal.mdx index 2c9ab15..777b3e7 100644 --- a/docs/cache/internal.mdx +++ b/docs/cache/internal.mdx @@ -27,6 +27,14 @@ You need to define the following config variables to enable the internal cache: * [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank * [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank * [`IMGPROXY_CACHE_REPORT_ERRORS`]: When `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` +* [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`]: _(optional)_ the maximum time imgproxy will wait for pending background cache writes to complete during a graceful shutdown. Default: `5s` +* [`IMGPROXY_CACHE_PROCESSING_ENABLED`]: _(optional)_ when `true`, imgproxy will cache processed images. Default: `true` +* [`IMGPROXY_CACHE_INFO_ENABLED`]: _(optional)_ when `true`, imgproxy will cache `/info` endpoint responses. Default: `true` +* [`IMGPROXY_CACHE_SOURCE_ENABLE`]: _(optional)_ when `true`, imgproxy caches downloaded source images in addition to processed results. Default: `false` + +### Source image caching + +In addition to caching processed results, imgproxy can cache the raw bytes of downloaded source images. Set `IMGPROXY_CACHE_SOURCE_ENABLE` to `true` to enable it. This is useful when you request the same source image with many different processing options. Instead of re-downloading the source for every variant, imgproxy fetches it once and serves subsequent requests from the cache. ### Storage configuration @@ -42,7 +50,7 @@ Configure the storage backend using `IMGPROXY_CACHE_*` variables: ## Cache key -The cache key is generated based on: +The cache key for processed images and `/info` responses is generated based on: * Source image URL * Processing options @@ -52,10 +60,43 @@ The cache key is generated based on: URL signature is **not** part of the cache key, allowing key rotation without invalidating the cache. +### Source cache key + +When [source image caching](#source-image-caching) is enabled, cached sources use their own separate key, based on: + +* Source image URL +* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS` +* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES` + +Unlike the processed-image cache key, it doesn’t include processing options or the output format because it stores the downloaded source image, not a processed variant. It also doesn’t include the [cachebuster](../usage/processing.mdx#cache-buster) value, so busting the processed-image cache doesn't invalidate the cached source. + +## Cache tags + +imgproxy Pro can attach cache tags to a cache entry using the [cache_tags](../usage/processing.mdx#cache-tags) processing option: + +```imgproxy_url_option +cache_tags:%tag1:%tag2:...:%tagN +ct:%tag1:%tag2:...:%tagN +``` + +Each tag can be up to 256 characters long and must consist of visible ASCII characters (character codes 33-126), excluding commas. We consider at most 50 tags per request; any beyond that are silently dropped. + +The tags are also written to the response headers, so a CDN in front of imgproxy can use them for tag-based cache invalidation. Use the [`IMGPROXY_CACHE_TAGS_FORMAT`](../configuration/options.mdx#IMGPROXY_CACHE_TAGS_FORMAT) config to choose which format(s) the tags are written in — [CloudFront](https://aws.amazon.com/blogs/networking-and-content-delivery/manage-caches-with-precision-using-amazon-cloudfront-invalidation-by-cache-tag/), [Cloudflare](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/), both (the default), or neither. + +## Bypassing the cache + +imgproxy Pro can bypass the internal cache for a single request using the [bypass_cache](../usage/processing.mdx#bypass-cache) processing option: + +```imgproxy_url_option +bypass_cache:%bypass +bc:%bypass +``` + +When enabled for a request, imgproxy skips reading and writing the cache entirely—including the source cache, if enabled—and processes and fetches everything from the source image. Because this lets a client bypass your cache, it’s not allowed unless the [`IMGPROXY_ALLOW_BYPASS_CACHE`](../configuration/options.mdx#IMGPROXY_ALLOW_BYPASS_CACHE) config is set to `true`. + ## Limitations * **No manual cache invalidation**: Currently, imgproxy doesn't provide a built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images. -* **No cache for info requests**: The internal cache is currently used only for image processing requests. Requests to the `/info` endpoint are not cached. ## How it works @@ -63,6 +104,11 @@ When a request comes in: 1. imgproxy checks the URL signature (if enabled). 2. imgproxy generates the cache key from the request parameters. -3. imgproxy checks if a cached image exists in the configured storage. +3. imgproxy checks if a cached processed image exists in the configured storage. 4. If the cached image exists and is valid, imgproxy serves it directly. -5. If not, imgproxy processes the image and stores the result in the cache before serving it. +5. If not, and [source image caching](#source-image-caching) is enabled, imgproxy checks the source cache (using its own [separate key](#source-cache-key)) before downloading the source image: + * On a hit, imgproxy uses the cached source bytes instead of re-downloading them. + * On a miss, imgproxy downloads the source image and caches it in the background. +6. imgproxy processes the image, serves the result, and stores it in the cache in the background — the response isn't delayed while it waits for the cache write to finish. + +Cache writes (both processed-image and source) always happen in the background this way. On a graceful shutdown, imgproxy waits up to [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`](../configuration/options.mdx#IMGPROXY_CACHE_SHUTDOWN_TIMEOUT) for any still-pending writes to finish before exiting. diff --git a/docs/configuration/options.mdx b/docs/configuration/options.mdx index 8bf8def..145c8b9 100644 --- a/docs/configuration/options.mdx +++ b/docs/configuration/options.mdx @@ -278,10 +278,10 @@ Autoquality requires the image to be saved several times. Use it only when you p * [`IMGPROXY_AUTOQUALITY_AVIF_NET`]: ((pro)) the path to the neural network model for AVIF. * [`IMGPROXY_AUTOQUALITY_JXL_NET`]: ((pro)) the path to the neural network model for JPEG XL. -* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the autoquality models. * [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the autoquality models. -* [`IMGPROXY_AUTOQUALITY_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the autoquality models. -* [`IMGPROXY_AUTOQUALITY_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the autoquality models. ## SVG processing * [`IMGPROXY_ALWAYS_RASTERIZE_SVG`]: when `true`, imgproxy will always rasterize SVG images unless SVG processing is not [skipped](#skip-processing). Default: `false` @@ -413,6 +413,20 @@ imgproxy Pro can process digital camera RAW images. Since loading RAW images is Read more about watermarks in the [Watermark](../features/watermark.mdx) guide. +## C2PA + +imgproxy can attach [C2PA](https://c2pa.org/) content provenance manifests to processed images. + +* [`IMGPROXY_C2PA_ENABLED`]: ((pro)) when `true`, imgproxy will sign processed images with a C2PA manifest. Default: `false` +* [`IMGPROXY_C2PA_SETTINGS`]: ((pro)) the raw c2pa-rs SDK settings string, including signing credentials. Takes precedence over `IMGPROXY_C2PA_SETTINGS_PATH` +* [`IMGPROXY_C2PA_SETTINGS_PATH`]: ((pro)) the path to a file with the c2pa-rs SDK settings, as an alternative to `IMGPROXY_C2PA_SETTINGS` +* [`IMGPROXY_C2PA_FORMAT`]: ((pro)) the format of the C2PA settings. Can be `toml` or `json`. Default: `toml` +* [`IMGPROXY_C2PA_ACTION`]: ((pro)) the C2PA action recorded in the manifest for processed images. Default: `c2pa.edited` +* [`IMGPROXY_C2PA_SOFTWARE_AGENT`]: ((pro)) the software agent name recorded in the manifest. Default: `imgproxy` +* [`IMGPROXY_C2PA_SOFTWARE_AGENT_VERSION`]: ((pro)) the software agent version recorded in the manifest. Default: the running imgproxy version + +Read more about C2PA in the [C2PA](../features/c2pa.mdx) guide. + ## Unsharp masking imgproxy Pro can apply unsharp masking to your images. @@ -436,17 +450,17 @@ imgproxy Pro can apply unsharp masking to your images. These options allow you to configure common aspects of machine learning features such as object detection, classification, autoquality, etc. -* [`IMGPROXY_ML_NUM_STREAMS`]: ((pro)) the maximum number of inference requests that can be processed concurrently by each machine learning model. When the limit is reached, additional inference requests will be queued until the previous ones are finished. Default: the number of CPU cores available to imgproxy +* [`IMGPROXY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) the maximum number of inference requests that can be processed concurrently by each machine learning model. When the limit is reached, additional inference requests will be queued until the previous ones are finished. Default: the number of CPU cores available to imgproxy :::tip -The larger the `IMGPROXY_ML_NUM_STREAMS` value, the more memory ML features will consume. If you don't have a lot of RAM, you may want to set it to a value lower than the number of CPU cores. +The larger the `IMGPROXY_ML_INFERENCE_NUM_STREAMS` value, the more memory ML features will consume. If you don't have a lot of RAM, you may want to set it to a value lower than the number of CPU cores. ::: -* [`IMGPROXY_ML_INFERENCE_NUM_THREADS`]: ((pro)) the number of threads that can be used for inference by each machine learning model. If less than the `IMGPROXY_ML_NUM_STREAMS` value, the number of streams will be limited to this value. Default: the number of CPU cores available to imgproxy -* [`IMGPROXY_ML_EXECUTION_MODE`]: ((pro)) the execution mode of the machine learning models. Supported values are: +* [`IMGPROXY_ML_INFERENCE_NUM_THREADS`]: ((pro)) the number of threads that can be used for inference by each machine learning model. If less than the `IMGPROXY_ML_INFERENCE_NUM_STREAMS` value, the number of streams will be limited to this value. Default: the number of CPU cores available to imgproxy +* [`IMGPROXY_ML_INFERENCE_EXECUTION_MODE`]: ((pro)) the execution mode of the machine learning models. Supported values are: * `performance`: _(default)_ the model will be optimized for performance. Some model layers may be fused or converted to a different type to improve performance. This may lead to a slight decrease in accuracy. * `accuracy`: the model will be optimized for accuracy. The optimizations that may decrease accuracy will be disabled. This may lead to decreased performance. -* [`IMGPROXY_ML_CPU_PINNING`]: ((pro)) when `true`, machine learning inference threads will be pinned to CPU cores. This may improve performance on some workloads, but generally it is not recommended to enable this option. Default: `false` +* [`IMGPROXY_ML_INFERENCE_CPU_PINNING`]: ((pro)) when `true`, machine learning inference threads will be pinned to CPU cores. This may improve performance on some workloads, but generally it is not recommended to enable this option. Default: `false` ## Object detection @@ -465,10 +479,10 @@ imgproxy can detect objects on the image and use them to perform smart cropping, * `one_best`: in this mode, imgproxy will focus on the object with the highest score based on its area, confidence, and class weight. * `one_best_centermost`: the same as `one_best,` but imgproxy will add the object's proximity to the image center to its score. -* [`IMGPROXY_OBJECT_DETECTION_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the object detection model. -* [`IMGPROXY_OBJECT_DETECTION_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the object detection model. -* [`IMGPROXY_OBJECT_DETECTION_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the object detection model. -* [`IMGPROXY_OBJECT_DETECTION_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the object detection model. Read the [Object Detection guide](../features/object_detection.mdx) for more info. @@ -489,10 +503,10 @@ imgproxy can classify images by assigning them to predefined categories based on * `nhwc`: _(default)_ channels last (TensorFlow default) * `nchw`: channels first (PyTorch default) -* [`IMGPROXY_CLASSIFICATION_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the classification model. -* [`IMGPROXY_CLASSIFICATION_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the classification model. -* [`IMGPROXY_CLASSIFICATION_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the classification model. -* [`IMGPROXY_CLASSIFICATION_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the classification model. Read the [Classification guide](../features/classification.mdx) for more info. @@ -506,6 +520,10 @@ imgproxy can cache processed images in various storage backends to improve perfo * [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank * [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank * [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false` +* [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`]: ((pro)) the maximum time imgproxy will wait for pending background cache writes to complete during a graceful shutdown. Default: `5s` +* [`IMGPROXY_CACHE_PROCESSING_ENABLED`]: ((pro)) when `true`, imgproxy will cache processed images. Default: `true` +* [`IMGPROXY_CACHE_INFO_ENABLED`]: ((pro)) when `true`, imgproxy will cache `/info` endpoint responses. Default: `true` +* [`IMGPROXY_CACHE_SOURCE_ENABLE`]: ((pro)) when `true`, imgproxy will cache downloaded source image bytes in addition to processed results. Default: `false` * [`IMGPROXY_CACHE_TAGS_FORMAT`]: ((pro)) defines how the cache tags added by the [cache_tags](../usage/processing.mdx#cache-tags) option are written to the response headers. Supported values are: * `all`: _(default)_ imgproxy will write cache tags in all supported formats @@ -771,6 +789,7 @@ imgproxy can send request traces to an OpenTelemetry collector: * [`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`]: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with `\n`). Default: blank * [`IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`]: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray` * [`IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false` +* [`IMGPROXY_OPEN_TELEMETRY_LOGGER_NAME`]: the instrumentation scope name used when sending logs to the OpenTelemetry collector. Default: `imgproxy` Check out the [OpenTelemetry](../monitoring/open_telemetry.mdx) guide to learn more. @@ -789,6 +808,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_REPORT_IO_ERRORS`]: when `true`, imgproxy will report errors that occur while writing the response body to the client. 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/autoquality.mdx b/docs/features/autoquality.mdx index d6f3fb4..313ef23 100644 --- a/docs/features/autoquality.mdx +++ b/docs/features/autoquality.mdx @@ -126,6 +126,13 @@ IMGPROXY_AUTOQUALITY_JXL_NET="/networks/autoquality-jxl.onnx" If you trust your neural network model's autoquality, you may want to set `IMGPROXY_AUTOQUALITY_ALLOWED_ERROR` to 1 (the maximum possible DSSIM value). In this case, imgproxy will always use the quality predicted by the neural network model. ::: +### OpenVINO configuration options + +* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_STREAMS`]: when set, overrides the [IMGPROXY_ML_NUM_STREAMS](../configuration/options.mdx#IMGPROXY_ML_NUM_STREAMS) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_THREADS`]: when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](../configuration/options.mdx#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_EXECUTION_MODE`]: when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](../configuration/options.mdx#IMGPROXY_ML_EXECUTION_MODE) value for the autoquality models. +* [`IMGPROXY_AUTOQUALITY_ML_CPU_PINNING`]: when set, overrides the [IMGPROXY_ML_CPU_PINNING](../configuration/options.mdx#IMGPROXY_ML_CPU_PINNING) value for the autoquality models. + ### Processing options example ```imgproxy_url diff --git a/docs/features/c2pa.mdx b/docs/features/c2pa.mdx new file mode 100644 index 0000000..9ca31a0 --- /dev/null +++ b/docs/features/c2pa.mdx @@ -0,0 +1,97 @@ +--- +title: C2PA +description: Learn about how imgproxy adds C2PA content provenance manifests to processed images +--- + +# C2PA ((pro)) + +imgproxy can attach [C2PA](https://c2pa.org/) (Coalition for Content Provenance and Authenticity) manifests — also known as Content Credentials — to processed images. A C2PA manifest is a tamper-evident record embedded in the image that describes its provenance: who created or edited it, what software was used, and, when the source image already carries a manifest, the full edit history inherited from it. + +When enabled, imgproxy signs every processed image it outputs with a C2PA manifest, using [c2pa-rs](https://github.com/contentauth/c2pa-rs) under the hood. + +## Configuration + +* [`IMGPROXY_C2PA_ENABLED`]: when `true`, imgproxy will sign processed images with a C2PA manifest. Default: `false` +* [`IMGPROXY_C2PA_SETTINGS`]: the raw [c2pa-rs SDK settings](https://github.com/contentauth/c2pa-rs/blob/main/sdk/tests/fixtures/test_settings.toml) string, including signing credentials, trust anchors, and verification/builder options. Takes precedence over `IMGPROXY_C2PA_SETTINGS_PATH` when both are set +* [`IMGPROXY_C2PA_SETTINGS_PATH`]: the path to a file containing the c2pa-rs SDK settings, as an alternative to providing them inline via `IMGPROXY_C2PA_SETTINGS` +* [`IMGPROXY_C2PA_FORMAT`]: the format of the C2PA settings. Can be `toml` or `json`. Default: `toml` +* [`IMGPROXY_C2PA_ACTION`]: the C2PA action recorded in the manifest for processed images. Default: `c2pa.edited` +* [`IMGPROXY_C2PA_SOFTWARE_AGENT`]: the software agent name recorded in the manifest. Default: `imgproxy` +* [`IMGPROXY_C2PA_SOFTWARE_AGENT_VERSION`]: the software agent version recorded in the manifest. Default: the running imgproxy version + +You need to provide signing credentials (and, optionally, trust anchors and other c2pa-rs options) via `IMGPROXY_C2PA_SETTINGS` or `IMGPROXY_C2PA_SETTINGS_PATH` for signing to work — see the [c2pa-rs settings reference](https://github.com/contentauth/c2pa-rs/blob/main/sdk/tests/fixtures/test_settings.toml) for the full list of supported options, including the `[signer.local]` section. + +### Sample configuration + +Here's a minimal `IMGPROXY_C2PA_SETTINGS_PATH` TOML file with just a local signer, enough to get C2PA signing working: + +```toml +[signer.local] +alg = "es256" +sign_cert = """ +-----BEGIN CERTIFICATE----- +MIIChzCCAi6gAwIBAgIUcCTmJHYF8dZfG0d1UdT6/LXtkeYwCgYIKoZIzj0EAwIw +gYwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTESMBAGA1UEBwwJU29tZXdoZXJl +MScwJQYDVQQKDB5DMlBBIFRlc3QgSW50ZXJtZWRpYXRlIFJvb3QgQ0ExGTAXBgNV +BAsMEEZPUiBURVNUSU5HX09OTFkxGDAWBgNVBAMMD0ludGVybWVkaWF0ZSBDQTAe +Fw0yMjA2MTAxODQ2NDBaFw0zMDA4MjYxODQ2NDBaMIGAMQswCQYDVQQGEwJVUzEL +MAkGA1UECAwCQ0ExEjAQBgNVBAcMCVNvbWV3aGVyZTEfMB0GA1UECgwWQzJQQSBU +ZXN0IFNpZ25pbmcgQ2VydDEZMBcGA1UECwwQRk9SIFRFU1RJTkdfT05MWTEUMBIG +A1UEAwwLQzJQQSBTaWduZXIwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQPaL6R +kAkYkKU4+IryBSYxJM3h77sFiMrbvbI8fG7w2Bbl9otNG/cch3DAw5rGAPV7NWky +l3QGuV/wt0MrAPDoo3gwdjAMBgNVHRMBAf8EAjAAMBYGA1UdJQEB/wQMMAoGCCsG +AQUFBwMEMA4GA1UdDwEB/wQEAwIGwDAdBgNVHQ4EFgQUFznP0y83joiNOCedQkxT +tAMyNcowHwYDVR0jBBgwFoAUDnyNcma/osnlAJTvtW6A4rYOL2swCgYIKoZIzj0E +AwIDRwAwRAIgOY/2szXjslg/MyJFZ2y7OH8giPYTsvS7UPRP9GI9NgICIDQPMKrE +LQUJEtipZ0TqvI/4mieoyRCeIiQtyuS0LACz +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +MIICajCCAg+gAwIBAgIUfXDXHH+6GtA2QEBX2IvJ2YnGMnUwCgYIKoZIzj0EAwIw +dzELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTb21ld2hlcmUx +GjAYBgNVBAoMEUMyUEEgVGVzdCBSb290IENBMRkwFwYDVQQLDBBGT1IgVEVTVElO +R19PTkxZMRAwDgYDVQQDDAdSb290IENBMB4XDTIyMDYxMDE4NDY0MFoXDTMwMDgy +NzE4NDY0MFowgYwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTESMBAGA1UEBwwJ +U29tZXdoZXJlMScwJQYDVQQKDB5DMlBBIFRlc3QgSW50ZXJtZWRpYXRlIFJvb3Qg +Q0ExGTAXBgNVBAsMEEZPUiBURVNUSU5HX09OTFkxGDAWBgNVBAMMD0ludGVybWVk +aWF0ZSBDQTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABHllI4O7a0EkpTYAWfPM +D6Rnfk9iqhEmCQKMOR6J47Rvh2GGjUw4CS+aLT89ySukPTnzGsMQ4jK9d3V4Aq4Q +LsOjYzBhMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQW +BBQOfI1yZr+iyeUAlO+1boDitg4vazAfBgNVHSMEGDAWgBRembiG4Xgb2VcVWnUA +UrYpDsuojDAKBggqhkjOPQQDAgNJADBGAiEAtdZ3+05CzFo90fWeZ4woeJcNQC4B +84Ill3YeZVvR8ZECIQDVRdha1xEDKuNTAManY0zthSosfXcvLnZui1A/y/DYeg== +-----END CERTIFICATE----- +""" +private_key = """ +-----BEGIN PRIVATE KEY----- +MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgfNJBsaRLSeHizv0m +GL+gcn78QmtfLSm+n+qG9veC2W2hRANCAAQPaL6RkAkYkKU4+IryBSYxJM3h77sF +iMrbvbI8fG7w2Bbl9otNG/cch3DAw5rGAPV7NWkyl3QGuV/wt0MrAPDo +-----END PRIVATE KEY----- +""" +``` + +:::warning +This certificate/key pair is self-signed and intended for testing only (it's marked `FOR TESTING_ONLY` in its Subject). It lets you try C2PA signing end-to-end, but manifests it produces won't validate against real trust anchors. For production, replace `sign_cert`/`private_key` with your own CA-issued (or otherwise trusted) signing credentials — see the [c2pa-rs settings reference](https://github.com/contentauth/c2pa-rs/blob/main/sdk/tests/fixtures/test_settings.toml) for the full `[signer.*]` options, including remote/KMS-backed signers, and [Getting a signing certificate](https://opensource.contentauthenticity.org/docs/signing/get-cert/) for how to obtain one, either a self-signed certificate for testing or one purchased from a C2PA-approved Certificate Authority for production. +::: + +Point `IMGPROXY_C2PA_SETTINGS_PATH` at the file (or inline its contents via `IMGPROXY_C2PA_SETTINGS`) and set `IMGPROXY_C2PA_ENABLED=true` to start signing. + +:::info +C2PA signing is only available for JPEG, PNG, WebP, GIF, JPEG XL, AVIF, HEIC, TIFF, and SVG output. Other output formats are returned unsigned. +::: + +## Provenance and creation info + +Every signed image gets an action recorded using [`IMGPROXY_C2PA_ACTION`](../configuration/options.mdx#IMGPROXY_C2PA_ACTION) (`c2pa.edited` by default), with the software agent taken from [`IMGPROXY_C2PA_SOFTWARE_AGENT`](../configuration/options.mdx#IMGPROXY_C2PA_SOFTWARE_AGENT)/[`IMGPROXY_C2PA_SOFTWARE_AGENT_VERSION`](../configuration/options.mdx#IMGPROXY_C2PA_SOFTWARE_AGENT_VERSION). This always applies and can't be overridden per request. When the source image already contains a C2PA manifest, imgproxy also uses it as an ingredient and inherits its provenance chain. + +When the source image has **no** existing manifest, you can additionally attach a `c2pa.created` action — with its own software agent and a required digital source type — using the `c2pa_created_by`/`c2pa_cb` processing option. See the [Processing options](../usage/processing.mdx#c2pa-created-by) reference for its syntax and arguments. + +## Reading the manifest + +You can read back the C2PA manifest of a source or already-signed image using the `c2pa` info option: + +```imgproxy_url +/info/.../c2pa:1/... +``` + +Read more about the `c2pa` info option, including the response format, in the [Info options](../usage/getting_info.mdx#c2pa) reference. diff --git a/docs/features/classification.mdx b/docs/features/classification.mdx index c776213..e514551 100644 --- a/docs/features/classification.mdx +++ b/docs/features/classification.mdx @@ -601,6 +601,13 @@ You need to define the following config variables to enable object classificatio Default: `nhwc` +### OpenVINO configuration options + +* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_STREAMS`]: when set, overrides the [IMGPROXY_ML_NUM_STREAMS](../configuration/options.mdx#IMGPROXY_ML_NUM_STREAMS) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_THREADS`]: when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](../configuration/options.mdx#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_EXECUTION_MODE`]: when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](../configuration/options.mdx#IMGPROXY_ML_EXECUTION_MODE) value for the classification model. +* [`IMGPROXY_CLASSIFICATION_CPU_PINNING`]: when set, overrides the [IMGPROXY_ML_CPU_PINNING](../configuration/options.mdx#IMGPROXY_ML_CPU_PINNING) value for the classification model. + ### Class names file The class names file maps the neural network's class indexes to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_CLASSIFICATION_CLASSES` config variable. diff --git a/docs/features/object_detection.mdx b/docs/features/object_detection.mdx index 22818c4..55d9e00 100644 --- a/docs/features/object_detection.mdx +++ b/docs/features/object_detection.mdx @@ -257,6 +257,13 @@ You need to define the following config variables to enable object detection wit * [`IMGPROXY_OBJECT_DETECTION_SWAP_RB`]: when set to `true`, imgproxy will swap the R and B channels in the input image. Some models are trained on BGR images and perform incorrectly with RGB inputs. This option allows you to fix this issue. Default: `false` * [`IMGPROXY_OBJECT_DETECTION_FALLBACK_TO_SMART_CROP`]: ((pro)) defines imgproxy's behavior when object-oriented crop gravity is used but no objects are detected. When set to `true`, imgproxy will fallback to smart crop. When set to `false`, imgproxy will fallback to the center gravity. Default: `true` +### OpenVINO configuration options + +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_STREAMS`]: when set, overrides the [IMGPROXY_ML_NUM_STREAMS](../configuration/options.mdx#IMGPROXY_ML_NUM_STREAMS) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_THREADS`]: when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](../configuration/options.mdx#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_EXECUTION_MODE`]: when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](../configuration/options.mdx#IMGPROXY_ML_EXECUTION_MODE) value for the object detection model. +* [`IMGPROXY_OBJECT_DETECTION_CPU_PINNING`]: when set, overrides the [IMGPROXY_ML_CPU_PINNING](../configuration/options.mdx#IMGPROXY_ML_CPU_PINNING) value for the object detection model. + ### Class names file The class names file is used to map the class indexes from the neural network output to human-readable class names. The path to the class names file should be defined in the `IMGPROXY_OBJECT_DETECTION_CLASSES` config variable. diff --git a/docs/monitoring/cloud_watch.mdx b/docs/monitoring/cloud_watch.mdx index 570e265..e4f57cb 100644 --- a/docs/monitoring/cloud_watch.mdx +++ b/docs/monitoring/cloud_watch.mdx @@ -23,6 +23,10 @@ imgproxy sends the following metrics to CloudWatch: * `VipsMemory`: libvips memory usage (in bytes) * `VipsMaxMemory`: libvips maximum memory usage (in bytes) * `VipsAllocs`: the number of active vips allocations +* `CacheHits`: the number of cache hits (sent only when greater than 0) +* `CacheMisses`: the number of cache misses (sent only when greater than 0) +* `SrcCacheHits`: the number of source image cache hits (sent only when greater than 0) +* `SrcCacheMisses`: the number of source image cache misses (sent only when greater than 0) ### Set up credentials diff --git a/docs/monitoring/datadog.mdx b/docs/monitoring/datadog.mdx index 48beedd..7242391 100644 --- a/docs/monitoring/datadog.mdx +++ b/docs/monitoring/datadog.mdx @@ -47,3 +47,7 @@ When the `IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS` environment variable is se * `imgproxy.vips.memory`: libvips memory usage (in bytes) * `imgproxy.vips.max_memory`: libvips maximum memory usage (in bytes) * `imgproxy.vips.allocs`: the number of active vips allocations +* `imgproxy.cache.hits`: the number of cache hits (sent only when greater than 0) +* `imgproxy.cache.misses`: the number of cache misses (sent only when greater than 0) +* `imgproxy.src_cache.hits`: the number of source image cache hits (sent only when greater than 0) +* `imgproxy.src_cache.misses`: the number of source image cache misses (sent only when greater than 0) diff --git a/docs/monitoring/new_relic.mdx b/docs/monitoring/new_relic.mdx index e9934c4..edb9e84 100644 --- a/docs/monitoring/new_relic.mdx +++ b/docs/monitoring/new_relic.mdx @@ -33,3 +33,7 @@ Additionally, imgproxy sends the following metrics over [Metrics API](https://do * `vips/memory`: libvips memory usage (in bytes) * `vips/max_memory`: libvips maximum memory usage (in bytes) * `vips/allocs`: the number of active vips allocations +* `cache/hits`: the number of cache hits (sent only when greater than 0) +* `cache/misses`: the number of cache misses (sent only when greater than 0) +* `src_cache/hits`: the number of source image cache hits (sent only when greater than 0) +* `src_cache/misses`: the number of source image cache misses (sent only when greater than 0) diff --git a/docs/monitoring/open_telemetry.mdx b/docs/monitoring/open_telemetry.mdx index ab349d4..6fe849b 100644 --- a/docs/monitoring/open_telemetry.mdx +++ b/docs/monitoring/open_telemetry.mdx @@ -51,6 +51,11 @@ imgproxy will send the following info to the collector: If `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` is set to `true`, imgproxy will also send the following metrics to the collector: +* `requests_total`: a counter with the total number of HTTP requests imgproxy has processed +* `status_codes_total`: a counter of the response status codes separated by status +* `errors_total`: a counter of the occurred errors separated by type (timeout, downloading, processing) +* `request_duration_seconds`: a histogram of the request latency (in seconds) +* `request_span_duration_seconds`: a histogram of the request latency (in seconds) separated by span (queue, downloading, processing) * `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 @@ -61,6 +66,10 @@ If `IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS` is set to `true`, imgproxy will also * `vips_memory_bytes`: libvips memory usage * `vips_max_memory_bytes`: libvips maximum memory usage * `vips_allocs`: the number of active vips allocations +* `cache_hits_total`: a counter of the total number of cache hits +* `cache_misses_total`: a counter of the total number of cache misses +* `src_cache_hits_total`: a counter of the total number of source image cache hits +* `src_cache_misses_total`: a counter of the total number of source image cache misses * Some useful Go metrics like memstats and goroutines count ## Configuration diff --git a/docs/monitoring/prometheus.mdx b/docs/monitoring/prometheus.mdx index 103d38c..658cb81 100644 --- a/docs/monitoring/prometheus.mdx +++ b/docs/monitoring/prometheus.mdx @@ -27,4 +27,8 @@ imgproxy will collect the following metrics: * `vips_memory_bytes`: libvips memory usage * `vips_max_memory_bytes`: libvips maximum memory usage * `vips_allocs`: the number of active vips allocations +* `cache_hits_total`: a counter of the total number of cache hits +* `cache_misses_total`: a counter of the total number of cache misses +* `src_cache_hits_total`: a counter of the total number of source image cache hits +* `src_cache_misses_total`: a counter of the total number of source image cache misses * Some useful Go metrics like memstats and goroutines count diff --git a/docs/usage/getting_info.mdx b/docs/usage/getting_info.mdx index 28c6f42..8cef078 100644 --- a/docs/usage/getting_info.mdx +++ b/docs/usage/getting_info.mdx @@ -686,6 +686,31 @@ Default: empty Calculation of video file hashsums is not supported as it would require downloading the whole video file. imgproxy won't throw an error if you try to calculate the hashsum of a video file but it will skip the `hashsums` field ::: +### C2PA ((pro)) {#c2pa} + +```imgproxy_url_option +c2pa:%c2pa +``` + +When set to `1`, `t` or `true`, imgproxy will return the image's C2PA manifest (if any) as a `c2pa_manifest` JSON field. Read more about C2PA in the [C2PA](../features/c2pa.mdx) guide. + +Default: `false` + +**Response example:** + +```json +{ + "c2pa_manifest": { + "active_manifest": "", + "manifests": { + "": { } + } + } +} +``` + +`manifests` is keyed by manifest ID, and `active_manifest` points to the currently active one; each manifest object follows the [c2pa-rs manifest store](https://opensource.contentauthenticity.org/docs/manifest/json-ref/manifest-definition-schema) JSON format. + ### Page ```imgproxy_url_option diff --git a/docs/usage/processing.mdx b/docs/usage/processing.mdx index d277796..46a292a 100644 --- a/docs/usage/processing.mdx +++ b/docs/usage/processing.mdx @@ -1189,6 +1189,20 @@ att:%return_attachment When set to `1`, `t` or `true`, imgproxy will return `attachment` in the `Content-Disposition` header, and the browser will open a 'Save as' dialog. This is normally controlled by the [IMGPROXY_RETURN_ATTACHMENT](../configuration/options.mdx#IMGPROXY_RETURN_ATTACHMENT) configuration but this processing option allows the configuration to be set for each request. +### C2PA created by ((pro)) {#c2pa-created-by} + +```imgproxy_url_option +c2pa_created_by:%software_agent:%digital_source_type +c2pa_cb:%software_agent:%digital_source_type +``` + +Sets the creation info used for the `c2pa.created` action when the source image has no existing C2PA manifest to inherit from. This action is added in addition to the standard [IMGPROXY_C2PA_ACTION](../configuration/options.mdx#IMGPROXY_C2PA_ACTION) entry, which is always recorded using [IMGPROXY_C2PA_SOFTWARE_AGENT](../configuration/options.mdx#IMGPROXY_C2PA_SOFTWARE_AGENT) regardless of this option. + +* `software_agent`: the software agent name to record for the `c2pa.created` action. Independent of `IMGPROXY_C2PA_SOFTWARE_AGENT` — it does not override it. +* `digital_source_type`: the [C2PA digital source type](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_digital_source_type), for example `digitalCapture`, `trainedAlgorithmicMedia`, or `composite`. + +Both arguments are required for the option to take effect. Read more about C2PA in the [C2PA](../features/c2pa.mdx) guide. + ### Preset ```imgproxy_url_option diff --git a/sidebars.ts b/sidebars.ts index 864f620..fbd44c9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -96,6 +96,11 @@ const sidebars: SidebarsConfig = { }, ], }, + { + type: "doc", + id: "features/c2pa", + className: "menu__list-item--badge badge--pro", + }, ], }, {