fixup: Move this to ChannelCore and expose withUnsafeTransportIfAvailable via syncOperations

Author: simonjbeaumont

Sources/NIOCore/ChannelPipeline.swift

@@ -1605,6 +1605,29 @@ 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 NIO relies upon for the channel 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.
+        /// - 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.
+        @available(macOS 13, iOS 16, tvOS 16, watchOS 9, *)
+        public func withUnsafeTransportIfAvailable<Transport, Result>(
+            of _: Transport.Type,
+            _ body: (_ transport: Transport) throws -> Result
+        ) throws -> Result? {
+            self.eventLoop.assertInEventLoop()
+            guard let channel = self._pipeline._channel as? any NIOTransportAccessibleChannel<Transport> else {
+                return nil
+            }
+            return try channel.withUnsafeTransport(body)
+        }
     }
 
     /// Returns a view of operations which can be performed synchronously on this pipeline. All

Sources/NIOCore/NIOTransportAccessibleChannel.swift

@@ -12,8 +12,8 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A ``NIOTransportAccessibleChannel`` is a ``Channel`` that provides access to its underlying transport.
-public protocol NIOTransportAccessibleChannel<Transport>: Channel {
+/// A ``NIOTransportAccessibleChannel`` is a ``ChannelCore`` that provides access to its underlying transport.
+public protocol NIOTransportAccessibleChannel<Transport>: ChannelCore {
     /// The type of the underlying transport.
     associatedtype Transport
 
@@ -23,21 +23,10 @@ public protocol NIOTransportAccessibleChannel<Transport>: Channel {
     /// 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:
+    /// runtime.
     ///
-    /// ```swift
-    /// if let channel = channel as? any NIOTransportAccessibleChannel {
-    ///     channel.withUnsafeTransport { transport in /* Do something with untyped transport. */ }
-    /// }
-    /// ```
-    ///
-    /// When you expect a specific associated transport type, get a typed transport closure:
-    ///
-    /// ```swift
-    /// if let channel = channel as? any NIOTransportAccessibleChannel<NIOBSDSocket.Handle>) {
-    ///     channel.withUnsafeTransport { transport in /* Do something with typed transport. */ }
-    /// }
-    /// ```
+    /// Users should not attempt to use this API direcly, but should instead use
+    /// ``ChannelPipeline/SynchronousOperations/withUnsafeTransportIfAvailable(of:_:)``.
     ///
     /// - Parameter body: A closure that takes the underlying transport.
     /// - Returns: The value returned by the closure.

Tests/NIOPosixTests/NIOTransportAccessibleChannelTests.swift

@@ -46,5 +46,12 @@ import Testing
                 #expect(fd__ == fd_)
             }
         }
+
+        // But this is how we want people to use the API -- via sync operations.
+        try channel.eventLoop.submit {
+            try channel.pipeline.syncOperations.withUnsafeTransportIfAvailable(of: NIOBSDSocket.Handle.self) { transport in
+                #expect(type(of: transport) == NIOBSDSocket.Handle.self)
+            }
+        }.wait()
     }
 }