Stabilize auth flow using CallCredentials

auth/src/main/java/io/grpc/auth/GoogleAuthLibraryCallCredentials.java

@@ -68,6 +68,9 @@ public GoogleAuthLibraryCallCredentials(Credentials creds) {
     this.creds = creds;
   }
 
+  @Override
+  public void thisUsesUnstableApi() {}
+
   @Override
   public void applyRequestMetadata(MethodDescriptor<?, ?> method, Attributes attrs,
       Executor appExecutor, final MetadataApplier applier) {

auth/src/main/java/io/grpc/auth/MoreCallCredentials.java

@@ -18,15 +18,18 @@
 
 import com.google.auth.Credentials;
 import io.grpc.CallCredentials;
-import io.grpc.ExperimentalApi;
 
 /**
  * A utility class that converts other types of credentials to {@link CallCredentials}.
  */
-@ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914")
 public final class MoreCallCredentials {
   /**
    * Converts a Google Auth Library {@link Credentials} to {@link CallCredentials}.
+   *
+   * <p>Although this is a stable API, note that the returned instance's API is not stable. You are
+   * free to use the class name {@code CallCredentials} and pass the instance to other code, but the
+   * instance can't be called directly from code expecting stable behavior. See {@link
+   * CallCredentials}.
    */
   public static CallCredentials from(Credentials creds) {
     return new GoogleAuthLibraryCallCredentials(creds);

core/src/main/java/io/grpc/CallCredentials.java

@@ -28,14 +28,20 @@
  * FooGrpc.FooStub stub = FooGrpc.newStub(channel);
  * response = stub.withCallCredentials(creds).bar(request);
  * </pre>
+ *
+ * <p>The contents and nature of this interface (and whether it remains an interface) is
+ * experimental, in that it can change. However, we are guaranteeing stability for the
+ * <em>name</em>. That is, we are guaranteeing stability for code to be returned a reference and
+ * pass that reference to gRPC for usage. However, code may not call or implement the {@code
+ * CallCredentials} itself if it wishes to only use stable APIs.
  */
-@ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914")
 public interface CallCredentials {
   /**
    * The security level of the transport. It is guaranteed to be present in the {@code attrs} passed
    * to {@link #applyRequestMetadata}. It is by default {@link SecurityLevel#NONE} but can be
    * overridden by the transport.
    */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
   public static final Key<SecurityLevel> ATTR_SECURITY_LEVEL =
       Key.of("io.grpc.CallCredentials.securityLevel");
 
@@ -45,6 +51,7 @@ public interface CallCredentials {
    * by default from the channel, but can be overridden by the transport and {@link
    * io.grpc.CallOptions} with increasing precedence.
    */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
   public static final Key<String> ATTR_AUTHORITY = Key.of("io.grpc.CallCredentials.authority");
 
   /**
@@ -65,15 +72,24 @@ public interface CallCredentials {
    * @param applier The outlet of the produced headers. It can be called either before or after this
    *        method returns.
    */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
   void applyRequestMetadata(
       MethodDescriptor<?, ?> method, Attributes attrs,
       Executor appExecutor, MetadataApplier applier);
 
+  /**
+   * Should be a noop but never called; tries to make it clearer to implementors that they may break
+   * in the future.
+   */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
+  void thisUsesUnstableApi();
+
   /**
    * The outlet of the produced headers. Not thread-safe.
    *
    * <p>Exactly one of its methods must be called to make the RPC proceed.
    */
+  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914")
   public interface MetadataApplier {
     /**
      * Called when headers are successfully generated. They will be merged into the original

core/src/main/java/io/grpc/CallOptions.java

@@ -91,7 +91,6 @@ public CallOptions withAuthority(@Nullable String authority) {
   /**
    * Returns a new {@code CallOptions} with the given call credentials.
    */
-  @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914")
   public CallOptions withCallCredentials(@Nullable CallCredentials credentials) {
     CallOptions newOptions = new CallOptions(this);
     newOptions.credentials = credentials;
@@ -187,7 +186,6 @@ public String getAuthority() {
   /**
    * Returns the call credentials.
    */
-  @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914")
   @Nullable
   public CallCredentials getCredentials() {
     return credentials;

stub/src/main/java/io/grpc/stub/AbstractStub.java

@@ -173,7 +173,6 @@ public final S withInterceptors(ClientInterceptor... interceptors) {
    *
    * @since 1.0.0
    */
-  @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914")
   public final S withCallCredentials(CallCredentials credentials) {
     return build(channel, callOptions.withCallCredentials(credentials));
   }