feat(grpc): add server-side stream validators by sauravzg · Pull Request #2602 · hyperium/tonic

sauravzg · 2026-04-23T18:21:35Z

Introduces ServerSendStreamValidator and ServerRecvStreamValidator to enforce strict gRPC semantics on server streams. These are intended to wrap raw transport streams before passing them to application-level handlers, ensuring that user-provided service logic cannot violate protocol rules.

ServerSendStreamValidator ensures proper response sequencing (Headers -> Messages -> Trailers) and prevents invalid state transitions, while fully supporting trailers-only responses.
ServerRecvStreamValidator safely manages terminal states, ensuring that any subsequent polls after stream completion consistently return an error to prevent undefined behavior.
Adds comprehensive unit tests to verify state machine correctness and protocol compliance.

This is recreation of #2595 to allow using a stacked PR workflow

dfawley

I'm trying to figure out how exactly this is going to be used.

Most likely it will be a server-side interceptor? In which case, when an error occurs, I would think we'd want to terminate the RPC with a status that indicates the cause of the problem.

sauravzg · 2026-04-30T18:55:05Z

I'm trying to figure out how exactly this is going to be used.

Most likely it will be a server-side interceptor? In which case, when an error occurs, I would think we'd want to terminate the RPC with a status that indicates the cause of the problem.

Yes on the server side interceptor.

RecvStreamVal.. is somewhat straight forward. This'll be used closer to the protobuf API to ensure that we transition our generic stream request receiver to the protobuf API stream object.

SendStreamVal.. is closer to the transport to validate the outgoing data after all other interceptors.

I somewhat agree with the need for status. We need to update the SendStream API on the server side to return status. This wasn't a problem previously because Trailers were a part of the SendStream and would be used to send trailers and terminate the API.

Now that we are returning trailers instead of sending them, we need more details from SendStream to propagate to trailers . Does it sound okay to add Status to the SendStream API itself, because we initially had some reservations on it , but I guess the situation has changed.

dfawley · 2026-04-30T20:03:23Z

I somewhat agree with the need for status. We need to update the SendStream API on the server side to return status. This wasn't a problem previously because Trailers were a part of the SendStream and would be used to send trailers and terminate the API.

I was expecting we'd just need an interceptor that can terminate the RPC underneath the handler when either the SendStream or RecvStream has any problem. I.e. we can't do stream validation via something that simply wraps each stream independently.

sauravzg · 2026-05-04T04:35:25Z

I somewhat agree with the need for status. We need to update the SendStream API on the server side to return status. This wasn't a problem previously because Trailers were a part of the SendStream and would be used to send trailers and terminate the API.

I was expecting we'd just need an interceptor that can terminate the RPC underneath the handler when either the SendStream or RecvStream has any problem. I.e. we can't do stream validation via something that simply wraps each stream independently.

I mean we are definitely gonna need an interceptor for this. But I was planning to separate it into two responsibilities , one for lifecycle for stream and another for lifecycle of handler.

Something along the lines of RecvStreamValidator and moving the logic of stream termination closer to the protobuf API.
and then
SendStreamValidator and moving the logic of handling errors from the SendStream closer to the transport to handle error from interceptors.

But we might need some status on the SendStream now, because if sendstream terminates, we'll need to return Trailers. I could either terminate the stream with some arbitrary Internal stream broken error, or we could try and "safely" propagate the error to trailers?

dfawley · 2026-05-07T16:10:35Z

But I was planning to separate it into two responsibilities , one for lifecycle for stream and another for lifecycle of handler.

Sure but they will need to be linked, so it would make more sense to me to make them all together.

Something along the lines of RecvStreamValidator and moving the logic of stream termination closer to the protobuf API.
and then SendStreamValidator and moving the logic of handling errors from the SendStream closer to the transport to handle error from interceptors.

So you're thinking two different interceptors might be needed?

or we could try and "safely" propagate the error to trailers?

Yes we should make sure the RPC error includes an explanation of the protocol violation. I expect the interceptor would basically select on the handler future and a receive from a oneshot channel that the validator writes to, and then terminates with whichever status comes first, dropping the other future.

sauravzg · 2026-05-07T16:36:56Z

So, we discussed offline. It'd make sense for both stream and handler validation to be a part of the same PR.

I initially thought we'd need different handlers, but based on my progress so far, I believe a single one suffices.

Yes we should make sure the RPC error includes an explanation of the protocol violation. I expect the interceptor would basically select on the handler future and a receive from a oneshot channel that the validator writes to, and then terminates with whichever status comes first, dropping the other future.

Since , we don't expose error status from sendstream or recvstream right now, we cannot propagate anything beyond an arbitrary "internal error: stream broken" . Would you want to tweak our stream APIs to be able to propagate errors Err(Status) or Err(String) instead of Err()

sauravzg · 2026-05-08T16:31:38Z

The validation implementation has been updated to be interceptor based and the stream validation utilities are now private.

There's still a question about if we should introduce "status" or "error messages" into the sendstream and recvstream to be propagated to trailer or will an arbitrary "internal error" suffice.

Also, this now is stacked on top of #2634

Enforces strict gRPC stream state transitions and sequence validation on the server side to prevent malformed responses and improper polling. Key Changes: - **Send Stream Validation (`ServerSendStreamValidator`)**: Tracks state transitions (`Init` -> `HeadersSent` -> `MessagesSent` -> `Done`) to guarantee headers are sent exactly once and always precede messages, rejecting invalid operations. - **Receive Stream Validation (`ServerRecvStreamValidator`)**: Prevents erroneous polling by returning stable errors once the receive stream reaches EOF or a terminal error state. - **Preemptive Error Interception (`StreamValidationInterceptor`)**: Wraps streams with channel-aware validators to immediately preempt handler execution via `tokio::select!` upon detecting any protocol violation or underlying transport error, automatically returning an `Internal` status.

