1 /* 2 * Copyright 2016 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc; 18 19 import io.grpc.Attributes.Key; 20 import java.util.concurrent.Executor; 21 22 /** 23 * Carries credential data that will be propagated to the server via request metadata for each RPC. 24 * 25 * <p>This is used by {@link CallOptions#withCallCredentials} and {@code withCallCredentials()} on 26 * the generated stub, for example: 27 * <pre> 28 * FooGrpc.FooStub stub = FooGrpc.newStub(channel); 29 * response = stub.withCallCredentials(creds).bar(request); 30 * </pre> 31 * 32 * <p>The contents and nature of this interface (and whether it remains an interface) is 33 * experimental, in that it can change. However, we are guaranteeing stability for the 34 * <em>name</em>. That is, we are guaranteeing stability for code to be returned a reference and 35 * pass that reference to gRPC for usage. However, code may not call or implement the {@code 36 * CallCredentials} itself if it wishes to only use stable APIs. 37 */ 38 public interface CallCredentials { 39 /** 40 * The security level of the transport. It is guaranteed to be present in the {@code attrs} passed 41 * to {@link #applyRequestMetadata}. It is by default {@link SecurityLevel#NONE} but can be 42 * overridden by the transport. 43 */ 44 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 45 public static final Key<SecurityLevel> ATTR_SECURITY_LEVEL = 46 Key.create("io.grpc.CallCredentials.securityLevel"); 47 48 /** 49 * The authority string used to authenticate the server. Usually it's the server's host name. It 50 * is guaranteed to be present in the {@code attrs} passed to {@link #applyRequestMetadata}. It is 51 * by default from the channel, but can be overridden by the transport and {@link 52 * io.grpc.CallOptions} with increasing precedence. 53 */ 54 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 55 public static final Key<String> ATTR_AUTHORITY = Key.create("io.grpc.CallCredentials.authority"); 56 57 /** 58 * Pass the credential data to the given {@link MetadataApplier}, which will propagate it to 59 * the request metadata. 60 * 61 * <p>It is called for each individual RPC, within the {@link Context} of the call, before the 62 * stream is about to be created on a transport. Implementations should not block in this 63 * method. If metadata is not immediately available, e.g., needs to be fetched from network, the 64 * implementation may give the {@code applier} to an asynchronous task which will eventually call 65 * the {@code applier}. The RPC proceeds only after the {@code applier} is called. 66 * 67 * @param method The method descriptor of this RPC 68 * @param attrs Additional attributes from the transport, along with the keys defined in this 69 * interface (i.e. the {@code ATTR_*} fields) which are guaranteed to be present. 70 * @param appExecutor The application thread-pool. It is provided to the implementation in case it 71 * needs to perform blocking operations. 72 * @param applier The outlet of the produced headers. It can be called either before or after this 73 * method returns. 74 */ 75 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") applyRequestMetadata( MethodDescriptor<?, ?> method, Attributes attrs, Executor appExecutor, MetadataApplier applier)76 void applyRequestMetadata( 77 MethodDescriptor<?, ?> method, Attributes attrs, 78 Executor appExecutor, MetadataApplier applier); 79 80 /** 81 * Should be a noop but never called; tries to make it clearer to implementors that they may break 82 * in the future. 83 */ 84 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") thisUsesUnstableApi()85 void thisUsesUnstableApi(); 86 87 /** 88 * The outlet of the produced headers. Not thread-safe. 89 * 90 * <p>Exactly one of its methods must be called to make the RPC proceed. 91 */ 92 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 93 public interface MetadataApplier { 94 /** 95 * Called when headers are successfully generated. They will be merged into the original 96 * headers. 97 */ apply(Metadata headers)98 void apply(Metadata headers); 99 100 /** 101 * Called when there has been an error when preparing the headers. This will fail the RPC. 102 */ fail(Status status)103 void fail(Status status); 104 } 105 } 106