Merge remote-tracking branch 'origin/master' into server-framework-custom-events

Author: kannanjgithub

.github/workflows/branch-testing.yml

@@ -20,14 +20,14 @@ jobs:
       fail-fast: false # Should swap to true if we grow a large matrix
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
     - uses: actions/setup-java@v5
       with:
         java-version: ${{ matrix.jre }}
         distribution: 'temurin'
 
     - name: Gradle cache
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: |
           ~/.gradle/caches

.github/workflows/gradle-wrapper-validation.yml

@@ -9,5 +9,5 @@ jobs:
     name: "Gradle wrapper validation"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: gradle/actions/wrapper-validation@v6

.github/workflows/testing.yml

@@ -21,14 +21,14 @@ jobs:
       fail-fast: false # Should swap to true if we grow a large matrix
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
     - uses: actions/setup-java@v5
       with:
         java-version: ${{ matrix.jre }}
         distribution: 'temurin'
 
     - name: Gradle cache
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: |
           ~/.gradle/caches
@@ -37,7 +37,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-gradle-
     - name: Maven cache
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: |
           ~/.m2/repository
@@ -46,7 +46,7 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-maven-
     - name: Protobuf cache
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: /tmp/protobuf-cache
         key: ${{ runner.os }}-maven-${{ hashFiles('buildscripts/make_dependencies.sh') }}
@@ -71,7 +71,7 @@ jobs:
         COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
       run: ./gradlew :grpc-all:coveralls -PskipAndroid=true -x compileJava
     - name: Codecov
-      uses: codecov/codecov-action@v6
+      uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
 
