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 * @deprecated transport implementations should use {@code 45 * io.grpc.internal.GrpcAttributes.ATTR_SECURITY_LEVEL} instead. 46 */ 47 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 48 @Grpc.TransportAttr 49 @Deprecated 50 public static final Key<SecurityLevel> ATTR_SECURITY_LEVEL = 51 Key.create("io.grpc.internal.GrpcAttributes.securityLevel"); 52 53 /** 54 * The authority string used to authenticate the server. Usually it's the server's host name. It 55 * is guaranteed to be present in the {@code attrs} passed to {@link #applyRequestMetadata}. It is 56 * by default from the channel, but can be overridden by the transport and {@link 57 * io.grpc.CallOptions} with increasing precedence. 58 */ 59 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 60 @Grpc.TransportAttr 61 @Deprecated 62 public static final Key<String> ATTR_AUTHORITY = Key.create("io.grpc.CallCredentials.authority"); 63 64 /** 65 * Pass the credential data to the given {@link MetadataApplier}, which will propagate it to 66 * the request metadata. 67 * 68 * <p>It is called for each individual RPC, within the {@link Context} of the call, before the 69 * stream is about to be created on a transport. Implementations should not block in this 70 * method. If metadata is not immediately available, e.g., needs to be fetched from network, the 71 * implementation may give the {@code applier} to an asynchronous task which will eventually call 72 * the {@code applier}. The RPC proceeds only after the {@code applier} is called. 73 * 74 * @param method The method descriptor of this RPC 75 * @param attrs Additional attributes from the transport, along with the keys defined in this 76 * interface (i.e. the {@code ATTR_*} fields) which are guaranteed to be present. 77 * @param appExecutor The application thread-pool. It is provided to the implementation in case it 78 * needs to perform blocking operations. 79 * @param applier The outlet of the produced headers. It can be called either before or after this 80 * method returns. 81 * 82 * @deprecated implement {@link CallCredentials2} instead. 83 */ 84 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 85 @Deprecated applyRequestMetadata( MethodDescriptor<?, ?> method, Attributes attrs, Executor appExecutor, MetadataApplier applier)86 void applyRequestMetadata( 87 MethodDescriptor<?, ?> method, Attributes attrs, 88 Executor appExecutor, MetadataApplier applier); 89 90 /** 91 * Should be a noop but never called; tries to make it clearer to implementors that they may break 92 * in the future. 93 */ 94 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") thisUsesUnstableApi()95 void thisUsesUnstableApi(); 96 97 /** 98 * The outlet of the produced headers. Not thread-safe. 99 * 100 * <p>Exactly one of its methods must be called to make the RPC proceed. 101 */ 102 @Deprecated 103 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 104 public interface MetadataApplier { 105 /** 106 * Called when headers are successfully generated. They will be merged into the original 107 * headers. 108 */ apply(Metadata headers)109 void apply(Metadata headers); 110 111 /** 112 * Called when there has been an error when preparing the headers. This will fail the RPC. 113 */ fail(Status status)114 void fail(Status status); 115 } 116 117 /** 118 * The request-related information passed to {@code CallCredentials2.applyRequestMetadata()}. 119 */ 120 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 121 public abstract static class RequestInfo { 122 /** 123 * The method descriptor of this RPC. 124 */ getMethodDescriptor()125 public abstract MethodDescriptor<?, ?> getMethodDescriptor(); 126 127 /** 128 * The security level on the transport. 129 */ getSecurityLevel()130 public abstract SecurityLevel getSecurityLevel(); 131 132 /** 133 * Returns the authority string used to authenticate the server for this call. 134 */ getAuthority()135 public abstract String getAuthority(); 136 137 /** 138 * Returns the transport attributes. 139 */ 140 @Grpc.TransportAttr getTransportAttrs()141 public abstract Attributes getTransportAttrs(); 142 } 143 } 144