More docs and comments

Sources/GRPCNIOTransportCore/Client/Connection/Connection.swift

@@ -85,8 +85,8 @@ package final class Connection: Sendable {
   /// The address to connect to.
   private let address: SocketAddress
 
-  /// The server authority. If `nil`, a value will be computed based on the endpoint being
-  /// connected to.
+  /// The percent-encoded server authority. If `nil`, a value will be computed based on the endpoint
+  /// being connected to.
   private let authority: String?
 
   /// The default compression algorithm used for requests.
@@ -137,6 +137,9 @@ package final class Connection: Sendable {
       do {
         return try await self.http2Connector.establishConnection(
           to: self.address,
+          // The authority here is used for the SNI hostname in the TLS handshake (if applicable)
+          // where a raw IP address isn't permitted, so fallback to 'address.sniHostname' rather
+          // than 'address.authority'.
           authority: self.authority ?? self.address.sniHostname
         )
       } catch let error as RPCError {
@@ -223,6 +226,8 @@ package final class Connection: Sendable {
           let streamHandler = GRPCClientStreamHandler(
             methodDescriptor: descriptor,
             scheme: scheme,
+            // The value of authority here is being used for the ":authority" pseudo-header. Derive
+            // one from the address if we don't already have one.
             authority: self.authority ?? self.address.authority,
             outboundEncoding: compression,
             acceptedEncodings: self.enabledCompression,

Sources/GRPCNIOTransportCore/Client/Connection/ConnectionFactory.swift

@@ -19,6 +19,11 @@ package import NIOHTTP2
 internal import NIOPosix
 
 package protocol HTTP2Connector: Sendable {
+  /// Attempt to establish a connection to the given address.
+  ///
+  /// - Parameters:
+  ///   - address: The address to connect to.
+  ///   - authority: The authority as used for the TLS SNI extension (if applicable).
   func establishConnection(
     to address: SocketAddress,
     authority: String?

Sources/GRPCNIOTransportCore/Client/Connection/GRPCChannel.swift

@@ -52,8 +52,8 @@ package final class GRPCChannel: ClientTransport {
   /// A factory for connections.
   private let connector: any HTTP2Connector
 
-  /// The server authority. If `nil`, a value will be computed based on the endpoint being
-  /// connected to.
+  /// The percent-encoded server authority. If `nil`, a value will be computed based on the endpoint
+  /// being connected to.
   private let authority: String?
 
   /// The connection backoff configuration used by the subchannel when establishing a connection.
@@ -86,6 +86,9 @@ package final class GRPCChannel: ClientTransport {
     self.input = AsyncStream.makeStream()
     self.connector = connector
 
+    // Determine the authority to use for the ":authority" pseudo-header and in the TLS SNI
+    // extension. This value will be used for all subchannels and connections. If no authority
+    // is set then one will be derived for each address being connected to.
     if let authority = config.http2.authority ?? resolver.authority {
       self.authority = PercentEncoding.encodeAuthority(authority)
     } else {

Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/PickFirstLoadBalancer.swift

@@ -77,8 +77,8 @@ package final class PickFirstLoadBalancer: Sendable {
   /// A connector, capable of creating connections.
   private let connector: any HTTP2Connector
 
-  /// The server authority. If `nil`, a value will be computed based on the endpoint being
-  /// connected to.
+  /// The percent-encoded server authority. If `nil`, a value will be computed based on the endpoint
+  /// being connected to.
   private let authority: String?
 
   /// Connection backoff configuration.

Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/RoundRobinLoadBalancer.swift

@@ -109,8 +109,8 @@ package final class RoundRobinLoadBalancer: Sendable {
   /// A connector, capable of creating connections.
   private let connector: any HTTP2Connector
 
-  /// The server authority. If `nil`, a value will be computed based on the endpoint being
-  /// connected to.
+  /// The percent-encoded server authority. If `nil`, a value will be computed based on the endpoint
+  /// being connected to.
   private let authority: String?
 
   /// Connection backoff configuration.

Sources/GRPCNIOTransportCore/Client/Connection/LoadBalancers/Subchannel.swift

@@ -83,8 +83,8 @@ package final class Subchannel: Sendable {
   /// A factory for connections.
   private let connector: any HTTP2Connector
 
-  /// The server authority. If `nil`, a value will be computed based on the endpoint being
-  /// connected to.
+  /// The percent-encoded server authority. If `nil`, a value will be computed based on the endpoint
+  /// being connected to.
   private let authority: String?
 
   /// The connection backoff configuration used by the subchannel when establishing a connection.