Struct tonic::transport::server::Server

pub struct Server<L = Identity> { /* private fields */ }

A default batteries included transport server.

This provides an easy builder pattern style builder Server on top of hyper connections. This builder exposes easy configuration parameters for providing a fully featured http2 based gRPC server. This should provide a very good out of the box http2 server for use with tonic but is also a reference implementation that should be a good starting point for anyone wanting to create a more complex and/or specific implementation.

Implementations

impl Server

pub fn builder() -> Self

Create a new server builder that can configure a Server.

impl<L> Server<L>

pub fn concurrency_limit_per_connection(self, limit: usize) -> Self

Set the concurrency limit applied to on requests inbound per connection.

Example

builder.concurrency_limit_per_connection(32);

pub fn timeout(self, timeout: Duration) -> Self

Set a timeout on for all request handlers.

Example

builder.timeout(Duration::from_secs(30));

pub fn initial_stream_window_size(self, sz: impl Into<Option<u32>>) -> Self

Sets the SETTINGS_INITIAL_WINDOW_SIZE option for HTTP2 stream-level flow control.

Default is 65,535

pub fn initial_connection_window_size(self, sz: impl Into<Option<u32>>) -> Self

Sets the max connection-level flow control for HTTP2

Default is 65,535

pub fn max_concurrent_streams(self, max: impl Into<Option<u32>>) -> Self

Sets the SETTINGS_MAX_CONCURRENT_STREAMS option for HTTP2 connections.

Default is no limit (None).

pub fn max_connection_age(self, max_connection_age: Duration) -> Self

Sets the maximum time option in milliseconds that a connection may exist

Default is no limit (None).

Example

builder.max_connection_age(Duration::from_secs(60));

pub fn http2_keepalive_interval( self, http2_keepalive_interval: Option<Duration>, ) -> Self

Set whether HTTP2 Ping frames are enabled on accepted connections.

If None is specified, HTTP2 keepalive is disabled, otherwise the duration specified will be the time interval between HTTP2 Ping frames. The timeout for receiving an acknowledgement of the keepalive ping can be set with Server::http2_keepalive_timeout.

Default is no HTTP2 keepalive (None)

pub fn http2_keepalive_timeout( self, http2_keepalive_timeout: Option<Duration>, ) -> Self

Sets a timeout for receiving an acknowledgement of the keepalive ping.

If the ping is not acknowledged within the timeout, the connection will be closed. Does nothing if http2_keep_alive_interval is disabled.

Default is 20 seconds.

pub fn http2_adaptive_window(self, enabled: Option<bool>) -> Self

Sets whether to use an adaptive flow control. Defaults to false. Enabling this will override the limits set in http2_initial_stream_window_size and http2_initial_connection_window_size.

pub fn http2_max_pending_accept_reset_streams(self, max: Option<usize>) -> Self

Configures the maximum number of pending reset streams allowed before a GOAWAY will be sent.

This will default to whatever the default in h2 is. As of v0.3.17, it is 20.

See https://github.com/hyperium/hyper/issues/2877 for more information.

pub fn tcp_keepalive(self, tcp_keepalive: Option<Duration>) -> Self

Set whether TCP keepalive messages are enabled on accepted connections.

If None is specified, keepalive is disabled, otherwise the duration specified will be the time to remain idle before sending TCP keepalive probes.

Default is no keepalive (None)

pub fn tcp_nodelay(self, enabled: bool) -> Self

Set the value of TCP_NODELAY option for accepted connections. Enabled by default.

pub fn http2_max_header_list_size(self, max: impl Into<Option<u32>>) -> Self

Sets the max size of received header frames.

This will default to whatever the default in hyper is. As of v1.4.1, it is 16 KiB.

pub fn max_frame_size(self, frame_size: impl Into<Option<u32>>) -> Self

Sets the maximum frame size to use for HTTP2.

Passing None will do nothing.

If not set, will default from underlying transport.

pub fn accept_http1(self, accept_http1: bool) -> Self

Allow this server to accept http1 requests.

Accepting http1 requests is only useful when developing grpc-web enabled services. If this setting is set to true but services are not correctly configured to handle grpc-web requests, your server may return confusing (but correct) protocol errors.

Default is false.

pub fn trace_fn<F>(self, f: F) -> Self

where F: Fn(&Request<()>) -> Span + Send + Sync + 'static,

Intercept inbound headers and add a tracing::Span to each response future.

pub fn add_service<S>(&mut self, svc: S) -> Router<L>

where S: Service<Request<BoxBody>, Response = Response<BoxBody>, Error = Infallible> + NamedService + Clone + Send + 'static, S::Future: Send + 'static, L: Clone,

Create a router with the S typed service as the first service.

This will clone the Server builder and create a router that will route around different services.

pub fn add_optional_service<S>(&mut self, svc: Option<S>) -> Router<L>

where S: Service<Request<BoxBody>, Response = Response<BoxBody>, Error = Infallible> + NamedService + Clone + Send + 'static, S::Future: Send + 'static, L: Clone,

Create a router with the optional S typed service as the first service.

This will clone the Server builder and create a router that will route around different services.

Note

Even when the argument given is None this will capture all requests to this service name. As a result, one cannot use this to toggle between two identically named implementations.

pub fn add_routes(&mut self, routes: Routes) -> Router<L>

where L: Clone,

Create a router with given Routes.

This will clone the Server builder and create a router that will route around different services that were already added to the provided routes.

pub fn layer<NewLayer>(self, new_layer: NewLayer) -> Server<Stack<NewLayer, L>>

Set the Tower Layer all services will be wrapped in.

This enables using middleware from the Tower ecosystem.

Example

use tower::timeout::TimeoutLayer;
use std::time::Duration;

builder.layer(TimeoutLayer::new(Duration::from_secs(30)));

Note that timeouts should be set using Server::timeout. TimeoutLayer is only used here as an example.

You can build more complex layers using ServiceBuilder. Those layers can include interceptors:

use tower::ServiceBuilder;
use std::time::Duration;
use tonic::{Request, Status, service::interceptor};

fn auth_interceptor(request: Request<()>) -> Result<Request<()>, Status> {
    if valid_credentials(&request) {
        Ok(request)
    } else {
        Err(Status::unauthenticated("invalid credentials"))
    }
}

fn valid_credentials(request: &Request<()>) -> bool {
    // ...
}

fn some_other_interceptor(request: Request<()>) -> Result<Request<()>, Status> {
    Ok(request)
}

let layer = ServiceBuilder::new()
    .load_shed()
    .timeout(Duration::from_secs(30))
    .layer(interceptor(auth_interceptor))
    .layer(interceptor(some_other_interceptor))
    .into_inner();

Server::builder().layer(layer);

Trait Implementations

impl<L: Clone> Clone for Server<L>

fn clone(&self) -> Server<L>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L> Debug for Server<L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Server<Identity>

fn default() -> Self

Returns the “default value” for a type.