# pict-rs 0.4.6

## Overview

pict-rs 0.4.6 introduces a new internal endpoint to prepare servers for the 0.5.0 upgrade. This is
to enable the upgrade preparations to be completed on an 0.4 server without taking it offline, thus
improving the speed at which the upgrade will occur.

### Features

- [Upgrade Preparation Endpoint](#upgrade-preparation-endpoint)


### Changes

- [Improved Upload Performance](#improved-upload-performance)


## Upgrade Notes

There's no significant changes from 0.4.5, so upgrading should be as simple as pulling a new version
of pict-rs.


## Descriptions

### Upgrade Preparation Endpoint

In pict-rs 0.3 and 0.4, file metadata was automatically extracted from uploads when they were
created, but earlier versions did not do this. In some scenarios, uploads may be present in pict-rs
without associated metadata. pict-rs 0.5 introduces a requirement on the presence of this metadata,
and the upgrade process automatically extracts this information but the upgrade happens before
pict-rs 0.5 launches its web server, meaning that it will remain inaccessible while it takes the
time to extract the necessary metadata. 

A new internal endpoint has been introduced at `/internal/prepare_upgrade`. This endpoint will queue
a job to ensure all uploads pict-rs has handled have associated file metadata. This will improve the
speed at which the 0.5 upgrade will occur.

The endpoint is available via a `POST` request, and accepts an optional query parameter `force`
which can be set to `true` in order to force pict-rs to queue the metadata job, even if it has
already been queued. Generally, force should not be required.

After the endpoint is hit once, any further request to the endpoint without the `force` parameter
will return the current status of the upgrade preparation job.

Example:
```bash
curl \
    -XPOST \
    -H'X-APi-Token: api-key' \
    'http://localhost:8080/internal/prepare_upgrade'
```

pict-rs will respond with the following json:
```json
{
    "complete": false,
    "progress": 123,
    "total": 456
}
```

This example indicates that the upgrade preparation has processed 123 uploads out of the total 456,
and it is not complete. One thing to note is that when the job does complete, the progress value may
still be less than the total value, although it should be close.


### Improved Upload Performance

At the cost of memory, pict-rs will now accept file uploads and read their bytes before a permit for
external processing becomes available. This improves the speed with which uploads complete, and
allows clients to fully send their requests without being blocked on other uploads. This also fixes
a bug where it is possible for malicious clients to hold upload requests open and prevent pict-rs
from being able to process media.
