feat(xds): Add ExtAuthzClientInterceptor and related components

This commit introduces the client-side implementation of the external authorization filter.

The main component is the `ExtAuthzClientInterceptor`, which intercepts outgoing RPCs and performs external authorization checks. It uses a `BufferingAuthzClientCall` to buffer the outgoing RPC until the authorization decision is received from the authorization service.

The following new classes are introduced:
- `ExtAuthzClientInterceptor`: The main client interceptor for external authorization.
- `BufferingAuthzClientCall`: A `ClientCall` implementation that buffers requests until an authorization decision is made.
- `CallBuffer`: A helper class for `BufferingAuthzClientCall` to manage the buffered calls.
- `FailingClientCall`: A utility `ClientCall` that immediately fails, used when the filter is disabled and configured to deny calls.

This commit also includes comprehensive unit and integration tests for the new components.

Author: sauravzg

core/src/main/java/io/grpc/internal/FailingClientCall.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2025 The gRPC Authors
+ *
+ * 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.
+ */
+
+package io.grpc.internal;
+
+import io.grpc.ClientCall;
+import io.grpc.Metadata;
+import io.grpc.Status;
+import javax.annotation.Nullable;
+
+/**
+ * A {@link ClientCall} that fails immediately upon starting.
+ */
+public final class FailingClientCall<ReqT, RespT> extends ClientCall<ReqT, RespT> {
+
+  private final Status error;
+
+  /**
+   * Creates a new call that will fail with the given error.
+   */
+  public FailingClientCall(Status error) {
+    this.error = error;
+  }
+
+  /**
+   * Immediately fails the call by calling {@link Listener#onClose}.
+   */
+  @Override
+  public void start(Listener<RespT> responseListener, Metadata headers) {
+    responseListener.onClose(error, new Metadata());
+  }
+
+  @Override
+  public void request(int numMessages) {}
+
+  @Override
+  public void cancel(@Nullable String message, @Nullable Throwable cause) {}
+
+  @Override
+  public void halfClose() {}
+
+  @Override
+  public void sendMessage(ReqT message) {}
+}

core/src/test/java/io/grpc/internal/FailingClientCallTest.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2016 The gRPC Authors
+ *
+ * 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.
+ */
+
+package io.grpc.internal;
+
+import static org.junit.Assert.assertEquals;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoMoreInteractions;
+
+import io.grpc.ClientCall;
+import io.grpc.Metadata;
+import io.grpc.Status;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.MockitoJUnit;
+import org.mockito.junit.MockitoRule;
+
+/** Unit tests for {@link FailingClientCall}. */
+@RunWith(JUnit4.class)
+public class FailingClientCallTest {
+
+  @Rule public final MockitoRule mocks = MockitoJUnit.rule();
+
+  @Mock
+  private ClientCall.Listener<Object> mockListener;
+
+  @Test
+  public void startCallsOnClose() {
+    Status error = Status.UNAVAILABLE.withDescription("test error");
+    FailingClientCall<Object, Object> call = new FailingClientCall<>(error);
+    Metadata metadata = new Metadata();
+    call.start(mockListener, metadata);
+
+    ArgumentCaptor<Metadata> metadataCaptor = ArgumentCaptor.forClass(Metadata.class);
+    verify(mockListener).onClose(eq(error), metadataCaptor.capture());
+    assertEquals(0, metadataCaptor.getValue().keys().size());
+    verifyNoMoreInteractions(mockListener);
+  }
+
+  @Test
+  public void otherMethodsAreNoOps() {
+    Status error = Status.UNAVAILABLE.withDescription("test error");
+    FailingClientCall<Object, Object> call = new FailingClientCall<>(error);
+    Metadata metadata = new Metadata();
+
+    call.start(mockListener, metadata); // Must call start first
+
+    call.request(1);
+    call.cancel("message", new RuntimeException("cause"));
+    call.halfClose();
+    call.sendMessage(new Object());
+
+    ArgumentCaptor<Metadata> metadataCaptor = ArgumentCaptor.forClass(Metadata.class);
+    verify(mockListener).onClose(eq(error), metadataCaptor.capture());
+    assertEquals(0, metadataCaptor.getValue().keys().size());
+    verifyNoMoreInteractions(mockListener);
+  }
+}

xds/src/main/java/io/grpc/xds/ThreadSafeRandom.java

@@ -16,36 +16,34 @@
 
 package io.grpc.xds;
 
-import java.util.concurrent.ThreadLocalRandom;
 import javax.annotation.concurrent.ThreadSafe;
 
-@ThreadSafe // Except for impls/mocks in tests
-interface ThreadSafeRandom {
-  int nextInt(int bound);
-
-  long nextLong();
-
-  long nextLong(long bound);
+// TODO(sauravzg): Remove this class once all usages within xds are migrated to
+// the internal version.
+@ThreadSafe
+interface ThreadSafeRandom extends io.grpc.xds.internal.ThreadSafeRandom {
 
   final class ThreadSafeRandomImpl implements ThreadSafeRandom {
 
     static final ThreadSafeRandom instance = new ThreadSafeRandomImpl();
+    private final io.grpc.xds.internal.ThreadSafeRandom delegate =
+        io.grpc.xds.internal.ThreadSafeRandom.ThreadSafeRandomImpl.INSTANCE;
 
     private ThreadSafeRandomImpl() {}
 
     @Override
     public int nextInt(int bound) {
-      return ThreadLocalRandom.current().nextInt(bound);
+      return delegate.nextInt(bound);
     }
 
     @Override
     public long nextLong() {
-      return ThreadLocalRandom.current().nextLong();
+      return delegate.nextLong();
     }
 
     @Override
     public long nextLong(long bound) {
-      return ThreadLocalRandom.current().nextLong(bound);
+      return delegate.nextLong(bound);
     }
   }
 }

xds/src/main/java/io/grpc/xds/internal/ThreadSafeRandom.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2023 The gRPC Authors
+ *
+ * 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.
+ */
+
+package io.grpc.xds.internal;
+
+import java.util.concurrent.ThreadLocalRandom;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A thread-safe random number generator. This is intended for internal use only.
+ */
+@ThreadSafe // Except for impls/mocks in tests
+public interface ThreadSafeRandom {
+  int nextInt(int bound);
+
+  long nextLong();
+
+  long nextLong(long bound);
+
+  final class ThreadSafeRandomImpl implements ThreadSafeRandom {
+
+    public static final ThreadSafeRandom INSTANCE = new ThreadSafeRandomImpl();
+
+    private ThreadSafeRandomImpl() {}
+
+    @Override
+    public int nextInt(int bound) {
+      return ThreadLocalRandom.current().nextInt(bound);
+    }
+
+    @Override
+    public long nextLong() {
+      return ThreadLocalRandom.current().nextLong();
+    }
+
+    @Override
+    public long nextLong(long bound) {
+      return ThreadLocalRandom.current().nextLong(bound);
+    }
+  }
+}