RenewCMS/docs/releases/v3.1.0-beta.md

This release adds image variants: named sizes and formats of your images, generated on first use and cached, plus a size limit for the activity log.

New

Image variants

• Owners and admins define named variants (width, height, fit, format and quality) in the new variants screens under Settings. Variants can be created, edited, enabled, disabled, purged and deleted.
• Add ?v=<name> to any uploaded image URL to get the variant. It is generated on the first request, cached, and served from the cache afterwards. The original is never changed, and URLs without ?v= behave as before.
• Each image in the media library shows its variants, and lets you generate or purge them one by one or all at once.
• The new Cache screen shows how many files are generated, the disk space used, how many requests were rejected and what has been unused for 30 days. Purge everything, unused files, one variant or one image.
• Output can keep the original format or be converted to JPEG, PNG or lossy WebP. Images are never enlarged. SVG and animated GIF are served as they are.
• Oversized sources are refused with a clear error instead of exhausting memory, and identical concurrent requests share one generation.
• The new screens are available in English and French.

Activity log

• Retention can now also be capped by size, in GB, in addition to its age. Whichever limit is reached first removes the oldest events. No cap is set by default.

Improvements and fixes

• Fix the missing routes of the integration pages.
• Harmonize the design of the latest screens with the design spec.

API

• GET /v1/image-variants and POST /v1/image-variants list and create variants. PUT /v1/image-variants/{name} replaces a definition, PATCH enables or disables it and DELETE removes it with its files. POST /v1/image-variants/{name}/purge removes the generated files only.
• GET /v1/image-variants/cache returns the cache statistics, and POST /v1/image-variants/cache/purge purges by scope (all, unused, variant or image).
• GET /v1/media/{id}/variants lists the variants of an image. POST /v1/media/{id}/variants generates all missing ones and POST or DELETE /v1/media/{id}/variants/{name} generates or purges one.
• All of these routes are for owners and admins and accept a session only: an API key answers 403.
• GET /static/uploadedImages/<storedName>?v=<name> serves the variant. An unknown or disabled name, or a width, height, format or quality parameter, answers 400. A source over the size or pixel limit answers 413. The response carries an ETag and answers 304 to If-None-Match.
• PATCH /v1/settings also accepts a maximum activity log size in GB, returned as activity_retention_max_gb.

Under the hood

• Add the image variant domain, repositories, renderer, in-memory usage tracker flushed every 30 seconds, and use cases, behind the existing storage port so local and S3 storage both work.
• Document the feature in docs/image-variants.md, docs/api.md and docs/architecture.md, and add the specifications, design screens and Go and Vitest suites.

Upgrading

• Replace the binary, or pull the new image. The variant tables are created automatically at startup. No variant exists until you define one.
• Three optional environment variables are new: IMAGE_VARIANT_MAX_SOURCE_BYTES (10485760), IMAGE_VARIANT_MAX_SOURCE_PIXELS (50000000) and IMAGE_VARIANT_MAX_CONCURRENT_RENDERS (4). An existing install needs no change.
• Generated variants are stored next to your images, in the upload directory or the S3 bucket, and count toward the storage you use.
• Generating a variant when an image is uploaded is not part of this release.