Summary

Fixes #76790

Enhances client-side media processing with two reliability improvements:

• Automatic retry with exponential backoff - Failed uploads are retried up to 3 times with increasing delays (1s, 2s, 4s) and jitter to prevent thundering herd.
• Network resilience - The upload queue pauses when the browser goes offline and resumes automatically when connectivity returns.

These are background features without user-facing controls. Defaults are wired into the core/upload-media store's initial state, so the feature is active out of the box wherever the upload pipeline is used; embedders can override or opt out by passing a different retry value (or undefined) to MediaUploadProvider.

Retry Flow

flowchart LR
    A[Upload] --> B[Processing]
    B --> C{Success?}
    C -->|Yes| D[Complete]
    C -->|No| E{Retryable?}
    E -->|No| F[Failed]
    E -->|Yes| G{Retries < 3?}
    G -->|No| F
    G -->|Yes| H[Wait with backoff]
    H -->|1s / 2s / 4s| B

Retryability is determined by matching the error message against a small set of patterns covering Chrome (Failed to fetch), Safari (Load failed), Node DNS/TCP errors (ECONNRESET, ETIMEDOUT, ENOTFOUND), and the @wordpress/api-fetch fetch_error message - the rejections actually thrown by the existing upload path. A typed UploadError/ErrorCode classification can layer on top in a follow-up without changing this PR's behavior.

Network Resilience

flowchart LR
    A[Upload Queue] --> B{Browser Online?}
    B -->|Yes| C[Continue Processing]
    B -->|No| D[Pause Queue]
    D --> E[Wait for reconnect]
    E -->|online event| F[Resume Queue]
    F --> C
    C --> G[Complete]

Screencasts

Test turning off the network mid-processing twice; each time once the connection was retired, the sideloading process continued:

Test starting offline - uploading was paused, then going online - uploading resumed:

Defaults

DEFAULT_STATE.settings.retry in the store is initialized from DEFAULT_RETRY_SETTINGS:

updateSettings is a shallow merge, so MediaUploadProvider settings={{ retry: undefined }} cleanly disables the feature.

Test coverage

@wordpress/upload-media (20 suites, 238 tests):

• calculateRetryDelay - exponential growth, max-delay cap, jitter bounds, multiplier variants
• shouldRetryError - every retryable message pattern (Chrome Failed to fetch, Safari Load failed, Node ECONNRESET/ETIMEDOUT/ENOTFOUND, apiFetch fetch_error), non-retryable messages, retry-count limits, regression test that an UploadError with a non-transient message (e.g. IMAGE_TRANSCODING_ERROR) is not retried
• Reducer cases for RetryItem (status reset, error clear, count increment, fresh AbortController), ScheduleRetry, PauseQueue/ResumeQueue (transitions, idempotency, state preservation)
• cancelItem retry integration - schedules retry for retryable errors, skips when silent, skips for non-retryable, skips when retry settings are absent, clears the pending timer on manual cancel, falls through to cancellation after exhausting maxRetryAttempts
• scheduleRetry / executeRetry - sets PendingRetry status, stores error and nextRetryTimestamp, fires the timer, replaces the aborted AbortController, no-ops when the item is missing or not in PendingRetry
• removeItem clears the retry timer to prevent timer-map leaks

@wordpress/editor (7 tests for useNetworkReconnect):

• No-ops when __clientSideMediaProcessing is false / undefined
• Registers and removes offline / online listeners
• Dispatches pauseQueue on offline, resumeQueue on online
• Handles multiple offline/online cycles
• Cleans up listeners on unmount

Test plan

Automated

• npx jest packages/upload-media --config test/unit/jest.config.js - 20 suites pass.
• npx jest packages/editor/src/components/provider/test/use-network-reconnect.js --config test/unit/jest.config.js - network reconnect hook tests pass.

Manual: retry with exponential backoff

Prereqs:

1. npm run wp-env start, open the editor in Chrome.
2. In DevTools console, confirm window.__clientSideMediaProcessing === true. If not, enable "Client-side media processing" under Gutenberg > Experiments and reload.
3. Confirm defaults are present:

   wp.data.select('core/upload-media').getSettings?.().retry

   Expect { maxRetryAttempts: 3, initialRetryDelayMs: 1000, maxRetryDelayMs: 30000, backoffMultiplier: 2, retryJitter: 0.1 }.

Force a transient failure:

4. Open DevTools > Network. Right-click any request and "Block request URL", adding a pattern that matches the upload endpoint (e.g. */wp-json/wp/v2/media*). Alternative: use a Chrome extension like Requestly or ModHeader to force HTTP 500 on that URL pattern. (The "go offline" toggle exercises a different code path - see the network resilience section below.)
5. Insert an Image block and upload a JPEG.

Observe the retries:

• In the Network panel, watch for repeat POSTs to /wp/v2/media for the same file. Expect 4 total attempts (initial + 3 retries) with gaps of approximately 1s, then 2s, then 4s. Jitter is +/-10%, so accept ~0.9-1.1s, ~1.8-2.2s, ~3.6-4.4s.
• Between attempts, in the console:

  wp.data.select('core/upload-media').getAllItems?.()
    .map(i => ({ status: i.status, retryCount: i.retryCount, nextRetryTimestamp: i.nextRetryTimestamp }))

  Expect status: 'PENDING_RETRY' while waiting, with a nextRetryTimestamp slightly in the future. Expect status: 'PROCESSING' and an incrementing retryCount during each in-flight POST.
• After the 4th failed POST, no further POSTs appear and the block displays the standard upload-failure notice.
• Remove the request-blocking rule before testing other scenarios.

Manual: network resilience

• Start an upload of a large file. While it is in flight, open DevTools > Network and toggle the throttling dropdown to "Offline". Verify the queue pauses: no further requests fire, items stay in the queue (getAllItems() shows them in PROCESSING / PENDING_RETRY rather than being cancelled).
• Toggle back to "No throttling" or your normal connection. Verify the queue resumes automatically (uploads continue, items in PENDING_RETRY re-execute) without any user action.
• Repeat the offline/online toggle a couple of times in the same session to confirm listeners are not stacking or leaking.

Manual: opt-out path (optional, for embedders)

• In the console, run wp.data.dispatch('core/upload-media').updateSettings({ retry: undefined }) (this requires unlock, so most testers can skip), then trigger a transient failure as above. Expect the item to fail on the first error with no retries.

Use of AI

Most code and this PR description written by Claude code with careful prompting. I reviewed the code manually.