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

Leia primeiro McpAsyncClient.closeGracefully() e, em seguida, inspecione initializer.closeGracefully() e transport.closeGracefully() para entender o comportamento de conclusão deles. Verifique se o tratamento de timeout, o aviso e o fechamento forçado como fallback, o tratamento de erros e a conclusão final tornam o desligamento limitado sem alterar o caminho graceful pretendido.

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.