Split the media delegate into MediaProcessor and MediaUploader

[jkmassel]

Stacked on #594. Makes performing a media upload — and retrying it — a single, all-or-nothing responsibility: either GutenbergKit performs the upload and owns its retries, or the host does (say, to run it through its own networking so it can log every request). Both go to the same configured site; the only difference is who executes the requests. There's no in-between where the host performs the upload but GutenbergKit retries it.

Summary

Two protocols replace the single MediaUploadDelegate:

• MediaProcessor — transform the file before upload; GutenbergKit performs the upload and owns its retries. The common, safe extension point.
• MediaUploader — perform the upload yourself (your own networking, logging, retry policy, a background session) and own its whole lifecycle: retries, recovery, and cleanup. Receives a MediaUpload value carrying the file, its metadata, the editor's non-file form fields (post, additionalData), and the request query (?_embed).

EditorViewController / GutenbergView own whichever handler you set — their properties are strong on both platforms, so you can assign one and drop your own reference (just don't strongly retain the editor back).

Breaking: hosts migrate mediaUploadDelegate → mediaProcessor / mediaUploader.

The problem with the old design

When an upload fatals in server-side post-processing, it has to be retried: core retries POST …/post-process up to 5×, and cleans up the orphan if that fails.

MediaUploadDelegate.uploadFile let a host perform the upload itself by returning the raw response it received. But that split one upload's HTTP across two owners: the host performed the POST /wp/v2/media, then core — reading that raw response — drove the post-process retries (and the orphan cleanup) behind it. A host that took over uploads to run them through its own stack still didn't own the retries; those went out through the browser, not the host. Delivery and its retries were owned by different parties.

The fix

Make the upload and its retries one unit with one owner:

• MediaProcessor (handlesFile, processFile) only transforms the file. It never performs the upload, so GutenbergKit performs it and owns the retries. The extension point almost every host wants.
• MediaUploader (upload(_:)) performs the upload on the host's own stack and owns the whole lifecycle. upload returns the finished attachment or throws — there's no raw response for core to retry behind it, so the host drives its own post-process recovery and force-deletes its own orphan on terminal failure. The MediaUpload it receives carries everything needed to reproduce a native request — the file, the editor's post / additionalData fields, and the ?_embed query — so a host upload attaches to its post instead of landing as an unattached orphan.

So it's all-or-nothing: the host performs the upload and its retries, or GutenbergKit does — never a split. An uploader and GutenbergKit's built-in default both target the same configured site; the choice is only who executes the requests.

Media deletes always relay to the default uploader (the configured site) — every attachment lives there, even one a host uploader delivered, so there's no per-host delete path. The server starts if either handler is set and builds a default uploader whenever site credentials are present (it delivers GutenbergKit's own uploads and relays every delete). Because deletes need it, a mediaUploader set without site credentials is a configuration error and traps at startup rather than starting a server whose every delete would 500. MediaUploadResponse is now internal — it's no longer on any public API.

Accepted Risk / Out of Scope

• The configured-site delete relay isn't scoped. GutenbergKit relays core's cleanup DELETE to the configured site, but the relay can't distinguish it from any other DELETE the WebView sends — a client-side-compromised editor (a supply-chain-tampered JS bundle, or editor XSS) holding the loopback token could force-delete arbitrary media there. We accept this: such a script already has broad write access via allowed methods, and a server-side compromise (a malicious plugin) deletes media directly without the editor. An earlier revision carried a per-session ledger to scope the relay; it's dropped as not worth the cost for a client-side-only threat.

Test Plan

• iOS host suite green
• Android unit suites green — MediaUploadServer, GutenbergView
• SwiftLint + Detekt clean
• iOS demo app builds (xcodebuild, Xcode 26.4.1); Android demo builds (Detekt compiles it)
• Migrate mediaUploadDelegate in WordPress-iOS / WordPress-Android / Jetpack

Related

• Stacked on fix: recover media uploads that fail server-side post-processing #594; merges into it.

[wpmobilebot]

XCFramework Build

This PR's XCFramework is available for testing. Add the following to your Package.swift:

.package(url: "https://github.com/wordpress-mobile/GutenbergKit", branch: "pr-build/621")

_{Built from 2bbc65d}