1/*
2 *
3 * Copyright 2015 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_SUPPORT_CLIENT_INTERCEPTOR_H
20#define GRPCPP_SUPPORT_CLIENT_INTERCEPTOR_H
21
22#include <memory>
23#include <vector>
24
25#include <grpcpp/impl/rpc_method.h>
26#include <grpcpp/support/interceptor.h>
27#include <grpcpp/support/string_ref.h>
28
29namespace grpc {
30
31class Channel;
32class ClientContext;
33
34namespace internal {
35class InterceptorBatchMethodsImpl;
36}
37
38namespace experimental {
39class 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.
46class 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
56namespace internal {
57extern 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
65namespace experimental {
66class 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 an identifying suffix for the client stub, or nullptr if one wasn't
91 /// specified.
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
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
99 grpc::ClientContext* client_context() { return ctx_; }
100
101 /// Return the type of the RPC (unary or a streaming flavor)
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
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.
136 void RunInterceptor(
137 experimental::InterceptorBatchMethods* interceptor_methods, size_t pos) {
138 GPR_CODEGEN_ASSERT(pos < interceptors_.size());
139 interceptors_[pos]->Intercept(methods: interceptor_methods);
140 }
141
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(info: this);
155 if (interceptor != nullptr) {
156 interceptors_.push_back(
157 x: std::unique_ptr<experimental::Interceptor>(interceptor));
158 }
159 }
160 if (internal::g_global_client_interceptor_factory != nullptr) {
161 interceptors_.push_back(x: std::unique_ptr<experimental::Interceptor>(
162 internal::g_global_client_interceptor_factory
163 ->CreateClientInterceptor(info: 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.
188void RegisterGlobalClientInterceptorFactory(
189 ClientInterceptorFactoryInterface* factory);
190
191// For testing purposes only
192void TestOnlyResetGlobalClientInterceptorFactory();
193
194} // namespace experimental
195} // namespace grpc
196
197#endif // GRPCPP_SUPPORT_CLIENT_INTERCEPTOR_H
198

source code of include/grpcpp/support/client_interceptor.h