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 73 pub use call::GrpcWebCall; 74 pub use client::{GrpcWebClientLayer, GrpcWebClientService}; 75 pub use layer::GrpcWebLayer; 76 pub use service::{GrpcWebService, ResponseFuture}; 77 78 mod call; 79 mod client; 80 mod layer; 81 mod service; 82 83 type BoxError = Box<dyn std::error::Error + Send + Sync>; 84 85 pub(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 } 103