Document when channel.remoteAddress field can be nil

Sources/NIOChatClient/main.swift

@@ -82,6 +82,8 @@ let channel = try { () -> Channel in
     }
 }()
 
+// In production code, you should check if `channel.remoteAddress` is actually
+// present, as in rare situations it can be `nil`.
 print("ChatClient connected to ChatServer: \(channel.remoteAddress!), happy chatting\n. Press ^D to exit.")
 
 while let line = readLine(strippingNewline: false) {

Sources/NIOChatServer/main.swift

@@ -54,6 +54,8 @@ final class ChatHandler: ChannelInboundHandler {
     private var channels: [ObjectIdentifier: Channel] = [:]
 
     public func channelActive(context: ChannelHandlerContext) {
+        // In production code, you should check if `context.remoteAddress` is actually
+        // present, as in rare situations it can be `nil`.
         let remoteAddress = context.remoteAddress!
         let channel = context.channel
         self.channelsSyncQueue.async {
@@ -92,6 +94,9 @@ final class ChatHandler: ChannelInboundHandler {
 
         // 64 should be good enough for the ipaddress
         var buffer = context.channel.allocator.buffer(capacity: read.readableBytes + 64)
+
+        // In production code, you should check if `context.remoteAddress` is actually
+        // present, as in rare situations it can be `nil`.
         buffer.writeString("(\(context.remoteAddress!)) - ")
         buffer.writeBuffer(&read)
         self.channelsSyncQueue.async { [buffer] in

Sources/NIOCore/Channel.swift

@@ -122,6 +122,11 @@ public protocol Channel: AnyObject, ChannelOutboundInvoker, _NIOPreconcurrencySe
     var localAddress: SocketAddress? { get }
 
     /// The remote peer's `SocketAddress`.
+    ///
+    /// If we end up accepting an already-closed connection, the kernel can end up in a place
+    /// where it has no remote address to give us. In this situation, `remoteAddress` will be
+    /// `nil`. It can also be `nil` in cases where it isn't representable in SocketAddress, e.g. if
+    /// we're talking over a vsock.
     var remoteAddress: SocketAddress? { get }
 
     /// `Channel`s are hierarchical and might have a parent `Channel`. `Channel` hierarchies are in use for certain

Sources/NIOHTTP1Client/main.swift

@@ -23,6 +23,8 @@ private final class HTTPEchoHandler: ChannelInboundHandler {
     public typealias OutboundOut = HTTPClientRequestPart
 
     public func channelActive(context: ChannelHandlerContext) {
+        // In production code, you should check if `context.remoteAddress` is actually
+        // present, as in rare situations it can be `nil`.
         print("Client connected to \(context.remoteAddress!)")
 
         // We are connected. It's time to send the message to the server to initialize the ping-pong sequence.