1 | /* |
2 | * |
3 | * Copyright 2015-2016 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_SERVER_BUILDER_IMPL_H |
20 | #define GRPCPP_SERVER_BUILDER_IMPL_H |
21 | |
22 | #include <climits> |
23 | #include <map> |
24 | #include <memory> |
25 | #include <vector> |
26 | |
27 | #include <grpc/impl/codegen/port_platform.h> |
28 | |
29 | #include <grpc/compression.h> |
30 | #include <grpc/support/cpu.h> |
31 | #include <grpc/support/workaround_list.h> |
32 | #include <grpcpp/impl/channel_argument_option.h> |
33 | #include <grpcpp/impl/codegen/server_interceptor.h> |
34 | #include <grpcpp/impl/server_builder_option.h> |
35 | #include <grpcpp/impl/server_builder_plugin.h> |
36 | #include <grpcpp/server.h> |
37 | #include <grpcpp/support/config.h> |
38 | |
39 | struct grpc_resource_quota; |
40 | |
41 | namespace grpc_impl { |
42 | |
43 | class CompletionQueue; |
44 | class ResourceQuota; |
45 | class Server; |
46 | class ServerCompletionQueue; |
47 | class ServerCredentials; |
48 | } // namespace grpc_impl |
49 | |
50 | namespace grpc { |
51 | |
52 | class AsyncGenericService; |
53 | class Service; |
54 | namespace testing { |
55 | class ServerBuilderPluginTest; |
56 | } // namespace testing |
57 | |
58 | namespace internal { |
59 | class ExternalConnectionAcceptorImpl; |
60 | } // namespace internal |
61 | |
62 | #ifndef GRPC_CALLBACK_API_NONEXPERIMENTAL |
63 | namespace experimental { |
64 | #endif |
65 | class CallbackGenericService; |
66 | #ifndef GRPC_CALLBACK_API_NONEXPERIMENTAL |
67 | } // namespace experimental |
68 | #endif |
69 | |
70 | namespace experimental { |
71 | // EXPERIMENTAL API: |
72 | // Interface for a grpc server to build transports with connections created out |
73 | // of band. |
74 | // See ServerBuilder's AddExternalConnectionAcceptor API. |
75 | class ExternalConnectionAcceptor { |
76 | public: |
77 | struct NewConnectionParameters { |
78 | int listener_fd = -1; |
79 | int fd = -1; |
80 | ByteBuffer read_buffer; // data intended for the grpc server |
81 | }; |
82 | virtual ~ExternalConnectionAcceptor() {} |
83 | // If called before grpc::Server is started or after it is shut down, the new |
84 | // connection will be closed. |
85 | virtual void HandleNewConnection(NewConnectionParameters* p) = 0; |
86 | }; |
87 | |
88 | } // namespace experimental |
89 | } // namespace grpc |
90 | |
91 | namespace grpc_impl { |
92 | |
93 | /// A builder class for the creation and startup of \a grpc::Server instances. |
94 | class ServerBuilder { |
95 | public: |
96 | ServerBuilder(); |
97 | virtual ~ServerBuilder(); |
98 | |
99 | ////////////////////////////////////////////////////////////////////////////// |
100 | // Primary API's |
101 | |
102 | /// Return a running server which is ready for processing calls. |
103 | /// Before calling, one typically needs to ensure that: |
104 | /// 1. a service is registered - so that the server knows what to serve |
105 | /// (via RegisterService, or RegisterAsyncGenericService) |
106 | /// 2. a listening port has been added - so the server knows where to receive |
107 | /// traffic (via AddListeningPort) |
108 | /// 3. [for async api only] completion queues have been added via |
109 | /// AddCompletionQueue |
110 | virtual std::unique_ptr<grpc::Server> BuildAndStart(); |
111 | |
112 | /// Register a service. This call does not take ownership of the service. |
113 | /// The service must exist for the lifetime of the \a Server instance returned |
114 | /// by \a BuildAndStart(). |
115 | /// Matches requests with any :authority |
116 | ServerBuilder& RegisterService(grpc::Service* service); |
117 | |
118 | /// Enlists an endpoint \a addr (port with an optional IP address) to |
119 | /// bind the \a grpc::Server object to be created to. |
120 | /// |
121 | /// It can be invoked multiple times. |
122 | /// |
123 | /// \param addr_uri The address to try to bind to the server in URI form. If |
124 | /// the scheme name is omitted, "dns:///" is assumed. To bind to any address, |
125 | /// please use IPv6 any, i.e., [::]:<port>, which also accepts IPv4 |
126 | /// connections. Valid values include dns:///localhost:1234, / |
127 | /// 192.168.1.1:31416, dns:///[::1]:27182, etc.). |
128 | /// \param creds The credentials associated with the server. |
129 | /// \param selected_port[out] If not `nullptr`, gets populated with the port |
130 | /// number bound to the \a grpc::Server for the corresponding endpoint after |
131 | /// it is successfully bound by BuildAndStart(), 0 otherwise. AddListeningPort |
132 | /// does not modify this pointer. |
133 | ServerBuilder& AddListeningPort( |
134 | const grpc::string& addr_uri, |
135 | std::shared_ptr<grpc_impl::ServerCredentials> creds, |
136 | int* selected_port = nullptr); |
137 | |
138 | /// Add a completion queue for handling asynchronous services. |
139 | /// |
140 | /// Best performance is typically obtained by using one thread per polling |
141 | /// completion queue. |
142 | /// |
143 | /// Caller is required to shutdown the server prior to shutting down the |
144 | /// returned completion queue. Caller is also required to drain the |
145 | /// completion queue after shutting it down. A typical usage scenario: |
146 | /// |
147 | /// // While building the server: |
148 | /// ServerBuilder builder; |
149 | /// ... |
150 | /// cq_ = builder.AddCompletionQueue(); |
151 | /// server_ = builder.BuildAndStart(); |
152 | /// |
153 | /// // While shutting down the server; |
154 | /// server_->Shutdown(); |
155 | /// cq_->Shutdown(); // Always *after* the associated server's Shutdown()! |
156 | /// // Drain the cq_ that was created |
157 | /// void* ignored_tag; |
158 | /// bool ignored_ok; |
159 | /// while (cq_->Next(&ignored_tag, &ignored_ok)) { } |
160 | /// |
161 | /// \param is_frequently_polled This is an optional parameter to inform gRPC |
162 | /// library about whether this completion queue would be frequently polled |
163 | /// (i.e. by calling \a Next() or \a AsyncNext()). The default value is |
164 | /// 'true' and is the recommended setting. Setting this to 'false' (i.e. |
165 | /// not polling the completion queue frequently) will have a significantly |
166 | /// negative performance impact and hence should not be used in production |
167 | /// use cases. |
168 | std::unique_ptr<grpc_impl::ServerCompletionQueue> AddCompletionQueue( |
169 | bool is_frequently_polled = true); |
170 | |
171 | ////////////////////////////////////////////////////////////////////////////// |
172 | // Less commonly used RegisterService variants |
173 | |
174 | /// Register a service. This call does not take ownership of the service. |
175 | /// The service must exist for the lifetime of the \a Server instance |
176 | /// returned by \a BuildAndStart(). Only matches requests with :authority \a |
177 | /// host |
178 | ServerBuilder& RegisterService(const grpc::string& host, |
179 | grpc::Service* service); |
180 | |
181 | /// Register a generic service. |
182 | /// Matches requests with any :authority |
183 | /// This is mostly useful for writing generic gRPC Proxies where the exact |
184 | /// serialization format is unknown |
185 | ServerBuilder& RegisterAsyncGenericService( |
186 | grpc::AsyncGenericService* service); |
187 | |
188 | ////////////////////////////////////////////////////////////////////////////// |
189 | // Fine control knobs |
190 | |
191 | /// Set max receive message size in bytes. |
192 | /// The default is GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH. |
193 | ServerBuilder& SetMaxReceiveMessageSize(int max_receive_message_size) { |
194 | max_receive_message_size_ = max_receive_message_size; |
195 | return *this; |
196 | } |
197 | |
198 | /// Set max send message size in bytes. |
199 | /// The default is GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH. |
200 | ServerBuilder& SetMaxSendMessageSize(int max_send_message_size) { |
201 | max_send_message_size_ = max_send_message_size; |
202 | return *this; |
203 | } |
204 | |
205 | /// \deprecated For backward compatibility. |
206 | ServerBuilder& SetMaxMessageSize(int max_message_size) { |
207 | return SetMaxReceiveMessageSize(max_message_size); |
208 | } |
209 | |
210 | /// Set the support status for compression algorithms. All algorithms are |
211 | /// enabled by default. |
212 | /// |
213 | /// Incoming calls compressed with an unsupported algorithm will fail with |
214 | /// \a GRPC_STATUS_UNIMPLEMENTED. |
215 | ServerBuilder& SetCompressionAlgorithmSupportStatus( |
216 | grpc_compression_algorithm algorithm, bool enabled); |
217 | |
218 | /// The default compression level to use for all channel calls in the |
219 | /// absence of a call-specific level. |
220 | ServerBuilder& SetDefaultCompressionLevel(grpc_compression_level level); |
221 | |
222 | /// The default compression algorithm to use for all channel calls in the |
223 | /// absence of a call-specific level. Note that it overrides any compression |
224 | /// level set by \a SetDefaultCompressionLevel. |
225 | ServerBuilder& SetDefaultCompressionAlgorithm( |
226 | grpc_compression_algorithm algorithm); |
227 | |
228 | /// Set the attached buffer pool for this server |
229 | ServerBuilder& SetResourceQuota( |
230 | const grpc_impl::ResourceQuota& resource_quota); |
231 | |
232 | ServerBuilder& SetOption(std::unique_ptr<grpc::ServerBuilderOption> option); |
233 | |
234 | /// Options for synchronous servers. |
235 | enum SyncServerOption { |
236 | NUM_CQS, ///< Number of completion queues. |
237 | MIN_POLLERS, ///< Minimum number of polling threads. |
238 | MAX_POLLERS, ///< Maximum number of polling threads. |
239 | CQ_TIMEOUT_MSEC ///< Completion queue timeout in milliseconds. |
240 | }; |
241 | |
242 | /// Only useful if this is a Synchronous server. |
243 | ServerBuilder& SetSyncServerOption(SyncServerOption option, int value); |
244 | |
245 | /// Add a channel argument (an escape hatch to tuning core library parameters |
246 | /// directly) |
247 | template <class T> |
248 | ServerBuilder& AddChannelArgument(const grpc::string& arg, const T& value) { |
249 | return SetOption(grpc::MakeChannelArgumentOption(arg, value)); |
250 | } |
251 | |
252 | /// For internal use only: Register a ServerBuilderPlugin factory function. |
253 | static void InternalAddPluginFactory( |
254 | std::unique_ptr<grpc::ServerBuilderPlugin> (*CreatePlugin)()); |
255 | |
256 | /// Enable a server workaround. Do not use unless you know what the workaround |
257 | /// does. For explanation and detailed descriptions of workarounds, see |
258 | /// doc/workarounds.md. |
259 | ServerBuilder& EnableWorkaround(grpc_workaround_list id); |
260 | |
261 | /// NOTE: class experimental_type is not part of the public API of this class. |
262 | /// TODO(yashykt): Integrate into public API when this is no longer |
263 | /// experimental. |
264 | class experimental_type { |
265 | public: |
266 | explicit experimental_type(grpc_impl::ServerBuilder* builder) |
267 | : builder_(builder) {} |
268 | |
269 | void SetInterceptorCreators( |
270 | std::vector<std::unique_ptr< |
271 | grpc::experimental::ServerInterceptorFactoryInterface>> |
272 | interceptor_creators) { |
273 | builder_->interceptor_creators_ = std::move(interceptor_creators); |
274 | } |
275 | |
276 | #ifndef GRPC_CALLBACK_API_NONEXPERIMENTAL |
277 | /// Register a generic service that uses the callback API. |
278 | /// Matches requests with any :authority |
279 | /// This is mostly useful for writing generic gRPC Proxies where the exact |
280 | /// serialization format is unknown |
281 | ServerBuilder& RegisterCallbackGenericService( |
282 | grpc::experimental::CallbackGenericService* service); |
283 | #endif |
284 | |
285 | enum class ExternalConnectionType { |
286 | FROM_FD = 0 // in the form of a file descriptor |
287 | }; |
288 | |
289 | /// Register an acceptor to handle the externally accepted connection in |
290 | /// grpc server. The returned acceptor can be used to pass the connection |
291 | /// to grpc server, where a channel will be created with the provided |
292 | /// server credentials. |
293 | std::unique_ptr<grpc::experimental::ExternalConnectionAcceptor> |
294 | AddExternalConnectionAcceptor(ExternalConnectionType type, |
295 | std::shared_ptr<ServerCredentials> creds); |
296 | |
297 | private: |
298 | ServerBuilder* builder_; |
299 | }; |
300 | |
301 | #ifdef GRPC_CALLBACK_API_NONEXPERIMENTAL |
302 | /// Register a generic service that uses the callback API. |
303 | /// Matches requests with any :authority |
304 | /// This is mostly useful for writing generic gRPC Proxies where the exact |
305 | /// serialization format is unknown |
306 | ServerBuilder& RegisterCallbackGenericService( |
307 | grpc::CallbackGenericService* service); |
308 | #endif |
309 | |
310 | /// NOTE: The function experimental() is not stable public API. It is a view |
311 | /// to the experimental components of this class. It may be changed or removed |
312 | /// at any time. |
313 | experimental_type experimental() { return experimental_type(this); } |
314 | |
315 | protected: |
316 | /// Experimental, to be deprecated |
317 | struct Port { |
318 | grpc::string addr; |
319 | std::shared_ptr<grpc_impl::ServerCredentials> creds; |
320 | int* selected_port; |
321 | }; |
322 | |
323 | /// Experimental, to be deprecated |
324 | typedef std::unique_ptr<grpc::string> HostString; |
325 | struct NamedService { |
326 | explicit NamedService(grpc::Service* s) : service(s) {} |
327 | NamedService(const grpc::string& h, grpc::Service* s) |
328 | : host(new grpc::string(h)), service(s) {} |
329 | HostString host; |
330 | grpc::Service* service; |
331 | }; |
332 | |
333 | /// Experimental, to be deprecated |
334 | std::vector<Port> ports() { return ports_; } |
335 | |
336 | /// Experimental, to be deprecated |
337 | std::vector<NamedService*> services() { |
338 | std::vector<NamedService*> service_refs; |
339 | for (auto& ptr : services_) { |
340 | service_refs.push_back(ptr.get()); |
341 | } |
342 | return service_refs; |
343 | } |
344 | |
345 | /// Experimental, to be deprecated |
346 | std::vector<grpc::ServerBuilderOption*> options() { |
347 | std::vector<grpc::ServerBuilderOption*> option_refs; |
348 | for (auto& ptr : options_) { |
349 | option_refs.push_back(ptr.get()); |
350 | } |
351 | return option_refs; |
352 | } |
353 | |
354 | private: |
355 | friend class ::grpc::testing::ServerBuilderPluginTest; |
356 | |
357 | struct SyncServerSettings { |
358 | SyncServerSettings() |
359 | : num_cqs(1), min_pollers(1), max_pollers(2), cq_timeout_msec(10000) {} |
360 | |
361 | /// Number of server completion queues to create to listen to incoming RPCs. |
362 | int num_cqs; |
363 | |
364 | /// Minimum number of threads per completion queue that should be listening |
365 | /// to incoming RPCs. |
366 | int min_pollers; |
367 | |
368 | /// Maximum number of threads per completion queue that can be listening to |
369 | /// incoming RPCs. |
370 | int max_pollers; |
371 | |
372 | /// The timeout for server completion queue's AsyncNext call. |
373 | int cq_timeout_msec; |
374 | }; |
375 | |
376 | int max_receive_message_size_; |
377 | int max_send_message_size_; |
378 | std::vector<std::unique_ptr<grpc::ServerBuilderOption>> options_; |
379 | std::vector<std::unique_ptr<NamedService>> services_; |
380 | std::vector<Port> ports_; |
381 | |
382 | SyncServerSettings sync_server_settings_; |
383 | |
384 | /// List of completion queues added via \a AddCompletionQueue method. |
385 | std::vector<grpc_impl::ServerCompletionQueue*> cqs_; |
386 | |
387 | std::shared_ptr<grpc_impl::ServerCredentials> creds_; |
388 | std::vector<std::unique_ptr<grpc::ServerBuilderPlugin>> plugins_; |
389 | grpc_resource_quota* resource_quota_; |
390 | grpc::AsyncGenericService* generic_service_{nullptr}; |
391 | #ifdef GRPC_CALLBACK_API_NONEXPERIMENTAL |
392 | grpc::CallbackGenericService* callback_generic_service_{nullptr}; |
393 | #else |
394 | grpc::experimental::CallbackGenericService* callback_generic_service_{ |
395 | nullptr}; |
396 | #endif |
397 | |
398 | struct { |
399 | bool is_set; |
400 | grpc_compression_level level; |
401 | } maybe_default_compression_level_; |
402 | struct { |
403 | bool is_set; |
404 | grpc_compression_algorithm algorithm; |
405 | } maybe_default_compression_algorithm_; |
406 | uint32_t enabled_compression_algorithms_bitset_; |
407 | std::vector< |
408 | std::unique_ptr<grpc::experimental::ServerInterceptorFactoryInterface>> |
409 | interceptor_creators_; |
410 | std::vector<std::shared_ptr<grpc::internal::ExternalConnectionAcceptorImpl>> |
411 | acceptors_; |
412 | }; |
413 | |
414 | } // namespace grpc_impl |
415 | |
416 | #endif // GRPCPP_SERVER_BUILDER_IMPL_H |
417 | |