Skip to content

REST API: Skip main file conversion for client side media uploads - #16119

Open
b1ink0 wants to merge 1 commit into
WordPress:trunkfrom
b1ink0:fix/66763-client-side-main-file-conversion
Open

b1ink0 wants to merge 1 commit into
WordPress:trunkfrom
b1ink0:fix/66763-client-side-main-file-conversion

Conversation

@b1ink0

@b1ink0 b1ink0 commented Nov 20, 2026 •

Copy link
Copy Markdown

With client side media processing and an image_editor_output_format filter, the server converted the main file of the upload, for example photo.jpg to photo.webp. The browser then replaced the main file with its own scaled or rotated image, and the sideload recorded photo.webp as original_image. Nothing pointed at photo.jpg anymore, so it stayed on disk after "Delete permanently".

When generate_sub_sizes is false, create_item() now leaves the main file unconverted, using the same filter as convert_format: false. The browser supplies the converted main file through the sideload endpoint, so only one place writes the main file. The filter is added after the upload is stored, so the upload's name still reserves the names of the converted files. If another attachment already has photo.webp, the upload is saved as photo-1.jpg and its converted copy as photo-1.webp.

The new test uploads a JPEG with a JPEG to WebP filter and checks that the upload stays the attached file, that no WebP copy is written, and that the response still asks the client for WebP.

This needs the client change from WordPress/gutenberg#87135 in the same release. That change makes the browser create the converted main file for every image that needs a new format, not only for scaled or rotated ones. Without it, the served file of an image under the big image size threshold stays in the uploaded format, for example photo.jpg instead of photo.webp. The upload itself is always kept, either as the served file or as original_image.

Trac ticket: https://core.trac.wordpress.org/ticket/66763

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Tracing the upload flow, a script that replays the client's REST requests, and drafts of the fix. I reviewed, edited and tested the final changes.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code

With client side media processing and an `image_editor_output_format` filter, the server converted the main file of the upload, and the browser then replaced it with its own scaled or rotated image. The sideload recorded the converted copy as `original_image`, so the upload stayed on disk after the attachment was deleted permanently.

The main file of these uploads is now left unconverted, and the browser supplies the converted main file through the sideload endpoint. The output format filter is turned off only once the upload is stored, so its name still reserves the names of the converted files.

Follow-up to [62805], [63014].

Fixes #66763.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props b1ink0, adamsilverstein.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@adamsilverstein

adamsilverstein commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

This needs the client change from WordPress/gutenberg#87135 in the same release. Without it, images under the big image size threshold keep a main file in the uploaded format.

I believe thats expected behavior - the original upload is always saved. we may called the -scaled version "original_image" in meta so it gets served that way, but under the hood the original upload is a different image preserved under a different key, likely source_image. we may output a second image in a new format and call that the "original_image", but we always preserve the actual original.

One big reason we always preserve the original is so that users can always regenerate their images as needed, from the source.


