Add timeout and fallback logging for closeGracefully() to prevent hanging shutdown

Read McpAsyncClient.closeGracefully() first, then inspect initializer.closeGracefully() and transport.closeGracefully() to understand their completion behavior. Verify that timeout handling, warning and fallback forced close, error handling, and final completion make shutdown bounded without changing the intended graceful path.

Problem

When using McpAsyncClient.closeGracefully(), the client executes:

return this.initializer.closeGracefully()
        .then(transport.closeGracefully());

Both initializer.closeGracefully() and transport.closeGracefully() return Mono<Void>.
However, if either of them hangs—for example:

• The underlying transport (HTTP/SSE/WebSocket) never completes
• The server doesn’t respond to shutdown
• A Reactor pipeline remains open (no onComplete)

then the returned Mono never completes, causing the application to hang indefinitely during shutdown.

This results in JVMs or containers that never terminate, blocking CI/CD or production deployments.

Goal

Add a timeout and fallback mechanism to ensure that the client always terminates safely, even when the transport or initializer fails to complete.

Proposed Change

1. Wrap shutdown calls with timeout and fallback

Use Reactor’s timeout(Duration, fallbackMono) operator to guarantee a bounded shutdown duration.

public Mono<Void> closeGracefully() {
    return Mono.defer(() -> {
        long start = logger.isDebugEnabled() ? System.nanoTime() : 0L;
        Duration timeout = Duration.ofSeconds(
                Integer.getInteger("mcp.shutdown.timeout.seconds", 10));

        Mono<Void> graceful = this.initializer.closeGracefully()
            .then(transport.closeGracefully());

        Mono<Void> fallback = Mono.fromRunnable(() -> {
                logger.warn("closeGracefully() timed out after {} seconds; proceeding with best-effort shutdown.", timeout.getSeconds());
                try {
                    this.transport.close(); // force-close if needed
                } catch (Throwable t) {
                    logger.warn("Fallback forced close encountered error: {}", t.toString());
                }
            })
            .then();

        return graceful
            .timeout(timeout, fallback)
            .doOnError(e -> logger.warn("closeGracefully() failed: {}", e.toString()))
            .onErrorResume(e -> Mono.empty()) // ensure app doesn't hang
            .doFinally(sig -> {
                if (logger.isDebugEnabled()) {
                    long durationMs = (System.nanoTime() - start) / 1_000_000;
                    logger.debug("closeGracefully() finished with signal={}, took {} ms", sig, durationMs);
                }
            });
    });
}

Summary

Introduce a timeout and fallback mechanism for closeGracefully() to guarantee reliable termination, preventing hanging shutdowns when the transport or lifecycle initializer fails to complete.