Generate sugared client APIs (#2009)

glbrntt · web-flow · commit 7feca6abd8be · 2024-08-12T13:40:23.000Z
Motivation:

The generated client API uses the full expressive request/response types
which are used by the interceptors. This gives clients full control but
at the cost of usability.

In many cases we can simplify this for them:

- For single requests we can push the message and metadata into the stub
  signature and construct the request on behalf of the user
- For streaming requests we can push the metadata and request writing
  closure into the signature of the stub and construct the request for
  the user
- For single responses we can default the response handler to returning
  the message

Modifications:

- Add sugared API
- This, required that the struct swift representation and renderer be
  updated to support dictionary literls
- Regenrate the code
- Update the echo example to use the convenience API

Result:

Easier to use client APIs
diff --git a/Sources/InteroperabilityTests/Generated/empty_service.grpc.swift b/Sources/InteroperabilityTests/Generated/empty_service.grpc.swift
@@ -77,6 +77,10 @@ public protocol Grpc_Testing_EmptyServiceClientProtocol: Sendable {}
 extension Grpc_Testing_EmptyService.ClientProtocol {
 }
 
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension Grpc_Testing_EmptyService.ClientProtocol {
+}
+
 /// A service that has zero methods.
 /// See https://github.com/grpc/grpc/issues/15574
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
diff --git a/Sources/InteroperabilityTests/Generated/test.grpc.swift b/Sources/InteroperabilityTests/Generated/test.grpc.swift
@@ -686,6 +686,173 @@ extension Grpc_Testing_TestService.ClientProtocol {
     }
 }
 
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension Grpc_Testing_TestService.ClientProtocol {
+    /// One empty request followed by one empty response.
+    public func emptyCall<Result>(
+        _ message: Grpc_Testing_Empty,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_Empty>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_Empty>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.emptyCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// One request followed by one response.
+    public func unaryCall<Result>(
+        _ message: Grpc_Testing_SimpleRequest,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_SimpleResponse>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_SimpleRequest>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.unaryCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// One request followed by one response. Response has cache control
+    /// headers set such that a caching HTTP proxy (such as GFE) can
+    /// satisfy subsequent requests.
+    public func cacheableUnaryCall<Result>(
+        _ message: Grpc_Testing_SimpleRequest,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_SimpleResponse>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_SimpleRequest>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.cacheableUnaryCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// One request followed by a sequence of responses (streamed download).
+    /// The server returns the payload with client desired type and sizes.
+    public func streamingOutputCall<Result>(
+        _ message: Grpc_Testing_StreamingOutputCallRequest,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Stream<Grpc_Testing_StreamingOutputCallResponse>) async throws -> Result
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_StreamingOutputCallRequest>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.streamingOutputCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// A sequence of requests followed by one response (streamed upload).
+    /// The server returns the aggregated size of client payload as the result.
+    public func streamingInputCall<Result>(
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        requestProducer: @Sendable @escaping (GRPCCore.RPCWriter<Grpc_Testing_StreamingInputCallRequest>) async throws -> Void,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_StreamingInputCallResponse>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Stream<Grpc_Testing_StreamingInputCallRequest>(
+            metadata: metadata,
+            producer: requestProducer
+        )
+        return try await self.streamingInputCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// A sequence of requests with each request served by the server immediately.
+    /// As one request could lead to multiple responses, this interface
+    /// demonstrates the idea of full duplexing.
+    public func fullDuplexCall<Result>(
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        requestProducer: @Sendable @escaping (GRPCCore.RPCWriter<Grpc_Testing_StreamingOutputCallRequest>) async throws -> Void,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Stream<Grpc_Testing_StreamingOutputCallResponse>) async throws -> Result
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Stream<Grpc_Testing_StreamingOutputCallRequest>(
+            metadata: metadata,
+            producer: requestProducer
+        )
+        return try await self.fullDuplexCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// A sequence of requests followed by a sequence of responses.
+    /// The server buffers all the client requests and then serves them in order. A
+    /// stream of responses are returned to the client when the server starts with
+    /// first request.
+    public func halfDuplexCall<Result>(
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        requestProducer: @Sendable @escaping (GRPCCore.RPCWriter<Grpc_Testing_StreamingOutputCallRequest>) async throws -> Void,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Stream<Grpc_Testing_StreamingOutputCallResponse>) async throws -> Result
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Stream<Grpc_Testing_StreamingOutputCallRequest>(
+            metadata: metadata,
+            producer: requestProducer
+        )
+        return try await self.halfDuplexCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// The test server will not implement this method. It will be used
+    /// to test the behavior when clients call unimplemented methods.
+    public func unimplementedCall<Result>(
+        _ message: Grpc_Testing_Empty,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_Empty>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_Empty>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.unimplementedCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+}
+
 /// A simple service to test the various types of RPCs and experiment with
 /// performance with various types of payload.
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
@@ -894,6 +1061,29 @@ extension Grpc_Testing_UnimplementedService.ClientProtocol {
     }
 }
 
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension Grpc_Testing_UnimplementedService.ClientProtocol {
+    /// A call that no server should implement
+    public func unimplementedCall<Result>(
+        _ message: Grpc_Testing_Empty,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_Empty>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_Empty>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.unimplementedCall(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+}
+
 /// A simple service NOT implemented at servers so clients can test for
 /// that case.
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
@@ -980,6 +1170,47 @@ extension Grpc_Testing_ReconnectService.ClientProtocol {
     }
 }
 
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension Grpc_Testing_ReconnectService.ClientProtocol {
+    public func start<Result>(
+        _ message: Grpc_Testing_ReconnectParams,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_Empty>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_ReconnectParams>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.start(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    public func stop<Result>(
+        _ message: Grpc_Testing_Empty,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Testing_ReconnectInfo>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Testing_Empty>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.stop(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+}
+
 /// A service used to control reconnect server.
 @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
 public struct Grpc_Testing_ReconnectServiceClient: Grpc_Testing_ReconnectService.ClientProtocol {
diff --git a/Sources/Services/Health/Generated/health.grpc.swift b/Sources/Services/Health/Generated/health.grpc.swift
@@ -253,6 +253,69 @@ extension Grpc_Health_V1_Health.ClientProtocol {
     }
 }
 
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension Grpc_Health_V1_Health.ClientProtocol {
+    /// Check gets the health of the specified service. If the requested service
+    /// is unknown, the call will fail with status NOT_FOUND. If the caller does
+    /// not specify a service name, the server should respond with its overall
+    /// health status.
+    ///
+    /// Clients should set a deadline when calling Check, and can declare the
+    /// server unhealthy if they do not receive a timely response.
+    ///
+    /// Check implementations should be idempotent and side effect free.
+    package func check<Result>(
+        _ message: Grpc_Health_V1_HealthCheckRequest,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Single<Grpc_Health_V1_HealthCheckResponse>) async throws -> Result = {
+            try $0.message
+        }
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Health_V1_HealthCheckRequest>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.check(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+    
+    /// Performs a watch for the serving status of the requested service.
+    /// The server will immediately send back a message indicating the current
+    /// serving status.  It will then subsequently send a new message whenever
+    /// the service's serving status changes.
+    ///
+    /// If the requested service is unknown when the call is received, the
+    /// server will send a message setting the serving status to
+    /// SERVICE_UNKNOWN but will *not* terminate the call.  If at some
+    /// future point, the serving status of the service becomes known, the
+    /// server will send a new message with the service's serving status.
+    ///
+    /// If the call terminates with status UNIMPLEMENTED, then clients
+    /// should assume this method is not supported and should not retry the
+    /// call.  If the call terminates with any other status (including OK),
+    /// clients should retry the call with appropriate exponential backoff.
+    package func watch<Result>(
+        _ message: Grpc_Health_V1_HealthCheckRequest,
+        metadata: GRPCCore.Metadata = [:],
+        options: GRPCCore.CallOptions = .defaults,
+        onResponse handleResponse: @Sendable @escaping (GRPCCore.ClientResponse.Stream<Grpc_Health_V1_HealthCheckResponse>) async throws -> Result
+    ) async throws -> Result where Result: Sendable {
+        let request = GRPCCore.ClientRequest.Single<Grpc_Health_V1_HealthCheckRequest>(
+            message: message,
+            metadata: metadata
+        )
+        return try await self.watch(
+            request: request,
+            options: options,
+            handleResponse
+        )
+    }
+}
+
 /// Health is gRPC's mechanism for checking whether a server is able to handle
 /// RPCs. Its semantics are documented in
 /// https://github.com/grpc/grpc/blob/master/doc/health-checking.md.
