1 /* 2 * 3 * Copyright 2018 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef GRPCPP_IMPL_CODEGEN_CLIENT_INTERCEPTOR_H 20 #define GRPCPP_IMPL_CODEGEN_CLIENT_INTERCEPTOR_H 21 22 #include <memory> 23 #include <vector> 24 25 #include <grpcpp/impl/codegen/interceptor.h> 26 #include <grpcpp/impl/codegen/rpc_method.h> 27 #include <grpcpp/impl/codegen/string_ref.h> 28 29 namespace grpc { 30 31 class Channel; 32 class ClientContext; 33 34 namespace internal { 35 class InterceptorBatchMethodsImpl; 36 } 37 38 namespace experimental { 39 class ClientRpcInfo; 40 41 // A factory interface for creation of client interceptors. A vector of 42 // factories can be provided at channel creation which will be used to create a 43 // new vector of client interceptors per RPC. Client interceptor authors should 44 // create a subclass of ClientInterceptorFactorInterface which creates objects 45 // of their interceptors. 46 class ClientInterceptorFactoryInterface { 47 public: ~ClientInterceptorFactoryInterface()48 virtual ~ClientInterceptorFactoryInterface() {} 49 // Returns a pointer to an Interceptor object on successful creation, nullptr 50 // otherwise. If nullptr is returned, this server interceptor factory is 51 // ignored for the purposes of that RPC. 52 virtual Interceptor* CreateClientInterceptor(ClientRpcInfo* info) = 0; 53 }; 54 } // namespace experimental 55 56 namespace internal { 57 extern experimental::ClientInterceptorFactoryInterface* 58 g_global_client_interceptor_factory; 59 } 60 61 /// ClientRpcInfo represents the state of a particular RPC as it 62 /// appears to an interceptor. It is created and owned by the library and 63 /// passed to the CreateClientInterceptor method of the application's 64 /// ClientInterceptorFactoryInterface implementation 65 namespace experimental { 66 class ClientRpcInfo { 67 public: 68 // TODO(yashykt): Stop default-constructing ClientRpcInfo and remove UNKNOWN 69 // from the list of possible Types. 70 /// Type categorizes RPCs by unary or streaming type 71 enum class Type { 72 UNARY, 73 CLIENT_STREAMING, 74 SERVER_STREAMING, 75 BIDI_STREAMING, 76 UNKNOWN // UNKNOWN is not API and will be removed later 77 }; 78 ~ClientRpcInfo()79 ~ClientRpcInfo() {} 80 81 // Delete copy constructor but allow default move constructor 82 ClientRpcInfo(const ClientRpcInfo&) = delete; 83 ClientRpcInfo(ClientRpcInfo&&) = default; 84 85 // Getter methods 86 87 /// Return the fully-specified method name method()88 const char* method() const { return method_; } 89 90 /// Return an identifying suffix for the client stub, or nullptr if one wasn't 91 /// specified. suffix_for_stats()92 const char* suffix_for_stats() const { return suffix_for_stats_; } 93 94 /// Return a pointer to the channel on which the RPC is being sent channel()95 ChannelInterface* channel() { return channel_; } 96 97 /// Return a pointer to the underlying ClientContext structure associated 98 /// with the RPC to support features that apply to it client_context()99 grpc::ClientContext* client_context() { return ctx_; } 100 101 /// Return the type of the RPC (unary or a streaming flavor) type()102 Type type() const { return type_; } 103 104 private: 105 static_assert(Type::UNARY == 106 static_cast<Type>(internal::RpcMethod::NORMAL_RPC), 107 "violated expectation about Type enum"); 108 static_assert(Type::CLIENT_STREAMING == 109 static_cast<Type>(internal::RpcMethod::CLIENT_STREAMING), 110 "violated expectation about Type enum"); 111 static_assert(Type::SERVER_STREAMING == 112 static_cast<Type>(internal::RpcMethod::SERVER_STREAMING), 113 "violated expectation about Type enum"); 114 static_assert(Type::BIDI_STREAMING == 115 static_cast<Type>(internal::RpcMethod::BIDI_STREAMING), 116 "violated expectation about Type enum"); 117 118 // Default constructor should only be used by ClientContext 119 ClientRpcInfo() = default; 120 121 // Constructor will only be called from ClientContext ClientRpcInfo(grpc::ClientContext * ctx,internal::RpcMethod::RpcType type,const char * method,const char * suffix_for_stats,grpc::ChannelInterface * channel)122 ClientRpcInfo(grpc::ClientContext* ctx, internal::RpcMethod::RpcType type, 123 const char* method, const char* suffix_for_stats, 124 grpc::ChannelInterface* channel) 125 : ctx_(ctx), 126 type_(static_cast<Type>(type)), 127 method_(method), 128 suffix_for_stats_(suffix_for_stats), 129 channel_(channel) {} 130 131 // Move assignment should only be used by ClientContext 132 // TODO(yashykt): Delete move assignment 133 ClientRpcInfo& operator=(ClientRpcInfo&&) = default; 134 135 // Runs interceptor at pos \a pos. RunInterceptor(experimental::InterceptorBatchMethods * interceptor_methods,size_t pos)136 void RunInterceptor( 137 experimental::InterceptorBatchMethods* interceptor_methods, size_t pos) { 138 GPR_CODEGEN_ASSERT(pos < interceptors_.size()); 139 interceptors_[pos]->Intercept(interceptor_methods); 140 } 141 RegisterInterceptors(const std::vector<std::unique_ptr<experimental::ClientInterceptorFactoryInterface>> & creators,size_t interceptor_pos)142 void RegisterInterceptors( 143 const std::vector<std::unique_ptr< 144 experimental::ClientInterceptorFactoryInterface>>& creators, 145 size_t interceptor_pos) { 146 if (interceptor_pos > creators.size()) { 147 // No interceptors to register 148 return; 149 } 150 // NOTE: The following is not a range-based for loop because it will only 151 // iterate over a portion of the creators vector. 152 for (auto it = creators.begin() + interceptor_pos; it != creators.end(); 153 ++it) { 154 auto* interceptor = (*it)->CreateClientInterceptor(this); 155 if (interceptor != nullptr) { 156 interceptors_.push_back( 157 std::unique_ptr<experimental::Interceptor>(interceptor)); 158 } 159 } 160 if (internal::g_global_client_interceptor_factory != nullptr) { 161 interceptors_.push_back(std::unique_ptr<experimental::Interceptor>( 162 internal::g_global_client_interceptor_factory 163 ->CreateClientInterceptor(this))); 164 } 165 } 166 167 grpc::ClientContext* ctx_ = nullptr; 168 // TODO(yashykt): make type_ const once move-assignment is deleted 169 Type type_{Type::UNKNOWN}; 170 const char* method_ = nullptr; 171 const char* suffix_for_stats_ = nullptr; 172 grpc::ChannelInterface* channel_ = nullptr; 173 std::vector<std::unique_ptr<experimental::Interceptor>> interceptors_; 174 bool hijacked_ = false; 175 size_t hijacked_interceptor_ = 0; 176 177 friend class internal::InterceptorBatchMethodsImpl; 178 friend class grpc::ClientContext; 179 }; 180 181 // PLEASE DO NOT USE THIS. ALWAYS PREFER PER CHANNEL INTERCEPTORS OVER A GLOBAL 182 // INTERCEPTOR. IF USAGE IS ABSOLUTELY NECESSARY, PLEASE READ THE SAFETY NOTES. 183 // Registers a global client interceptor factory object, which is used for all 184 // RPCs made in this process. The application is responsible for maintaining the 185 // life of the object while gRPC operations are in progress. The global 186 // interceptor factory should only be registered once at the start of the 187 // process before any gRPC operations have begun. 188 void RegisterGlobalClientInterceptorFactory( 189 ClientInterceptorFactoryInterface* factory); 190 191 // For testing purposes only 192 void TestOnlyResetGlobalClientInterceptorFactory(); 193 194 } // namespace experimental 195 } // namespace grpc 196 197 #endif // GRPCPP_IMPL_CODEGEN_CLIENT_INTERCEPTOR_H 198