Add ConnectionError; make isSiteUnreachable cover DNS + connection failures (#1524)

* Narrow NonExistentSiteError to DNS-only

A refused connection (the host resolves, but nothing is listening) was
classified as NonExistentSiteError on Swift but not on Kotlin or reqwest, so
the isSiteUnreachable predicate from #1488 returned a different answer per
platform for the same outage.

Move Swift's .cannotConnectToHost out of the non-existent-site set, leaving
NonExistentSiteError to mean a DNS-resolution failure. The follow-up commit
gives refused/unreachable connections a dedicated ConnectionError reason
across all three executors.

Refs #1495.

* Add ConnectionError variant; broaden isSiteUnreachable to cover it

Refused and unreachable connections were lumped into the generic HttpError
(Kotlin, reqwest) or, before the previous commit, NonExistentSiteError
(Swift). None of the existing reasons isolate "the host resolved, but a
connection couldn't be established."

Add a ConnectionError { reason } variant and route connection-establishment
failures to it across all three executors:
- reqwest: io::ErrorKind::{ConnectionRefused, HostUnreachable, NetworkUnreachable}
- Kotlin: ConnectException, NoRouteToHostException
- Swift: URLError.cannotConnectToHost

Broaden is_site_unreachable to match NonExistentSiteError | ConnectionError, so
it is one portable "couldn't reach the site" signal that answers the same on
every executor. Callers that need to tell a bad domain from a down server match
the two variants directly.

A connect timeout is deliberately excluded: neither reqwest's is_timeout() nor
OkHttp's SocketTimeoutException separates a connect timeout from a read timeout,
so those stay HttpTimeoutError.

Refs #1495.

Author: jkmassel

CHANGELOG.md

@@ -15,7 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - WordPress.com `POST /sites/<site_id>/domains/primary` endpoint for setting a site's primary domain
 - WordPress.com `GET /sites/<site_id>/stats/post/<post_id>` endpoint for a post's view history, like count, comment count, and metadata
 - WordPress.com `GET /sites/<site_id>/plans` endpoint for listing the plans a site can buy, priced for that site, with the plan it's currently on flagged.
-- `RequestExecutionErrorReason` gained `isSiteUnreachable` and `isDeviceOffline` for distinguishing a site that could not be reached (most reliably, a DNS failure) from a device with no network connection. Previously consumers had to match the `NonExistentSiteError` / `DeviceIsOfflineError` variants themselves. Available on both platforms as properties on the reason, which is reachable from `WpRequestResult.RequestExecutionFailed` and `WpApiException.RequestExecutionFailed` on Kotlin. Swift additionally exposes both as convenience properties on `WpApiError` and `RequestExecutionError`.
+- `RequestExecutionErrorReason` gained `isSiteUnreachable` and `isDeviceOffline` for distinguishing a site that could not be reached (the host did not resolve, or a connection to it could not be established) from a device with no network connection. Previously consumers had to match the `NonExistentSiteError` / `DeviceIsOfflineError` variants themselves. Available on both platforms as properties on the reason, which is reachable from `WpRequestResult.RequestExecutionFailed` and `WpApiException.RequestExecutionFailed` on Kotlin. Swift additionally exposes both as convenience properties on `WpApiError` and `RequestExecutionError`.
+- **BREAKING:** `RequestExecutionErrorReason` gained a `ConnectionError` variant — the host resolved, but no connection to the server could be established (the connection was refused, there was no route, or the host was unreachable). Exhaustive matches over `RequestExecutionErrorReason` (Swift `switch`, Kotlin `when`, Rust `match`) must now handle the new case. `isSiteUnreachable` covers it alongside DNS failures, so it's a single portable "we couldn't reach the site" signal that returns the same answer on every executor; match `NonExistentSiteError` / `ConnectionError` directly to tell a bad domain apart from a server that's down. Refused and unreachable connections previously classified as the generic `HttpError` on Kotlin and reqwest. A connect timeout is not included; it remains `HttpTimeoutError`.
 
 ### Changed
 
@@ -42,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Swift: `WpRequestExecutor.sleep(millis:)` converted milliseconds to nanoseconds with the wrong factor (`* 1_000` instead of `* 1_000_000`), so it slept 1000× too short — a `Retry-After: 30` waited 30 ms instead of 30 s. `RetryAfterMiddleware` then re-sent immediately, the server kept returning 429, and after `max_retries` the caller observed `MisconfiguredRateLimitError` where honoring the backoff would usually have succeeded. The executor now waits the full interval, and no longer risks a `fatalError` if the sleep's task is cancelled.
 - Swift: Classify invalid-SSL failures from the failed handshake's `SecTrust` (`URLError.failureURLPeerTrust`), via `SecTrustCopyCertificateChain`, instead of reading the undocumented `NSErrorPeerCertificateChainKey` `userInfo` string that has no public constant. Behavior is unchanged on every platform: iOS/macOS/tvOS still surface the presented certificate as `certificateNotValidForName`, and watchOS — which exposes no peer trust — still degrades to `genericSslError`. ([#1510](https://github.com/Automattic/wordpress-rs/issues/1510))
+- `isSiteUnreachable` now returns the same answer for a refused connection — the host resolves, but nothing is listening (server down, wrong port) — on every executor. Previously it was `NonExistentSiteError` on Swift (so `isSiteUnreachable` was `true`) but the generic `HttpError` on Kotlin and reqwest (so it was `false`); a refused connection is now a `ConnectionError` everywhere, which `isSiteUnreachable` covers. `NonExistentSiteError` is reserved for a DNS-resolution failure.
 
 ### Security
 

native/kotlin/api/kotlin/src/integrationTest/kotlin/WpRequestExecutorTest.kt

@@ -249,6 +249,38 @@ class WpRequestExecutorTest {
             assertTrue(loggedErrors.isEmpty(), "cancellation should not be logged as an error: $loggedErrors")
         }
 
+    @Test
+    fun `refused connection is mapped to ConnectionError`() = runTest {
+        // Reserve a port with a throwaway server, then shut it down so nothing is
+        // listening — a connection to it is refused (ConnectException). That must
+        // classify as ConnectionError, not the generic HttpError and not
+        // NonExistentSiteError (which is reserved for DNS failures).
+        val closedServer = MockWebServer()
+        closedServer.start()
+        val refusedUrl = closedServer.url("/wp-json")
+        closedServer.shutdown()
+
+        val executor = WpRequestExecutor(
+            httpClient = WpHttpClient.CustomOkHttpClient(OkHttpClient()),
+            networkAvailabilityProvider = NetworkAvailabilityProvider { true }
+        )
+
+        val apiClient = WpApiClient(
+            wpOrgSiteApiRootUrl = URI(refusedUrl.toString()).toURL(),
+            authProvider = WpAuthenticationProvider.none(),
+            requestExecutor = executor
+        )
+
+        val result = apiClient.request { requestBuilder ->
+            requestBuilder.users().listWithEditContext(params = UserListParams())
+        }
+
+        assertIs<WpRequestResult.RequestExecutionFailed<*>>(result)
+        assertIs<RequestExecutionErrorReason.ConnectionError>(
+            (result as WpRequestResult.RequestExecutionFailed<*>).reason
+        )
+    }
+
     /**
      * Resolves media fixtures (e.g. `test_media.jpg`) from the test classpath so uploads can be
      * built without touching the real filesystem layout.

native/kotlin/api/kotlin/src/main/kotlin/rs/wordpress/api/kotlin/RequestExecutionErrorReasonExtensions.kt

@@ -8,26 +8,30 @@ import uniffi.wp_api.requestExecutionErrorReasonIsSiteUnreachable
  * Extension properties for classifying connectivity failures.
  *
  * The request executor maps the underlying platform errors onto
- * [RequestExecutionErrorReason.NonExistentSiteError] and
+ * [RequestExecutionErrorReason.NonExistentSiteError],
+ * [RequestExecutionErrorReason.ConnectionError], and
  * [RequestExecutionErrorReason.DeviceIsOfflineError]. These properties expose
- * that distinction without requiring callers to match the variants themselves.
+ * those distinctions without requiring callers to match the variants themselves.
  *
  * The reason is available as `reason` on `WpRequestResult.RequestExecutionFailed`
  * and on `WpApiException.RequestExecutionFailed`.
  */
 
 /**
- * Whether the site could not be reached — most reliably, the host did not
- * resolve.
+ * Whether the site could not be reached at all — either its host did not resolve
+ * ([RequestExecutionErrorReason.NonExistentSiteError]) or the host resolved but
+ * no connection could be established
+ * ([RequestExecutionErrorReason.ConnectionError]).
  *
- * Distinct from [isDeviceOffline]: this indicates a problem reaching *this
- * particular site*, not a loss of device connectivity.
+ * This is a portable signal: every executor classifies both failure modes the
+ * same way. To tell them apart — a domain that doesn't resolve vs. a server
+ * that's down — match the two variants directly.
  *
- * Note that a refused connection (the host resolves, but nothing is listening)
- * is reported here as an HTTP error rather than an unreachable site, whereas
- * the Swift executor reports it as unreachable. Only a DNS failure is treated
- * as an unreachable site by every executor. A malformed site URL never reaches
- * this predicate; it surfaces as `WpApiException.SiteUrlParsingException`.
+ * Distinct from [isDeviceOffline]: this indicates a problem reaching *this
+ * particular site*, not a loss of device connectivity. A connect timeout is not
+ * included (it stays [RequestExecutionErrorReason.HttpTimeoutError]); a malformed
+ * site URL never reaches this predicate either — it surfaces as
+ * `WpApiException.SiteUrlParsingException`.
  */
 val RequestExecutionErrorReason.isSiteUnreachable: Boolean
     get() = requestExecutionErrorReasonIsSiteUnreachable(this)

native/kotlin/api/kotlin/src/main/kotlin/rs/wordpress/api/kotlin/WpRequestExecutor.kt

@@ -236,7 +236,7 @@ class WpRequestExecutor @JvmOverloads constructor(
         } catch (e: NoRouteToHostException) {
             RequestExecutionErrorReason.noRouteToHost(e)
         } catch (e: ConnectException) {
-            RequestExecutionErrorReason.HttpError(reason = "Connection failed: ${e.localizedMessage}")
+            RequestExecutionErrorReason.ConnectionError(reason = "Connection failed: ${e.localizedMessage}")
         } catch (e: SocketTimeoutException) {
             RequestExecutionErrorReason.HttpTimeoutError
         } catch (e: InterruptedIOException) {

native/kotlin/example/composeApp/src/commonMain/kotlin/rs/wordpress/example/shared/ui/components/ErrorMessage.kt

@@ -39,6 +39,7 @@ private fun RequestExecutionErrorReason.description(): String = when (this) {
     is RequestExecutionErrorReason.HttpTimeoutError -> "Request timed out"
     is RequestExecutionErrorReason.InvalidSslError -> "SSL error: $reason"
     is RequestExecutionErrorReason.NonExistentSiteError -> errorMessage ?: "Site not found"
+    is RequestExecutionErrorReason.ConnectionError -> "Could not connect to the server: $reason"
     is RequestExecutionErrorReason.HttpAuthenticationRequiredError -> "Authentication required for $hostname"
     is RequestExecutionErrorReason.HttpAuthenticationRejectedError -> "Authentication rejected for $hostname"
     is RequestExecutionErrorReason.HttpForbiddenError -> "Access forbidden for $hostname"

native/swift/Sources/wordpress-api/Extensions.swift

@@ -50,20 +50,24 @@ extension WpApiError {
 }
 
 extension RequestExecutionErrorReason {
-    /// Whether the site could not be reached — most reliably, the host did not
-    /// resolve.
+    /// Whether the site could not be reached at all — either its host did not
+    /// resolve (`NonExistentSiteError`) or the host resolved but no connection
+    /// could be established (`ConnectionError`).
+    ///
+    /// This is a portable signal: every executor classifies both failure modes
+    /// the same way. To tell them apart — a domain that doesn't resolve vs. a
+    /// server that's down — match `.nonExistentSiteError` and `.connectionError`
+    /// directly.
     ///
     /// Distinct from ``isDeviceOffline``: this indicates a problem reaching
     /// *this particular site*, not a loss of device connectivity.
     ///
-    /// - Note: A refused connection (the host resolves, but nothing is
-    ///   listening) is classified differently per platform — Swift reports it
-    ///   here, Kotlin reports it as an HTTP error. Only a DNS failure is treated
-    ///   as an unreachable site by every executor. A site URL rejected while
-    ///   parsing surfaces as `WpApiError.SiteUrlParsingError` and never reaches
-    ///   this predicate; a `.badURL` that only `URLSession` rejects at send time
-    ///   is classified here for lack of a dedicated invalid-URL case, though no
-    ///   known URL actually reaches that branch.
+    /// - Note: A connect timeout is not included (it stays `HttpTimeoutError`). A
+    ///   site URL rejected while parsing surfaces as
+    ///   `WpApiError.SiteUrlParsingError` and never reaches this predicate; a
+    ///   `.badURL` that only `URLSession` rejects at send time is classified as
+    ///   `NonExistentSiteError` for lack of a dedicated invalid-URL case, though
+    ///   no known URL actually reaches that branch.
     public var isSiteUnreachable: Bool {
         requestExecutionErrorReasonIsSiteUnreachable(reason: self)
     }
@@ -88,11 +92,10 @@ public protocol CarriesRequestExecutionErrorReason {
 }
 
 public extension CarriesRequestExecutionErrorReason {
-    /// Whether the site could not be reached — most reliably, the host did not
-    /// resolve.
+    /// Whether the site could not be reached at all — the host did not resolve,
+    /// or the connection could not be established.
     ///
-    /// See ``RequestExecutionErrorReason/isSiteUnreachable`` for the platform
-    /// differences that apply.
+    /// See ``RequestExecutionErrorReason/isSiteUnreachable``.
     var isSiteUnreachable: Bool {
         executionErrorReason?.isSiteUnreachable ?? false
     }

native/swift/Sources/wordpress-api/SafeRequestExecutor.swift

@@ -98,6 +98,10 @@ public final class WpRequestExecutor: SafeRequestExecutor {
                 return handleNonExistentSiteError(error, for: request)
             }
 
+            if errorIsConnectionError(error) {
+                return handleConnectionError(error, for: request)
+            }
+
             if errorIsDeviceIsOffline(error) {
                 return handleDeviceIsOfflineError(error, for: request)
             }
@@ -225,6 +229,21 @@ public final class WpRequestExecutor: SafeRequestExecutor {
         )
     }
 
+    func handleConnectionError(
+        _ error: Error,
+        for request: NetworkRequestContent
+    ) -> Result<WpNetworkResponse, RequestExecutionError> {
+        .failure(
+            .RequestExecutionFailed(
+                statusCode: nil,
+                redirects: executorDelegate.redirects(for: request.requestId()),
+                reason: .connectionError(reason: error.localizedDescription),
+                requestUrl: request.url(),
+                requestMethod: request.method()
+            )
+        )
+    }
+
     public func sleep(millis: UInt64) async {
         // `try?`: `Task.sleep` only throws on cancellation, which this non-throwing `sleep`
         // leaves to the request machinery to handle.
@@ -247,24 +266,42 @@ public final class WpRequestExecutor: SafeRequestExecutor {
     }
 
     private func errorIsNonExistentSiteError(_ error: Error) -> Bool {
-        // `.badURL` is grouped with the non-existent-site errors deliberately.
-        // A malformed URL has no dedicated classification at the executor layer:
-        // `RequestExecutionError` can't produce `WpApiError.SiteUrlParsingError`
-        // (that's a parse-time error, one layer up) and `RequestExecutionErrorReason`
-        // has no invalid-URL case, so `NonExistentSiteError` is the nearest fit.
-        // In practice we could not construct a URL that reaches this branch:
-        // request URLs are normalized by the Rust `url` crate before they arrive,
-        // and modern Foundation repairs the leftovers (e.g. an invalid `%zz`
-        // becomes `%25zz`) rather than raising `.badURL`. It's kept for completeness.
+        // A refused connection (`.cannotConnectToHost` — the host resolves, but
+        // nothing is listening) is deliberately *not* here: it is a failed
+        // connection handled by `errorIsConnectionError`, matching the Kotlin and
+        // reqwest executors. This keeps `NonExistentSiteError` — and the
+        // `isSiteUnreachable` predicate built on it — a portable "the host does
+        // not resolve" signal across platforms. See #1495.
+        //
+        // `.badURL` is grouped here deliberately. A malformed URL has no dedicated
+        // classification at the executor layer: `RequestExecutionError` can't
+        // produce `WpApiError.SiteUrlParsingError` (that's a parse-time error, one
+        // layer up) and `RequestExecutionErrorReason` has no invalid-URL case, so
+        // `NonExistentSiteError` is the nearest fit. In practice we could not
+        // construct a URL that reaches this branch: request URLs are normalized by
+        // the Rust `url` crate before they arrive, and modern Foundation repairs
+        // the leftovers (e.g. an invalid `%zz` becomes `%25zz`) rather than raising
+        // `.badURL`. It's kept for completeness.
         [
             .badURL,
-            .cannotConnectToHost,
             .cannotFindHost,
             .dnsLookupFailed
         ]
         .contains((error as? URLError)?.code)
     }
 
+    private func errorIsConnectionError(_ error: Error) -> Bool {
+        // A failed connection: the host resolves, but nothing accepts the
+        // connection (server down, wrong port, not listening, or no route). It
+        // maps to `ConnectionError` — the same classification the Kotlin
+        // (`ConnectException` / `NoRouteToHostException`) and reqwest (io-error)
+        // executors use. `isSiteUnreachable` covers it alongside a DNS failure.
+        [
+            .cannotConnectToHost
+        ]
+        .contains((error as? URLError)?.code)
+    }
+
     private func errorIsDeviceIsOffline(_ error: Error) -> Bool {
         [
             .networkConnectionLost,

native/swift/Tests/wordpress-api/WordPressAPITests.swift

@@ -90,6 +90,56 @@ struct WordPressAPITests {
         let details = try await api.apiRoot.get()
         #expect(details.data.siteUrlString() == "https://vanilla.wpmt.co")
     }
+
+    // A refused connection — the host resolves (loopback), but nothing is
+    // listening on the port — must be classified as `.connectionError`, matching
+    // the Kotlin and reqwest executors. It must *not* be `.nonExistentSiteError`,
+    // which is reserved for DNS failures so `isSiteUnreachable` stays a portable
+    // "the host does not resolve" signal across platforms. See #1495.
+    @Test(.enabled(if: !isLinux()))
+    func testRefusedConnectionIsConnectionError() async throws {
+        // Port 1 on loopback is privileged, so nothing is bound in any test
+        // environment, and the OS refuses the connection immediately
+        // (`URLError.cannotConnectToHost`).
+        let api = try WordPressAPI(
+            siteInfo: .selfHosted(
+                siteUrl: ParsedUrl.parse(input: "http://127.0.0.1:1"),
+                apiRoot: ParsedUrl.parse(input: "http://127.0.0.1:1/wp-json")
+            ),
+            authenticationProvider: .none(),
+            executor: WpRequestExecutor(urlSession: .init(configuration: .ephemeral)),
+            middlewarePipeline: .default,
+            appNotifier: nil
+        )
+
+        await #expect(
+            performing: {
+                _ = try await api.apiRoot.get()
+            },
+            throws: { error in
+                guard
+                    let apiError = error as? WpApiError,
+                    case .RequestExecutionFailed(
+                        statusCode: _,
+                        redirects: _,
+                        reason: let reason,
+                        requestUrl: _,
+                        requestMethod: _
+                    ) = apiError
+                else {
+                    Issue.record("Expected WpApiError.RequestExecutionFailed, got: \(error)")
+                    return false
+                }
+
+                guard case .connectionError = reason else {
+                    Issue.record("A refused connection must be `.connectionError`, got: \(reason)")
+                    return false
+                }
+
+                return true
+            }
+        )
+    }
 }
 
 private actor CounterMiddleware: Middleware {