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/compression.h>
57 : #include <grpc/grpc.h>
58 : #include <grpc/support/log.h>
59 : #include <grpc/support/time.h>
60 : #include <grpc++/security/auth_context.h>
61 : #include <grpc++/support/config.h>
62 : #include <grpc++/support/status.h>
63 : #include <grpc++/support/string_ref.h>
64 : #include <grpc++/support/time.h>
65 :
66 : struct census_context;
67 :
68 : namespace grpc {
69 :
70 : class Channel;
71 : class CompletionQueue;
72 : class Credentials;
73 : class RpcMethod;
74 : template <class R>
75 : class ClientReader;
76 : template <class W>
77 : class ClientWriter;
78 : template <class R, class W>
79 : class ClientReaderWriter;
80 : template <class R>
81 : class ClientAsyncReader;
82 : template <class W>
83 : class ClientAsyncWriter;
84 : template <class R, class W>
85 : class ClientAsyncReaderWriter;
86 : template <class R>
87 : class ClientAsyncResponseReader;
88 : class ServerContext;
89 :
90 : /// Options for \a ClientContext::FromServerContext specifying which traits from
91 : /// the \a ServerContext to propagate (copy) from it into a new \a
92 : /// ClientContext.
93 : ///
94 : /// \see ClientContext::FromServerContext
95 : class PropagationOptions {
96 : public:
97 1297529 : PropagationOptions() : propagate_(GRPC_PROPAGATE_DEFAULTS) {}
98 :
99 : PropagationOptions& enable_deadline_propagation() {
100 : propagate_ |= GRPC_PROPAGATE_DEADLINE;
101 : return *this;
102 : }
103 :
104 : PropagationOptions& disable_deadline_propagation() {
105 : propagate_ &= ~GRPC_PROPAGATE_DEADLINE;
106 : return *this;
107 : }
108 :
109 : PropagationOptions& enable_census_stats_propagation() {
110 : propagate_ |= GRPC_PROPAGATE_CENSUS_STATS_CONTEXT;
111 : return *this;
112 : }
113 :
114 : PropagationOptions& disable_census_stats_propagation() {
115 : propagate_ &= ~GRPC_PROPAGATE_CENSUS_STATS_CONTEXT;
116 : return *this;
117 : }
118 :
119 : PropagationOptions& enable_census_tracing_propagation() {
120 : propagate_ |= GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT;
121 : return *this;
122 : }
123 :
124 : PropagationOptions& disable_census_tracing_propagation() {
125 : propagate_ &= ~GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT;
126 : return *this;
127 : }
128 :
129 : PropagationOptions& enable_cancellation_propagation() {
130 : propagate_ |= GRPC_PROPAGATE_CANCELLATION;
131 : return *this;
132 : }
133 :
134 : PropagationOptions& disable_cancellation_propagation() {
135 : propagate_ &= ~GRPC_PROPAGATE_CANCELLATION;
136 : return *this;
137 : }
138 :
139 1299121 : gpr_uint32 c_bitmask() const { return propagate_; }
140 :
141 : private:
142 : gpr_uint32 propagate_;
143 : };
144 :
145 : namespace testing {
146 : class InteropClientContextInspector;
147 : } // namespace testing
148 :
149 : class ClientContext {
150 : public:
151 : ClientContext();
152 : ~ClientContext();
153 :
154 : /// Create a new \a ClientContext as a child of an incoming server call,
155 : /// according to \a options (\see PropagationOptions).
156 : ///
157 : /// \param server_context The source server context to use as the basis for
158 : /// constructing the client context.
159 : /// \param options The options controlling what to copy from the \a
160 : /// server_context.
161 : ///
162 : /// \return A newly constructed \a ClientContext instance based on \a
163 : /// server_context, with traits propagated (copied) according to \a options.
164 : static std::unique_ptr<ClientContext> FromServerContext(
165 : const ServerContext& server_context,
166 : PropagationOptions options = PropagationOptions());
167 :
168 : /// Add the (\a meta_key, \a meta_value) pair to the metadata associated with
169 : /// a client call. These are made available at the server side by the \a
170 : /// grpc::ServerContext::client_metadata() method.
171 : ///
172 : /// \warning This method should only be called before invoking the rpc.
173 : ///
174 : /// \param meta_key The metadata key. If \a meta_value is binary data, it must
175 : /// end in "-bin".
176 : /// \param meta_value The metadata value. If its value is binary, it must be
177 : /// base64-encoding (see https://tools.ietf.org/html/rfc4648#section-4) and \a
178 : /// meta_key must end in "-bin".
179 : void AddMetadata(const grpc::string& meta_key,
180 : const grpc::string& meta_value);
181 :
182 : /// Return a collection of initial metadata key-value pairs. Note that keys
183 : /// may happen more than once (ie, a \a std::multimap is returned).
184 : ///
185 : /// \warning This method should only be called after initial metadata has been
186 : /// received. For streaming calls, see \a
187 : /// ClientReaderInterface::WaitForInitialMetadata().
188 : ///
189 : /// \return A multimap of initial metadata key-value pairs from the server.
190 : const std::multimap<grpc::string_ref, grpc::string_ref>&
191 6 : GetServerInitialMetadata() {
192 6 : GPR_ASSERT(initial_metadata_received_);
193 6 : return recv_initial_metadata_;
194 : }
195 :
196 : /// Return a collection of trailing metadata key-value pairs. Note that keys
197 : /// may happen more than once (ie, a \a std::multimap is returned).
198 : ///
199 : /// \warning This method is only callable once the stream has finished.
200 : ///
201 : /// \return A multimap of metadata trailing key-value pairs from the server.
202 : const std::multimap<grpc::string_ref, grpc::string_ref>&
203 14 : GetServerTrailingMetadata() {
204 : // TODO(yangg) check finished
205 14 : return trailing_metadata_;
206 : }
207 :
208 : /// Set the deadline for the client call.
209 : ///
210 : /// \warning This method should only be called before invoking the rpc.
211 : ///
212 : /// \param deadline the deadline for the client call. Units are determined by
213 : /// the type used.
214 : template <typename T>
215 24 : void set_deadline(const T& deadline) {
216 24 : TimePoint<T> deadline_tp(deadline);
217 24 : deadline_ = deadline_tp.raw_time();
218 24 : }
219 :
220 : #ifndef GRPC_CXX0X_NO_CHRONO
221 : /// Return the deadline for the client call.
222 : std::chrono::system_clock::time_point deadline() {
223 : return Timespec2Timepoint(deadline_);
224 : }
225 : #endif // !GRPC_CXX0X_NO_CHRONO
226 :
227 : /// Return a \a gpr_timespec representation of the client call's deadline.
228 1299062 : gpr_timespec raw_deadline() { return deadline_; }
229 :
230 : /// Set the per call authority header (see
231 : /// https://tools.ietf.org/html/rfc7540#section-8.1.2.3).
232 1 : void set_authority(const grpc::string& authority) { authority_ = authority; }
233 :
234 : /// Return the authentication context for this client call.
235 : ///
236 : /// \see grpc::AuthContext.
237 : std::shared_ptr<const AuthContext> auth_context() const;
238 :
239 : /// Set credentials for the client call.
240 : ///
241 : /// A credentials object encapsulates all the state needed by a client to
242 : /// authenticate with a server and make various assertions, e.g., about the
243 : /// client’s identity, role, or whether it is authorized to make a particular
244 : /// call.
245 : ///
246 : /// \see https://github.com/grpc/grpc/blob/master/doc/grpc-auth-support.md
247 10 : void set_credentials(const std::shared_ptr<Credentials>& creds) {
248 10 : creds_ = creds;
249 10 : }
250 :
251 : /// Return the compression algorithm to be used by the client call.
252 : grpc_compression_algorithm compression_algorithm() const {
253 : return compression_algorithm_;
254 : }
255 :
256 : /// Set \a algorithm to be the compression algorithm used for the client call.
257 : ///
258 : /// \param algorith The compression algorithm used for the client call.
259 : void set_compression_algorithm(grpc_compression_algorithm algorithm);
260 :
261 : /// Return the peer uri in a string.
262 : ///
263 : /// \warning This value is never authenticated or subject to any security
264 : /// related code. It must not be used for any authentication related
265 : /// functionality. Instead, use auth_context.
266 : ///
267 : /// \return The call's peer URI.
268 : grpc::string peer() const;
269 :
270 : /// Get and set census context
271 : void set_census_context(struct census_context* ccp) { census_context_ = ccp; }
272 1299192 : struct census_context* census_context() const {
273 1299192 : return census_context_;
274 : }
275 :
276 : /// Send a best-effort out-of-band cancel. The call could be in any stage.
277 : /// e.g. if it is already finished, it may still return success.
278 : ///
279 : /// There is no guarantee the call will be cancelled.
280 : void TryCancel();
281 :
282 : private:
283 : // Disallow copy and assign.
284 : ClientContext(const ClientContext&);
285 : ClientContext& operator=(const ClientContext&);
286 :
287 : friend class ::grpc::testing::InteropClientContextInspector;
288 : friend class CallOpClientRecvStatus;
289 : friend class CallOpRecvInitialMetadata;
290 : friend class Channel;
291 : template <class R>
292 : friend class ::grpc::ClientReader;
293 : template <class W>
294 : friend class ::grpc::ClientWriter;
295 : template <class R, class W>
296 : friend class ::grpc::ClientReaderWriter;
297 : template <class R>
298 : friend class ::grpc::ClientAsyncReader;
299 : template <class W>
300 : friend class ::grpc::ClientAsyncWriter;
301 : template <class R, class W>
302 : friend class ::grpc::ClientAsyncReaderWriter;
303 : template <class R>
304 : friend class ::grpc::ClientAsyncResponseReader;
305 : template <class InputMessage, class OutputMessage>
306 : friend Status BlockingUnaryCall(Channel* channel, const RpcMethod& method,
307 : ClientContext* context,
308 : const InputMessage& request,
309 : OutputMessage* result);
310 :
311 : grpc_call* call() { return call_; }
312 : void set_call(grpc_call* call, const std::shared_ptr<Channel>& channel);
313 :
314 1298732 : grpc::string authority() { return authority_; }
315 :
316 : bool initial_metadata_received_;
317 : std::shared_ptr<Channel> channel_;
318 : grpc_call* call_;
319 : gpr_timespec deadline_;
320 : grpc::string authority_;
321 : std::shared_ptr<Credentials> creds_;
322 : mutable std::shared_ptr<const AuthContext> auth_context_;
323 : struct census_context* census_context_;
324 : std::multimap<grpc::string, grpc::string> send_initial_metadata_;
325 : std::multimap<grpc::string_ref, grpc::string_ref> recv_initial_metadata_;
326 : std::multimap<grpc::string_ref, grpc::string_ref> trailing_metadata_;
327 :
328 : grpc_call* propagate_from_call_;
329 : PropagationOptions propagation_options_;
330 :
331 : grpc_compression_algorithm compression_algorithm_;
332 : };
333 :
334 : } // namespace grpc
335 :
336 : #endif // GRPCXX_CLIENT_CONTEXT_H
|
