tonic_web/
lib.rs

1//! grpc-web protocol translation for [`tonic`] services.
2//!
3//! [`tonic_web`] enables tonic servers to handle requests from [grpc-web] clients directly,
4//! without the need of an external proxy. It achieves this by wrapping individual tonic services
5//! with a [tower] service that performs the translation between protocols and handles `cors`
6//! requests.
7//!
8//! ## Enabling tonic services
9//!
10//! You can customize the CORS configuration composing the [`GrpcWebLayer`] with the cors layer of your choice.
11//!
12//! ```ignore
13//! #[tokio::main]
14//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
15//!     let addr = "[::1]:50051".parse().unwrap();
16//!     let greeter = GreeterServer::new(MyGreeter::default());
17//!
18//!     Server::builder()
19//!        .accept_http1(true)
20//!        // This will apply the gRPC-Web translation layer
21//!        .layer(GrpcWebLayer::new())
22//!        .add_service(greeter)
23//!        .serve(addr)
24//!        .await?;
25//!
26//!    Ok(())
27//! }
28//! ```
29//!
30//! Alternatively, if you have a tls enabled server, you could skip setting `accept_http1` to `true`.
31//! This works because the browser will handle `ALPN`.
32//!
33//! ```ignore
34//! #[tokio::main]
35//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
36//!     let cert = tokio::fs::read("server.pem").await?;
37//!     let key = tokio::fs::read("server.key").await?;
38//!     let identity = Identity::from_pem(cert, key);
39//!
40//!     let addr = "[::1]:50051".parse().unwrap();
41//!     let greeter = GreeterServer::new(MyGreeter::default());
42//!
43//!     // No need to enable HTTP/1
44//!     Server::builder()
45//!        .tls_config(ServerTlsConfig::new().identity(identity))?
46//!        .layer(GrpcWebLayer::new())
47//!        .add_service(greeter)
48//!        .serve(addr)
49//!        .await?;
50//!
51//!    Ok(())
52//! }
53//! ```
54//!
55//! ## Limitations
56//!
57//! * `tonic_web` is designed to work with grpc-web-compliant clients only. It is not expected to
58//!   handle arbitrary HTTP/x.x requests or bespoke protocols.
59//! * Similarly, the cors support implemented  by this crate will *only* handle grpc-web and
60//!   grpc-web preflight requests.
61//! * Currently, grpc-web clients can only perform `unary` and `server-streaming` calls. These
62//!   are the only requests this crate is designed to handle. Support for client and bi-directional
63//!   streaming will be officially supported when clients do.
64//! * There is no support for web socket transports.
65//!
66//!
67//! [`tonic`]: https://github.com/hyperium/tonic
68//! [`tonic_web`]: https://github.com/hyperium/tonic
69//! [grpc-web]: https://github.com/grpc/grpc-web
70//! [tower]: https://github.com/tower-rs/tower
71#![doc(issue_tracker_base_url = "https://github.com/hyperium/tonic/issues/")]
72
73pub use call::GrpcWebCall;
74pub use client::{GrpcWebClientLayer, GrpcWebClientService};
75pub use layer::GrpcWebLayer;
76pub use service::{GrpcWebService, ResponseFuture};
77
78mod call;
79mod client;
80mod layer;
81mod service;
82
83type BoxError = Box<dyn std::error::Error + Send + Sync>;
84
85pub(crate) mod util {
86    pub(crate) mod base64 {
87        use base64::{
88            alphabet,
89            engine::{
90                general_purpose::{GeneralPurpose, GeneralPurposeConfig},
91                DecodePaddingMode,
92            },
93        };
94
95        pub(crate) const STANDARD: GeneralPurpose = GeneralPurpose::new(
96            &alphabet::STANDARD,
97            GeneralPurposeConfig::new()
98                .with_encode_padding(true)
99                .with_decode_padding_mode(DecodePaddingMode::Indifferent),
100        );
101    }
102}
tonic_web/lib.rs

tonic_web/
lib.rs
