REST API: post-process endpoint cannot be discovered from media creation endpoint

[kadamwhite]

Split out from #47987:

In #47987 we introduced a new /wp/v2/media/{id}/post-process endpoint, which may be hit with a POST to resume media processing in the event the initial POST to /wp/v2/media fails. Clients may know to utilize this new endpoint through the presence of a new non-standard header X-WP-Upload-Attachment-ID, but @rmccue caught that we do not provide any Link-based method of discovering the existence of this endpoint from the initial media collection. @TimothyBlynJacobs proposes using the edit-media relation for this link.

We should add an additional Link to the header of the failing POST response (or any POST response, potentially, with the understanding a link is only necessary in the event of failure). Implementing this Link was punted from 5.3 because the $response object on which we can call add_link was not available at the time we set the initial X-header, which we can work around but did not have time to resolve before the final 5.3 beta.

Aside: If we're able to resolve the order-of-operations issue, it's possible that the Link could become the preferred method of signalling that post-processing should occur, rather than the non-standard header. However the X-header is more appropriate for the other media paths in media.php and admin-ajax.php, so this may not be feasible.

[kunalpareek]

I've reviewed this ticket along with #47987 and looked at the current trunk code in class-wp-rest-attachments-controller.php.

The order-of-operations issue mentioned in the description is still present. In create_item(), X-WP-Upload-Attachment-ID is sent via a raw header() call before $response exists - $response is only available after wp_update_attachment_metadata(), which is exactly the step that can fatal.

However, the Link header does not need to be sent at the same moment as X-WP-Upload-Attachment-ID. It can be added to $response after it is constructed, alongside the existing Location header. On a successful response this makes the post-process endpoint formally discoverable. If the server fatals mid-processing, the client still has X-WP-Upload-Attachment-ID as the fallback signal both mechanisms complement each other.

I've attached a patch that adds $response->add_link() in create_item() using the ​https://api.w.org/action-post-process relation, following the api.w.org/action-* pattern used elsewhere in core. I avoided edit-media as that relation is already used by the /edit endpoint and would be semantically incorrect here.

Please let me know if the relation name needs adjustment or if the patch needs changes.