tower-mcp 0.25.0

//! Client transport trait for raw JSON message I/O.
//!
//! This module defines the [`ClientTransport`] trait, the low-level abstraction
//! for sending and receiving JSON-RPC messages over a transport mechanism.
//!
//! Unlike the previous `ClientTransport` which bundled request/response
//! correlation, this trait provides raw message I/O. The [`McpClient`](super::McpClient)
//! handles correlation, multiplexing, and dispatch in its background task.

use async_trait::async_trait;

use crate::error::Result;
use crate::protocol::RequestId;

/// Low-level transport for sending and receiving raw JSON-RPC messages.
///
/// Implementations handle the physical I/O (stdio, HTTP, WebSocket) while
/// the [`McpClient`](super::McpClient) handles JSON-RPC framing, request/response
/// correlation, and server-initiated request dispatch.
///
/// # Implementing a Custom Transport
///
/// ```rust,ignore
/// use async_trait::async_trait;
/// use tower_mcp::client::ClientTransport;
/// use tower_mcp::error::Result;
///
/// struct MyTransport { /* ... */ }
///
/// #[async_trait]
/// impl ClientTransport for MyTransport {
///     async fn send(&mut self, message: &str) -> Result<()> {
///         // Write message to the transport
///         Ok(())
///     }
///
///     async fn recv(&mut self) -> Result<Option<String>> {
///         // Read next message, None on EOF
///         Ok(None)
///     }
///
///     fn is_connected(&self) -> bool { true }
///
///     async fn close(&mut self) -> Result<()> { Ok(()) }
/// }
/// ```
#[async_trait]
pub trait ClientTransport: Send + 'static {
    /// Send a raw JSON message to the server.
    ///
    /// The message is a complete JSON-RPC request, response, or notification
    /// serialized as a string. The transport adds any necessary framing
    /// (e.g., newline for stdio).
    async fn send(&mut self, message: &str) -> Result<()>;

    /// Receive the next raw JSON message from the server.
    ///
    /// Returns `Ok(Some(json))` for a message, `Ok(None)` for clean EOF/close,
    /// or `Err(...)` for transport errors.
    ///
    /// Both non-message returns end the connection: the client's message loop
    /// stops reading and fails every pending request. Reserve them for the
    /// connection actually being over. A single message that arrives damaged,
    /// such as one the transport cannot decode, is not that; log it, drop it,
    /// and return the next one. [`StdioClientTransport`](super::StdioClientTransport)
    /// documents the reasoning in full.
    async fn recv(&mut self) -> Result<Option<String>>;

    /// Check if the transport is still connected.
    fn is_connected(&self) -> bool;

    /// Close the transport gracefully.
    ///
    /// After calling this, `recv()` should return `Ok(None)`.
    async fn close(&mut self) -> Result<()>;

    /// Reset the transport's session state for re-initialization.
    ///
    /// Called when the server indicates the session has expired. The
    /// transport should clear its session ID, stop any SSE streams,
    /// and prepare for a new `initialize` handshake.
    ///
    /// The default implementation is a no-op (for transports like stdio
    /// that don't have sessions).
    async fn reset_session(&mut self) {}

    /// Terminate the session an `initialize` left behind, without closing
    /// the transport.
    ///
    /// Called when `initialize` fails after the server may already have
    /// issued a session, so the server can release it now instead of waiting
    /// for it to idle out. The transport should end the session on the
    /// server, best effort, and then forget it as [`reset_session`] does.
    ///
    /// The default implementation is a no-op (for transports like stdio
    /// that don't have sessions).
    ///
    /// [`reset_session`]: ClientTransport::reset_session
    async fn end_session(&mut self) {}

    /// Cancel one in-flight request.
    ///
    /// Message-oriented transports such as stdio use the protocol's
    /// `notifications/cancelled` notification. HTTP overrides this method to
    /// close only the response stream belonging to the request, which is the
    /// whole cancellation on the 2026-07-28 protocol; on a 2025-11-25 session
    /// it also sends the notification, since a closed connection does not
    /// cancel there.
    async fn cancel_request(&mut self, request_id: &RequestId) -> Result<()> {
        self.send(
            &serde_json::json!({
                "jsonrpc": "2.0",
                "method": "notifications/cancelled",
                "params": {
                    "requestId": request_id,
                }
            })
            .to_string(),
        )
        .await
    }

    /// Whether this transport supports automatic session recovery.
    ///
    /// When true, the client will attempt to re-initialize and retry
    /// failed operations when the server returns a session expired error.
    ///
    /// Default: `false`.
    fn supports_session_recovery(&self) -> bool {
        false
    }
}