Add opt-in API for channels to expose their underlying transport (#3509)

## Motivation

NIO channels abstract over an underlying transport mechanisms (sockets,
pipes, etc.), which users typically need not interact with. However,
there are scenarios where users need direct access to the underlying
transport for low-level operations that work outside NIOs abstraction.
One example is performing out out-of-band operations on the underlying
file descriptor for a socket-based channel.

This PR adds a structured way to access the underlying transport of a
channel, for channels that choose to implement it.

## Modifications

- Add a new `public protocol
NIOTransportAccessibleChannelCore<Transport>` which provides a scoped
`withUnsafeTransport(_:)`, used for channel implementations to opt-in.
- Add conformance to
`NIOTransportAccessibleChannel<NIOBSDSocket.Handle>` for
`BaseSocketChannel`, to make this API available for all socket-based
channels, including channels returned from the socket-based bootstrap
public APIs.
- Add public API
`ChannelPipeline.SynchronousOperations.withUnsafeTransportIfAvailable(_:)`

Note that not all channels need to or should their transport, which is
why this was added as an additional protocol that refines `ChannelCore`,
vs. extending `Channel` or `ChannelCore` with a default implementation.

The protocol uses a primary associated type allowing channels to provide
typed access to the transport. E.g. this could be used in NIO Transport
Services to expose the underlying `NWConnection`, if desired.

The method itself is spelled with "unsafe", uses scoped access, and has
clear documentation that users must not violated any of NIOs assumptions
about the state of the underlying transport. It's very much not intended
for every day use. It being on `ChannelCore` should defer users of the
low-level API, since `Channel._channelCore` is marked as for NIO
internal use, and the public `withUnsafeTransportIfAvailable(_:)` will
take care of the runtime checks for channels that have opted into this
API.

## Result

- New opt-in API for channel implementations to expose their underlying
transport
- All socket-based channels from NIOPosix now expose the underlying
socket file descriptor
- New API
`ChannelPipeline.SynchronousOperations.withUnsafeTransportIfAvailable(_:)`
for users

---------

Co-authored-by: Agam Dua <agam_dua@apple.com>

Author: simonjbeaumont

Sources/NIOCore/BSDSocketAPI.swift

@@ -129,6 +129,16 @@ public enum NIOBSDSocket: Sendable {
     #else
     public typealias Handle = CInt
     #endif
+    public struct PipeHandle {
+        public var input: Handle
+        public var output: Handle
+
+        @inlinable
+        public init(input: Handle, output: Handle) {
+            self.input = input
+            self.output = output
+        }
+    }
 }
 
 extension NIOBSDSocket {

Sources/NIOCore/ChannelPipeline.swift

@@ -154,6 +154,7 @@ public final class ChannelPipeline: ChannelInvoker {
     private var _channel: Optional<Channel>
 
     /// The `Channel` that this `ChannelPipeline` belongs to.
+    @usableFromInline
     internal var channel: Channel {
         self.eventLoop.assertInEventLoop()
         assert(self._channel != nil || self.destroyed)
@@ -1605,6 +1606,72 @@ extension ChannelPipeline {
             self.eventLoop.assertInEventLoop()
             self._pipeline.triggerUserOutboundEvent0(event, promise: promise)
         }
+
+        /// Provides scoped access to the underlying transport, if the channel supports it.
+        ///
+        /// This is an advanced API for reading or manipulating the underlying transport that backs a channel. Users
+        /// must not close the transport or invalidate any invariants that the channel relies upon for its operation.
+        ///
+        /// Not all channels support access to the underlying channel. If the channel does not support this API, the
+        /// closure is not called and this function immediately returns `nil`.
+        ///
+        /// Note that you must call this API with an appropriate closure, or otherwise explicitly specify the correct
+        /// transport type prarameter, in order for the closure to be run. Calling this function such that the compiler
+        /// infers a type for the transport closure parameter that differs from the channel implementation will result
+        /// in the closure not being run and this function will return `nil`.
+        ///
+        /// For example, for socket-based channels, that expose the underlying socket handle:
+        ///
+        /// ```swift
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable { transport in
+        ///     // This closure is called.
+        ///     transport == NIOBSDSocketHandle.invalid
+        /// }
+        ///
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable { (_: NIOBSDSocket.Handle) in
+        ///     // This closure is called.
+        ///     return
+        /// }
+        ///
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable(of: NIOBSDSocket.Handle.self) { _ in
+        ///     // This closure is called.
+        ///     return
+        /// }
+        ///
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable {
+        ///     // This closure is NOT called.
+        ///     return
+        /// }
+        ///
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable { (_: Any.self) in
+        ///     // This closure is NOT called.
+        ///     return
+        /// }
+        ///
+        /// try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable(of: Any.self) { _ in
+        ///     // This closure is NOT called.
+        ///     return
+        /// }
+        /// ```
+        ///
+        /// - Parameters:
+        ///   - type: The expected transport type the channel makes available.
+        ///   - body: /// A closure that takes the underlying transport, if the channel supports this operation.
+        /// - Returns: The value returned by the closure, or `nil` if the channel does not expose its transport.
+        /// - Throws: If there was an error accessing the underlying transport, or an error was thrown by the closure.
+        @available(macOS 13, iOS 16, tvOS 16, watchOS 9, *)
+        @inlinable
+        public func withUnsafeTransportIfAvailable<Transport, Result>(
+            of type: Transport.Type = Transport.self,
+            _ body: (_ transport: Transport) throws -> Result
+        ) throws -> Result? {
+            self.eventLoop.assertInEventLoop()
+            guard let core = self._pipeline.channel._channelCore as? any NIOTransportAccessibleChannelCore<Transport>
+            else {
+                return nil
+            }
+            return try core.withUnsafeTransport(body)
+        }
     }
 
     /// Returns a view of operations which can be performed synchronously on this pipeline. All

Sources/NIOCore/NIOTransportAccessibleChannelCore.swift

@@ -0,0 +1,43 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// A ``ChannelCore`` that provides access to its underlying transport.
+///
+/// This API is only used for ``Channel`` implementations: if you are not implementing a ``Channel``, do not use this
+/// protocol directly. Instead use ``ChannelPipeline/SynchronousOperations/withUnsafeTransportIfAvailable(of:_:)``.
+///
+/// Not all channels are expected to conform to ``NIOTransportAccessibleChannelCore``, but this is determined at runtime, by
+/// ``ChannelPipeline/SynchronousOperations/withUnsafeTransportIfAvailable(of:_:)``.
+public protocol NIOTransportAccessibleChannelCore<Transport>: ChannelCore {
+    /// The type of the underlying transport.
+    associatedtype Transport
+
+    /// Provides scoped access to the underlying transport.
+    ///
+    /// This is an advanced API for reading or manipulating the underlying transport that backs a channel. Users must
+    /// not close the transport or invalidate any invariants that NIO relies upon for the channel operation.
+    ///
+    /// Users should not attempt to use this API direcly, but should instead use
+    /// ``ChannelPipeline/SynchronousOperations/withUnsafeTransportIfAvailable(of:_:)``.
+    ///
+    /// Not all channels are expected to conform to ``NIOTransportAccessibleChannelCore``. If your channel implementation
+    /// does not support this protocol, do not provide a throwing implementation to indicate this. Instead, simply do
+    /// not conform your channel core to this protocol. Availablity of this functionality is communicated to users by /// ///
+    /// ``ChannelPipeline/SynchronousOperations/withUnsafeTransportIfAvailable(of:_:)``.
+    ///
+    /// - Parameter body: A closure that takes the underlying transport.
+    /// - Returns: The value returned by the closure.
+    /// - Throws: If the underlying transport is unavailable, or rethrows any error thrown by the closure.
+    func withUnsafeTransport<Result>(_ body: (_ transport: Transport) throws -> Result) throws -> Result
+}

Sources/NIOPosix/BSDSocketAPICommon.swift

@@ -44,9 +44,9 @@ internal enum Shutdown: _SocketShutdownProtocol, Sendable {
 
 extension NIOBSDSocket {
     #if os(Windows)
-    internal static let invalidHandle: Handle = INVALID_SOCKET
+    public static let invalidHandle: Handle = INVALID_SOCKET
     #else
-    internal static let invalidHandle: Handle = -1
+    public static let invalidHandle: Handle = -1
     #endif
 }
 

Sources/NIOPosix/BaseSocketChannel+AccessibleTransport.swift

@@ -0,0 +1,45 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import NIOCore
+
+extension BaseSocketChannel where SocketType: BaseSocket {
+    /// The underlying transport type backing this channel.
+    typealias Transport = NIOBSDSocket.Handle
+
+    /// Provides scoped access to the socket file handle.
+    func withUnsafeTransport<Result>(_ body: (_ transport: NIOBSDSocket.Handle) throws -> Result) throws -> Result {
+        try self.socket.withUnsafeHandle(body)
+    }
+}
+
+extension BaseSocketChannel where SocketType: PipePair {
+    /// The underlying transport type backing this channel.
+    typealias Transport = NIOBSDSocket.PipeHandle
+
+    /// Provides scoped access to the pipe file descriptors.
+    func withUnsafeTransport<Result>(_ body: (_ transport: NIOBSDSocket.PipeHandle) throws -> Result) throws -> Result {
+        try body(
+            NIOBSDSocket.PipeHandle(
+                input: self.socket.input?.fileDescriptor ?? NIOBSDSocket.invalidHandle,
+                output: self.socket.output?.fileDescriptor ?? NIOBSDSocket.invalidHandle
+            )
+        )
+    }
+}
+
+extension SocketChannel: NIOTransportAccessibleChannelCore {}
+extension ServerSocketChannel: NIOTransportAccessibleChannelCore {}
+extension DatagramChannel: NIOTransportAccessibleChannelCore {}
+extension PipeChannel: NIOTransportAccessibleChannelCore {}

Tests/NIOPosixTests/NIOTransportAccessibleChannelCoreTests.swift

@@ -0,0 +1,113 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import NIOCore  // NOTE: Not @testable import here -- testing public API surface.
+import NIOEmbedded
+import NIOPosix  // NOTE: Not @testable import here -- testing public API surface.
+import Testing
+
+@Suite struct NIOTransportAccessibleChannelCoreTests {
+    @Test func testUnderlyingSocketAccessForSocketBasedChannel() throws {
+        let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer { #expect(throws: Never.self) { try group.syncShutdownGracefully() } }
+        let channel = try DatagramBootstrap(group: group).bind(host: "127.0.0.1", port: 0).wait()
+        defer { #expect(throws: Never.self) { try channel.close().wait() } }
+
+        // We don't expect users to do this runtime check, but test the channel we got back from bootstrap conforms.
+        #expect(channel is any NIOTransportAccessibleChannelCore)
+        #expect(channel is any NIOTransportAccessibleChannelCore<NIOBSDSocket.Handle>)
+        #expect(channel is any NIOTransportAccessibleChannelCore<Any> == false)
+
+        // Here we try the public API use, in various flavours.
+        try channel.eventLoop.submit {
+            let syncOps = channel.pipeline.syncOperations
+
+            // Calling without explicit transport type runs closure if body inefers correct transport type.
+            try #expect(syncOps.withUnsafeTransportIfAvailable { fd in fd != NIOBSDSocket.invalidHandle } == true)
+            try #expect(syncOps.withUnsafeTransportIfAvailable { $0 != NIOBSDSocket.invalidHandle } == true)
+
+            // Calling with explicit correct transport type runs closure.
+            try #expect(syncOps.withUnsafeTransportIfAvailable(of: NIOBSDSocket.Handle.self) { _ in 42 } == 42)
+            try #expect(syncOps.withUnsafeTransportIfAvailable { (_: NIOBSDSocket.Handle) in 42 } == 42)
+
+            // Calling with explicit incorrect transport type does not run closure.
+            try #expect(syncOps.withUnsafeTransportIfAvailable(of: String.self) { _ in 42 } == nil)
+            try #expect(syncOps.withUnsafeTransportIfAvailable { (_: String) in 42 } == nil)
+
+            // Calling with explicit Any transport type does not run closure.
+            try #expect(syncOps.withUnsafeTransportIfAvailable(of: Any.self) { _ in 42 } == nil)
+            try #expect(syncOps.withUnsafeTransportIfAvailable { (_: Any) in 42 } == nil)
+
+            // Calling without explicit transport type does not run closure, even if body doesn't use transport.
+            try #expect(syncOps.withUnsafeTransportIfAvailable { 42 } == nil)
+
+            // Fun aside: What is the resolved type of the above function and why does it allow ignoring closure param?
+            try #expect(syncOps.withUnsafeTransportIfAvailable { $0.self } == nil)
+            // Answer: `$0: any (~Copyable & ~Escapable).Type`
+
+            // Calling without explicit transport type does not run closure, even if body uses compatible literal value.
+            try #expect(syncOps.withUnsafeTransportIfAvailable { transport in transport != -1 } == nil)
+        }.wait()
+    }
+
+    @Test func testUnderlyingTransportForUnsupportedChannels() throws {
+        let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer { #expect(throws: Never.self) { try group.syncShutdownGracefully() } }
+        let channel = EmbeddedChannel()
+        defer { #expect(throws: Never.self) { try channel.close().wait() } }
+
+        #expect(channel is any NIOTransportAccessibleChannelCore == false)
+
+        // Calling the public API will never run the closure -- we cannot specify a type to pass the runtime check.
+        let syncOps = channel.pipeline.syncOperations
+        try #expect(syncOps.withUnsafeTransportIfAvailable { 42 } == nil)
+        try #expect(syncOps.withUnsafeTransportIfAvailable(of: Any.self) { _ in 42 } == nil)
+        try #expect(syncOps.withUnsafeTransportIfAvailable(of: CInt.self) { _ in 42 } == nil)
+        try #expect(syncOps.withUnsafeTransportIfAvailable(of: type(of: STDOUT_FILENO).self) { _ in 42 } == nil)
+    }
+
+    @Test func testUnderlyingTransportConformanceForExpectedChannels() throws {
+        let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer { #expect(throws: Never.self) { try group.syncShutdownGracefully() } }
+
+        // SeverSocketChannel -- yep.
+        let serverChannel = try ServerBootstrap(group: group).bind(host: "127.0.0.1", port: 0).wait()
+        defer { #expect(throws: Never.self) { try serverChannel.close().wait() } }
+        #expect(serverChannel is any NIOTransportAccessibleChannelCore)
+        #expect(serverChannel is any NIOTransportAccessibleChannelCore<NIOBSDSocket.Handle>)
+
+        // SocketChannel -- yep.
+        let clientChannel = try ClientBootstrap(group: group).connect(to: serverChannel.localAddress!).wait()
+        defer { #expect(throws: Never.self) { try clientChannel.close().wait() } }
+        #expect(clientChannel is any NIOTransportAccessibleChannelCore)
+        #expect(clientChannel is any NIOTransportAccessibleChannelCore<NIOBSDSocket.Handle>)
+
+        // DatagramChannel -- yep.
+        let datagramChannel = try DatagramBootstrap(group: group).bind(host: "127.0.0.1", port: 0).wait()
+        defer { #expect(throws: Never.self) { try datagramChannel.close().wait() } }
+        #expect(datagramChannel is any NIOTransportAccessibleChannelCore)
+        #expect(datagramChannel is any NIOTransportAccessibleChannelCore<NIOBSDSocket.Handle>)
+
+        // PipeChannel -- yep.
+        let pipeChannel = try NIOPipeBootstrap(group: group).takingOwnershipOfDescriptor(output: STDOUT_FILENO).wait()
+        defer { #expect(throws: Never.self) { try pipeChannel.close().wait() } }
+        #expect(pipeChannel is any NIOTransportAccessibleChannelCore)
+        #expect(pipeChannel is any NIOTransportAccessibleChannelCore<NIOBSDSocket.PipeHandle>)
+
+        // EmbeddedChannel -- nope.
+        let embeddedChannel = EmbeddedChannel()
+        defer { #expect(throws: Never.self) { try embeddedChannel.close().wait() } }
+        #expect(embeddedChannel is any NIOTransportAccessibleChannelCore == false)
+    }
+}

Tests/NIOPosixTests/SocketChannelTest.swift

@@ -1126,6 +1126,23 @@ final class SocketChannelTest: XCTestCase {
         #endif
     }
 
+    func testBaseSocketChannelWithUnderlyingTransport() throws {
+        let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+        defer { XCTAssertNoThrow(try group.syncShutdownGracefully()) }
+        let socket = try Socket.SocketType(protocolFamily: .inet, type: .datagram)
+        let channel = try BaseSocketChannel(
+            socket: socket,
+            parent: nil,
+            eventLoop: group.next() as! SelectableEventLoop,
+            recvAllocator: FixedSizeRecvByteBufferAllocator(capacity: 1024),
+            supportReconnect: false
+        )
+
+        try channel.socket.withUnsafeHandle { fd in
+            XCTAssertNotEqual(fd, NIOBSDSocket.invalidHandle)
+            try channel.withUnsafeTransport { XCTAssertEqual($0, fd) }
+        }
+    }
 }
 
 final class DropAllReadsOnTheFloorHandler: ChannelDuplexHandler, Sendable {