From 68b4f42e7a00fd2c47ca1c9a84353ddf9c799373 Mon Sep 17 00:00:00 2001
From: deadEternally <kannan.jayaprakasam@gmail.com>
Date: Sat, 1 Feb 2025 21:33:20 +0530
Subject: [PATCH 1/2] Changes

---
 stub/src/main/java/io/grpc/stub/ClientCalls.java | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/stub/src/main/java/io/grpc/stub/ClientCalls.java b/stub/src/main/java/io/grpc/stub/ClientCalls.java
index 13fb00d3b3e..8f83670558d 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCalls.java
@@ -100,6 +100,12 @@ public static <ReqT, RespT> void asyncServerStreamingCall(
    * {@code beforeStart()} will be called.
    *
    * @return request stream observer. It will extend {@link ClientCallStreamObserver}
+   * onError called on the request stream observer will result in stream cancellation. The response
+   * {@link StreamObserver} will be immediately notified of the cancellation with a
+   * {@link io.grpc.StatusRuntimeException}. The server's request stream observer will receive an
+   * onError callbackk from the gRPC server framework with a {@link io.grpc.StatusRuntimeException}
+   * for the cancellation. The actual exception passed by the client to onError is never actually
+   * transmitted to the server.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
       ClientCall<ReqT, RespT> call,
@@ -116,6 +122,12 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
    * {@code beforeStart()} will be called.
    *
    * @return request stream observer. It will extend {@link ClientCallStreamObserver}
+   * onError called on the request stream observer will result in stream cancellation. The response
+   * {@link StreamObserver} will be immediately notified of the cancellation with a
+   * {@link io.grpc.StatusRuntimeException}. The server's request stream observer will receive an
+   * onError callbackk from the gRPC server framework with a {@link io.grpc.StatusRuntimeException}
+   * for the cancellation. The actual exception passed by the client to onError is never actually
+   * transmitted to the server.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
       ClientCall<ReqT, RespT> call, StreamObserver<RespT> responseObserver) {

From 916e8487175bbadc8ff6d01dc55df1a769912a23 Mon Sep 17 00:00:00 2001
From: deadEternally <kannan.jayaprakasam@gmail.com>
Date: Tue, 4 Feb 2025 14:08:29 +0530
Subject: [PATCH 2/2] Documenting error transmission and callback behavior.

---
 .../main/java/io/grpc/stub/ClientCalls.java   | 52 ++++++++++++++---
 .../main/java/io/grpc/stub/ServerCalls.java   | 58 +++++++++++++++++++
 2 files changed, 102 insertions(+), 8 deletions(-)

diff --git a/stub/src/main/java/io/grpc/stub/ClientCalls.java b/stub/src/main/java/io/grpc/stub/ClientCalls.java
index 8f83670558d..194e37acd7a 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCalls.java
@@ -70,6 +70,13 @@ private ClientCalls() {}
    *
    * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
    * {@code beforeStart()} will be called.
+   *
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
+   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
+   * description will be encoded to the stream trailer, but the cause (which may contain server
+   * application's information) will not.
    */
   public static <ReqT, RespT> void asyncUnaryCall(
       ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -84,6 +91,13 @@ public static <ReqT, RespT> void asyncUnaryCall(
    *
    * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
    * {@code beforeStart()} will be called.
+   *
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
+   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
+   * description will be encoded to the stream trailer, but the cause (which may contain server
+   * application's information) will not.
    */
   public static <ReqT, RespT> void asyncServerStreamingCall(
       ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -100,12 +114,23 @@ public static <ReqT, RespT> void asyncServerStreamingCall(
    * {@code beforeStart()} will be called.
    *
    * @return request stream observer. It will extend {@link ClientCallStreamObserver}
+   *
+   * <h3>Client errors</h3>
    * onError called on the request stream observer will result in stream cancellation. The response
    * {@link StreamObserver} will be immediately notified of the cancellation with a
-   * {@link io.grpc.StatusRuntimeException}. The server's request stream observer will receive an
-   * onError callbackk from the gRPC server framework with a {@link io.grpc.StatusRuntimeException}
-   * for the cancellation. The actual exception passed by the client to onError is never actually
-   * transmitted to the server.
+   * {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
+   * and the stream is considered closed. The server's request stream observer will receive an
+   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
+   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * passed by the client to onError is never actually transmitted to the server and the server
+   * just receives a RST_STREAM frame indicating cancellation by the client.
+   *
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
+   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
+   * description will be encoded to the stream trailer, but the cause (which may contain server
+   * application's information) will not.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
       ClientCall<ReqT, RespT> call,
@@ -122,12 +147,23 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
    * {@code beforeStart()} will be called.
    *
    * @return request stream observer. It will extend {@link ClientCallStreamObserver}
+   *
+   * <h3>Client errors</h3>
    * onError called on the request stream observer will result in stream cancellation. The response
    * {@link StreamObserver} will be immediately notified of the cancellation with a
-   * {@link io.grpc.StatusRuntimeException}. The server's request stream observer will receive an
-   * onError callbackk from the gRPC server framework with a {@link io.grpc.StatusRuntimeException}
-   * for the cancellation. The actual exception passed by the client to onError is never actually
-   * transmitted to the server.
+   * {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
+   * and the stream is considered closed. The server's request stream observer will receive an
+   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
+   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * passed by the client to onError is never actually transmitted to the server and the server
+   * just receives a RST_STREAM frame indicating cancellation by the client.
+   *
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be
+   * received by the {@link ClientCall}'s onClose, and UNKNOWN status code otherwise. Its
+   * description will be encoded to the stream trailer, but the cause (which may contain server
+   * application's information) will not.
    */
   public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
       ClientCall<ReqT, RespT> call, StreamObserver<RespT> responseObserver) {
diff --git a/stub/src/main/java/io/grpc/stub/ServerCalls.java b/stub/src/main/java/io/grpc/stub/ServerCalls.java
index 7990a5b34c0..b16bc396a04 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCalls.java
@@ -26,6 +26,8 @@
 import io.grpc.ServerCall;
 import io.grpc.ServerCallHandler;
 import io.grpc.Status;
+import io.grpc.StatusException;
+import io.grpc.StatusRuntimeException;
 
 /**
  * Utility functions for adapting {@link ServerCallHandler}s to application service implementation,
@@ -45,6 +47,14 @@ private ServerCalls() {
    * Creates a {@link ServerCallHandler} for a unary call method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
+   * <p>
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be sent
+   * and UNKNOWN status code otherwise. Its description will be encoded to the stream trailer, but
+   * the cause (which may contain server application's information) will not. After the stream
+   * trailer with END_STREAM is sent, the server side call is considered to be closed.
+   * </p>
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncUnaryCall(
       UnaryMethod<ReqT, RespT> method) {
@@ -55,6 +65,22 @@ public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncUnaryCall(
    * Creates a {@link ServerCallHandler} for a server streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
+   * <p>
+   * <h3>Client errors</h3>
+   * The server's request stream observer will receive an
+   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
+   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * passed by the client to onError is never actually transmitted to the server and the server just
+   * receives a RST_STREAM frame indicating cancellation by the client.
+   * </p>
+   * <p>
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be sent
+   * and UNKNOWN status code otherwise. Its description will be encoded to the stream trailer, but
+   * the cause (which may contain server application's information) will not. After the stream
+   * trailer with END_STREAM is sent, the server side call is considered to be closed.
+   * </p>
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncServerStreamingCall(
       ServerStreamingMethod<ReqT, RespT> method) {
@@ -65,6 +91,22 @@ public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncServerStreamingC
    * Creates a {@link ServerCallHandler} for a client streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
+   * <p>
+   * <h3>Client errors</h3>
+   * The server's request stream observer will receive an
+   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
+   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * passed by the client to onError is never actually transmitted to the server and the server just
+   * receives a RST_STREAM frame indicating cancellation by the client.
+   * </p>
+   * <p>
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be sent
+   * and UNKNOWN status code otherwise. Its description will be encoded to the stream trailer, but
+   * the cause (which may contain server application's information) will not. After the stream
+   * trailer with END_STREAM is sent, the server side call is considered to be closed.
+   * </p>
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncClientStreamingCall(
       ClientStreamingMethod<ReqT, RespT> method) {
@@ -75,6 +117,22 @@ public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncClientStreamingC
    * Creates a {@link ServerCallHandler} for a bidi streaming method of the service.
    *
    * @param method an adaptor to the actual method on the service implementation.
+   * <p>
+   * <h3>Client errors</h3>
+   * The server's request stream observer will receive an
+   * onError callback with a {@link io.grpc.StatusRuntimeException} for the cancellation with the
+   * message 'Client cancelled', and exception cause set to null because the actual exception
+   * passed by the client to onError is never actually transmitted to the server and the server just
+   * receives a RST_STREAM frame indicating cancellation by the client.
+   * </p>
+   * <p>
+   * <h3>Server errors</h3>
+   * If the throwable sent to the server's outbound {@link StreamObserver}'s onError
+   * is a {@link StatusException} or {@link StatusRuntimeException}, that status code will be sent
+   * and UNKNOWN status code otherwise. Its description will be encoded to the stream trailer, but
+   * the cause (which may contain server application's information) will not. After the stream
+   * trailer with END_STREAM is sent, the server side call is considered to be closed.
+   * </p>
    */
   public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncBidiStreamingCall(
       BidiStreamingMethod<ReqT, RespT> method) {