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

source code of include/grpcpp/impl/codegen/client_interceptor.h