Skip to main content

tonic/server/
grpc.rs

1/*
2 *
3 * Copyright 2025 gRPC authors.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to
7 * deal in the Software without restriction, including without limitation the
8 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 * sell copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
21 * IN THE SOFTWARE.
22 *
23 */
24
25use crate::codec::EncodeBody;
26use crate::codec::compression::{
27    CompressionEncoding, EnabledCompressionEncodings, SingleMessageCompressionOverride,
28};
29use crate::metadata::GRPC_CONTENT_TYPE;
30use crate::{
31    Request, Status,
32    body::Body,
33    codec::{Codec, Streaming},
34    server::{ClientStreamingService, ServerStreamingService, StreamingService, UnaryService},
35};
36use http_body::Body as HttpBody;
37use std::{fmt, pin::pin};
38use tokio_stream::{Stream, StreamExt};
39
40macro_rules! t {
41    ($result:expr) => {
42        match $result {
43            Ok(value) => value,
44            Err(status) => return status.into_http(),
45        }
46    };
47}
48
49/// A gRPC Server handler.
50///
51/// This will wrap some inner [`Codec`] and provide utilities to handle
52/// inbound unary, client side streaming, server side streaming, and
53/// bi-directional streaming.
54///
55/// Each request handler method accepts some service that implements the
56/// corresponding service trait and a http request that contains some body that
57/// implements some [`Body`].
58pub struct Grpc<T> {
59    codec: T,
60    /// Which compression encodings does the server accept for requests?
61    accept_compression_encodings: EnabledCompressionEncodings,
62    /// Which compression encodings might the server use for responses.
63    send_compression_encodings: EnabledCompressionEncodings,
64    /// Limits the maximum size of a decoded message.
65    max_decoding_message_size: Option<usize>,
66    /// Limits the maximum size of an encoded message.
67    max_encoding_message_size: Option<usize>,
68}
69
70impl<T> Grpc<T>
71where
72    T: Codec,
73{
74    /// Creates a new gRPC server with the provided [`Codec`].
75    pub fn new(codec: T) -> Self {
76        Self {
77            codec,
78            accept_compression_encodings: EnabledCompressionEncodings::default(),
79            send_compression_encodings: EnabledCompressionEncodings::default(),
80            max_decoding_message_size: None,
81            max_encoding_message_size: None,
82        }
83    }
84
85    /// Enable accepting compressed requests.
86    ///
87    /// If a request with an unsupported encoding is received the server will respond with
88    /// [`Code::UnUnimplemented`](crate::Code).
89    ///
90    /// # Example
91    ///
92    /// The most common way of using this is through a server generated by tonic-build:
93    ///
94    /// ```rust
95    /// # enum CompressionEncoding { Gzip }
96    /// # struct Svc;
97    /// # struct ExampleServer<T>(T);
98    /// # impl<T> ExampleServer<T> {
99    /// #     fn new(svc: T) -> Self { Self(svc) }
100    /// #     fn accept_compressed(self, _: CompressionEncoding) -> Self { self }
101    /// # }
102    /// # #[tonic::async_trait]
103    /// # trait Example {}
104    ///
105    /// #[tonic::async_trait]
106    /// impl Example for Svc {
107    ///     // ...
108    /// }
109    ///
110    /// let service = ExampleServer::new(Svc).accept_compressed(CompressionEncoding::Gzip);
111    /// ```
112    pub fn accept_compressed(mut self, encoding: CompressionEncoding) -> Self {
113        self.accept_compression_encodings.enable(encoding);
114        self
115    }
116
117    /// Enable sending compressed responses.
118    ///
119    /// Requires the client to also support receiving compressed responses.
120    ///
121    /// # Example
122    ///
123    /// The most common way of using this is through a server generated by tonic-build:
124    ///
125    /// ```rust
126    /// # enum CompressionEncoding { Gzip }
127    /// # struct Svc;
128    /// # struct ExampleServer<T>(T);
129    /// # impl<T> ExampleServer<T> {
130    /// #     fn new(svc: T) -> Self { Self(svc) }
131    /// #     fn send_compressed(self, _: CompressionEncoding) -> Self { self }
132    /// # }
133    /// # #[tonic::async_trait]
134    /// # trait Example {}
135    ///
136    /// #[tonic::async_trait]
137    /// impl Example for Svc {
138    ///     // ...
139    /// }
140    ///
141    /// let service = ExampleServer::new(Svc).send_compressed(CompressionEncoding::Gzip);
142    /// ```
143    pub fn send_compressed(mut self, encoding: CompressionEncoding) -> Self {
144        self.send_compression_encodings.enable(encoding);
145        self
146    }
147
148    /// Limits the maximum size of a decoded message.
149    ///
150    /// # Example
151    ///
152    /// The most common way of using this is through a server generated by tonic-build:
153    ///
154    /// ```rust
155    /// # struct Svc;
156    /// # struct ExampleServer<T>(T);
157    /// # impl<T> ExampleServer<T> {
158    /// #     fn new(svc: T) -> Self { Self(svc) }
159    /// #     fn max_decoding_message_size(self, _: usize) -> Self { self }
160    /// # }
161    /// # #[tonic::async_trait]
162    /// # trait Example {}
163    ///
164    /// #[tonic::async_trait]
165    /// impl Example for Svc {
166    ///     // ...
167    /// }
168    ///
169    /// // Set the limit to 2MB, Defaults to 4MB.
170    /// let limit = 2 * 1024 * 1024;
171    /// let service = ExampleServer::new(Svc).max_decoding_message_size(limit);
172    /// ```
173    pub fn max_decoding_message_size(mut self, limit: usize) -> Self {
174        self.max_decoding_message_size = Some(limit);
175        self
176    }
177
178    /// Limits the maximum size of a encoded message.
179    ///
180    /// # Example
181    ///
182    /// The most common way of using this is through a server generated by tonic-build:
183    ///
184    /// ```rust
185    /// # struct Svc;
186    /// # struct ExampleServer<T>(T);
187    /// # impl<T> ExampleServer<T> {
188    /// #     fn new(svc: T) -> Self { Self(svc) }
189    /// #     fn max_encoding_message_size(self, _: usize) -> Self { self }
190    /// # }
191    /// # #[tonic::async_trait]
192    /// # trait Example {}
193    ///
194    /// #[tonic::async_trait]
195    /// impl Example for Svc {
196    ///     // ...
197    /// }
198    ///
199    /// // Set the limit to 2MB, Defaults to 4MB.
200    /// let limit = 2 * 1024 * 1024;
201    /// let service = ExampleServer::new(Svc).max_encoding_message_size(limit);
202    /// ```
203    pub fn max_encoding_message_size(mut self, limit: usize) -> Self {
204        self.max_encoding_message_size = Some(limit);
205        self
206    }
207
208    #[doc(hidden)]
209    pub fn apply_compression_config(
210        mut self,
211        accept_encodings: EnabledCompressionEncodings,
212        send_encodings: EnabledCompressionEncodings,
213    ) -> Self {
214        for &encoding in CompressionEncoding::ENCODINGS {
215            if accept_encodings.is_enabled(encoding) {
216                self = self.accept_compressed(encoding);
217            }
218            if send_encodings.is_enabled(encoding) {
219                self = self.send_compressed(encoding);
220            }
221        }
222
223        self
224    }
225
226    #[doc(hidden)]
227    pub fn apply_max_message_size_config(
228        mut self,
229        max_decoding_message_size: Option<usize>,
230        max_encoding_message_size: Option<usize>,
231    ) -> Self {
232        if let Some(limit) = max_decoding_message_size {
233            self = self.max_decoding_message_size(limit);
234        }
235        if let Some(limit) = max_encoding_message_size {
236            self = self.max_encoding_message_size(limit);
237        }
238
239        self
240    }
241
242    /// Handle a single unary gRPC request.
243    pub async fn unary<S, B>(
244        &mut self,
245        mut service: S,
246        req: http::Request<B>,
247    ) -> http::Response<Body>
248    where
249        S: UnaryService<T::Decode, Response = T::Encode>,
250        B: HttpBody + Send + 'static,
251        B::Error: Into<crate::BoxError> + Send,
252    {
253        let accept_encoding = CompressionEncoding::from_accept_encoding_header(
254            req.headers(),
255            self.send_compression_encodings,
256        );
257
258        let request = match self.map_request_unary(req).await {
259            Ok(r) => r,
260            Err(status) => {
261                return self.map_response::<tokio_stream::Once<Result<T::Encode, Status>>>(
262                    Err(status),
263                    accept_encoding,
264                    SingleMessageCompressionOverride::default(),
265                    self.max_encoding_message_size,
266                );
267            }
268        };
269
270        let response = service
271            .call(request)
272            .await
273            .map(|r| r.map(|m| tokio_stream::once(Ok(m))));
274
275        let compression_override = compression_override_from_response(&response);
276
277        self.map_response(
278            response,
279            accept_encoding,
280            compression_override,
281            self.max_encoding_message_size,
282        )
283    }
284
285    /// Handle a server side streaming request.
286    pub async fn server_streaming<S, B>(
287        &mut self,
288        mut service: S,
289        req: http::Request<B>,
290    ) -> http::Response<Body>
291    where
292        S: ServerStreamingService<T::Decode, Response = T::Encode>,
293        S::ResponseStream: Send + 'static,
294        B: HttpBody + Send + 'static,
295        B::Error: Into<crate::BoxError> + Send,
296    {
297        let accept_encoding = CompressionEncoding::from_accept_encoding_header(
298            req.headers(),
299            self.send_compression_encodings,
300        );
301
302        let request = match self.map_request_unary(req).await {
303            Ok(r) => r,
304            Err(status) => {
305                return self.map_response::<S::ResponseStream>(
306                    Err(status),
307                    accept_encoding,
308                    SingleMessageCompressionOverride::default(),
309                    self.max_encoding_message_size,
310                );
311            }
312        };
313
314        let response = service.call(request).await;
315
316        self.map_response(
317            response,
318            accept_encoding,
319            // disabling compression of individual stream items must be done on
320            // the items themselves
321            SingleMessageCompressionOverride::default(),
322            self.max_encoding_message_size,
323        )
324    }
325
326    /// Handle a client side streaming gRPC request.
327    pub async fn client_streaming<S, B>(
328        &mut self,
329        mut service: S,
330        req: http::Request<B>,
331    ) -> http::Response<Body>
332    where
333        S: ClientStreamingService<T::Decode, Response = T::Encode>,
334        B: HttpBody + Send + 'static,
335        B::Error: Into<crate::BoxError> + Send + 'static,
336    {
337        let accept_encoding = CompressionEncoding::from_accept_encoding_header(
338            req.headers(),
339            self.send_compression_encodings,
340        );
341
342        let request = t!(self.map_request_streaming(req));
343
344        let response = service
345            .call(request)
346            .await
347            .map(|r| r.map(|m| tokio_stream::once(Ok(m))));
348
349        let compression_override = compression_override_from_response(&response);
350
351        self.map_response(
352            response,
353            accept_encoding,
354            compression_override,
355            self.max_encoding_message_size,
356        )
357    }
358
359    /// Handle a bi-directional streaming gRPC request.
360    pub async fn streaming<S, B>(
361        &mut self,
362        mut service: S,
363        req: http::Request<B>,
364    ) -> http::Response<Body>
365    where
366        S: StreamingService<T::Decode, Response = T::Encode> + Send,
367        S::ResponseStream: Send + 'static,
368        B: HttpBody + Send + 'static,
369        B::Error: Into<crate::BoxError> + Send,
370    {
371        let accept_encoding = CompressionEncoding::from_accept_encoding_header(
372            req.headers(),
373            self.send_compression_encodings,
374        );
375
376        let request = t!(self.map_request_streaming(req));
377
378        let response = service.call(request).await;
379
380        self.map_response(
381            response,
382            accept_encoding,
383            SingleMessageCompressionOverride::default(),
384            self.max_encoding_message_size,
385        )
386    }
387
388    async fn map_request_unary<B>(
389        &mut self,
390        request: http::Request<B>,
391    ) -> Result<Request<T::Decode>, Status>
392    where
393        B: HttpBody + Send + 'static,
394        B::Error: Into<crate::BoxError> + Send,
395    {
396        let request_compression_encoding = self.request_encoding_if_supported(&request)?;
397
398        let (parts, body) = request.into_parts();
399
400        let mut stream = pin!(Streaming::new_request(
401            self.codec.decoder(),
402            body,
403            request_compression_encoding,
404            self.max_decoding_message_size,
405        ));
406
407        let message = stream
408            .try_next()
409            .await?
410            .ok_or_else(|| Status::internal("Missing request message."))?;
411
412        let mut req = Request::from_http_parts(parts, message);
413
414        if let Some(trailers) = stream.trailers().await? {
415            req.metadata_mut().merge(trailers);
416        }
417
418        Ok(req)
419    }
420
421    fn map_request_streaming<B>(
422        &mut self,
423        request: http::Request<B>,
424    ) -> Result<Request<Streaming<T::Decode>>, Status>
425    where
426        B: HttpBody + Send + 'static,
427        B::Error: Into<crate::BoxError> + Send,
428    {
429        let encoding = self.request_encoding_if_supported(&request)?;
430
431        let request = request.map(|body| {
432            Streaming::new_request(
433                self.codec.decoder(),
434                body,
435                encoding,
436                self.max_decoding_message_size,
437            )
438        });
439
440        Ok(Request::from_http(request))
441    }
442
443    fn map_response<B>(
444        &mut self,
445        response: Result<crate::Response<B>, Status>,
446        accept_encoding: Option<CompressionEncoding>,
447        compression_override: SingleMessageCompressionOverride,
448        max_message_size: Option<usize>,
449    ) -> http::Response<Body>
450    where
451        B: Stream<Item = Result<T::Encode, Status>> + Send + 'static,
452    {
453        let response = t!(response);
454
455        let (mut parts, body) = response.into_http().into_parts();
456
457        // Set the content type
458        parts
459            .headers
460            .insert(http::header::CONTENT_TYPE, GRPC_CONTENT_TYPE);
461
462        #[cfg(any(feature = "gzip", feature = "deflate", feature = "zstd"))]
463        if let Some(encoding) = accept_encoding {
464            // Set the content encoding
465            parts.headers.insert(
466                crate::codec::compression::ENCODING_HEADER,
467                encoding.into_header_value(),
468            );
469        }
470
471        let body = EncodeBody::new_server(
472            self.codec.encoder(),
473            body,
474            accept_encoding,
475            compression_override,
476            max_message_size,
477        );
478
479        http::Response::from_parts(parts, Body::new(body))
480    }
481
482    fn request_encoding_if_supported<B>(
483        &self,
484        request: &http::Request<B>,
485    ) -> Result<Option<CompressionEncoding>, Status> {
486        CompressionEncoding::from_encoding_header(
487            request.headers(),
488            self.accept_compression_encodings,
489        )
490    }
491}
492
493impl<T: fmt::Debug> fmt::Debug for Grpc<T> {
494    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
495        f.debug_struct("Grpc")
496            .field("codec", &self.codec)
497            .field(
498                "accept_compression_encodings",
499                &self.accept_compression_encodings,
500            )
501            .field(
502                "send_compression_encodings",
503                &self.send_compression_encodings,
504            )
505            .finish()
506    }
507}
508
509fn compression_override_from_response<B, E>(
510    res: &Result<crate::Response<B>, E>,
511) -> SingleMessageCompressionOverride {
512    res.as_ref()
513        .ok()
514        .and_then(|response| {
515            response
516                .extensions()
517                .get::<SingleMessageCompressionOverride>()
518                .copied()
519        })
520        .unwrap_or_default()
521}