// The client sideloads the converted main file.
if ( false === $request['generate_sub_sizes'] ) {
add_filter( 'image_editor_output_format', '__return_empty_array', 100 );

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmmm, i'm not sure disabling the filtered mapping is the best solution here, how else could we fix this?

Can we make this change at a different part of the stack?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how else could we fix this? Can we make this change at a different part of the stack?

The mapping is still used. The upload response still returns image/webp as image_output_format (the new test checks that), and the browser uses it to convert the main file and the sub sizes. This filter only stops the server from converting the main file during the upload request, so the server stores only the original, as you described on the ticket. It's the same filter convert_format: false already adds in create_item().

The other part of the stack is the client: WordPress/gutenberg#87135 makes the browser create the converted main file, which the server used to make.

I also tried a server only fix: keep the server's conversion, and when the browser's scaled or rotated main file arrives in sideload_item(), keep photo.jpg as original_image and delete the server's photo.webp. That stops the leak too, but the server still converts every upload at full size only to delete it, which is the work client side processing is meant to move to the browser.

@b1ink0

b1ink0 commented Nov 20, 2026

Copy link
Copy Markdown
Author

I believe thats expected behavior - the original upload is always saved. we may called the -scaled version "original_image" in meta so it gets served that way, but under the hood the original upload is a different image preserved under a different key, likely source_image.

Agreed that the upload is always saved, and with both PRs it is. The sentence you quoted was unclear, sorry. By "main file" I meant the file the attachment serves, not the upload. I've reworded it in the description.

One thing about the keys: the served file is the attached file, and original_image is the upload. With both PRs, a 3000x2000 photo.jpg is served as photo-scaled.webp and kept as original_image, the same as when core processes it on the server.

More detail on the ticket: https://core.trac.wordpress.org/ticket/66763#comment:8

@adamsilverstein

Copy link
Copy Markdown
Member

Thanks for the detailed replies @b1ink0, that clears up my confusion about the keys - the attached file is what gets served and original_image is the upload. Agreed the server shouldn't be converting here. I wanted to double check that we wind up with the same files as the server path, so I had Claude test that.

Claude ran the uploads on each path and compared the results:

Tested in the block editor (Chromium) with the JPEG to WebP filter from the ticket, using a 3000x2000 and a 2000x1332 JPEG. "Server path" is the same upload with wp_client_side_media_processing_enabled filtered to false.

3000x2000 (over the big image threshold)

Path Attached (served) file original_image Full size files on disk Left after delete
Server path photo-scaled.webp photo.jpg photo.jpg, photo-scaled.webp nothing
Client side, trunk photo-scaled.webp photo.webp photo.jpg, photo.webp, photo-scaled.webp photo.jpg
Client side, this PR photo-scaled.webp photo.jpg photo.jpg, photo-scaled.webp nothing

2000x1332 (under the threshold)

Path Attached (served) file original_image Full size files on disk Left after delete
Server path photo.webp photo.jpg photo.jpg, photo.webp nothing
Client side, trunk photo.webp photo.jpg photo.jpg, photo.webp nothing
Client side, this PR with trunk's client photo.jpg not set photo.jpg nothing
This PR plus the requests from Gutenberg #87135 photo.webp photo.jpg photo.jpg, photo.webp nothing

In every case the sub-sizes are WebP, source_image is not set and post_mime_type stays image/jpeg, the same as the server path.

So for the big image this PR matches the server path exactly and fixes the leftover file. For the smaller image it only matches once the client sends the converted main file: with trunk's client the full size stays a JPEG, where trunk and the server path both serve photo.webp.

Note the last row was not tested with a build of WordPress/gutenberg#87135. It replays the requests that PR sends (upload, an original sideload of the full size WebP with convert_format false, then finalize) against this branch, so it confirms the server side of the pairing only.

On the server path a full size WebP at the upload's dimensions only exists for images under the threshold. Over the threshold the full size is photo-scaled.webp and there is no unscaled WebP, which this PR also matches. The upload itself is kept as original_image in both cases.

Suggestions:

  • This should not be committed ahead of the Gutenberg change reaching core, since on its own it changes the full size format for images under the threshold. Committing it together with the gutenberg.sha bump that includes #87135 would avoid that window.
  • The new test covers create_item() only. A flow test with the filter active (upload, scaled sideload, finalize, permanent delete) asserting original_image is the JPEG and no files remain would cover the bug from the ticket, ideally with an original sideload case for the smaller image as well.
  • generate_sub_sizes false now also means the main file is not converted. Worth saying so in the parameter description and the @since note on create_item().
  • Adding the filter after the upload is stored looks like the right place, since wp_unique_filename() still reserves the .webp name. The inline comment could say that, it is the non-obvious part.

Unrelated to this PR: for the 2000x1332 image the client names medium_large 767x511 where the server path produces 768x511. Probably worth its own issue.

Before, on trunk (photo.jpg is left after "Delete permanently"):

trac-66763-before-trunk.mp4

After, with this PR:

trac-66763-after-pr-16119.mp4

Does the plan to land both together work for you? I'd rather not have the core change go in first.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants