From 8615ffff95285cdf469a00e6056100dcd6029a1a Mon Sep 17 00:00:00 2001 From: asonix Date: Fri, 8 Dec 2023 23:56:51 -0600 Subject: [PATCH] Flesh out remaining 0.5 documentation --- releases/0.5.0.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/releases/0.5.0.md b/releases/0.5.0.md index 7a6b5ea6..eb25e9f0 100644 --- a/releases/0.5.0.md +++ b/releases/0.5.0.md @@ -443,23 +443,60 @@ For more information about this API, see the ### Error Codes +In pict-rs 0.5, all errors returned by the application have an associated error code. While pict-rs +has always provided an error description in the `"msg"` field of the response, the new `"code"` +field represents a general idea of the error that can be used for choosing a translation in +downstream software. + +While there's no documentation-level enumeration of all error codes, the file defining them is +pretty easy to understand. You can find it +[here](https://git.asonix.dog/asonix/pict-rs/src/branch/main/src/error_code.rs). + ### Clean Stray Magick Files +pict-rs depends on other applications in order to identify and process media. If these applications +crash for any reason, they can potentially leave behind temporary files, which slowly aggregate over +time, using disk or RAM. pict-rs 0.5 attempts to solve this by generating a new temporary directory +for each invocation of imagemagick, and cleaning up that directory after the program terminates, +regardless of success. This means that any stray `magick-` files should now be properly removed when +they are no longer in use. + ### Always Drain Payloads +Actix Web, the framework used by pict-rs, has historically had problems with connections remaining +open when request bodies are not read to completion. In order to avoid this, pict-rs has a dedicated +task on each request thread that takes ownership of dropped request payloads and attempts to drain +them, allowing the connections to close. + ### Constant-Time Equality for Deletions +pict-rs uses unique tokens generated per-image in order to authorize the deletion of those images. +In pict-rs 0.5 the checking of these tokens has been made constant-time, preventing the use of +timing attacks that could lead to images being deleted by an attacker. + ### ini and json5 +These configuration formats have been removed from pict-rs 0.5 in order to improve compile times. If +this upsets anyone let me know. I only provide examples in toml anyway. + ### Client Pool Size +The client_pool_size configuration value hasn't meant anything since the switch from awc to reqwest +as pict-rs' http client. It has been removed in 0.5. + ### 0.3 Migration Path +pict-rs 0.5 is not capable of migrating directly from 0.3. Instead, the upgrade path is to upgrade +to 0.4 and then to 0.5. + ### Prepare Upgrade Endpoint + +The internal prepare_upgrade endpoint was only useful in 0.4 to prepare for the 0.5 upgrade, so 0.5 +removes this endpoint.