fixup: Polish up the new approach, based on syncOperations

Author: simonjbeaumont

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)
@@ -1608,25 +1609,68 @@ extension ChannelPipeline {
 
         /// 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 NIO relies upon for the channel operation.
+        /// 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`.
         ///
-        /// - Parameter body: A closure that takes the underlying transport, if the channel supports this operation.
+        /// 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 the underlying transport is unavailable, or rethrows any error thrown by the closure.
+        /// - 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 _: Transport.Type,
+            of type: Transport.Type = Transport.self,
             _ body: (_ transport: Transport) throws -> Result
         ) throws -> Result? {
             self.eventLoop.assertInEventLoop()
-            guard let channel = self._pipeline._channel as? any NIOTransportAccessibleChannel<Transport> else {
+            guard let core = self._pipeline.channel._channelCore as? any NIOTransportAccessibleChannelCore<Transport>
+            else {
                 return nil
             }
-            return try channel.withUnsafeTransport(body)
+            return try core.withUnsafeTransport(body)
         }
     }
 

…Core/NIOTransportAccessibleChannel.swift …/NIOTransportAccessibleChannelCore.swiftSources/NIOCore/NIOTransportAccessibleChannel.swift renamed to Sources/NIOCore/NIOTransportAccessibleChannelCore.swift Sources/NIOCore/NIOTransportAccessibleChannel.swift renamed to Sources/NIOCore/NIOTransportAccessibleChannelCore.swift

@@ -12,8 +12,14 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A ``NIOTransportAccessibleChannel`` is a ``ChannelCore`` that provides access to its underlying transport.
-public protocol NIOTransportAccessibleChannel<Transport>: ChannelCore {
+/// 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
 
@@ -22,12 +28,14 @@ public protocol NIOTransportAccessibleChannel<Transport>: ChannelCore {
     /// 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.
     ///
-    /// Not all channels are expected to conform to ``NIOTransportAccessibleChannel``, but this can be determined at
-    /// runtime.
-    ///
     /// 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.

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.swift

@@ -1479,7 +1479,7 @@ extension BaseSocketChannel {
     }
 }
 
-extension BaseSocketChannel: NIOTransportAccessibleChannel where SocketType: BaseSocket {
+extension BaseSocketChannel: NIOTransportAccessibleChannelCore where SocketType: BaseSocket {
     /// The underlying transport which is a BSD socket file handle.
     typealias Transport = NIOBSDSocket.Handle
 

Tests/NIOPosixTests/NIOTransportAccessibleChannelCoreTests.swift

@@ -0,0 +1,83 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 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() } }
+
+        // Right now pipe channels do not expose their underlying transport, so we'll use this to test API behaviour.
+        let channel = try NIOPipeBootstrap(group: group).takingOwnershipOfDescriptor(output: STDOUT_FILENO).wait()
+        defer { #expect(throws: Never.self) { try channel.close().wait() } }
+
+        #expect(channel is any NIOTransportAccessibleChannelCore == false)
+
+        try channel.eventLoop.submit {
+            let syncOps = channel.pipeline.syncOperations
+
+            // Calling the public API will never run the closure -- we cannot specify a type to pass the runtime check.
+            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)
+        }.wait()
+    }
+}