dfawley · 2026-05-14T21:52:15Z

+}
+
+impl<S: SendStream> ServerSendStreamValidator<S> {
+    pub fn new(inner: S) -> Self {


I think this needs to not be public since the type isn't public? (And same for the other types below)

dfawley · 2026-05-14T21:58:35Z

+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum RecvStreamState {
+    Init,


Nit: Init isn't quite right here, because you stay in init even after getting some messages. Maybe Active? Or you could replace this enum with a bool, maybe.

dfawley · 2026-05-14T22:09:20Z

+
+struct ChannelAwareSendStreamValidator<S> {
+    inner: ServerSendStreamValidator<S>,
+    error_tx: tokio::sync::mpsc::Sender<()>,


Would an Option<Oneshot> be preferable here? It might make the access simpler, but I'm not sure.

dfawley · 2026-05-14T22:13:43Z

+    }
+}
+
+struct ChannelAwareRecvStreamValidator<R> {


Maybe we don't need this? It seems OK if the application keeps receiving after getting an error. We want our wrapper to avoid propagating that read down further, since it would be illegal-per-the-API to do so, but I don't think that needs to error the whole call?

dfawley · 2026-05-14T22:15:15Z

+        tokio::select! {
+            res = next.handle(headers, options, &mut wrapped_tx, wrapped_rx) => {
+                if error_rx.try_recv().is_ok() {
+                    Trailers::new(Err(StatusError::new(StatusCodeError::Internal, "Stream validation error")))


On the one hand, it's unfortunate that we aren't being any more specific than this. "Server attempted to send multiple headers / messages before headers / etc"

On the other hand, maybe it's for the best, since the client maybe shouldn't get details about server bugs?

sauravzg requested a review from dfawley April 23, 2026 18:21

sauravzg force-pushed the sauravz/handle-trailers branch from 507787e to e2f4bd0 Compare April 23, 2026 18:29

sauravzg force-pushed the sauravz/server-stream-validators branch 2 times, most recently from c5c0e67 to 038f365 Compare April 23, 2026 18:52

sauravzg force-pushed the sauravz/handle-trailers branch from e2f4bd0 to 90ae261 Compare April 27, 2026 15:40

sauravzg force-pushed the sauravz/server-stream-validators branch from 038f365 to 89b8525 Compare April 27, 2026 15:40

Base automatically changed from sauravz/handle-trailers to master April 29, 2026 12:02

sauravzg added the A-grpc-next label Apr 29, 2026

sauravzg force-pushed the sauravz/server-stream-validators branch from 89b8525 to 355c9cd Compare April 29, 2026 12:04

dfawley reviewed Apr 29, 2026

View reviewed changes

Comment thread grpc/src/server/stream_util.rs Outdated

dfawley assigned sauravzg Apr 29, 2026

sauravzg force-pushed the sauravz/server-stream-validators branch from 355c9cd to de7ee29 Compare April 30, 2026 18:34

sauravzg removed their assignment Apr 30, 2026

sauravzg requested a review from dfawley April 30, 2026 18:55

sauravzg force-pushed the sauravz/server-stream-validators branch from de7ee29 to a2a44a2 Compare May 8, 2026 16:28

sauravzg changed the base branch from master to sauravz/server-interceptor-api May 8, 2026 16:29

sauravzg force-pushed the sauravz/server-stream-validators branch from a2a44a2 to e930953 Compare May 14, 2026 16:08

sauravzg force-pushed the sauravz/server-interceptor-api branch from 56323f1 to 51903a9 Compare May 14, 2026 16:08

dfawley reviewed May 14, 2026

View reviewed changes

dfawley assigned sauravzg May 14, 2026

dfawley added this to the grpc-next milestone May 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(grpc): add server-side stream validators#2602

feat(grpc): add server-side stream validators#2602
sauravzg wants to merge 1 commit into
sauravz/server-interceptor-apifrom
sauravz/server-stream-validators

sauravzg commented Apr 23, 2026

Uh oh!

dfawley left a comment

Uh oh!

Uh oh!

sauravzg commented Apr 30, 2026

Uh oh!

dfawley commented Apr 30, 2026

Uh oh!

sauravzg commented May 4, 2026

Uh oh!

dfawley commented May 7, 2026

Uh oh!

sauravzg commented May 7, 2026

Uh oh!

sauravzg commented May 8, 2026 •

edited

Loading

Uh oh!

dfawley May 14, 2026

Uh oh!

dfawley May 14, 2026

Uh oh!

dfawley May 14, 2026

Uh oh!

dfawley May 14, 2026

Uh oh!

dfawley May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sauravzg commented Apr 23, 2026

Uh oh!

dfawley left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sauravzg commented Apr 30, 2026

Uh oh!

dfawley commented Apr 30, 2026

Uh oh!

sauravzg commented May 4, 2026

Uh oh!

dfawley commented May 7, 2026

Uh oh!

sauravzg commented May 7, 2026

Uh oh!

sauravzg commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dfawley May 14, 2026

Choose a reason for hiding this comment

Uh oh!

dfawley May 14, 2026

Choose a reason for hiding this comment

Uh oh!

dfawley May 14, 2026

Choose a reason for hiding this comment

Uh oh!

dfawley May 14, 2026

Choose a reason for hiding this comment

Uh oh!

dfawley May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sauravzg commented May 8, 2026 •

edited

Loading