PR changes

Author: gjcairo

Examples/echo-metadata/Package.swift

@@ -21,7 +21,7 @@ let package = Package(
   name: "echo-metadata",
   platforms: [.macOS("15.0")],
   dependencies: [
-    .package(url: "https://github.com/grpc/grpc-swift.git", exact: "2.0.0-rc.1"),
+        .package(url: "https://github.com/grpc/grpc-swift.git", exact: "2.0.0-rc.1"),
     .package(url: "https://github.com/grpc/grpc-swift-protobuf.git", exact: "1.0.0-rc.1"),
     .package(url: "https://github.com/grpc/grpc-swift-nio-transport.git", exact: "1.0.0-rc.1"),
     .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"),

Examples/echo-metadata/README.md

@@ -2,19 +2,20 @@
 
 This example demonstrates how to interact with `Metadata` on RPCs: how to set and read it on unary 
 and streaming requests, as well as how to set and read both initial and trailing metadata on unary 
-and streaming responses. This is done using a simple 'echo' server and client and the Swift NIO 
+and streaming responses. This is done using a simple 'echo' server and client and the SwiftNIO 
 based HTTP/2 transport.
 
 ## Overview
 
-An `echo-metadata` command line tool that uses generated stubs for an 'echo' service
-which allows you to start a server and to make requests against it. The client will automatically
-run a unary request followed by a bidirectional streaming request. In both cases, no message will
-be sent as part of the request: only the metadata provided as arguments to the executable will be
-included.
-The server will then echo back all metadata key-value pairs that begin with "echo-". No message 
-will be included in the responses, and the echoed values will be included in both the initial and
-the trailing metadata.
+An `echo-metadata` command line tool that uses generated stubs for an 'echo-metadata' service
+which allows you to start a server and to make requests against it. 
+
+You can use any of the client's subcommands (`get`, `collect`, `expand` and `update`) to send the
+provided `message` as both the request's message, and as the value for the `echo-message` key in
+the request's metadata.
+
+The server will then echo back the message and the metadata's `echo-message` key-value pair sent
+by the client. The request's metadata will be echoed both in the initial and the trailing metadata.
 
 The tool uses the [SwiftNIO](https://github.com/grpc/grpc-swift-nio-transport) HTTP/2 transport.
 
@@ -36,16 +37,15 @@ $ PROTOC_PATH=$(which protoc) swift run echo-metadata serve
 Echo-Metadata listening on [ipv4]127.0.0.1:1234
 ```
 
-Use the CLI to run the client and make a unary request followed by a bidirectional streaming one:
+Use the CLI to run the client and make a `get` (unary) request:
 
 ```console
-$ PROTOC_PATH=$(which protoc) swift run echo-metadata echo --metadata "echo-key=value" --metadata "another-key=value"
-unary → [("echo-key", value)]
-unary ← Initial metadata: [("echo-key", value)]
-unary ← Trailing metadata: [("echo-key", value)]
-bidirectional → [("echo-key", value)]
-bidirectional ← Initial metadata: [("echo-key", value)]
-bidirectional ← Trailing metadata: [("echo-key", value)]
+$ PROTOC_PATH=$(which protoc) swift run echo-metadata get --message "hello"
+get → metadata: [("echo-message", "hello")]
+get → message: hello
+get ← initial metadata: [("echo-message", "hello")]
+get ← message: hello
+get ← trailing metadata: [("echo-message", "hello")]
 ```
 
 Get help with the CLI by running:

Examples/echo-metadata/Sources/Subcommands/ClientArguments.swift Examples/echo-metadata/Sources/ClientArguments.swift

@@ -23,9 +23,9 @@ struct ClientArguments: ParsableArguments {
 
   @Option(
     help:
-      "Metadata 'key=value' pair to send to the server. Key must begin with 'echo-' to be echoed back."
+      "Message to send to the server. It will also be sent in the request's metadata as the value for `echo-message`."
   )
-  var metadata: [String]
+  var message: String
 }
 
 extension ClientArguments {

Examples/echo-metadata/Sources/EchoMetadata.swift

@@ -22,12 +22,6 @@ struct EchoMetadata: AsyncParsableCommand {
   static let configuration = CommandConfiguration(
     commandName: "echo-metadata",
     abstract: "A multi-tool to run an echo-metadata server and execute RPCs against it.",
-    subcommands: [Serve.self, Echo.self]
+    subcommands: [Serve.self, Get.self, Collect.self, Update.self, Expand.self]
   )
 }
-
-extension Metadata {
-  var echoPairs: Self {
-    Metadata(self.filter({ $0.key.starts(with: "echo-") }))
-  }
-}

Examples/echo-metadata/Sources/Subcommands/EchoService.swift Examples/echo-metadata/Sources/EchoService.swift

@@ -21,9 +21,9 @@ struct EchoService: Echo_Echo.ServiceProtocol {
     request: ServerRequest<Echo_EchoRequest>,
     context: ServerContext
   ) async throws -> ServerResponse<Echo_EchoResponse> {
-    let responseMetadata = request.metadata.echoPairs
+    let responseMetadata = Metadata(request.metadata.filter({ $0.key.starts(with: "echo-") }))
     return ServerResponse(
-      message: .init(),
+      message: .with { $0.text = request.message.text },
       metadata: responseMetadata,
       trailingMetadata: responseMetadata
     )
@@ -33,9 +33,12 @@ struct EchoService: Echo_Echo.ServiceProtocol {
     request: StreamingServerRequest<Echo_EchoRequest>,
     context: ServerContext
   ) async throws -> ServerResponse<Echo_EchoResponse> {
-    let responseMetadata = request.metadata.echoPairs
+    let responseMetadata = Metadata(request.metadata.filter({ $0.key.starts(with: "echo-") }))
+    let messages = try await request.messages.reduce(into: []) { $0.append($1.text) }
+    let joined = messages.joined(separator: " ")
+
     return ServerResponse(
-      message: .init(),
+      message: .with { $0.text = joined },
       metadata: responseMetadata,
       trailingMetadata: responseMetadata
     )
@@ -45,31 +48,26 @@ struct EchoService: Echo_Echo.ServiceProtocol {
     request: ServerRequest<Echo_EchoRequest>,
     context: ServerContext
   ) async throws -> StreamingServerResponse<Echo_EchoResponse> {
-    let responseMetadata = request.metadata.echoPairs
-    return StreamingServerResponse(
-      single: ServerResponse(
-        message: .init(),
-        metadata: responseMetadata,
-        trailingMetadata: responseMetadata
-      )
-    )
+    let responseMetadata = Metadata(request.metadata.filter({ $0.key.starts(with: "echo-") }))
+    let parts = request.message.text.split(separator: " ")
+    let messages = parts.map { part in Echo_EchoResponse.with { $0.text = String(part) } }
+
+    return StreamingServerResponse(metadata: responseMetadata) { writer in
+      try await writer.write(contentsOf: messages)
+      return responseMetadata
+    }
   }
 
   func update(
     request: StreamingServerRequest<Echo_EchoRequest>,
     context: ServerContext
   ) async throws -> StreamingServerResponse<Echo_EchoResponse> {
-    for try await _ in request.messages {
-      // Wait for request to be done
+    let responseMetadata = Metadata(request.metadata.filter({ $0.key.starts(with: "echo-") }))
+    return StreamingServerResponse(metadata: responseMetadata) { writer in
+      for try await message in request.messages {
+        try await writer.write(.with { $0.text = message.text })
+      }
+      return responseMetadata
     }
-
-    let responseMetadata = request.metadata.echoPairs
-    return StreamingServerResponse(
-      single: ServerResponse(
-        message: .init(),
-        metadata: responseMetadata,
-        trailingMetadata: responseMetadata
-      )
-    )
   }
 }

Examples/echo-metadata/Sources/Subcommands/Collect.swift

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025, gRPC Authors All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import ArgumentParser
+import GRPCCore
+import GRPCNIOTransportHTTP2
+
+struct Collect: AsyncParsableCommand {
+  static let configuration = CommandConfiguration(
+    abstract: "Makes a client streaming RPC to the echo-metadata server."
+  )
+
+  @OptionGroup
+  var arguments: ClientArguments
+
+  func run() async throws {
+    try await withGRPCClient(
+      transport: .http2NIOPosix(
+        target: self.arguments.target,
+        transportSecurity: .plaintext
+      )
+    ) { client in
+      let echo = Echo_Echo.Client(wrapping: client)
+      let requestMetadata: Metadata = ["echo-message": "\(arguments.message)"]
+
+      print("collect → metadata: \(requestMetadata)")
+      try await echo.collect(metadata: requestMetadata) { writer in
+        for part in self.arguments.message.split(separator: " ") {
+          print("collect → \(part)")
+          try await writer.write(.with { $0.text = String(part) })
+        }
+      } onResponse: { response in
+        print(
+          "collect ← initial metadata: \(response.metadata.filter({ $0.key.starts(with: "echo-") }))"
+        )
+        print("collect ← message: \(try response.message.text)")
+        print("collect ← trailing metadata: \(response.trailingMetadata)")
+      }
+    }
+  }
+}

Examples/echo-metadata/Sources/Subcommands/Echo.swift

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025, gRPC Authors All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import ArgumentParser
+import GRPCCore
+import GRPCNIOTransportHTTP2
+
+struct Expand: AsyncParsableCommand {
+  static let configuration = CommandConfiguration(
+    abstract: "Makes a server streaming RPC to the echo-metadata server."
+  )
+
+  @OptionGroup
+  var arguments: ClientArguments
+
+  func run() async throws {
+    try await withGRPCClient(
+      transport: .http2NIOPosix(
+        target: self.arguments.target,
+        transportSecurity: .plaintext
+      )
+    ) { client in
+      let echo = Echo_Echo.Client(wrapping: client)
+      let requestMetadata: Metadata = ["echo-message": "\(arguments.message)"]
+      let message = Echo_EchoRequest.with { $0.text = self.arguments.message }
+
+      print("expand → metadata: \(requestMetadata)")
+      print("expand → message: \(message.text)")
+
+      try await echo.expand(message, metadata: requestMetadata) { response in
+        let responseContents = try response.accepted.get()
+
+        print(
+          "expand ← initial metadata: \(Metadata(responseContents.metadata.filter({ $0.key.starts(with: "echo-") })))"
+        )
+        for try await part in responseContents.bodyParts {
+          switch part {
+          case .message(let message):
+            print("expand ← message: \(message.text)")
+
+          case .trailingMetadata(let trailingMetadata):
+            print(
+              "expand ← trailing metadata: \(Metadata(trailingMetadata.filter({ $0.key.starts(with: "echo-") })))"
+            )
+          }
+        }
+      }
+    }
+  }
+}