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 a pointer to the channel on which the RPC is being sent
channel()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
client_context()95   grpc::ClientContext* client_context() { return ctx_; }
96 
97   /// Return the type of the RPC (unary or a streaming flavor)
type()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
ClientRpcInfo(grpc::ClientContext * ctx,internal::RpcMethod::RpcType type,const char * method,grpc::ChannelInterface * channel)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.
RunInterceptor(experimental::InterceptorBatchMethods * interceptor_methods,size_t 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 
RegisterInterceptors(const std::vector<std::unique_ptr<experimental::ClientInterceptorFactoryInterface>> & creators,size_t interceptor_pos)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     // NOTE: The following is not a range-based for loop because it will only
145     //       iterate over a portion of the creators vector.
146     for (auto it = creators.begin() + interceptor_pos; it != creators.end();
147          ++it) {
148       auto* interceptor = (*it)->CreateClientInterceptor(this);
149       if (interceptor != nullptr) {
150         interceptors_.push_back(
151             std::unique_ptr<experimental::Interceptor>(interceptor));
152       }
153     }
154     if (internal::g_global_client_interceptor_factory != nullptr) {
155       interceptors_.push_back(std::unique_ptr<experimental::Interceptor>(
156           internal::g_global_client_interceptor_factory
157               ->CreateClientInterceptor(this)));
158     }
159   }
160 
161   grpc::ClientContext* ctx_ = nullptr;
162   // TODO(yashykt): make type_ const once move-assignment is deleted
163   Type type_{Type::UNKNOWN};
164   const char* method_ = nullptr;
165   grpc::ChannelInterface* channel_ = nullptr;
166   std::vector<std::unique_ptr<experimental::Interceptor>> interceptors_;
167   bool hijacked_ = false;
168   size_t hijacked_interceptor_ = 0;
169 
170   friend class internal::InterceptorBatchMethodsImpl;
171   friend class grpc::ClientContext;
172 };
173 
174 // PLEASE DO NOT USE THIS. ALWAYS PREFER PER CHANNEL INTERCEPTORS OVER A GLOBAL
175 // INTERCEPTOR. IF USAGE IS ABSOLUTELY NECESSARY, PLEASE READ THE SAFETY NOTES.
176 // Registers a global client interceptor factory object, which is used for all
177 // RPCs made in this process. The application is responsible for maintaining the
178 // life of the object while gRPC operations are in progress. The global
179 // interceptor factory should only be registered once at the start of the
180 // process before any gRPC operations have begun.
181 void RegisterGlobalClientInterceptorFactory(
182     ClientInterceptorFactoryInterface* factory);
183 
184 // For testing purposes only
185 void TestOnlyResetGlobalClientInterceptorFactory();
186 
187 }  // namespace experimental
188 }  // namespace grpc
189 
190 #endif  // GRPCPP_IMPL_CODEGEN_CLIENT_INTERCEPTOR_H
191