pict-rs/releases/0.5.0.md

# pict-rs 0.5.0

## Overview

### Headline Features

- [Postgres Repo](#postgres-repo)
- [Media Proxy](#media-proxy)


### Changes

- [Improved Animation Support](#improved-animation-support)
- [Media Configuration](#media-configuration)
- [Improved Collision Resistance](#improved-collision-resistance)
- [Optional Video Transcoding](#optional-video-transcoding)
- [Library API Changes](#library-api-changes)
- [Reject Malformed Deadliens](#reject-malformed-deadlines)
- [Logging Verbosity](#logging-verbosity)


### Other Features

- [Quality Configuration](#quality-configuration)
- [Read-Only Mode](#read-only-mode)
- [Danger-Dummy Mode](#danger-dummy-mode)
- [Media Variant Retention](#media-variant-retention)
- [Configurable Temporary Directory](#configurable-temporary-directory)
- [Serve From Object Storage](#serve-from-object-storage)
- [Prometheus Metrics](#prometheus-metrics)
- [Internal Hashes Endpoint](#internal-hashes-endpoint)
- [Internal Delete Endpoint](#internal-delete-endpoint)
- [Error Codes](#error-codes)


### Fixes

- [Clean Stray Magick Files](#clean-stray-magick-files)
- [Always Drain Payloads](#always-drain-payloads)
- [Constant-Time Equality for Deletion](#constant-time-equality-for-deletion)


### Removals

- [ini and json5](#ini-and-json5)
- [Client Pool Size](#client-pool-size)
- [0.3 Migration Path](#03-migration-path)
- [Prepare Upgrade Endpoint](#prepare-upgrade-endpoint)


## Upgrade Notes

The upgrade from pict-rs 0.4 to 0.5 might take some time. Any uploads that have not had their
metadata extracted will be processed during this migration. In order to reduce the time required the
migration, pict-rs version 0.4.6 can be run first, and the `/internal/prepare_upgrade` endpoint can
be hit. This will tell pict-rs to extract the required metadata for the 0.5 upgrade in the
background while 0.4 is still running, enabling the upgrade to 0.5 to proceed much faster after it
completes. More information about this endpoint can be found in the
[0.4.6 release document](./0.4.6.md)

If you're running the provided docker container with default configuration values, the 0.5 container
can be pulled and launched with no changes. There is a migration from the 0.4 database format to the
0.5 database format that will occur automatically on first launch. This is also the process that
will extract metadata for any uploads that have not had their metadata extracted yet.

If you have any custom configuration, note that some media-related configuration values have been
moved. See [Media Configuration](#media-configuration) below.

pict-rs 0.5 now supports postgres for metadata storage. It is possible to upgrade directly from 0.4
to 0.5 with postgres, rather than upgrading to 0.5 with sled and then making the migration later.
This process is documented in the
[pict-rs readme](https://git.asonix.dog/asonix/pict-rs#upgrading-directly-to-postgres).

A notable addition in 0.5 is upgrade configuration. Since the migration accesses media from the
configured store, increasing the concurrency can be beneficial. By default, pict-rs will attempt to
migrate 32 records at a time, but this value can be increased.

In the configuration file
```toml
[upgrade]
concurrency = 32
```

With environment variables
```bash
PICTRS__UPGRADE__CONCURRENCY=32
```

On the commandline
```bash
pict-rs run --upgrade-concurrency 32
```

More information can be found in the
[pict-rs 0.4 to 0.5 migration guide](https://git.asonix.dog/asonix/pict-rs#04-to-05-migration-guide).


## Descriptions

### Postgres Repo

One of the most anticipated features of pict-rs 0.5 is the support for postgres for metadata
storage. This makes pict-rs (mostly) stateless, enabling it to be scaled horizontally across
multiple physical or virtual hosts. It also simplifies administration and backup processes for folks
who are already running a postgres server for other reasons.

Configuring postgres is simple. The `repo` section of the pict-rs configuration now supports more
than just `sled`.

In the configuration file
```toml
[repo]
type = 'postgres'
url = 'postgres://user:password@host:5432/db'
```

With environment variables
```bash
PICTRS__REPO__TYPE=postgres
PICTRS__REPO__URL=postgres://user:password@host:5432/db
```

On the commandline
```bash
pict-rs run filesystem -p ./data postgres -u 'postgres://user:password@host:5432/db'
```

It is possible to update from 0.4 directly to 0.5 with postgres, this process is documented in the
[pict-rs readme](https://git.asonix.dog/asonix/pict-rs#upgrading-directly-to-postgres).

It is possible to migrate to postgres after first upgrading to 0.5. This is also ducmented in the
[pict-rs readme](https://git.asonix.dog/asonix/pict-rs#sled-to-postgres-migration).


### Media Proxy

pict-rs 0.5 supports caching media, and purging cached media after it is no longer necessary to
keep. This behavior is accessed with pict-rs' new `proxy` query parameter at the `/image/original`
endpoint, and the `/image/process.{ext}` endpoint. By passing the URL to an image to the `proxy`
parameter, you can instruct pict-rs to download the media from that URL and cache it locally before
serving it, or a processed version of it. The proxied media is stored for a configurable time limit,
which resets on each access to the proxied media.

This value can be configured as follows

In the configuration file
```toml
[media.retention]
proxy = "7d" # units available are "m" for minutes, "h" for hours, "d" for days, and "y" for years
```

With environment variables
```bash
PICTRS__MEDIA__RETENTION__PROXY=7d
```

On the commandline
```bash
pict-rs run --media-retention-proxy 7d
```

More documentation can be found in the [pict-rs readme](https://git.asonix.dog/asonix/pict-rs#api)
and in the example [pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/branch/main/pict-rs.toml).


### Improved Animation Support

pict-rs 0.4 only supported `gif` for animated images. This decision had been made due to the
format's poor support for higher-resolution animations with higher framerates compared to silent
videos for a given file size. In pict-rs 0.5, animated images are now supported to the same extent
as still images. Available formats for animated images include apng, avif, gif, and webp (although
not jxl yet).

With this support for more animated file types, pict-rs no longer transcodes larger animations into
videos. Instead, animated images will be left in their original format unless an override is
configured, and the default values for maximum animation dimensions, file size, and frame count have
been increased.

Configuration related to animations has been moved from `[media.gif]` to `[media.animation]` to
better reflect what it applies to.

For all configuration options regarding animations, see the example
[pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/branch/main/pict-rs.toml).


### Media Configuration

pict-rs 0.5 splits media configuration further, allowing images, animations, and videos to each
specify their own maximum file size, dimensions, frame counts, etc, in addition to a few global
limits. Relevant sections of configuration are `[media]`, `[media.image]`, `[media.animation]`, and
`[media.video]`.

A list of updated and moved configuration values can be found below.

##### Image Changes
| Old Environment Variable       | New Environment Variable              |
| ------------------------------ | ------------------------------------- |
| `PICTRS__MEDIA__FORMAT`        | `PICTRS__MEDIA__IMAGE__FORMAT`        |
| `PICTRS__MEDIA__MAX_WIDTH`     | `PICTRS__MEDIA__IMAGE__MAX_WIDTH`     |
| `PICTRS__MEDIA__MAX_HEIGHT`    | `PICTRS__MEDIA__IMAGE__MAX_HEIGHT`    |
| `PICTRS__MEDIA__MAX_AREA`      | `PICTRS__MEDIA__IMAGE__MAX_AREA`      |
|                                | `PICTRS__MEDIA__IMAGE__MAX_FILE_SIZE` |

| Old TOML Value          | New TOML Value                |
| ----------------------- | ----------------------------- |
| `[media] format`        | `[media.image] format`        |
| `[media] max_width`     | `[media.image] max_width`     |
| `[media] max_height`    | `[media.image] max_height`    |
| `[media] max_area`      | `[media.image] max_area`      |
|                         | `[media.image] max_file_size` |

##### Animation Changes
| Old Environment Variable              | New Environment Variable                    |
| ------------------------------------- | ------------------------------------------- |
| `PICTRS__MEDIA__GIF__MAX_WIDTH`       | `PICTRS__MEDIA__ANIMATION__MAX_WIDTH`       |
| `PICTRS__MEDIA__GIF__MAX_HEIGHT`      | `PICTRS__MEDIA__ANIMATION__MAX_HEIGHT`      |
| `PICTRS__MEDIA__GIF__MAX_AREA`        | `PICTRS__MEDIA__ANIMATION__MAX_AREA`        |
| `PICTRS__MEDIA__GIF__MAX_FILE_SIZE`   | `PICTRS__MEDIA__ANIMATION__MAX_FILE_SIZE`   |
| `PICTRS__MEDIA__GIF__MAX_FRAME_COUNT` | `PICTRS__MEDIA__ANIMATION__MAX_FRAME_COUNT` |
|                                       | `PICTRS__MEDIA__ANIMATION__FORMAT`          |
|                                       | `PICTRS__MEDIA__ANIMATION__MAX_FILE_SIZE`   |

| Old TOML Value                | New TOML Value                      |
| ----------------------------- | ----------------------------------- |
| `[media.gif] max_width`       | `[media.animation] max_width`       |
| `[media.gif] max_height`      | `[media.animation] max_height`      |
| `[media.gif] max_area`        | `[media.animation] max_area`        |
| `[media.gif] max_file_size`   | `[media.animation] max_file_size`   |
| `[media.gif] max_frame_count` | `[media.animation] max_frame_count` |
|                               | `[media.animation] format`          |
|                               | `[media.animation] max_file_size`   |

##### Video Changes
| Old Environment Variable             | New Environment Variable                |
| ------------------------------------ | --------------------------------------- |
| `PICTRS__MEDIA__ENABLE_SILENT_VIDEO` | `PICTRS__MEDIA__VIDEO__ENABLE`          |
| `PICTRS__MEDIA__ENABLE_FULL_VIDEO`   | `PICTRS__MEDIA__VIDEO__ALLOW_AUDIO`     |
| `PICTRS__MEDIA__VIDEO_CODEC`         | `PICTRS__MEDIA__VIDEO__VIDEO_CODEC`     |
| `PICTRS__MEDIA__AUDIO_CODEC`         | `PICTRS__MEDIA__VIDEO__AUDIO_CODEC`     |
| `PICTRS__MEDIA__MAX_FRAME_COUNT`     | `PICTRS__MEDIA__VIDEO__MAX_FRAME_COUNT` |
| `PICTRS__MEDIA__ENABLE_FULL_VIDEO`   | `PICTRS__MEDIA__VIDEO__ALLOW_AUDIO`     |
|                                      | `PICTRS__MEDIA__VIDEO__MAX_WIDTH`       |
|                                      | `PICTRS__MEDIA__VIDEO__MAX_HEIGHT`      |
|                                      | `PICTRS__MEDIA__VIDEO__MAX_AREA`        |
|                                      | `PICTRS__MEDIA__VIDEO__MAX_FILE_SIZE`   |

| Old TOML Value                | New TOML Value                  |
| ----------------------------- | ------------------------------- |
| `[media] enable_silent_video` | `[media.video] enable`          |
| `[media] enable_full_video`   | `[media.video] allow_audio`     |
| `[media] video_codec`         | `[media.video] video_codec`     |
| `[media] audio_codec`         | `[media.video] audio_codec`     |
| `[media] max_frame_count`     | `[media.video] max_frame_count` |
| `[media] enable_full_video`   | `[media.video] allow_audio`     |
|                               | `[media.video] max_width`       |
|                               | `[media.video] max_height`      |
|                               | `[media.video] max_area`        |
|                               | `[media.video] max_file_size`   |

Note that although each media type now includes its own `MAX_FILE_SIZE` configuration, the
`PICTRS__MEDIA__MAX_FILE_SIZE` value still exists as a global limit for any file type.

In addition to all the configuration options mentioned above, there are now individual quality
settings that can be configured for each image and animation type, as well as for video files.
Please see the [pict-rs.toml](./pict-rs.toml) file for more information.

For all configuration options regarding media, see the example
[pict-rs.toml](https://git.asonix.dog/asonix/pict-rs/src/branch/main/pict-rs.toml).


### Improved Collision Resistance


### Optional Video Transcoding


### Library API Changes


### Reject Malformed Deadlines


### Logging Verbosity


### Quality Configuration


### Read-Only Mode


### Danger-Dummy Mode


### Media Variant Retention


### Configurable Temporary Directory


### Serve From Object Storage


### Prometheus Metrics


### Internal Hashes Endpoint


### Internal Delete Endpoint


### Error Codes


### Clean Stray Magick Files


### Always Drain Payloads


### Constant-Time Equality for Deletions


### ini and json5


### Client Pool Size


### 0.3 Migration Path


### Prepare Upgrade Endpoint