feat(xds): Add ExtAuthzClientInterceptor and related components

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);
+    }
+  }
+}

xds/src/main/java/io/grpc/xds/internal/extauthz/AuthzResponse.java

@@ -0,0 +1,91 @@
+/*
+ * 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.xds.internal.extauthz;
+
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableList;
+import io.grpc.Metadata;
+import io.grpc.Status;
+import io.grpc.xds.internal.headermutations.HeaderMutations.ResponseHeaderMutations;
+import java.util.Optional;
+
+/**
+ * Represents the outcome of an authorization check, detailing whether the request is allowed or
+ * denied and including any associated headers or status information.
+ */
+@AutoValue
+public abstract class AuthzResponse {
+
+  /** Defines the authorization decision. */
+  public enum Decision {
+    /** The request is permitted. */
+    ALLOW,
+    /** The request is rejected. */
+    DENY,
+  }
+
+  /** Creates a builder for an ALLOW response, initializing with the specified headers. */
+  public static Builder allow(Metadata headers) {
+    return new AutoValue_AuthzResponse.Builder().setDecision(Decision.ALLOW)
+        .setResponseHeaderMutations(ResponseHeaderMutations.create(ImmutableList.of()))
+        .setHeaders(headers);
+  }
+
+  /** Creates a builder for a DENY response, initializing with the specified status. */
+  public static Builder deny(Status status) {
+    return new AutoValue_AuthzResponse.Builder().setDecision(Decision.DENY)
+        .setResponseHeaderMutations(ResponseHeaderMutations.create(ImmutableList.of()))
+        .setStatus(status);
+  }
+
+  /** Returns the authorization decision. */
+  public abstract Decision decision();
+
+  /**
+   * For DENY decisions, this provides the status to be returned to the calling client. It is empty
+   * for ALLOW decisions.
+   */
+  public abstract Optional<Status> status();
+
+  /**
+   * For ALLOW decisions, this provides the headers to be appended to the request headers for
+   * upstream. It is empty for DENY decisions.
+   */
+  public abstract Optional<Metadata> headers();
+
+  /**
+   * Returns mutations to be applied to the response headers. This is used for both ALLOW and DENY
+   * decisions.
+   */
+  public abstract ResponseHeaderMutations responseHeaderMutations();
+
+  /** Builder for creating {@link AuthzResponse} instances. */
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    abstract Builder setDecision(Decision decision);
+
+    abstract Builder setStatus(Status status);
+
+    abstract Builder setHeaders(Metadata headers);
+
+    public abstract Builder setResponseHeaderMutations(
+        ResponseHeaderMutations responseHeaderMutations);
+
+    public abstract AuthzResponse build();
+  }
+}