@@ -88,15 +88,15 @@ jobs:
       USE_BAZEL_VERSION: ${{ matrix.bazel_version }}
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
 
     - name: Check versions match in MODULE.bazel and repositories.bzl
       run: |
         diff -u <(sed -n '/GRPC_DEPS_START/,/GRPC_DEPS_END/ {/GRPC_DEPS_/! p}' MODULE.bazel) \
                 <(sed -n '/GRPC_DEPS_START/,/GRPC_DEPS_END/ {/GRPC_DEPS_/! p}' repositories.bzl)
 
     - name: Bazel cache
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: |
           ~/.cache/bazel/*/cache

MODULE.bazel

@@ -20,9 +20,9 @@ IO_GRPC_GRPC_JAVA_ARTIFACTS = [
     "com.google.re2j:re2j:1.8",
     "com.google.s2a.proto.v2:s2a-proto:0.1.3",
     "com.google.truth:truth:1.4.5",
-    "dev.cel:runtime:0.13.0",
-    "dev.cel:protobuf:0.13.0",
-    "dev.cel:common:0.13.0",
+    "dev.cel:runtime:0.13.1",
+    "dev.cel:protobuf:0.13.1",
+    "dev.cel:common:0.13.1",
     "com.squareup.okhttp:okhttp:2.7.5",
     "com.squareup.okio:okio:2.10.0",  # 3.0+ needs swapping to -jvm; need work to avoid flag-day
     "io.netty:netty-buffer:4.2.15.Final",

README.md

@@ -44,8 +44,8 @@ For a guided tour, take a look at the [quick start
 guide](https://grpc.io/docs/languages/java/quickstart) or the more explanatory [gRPC
 basics](https://grpc.io/docs/languages/java/basics).
 
-The [examples](https://github.com/grpc/grpc-java/tree/v1.82.1/examples) and the
-[Android example](https://github.com/grpc/grpc-java/tree/v1.82.1/examples/android)
+The [examples](https://github.com/grpc/grpc-java/tree/v1.83.1/examples) and the
+[Android example](https://github.com/grpc/grpc-java/tree/v1.83.1/examples/android)
 are standalone projects that showcase the usage of gRPC.
 
 Download
@@ -56,42 +56,42 @@ Download [the JARs][]. Or for Maven with non-Android, add to your `pom.xml`:
 <dependency>
   <groupId>io.grpc</groupId>
   <artifactId>grpc-netty-shaded</artifactId>
-  <version>1.82.1</version>
+  <version>1.83.1</version>
   <scope>runtime</scope>
 </dependency>
 <dependency>
   <groupId>io.grpc</groupId>
   <artifactId>grpc-protobuf</artifactId>
-  <version>1.82.1</version>
+  <version>1.83.1</version>
 </dependency>
 <dependency>
   <groupId>io.grpc</groupId>
   <artifactId>grpc-stub</artifactId>
-  <version>1.82.1</version>
+  <version>1.83.1</version>
 </dependency>
 ```
 
 Or for Gradle with non-Android, add to your dependencies:
 ```gradle
-runtimeOnly 'io.grpc:grpc-netty-shaded:1.82.1'
-implementation 'io.grpc:grpc-protobuf:1.82.1'
-implementation 'io.grpc:grpc-stub:1.82.1'
+runtimeOnly 'io.grpc:grpc-netty-shaded:1.83.1'
+implementation 'io.grpc:grpc-protobuf:1.83.1'
+implementation 'io.grpc:grpc-stub:1.83.1'
 ```
 
 For Android client, use `grpc-okhttp` instead of `grpc-netty-shaded` and
 `grpc-protobuf-lite` instead of `grpc-protobuf`:
 ```gradle
-implementation 'io.grpc:grpc-okhttp:1.82.1'
-implementation 'io.grpc:grpc-protobuf-lite:1.82.1'
-implementation 'io.grpc:grpc-stub:1.82.1'
+implementation 'io.grpc:grpc-okhttp:1.83.1'
+implementation 'io.grpc:grpc-protobuf-lite:1.83.1'
+implementation 'io.grpc:grpc-stub:1.83.1'
 ```
 
 For [Bazel](https://bazel.build), you can either
 [use Maven](https://github.com/bazelbuild/rules_jvm_external)
 (with the GAVs from above), or use `@io_grpc_grpc_java//api` et al (see below).
 
 [the JARs]:
-https://search.maven.org/search?q=g:io.grpc%20AND%20v:1.82.1
+https://search.maven.org/search?q=g:io.grpc%20AND%20v:1.83.1
 
 Development snapshots are available in [Sonatypes's snapshot
 repository](https://central.sonatype.com/repository/maven-snapshots/).
@@ -123,7 +123,7 @@ For protobuf-based codegen integrated with the Maven build system, you can use
       <configuration>
         <protocArtifact>com.google.protobuf:protoc:3.25.8:exe:${os.detected.classifier}</protocArtifact>
         <pluginId>grpc-java</pluginId>
-        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.82.1:exe:${os.detected.classifier}</pluginArtifact>
+        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.83.1:exe:${os.detected.classifier}</pluginArtifact>
       </configuration>
       <executions>
         <execution>
@@ -153,7 +153,7 @@ protobuf {
   }
   plugins {
     grpc {
-      artifact = 'io.grpc:protoc-gen-grpc-java:1.82.1'
+      artifact = 'io.grpc:protoc-gen-grpc-java:1.83.1'
     }
   }
   generateProtoTasks {
@@ -186,7 +186,7 @@ protobuf {
   }
   plugins {
     grpc {
-      artifact = 'io.grpc:protoc-gen-grpc-java:1.82.1'
+      artifact = 'io.grpc:protoc-gen-grpc-java:1.83.1'
     }
   }
   generateProtoTasks {

api/build.gradle

@@ -17,13 +17,11 @@ sourceSets {
 }
 
 tasks.named("compileContextJava").configure {
-    if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_20)) {
-        println("!!! Javac does not support generating Java 7 bytecode. Do not use for release builds !!!")
-    } else if (JavaVersion.current().isJava9Compatible()) {
-        options.release = 7
+    if (JavaVersion.current().isJava9Compatible()) {
+        options.release = 8
     } else {
-        sourceCompatibility = JavaVersion.VERSION_1_7
-        targetCompatibility = JavaVersion.VERSION_1_7
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
     }
 }
 

api/src/main/java/io/grpc/ClientInterceptor.java

@@ -32,6 +32,11 @@
  * CallCredentials}. But a {@code ClientInterceptor} could set the {@code
  * CallCredentials} within the {@link CallOptions}.
  *
+ * <p>From gRPC's perspective, interceptors don't generally exist and are more of a convenience.
+ * Convenience APIs will use {@link ClientInterceptors} to convert the interceptor into a {@code
+ * Channel}. Thus interceptors are an extension of the application and run on the same
+ * threads and receive callbacks using the same executor.
+ *
  * <p>The interceptor may be called for multiple {@link ClientCall calls} by one or more threads
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ClientCall.Listener ClientCall.Listener} docs for more details regarding thread

api/src/main/java/io/grpc/ManagedChannelBuilder.java

@@ -92,12 +92,13 @@ public static ManagedChannelBuilder<?> forTarget(String target) {
   }
 
   /**
-   * Execute application code directly in the transport thread.
-   *
-   * <p>Depending on the underlying transport, using a direct executor may lead to substantial
-   * performance improvements. However, it also requires the application to not block under
+   * Execute application code directly in the transport thread. The application must not block under
    * any circumstances.
    *
+   * <p>Depending on the underlying transport and the application code, using a direct executor may
+   * lead to 10s of µs latency reduction but causes a substantial performance degradation when
+   * misused.
+   *
    * <p>Calling this method is semantically equivalent to calling {@link #executor(Executor)} and
    * passing in a direct executor. However, this is the preferred way as it may allow the transport
    * to perform special optimizations.
@@ -108,7 +109,10 @@ public static ManagedChannelBuilder<?> forTarget(String target) {
   public abstract T directExecutor();
 
   /**
-   * Provides a custom executor.
+   * Set the default executor for callbacks. This is used for async and future stub callbacks, but
+   * can be overridden by {@link CallOptions#withExecutor} and {@code stub.withExecutor()}. Blocking
+   * stubs specify a per-RPC executor. This is also used for {@link
+   * ManagedChannel#notifyWhenStateChanged}.
    *
    * <p>It's an optional parameter. If the user has not provided an executor when the channel is
    * built, the builder will use a static cached thread pool.

api/src/main/java/io/grpc/ServerBuilder.java

@@ -45,12 +45,13 @@ public static ServerBuilder<?> forPort(int port) {
   }
 
   /**
-   * Execute application code directly in the transport thread.
-   *
-   * <p>Depending on the underlying transport, using a direct executor may lead to substantial
-   * performance improvements. However, it also requires the application to not block under
+   * Execute application code directly in the transport thread. The application must not block under
    * any circumstances.
    *
+   * <p>Depending on the underlying transport and the application code, using a direct executor may
+   * lead to 10s of µs latency reduction but causes a substantial performance degradation when
+   * misused.
+   *
    * <p>Calling this method is semantically equivalent to calling {@link #executor(Executor)} and
    * passing in a direct executor. However, this is the preferred way as it may allow the transport
    * to perform special optimizations.
@@ -61,10 +62,11 @@ public static ServerBuilder<?> forPort(int port) {
   public abstract T directExecutor();
 
   /**
-   * Provides a custom executor.
+   * Set the default executor for service callbacks.
    *
    * <p>It's an optional parameter. If the user has not provided an executor when the server is
-   * built, the builder will use a static cached thread pool.
+   * built, the builder will use a static cached thread pool. Users are encouraged to specify their
+   * own executor that limits the number of threads.
    *
    * <p>The server won't take ownership of the given executor. It's caller's responsibility to
    * shut down the executor when it's desired.
@@ -85,11 +87,13 @@ public static ServerBuilder<?> forPort(int port) {
    * it switches over. But if calling {@link ServerCallExecutorSupplier} returns null, the server
    * call is still handled by the default {@link #executor(Executor)} as a fallback.
    *
+   * <p>If your {@code executorSupplier} runs quickly and always returns a non-{@code null}
+   * executor, then you may want to use {@link #directExecutor} to reduce latency.
+   *
    * @param executorSupplier the server call executor provider
    * @return this
    * @since 1.39.0
-   *
-   * */
+   */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/8274")
   public T callExecutor(ServerCallExecutorSupplier executorSupplier) {
     return thisT();

api/src/main/java/io/grpc/ServerInterceptor.java

@@ -29,6 +29,11 @@
  * <li>Delegating calls to other servers</li>
  * </ul>
  *
+ * <p>From gRPC's perspective, interceptors don't generally exist and are more of a convenience.
+ * Convenience APIs will use {@link ServerInterceptors} to convert the interceptor into a {@code
+ * ServerCallHandler}. Thus interceptors are an extension of the application and run on the same
+ * threads and receive callbacks using the same executor.
+ *
  * <p>The interceptor may be called for multiple {@link ServerCall calls} by one or more threads
  * without completing the previous ones first. Refer to the
  * {@link io.grpc.ServerCall.Listener ServerCall.Listener} docs for more details regarding thread