include/grpcpp/impl/codegen/client_interceptor.h

   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 ClientContext;
  32 class Channel;
  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:
  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
  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
  88   const char* method() const { return method_; }
  89
  90   /// Return a pointer to the channel on which the RPC is being sent
  91   ChannelInterface* channel() { return channel_; }
  92
  93   /// Return a pointer to the underlying ClientContext structure associated
  94   /// with the RPC to support features that apply to it
  95   grpc::ClientContext* client_context() { return ctx_; }
  96
  97   /// Return the type of the RPC (unary or a streaming flavor)
  98   Type type() const { return type_; }
  99
 100  private:
 101   static_assert(Type::UNARY ==
 102                     static_cast<Type>(internal::RpcMethod::NORMAL_RPC),
 103                 "violated expectation about Type enum");
 104   static_assert(Type::CLIENT_STREAMING ==
 105                     static_cast<Type>(internal::RpcMethod::CLIENT_STREAMING),
 106                 "violated expectation about Type enum");
 107   static_assert(Type::SERVER_STREAMING ==
 108                     static_cast<Type>(internal::RpcMethod::SERVER_STREAMING),
 109                 "violated expectation about Type enum");
 110   static_assert(Type::BIDI_STREAMING ==
 111                     static_cast<Type>(internal::RpcMethod::BIDI_STREAMING),
 112                 "violated expectation about Type enum");
 113
 114   // Default constructor should only be used by ClientContext
 115   ClientRpcInfo() = default;
 116
 117   // Constructor will only be called from ClientContext
 118   ClientRpcInfo(grpc::ClientContext* ctx, internal::RpcMethod::RpcType type,
 119                 const char* method, grpc::ChannelInterface* channel)
 120       : ctx_(ctx),
 121         type_(static_cast<Type>(type)),
 122         method_(method),
 123         channel_(channel) {}
 124
 125   // Move assignment should only be used by ClientContext
 126   // TODO(yashykt): Delete move assignment
 127   ClientRpcInfo& operator=(ClientRpcInfo&&) = default;
 128
 129   // Runs interceptor at pos \a pos.
 130   void RunInterceptor(
 131       experimental::InterceptorBatchMethods* interceptor_methods, size_t pos) {
 132     GPR_CODEGEN_ASSERT(pos < interceptors_.size());
 133     interceptors_[pos]->Intercept(interceptor_methods);
 134   }
 135
 136   void RegisterInterceptors(
 137       const std::vector<std::unique_ptr<
 138           experimental::ClientInterceptorFactoryInterface>>& creators,
 139       size_t interceptor_pos) {
 140     if (interceptor_pos > creators.size()) {
 141       // No interceptors to register
 142       return;
 143     }
 144     for (auto it = creators.begin() + interceptor_pos; it != creators.end();
 145          ++it) {
 146       auto* interceptor = (*it)->CreateClientInterceptor(this);
 147       if (interceptor != nullptr) {
 148         interceptors_.push_back(
 149             std::unique_ptr<experimental::Interceptor>(interceptor));
 150       }
 151     }
 152     if (internal::g_global_client_interceptor_factory != nullptr) {
 153       interceptors_.push_back(std::unique_ptr<experimental::Interceptor>(
 154           internal::g_global_client_interceptor_factory
 155               ->CreateClientInterceptor(this)));
 156     }
 157   }
 158
 159   grpc::ClientContext* ctx_ = nullptr;
 160   // TODO(yashykt): make type_ const once move-assignment is deleted
 161   Type type_{Type::UNKNOWN};
 162   const char* method_ = nullptr;
 163   grpc::ChannelInterface* channel_ = nullptr;
 164   std::vector<std::unique_ptr<experimental::Interceptor>> interceptors_;
 165   bool hijacked_ = false;
 166   size_t hijacked_interceptor_ = 0;
 167
 168   friend class internal::InterceptorBatchMethodsImpl;
 169   friend class grpc::ClientContext;
 170 };
 171
 172 // PLEASE DO NOT USE THIS. ALWAYS PREFER PER CHANNEL INTERCEPTORS OVER A GLOBAL
 173 // INTERCEPTOR. IF USAGE IS ABSOLUTELY NECESSARY, PLEASE READ THE SAFETY NOTES.
 174 // Registers a global client interceptor factory object, which is used for all
 175 // RPCs made in this process. The application is responsible for maintaining the
 176 // life of the object while gRPC operations are in progress. The global
 177 // interceptor factory should only be registered once at the start of the
 178 // process before any gRPC operations have begun.
 179 void RegisterGlobalClientInterceptorFactory(
 180     ClientInterceptorFactoryInterface* factory);
 181
 182 // For testing purposes only
 183 void TestOnlyResetGlobalClientInterceptorFactory();
 184
 185 }  // namespace experimental
 186 }  // namespace grpc
 187
 188 #endif  // GRPCPP_IMPL_CODEGEN_CLIENT_INTERCEPTOR_H