Line data Source code
1 : /*
2 : *
3 : * Copyright 2015, Google Inc.
4 : * All rights reserved.
5 : *
6 : * Redistribution and use in source and binary forms, with or without
7 : * modification, are permitted provided that the following conditions are
8 : * met:
9 : *
10 : * * Redistributions of source code must retain the above copyright
11 : * notice, this list of conditions and the following disclaimer.
12 : * * Redistributions in binary form must reproduce the above
13 : * copyright notice, this list of conditions and the following disclaimer
14 : * in the documentation and/or other materials provided with the
15 : * distribution.
16 : * * Neither the name of Google Inc. nor the names of its
17 : * contributors may be used to endorse or promote products derived from
18 : * this software without specific prior written permission.
19 : *
20 : * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 : * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 : * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 : * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 : * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 : * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 : * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 : * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 : * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 : * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 : * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 : *
32 : */
33 :
34 : /// A ClientContext allows the person implementing a service client to:
35 : ///
36 : /// - Add custom metadata key-value pairs that will propagated to the server
37 : /// side.
38 : /// - Control call settings such as compression and authentication.
39 : /// - Initial and trailing metadata coming from the server.
40 : /// - Get performance metrics (ie, census).
41 : ///
42 : /// Context settings are only relevant to the call they are invoked with, that
43 : /// is to say, they aren't sticky. Some of these settings, such as the
44 : /// compression options, can be made persistant at channel construction time
45 : /// (see \a grpc::CreateCustomChannel).
46 : ///
47 : /// \warning ClientContext instances should \em not be reused across rpcs.
48 :
49 : #ifndef GRPCXX_CLIENT_CONTEXT_H
50 : #define GRPCXX_CLIENT_CONTEXT_H
51 :
52 : #include <map>
53 : #include <memory>
54 : #include <string>
55 :
56 : #include <grpc++/impl/sync.h>
57 : #include <grpc++/security/auth_context.h>
58 : #include <grpc++/support/config.h>
59 : #include <grpc++/support/status.h>
60 : #include <grpc++/support/string_ref.h>
61 : #include <grpc++/support/time.h>
62 : #include <grpc/compression.h>
63 : #include <grpc/grpc.h>
64 : #include <grpc/support/log.h>
65 : #include <grpc/support/time.h>
66 :
67 : struct census_context;
68 :
69 : namespace grpc {
70 :
71 : class Channel;
72 : class CompletionQueue;
73 : class CallCredentials;
74 : class RpcMethod;
75 : template <class R>
76 : class ClientReader;
77 : template <class W>
78 : class ClientWriter;
79 : template <class R, class W>
80 : class ClientReaderWriter;
81 : template <class R>
82 : class ClientAsyncReader;
83 : template <class W>
84 : class ClientAsyncWriter;
85 : template <class R, class W>
86 : class ClientAsyncReaderWriter;
87 : template <class R>
88 : class ClientAsyncResponseReader;
89 : class ServerContext;
90 :
91 : /// Options for \a ClientContext::FromServerContext specifying which traits from
92 : /// the \a ServerContext to propagate (copy) from it into a new \a
93 : /// ClientContext.
94 : ///
95 : /// \see ClientContext::FromServerContext
96 : class PropagationOptions {
97 : public:
98 1646666 : PropagationOptions() : propagate_(GRPC_PROPAGATE_DEFAULTS) {}
99 :
100 : PropagationOptions& enable_deadline_propagation() {
101 : propagate_ |= GRPC_PROPAGATE_DEADLINE;
102 : return *this;
103 : }
104 :
105 : PropagationOptions& disable_deadline_propagation() {
106 : propagate_ &= ~GRPC_PROPAGATE_DEADLINE;
107 : return *this;
108 : }
109 :
110 : PropagationOptions& enable_census_stats_propagation() {
111 : propagate_ |= GRPC_PROPAGATE_CENSUS_STATS_CONTEXT;
112 : return *this;
113 : }
114 :
115 : PropagationOptions& disable_census_stats_propagation() {
116 : propagate_ &= ~GRPC_PROPAGATE_CENSUS_STATS_CONTEXT;
117 : return *this;
118 : }
119 :
120 : PropagationOptions& enable_census_tracing_propagation() {
121 : propagate_ |= GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT;
122 : return *this;
123 : }
124 :
125 : PropagationOptions& disable_census_tracing_propagation() {
126 : propagate_ &= ~GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT;
127 : return *this;
128 : }
129 :
130 : PropagationOptions& enable_cancellation_propagation() {
131 : propagate_ |= GRPC_PROPAGATE_CANCELLATION;
132 : return *this;
133 : }
134 :
135 : PropagationOptions& disable_cancellation_propagation() {
136 : propagate_ &= ~GRPC_PROPAGATE_CANCELLATION;
137 : return *this;
138 : }
139 :
140 1646633 : gpr_uint32 c_bitmask() const { return propagate_; }
141 :
142 : private:
143 : gpr_uint32 propagate_;
144 : };
145 :
146 : namespace testing {
147 : class InteropClientContextInspector;
148 : } // namespace testing
149 :
150 : class ClientContext {
151 : public:
152 : ClientContext();
153 : ~ClientContext();
154 :
155 : /// Create a new \a ClientContext as a child of an incoming server call,
156 : /// according to \a options (\see PropagationOptions).
157 : ///
158 : /// \param server_context The source server context to use as the basis for
159 : /// constructing the client context.
160 : /// \param options The options controlling what to copy from the \a
161 : /// server_context.
162 : ///
163 : /// \return A newly constructed \a ClientContext instance based on \a
164 : /// server_context, with traits propagated (copied) according to \a options.
165 : static std::unique_ptr<ClientContext> FromServerContext(
166 : const ServerContext& server_context,
167 : PropagationOptions options = PropagationOptions());
168 :
169 : /// Add the (\a meta_key, \a meta_value) pair to the metadata associated with
170 : /// a client call. These are made available at the server side by the \a
171 : /// grpc::ServerContext::client_metadata() method.
172 : ///
173 : /// \warning This method should only be called before invoking the rpc.
174 : ///
175 : /// \param meta_key The metadata key. If \a meta_value is binary data, it must
176 : /// end in "-bin".
177 : /// \param meta_value The metadata value. If its value is binary, it must be
178 : /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a
179 : /// meta_key must end in "-bin".
180 : void AddMetadata(const grpc::string& meta_key,
181 : const grpc::string& meta_value);
182 :
183 : /// Return a collection of initial metadata key-value pairs. Note that keys
184 : /// may happen more than once (ie, a \a std::multimap is returned).
185 : ///
186 : /// \warning This method should only be called after initial metadata has been
187 : /// received. For streaming calls, see \a
188 : /// ClientReaderInterface::WaitForInitialMetadata().
189 : ///
190 : /// \return A multimap of initial metadata key-value pairs from the server.
191 : const std::multimap<grpc::string_ref, grpc::string_ref>&
192 6 : GetServerInitialMetadata() {
193 6 : GPR_ASSERT(initial_metadata_received_);
194 6 : return recv_initial_metadata_;
195 : }
196 :
197 : /// Return a collection of trailing metadata key-value pairs. Note that keys
198 : /// may happen more than once (ie, a \a std::multimap is returned).
199 : ///
200 : /// \warning This method is only callable once the stream has finished.
201 : ///
202 : /// \return A multimap of metadata trailing key-value pairs from the server.
203 : const std::multimap<grpc::string_ref, grpc::string_ref>&
204 14 : GetServerTrailingMetadata() {
205 : // TODO(yangg) check finished
206 14 : return trailing_metadata_;
207 : }
208 :
209 : /// Set the deadline for the client call.
210 : ///
211 : /// \warning This method should only be called before invoking the rpc.
212 : ///
213 : /// \param deadline the deadline for the client call. Units are determined by
214 : /// the type used.
215 : template <typename T>
216 24 : void set_deadline(const T& deadline) {
217 24 : TimePoint<T> deadline_tp(deadline);
218 24 : deadline_ = deadline_tp.raw_time();
219 24 : }
220 :
221 : #ifndef GRPC_CXX0X_NO_CHRONO
222 : /// Return the deadline for the client call.
223 : std::chrono::system_clock::time_point deadline() {
224 : return Timespec2Timepoint(deadline_);
225 : }
226 : #endif // !GRPC_CXX0X_NO_CHRONO
227 :
228 : /// Return a \a gpr_timespec representation of the client call's deadline.
229 1646638 : gpr_timespec raw_deadline() { return deadline_; }
230 :
231 : /// Set the per call authority header (see
232 : /// https://tools.ietf.org/html/rfc7540#section-8.1.2.3).
233 1 : void set_authority(const grpc::string& authority) { authority_ = authority; }
234 :
235 : /// Return the authentication context for this client call.
236 : ///
237 : /// \see grpc::AuthContext.
238 : std::shared_ptr<const AuthContext> auth_context() const;
239 :
240 : /// Set credentials for the client call.
241 : ///
242 : /// A credentials object encapsulates all the state needed by a client to
243 : /// authenticate with a server and make various assertions, e.g., about the
244 : /// client’s identity, role, or whether it is authorized to make a particular
245 : /// call.
246 : ///
247 : /// \see https://github.com/grpc/grpc/blob/master/doc/grpc-auth-support.md
248 9 : void set_credentials(const std::shared_ptr<CallCredentials>& creds) {
249 9 : creds_ = creds;
250 9 : }
251 :
252 : /// Return the compression algorithm to be used by the client call.
253 : grpc_compression_algorithm compression_algorithm() const {
254 : return compression_algorithm_;
255 : }
256 :
257 : /// Set \a algorithm to be the compression algorithm used for the client call.
258 : ///
259 : /// \param algorith The compression algorithm used for the client call.
260 : void set_compression_algorithm(grpc_compression_algorithm algorithm);
261 :
262 : /// Return the peer uri in a string.
263 : ///
264 : /// \warning This value is never authenticated or subject to any security
265 : /// related code. It must not be used for any authentication related
266 : /// functionality. Instead, use auth_context.
267 : ///
268 : /// \return The call's peer URI.
269 : grpc::string peer() const;
270 :
271 : /// Get and set census context
272 : void set_census_context(struct census_context* ccp) { census_context_ = ccp; }
273 1646792 : struct census_context* census_context() const {
274 1646792 : return census_context_;
275 : }
276 :
277 : /// Send a best-effort out-of-band cancel. The call could be in any stage.
278 : /// e.g. if it is already finished, it may still return success.
279 : ///
280 : /// There is no guarantee the call will be cancelled.
281 : void TryCancel();
282 :
283 : private:
284 : // Disallow copy and assign.
285 : ClientContext(const ClientContext&);
286 : ClientContext& operator=(const ClientContext&);
287 :
288 : friend class ::grpc::testing::InteropClientContextInspector;
289 : friend class CallOpClientRecvStatus;
290 : friend class CallOpRecvInitialMetadata;
291 : friend class Channel;
292 : template <class R>
293 : friend class ::grpc::ClientReader;
294 : template <class W>
295 : friend class ::grpc::ClientWriter;
296 : template <class R, class W>
297 : friend class ::grpc::ClientReaderWriter;
298 : template <class R>
299 : friend class ::grpc::ClientAsyncReader;
300 : template <class W>
301 : friend class ::grpc::ClientAsyncWriter;
302 : template <class R, class W>
303 : friend class ::grpc::ClientAsyncReaderWriter;
304 : template <class R>
305 : friend class ::grpc::ClientAsyncResponseReader;
306 : template <class InputMessage, class OutputMessage>
307 : friend Status BlockingUnaryCall(Channel* channel, const RpcMethod& method,
308 : ClientContext* context,
309 : const InputMessage& request,
310 : OutputMessage* result);
311 :
312 : grpc_call* call() { return call_; }
313 : void set_call(grpc_call* call, const std::shared_ptr<Channel>& channel);
314 :
315 1646154 : grpc::string authority() { return authority_; }
316 :
317 : bool initial_metadata_received_;
318 : std::shared_ptr<Channel> channel_;
319 : grpc::mutex mu_;
320 : grpc_call* call_;
321 : bool call_canceled_;
322 : gpr_timespec deadline_;
323 : grpc::string authority_;
324 : std::shared_ptr<CallCredentials> creds_;
325 : mutable std::shared_ptr<const AuthContext> auth_context_;
326 : struct census_context* census_context_;
327 : std::multimap<grpc::string, grpc::string> send_initial_metadata_;
328 : std::multimap<grpc::string_ref, grpc::string_ref> recv_initial_metadata_;
329 : std::multimap<grpc::string_ref, grpc::string_ref> trailing_metadata_;
330 :
331 : grpc_call* propagate_from_call_;
332 : PropagationOptions propagation_options_;
333 :
334 : grpc_compression_algorithm compression_algorithm_;
335 : };
336 :
337 : } // namespace grpc
338 :
339 : #endif // GRPCXX_CLIENT_CONTEXT_H
|
