feat: add connectivity error classification to RequestExecutionErrorReason

[dcalhoun]

Description

The request executors map the underlying platform errors onto NonExistentSiteError and DeviceIsOfflineError, but consumers have to match those variants themselves to tell "this site could not be reached" from "this device has no connection". That is fragile — it breaks whenever the enum gains a case — and the knowledge belongs to the library rather than to each consumer.

Raised in GutenbergKit review feedback, tracked by GutenbergKit#578, where the iOS demo app hand-rolls both checks.

Changes

• RequestExecutionErrorReason::is_site_unreachable() and is_device_offline() as inherent methods, for Rust callers
• request_execution_error_reason_is_site_unreachable / ..._is_device_offline as #[uniffi::export] free functions, for the bindings
• Swift: properties on RequestExecutionErrorReason, plus convenience properties on WpApiError and RequestExecutionError. Both conform to a CarriesRequestExecutionErrorReason protocol, so the predicates are written once and each type supplies only the reason accessor.
• Kotlin: extension properties on RequestExecutionErrorReason
• Unit tests covering all 12 RequestExecutionErrorReason variants — two positives, ten negatives

Additive only; no behaviour change to existing APIs.

Why these live on the reason rather than on WpApiError

The variants are defined on RequestExecutionErrorReason, and the reason is what consumers actually hold:

• Swift — WordPress-iOS reaches the reason from two different outer errors (SelfHostedSiteAuthenticator.swift has both a log(error: WpApiError) and a log(error: RequestExecutionError) overload that funnel into the same reason handler). Predicates on the reason serve both; the WpApiError convenience property preserves the error.isCancellationError shape that Extensions/Error.swift already uses.
• Kotlin — WpApiException is largely internal plumbing; consumers hold a WpRequestResult. In GutenbergKit's Android demo app, all four files that touch wordpress-rs errors use WpRequestResult and none reference WpApiException. WpRequestResult.RequestExecutionFailed exposes reason directly.

Export shape

Follows application_passwords_url in login::url_discovery — a #[uniffi::export] free function taking a data-carrying uniffi::Enum by reference, with an inherent method behind it. Every #[uniffi::export] impl block in wp_api/src/ targets a uniffi::Object, so an exported impl on an enum would be novel here.

Open questions for review

1. Predicate placement. Reason vs. WpApiError. The evidence above favours the reason, but I did not find a precedent that settles it either way — happy to move them if you'd rather they sat on the error.
2. Naming. request_execution_error_reason_is_site_unreachable generates requestExecutionErrorReasonIsSiteUnreachable(reason:), which is a mouthful. The type-prefixed convention is my own; application_passwords_url is unprefixed. Shorter names welcome.
3. bool vs Option<bool>. Both patterns exist (FindApiRootFailure::is_network_error returns bool; is_application_passwords_disabled returns Option<bool>). I used bool since the question always applies to a reason, but flagging the choice.

Known limitation: the executor mappings disagree

The three executors do not classify the same failure the same way. The doc comments on both predicates now spell this out, but it is worth stating plainly here.

Connection refused — Kotlin is the odd one out:

Condition	Swift (SafeRequestExecutor)	Rust (ReqwestRequestExecutor)	Kotlin (WpRequestExecutor)
Host does not resolve	NonExistentSiteError	NonExistentSiteError	NonExistentSiteError
Connection refused	NonExistentSiteError (.cannotConnectToHost)	NonExistentSiteError (is_connect())	HttpError (ConnectException)
No route to host	NonExistentSiteError	NonExistentSiteError	HttpError (NoRouteToHostException)

So isSiteUnreachable returns true on Swift and false on Kotlin for the same real-world failure — e.g. a local dev server that is not running. Verified with okhttp 5.4.0: a closed local port throws java.net.ConnectException, which WpRequestExecutor maps to HttpError. HttpError is included as a negative case in the unit tests so the current behaviour is explicit.

Offline detection is platform-only. DeviceIsOfflineError is constructed exclusively by the Swift and Kotlin executors, which consult a NetworkAvailabilityProvider. ReqwestRequestExecutor has no such mapping, so for consumers that build it directly — wp_rs_web, wp_com_e2e — is_device_offline() is always false. Worse, an offline failure there fails DNS resolution and is reported as NonExistentSiteError, so is_site_unreachable() returns true instead. The two predicates are effectively inverted on that path.

Only a DNS failure means the same thing everywhere. Callers needing identical behaviour across all three executors should rely on that case alone until the mappings are aligned.

This PR does not change the mappings, because aligning Kotlin with Swift is a behaviour change with a downstream hazard. In WordPress-Android, MediaRSApiRestClient maps NonExistentSiteError to MediaErrorType.NOT_FOUND, and MediaDeleteService responds to NOT_FOUND by deleting the local media record. Today a refused connection yields HttpError → GENERIC_ERROR, which is non-destructive. Remapping without fixing that first would make an unreachable site look like deleted remote media. The when in question is exhaustive with no else, so the change would compile silently, and there is no test covering that arm.

Suggested sequencing, if the alignment is wanted: fix the WordPress-Android media mapping first, then align ConnectException (and probably NoRouteToHostException) in a follow-up PR here. Giving ReqwestRequestExecutor a way to report offline is a separate question, since it has no NetworkAvailabilityProvider equivalent.

Test plan

Automated:

• cargo test -p wp_api --lib api_error — 13 tests pass
• cargo fmt --all -- --check — clean
• cargo clippy -p wp_api --lib --all-features -- -D warnings — clean
• swift build --target WordPressAPI — 35/35 files, 0 errors
• ./gradlew :api:kotlin:compileKotlin :api:kotlin:detekt — BUILD SUCCESSFUL, 0 findings

Manual, via GutenbergKit's iOS demo app pointed at this PR's snapshot branch:

• wp-env stopped, network up → isSiteUnreachable, correct guidance shown
• Airplane mode with a saved account → isDeviceOffline, offline editor configuration applied
• Site host blocked in /etc/hosts, network up → isSiteUnreachable true and isDeviceOffline false on the same error, so the offline fallback correctly does not apply

Changelog

• I've added an entry to CHANGELOG.md under ## [Unreleased], using the Keep a Changelog categories (Added, Changed, Deprecated, Removed, Fixed, Security). Prefix breaking changes with **BREAKING:**.

[wpmobilebot]

XCFramework Build

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

.package(url: "https://github.com/automattic/wordpress-rs", branch: "pr-build/1488")

_{Built from e5525ed}

[dcalhoun]

Flagging the executor divergences documented in the Known limitation section above. I uncovered these while building this out, rather than knowing them going in.

Worth noting they're preexisting: nothing here changes how any executor classifies errors. The divergences exist on trunk today. What this PR adds is a single name spanning all three executors, which is what made them visible.

It remains unclear to me whether that's acceptable for now, whether the mappings should be aligned before this ships, or whether the Swift-only option from the original feedback is the better move. I welcome guidance on the best way to move forward with this.

[jkmassel]

This is as correct as it can be given the inconsistencies you noted. I did some research and opened several issues we can address after this PR lands.

I also opened #1493 with some suggested refinements from my research.