Preserve getaddrinfo error code in SocketAddressError (apple#3558)

As observed by @weissi apple#3382
  ### Motivation:
When `getaddrinfo` fails, SwiftNIO throws `SocketAddressError.unknown`
which discards the error code. This makes it impossible for callers to
distinguish between different failure reasons (e.g., `EAI_NONAME` vs
`EAI_AGAIN`), which is needed for retry logic and diagnostics.
   
### Modifications:
- Add `SocketAddressError.UnknownHost` struct that carries `host`,
`port`, `errorCode` (from `getaddrinfo`), and `errorDescription` (from
`gai_strerror`).
- Update `SocketAddress.makeAddressResolvingHost` and
`GetaddrinfoResolver` to throw/fail with the new error type on both
POSIX and Windows paths.
- Update existing test catch blocks to use the new error type.
- Add `testGetaddrinfoErrorCodeIsPreserved` to verify the error code is
captured.
  ### Result:
Callers can now inspect the `getaddrinfo` error code when host
resolution fails, enabling more specific error handling. Resolves
apple#3382
  
### Questions for reviewer

1. **Should `case unknown(host:port:)` be deprecated?** — This enum case
is no longer thrown after this PR. Callers catching `.unknown` will
silently stop matching. Should I add
`@available(*, deprecated, renamed: "UnknownHost")` to provide a
migration path?

2. **Should the doc comment on `makeAddressResolvingHost` be updated?**
— The `- Throws:` line still references `SocketAddressError.unknown`
instead of the new
   `SocketAddressError.UnknownHost`.

---------

Co-authored-by: Si Beaumont <beaumont@apple.com>

Author: thisismanan

Sources/NIOCore/SocketAddresses.swift

@@ -23,6 +23,7 @@ import let WinSDK.INET6_ADDRSTRLEN
 
 import func WinSDK.FreeAddrInfoW
 import func WinSDK.GetAddrInfoW
+import func WinSDK.gai_strerrorA
 
 import struct WinSDK.ADDRESS_FAMILY
 import struct WinSDK.ADDRINFOW
@@ -64,6 +65,7 @@ import CNIOOpenBSD
 /// Special `Error` that may be thrown if we fail to create a `SocketAddress`.
 public enum SocketAddressError: Error, Equatable, Hashable {
     /// The host is unknown (could not be resolved).
+    @available(*, deprecated, message: "Use SocketAddressError.UnknownHost instead.")
     case unknown(host: String, port: Int)
     /// The requested `SocketAddress` is not supported.
     case unsupported
@@ -82,6 +84,27 @@ extension SocketAddressError {
             self.address = address
         }
     }
+
+    public struct UnknownHost: Error, Hashable, CustomStringConvertible {
+        public var host: String
+
+        public var port: Int
+
+        public var errorCode: Int
+
+        public var errorDescription: String
+
+        package init(host: String, port: Int, errorCode: Int, errorDescription: String) {
+            self.host = host
+            self.port = port
+            self.errorCode = errorCode
+            self.errorDescription = errorDescription
+        }
+
+        public var description: String {
+            "SocketAddressError.UnknownHost: \(self.errorDescription) (error \(self.errorCode)) for host \(self.host), port \(self.port)"
+        }
+    }
 }
 
 /// Represent a socket address to which we may want to connect or bind.
