include/grpcpp/server_builder_impl.h

   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