Crate tonic_web

grpc-web protocol translation for tonic services.

tonic_web enables tonic servers to handle requests from grpc-web clients directly, without the need of an external proxy. It achieves this by wrapping individual tonic services with a tower service that performs the translation between protocols and handles cors requests.

Enabling tonic services

The easiest way to get started, is to call the enable function with your tonic service and allow the tonic server to accept HTTP/1.1 requests:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr = "[::1]:50051".parse().unwrap();
    let greeter = GreeterServer::new(MyGreeter::default());

    Server::builder()
       .accept_http1(true)
       .add_service(tonic_web::enable(greeter))
       .serve(addr)
       .await?;

   Ok(())
}

This will apply a default configuration that works well with grpc-web clients out of the box.

You can customize the CORS configuration composing the GrpcWebLayer with the cors layer of your choice.

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr = "[::1]:50051".parse().unwrap();
    let greeter = GreeterServer::new(MyGreeter::default());

    Server::builder()
       .accept_http1(true)
       // This will apply the gRPC-Web translation layer
       .layer(GrpcWebLayer::new())
       .add_service(greeter)
       .serve(addr)
       .await?;

   Ok(())
}

Alternatively, if you have a tls enabled server, you could skip setting accept_http1 to true. This works because the browser will handle ALPN.

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cert = tokio::fs::read("server.pem").await?;
    let key = tokio::fs::read("server.key").await?;
    let identity = Identity::from_pem(cert, key);

    let addr = "[::1]:50051".parse().unwrap();
    let greeter = GreeterServer::new(MyGreeter::default());

    // No need to enable HTTP/1
    Server::builder()
       .tls_config(ServerTlsConfig::new().identity(identity))?
       .add_service(tonic_web::enable(greeter))
       .serve(addr)
       .await?;

   Ok(())
}

Limitations

• tonic_web is designed to work with grpc-web-compliant clients only. It is not expected to handle arbitrary HTTP/x.x requests or bespoke protocols.
• Similarly, the cors support implemented by this crate will only handle grpc-web and grpc-web preflight requests.
• Currently, grpc-web clients can only perform unary and server-streaming calls. These are the only requests this crate is designed to handle. Support for client and bi-directional streaming will be officially supported when clients do.
• There is no support for web socket transports.

Structs

• CorsGrpcWeb
  A newtype wrapper around GrpcWebLayer and tower_http::cors::CorsLayer to allow tonic_web::enable to implement the NamedService trait.
• GrpcWebCall
  HttpBody adapter for the grpc web based services.
• GrpcWebClientLayer
  Layer implementing the grpc-web protocol for clients.
• GrpcWebClientService
  A Service that wraps some inner http service that will coerce requests coming from tonic::client::Grpc into proper grpc-web requests.
• GrpcWebLayer
  Layer implementing the grpc-web protocol.
• GrpcWebService
  Service implementing the grpc-web protocol.
• ResponseFuture
  Response future for the GrpcWebService.

Functions

• enable
  Enable a tonic service to handle grpc-web requests with the default configuration.