@@ -516,7 +539,7 @@ public enum SocketAddress: CustomStringConvertible, Sendable {
     ///   - host: the hostname which should be resolved.
     ///   - port: the port itself
     /// - Returns: the `SocketAddress` for the host / port pair.
-    /// - Throws: a `SocketAddressError.unknown` if we could not resolve the `host`, or `SocketAddressError.unsupported` if the address itself is not supported (yet).
+    /// - Throws: a `SocketAddressError.UnknownHost` if we could not resolve the `host`, or `SocketAddressError.unsupported` if the address itself is not supported (yet).
     public static func makeAddressResolvingHost(_ host: String, port: Int) throws -> SocketAddress {
         #if os(WASI)
         throw SocketAddressError.unsupported
@@ -529,7 +552,12 @@ public enum SocketAddress: CustomStringConvertible, Sendable {
 
                 let result = GetAddrInfoW(wszHost, wszPort, nil, &pResult)
                 guard result == 0 else {
-                    throw SocketAddressError.unknown(host: host, port: port)
+                    throw SocketAddressError.UnknownHost(
+                        host: host,
+                        port: port,
+                        errorCode: Int(result),
+                        errorDescription: String(cString: gai_strerrorA(result))
+                    )
                 }
 
                 defer {
@@ -554,8 +582,14 @@ public enum SocketAddress: CustomStringConvertible, Sendable {
         var info: UnsafeMutablePointer<addrinfo>?
 
         // FIXME: this is blocking!
-        if getaddrinfo(host, String(port), nil, &info) != 0 {
-            throw SocketAddressError.unknown(host: host, port: port)
+        let rc = getaddrinfo(host, String(port), nil, &info)
+        guard rc == 0 else {
+            throw SocketAddressError.UnknownHost(
+                host: host,
+                port: port,
+                errorCode: Int(rc),
+                errorDescription: String(cString: gai_strerror(rc))
+            )
         }
 
         defer {

Sources/NIOPosix/GetaddrinfoResolver.swift

@@ -147,7 +147,14 @@ internal final class GetaddrinfoResolver: Resolver, Sendable {
 
                 let iResult = GetAddrInfoW(wszHost, wszPort, &aiHints, &pResult)
                 guard iResult == 0 else {
-                    self.fail(SocketAddressError.unknown(host: host, port: port))
+                    self.fail(
+                        SocketAddressError.UnknownHost(
+                            host: host,
+                            port: port,
+                            errorCode: Int(iResult),
+                            errorDescription: String(cString: gai_strerrorA(iResult))
+                        )
+                    )
                     return
                 }
 
@@ -165,8 +172,16 @@ internal final class GetaddrinfoResolver: Resolver, Sendable {
         var hint = addrinfo()
         hint.ai_socktype = self.aiSocktype.rawValue
         hint.ai_protocol = self.aiProtocol.rawValue
-        guard getaddrinfo(host, String(port), &hint, &info) == 0 else {
-            self.fail(SocketAddressError.unknown(host: host, port: port))
+        let rc = getaddrinfo(host, String(port), &hint, &info)
+        guard rc == 0 else {
+            self.fail(
+                SocketAddressError.UnknownHost(
+                    host: host,
+                    port: port,
+                    errorCode: Int(rc),
+                    errorDescription: String(cString: gai_strerror(rc))
+                )
+            )
             return
         }
 

Tests/NIOPosixTests/DatagramChannelTests.swift

@@ -761,14 +761,9 @@ class DatagramChannelTests: XCTestCase {
                     let channel2 = try buildChannel(group: self.group, host: "::1")
                     try channel2.setOption(.explicitCongestionNotification, value: false).wait()
                     XCTAssertFalse(try channel2.getOption(.explicitCongestionNotification).wait())
-                } catch let error as SocketAddressError {
-                    switch error {
-                    case .unknown:
-                        // IPv6 resolution can fail even if supported.
-                        return
-                    case .unsupported, .unixDomainSocketPathTooLong, .failedToParseIPString:
-                        throw error
-                    }
+                } catch is SocketAddressError.UnknownHost {
+                    // IPv6 resolution can fail even if supported.
+                    return
                 }
             }()
         )
@@ -969,14 +964,9 @@ class DatagramChannelTests: XCTestCase {
                     let channel2 = try buildChannel(group: self.group, host: "::1")
                     try channel2.setOption(.receivePacketInfo, value: false).wait()
                     XCTAssertFalse(try channel2.getOption(.receivePacketInfo).wait())
-                } catch let error as SocketAddressError {
-                    switch error {
-                    case .unknown:
-                        // IPv6 resolution can fail even if supported.
-                        return
-                    case .unsupported, .unixDomainSocketPathTooLong, .failedToParseIPString:
-                        throw error
-                    }
+                } catch is SocketAddressError.UnknownHost {
+                    // IPv6 resolution can fail even if supported.
+                    return
                 }
             }()
         )

Tests/NIOPosixTests/EchoServerClientTest.swift

@@ -958,15 +958,9 @@ class EchoServerClientTest: XCTestCase {
                         sem.signal()
                         return channel.eventLoop.makeSucceededFuture(())
                     }.bind(host: host, port: 0).wait()
-            } catch let e as SocketAddressError {
-                if case .unknown(host, port: 0) = e {
-                    // this can happen if the system isn't configured for both IPv4 and IPv6
-                    continue
-                } else {
-                    // nope, that's a different socket error
-                    XCTFail("unexpected SocketAddressError: \(e)")
-                    break
-                }
+            } catch let e as SocketAddressError.UnknownHost where e.host == host && e.port == 0 {
+                // this can happen if the system isn't configured for both IPv4 and IPv6
+                continue
             } catch {
                 // other unknown error
                 XCTFail("unexpected error: \(error)")

Tests/NIOPosixTests/SocketAddressTest.swift

@@ -699,4 +699,18 @@ class SocketAddressTest: XCTestCase {
             XCTAssertEqual(SocketAddress(ipv6MaskForPrefix: vector.0), vector.1)
         }
     }
+
+    func testGetaddrinfoErrorCodeIsPreserved() {
+        // .invalid TLD is guaranteed by RFC 6761 to never resolve.
+        XCTAssertThrowsError(try SocketAddress.makeAddressResolvingHost("somehost.invalid", port: 80)) { error in
+            guard let unknownHostError = error as? SocketAddressError.UnknownHost else {
+                XCTFail("Expected SocketAddressError.UnknownHost, got \(type(of: error)): \(error)")
+                return
+            }
+            XCTAssertEqual(unknownHostError.host, "somehost.invalid")
+            XCTAssertEqual(unknownHostError.port, 80)
+            XCTAssertNotEqual(unknownHostError.errorCode, 0, "Error code should be non-zero")
+            XCTAssertFalse(unknownHostError.errorDescription.isEmpty, "Error description should not be empty")
+        }
+    }
 }