Should ServiceExt::serve() return after initialization?

[the-isz]

Looking at examples/servers/src/counter_stdio.rs (but other examples and README.md use the same code):

let service = Counter::new().serve(stdio()).await.inspect_err(|e| {
    tracing::error!("serving error: {:?}", e);
})?;

service.waiting().await?;

The above code implies to me that ServiceExt::serve() returns either a RunningService or an initialization error after being awaited.
After the successful initialization I expect that I can do other stuff and then eventually wait for the service to shut down (e.g. via the second line).

However, any code I add after the first line is never reached.
So I think something is wrong here.

Either I'm misunderstanding the API and ServiceExt::serve() is not supposed to return after initialization.
But then I wonder why we even have the second line in the example and how I'm supposed to do other (asynchronous) stuff after starting the service.

Or this is a bug and ServiceExt::serve() is supposed to return after initialization.

Thank you for your help!
I'm really impressed by this package and glad it sees so much development!

[the-isz]

I forgot to mention I created my own Cargo.toml with just src/bin/counter_stdio.rs and src/common/counter.rs - maybe I did something wrong in my Cargo.toml?

Cargo.toml

[package]
name = "mcp_test"
version = "0.1.0"
edition = "2024"

[dependencies]
anyhow = "1.0.104"
axum = "0.8.9"
rmcp = { version = "3.1.1", features = ["transport-io"] }
serde = "1.0.229"
serde_json = "1.0.151"
tokio = { version = "1.53.1", features = ["full"] }
tracing = "0.1.44"
tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }

[the-isz]

I experimented a little more and think I found a way to execute other asynchronous code (handling CTRL-C in my example):

    let ct = tokio_util::sync::CancellationToken::new();
    let ct2 = ct.clone();

    let service_task = tokio::spawn(async move {
        match Counter::new().serve_with_ct(stdio(), ct2).await {
            Ok(running_service) => {
                running_service.waiting().await;
            }
            Err(e) => tracing::error!("serving error: {:?}", e),
        };
    });

    tokio::signal::ctrl_c().await?;
    tracing::info!("CTRL-C -> Stop service");
    ct.cancel();
    tracing::info!("Wait for service to shut down");
    service_task.await?;
    tracing::info!("Service shut down -> Exit");

While this code does what I expected, it has multiple problems:

1. After printing Service shut down -> Exit, the program hangs and needs to be killed (SIGKILL).
2. The code is much different from what the examples are using. New users may run into the same issue.

I haven't tested this with a matching client (I just started the server).
Does this maybe not happen when a client talks to the server?
Could it be a problem of blocking I/O?

[the-isz]

I tested the counter service with a process (client) that spawns the service (based on examples/clients/src/task_stdio.rs) and everything works fine:
ServiceExt::serve() returns after the initialization request (but blocks until this first request has been received).

My big misconception was that I thought of the service executable as a standalone executable (like you would with a service listening on a port).
stdio-based processes however typically only make sense when launched from another process.

Now that I realize this, the issue seems much less critical.

• Are there any strategic spots in the documentation and/or the stdio examples where one could add a comment that ServiceExt::serve() only returns after the first request?
• Is it even possible to have ServiceExt::serve() return before the first request?
  That would be the nicest solution, since it matches the behavior of other transport implementations.