After a couple of questions from hosting companies about how to detect how well uploads are working at the server/request level, I thought further documentation would help.
Here is a walkthrough of the request flow for media uploads, both before and after WordPress 5.3. Hopefully this will help with troubleshooting and debugging uploads on your infrastructure or sites!
Before WordPress 5.3
Before WordPress 5.3, uploads had to complete during a single HTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. POST request to .../wp-admin/async-upload.php or to the REST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. with the media endpoint (.../wp-json/wp/v2/media/).
The block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor uses the REST API to upload, while any uploads outside the block editor (or using the popup Media Modal) use async-upload.php.
When uploads failed, they would return whatever HTTP error the server is set up to give (usually in the 5xx range). This is usually due to timeout or resource exhaustion (like running out of memory) reasons.
WordPress 5.3+
In WordPress 5.3+, uploads have been decoupled from a single request to allow for resuming. Now, when an upload returns a 5xx error, there can be up to 5 followup requests.
This is accomplished differently depending on whether async-upload.php or the REST API are used.
Legacy Uploads
Outside of the REST API, the upload happens first with a request to async-upload.php, just like before 5.3.
If it fails, a request is made to admin-ajax.php with form-data containing action: media-create-image-subsizes and attachment_id: #### to attempt to complete the action.
If all retry attempts fail, the last request to admin-ajax.php has _wp_upload_failed_cleanup: true in form-data and attempts a cleanup. This deletes the the attachment post, the uploaded file, and any intermediate sizes that were created. Then, an error message is shown to users advising them to scale down the image and try uploading again.
REST API Uploads
When using the REST API, the initial request is to .../wp-json/wp/v2/media?_locale=user, and retry requests are to .../wp-json/wp/v2/media/####/post-process?_locale=user (where #### is the attachment post ID).
If all attempts to resume post-processing fail with HTTP 5xx errors, the last is a standard “delete attachment” request, sent to .../wp-json/wp/v2/media/####?force=true&_locale=user with X-HTTP-Method-Override: DELETE header The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. It performs the same cleanup as described for the admin-ajax.php upload method.
Hopefully this helps in understanding how uploads work! If you have any questions, please ask in the comments for clarification.
Thanks to @azaozz for helping write this post!
+make.wordpress.org/hosting
#5-3, #dev-notes, #media
