pict-rs/releases/0.5.11.md

# pict-rs 0.5.11

pict-rs is a simple image hosting microservice, designed to handle storing and retrieving images,
animations, and videos, as well as providing basic image processing functionality.

## Overview

pict-rs 0.5.11 introduces new per-upload media validations, and new per-upload media processing.
These features will enable applications to be more precise about their media requirements, such as
allowing different media types and sizes for different endpoints, or pre-processing certain media to
optimize for size.

### Features

- [Upload Validations](#upload-validations)
- [Upload Processing](#upload-processing)


### Changes

- [Backgrounded Variants](#backgrounded-variants)


## Upgrade Notes

For postgres-based installations, a small migration will be run when pict-rs 0.5.11 first launches
to create a new notifications table. No manual intervention is required. Upgrading should be as
simple as pulling a new version of pict-rs.


## Descriptions

### Upload Validations

When ingesting media using `POST /image`, `POST /image/backgrounded`, `POST /internal/import`, or
`GET /image/download`, validations can now be applied per-upload. These can be provided in the
request query. The following query parameters are supported:

- max_width: maximum width, in pixels, allowed for the uploaded media
- max_height: maximum height, in pixels, allowed for the uploaded media
- max_area: maximum area, in pixels, allowed for the uploaded media
- max_frame_count: maximum number of frames permitted for animations and videos
- max_file_size: maximum size, in megabytes, allowed
- allow_image: whether to permit still images in the upload
- allow_animation: whether to permit animations in the upload
- allow_video: whether to permit video in the upload

An example request could look like this: `POST /image/backgrounded?max_area=3200&allow_video=false`

Validations are performed in addition to the validations specified in the pict-rs configuration, so
if uploaded media violates any of the validations, it will fail to ingest.


### Upload Processing

In a similar vein to the upload validations, preprocessing steps can now be applied on a per-upload
basis. These are also provided as query parameters, and will be applied _instead of_ the configured
preprocess steps. The preprocess query parameters are provided and processed the same way as in the
`GET image/process.{ext}` endpoint.

An example request could be `POST /image/backgrounded?blur=2.5&resize=300`, which would blur the
uploaded image and fit it inside a 300x300 box before saving it.


### Backgrounded Variants

When serving images from the /process.{ext} endpoint, pict-rs will now queue the processing to
happen via the job queue, rather than processing media inline. It will still wait up to 30 seconds
for the processing to be complete, and return the processed image the same way it always has.

If processing exceeds 30 seconds, pict-rs will return a timeout error, but the processing will
continue in the background. The same variant can be requested again, and it will wait for the same
background process to complete, rather than trying to process the variant a second time.

pict-rs has historically had a method of reducing variant processing to prevent two requests for the
same variant from doing the same work, but this was only effective in environments that only ran 1
copy of pict-rs. In environments that had multiple replicas, each one could end up processing the
same variant if it was requested more than once at a time. This has been solved by using postgres as
a notification system to enable globally unique processing for a given variant.

In sled-based configurations there shouldn't be a noticible difference, aside from the 30 second
timeout on variant endpoints.