Motivation:

aryan-25 · aryan-25 · commit f26ed0a168ed · 2025-12-01T12:02:49.000Z
Currently, when specifying port 0 in `HTTPServerConfiguration`, there is no public API to determine what port the `NIOHTTPServer` has actually been bound to.

Modifications:
- Added a `SocketAddress` type for representing a host address and port.
- Added an async `listeningAddress` property on `NIOHTTPServer` that returns a `SocketAddress` once the server has started listening (or throws an error if the address couldn't be bound to or if the server has closed).
- Added a `State` type to `NIOHTTPServer` for representing the idle, listening, and closed states and managing transitions between them.

Result:
Users can determine the address and port the `NIOHTTPServer` is listening at.
diff --git a/Sources/HTTPServer/NIOHTTPServer+ListeningAddress.swift b/Sources/HTTPServer/NIOHTTPServer+ListeningAddress.swift
@@ -0,0 +1,131 @@
+import NIOConcurrencyHelpers
+import NIOCore
+import NIOPosix
+
+enum ListeningAddressError: CustomStringConvertible, Error {
+    case addressOrPortNotAvailable
+    case unsupportedAddressType
+    case serverClosed
+
+    var description: String {
+        switch self {
+        case .addressOrPortNotAvailable:
+            return "Unable to retrieve the bound address or port from the underlying socket"
+        case .unsupportedAddressType:
+            return "Unsupported address type: only IPv4 and IPv6 are supported"
+        case .serverClosed:
+            return """
+                There is no listening address bound for this server: there may have been \
+                an error which caused the server to close, or it may have shut down.
+                """
+        }
+    }
+}
+
+@available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
+extension NIOHTTPServer {
+    func addressBound(_ address: NIOCore.SocketAddress?) throws {
+        switch self.listeningAddressState.withLockedValue({ $0.addressBound(address) }) {
+        case .succeedPromise(let promise, let boundAddress):
+            promise.succeed(boundAddress)
+        case .failPromise(let promise, let error):
+            promise.fail(error)
+        }
+    }
+    
+    /// The address the server is listening from.
+    ///
+    /// It is an `async` property because it will only return once the address has been successfully bound.
+    ///
+    /// - Throws: An error will be thrown if the address could not be bound or is not bound any longer because the
+    ///   server isn't listening anymore.
+    public var listeningAddress: SocketAddress {
+        get async throws {
+            return try await self.listeningAddressState
+              .withLockedValue { try $0.listeningAddressFuture }
+              .get()
+        }
+    }
+}
+
+@available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
+extension NIOHTTPServer {
+    enum State {
+        case idle(EventLoopPromise<SocketAddress>)
+        case listening(EventLoopFuture<SocketAddress>)
+        case closedOrInvalidAddress(ListeningAddressError)
+
+        var listeningAddressFuture: EventLoopFuture<SocketAddress> {
+            get throws {
+                switch self {
+                case .idle(let eventLoopPromise):
+                    return eventLoopPromise.futureResult
+                case .listening(let eventLoopFuture):
+                    return eventLoopFuture
+                case .closedOrInvalidAddress(let error):
+                    throw error
+                }
+            }
+        }
+
+        enum OnBound {
+            case succeedPromise(_ promise: EventLoopPromise<SocketAddress>, address: SocketAddress)
+            case failPromise(_ promise: EventLoopPromise<SocketAddress>, error: ListeningAddressError)
+        }
+
+        mutating func addressBound(_ address: NIOCore.SocketAddress?) -> OnBound {
+            switch self {
+            case .idle(let listeningAddressPromise):
+                do {
+                    let socketAddress = try SocketAddress(address)
+                    self = .listening(listeningAddressPromise.futureResult)
+                    return .succeedPromise(listeningAddressPromise, address: socketAddress)
+                }
+                catch {
+                    self = .closedOrInvalidAddress(error)
+                    return .failPromise(listeningAddressPromise, error: error)
+                }
+
+            case .listening, .closedOrInvalidAddress:
+                fatalError("Invalid state: addressBound should only be called once and when in idle state")
+            }
+        }
+
+        enum OnClose {
+            case failPromise(_ promise: EventLoopPromise<SocketAddress>, error: ListeningAddressError)
+            case doNothing
+        }
+
+        mutating func close() -> OnClose {
+            switch self {
+            case .idle(let listeningAddressPromise):
+                self = .closedOrInvalidAddress(.serverClosed)
+                return .failPromise(listeningAddressPromise, error: .serverClosed)
+
+            case .listening:
+                self = .closedOrInvalidAddress(.serverClosed)
+                return .doNothing
+
+            case .closedOrInvalidAddress:
+                return .doNothing
+            }
+        }
+    }
+}
+
+extension SocketAddress {
+    fileprivate init(_ address: NIOCore.SocketAddress?) throws(ListeningAddressError) {
+        guard let address, let port = address.port else {
+            throw ListeningAddressError.addressOrPortNotAvailable
+        }
+
+        switch address {
+        case .v4(let ipv4Address):
+            self.init(base: .ipv4(.init(host: ipv4Address.host, port: port)))
+        case .v6(let ipv6Address):
+            self.init(base: .ipv6(.init(host: ipv6Address.host, port: port)))
+        case .unixDomainSocket:
+            throw ListeningAddressError.unsupportedAddressType
+        }
+    }
+}
diff --git a/Sources/HTTPServer/NIOHTTPServer.swift b/Sources/HTTPServer/NIOHTTPServer.swift
@@ -1,6 +1,7 @@
 public import Logging
 import HTTPTypes
 import NIOCertificateReloading
+import NIOConcurrencyHelpers
 import NIOCore
 import NIOHTTP1
 import NIOHTTP2
@@ -69,6 +70,8 @@ public struct NIOHTTPServer: HTTPServerProtocol {
     private let logger: Logger
     private let configuration: HTTPServerConfiguration
 
+    var listeningAddressState: NIOLockedValueBox<State>
+
     /// Create a new ``HTTPServer`` implemented over `SwiftNIO`.
     /// - Parameters:
     ///   - logger: A logger instance for recording server events and debugging information.
@@ -79,6 +82,10 @@ public struct NIOHTTPServer: HTTPServerProtocol {
     ) {
         self.logger = logger
         self.configuration = configuration
+
+        // TODO: If we allow users to pass in an event loop, use that instead of the singleton MTELG.
+        let eventLoopGroup: MultiThreadedEventLoopGroup = .singletonMultiThreadedEventLoopGroup
+        self.listeningAddressState = .init(.idle(eventLoopGroup.any().makePromise()))
     }
 
     /// Starts an HTTP server with the specified request handler.
@@ -120,6 +127,15 @@ public struct NIOHTTPServer: HTTPServerProtocol {
     /// )
     /// ```
     public func serve(handler: some HTTPServerRequestHandler<RequestReader, ResponseWriter>) async throws {
+        defer {
+            switch self.listeningAddressState.withLockedValue({ $0.close() }) {
+            case .failPromise(let promise, let error):
+                promise.fail(error)
+            case .doNothing:
+                ()
+            }
+        }
+
         let asyncChannelConfiguration: NIOAsyncChannel<HTTPRequestPart, HTTPResponsePart>.Configuration
         switch self.configuration.backpressureStrategy.backing {
         case .watermark(let low, let high):
@@ -292,6 +308,8 @@ public struct NIOHTTPServer: HTTPServerProtocol {
                     }
                 }
 
+            try self.addressBound(serverChannel.channel.localAddress)
+
             try await withThrowingDiscardingTaskGroup { group in
                 try await serverChannel.executeThenClose { inbound in
                     for try await http1Channel in inbound {
@@ -354,6 +372,8 @@ public struct NIOHTTPServer: HTTPServerProtocol {
                     }
                 }
 
+            try self.addressBound(serverChannel.channel.localAddress)
+
             try await withThrowingDiscardingTaskGroup { group in
                 try await serverChannel.executeThenClose { inbound in
                     for try await upgradeResult in inbound {
diff --git a/Sources/HTTPServer/SocketAddress.swift b/Sources/HTTPServer/SocketAddress.swift
@@ -0,0 +1,75 @@
+import NIOCore
+
+/// Represents an IPv4 address.
+public struct IPv4: Hashable, Sendable {
+    /// The resolved host address.
+    public var host: String
+    /// The port to connect to.
+    public var port: Int
+
+    /// Creates a new IPv4 address.
+    ///
+    /// - Parameters:
+    ///   - host: Resolved host address.
+    ///   - port: Port to connect to.
+    public init(host: String, port: Int) {
+        self.host = host
+        self.port = port
+    }
+}
+
+/// Represents an IPv6 address.
+public struct IPv6: Hashable, Sendable {
+    /// The resolved host address.
+    public var host: String
+    /// The port to connect to.
+    public var port: Int
+
+    /// Creates a new IPv6 address.
+    ///
+    /// - Parameters:
+    ///   - host: Resolved host address.
+    ///   - port: Port to connect to.
+    public init(host: String, port: Int) {
+        self.host = host
+        self.port = port
+    }
+}
+
+/// An address to which a socket may connect or bind to.
+public struct SocketAddress: Hashable, Sendable {
+    enum Base: Hashable, Sendable {
+        case ipv4(IPv4)
+        case ipv6(IPv6)
+    }
+
+    let base: Base
+
+    /// Creates an IPv4 socket address.
+    public static func ipv4(host: String, port: Int) -> Self {
+        Self(base: .ipv4(.init(host: host, port: port)))
+    }
+
+    /// Creates an IPv6 socket address.
+    public static func ipv6(host: String, port: Int) -> Self {
+        Self(base: .ipv6(.init(host: host, port: port)))
+    }
+
+    /// Returns the address as an IPv4 address, if possible.
+    public var ipv4: IPv4? {
+        guard case .ipv4(let address) = self.base else {
+            return nil
+        }
+
+        return address
+    }
+
+    /// Returns the address as an IPv6 address, if possible.
+    public var ipv6: IPv6? {
+        guard case .ipv6(let address) = self.base else {
+            return nil
+        }
+
+        return address
+    }
+}
diff --git a/Tests/HTTPServerTests/NIOHTTPServerTests.swift b/Tests/HTTPServerTests/NIOHTTPServerTests.swift
@@ -0,0 +1,45 @@
+@testable import HTTPServer
+import HTTPTypes
+import Logging
+import NIOCore
+import NIOHTTP1
+import NIOHTTPTypes
+import NIOPosix
+import Testing
+
+#if canImport(Dispatch)
+import Dispatch
+#endif
+
+@Suite
+struct NIOHTTPServerTests {
+    @available(macOS 26.0, iOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0, *)
+    @Test("Obtain the listening address correctly")
+    func testListeningAddress() async throws {
+        let server = NIOHTTPServer(
+            logger: Logger(label: "Test"),
+            configuration: .init(bindTarget: .hostAndPort(host: "127.0.0.1", port: 1234))
+        )
+
+        try await withThrowingTaskGroup { group in
+            group.addTask {
+                try await server.serve { _, _, _, _ in
+                    return
+                }
+            }
+
+            let serverAddress = try await server.listeningAddress
+
+            let address = try #require(serverAddress.ipv4)
+            #expect(address.host == "127.0.0.1")
+            #expect(address.port == 1234)
+
+            group.cancelAll()
+        }
+
+        // Now that the server has shut down, try obtaining the listening address. This should result in an error.
+        await #expect(throws: ListeningAddressError.serverClosed) {
+            try await server.listeningAddress
+        }
+    }
+}
