Improve the names of a few commonly used APIs (#2014)

Motivation:

Naming is important; it should be clear and concise.

Modifications:

The follow renames all offer more precise names:
- Rename `server.run()` to `server.serve()`
- Rename `server.stopListening()` to `server.beginGracefulShutdown()`
- Rename `client.close()` to `client.beginGracefulShutdown()`

Result:

Clearer APIs

Sources/GRPCHTTP2Core/Client/Connection/GRPCChannel.swift

@@ -138,9 +138,9 @@ package final class GRPCChannel: ClientTransport {
             for try await result in self.resolver.names {
               self.input.continuation.yield(.handleResolutionResult(result))
             }
-            self.close()
+            self.beginGracefulShutdown()
           } catch {
-            self.close()
+            self.beginGracefulShutdown()
           }
         }
 
@@ -183,7 +183,7 @@ package final class GRPCChannel: ClientTransport {
 
   /// Signal to the transport that no new streams may be created and that connections should be
   /// closed when all streams are closed.
-  package func close() {
+  package func beginGracefulShutdown() {
     self.input.continuation.yield(.close)
   }
 
@@ -393,7 +393,7 @@ extension GRPCChannel {
       self.updateLoadBalancer(serviceConfig: config, endpoints: result.endpoints, in: &group)
 
     case .failure:
-      self.close()
+      self.beginGracefulShutdown()
     }
   }
 
@@ -567,10 +567,10 @@ extension GRPCChannel {
       if let result = try await iterator.next() {
         self.handleNameResolutionResult(result, in: &group)
       } else {
-        self.close()
+        self.beginGracefulShutdown()
       }
     } catch {
-      self.close()
+      self.beginGracefulShutdown()
     }
   }
 }

Sources/GRPCHTTP2TransportNIOPosix/HTTP2ClientTransport+Posix.swift

@@ -105,8 +105,8 @@ extension HTTP2ClientTransport {
       self.channel.configuration(forMethod: descriptor)
     }
 
-    public func close() {
-      self.channel.close()
+    public func beginGracefulShutdown() {
+      self.channel.beginGracefulShutdown()
     }
 
     public func withStream<T: Sendable>(

Sources/GRPCHTTP2TransportNIOPosix/HTTP2ServerTransport+Posix.swift

@@ -328,7 +328,7 @@ extension HTTP2ServerTransport {
       }
     }
 
-    public func stopListening() {
+    public func beginGracefulShutdown() {
       self.serverQuiescingHelper.initiateShutdown(promise: nil)
     }
   }

Sources/GRPCHTTP2TransportNIOTransportServices/HTTP2ServerTransport+TransportServices.swift

@@ -280,7 +280,7 @@ extension HTTP2ServerTransport {
       }
     }
 
-    public func stopListening() {
+    public func beginGracefulShutdown() {
       self.serverQuiescingHelper.initiateShutdown(promise: nil)
     }
   }

Tests/GRPCHTTP2CoreTests/Client/Connection/GRPCChannelTests.swift

@@ -96,7 +96,7 @@ final class GRPCChannelTests: XCTestCase {
           XCTAssertEqual(throttle.tokenRatio, 0.1)
 
           // Now close.
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -176,7 +176,7 @@ final class GRPCChannelTests: XCTestCase {
             return noConfigForGet && configForUpdate && noThrottle
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -362,7 +362,7 @@ final class GRPCChannelTests: XCTestCase {
         switch part1 {
         case .metadata:
           // Got metadata, close the channel.
-          channel.close()
+          channel.beginGracefulShutdown()
         case .message, .status, .none:
           XCTFail("Expected metadata, got \(String(describing: part1))")
         }
@@ -472,7 +472,7 @@ final class GRPCChannelTests: XCTestCase {
 
           // All RPCs done, close the channel and cancel the group to stop the server.
           if outstandingRPCs == 0 {
-            channel.close()
+            channel.beginGracefulShutdown()
             group.cancelAll()
           }
 
@@ -537,7 +537,7 @@ final class GRPCChannelTests: XCTestCase {
 
           // All RPCs done, close the channel and cancel the group to stop the server.
           if outstandingRPCs == 0 {
-            channel.close()
+            channel.beginGracefulShutdown()
             group.cancelAll()
           }
 
@@ -616,7 +616,7 @@ final class GRPCChannelTests: XCTestCase {
             server1.clients.count == 0 && server2.clients.count == 0 && server3.clients.count == 1
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         case .shutdown:
           group.cancelAll()
@@ -683,7 +683,7 @@ final class GRPCChannelTests: XCTestCase {
                 break
               }
             }
-            channel.close()
+            channel.beginGracefulShutdown()
           default:
             ()
           }
@@ -737,7 +737,7 @@ final class GRPCChannelTests: XCTestCase {
             server1.clients.count == 1 && server2.clients.count == 0
           }
 
-          channel.close()
+          channel.beginGracefulShutdown()
 
         default:
           ()
@@ -776,7 +776,7 @@ final class GRPCChannelTests: XCTestCase {
             // Sleep a little to increase the chances of the stream being queued before the channel
             // reacts to the close.
             try await Task.sleep(for: .milliseconds(10))
-            channel.close()
+            channel.beginGracefulShutdown()
           }
 
           // Try to open a new stream.

Tests/GRPCHTTP2TransportTests/HTTP2TransportNIOPosixTests.swift

@@ -40,7 +40,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv4Address = try XCTUnwrap(address.ipv4)
         XCTAssertNotEqual(ipv4Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -60,7 +60,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv6Address = try XCTUnwrap(address.ipv6)
         XCTAssertNotEqual(ipv6Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -82,7 +82,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
           address.unixDomainSocket,
           GRPCHTTP2Core.SocketAddress.UnixDomainSocket(path: "/tmp/posix-uds-test")
         )
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -103,7 +103,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.virtualSocket)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -165,7 +165,7 @@ final class HTTP2TransportNIOPosixTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.ipv4)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }

Tests/GRPCHTTP2TransportTests/HTTP2TransportNIOTransportServicesTests.swift

@@ -37,7 +37,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv4Address = try XCTUnwrap(address.ipv4)
         XCTAssertNotEqual(ipv4Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -57,7 +57,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
         let address = try await transport.listeningAddress
         let ipv6Address = try XCTUnwrap(address.ipv6)
         XCTAssertNotEqual(ipv6Address.port, 0)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -83,7 +83,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
           address.unixDomainSocket,
           GRPCHTTP2Core.SocketAddress.UnixDomainSocket(path: "/tmp/niots-uds-test")
         )
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }
@@ -145,7 +145,7 @@ final class HTTP2TransportNIOTransportServicesTests: XCTestCase {
       group.addTask {
         let address = try await transport.listeningAddress
         XCTAssertNotNil(address.ipv4)
-        transport.stopListening()
+        transport.beginGracefulShutdown()
       }
     }
   }

Tests/GRPCHTTP2TransportTests/HTTP2TransportTests.swift

@@ -94,8 +94,8 @@ final class HTTP2TransportTests: XCTestCase {
           XCTFail("Unexpected error: '\(error)' (\(pair))")
         }
 
-        server.stopListening()
-        client.close()
+        server.beginGracefulShutdown()
+        client.beginGracefulShutdown()
       }
     }
   }
@@ -155,7 +155,7 @@ final class HTTP2TransportTests: XCTestCase {
       )
 
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       let address = try await server.listeningAddress!
@@ -174,7 +174,7 @@ final class HTTP2TransportTests: XCTestCase {
       )
 
       group.addTask {
-        try await server.run()
+        try await server.serve()
       }
 
       let address = try await server.listeningAddress!