Non-Send gRPC handler futures can be hard to diagnose when using connectrpc-axum

[FedorKiselev76]

Summary

While migrating to axum 0.8 + tonic 0.14, I ran into a situation where a non-Send gRPC handler future was effectively hidden when using connectrpc-axum, but became immediately obvious when switching to direct Axum routing with post_service.

This is not a bug in connectrpc-axum, but the abstraction can make the real root cause harder to discover, especially for users migrating to newer Axum versions.

Root cause

The actual issue was in my tonic service implementation.

I was holding a tokio::sync::MutexGuard across an .await, which makes the handler future !Send.

Axum 0.8 correctly requires:

Service::Future: Send

Problematic pattern (old code)

#[derive(Clone)]
pub struct LocalAuth {
    issuer: Arc<JwtIssuer>,
    dbcache: Arc<tokio::sync::Mutex<DbCacheWrapper>>,
}

#[tonic::async_trait]
impl Auth for LocalAuth {
    async fn init(
        &self,
        req: Request<InitRequest>,
    ) -> Result<Response<InitResponse>, Status> {
        let uuid = req.into_inner().uuid;

        // ❌ MutexGuard is held across an await
        let client_id = {
            let mut dbc = self.dbcache.lock().await;
            dbc.get_by_uuid(&uuid).await?.customer_id
        };

        Ok(Response::new(InitResponse {
            /* ... */
        }))
    }
}

Holding a MutexGuard across .await causes the entire future returned by init() to become non-Send.

Why this was confusing with connectrpc-axum

When the service was wired using:

MakeServiceBuilder::new()
    .add_grpc_service(AuthServer::new(local_auth))
    .build();

the !Send future did not surface immediately at the integration point.

After switching to direct Axum integration:

Router::new()
    .route(
        "/auth.v1.Auth/{*wildcard}",
        post_service(AuthServer::new(local_auth)),
    )

Axum failed fast with a clear and direct error:

error[E0277]: the trait bound ...::Future: Send is not satisfied

This instantly pointed to the real issue.

Why this matters

Axum 0.8 enforces Send very strictly (and correctly)

Holding a MutexGuard across .await is a common async Rust pitfall

With connectrpc-axum, this issue may:

surface later

or appear in a less obvious place

This can make debugging harder for users migrating from older stacks

Suggestions (documentation / diagnostics)

This is not a request to change behavior, just a suggestion to improve developer experience.

Documentation note

It would be very helpful to explicitly mention that:

gRPC handlers must be Send

Holding tokio::sync::MutexGuard across .await will break this

This is especially important with axum 0.8+

Earlier diagnostics (if feasible)

If possible, adding earlier trait bounds or clearer diagnostics around:

Service::Future: Send

could help users discover this issue closer to where services are registered.

[washanhanzi]

Thanks for reporting this. I will check If I can add the Send trait bound.

[washanhanzi]

I tried to reproduce the problem.

use axum::extract::State;
use connectrpc_axum::prelude::*;
use hello_connect::{helloworldservice, HelloRequest, HelloResponse};
use std::sync::{Arc, Mutex};

#[derive(Clone, Default)]
struct AppState {
    counter: Arc<Mutex<u64>>,
}

async fn say_hello(
    State(s): State<AppState>,
    ConnectRequest(req): ConnectRequest<HelloRequest>,
) -> Result<ConnectResponse<HelloResponse>, ConnectError> {
    // Hold MutexGuard across await - makes future non-Send!
    let mut counter = s.counter.lock().unwrap();
    tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
    *counter += 1;
    Ok(ConnectResponse(HelloResponse {
        message: format!("Hello, {}!", req.name.unwrap_or_default()),
    }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build both Connect router and gRPC server from same handlers
    let (connect_router, grpc_server) =
        helloworldservice::HelloWorldServiceTonicCompatibleBuilder::new()
            // ------------------ COMPILE ERROR HERE
            .say_hello(say_hello)
            .with_state(AppState::default())
            .build();

    // Combine into a single service that routes by Content-Type:
    // - application/grpc* -> Tonic gRPC server
    // - Otherwise -> Axum routes (Connect protocol)
    let service = connectrpc_axum::MakeServiceBuilder::new()
        .add_router(connect_router)
        .add_grpc_service(grpc_server)
        .build();

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, tower::make::Shared::new(service)).await?;
    Ok(())
}

This is actually the same behavior in axum (I use the same axum design for tonic handler):

use axum::{Router, extract::State, routing::get};
use std::sync::{Arc, Mutex};

struct AppState {
    counter: Mutex<u64>,
}

async fn handler(State(state): State<Arc<AppState>>) -> String {
    let mut counter = state.counter.lock().unwrap();

    // Simulate some async work while holding the lock
    tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;

    *counter += 1;
    format!("Counter: {}", *counter)
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        counter: Mutex::new(0),
    });

    // ------------------ COMPILE ERROR HERE
    let app = Router::new().route("/", get(handler)).with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

The MakeServiceBuilder is not aware of the underlying handler, it only work with axum route or tonic service. I have setup a docuemtn on this: https://washanhanzi.github.io/connectrpc-axum/guide/configuration

I don't know whether my code example fully reproduce your problem. If not, could you provide a more detailed code example or an example repo?

[FedorKiselev76]

One small clarification: in my original code the guard was tokio::sync::MutexGuard, not std::sync::MutexGuard.

Would you mind trying the same reproduction but replacing

use std::sync::Mutex;

with

use tokio::sync::Mutex;

and then holding the MutexGuard across an .await, for example:

let mut guard = state.counter.lock().await;
tokio::time::sleep(Duration::from_millis(100)).await;
*guard += 1;

In my case this was the exact pattern (tokio::sync::MutexGuard held across .await) that caused the handler future to become non-Send.

The underlying issue is the same class of bug, but since many async Rust users default to tokio::sync::Mutex, it might be useful to confirm and/or mention this variant explicitly as well.

Thanks!

[washanhanzi]

Hmm, I can't get any error.

the tokio::Mutex can hold across the await.

/// This type acts similarly to [std::sync::Mutex], with two major
/// differences: [lock] is an async method so does not block, and the lock
/// guard is designed to be held across .await points.

use axum::{Router, extract::State, routing::get};
use std::{sync::Arc, time::Duration};
use tokio::sync::Mutex;

struct AppState {
    counter: Mutex<u64>,
}

async fn handler(State(state): State<Arc<AppState>>) -> String {
    let mut guard = state.counter.lock().await;
    tokio::time::sleep(Duration::from_millis(100)).await;
    *guard += 1;
    guard.to_string()
}

#[tokio::main]
async fn main() {
    let state = Arc::new(AppState {
        counter: Mutex::new(0),
    });

    let app = Router::new().route("/", get(handler)).with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}