agent_client_protocol/jsonrpc.rs
1//! Core JSON-RPC server support.
2
3use agent_client_protocol_schema::v1::{JsonRpcMessage as VersionedJsonRpcMessage, SessionId};
4
5// Types re-exported from crate root
6use serde::{Deserialize, Serialize};
7use std::any::TypeId;
8use std::collections::HashMap;
9use std::fmt::Debug;
10use std::marker::PhantomData;
11use std::panic::Location;
12use std::pin::pin;
13use std::sync::{
14 Arc, Mutex, Weak,
15 atomic::{AtomicBool, AtomicU8, Ordering},
16};
17use uuid::Uuid;
18
19use futures::FutureExt;
20use futures::channel::{mpsc, oneshot};
21use futures::future::{self, BoxFuture, Either};
22use futures::{AsyncRead, AsyncWrite, StreamExt};
23
24pub(crate) mod close;
25mod dynamic_handler;
26pub(crate) mod handlers;
27mod incoming_actor;
28mod outgoing_actor;
29#[cfg(test)]
30mod prepared_request_tests;
31pub(crate) mod protocol;
32mod protocol_compat;
33mod raw_error;
34pub(crate) mod raw_id;
35pub(crate) mod run;
36mod task_actor;
37mod termination;
38mod transport_actor;
39pub(crate) mod v1_connection;
40#[cfg(feature = "unstable_protocol_v2")]
41pub(crate) mod v2_connection;
42
43use crate::jsonrpc::close::{ChainedClose, CloseCallback};
44pub use crate::jsonrpc::close::{HandleConnectionClose, NullClose};
45use crate::jsonrpc::dynamic_handler::DynamicHandlerMessage;
46pub use crate::jsonrpc::handlers::NullHandler;
47use crate::jsonrpc::handlers::{ChainedHandler, NamedHandler};
48use crate::jsonrpc::handlers::{MessageHandler, NotificationHandler, RequestHandler};
49use crate::jsonrpc::outgoing_actor::{OutgoingMessageTx, send_raw_message};
50use crate::jsonrpc::protocol::HandleId;
51#[cfg(feature = "unstable_protocol_v2")]
52pub use crate::jsonrpc::protocol::V2;
53
54#[cfg(feature = "unstable_mcp_over_acp")]
55use crate::Client;
56pub use crate::jsonrpc::protocol::{Protocol, Raw, V1};
57#[cfg(feature = "unstable_protocol_v2")]
58pub(crate) use crate::jsonrpc::protocol_compat::normalize_newer_v2_initialize_request;
59pub(crate) use crate::jsonrpc::protocol_compat::normalize_v1_initialize_request;
60#[cfg(feature = "unstable_protocol_v2")]
61pub use crate::jsonrpc::protocol_compat::{
62 InitializationVersionMismatch, InitializeOutcome, SelectedInitializeResponse,
63};
64use crate::jsonrpc::protocol_compat::{ProtocolCompat, ProtocolMode};
65pub use crate::jsonrpc::raw_error::{RawJsonRpcError, RawJsonRpcResponse};
66pub use crate::jsonrpc::raw_id::RawJsonRpcId;
67use crate::jsonrpc::run::SpawnedRun;
68use crate::jsonrpc::run::{ChainRun, NullRun, RunWithConnectionTo};
69use crate::jsonrpc::task_actor::{Task, TaskTx};
70pub use crate::jsonrpc::termination::{
71 CONNECTION_TERMINATED_REASON, ConnectionTermination, is_connection_terminated,
72};
73use crate::jsonrpc::termination::{
74 TerminationSource, TerminationSources, connection_terminated_error,
75};
76#[cfg(feature = "unstable_mcp_over_acp")]
77use crate::mcp_server::McpServer;
78use crate::role::{HasPeer, RemoteStyle, Role};
79use crate::{Agent, ConnectTo, RoleId};
80
81/// One valid JSON-RPC message carried inside a [`TransportFrame`].
82///
83/// Raw messages are the same for every ACP protocol version: IDs are
84/// [`RawJsonRpcId`]s, and method params and response errors are not
85/// interpreted at the transport boundary.
86///
87/// Serializing adds the `"jsonrpc": "2.0"` member, and deserializing requires
88/// it. Requests and notifications keep only `id`, `method` and `params`:
89/// other members of the envelope are dropped. Error responses keep unknown
90/// members of the error object in [`RawJsonRpcError::extra`].
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub enum RawJsonRpcMessage {
93 /// A JSON-RPC request with an id and expected response.
94 Request(RawJsonRpcRequest),
95 /// A JSON-RPC notification without a response.
96 Notification(RawJsonRpcNotification),
97 /// A JSON-RPC response to a prior request.
98 Response(RawJsonRpcResponse),
99}
100
101/// A JSON-RPC frame exchanged between protocol components and transports.
102///
103/// A frame is one JSON-RPC wire value. Malformed wire input, including a
104/// JSON-RPC batch array, which the SDK does not support, is represented
105/// explicitly; transport failures are reported by the future that drives the
106/// transport rather than sent through a [`Channel`].
107#[derive(Clone, Debug)]
108#[non_exhaustive]
109pub enum TransportFrame {
110 /// One valid JSON-RPC message.
111 Single(RawJsonRpcMessage),
112 /// One malformed or invalid wire value retained for relays.
113 Malformed {
114 /// The original wire representation.
115 raw: String,
116 /// The JSON-RPC error associated with the malformed value.
117 error: crate::Error,
118 },
119}
120
121pub(crate) fn is_response_only_shape(value: &serde_json::Value) -> bool {
122 value.as_object().is_some_and(|object| {
123 !object.contains_key("method")
124 && (object.contains_key("result") || object.contains_key("error"))
125 })
126}
127
128pub(crate) fn raw_is_response_only_shape(raw: &str) -> bool {
129 serde_json::from_str(raw).is_ok_and(|value| is_response_only_shape(&value))
130}
131
132impl TransportFrame {
133 fn inspect_messages(
134 &self,
135 observer: &mut impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error>,
136 ) -> Result<(), crate::Error> {
137 match self {
138 Self::Single(message) => observer(message),
139 Self::Malformed { .. } => Ok(()),
140 }
141 }
142}
143
144/// A JSON-RPC request with uninterpreted params.
145///
146/// This is the request without the `jsonrpc` member, which
147/// [`RawJsonRpcMessage`] adds and checks. Other members of the request object
148/// are not kept: a relay that parses and re-serializes a request drops them.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150pub struct RawJsonRpcRequest {
151 /// The ID the response must carry.
152 pub id: RawJsonRpcId,
153 /// The method to invoke.
154 pub method: Arc<str>,
155 /// The params, if any. `None` omits the member.
156 #[serde(default, skip_serializing_if = "Option::is_none")]
157 pub params: Option<RawJsonRpcParams>,
158}
159
160/// A JSON-RPC notification with uninterpreted params.
161///
162/// This is the notification without the `jsonrpc` member, which
163/// [`RawJsonRpcMessage`] adds and checks. Other members of the notification
164/// object are not kept: a relay that parses and re-serializes a notification
165/// drops them.
166#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
167pub struct RawJsonRpcNotification {
168 /// The notification method.
169 pub method: Arc<str>,
170 /// The params, if any. `None` omits the member.
171 #[serde(default, skip_serializing_if = "Option::is_none")]
172 pub params: Option<RawJsonRpcParams>,
173}
174
175impl From<RawJsonRpcRequest> for RawJsonRpcMessage {
176 fn from(request: RawJsonRpcRequest) -> Self {
177 Self::Request(request)
178 }
179}
180
181impl From<RawJsonRpcNotification> for RawJsonRpcMessage {
182 fn from(notification: RawJsonRpcNotification) -> Self {
183 Self::Notification(notification)
184 }
185}
186
187impl From<RawJsonRpcResponse> for RawJsonRpcMessage {
188 fn from(response: RawJsonRpcResponse) -> Self {
189 Self::Response(response)
190 }
191}
192
193/// Raw JSON-RPC request or notification parameters.
194///
195/// JSON-RPC params, when present, must be either an array or an object.
196#[derive(Debug, Clone, PartialEq, Eq)]
197pub enum RawJsonRpcParams {
198 /// Positional JSON-RPC params.
199 Array(Vec<serde_json::Value>),
200 /// Named JSON-RPC params.
201 Object(serde_json::Map<String, serde_json::Value>),
202}
203
204impl RawJsonRpcParams {
205 /// Convert a JSON value into JSON-RPC params. JSON `null` means no params.
206 ///
207 /// # Errors
208 ///
209 /// Returns Invalid params (`-32602`) for strings, numbers, and booleans.
210 pub fn from_value(value: serde_json::Value) -> Result<Option<Self>, crate::Error> {
211 match value {
212 serde_json::Value::Null => Ok(None),
213 serde_json::Value::Array(array) => Ok(Some(Self::Array(array))),
214 serde_json::Value::Object(object) => Ok(Some(Self::Object(object))),
215 _ => {
216 Err(crate::Error::invalid_params()
217 .data("JSON-RPC params must be an object or array"))
218 }
219 }
220 }
221
222 /// Convert params back into a JSON value.
223 #[must_use]
224 pub fn into_value(self) -> serde_json::Value {
225 match self {
226 Self::Array(array) => serde_json::Value::Array(array),
227 Self::Object(object) => serde_json::Value::Object(object),
228 }
229 }
230}
231
232impl Serialize for RawJsonRpcParams {
233 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
234 where
235 S: serde::Serializer,
236 {
237 match self {
238 Self::Array(array) => array.serialize(serializer),
239 Self::Object(object) => object.serialize(serializer),
240 }
241 }
242}
243
244impl<'de> Deserialize<'de> for RawJsonRpcParams {
245 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
246 where
247 D: serde::Deserializer<'de>,
248 {
249 let value = serde_json::Value::deserialize(deserializer)?;
250 match value {
251 serde_json::Value::Array(array) => Ok(Self::Array(array)),
252 serde_json::Value::Object(object) => Ok(Self::Object(object)),
253 _ => Err(serde::de::Error::custom(
254 "JSON-RPC params must be an object or array",
255 )),
256 }
257 }
258}
259
260impl RawJsonRpcMessage {
261 /// Build a raw JSON-RPC request message.
262 ///
263 /// # Errors
264 ///
265 /// Returns Invalid params (`-32602`) if `params` is not an object, an array, or `null`.
266 pub fn request(
267 method: String,
268 params: serde_json::Value,
269 id: impl Into<RawJsonRpcId>,
270 ) -> Result<Self, crate::Error> {
271 Ok(Self::Request(RawJsonRpcRequest {
272 id: id.into(),
273 method: Arc::from(method),
274 params: RawJsonRpcParams::from_value(params)?,
275 }))
276 }
277
278 /// Build a raw JSON-RPC notification message.
279 ///
280 /// # Errors
281 ///
282 /// Returns Invalid params (`-32602`) if `params` is not an object, an array, or `null`.
283 pub fn notification(method: String, params: serde_json::Value) -> Result<Self, crate::Error> {
284 Ok(Self::Notification(RawJsonRpcNotification {
285 method: Arc::from(method),
286 params: RawJsonRpcParams::from_value(params)?,
287 }))
288 }
289
290 /// Build a JSON-RPC response from an ACP result.
291 ///
292 /// For other protocols, construct [`RawJsonRpcResponse`] directly so error
293 /// codes and fields are not interpreted as ACP.
294 #[must_use]
295 pub fn response(
296 id: impl Into<RawJsonRpcId>,
297 response: Result<serde_json::Value, crate::Error>,
298 ) -> Self {
299 Self::Response(RawJsonRpcResponse::new(
300 id,
301 response.map_err(|error| Box::new(error.into())),
302 ))
303 }
304
305 /// The response id, if this is a response.
306 #[must_use]
307 pub fn response_id(&self) -> Option<&RawJsonRpcId> {
308 match self {
309 Self::Response(
310 RawJsonRpcResponse::Result { id, .. } | RawJsonRpcResponse::Error { id, .. },
311 ) => Some(id),
312 Self::Request(_) | Self::Notification(_) => None,
313 }
314 }
315}
316
317impl Serialize for RawJsonRpcMessage {
318 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
319 where
320 S: serde::Serializer,
321 {
322 match self {
323 Self::Request(request) => {
324 VersionedJsonRpcMessage::wrap(request.clone()).serialize(serializer)
325 }
326 Self::Notification(notification) => {
327 VersionedJsonRpcMessage::wrap(notification.clone()).serialize(serializer)
328 }
329 Self::Response(response) => {
330 VersionedJsonRpcMessage::wrap(response.clone()).serialize(serializer)
331 }
332 }
333 }
334}
335
336impl<'de> Deserialize<'de> for RawJsonRpcMessage {
337 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
338 where
339 D: serde::Deserializer<'de>,
340 {
341 let value = serde_json::Value::deserialize(deserializer)?;
342 let Some(object) = value.as_object() else {
343 return Err(serde::de::Error::custom("invalid JSON-RPC message"));
344 };
345
346 let has_method = object.contains_key("method");
347 let has_id = object.contains_key("id");
348 let has_result = object.contains_key("result");
349 let has_error = object.contains_key("error");
350
351 if has_method && !has_result && !has_error {
352 if has_id {
353 let request =
354 serde_json::from_value::<VersionedJsonRpcMessage<RawJsonRpcRequest>>(value)
355 .map_err(serde::de::Error::custom)?
356 .into_inner();
357 Ok(Self::Request(request))
358 } else {
359 let notification = serde_json::from_value::<
360 VersionedJsonRpcMessage<RawJsonRpcNotification>,
361 >(value)
362 .map_err(serde::de::Error::custom)?
363 .into_inner();
364 Ok(Self::Notification(notification))
365 }
366 } else if !has_method && has_id && has_result != has_error {
367 let response =
368 serde_json::from_value::<VersionedJsonRpcMessage<RawJsonRpcResponse>>(value)
369 .map_err(serde::de::Error::custom)?
370 .into_inner();
371 Ok(Self::Response(response))
372 } else {
373 Err(serde::de::Error::custom("invalid JSON-RPC message"))
374 }
375 }
376}
377
378fn params_from_transport(params: Option<RawJsonRpcParams>) -> serde_json::Value {
379 params.map_or(serde_json::Value::Null, RawJsonRpcParams::into_value)
380}
381
382/// Handlers process incoming JSON-RPC messages on a connection.
383///
384/// When messages arrive, they flow through a chain of handlers. Each handler can
385/// either **claim** the message (handle it) or **decline** it (pass to the next handler).
386///
387/// # Message Flow
388///
389/// Messages flow through three layers of handlers in order:
390///
391/// ```text
392/// ┌─────────────────────────────────────────────────────────────────┐
393/// │ Incoming Message │
394/// └─────────────────────────────────────────────────────────────────┘
395/// │
396/// ▼
397/// ┌─────────────────────────────────────────────────────────────────┐
398/// │ 1. User Handlers (registered via on_receive_request, etc.) │
399/// │ - Tried in registration order │
400/// │ - First handler to return Handled::Yes claims the message │
401/// └─────────────────────────────────────────────────────────────────┘
402/// │ Handled::No
403/// ▼
404/// ┌─────────────────────────────────────────────────────────────────┐
405/// │ 2. Dynamic Handlers (added at runtime) │
406/// │ - Used for session-specific message handling │
407/// │ - Added via ConnectionTo::add_dynamic_handler │
408/// └─────────────────────────────────────────────────────────────────┘
409/// │ Handled::No
410/// ▼
411/// ┌─────────────────────────────────────────────────────────────────┐
412/// │ 3. Role Default Handler │
413/// │ - Fallback based on the connection's Role │
414/// │ - Handles protocol-level messages (e.g., proxy forwarding) │
415/// └─────────────────────────────────────────────────────────────────┘
416/// │ Handled::No
417/// ▼
418/// ┌─────────────────────────────────────────────────────────────────┐
419/// │ Unhandled: requests error, notifications ignored │
420/// └─────────────────────────────────────────────────────────────────┘
421/// ```
422///
423/// # The `Handled` Return Value
424///
425/// Each handler returns [`Handled`] to indicate whether it processed the message:
426///
427/// - **`Handled::Yes`** - Message was handled. No further handlers are invoked.
428/// - **`Handled::No { message, retry }`** - Message was not handled. The message
429/// (possibly modified) is passed to the next handler in the chain.
430///
431/// For convenience, handlers can return `()` which is equivalent to `Handled::Yes`.
432///
433/// # The Retry Mechanism
434///
435/// The `retry` flag in `Handled::No` controls what happens when no handler claims a message:
436///
437/// - **`retry: false`** (default) - Send a "method not found" error
438/// response immediately for requests, or ignore notifications.
439/// - **`retry: true`** - Queue the message and retry it when new dynamic handlers are added.
440///
441/// This mechanism exists because of a timing issue with sessions: when a `session/new`
442/// response is being processed, the dynamic handler for that session hasn't been registered
443/// yet, but `session/update` notifications for that session may already be arriving.
444/// By setting `retry: true`, these early notifications are queued until the session's
445/// dynamic handler is added.
446///
447/// The queue holds at most 1024 messages per connection. Queuing one more gives up on the
448/// oldest: a request gets the "method not found" error, a notification is dropped with a
449/// log, and a response goes to its awaiter.
450///
451/// On v1 and unguarded connections, a client's role also retries unhandled messages from
452/// the agent that carry a `sessionId`. Its notifications are queued as above. Its requests
453/// are queued only while a dropped dynamic handler's removal is still pending, which covers
454/// a session handler being replaced, and are answered with "method not found" once no such
455/// removal is left. Any other unhandled session request is answered right away, so the
456/// agent never waits for a handler that nobody registers.
457///
458/// # Handler Registration
459///
460/// Most users register handlers using the builder methods on [`Builder`]:
461///
462/// ```
463/// # use agent_client_protocol::{Agent, Client, ConnectTo};
464/// # use agent_client_protocol::v1::schema::{AgentCapabilities, InitializeRequest, InitializeResponse};
465/// # use agent_client_protocol_test::StatusUpdate;
466/// # async fn example(transport: impl ConnectTo<Agent>) -> Result<(), agent_client_protocol::Error> {
467/// Agent.v1()
468/// .on_receive_request(async |req: InitializeRequest, responder, cx| {
469/// responder.respond(
470/// InitializeResponse::new(req.protocol_version)
471/// .agent_capabilities(AgentCapabilities::new()),
472/// )
473/// }, agent_client_protocol::on_receive_request!())
474/// .on_receive_notification(async |notif: StatusUpdate, cx| {
475/// // Process notification
476/// Ok(())
477/// }, agent_client_protocol::on_receive_notification!())
478/// .connect_to(transport)
479/// .await?;
480/// # Ok(())
481/// # }
482/// ```
483///
484/// The type parameter on the closure determines which messages are dispatched to it.
485/// Messages that don't match the type are automatically passed to the next handler.
486///
487/// # Implementing Custom Handlers
488///
489/// For advanced use cases, you can implement [`HandleDispatchFrom`] directly:
490///
491/// ```no_run
492/// use agent_client_protocol::{
493/// Client, ConnectionTo, Dispatch, Error, HandleDispatchFrom, Handled,
494/// };
495///
496/// struct MyHandler;
497///
498/// impl HandleDispatchFrom<Client> for MyHandler {
499/// async fn handle_dispatch_from(
500/// &mut self,
501/// message: Dispatch,
502/// _connection: ConnectionTo<Client>,
503/// ) -> Result<Handled<Dispatch>, Error> {
504/// if message.method() == "my/custom/method" {
505/// // Handle it
506/// Ok(Handled::Yes)
507/// } else {
508/// // Pass to next handler
509/// Ok(Handled::No { message, retry: false })
510/// }
511/// }
512///
513/// fn describe_chain(&self) -> impl std::fmt::Debug {
514/// "MyHandler"
515/// }
516/// }
517/// ```
518///
519/// # Important: Handlers Must Not Block
520///
521/// The connection processes messages on a single async task. While a handler is running,
522/// no other messages can be processed. For expensive operations, use [`ConnectionTo::spawn`]
523/// to run work concurrently:
524///
525/// ```
526/// # use agent_client_protocol::{Client, Agent, ConnectTo};
527/// # use agent_client_protocol_test::{expensive_operation, ProcessComplete};
528/// # async fn example(transport: impl ConnectTo<Client>) -> Result<(), agent_client_protocol::Error> {
529/// # Client.v1().connect_with(transport, async |cx| {
530/// cx.spawn({
531/// let connection = cx.clone();
532/// async move {
533/// let result = expensive_operation("data").await?;
534/// connection.send_notification(ProcessComplete { result })?;
535/// Ok(())
536/// }
537/// })?;
538/// # Ok(())
539/// # }).await?;
540/// # Ok(())
541/// # }
542/// ```
543#[allow(async_fn_in_trait)]
544/// A handler for incoming JSON-RPC messages.
545///
546/// This trait is implemented by types that can process incoming messages on a connection.
547/// Handlers are registered with a [`Builder`] and are called in order until
548/// one claims the message.
549///
550/// The type parameter is the counterpart role that messages arrive from and
551/// that the supplied [`ConnectionTo`] addresses. An agent handler therefore
552/// implements `HandleDispatchFrom<Client>`, while a client handler implements
553/// `HandleDispatchFrom<Agent>`.
554pub trait HandleDispatchFrom<Counterpart: Role>: Send {
555 /// Attempt to claim an incoming dispatch (request, notification, or response).
556 ///
557 /// # Important: do not block
558 ///
559 /// The server will not process new messages until this handler returns.
560 /// You should avoid blocking in this callback unless you wish to block the server (e.g., for rate limiting).
561 /// The recommended approach to manage expensive operations is to the [`ConnectionTo::spawn`] method available on the message context.
562 ///
563 /// # Parameters
564 ///
565 /// * `message` - The incoming message to handle.
566 /// * `connection` - The connection, used to send messages and access connection state.
567 ///
568 /// # Returns
569 ///
570 /// * `Ok(Handled::Yes)` if the message was claimed. It will not be propagated further.
571 /// * `Ok(Handled::No(message))` if not; the (possibly changed) message will be passed to the remaining handlers.
572 /// * `Err` if processing fails. Requests receive an Error Response, response
573 /// errors are routed to the local request awaiter, and notification errors
574 /// are logged without a wire reply.
575 fn handle_dispatch_from(
576 &mut self,
577 message: Dispatch,
578 connection: ConnectionTo<Counterpart>,
579 ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send;
580
581 /// Returns a debug description of the registered handlers for diagnostics.
582 fn describe_chain(&self) -> impl std::fmt::Debug;
583}
584
585impl<Counterpart: Role, H> HandleDispatchFrom<Counterpart> for &mut H
586where
587 H: HandleDispatchFrom<Counterpart>,
588{
589 fn handle_dispatch_from(
590 &mut self,
591 message: Dispatch,
592 cx: ConnectionTo<Counterpart>,
593 ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send {
594 H::handle_dispatch_from(self, message, cx)
595 }
596
597 fn describe_chain(&self) -> impl std::fmt::Debug {
598 H::describe_chain(self)
599 }
600}
601
602/// A JSON-RPC connection that can act as either a server, client, or both.
603///
604/// [`Builder`] provides a builder-style API for creating JSON-RPC servers and clients.
605/// You start with a versioned entry point such as `Client.v1()` or `Client.v2()`, then add message
606/// handlers, and finally drive the connection with either [`connect_to`](Builder::connect_to)
607/// or [`connect_with`](Builder::connect_with), providing a component implementation
608/// (e.g., [`ByteStreams`] for byte streams).
609///
610/// # JSON-RPC Primer
611///
612/// JSON-RPC 2.0 has two fundamental message types:
613///
614/// * **Requests** - Messages that expect a response. They have an `id` field that gets
615/// echoed back in the response so the sender can correlate them.
616/// * **Notifications** - Fire-and-forget messages with no `id` field. The sender doesn't
617/// expect or receive a response.
618///
619/// # Type-Driven Message Dispatch
620///
621/// The handler registration methods use Rust's type system to determine which messages
622/// to handle. The type parameter you provide controls what gets dispatched to your handler:
623///
624/// ## Single Message Types
625///
626/// The simplest case - handle one specific message type:
627///
628/// ```no_run
629/// # use agent_client_protocol_test::*;
630/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, SessionNotification};
631/// # async fn example() -> Result<(), agent_client_protocol::Error> {
632/// # let connection = mock_connection();
633/// connection
634/// .on_receive_request(async |req: InitializeRequest, responder, cx| {
635/// // Handle only InitializeRequest messages
636/// responder.respond(InitializeResponse::make())
637/// }, agent_client_protocol::on_receive_request!())
638/// .on_receive_notification(async |notif: SessionNotification, cx| {
639/// // Handle only SessionUpdate notifications
640/// Ok(())
641/// }, agent_client_protocol::on_receive_notification!())
642/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
643/// # Ok(())
644/// # }
645/// ```
646///
647/// ## Enum Message Types
648///
649/// You can also handle multiple related messages with a single handler by defining an enum
650/// that implements the appropriate trait ([`JsonRpcRequest`] or [`JsonRpcNotification`]):
651///
652/// ```no_run
653/// # use agent_client_protocol_test::*;
654/// # use agent_client_protocol::{JsonRpcRequest, JsonRpcMessage, UntypedMessage};
655/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse};
656/// # async fn example() -> Result<(), agent_client_protocol::Error> {
657/// # let connection = mock_connection();
658/// // Define an enum for multiple request types
659/// #[derive(Debug, Clone)]
660/// enum MyRequests {
661/// Initialize(InitializeRequest),
662/// Prompt(PromptRequest),
663/// }
664///
665/// // Implement JsonRpcRequest for your enum
666/// # impl JsonRpcMessage for MyRequests {
667/// # fn matches_method(_method: &str) -> bool { false }
668/// # fn method(&self) -> &str { "myRequests" }
669/// # fn to_untyped_message(&self) -> Result<UntypedMessage, agent_client_protocol::Error> { todo!() }
670/// # fn parse_message(_method: &str, _params: &serde_json::Value) -> Result<Self, agent_client_protocol::Error> { Err(agent_client_protocol::Error::method_not_found()) }
671/// # }
672/// impl JsonRpcRequest for MyRequests { type Response = serde_json::Value; }
673///
674/// // Handle all variants in one place
675/// connection.on_receive_request(async |req: MyRequests, responder, cx| {
676/// match req {
677/// MyRequests::Initialize(init) => { responder.respond(serde_json::json!({})) }
678/// MyRequests::Prompt(prompt) => { responder.respond(serde_json::json!({})) }
679/// }
680/// }, agent_client_protocol::on_receive_request!())
681/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
682/// # Ok(())
683/// # }
684/// ```
685///
686/// ## Mixed Message Types
687///
688/// To handle requests, notifications, and responses in one callback, use
689/// [`on_receive_dispatch`](Self::on_receive_dispatch):
690///
691/// ```no_run
692/// # use agent_client_protocol_test::*;
693/// # use agent_client_protocol::v1::Dispatch;
694/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, SessionNotification};
695/// # async fn example() -> Result<(), agent_client_protocol::Error> {
696/// # let connection = mock_connection();
697/// // on_receive_dispatch receives requests, notifications, and responses
698/// connection.on_receive_dispatch(async |msg: Dispatch<InitializeRequest, SessionNotification>, _cx| {
699/// match msg {
700/// Dispatch::Request(req, responder) => {
701/// responder.respond(InitializeResponse::make())
702/// }
703/// Dispatch::Notification(notif) => {
704/// Ok(())
705/// }
706/// Dispatch::Response(result, router) => {
707/// // Forward response to its destination
708/// router.route_with_result(result)
709/// }
710/// }
711/// }, agent_client_protocol::on_receive_dispatch!())
712/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
713/// # Ok(())
714/// # }
715/// ```
716///
717/// # Handler Registration
718///
719/// Register handlers using these methods (listed from most common to most flexible):
720///
721/// * [`on_receive_request`](Self::on_receive_request) - Handle JSON-RPC requests (messages expecting responses)
722/// * [`on_receive_notification`](Self::on_receive_notification) - Handle JSON-RPC notifications (fire-and-forget)
723/// * [`on_receive_dispatch`](Self::on_receive_dispatch) - Handle requests, notifications, and responses in one callback
724/// * [`with_handler`](Self::with_handler) - Low-level primitive for maximum flexibility
725///
726/// ## Handler Ordering
727///
728/// Handlers are tried in the order you register them. The first handler that claims a message
729/// (by matching its type) will process it. Subsequent handlers won't see that message:
730///
731/// ```no_run
732/// # use agent_client_protocol_test::*;
733/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse};
734/// # async fn example() -> Result<(), agent_client_protocol::Error> {
735/// # let connection = mock_connection();
736/// connection
737/// .on_receive_request(async |req: InitializeRequest, responder, cx| {
738/// // This runs first for InitializeRequest
739/// responder.respond(InitializeResponse::make())
740/// }, agent_client_protocol::on_receive_request!())
741/// .on_receive_request(async |req: PromptRequest, responder, cx| {
742/// // This runs first for PromptRequest
743/// responder.respond(PromptResponse::make())
744/// }, agent_client_protocol::on_receive_request!())
745/// // Unknown requests receive Method not found automatically; unhandled
746/// // notifications are ignored.
747/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
748/// # Ok(())
749/// # }
750/// ```
751///
752/// # Event Loop and Concurrency
753///
754/// Understanding the event loop is critical for writing correct handlers.
755///
756/// ## The Event Loop
757///
758/// [`Builder`] runs all handler callbacks on a single async task - the event loop.
759/// While a handler is running, **the server cannot receive new messages**. This means
760/// any blocking or expensive work in your handlers will stall the entire connection.
761///
762/// To avoid blocking the event loop, use [`ConnectionTo::spawn`] to offload serious
763/// work to concurrent tasks:
764///
765/// ```no_run
766/// # use agent_client_protocol_test::*;
767/// # async fn example() -> Result<(), agent_client_protocol::Error> {
768/// # let connection = mock_connection();
769/// connection.on_receive_request(async |req: AnalyzeRequest, responder, cx| {
770/// // Clone cx for the spawned task
771/// cx.spawn({
772/// let connection = cx.clone();
773/// async move {
774/// let result = expensive_analysis(&req.data).await?;
775/// connection.send_notification(AnalysisComplete { result })?;
776/// Ok(())
777/// }
778/// })?;
779///
780/// // Respond immediately without blocking
781/// responder.respond(AnalysisStarted { job_id: 42 })
782/// }, agent_client_protocol::on_receive_request!())
783/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
784/// # Ok(())
785/// # }
786/// ```
787///
788/// Note that the entire connection runs within one async task, so parallelism must be
789/// managed explicitly using [`spawn`](ConnectionTo::spawn).
790///
791/// ## The Connection Context
792///
793/// Handler callbacks receive a context object (`cx`) for interacting with the connection:
794///
795/// * **For request handlers** - [`Responder<R>`] provides [`respond`](Responder::respond)
796/// to send the response, plus methods to send other messages
797/// * **For notification handlers** - [`ConnectionTo`] provides methods to send messages
798/// and spawn tasks
799///
800/// Both context types support:
801/// * [`send_request`](ConnectionTo::send_request) - Send requests to the other side
802/// * [`send_notification`](ConnectionTo::send_notification) - Send notifications
803/// * [`spawn`](ConnectionTo::spawn) - Run tasks concurrently without blocking the event loop
804///
805/// The [`SentRequest`] returned by `send_request` provides methods like
806/// [`on_receiving_result`](SentRequest::on_receiving_result) that help you
807/// avoid accidentally blocking the event loop while waiting for responses.
808///
809/// # Driving the Connection
810///
811/// After adding handlers, you must drive the connection using one of two modes:
812///
813/// ## Server Mode: `connect_to()`
814///
815/// Use [`connect_to`](Self::connect_to) when you only need to respond to incoming messages:
816///
817/// ```no_run
818/// # use agent_client_protocol_test::*;
819/// # async fn example() -> Result<(), agent_client_protocol::Error> {
820/// # let connection = mock_connection();
821/// connection
822/// .on_receive_request(async |req: MyRequest, responder, cx| {
823/// responder.respond(MyResponse { status: "ok".into() })
824/// }, agent_client_protocol::on_receive_request!())
825/// .connect_to(MockTransport) // Runs until connection closes or error occurs
826/// .await?;
827/// # Ok(())
828/// # }
829/// ```
830///
831/// The connection will process incoming messages and invoke your handlers until the
832/// connection is closed or an error occurs.
833///
834/// ## Client Mode: `connect_with()`
835///
836/// Use [`connect_with`](Self::connect_with) when you need to both handle incoming messages
837/// AND send your own requests/notifications:
838///
839/// ```no_run
840/// # use agent_client_protocol_test::*;
841/// # use agent_client_protocol::v1::schema::InitializeRequest;
842/// # async fn example() -> Result<(), agent_client_protocol::Error> {
843/// # let connection = mock_connection();
844/// connection
845/// .on_receive_request(async |req: MyRequest, responder, cx| {
846/// responder.respond(MyResponse { status: "ok".into() })
847/// }, agent_client_protocol::on_receive_request!())
848/// .connect_with(MockTransport, async |cx| {
849/// // You can send requests to the other side
850/// let response = cx.send_request(InitializeRequest::make())
851/// .block_task()
852/// .await?;
853///
854/// // And send notifications
855/// cx.send_notification(StatusUpdate { message: "ready".into() })?;
856///
857/// Ok(())
858/// })
859/// .await?;
860/// # Ok(())
861/// # }
862/// ```
863///
864/// The connection will serve incoming messages in the background while your client closure
865/// runs. When the closure returns, the connection shuts down.
866///
867/// # Example: Complete Agent
868///
869/// ```no_run
870/// # use agent_client_protocol::UntypedRole;
871/// # use agent_client_protocol::{Builder};
872/// # use agent_client_protocol::v1::schema::{InitializeRequest, InitializeResponse, PromptRequest, PromptResponse, SessionNotification};
873/// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
874///
875/// UntypedRole.builder()
876/// .name("my-agent") // Optional: for debugging logs
877/// .on_receive_request(async |init: InitializeRequest, responder, cx| {
878/// let response: InitializeResponse = todo!();
879/// responder.respond(response)
880/// }, agent_client_protocol::on_receive_request!())
881/// .on_receive_request(async |prompt: PromptRequest, responder, cx| {
882/// // You can send notifications while processing a request
883/// let notif: SessionNotification = todo!();
884/// cx.send_notification(notif)?;
885///
886/// // Then respond to the request
887/// let response: PromptResponse = todo!();
888/// responder.respond(response)
889/// }, agent_client_protocol::on_receive_request!())
890/// .connect_to(transport)
891/// .await?;
892/// # Ok(())
893/// # }
894/// ```
895///
896/// # Protocol version
897///
898/// `P` is the [`Protocol`] marker of the request handles that typed handlers
899/// receive and of the connection type callbacks receive. `Client.v1()`,
900/// `Agent.v1()` and `Proxy.v1()` return [`V1`] builders
901/// ([`v1::Builder`](crate::v1::Builder)), the v2 builders use `V2`
902/// (`v2::Builder`), and [`Builder::new`] and other roles' builders use the
903/// version-neutral default, [`Raw`], with no protocol-version guard.
904#[must_use]
905#[derive(Debug)]
906pub struct Builder<Host: Role, Handler = NullHandler, Runner = NullRun, Close = NullClose, P = Raw>
907where
908 Handler: HandleDispatchFrom<Host::Counterpart>,
909 Runner: RunWithConnectionTo<Host::Counterpart>,
910 Close: HandleConnectionClose<Host::Counterpart>,
911 P: Protocol,
912{
913 /// My role.
914 host: Host,
915
916 /// Name of the connection, used in tracing logs.
917 name: Option<String>,
918
919 /// Handler for incoming messages.
920 handler: Handler,
921
922 /// Runner for background connection tasks.
923 runner: Runner,
924
925 /// Protocol version mode for the public API and wire compatibility layer.
926 protocol_mode: ProtocolMode,
927
928 /// Handler run when the incoming transport reaches clean EOF.
929 on_close: Close,
930
931 /// The protocol version of the callbacks: their connection type and the
932 /// request handles they receive.
933 protocol: PhantomData<fn() -> P>,
934}
935
936impl<Host: Role> Builder<Host, NullHandler, NullRun, NullClose> {
937 /// Create a new version-neutral connection builder for the given role.
938 /// This type follows a builder pattern; use other methods to configure and then invoke
939 /// [`Self::connect_to`] (to use as a server) or [`Self::connect_with`] to use as a client.
940 ///
941 /// The builder is raw: it applies no ACP protocol-version guard, even for
942 /// [`Client`](crate::Client), [`Agent`] and [`Proxy`](crate::Proxy), and
943 /// its callbacks receive [`Raw`] request handles. Messages are sent and received exactly as
944 /// handlers produce them. This suits protocol-routing infrastructure that
945 /// validates `initialize` itself and forwarders such as the conductor,
946 /// which leave version validation to the endpoints.
947 ///
948 /// Applications should use [`Client.v1()`](crate::Client::v1),
949 /// [`Agent.v1()`](crate::Agent::v1) or [`Proxy.v1()`](crate::Proxy::v1)
950 /// (or the `v2()` entry points with the `unstable_protocol_v2` feature),
951 /// which apply that version's wire guard.
952 pub fn new(role: Host) -> Self {
953 Self {
954 host: role,
955 name: None,
956 handler: NullHandler,
957 runner: NullRun,
958 protocol_mode: ProtocolMode::disabled(),
959 on_close: NullClose,
960 protocol: PhantomData,
961 }
962 }
963}
964
965impl<Host: Role, Handler> Builder<Host, Handler, NullRun, NullClose>
966where
967 Handler: HandleDispatchFrom<Host::Counterpart>,
968{
969 /// Create a new connection builder with the given handler.
970 ///
971 /// Like [`Builder::new`], the builder applies no protocol-version guard.
972 pub fn new_with(role: Host, handler: Handler) -> Self {
973 Self {
974 host: role,
975 name: None,
976 handler,
977 runner: NullRun,
978 protocol_mode: ProtocolMode::disabled(),
979 on_close: NullClose,
980 protocol: PhantomData,
981 }
982 }
983}
984
985impl<
986 Host: Role,
987 Handler: HandleDispatchFrom<Host::Counterpart>,
988 Runner: RunWithConnectionTo<Host::Counterpart>,
989 Close: HandleConnectionClose<Host::Counterpart>,
990 P: Protocol,
991> Builder<Host, Handler, Runner, Close, P>
992{
993 /// Set the "name" of this connection -- used only for debugging logs.
994 pub fn name(mut self, name: impl ToString) -> Self {
995 self.name = Some(name.to_string());
996 self
997 }
998
999 /// The same builder with callbacks for protocol `Q`. Handlers already
1000 /// registered keep their own protocol.
1001 pub(crate) fn into_protocol<Q: Protocol>(self) -> Builder<Host, Handler, Runner, Close, Q> {
1002 Builder {
1003 host: self.host,
1004 name: self.name,
1005 handler: self.handler,
1006 runner: self.runner,
1007 protocol_mode: self.protocol_mode,
1008 on_close: self.on_close,
1009 protocol: PhantomData,
1010 }
1011 }
1012
1013 #[cfg(feature = "unstable_protocol_v2")]
1014 pub(crate) fn v2_agent(self) -> Builder<Host, Handler, Runner, Close, V2> {
1015 let mut builder = self.into_protocol();
1016 builder.protocol_mode = ProtocolMode::v2_agent();
1017 builder
1018 }
1019
1020 #[cfg(feature = "unstable_protocol_v2")]
1021 pub(crate) fn v2_client(self) -> Builder<Host, Handler, Runner, Close, V2> {
1022 let mut builder = self.into_protocol();
1023 builder.protocol_mode = ProtocolMode::v2_client();
1024 builder
1025 }
1026
1027 #[cfg(feature = "unstable_protocol_v2")]
1028 pub(crate) fn v2_proxy(self) -> Builder<Host, Handler, Runner, Close, V2> {
1029 let mut builder = self.into_protocol();
1030 builder.protocol_mode = ProtocolMode::v2_proxy();
1031 builder
1032 }
1033
1034 pub(crate) fn v1_agent(self) -> Builder<Host, Handler, Runner, Close, V1> {
1035 let mut builder = self.into_protocol();
1036 builder.protocol_mode = ProtocolMode::v1_agent();
1037 builder
1038 }
1039
1040 pub(crate) fn v1_client(self) -> Builder<Host, Handler, Runner, Close, V1> {
1041 let mut builder = self.into_protocol();
1042 builder.protocol_mode = ProtocolMode::v1_client();
1043 builder
1044 }
1045
1046 pub(crate) fn v1_proxy(self) -> Builder<Host, Handler, Runner, Close, V1> {
1047 let mut builder = self.into_protocol();
1048 builder.protocol_mode = ProtocolMode::v1_proxy();
1049 builder
1050 }
1051
1052 /// Record a request handler of type `Req`.
1053 ///
1054 /// A v1 agent that handles `initialize` itself rejects other requests
1055 /// until initialization completes, as v1 agents SHOULD. Agents without
1056 /// such a handler, including those with only catch-all handlers, keep
1057 /// accepting requests without initialization, because they could not
1058 /// complete one.
1059 fn note_request_handler<Req: JsonRpcRequest>(mut self) -> Self {
1060 // A handler for every method is a catch-all, not an initialize handler.
1061 const UNRELATED_METHOD: &str = "\0acp-sdk/not-a-method";
1062 if TypeId::of::<Host>() == TypeId::of::<Agent>()
1063 && Req::matches_method("initialize")
1064 && !Req::matches_method(UNRELATED_METHOD)
1065 {
1066 self.protocol_mode = self.protocol_mode.require_initialize();
1067 }
1068 self
1069 }
1070
1071 /// Merge another [`Builder`] into this one.
1072 ///
1073 /// Prefer [`Self::on_receive_request`] or [`Self::on_receive_notification`].
1074 /// This is a low-level method that is not intended for general use.
1075 pub fn with_connection_builder(
1076 self,
1077 other: Builder<
1078 Host,
1079 impl HandleDispatchFrom<Host::Counterpart>,
1080 impl RunWithConnectionTo<Host::Counterpart>,
1081 impl HandleConnectionClose<Host::Counterpart>,
1082 P,
1083 >,
1084 ) -> Builder<
1085 Host,
1086 impl HandleDispatchFrom<Host::Counterpart>,
1087 impl RunWithConnectionTo<Host::Counterpart>,
1088 impl HandleConnectionClose<Host::Counterpart>,
1089 P,
1090 > {
1091 let Builder {
1092 name: other_name,
1093 handler: other_handler,
1094 runner: other_runner,
1095 protocol_mode: other_protocol_mode,
1096 on_close: other_on_close,
1097 protocol: _,
1098 host: _,
1099 } = other;
1100 Builder {
1101 host: self.host,
1102 name: self.name,
1103 handler: ChainedHandler::new(
1104 self.handler,
1105 NamedHandler::new(other_name, other_handler),
1106 ),
1107 runner: ChainRun::new(self.runner, other_runner),
1108 protocol_mode: self.protocol_mode.merge(other_protocol_mode),
1109 on_close: ChainedClose::new(self.on_close, other_on_close),
1110 protocol: PhantomData,
1111 }
1112 }
1113
1114 /// Add a new [`HandleDispatchFrom`] to the chain.
1115 ///
1116 /// Prefer [`Self::on_receive_request`] or [`Self::on_receive_notification`].
1117 /// This is a low-level method that is not intended for general use.
1118 pub fn with_handler(
1119 self,
1120 handler: impl HandleDispatchFrom<Host::Counterpart>,
1121 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P> {
1122 Builder {
1123 host: self.host,
1124 name: self.name,
1125 handler: ChainedHandler::new(self.handler, handler),
1126 runner: self.runner,
1127 protocol_mode: self.protocol_mode,
1128 on_close: self.on_close,
1129 protocol: PhantomData,
1130 }
1131 }
1132
1133 /// Add a new [`RunWithConnectionTo`] to the chain.
1134 pub fn with_runner<Run1>(
1135 self,
1136 runner: Run1,
1137 ) -> Builder<Host, Handler, impl RunWithConnectionTo<Host::Counterpart>, Close, P>
1138 where
1139 Run1: RunWithConnectionTo<Host::Counterpart>,
1140 {
1141 Builder {
1142 host: self.host,
1143 name: self.name,
1144 handler: self.handler,
1145 runner: ChainRun::new(self.runner, runner),
1146 protocol_mode: self.protocol_mode,
1147 on_close: self.on_close,
1148 protocol: PhantomData,
1149 }
1150 }
1151
1152 /// Enqueue a task to run once the connection is actively serving traffic.
1153 #[track_caller]
1154 pub fn with_spawned<F, Fut>(
1155 self,
1156 task: F,
1157 ) -> Builder<Host, Handler, impl RunWithConnectionTo<Host::Counterpart>, Close, P>
1158 where
1159 F: FnOnce(P::Connection<Host::Counterpart>) -> Fut + Send,
1160 Fut: Future<Output = Result<(), crate::Error>> + Send,
1161 {
1162 let location = Location::caller();
1163 // Boxed for the same reason as `main_fn` in `connect_with`: the driver
1164 // would otherwise store the task's captured state once per layer.
1165 self.with_runner(SpawnedRun::<_, P>::new(location, Box::new(task)))
1166 }
1167
1168 /// Run a callback when the incoming transport reaches clean EOF.
1169 ///
1170 /// Each callback runs at most once and receives the connection context. A
1171 /// successful callback observes the close without otherwise changing the
1172 /// lifetime of [`connect_with`](Self::connect_with). Returning an error
1173 /// shuts down the connection and cancels a still-running `connect_with`
1174 /// future.
1175 ///
1176 /// Multiple callbacks run sequentially in registration order. All of them
1177 /// run even if an earlier callback fails, after which the first error is
1178 /// returned. Pending requests are failed before callbacks begin, while the
1179 /// selected connection context's `incoming_closed` future completes only
1180 /// after they finish. A callback must therefore not await that close
1181 /// future itself.
1182 ///
1183 /// This separation lets applications choose their cancellation policy. A
1184 /// callback can notify application-owned tasks and return `Ok(())` for
1185 /// graceful cleanup, or return an error to stop them immediately.
1186 ///
1187 /// Close callbacks do not run for transport or handler errors, foreground
1188 /// completion, or a dropped driver. Use [`ConnectionTo::terminated`] to
1189 /// observe every way the connection can end.
1190 ///
1191 /// ```
1192 /// # use agent_client_protocol::{Client, ConnectTo, Error};
1193 /// # async fn example(transport: impl ConnectTo<Client>) -> Result<(), Error> {
1194 /// Client.v1()
1195 /// .on_close(async |_cx| {
1196 /// Err(Error::internal_error().data("agent transport closed"))
1197 /// })
1198 /// .connect_with(transport, async |_cx| {
1199 /// std::future::pending().await
1200 /// })
1201 /// .await?;
1202 /// # Ok(())
1203 /// # }
1204 /// ```
1205 pub fn on_close<F, Fut>(
1206 self,
1207 callback: F,
1208 ) -> Builder<Host, Handler, Runner, impl HandleConnectionClose<Host::Counterpart>, P>
1209 where
1210 F: FnOnce(P::Connection<Host::Counterpart>) -> Fut + Send,
1211 Fut: Future<Output = Result<(), crate::Error>> + Send,
1212 {
1213 Builder {
1214 host: self.host,
1215 name: self.name,
1216 handler: self.handler,
1217 runner: self.runner,
1218 protocol_mode: self.protocol_mode,
1219 on_close: ChainedClose::new(self.on_close, CloseCallback::<_, P>::new(callback)),
1220 protocol: PhantomData,
1221 }
1222 }
1223
1224 /// Register a handler for requests, notifications, and responses.
1225 ///
1226 /// Use this when you want to handle all JSON-RPC message kinds in one callback.
1227 /// Your handler receives a [`Dispatch<Req, Notif>`] with three variants:
1228 ///
1229 /// - `Dispatch::Request(request, responder)` - A request with its response context
1230 /// - `Dispatch::Notification(notification)` - A notification
1231 /// - `Dispatch::Response(result, router)` - A response to a request we sent
1232 ///
1233 /// # Example
1234 ///
1235 /// ```no_run
1236 /// # use agent_client_protocol_test::*;
1237 /// # use agent_client_protocol::v1::Dispatch;
1238 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
1239 /// # let connection = mock_connection();
1240 /// connection.on_receive_dispatch(async |message: Dispatch<MyRequest, StatusUpdate>, _cx| {
1241 /// match message {
1242 /// Dispatch::Request(req, responder) => {
1243 /// // Handle request and send response
1244 /// responder.respond(MyResponse { status: "ok".into() })
1245 /// }
1246 /// Dispatch::Notification(notif) => {
1247 /// // Handle notification (no response needed)
1248 /// Ok(())
1249 /// }
1250 /// Dispatch::Response(result, router) => {
1251 /// // Forward response to its destination
1252 /// router.route_with_result(result)
1253 /// }
1254 /// }
1255 /// }, agent_client_protocol::on_receive_dispatch!())
1256 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
1257 /// # Ok(())
1258 /// # }
1259 /// ```
1260 ///
1261 /// For most use cases, prefer [`on_receive_request`](Self::on_receive_request) or
1262 /// [`on_receive_notification`](Self::on_receive_notification) which provide cleaner APIs
1263 /// for handling requests or notifications separately.
1264 ///
1265 /// # Ordering
1266 ///
1267 /// This callback runs inside the dispatch loop and blocks further message processing
1268 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1269 /// ordering guarantees and how to avoid deadlocks.
1270 pub fn on_receive_dispatch<Req, Notif, F, T, ToFut>(
1271 self,
1272 op: F,
1273 to_future_hack: ToFut,
1274 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1275 where
1276 Host::Counterpart: HasPeer<Host::Counterpart>,
1277 Req: JsonRpcRequest,
1278 Notif: JsonRpcNotification,
1279 F: AsyncFnMut(
1280 Dispatch<Req, Notif, P>,
1281 P::Connection<Host::Counterpart>,
1282 ) -> Result<T, crate::Error>
1283 + Send,
1284 T: IntoHandled<Dispatch<Req, Notif, P>>,
1285 ToFut: Fn(
1286 &mut F,
1287 Dispatch<Req, Notif, P>,
1288 P::Connection<Host::Counterpart>,
1289 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1290 + Send
1291 + Sync,
1292 {
1293 let handler = MessageHandler::<_, _, P, _, _, _, _>::new(
1294 self.host.counterpart(),
1295 self.host.counterpart(),
1296 op,
1297 to_future_hack,
1298 );
1299 self.note_request_handler::<Req>().with_handler(handler)
1300 }
1301
1302 /// Register a handler for JSON-RPC requests of type `Req`.
1303 ///
1304 /// Your handler receives three arguments:
1305 /// 1. The request (type `Req`)
1306 /// 2. A [`Responder<Req::Response, P>`] for sending the response
1307 /// 3. The builder-selected connection context for the peer that sent the
1308 /// request (`ConnectionTo` by default, or `v2::ConnectionTo` for a
1309 /// `v2::Builder`)
1310 ///
1311 /// The request context allows you to:
1312 /// - Send the response with [`Responder::respond`]
1313 /// - Send notifications to the client with the context's
1314 /// `send_notification` method
1315 /// - Send requests to the client with the context's `send_request` method
1316 ///
1317 /// # Example
1318 ///
1319 /// ```no_run
1320 /// # use agent_client_protocol::{Agent, ConnectTo};
1321 /// # use agent_client_protocol::v1::schema::{PromptRequest, PromptResponse, SessionNotification};
1322 /// # async fn example(transport: impl ConnectTo<Agent>) -> Result<(), agent_client_protocol::Error> {
1323 /// Agent.v1().on_receive_request(async |request: PromptRequest, responder, cx| {
1324 /// // Send a notification while processing
1325 /// let notif: SessionNotification = todo!();
1326 /// cx.send_notification(notif)?;
1327 ///
1328 /// // Send the response
1329 /// let response: PromptResponse = todo!();
1330 /// responder.respond(response)
1331 /// }, agent_client_protocol::on_receive_request!())
1332 /// .connect_to(transport)
1333 /// .await
1334 /// # }
1335 /// ```
1336 ///
1337 /// # Type Parameter
1338 ///
1339 /// `Req` can be either a single request type or an enum of multiple request types.
1340 /// See the [type-driven dispatch](Self#type-driven-message-dispatch) section for details.
1341 ///
1342 /// # Ordering
1343 ///
1344 /// This callback runs inside the dispatch loop and blocks further message processing
1345 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1346 /// ordering guarantees and how to avoid deadlocks.
1347 pub fn on_receive_request<Req: JsonRpcRequest, F, T, ToFut>(
1348 self,
1349 op: F,
1350 to_future_hack: ToFut,
1351 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1352 where
1353 Host::Counterpart: HasPeer<Host::Counterpart>,
1354 F: AsyncFnMut(
1355 Req,
1356 Responder<Req::Response, P>,
1357 P::Connection<Host::Counterpart>,
1358 ) -> Result<T, crate::Error>
1359 + Send,
1360 T: IntoHandled<(Req, Responder<Req::Response, P>)>,
1361 ToFut: Fn(
1362 &mut F,
1363 Req,
1364 Responder<Req::Response, P>,
1365 P::Connection<Host::Counterpart>,
1366 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1367 + Send
1368 + Sync,
1369 {
1370 let handler = RequestHandler::<_, _, P, _, _, _>::new(
1371 self.host.counterpart(),
1372 self.host.counterpart(),
1373 op,
1374 to_future_hack,
1375 );
1376 self.note_request_handler::<Req>().with_handler(handler)
1377 }
1378
1379 /// Register a handler for JSON-RPC notifications of type `Notif`.
1380 ///
1381 /// Notifications are fire-and-forget messages that don't expect a response.
1382 /// Your handler receives:
1383 /// 1. The notification (type `Notif`)
1384 /// 2. The builder-selected connection context for sending messages to the
1385 /// other side
1386 ///
1387 /// Unlike request handlers, you cannot send a response (notifications don't have IDs),
1388 /// but you can still send your own requests and notifications using the context.
1389 ///
1390 /// # Example
1391 ///
1392 /// ```no_run
1393 /// # use agent_client_protocol_test::*;
1394 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
1395 /// # let connection = mock_connection();
1396 /// connection.on_receive_notification(async |notif: SessionUpdate, cx| {
1397 /// // Process the notification
1398 /// update_session_state(¬if)?;
1399 ///
1400 /// // Optionally send a notification back
1401 /// cx.send_notification(StatusUpdate {
1402 /// message: "Acknowledged".into(),
1403 /// })?;
1404 ///
1405 /// Ok(())
1406 /// }, agent_client_protocol::on_receive_notification!())
1407 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
1408 /// # Ok(())
1409 /// # }
1410 /// ```
1411 ///
1412 /// # Type Parameter
1413 ///
1414 /// `Notif` can be either a single notification type or an enum of multiple notification types.
1415 /// See the [type-driven dispatch](Self#type-driven-message-dispatch) section for details.
1416 ///
1417 /// # Ordering
1418 ///
1419 /// This callback runs inside the dispatch loop and blocks further message processing
1420 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1421 /// ordering guarantees and how to avoid deadlocks.
1422 pub fn on_receive_notification<Notif, F, T, ToFut>(
1423 self,
1424 op: F,
1425 to_future_hack: ToFut,
1426 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1427 where
1428 Host::Counterpart: HasPeer<Host::Counterpart>,
1429 Notif: JsonRpcNotification,
1430 F: AsyncFnMut(Notif, P::Connection<Host::Counterpart>) -> Result<T, crate::Error> + Send,
1431 T: IntoHandled<(Notif, P::Connection<Host::Counterpart>)>,
1432 ToFut: Fn(
1433 &mut F,
1434 Notif,
1435 P::Connection<Host::Counterpart>,
1436 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1437 + Send
1438 + Sync,
1439 {
1440 let handler = NotificationHandler::<_, _, P, _, _, _>::new(
1441 self.host.counterpart(),
1442 self.host.counterpart(),
1443 op,
1444 to_future_hack,
1445 );
1446 self.with_handler(handler)
1447 }
1448
1449 /// Register a handler for messages from a specific peer.
1450 ///
1451 /// This is similar to [`on_receive_dispatch`](Self::on_receive_dispatch), but allows
1452 /// specifying the source peer explicitly. This is useful when receiving messages
1453 /// from a peer that requires message transformation (e.g., unwrapping `SuccessorMessage`
1454 /// envelopes when receiving from an agent via a proxy).
1455 ///
1456 /// For the common case of receiving from the default counterpart, use
1457 /// [`on_receive_dispatch`](Self::on_receive_dispatch) instead.
1458 ///
1459 /// # Ordering
1460 ///
1461 /// This callback runs inside the dispatch loop and blocks further message processing
1462 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1463 /// ordering guarantees and how to avoid deadlocks.
1464 pub fn on_receive_dispatch_from<
1465 Req: JsonRpcRequest,
1466 Notif: JsonRpcNotification,
1467 Peer: Role,
1468 F,
1469 T,
1470 ToFut,
1471 >(
1472 self,
1473 peer: Peer,
1474 op: F,
1475 to_future_hack: ToFut,
1476 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1477 where
1478 Host::Counterpart: HasPeer<Peer>,
1479 F: AsyncFnMut(
1480 Dispatch<Req, Notif, P>,
1481 P::Connection<Host::Counterpart>,
1482 ) -> Result<T, crate::Error>
1483 + Send,
1484 T: IntoHandled<Dispatch<Req, Notif, P>>,
1485 ToFut: Fn(
1486 &mut F,
1487 Dispatch<Req, Notif, P>,
1488 P::Connection<Host::Counterpart>,
1489 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1490 + Send
1491 + Sync,
1492 {
1493 let handler = MessageHandler::<_, _, P, _, _, _, _>::new(
1494 self.host.counterpart(),
1495 peer,
1496 op,
1497 to_future_hack,
1498 );
1499 self.note_request_handler::<Req>().with_handler(handler)
1500 }
1501
1502 /// Register a handler for JSON-RPC requests from a specific peer.
1503 ///
1504 /// This is similar to [`on_receive_request`](Self::on_receive_request), but allows
1505 /// specifying the source peer explicitly. This is useful when receiving messages
1506 /// from a peer that requires message transformation (e.g., unwrapping `SuccessorRequest`
1507 /// envelopes when receiving from an agent via a proxy).
1508 ///
1509 /// For the common case of receiving from the default counterpart, use
1510 /// [`on_receive_request`](Self::on_receive_request) instead.
1511 ///
1512 /// # Example
1513 ///
1514 /// ```ignore
1515 /// use agent_client_protocol::Agent;
1516 /// use agent_client_protocol::v1::schema::InitializeRequest;
1517 ///
1518 /// // Conductor receiving from agent direction - messages will be unwrapped from SuccessorMessage
1519 /// connection.on_receive_request_from(Agent, async |req: InitializeRequest, responder, cx| {
1520 /// // Handle the request
1521 /// responder.respond(InitializeResponse::make())
1522 /// })
1523 /// ```
1524 ///
1525 /// # Ordering
1526 ///
1527 /// This callback runs inside the dispatch loop and blocks further message processing
1528 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1529 /// ordering guarantees and how to avoid deadlocks.
1530 pub fn on_receive_request_from<Req: JsonRpcRequest, Peer: Role, F, T, ToFut>(
1531 self,
1532 peer: Peer,
1533 op: F,
1534 to_future_hack: ToFut,
1535 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1536 where
1537 Host::Counterpart: HasPeer<Peer>,
1538 F: AsyncFnMut(
1539 Req,
1540 Responder<Req::Response, P>,
1541 P::Connection<Host::Counterpart>,
1542 ) -> Result<T, crate::Error>
1543 + Send,
1544 T: IntoHandled<(Req, Responder<Req::Response, P>)>,
1545 ToFut: Fn(
1546 &mut F,
1547 Req,
1548 Responder<Req::Response, P>,
1549 P::Connection<Host::Counterpart>,
1550 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1551 + Send
1552 + Sync,
1553 {
1554 let handler = RequestHandler::<_, _, P, _, _, _>::new(
1555 self.host.counterpart(),
1556 peer,
1557 op,
1558 to_future_hack,
1559 );
1560 self.note_request_handler::<Req>().with_handler(handler)
1561 }
1562
1563 /// Register a handler for JSON-RPC notifications from a specific peer.
1564 ///
1565 /// This is similar to [`on_receive_notification`](Self::on_receive_notification), but allows
1566 /// specifying the source peer explicitly. This is useful when receiving messages
1567 /// from a peer that requires message transformation (e.g., unwrapping `SuccessorNotification`
1568 /// envelopes when receiving from an agent via a proxy).
1569 ///
1570 /// For the common case of receiving from the default counterpart, use
1571 /// [`on_receive_notification`](Self::on_receive_notification) instead.
1572 ///
1573 /// # Ordering
1574 ///
1575 /// This callback runs inside the dispatch loop and blocks further message processing
1576 /// until it completes. See the [`ordering`](crate::concepts::ordering) module for details on
1577 /// ordering guarantees and how to avoid deadlocks.
1578 pub fn on_receive_notification_from<Notif: JsonRpcNotification, Peer: Role, F, T, ToFut>(
1579 self,
1580 peer: Peer,
1581 op: F,
1582 to_future_hack: ToFut,
1583 ) -> Builder<Host, impl HandleDispatchFrom<Host::Counterpart>, Runner, Close, P>
1584 where
1585 Host::Counterpart: HasPeer<Peer>,
1586 F: AsyncFnMut(Notif, P::Connection<Host::Counterpart>) -> Result<T, crate::Error> + Send,
1587 T: IntoHandled<(Notif, P::Connection<Host::Counterpart>)>,
1588 ToFut: Fn(
1589 &mut F,
1590 Notif,
1591 P::Connection<Host::Counterpart>,
1592 ) -> crate::BoxFuture<'_, Result<T, crate::Error>>
1593 + Send
1594 + Sync,
1595 {
1596 let handler = NotificationHandler::<_, _, P, _, _, _>::new(
1597 self.host.counterpart(),
1598 peer,
1599 op,
1600 to_future_hack,
1601 );
1602 self.with_handler(handler)
1603 }
1604
1605 /// Run in server mode with the provided transport.
1606 ///
1607 /// This drives the connection by continuously processing messages from the transport
1608 /// and dispatching them to your registered handlers. The connection will run until:
1609 /// - The transport closes (e.g., EOF on byte streams)
1610 /// - An error occurs
1611 ///
1612 /// Handler errors are normally contained: requests receive an Error Response,
1613 /// response-handler errors are routed to the pending local request, and
1614 /// notification errors are logged without a wire reply.
1615 ///
1616 /// On clean EOF, messages already accepted by the outgoing queue—including
1617 /// handler responses and close-callback notifications—are drained through
1618 /// the transport sink before this returns `Ok(())`.
1619 ///
1620 /// The transport boundary carries [`TransportFrame`] values. Physical stream adapters
1621 /// serialize and deserialize frames, while channel-based components relay them directly.
1622 ///
1623 /// Use this mode when you only need to respond to incoming messages and don't need
1624 /// to initiate your own requests. If you need to send requests to the other side,
1625 /// use [`connect_with`](Self::connect_with) instead.
1626 ///
1627 /// # Errors
1628 ///
1629 /// Returns errors from the transport, connection tasks, or close callbacks.
1630 /// An error sent to a peer in a response is not itself a connection failure.
1631 ///
1632 /// # Example: Byte Stream Transport
1633 ///
1634 /// ```no_run
1635 /// # use agent_client_protocol::UntypedRole;
1636 /// # use agent_client_protocol::{Builder};
1637 /// # use agent_client_protocol_test::*;
1638 /// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
1639 ///
1640 /// UntypedRole.builder()
1641 /// .on_receive_request(async |req: MyRequest, responder, cx| {
1642 /// responder.respond(MyResponse { status: "ok".into() })
1643 /// }, agent_client_protocol::on_receive_request!())
1644 /// .connect_to(transport)
1645 /// .await?;
1646 /// # Ok(())
1647 /// # }
1648 /// ```
1649 pub async fn connect_to(
1650 self,
1651 transport: impl ConnectTo<Host> + 'static,
1652 ) -> Result<(), crate::Error> {
1653 let (_, future) = self.into_connection_and_future(transport, true, async move |cx| {
1654 cx.incoming_closed().await;
1655 Ok(())
1656 });
1657 future.await
1658 }
1659
1660 /// Run the connection until the provided closure completes.
1661 ///
1662 /// This drives the connection by:
1663 /// 1. Running your registered handlers in the background to process incoming messages
1664 /// 2. Executing your `main_fn` closure with the builder-selected connection
1665 /// context for sending requests and notifications
1666 ///
1667 /// The connection stays active until your `main_fn` returns, then shuts down.
1668 /// Clean incoming EOF fails every pending request and makes future
1669 /// requests fail immediately. It does not cancel unrelated work in
1670 /// `main_fn`: that future may observe the context's `incoming_closed`
1671 /// future, or the builder can use [`on_close`](Self::on_close) to notify it
1672 /// or return an error and stop it.
1673 ///
1674 /// Use this mode when you need to initiate communication (send requests/notifications)
1675 /// in addition to responding to incoming messages. For server-only mode where you just
1676 /// respond to messages, use [`connect_to`](Self::connect_to) instead.
1677 ///
1678 /// # Example
1679 ///
1680 /// ```no_run
1681 /// # use agent_client_protocol::UntypedRole;
1682 /// # use agent_client_protocol::{Builder};
1683 /// # use agent_client_protocol::ByteStreams;
1684 /// # use agent_client_protocol::v1::schema::InitializeRequest;
1685 /// # use agent_client_protocol_test::*;
1686 /// # async fn example(transport: impl agent_client_protocol::ConnectTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
1687 ///
1688 /// UntypedRole.builder()
1689 /// .on_receive_request(async |req: MyRequest, responder, cx| {
1690 /// // Handle incoming requests in the background
1691 /// responder.respond(MyResponse { status: "ok".into() })
1692 /// }, agent_client_protocol::on_receive_request!())
1693 /// .connect_with(transport, async |cx| {
1694 /// // Initialize the protocol
1695 /// let init_response = cx.send_request(InitializeRequest::make())
1696 /// .block_task()
1697 /// .await?;
1698 ///
1699 /// // Send more requests...
1700 /// let result = cx.send_request(MyRequest {})
1701 /// .block_task()
1702 /// .await?;
1703 ///
1704 /// // When this closure returns, the connection shuts down
1705 /// Ok(())
1706 /// })
1707 /// .await?;
1708 /// # Ok(())
1709 /// # }
1710 /// ```
1711 ///
1712 /// # Parameters
1713 ///
1714 /// - `main_fn`: Your client logic. Receives the builder-selected connection
1715 /// context for sending messages.
1716 ///
1717 /// # Errors
1718 ///
1719 /// Returns an error if a handler, background task, transport, or close
1720 /// callback fails, or if `main_fn` returns an error. Clean incoming EOF is
1721 /// observable through the context's `incoming_closed` future and is not
1722 /// itself an error in this mode.
1723 pub async fn connect_with<R>(
1724 self,
1725 transport: impl ConnectTo<Host> + 'static,
1726 main_fn: impl AsyncFnOnce(P::Connection<Host::Counterpart>) -> Result<R, crate::Error>,
1727 ) -> Result<R, crate::Error> {
1728 // The driver moves `main_fn` through several nested futures, and each
1729 // one reserves room for it. Box the closure and its future so that the
1730 // returned future holds the caller's captured state once instead of
1731 // once per layer. Otherwise a closure that captures a few kilobytes,
1732 // such as an `initialize` request and response, makes it very large.
1733 let main_fn = Box::new(main_fn);
1734 let (_, future) =
1735 self.into_connection_and_future(transport, false, async move |connection| {
1736 Box::pin(main_fn(protocol::connection_from_raw::<P, _>(connection))).await
1737 });
1738 future.await
1739 }
1740
1741 /// Helper that returns a [`ConnectionTo<R>`] and a future that runs this connection until `main_fn` returns.
1742 fn into_connection_and_future<R>(
1743 self,
1744 transport: impl ConnectTo<Host> + 'static,
1745 wait_owned_transport: bool,
1746 main_fn: impl AsyncFnOnce(ConnectionTo<Host::Counterpart>) -> Result<R, crate::Error>,
1747 ) -> (
1748 ConnectionTo<Host::Counterpart>,
1749 impl Future<Output = Result<R, crate::Error>>,
1750 ) {
1751 let Self {
1752 name,
1753 handler,
1754 runner,
1755 host: me,
1756 protocol_mode,
1757 on_close,
1758 protocol: _,
1759 } = self;
1760
1761 let (outgoing_tx, outgoing_rx) = mpsc::unbounded();
1762 let (new_task_tx, new_task_rx) = mpsc::unbounded();
1763 let (dynamic_handler_tx, dynamic_handler_rx) = mpsc::unbounded();
1764 let (foreground_succeeded_tx, foreground_succeeded) = completion_signal();
1765 let (foreground_done_tx, foreground_done) = completion_signal();
1766 let pending_replies = PendingReplies::default();
1767 let termination_sources = TerminationSources::default();
1768
1769 // Normalize the transport without losing ownership or finish metadata.
1770 let transport_component = crate::DynConnectTo::new(transport);
1771 let (transport_channel, mut transport_future) =
1772 transport_component.into_channel_and_future();
1773 let owned_transport = transport_future.is_some();
1774 let transport_finish = transport_future
1775 .as_mut()
1776 .and_then(crate::ConnectionDriver::take_finish);
1777 let (transport_completion_tx, transport_completion_rx) = oneshot::channel();
1778 let transport_completion = transport_completion_rx
1779 .map(|result| {
1780 result.unwrap_or_else(|error| {
1781 Err(crate::util::internal_error(format!(
1782 "transport task dropped before reporting completion: {error}"
1783 )))
1784 })
1785 })
1786 .boxed()
1787 .shared();
1788
1789 let connection = ConnectionTo::new(
1790 me.counterpart(),
1791 outgoing_tx,
1792 new_task_tx,
1793 dynamic_handler_tx,
1794 transport_completion,
1795 pending_replies.registrar(),
1796 protocol_mode,
1797 );
1798 // Transport progress must outlive successful foreground completion.
1799 // Application tasks remain cancellable. The inherited close-callback
1800 // phase still polls them for cleanup, but physical drain alone does not.
1801 let transport_driver = if let Some(driver) = transport_future {
1802 let termination_sources = termination_sources.clone();
1803 async move {
1804 let result = driver.await;
1805 termination_sources.record(TerminationSource::Transport, &result);
1806 drop(transport_completion_tx.send(result.clone()));
1807 result
1808 }
1809 .boxed()
1810 } else {
1811 // Channel-only endpoints have no physical sink work to await.
1812 // Their protocol drain marker still orders accepted output.
1813 drop(transport_completion_tx.send(Ok(())));
1814 future::ready(Ok(())).boxed()
1815 };
1816
1817 // Destructure the channel endpoints
1818 let Channel {
1819 rx: mut transport_incoming_rx,
1820 tx: transport_outgoing_tx,
1821 } = transport_channel;
1822
1823 let transport_incoming = futures::stream::poll_fn({
1824 let mut completion = connection.transport_completion.clone();
1825 let mut completed = false;
1826 move |cx| {
1827 if owned_transport
1828 && !completed
1829 && let std::task::Poll::Ready(Ok(())) =
1830 std::pin::Pin::new(&mut completion).poll(cx)
1831 {
1832 // Owned completion closes the producer boundary, not the
1833 // accepted buffer. The incoming actor still dispatches every
1834 // accepted frame and completes its close callbacks in order.
1835 transport_incoming_rx.close();
1836 completed = true;
1837 }
1838 transport_incoming_rx.poll_next_unpin(cx)
1839 }
1840 });
1841
1842 let protocol_compat = ProtocolCompat::new(protocol_mode);
1843
1844 // Constructed outside the driver so dropping it unpolled still
1845 // publishes a termination.
1846 let termination_guard = TerminationGuard {
1847 incoming_closed: connection.incoming_closed.clone(),
1848 pending_replies: pending_replies.clone(),
1849 };
1850
1851 let future = crate::util::instrument_with_connection_name(name, {
1852 let connection = connection.clone();
1853 async move {
1854 let sources = &termination_sources;
1855 let driver = async {
1856 let background = async {
1857 let incoming = {
1858 let pending_replies = pending_replies.clone();
1859 let protocol_compat = protocol_compat.clone();
1860 async {
1861 let mut transport_incoming = std::pin::pin!(transport_incoming);
1862 let incoming = incoming_actor::incoming_protocol_actor(
1863 me.counterpart(),
1864 &connection,
1865 transport_incoming.as_mut(),
1866 dynamic_handler_rx,
1867 pending_replies,
1868 incoming_actor::IncomingHandlers::new(
1869 handler,
1870 on_close,
1871 foreground_succeeded.clone(),
1872 ),
1873 protocol_compat,
1874 );
1875 // Success stops delivery, not physical I/O. An
1876 // underway close callback finishes before sealing.
1877 let result = run_incoming_until_foreground_succeeds(
1878 incoming,
1879 foreground_succeeded,
1880 connection.incoming_closed.clone(),
1881 )
1882 .await;
1883 sources.record(TerminationSource::Handler, &result);
1884 if result.is_err() {
1885 connection.request_shutdown();
1886 }
1887 result?;
1888 // Keep the raw producer boundary alive while the
1889 // physical driver drains. Discard without application
1890 // delivery, rather than fail a late read-side send.
1891 while transport_incoming.next().await.is_some() {}
1892 Ok(())
1893 }
1894 };
1895 let other_actors = async {
1896 let result = futures::try_join!(
1897 // A ready driver error is authoritative even if its
1898 // closed channel would also make output forwarding fail.
1899 transport_driver,
1900 // Protocol layer: OutgoingMessage -> RawJsonRpcMessage
1901 outgoing_actor::outgoing_protocol_actor(
1902 outgoing_rx,
1903 pending_replies,
1904 transport_outgoing_tx,
1905 protocol_compat,
1906 foreground_done,
1907 )
1908 .inspect(
1909 |result| sources.record(TerminationSource::Transport, result)
1910 ),
1911 );
1912 // Signal before awaiting an underway close callback.
1913 if result.is_err() {
1914 connection.request_shutdown();
1915 }
1916 result?;
1917 Ok(())
1918 };
1919
1920 // Keep close callbacks alive when another core actor fails.
1921 // The outer coordination provides the same protection when
1922 // EOF wakes an application task or the foreground.
1923 run_until_connection_close(
1924 incoming,
1925 other_actors,
1926 connection.incoming_closed.clone(),
1927 )
1928 .await
1929 };
1930
1931 run_until_connection_close(
1932 finish_actor_error(background, &connection),
1933 async {
1934 let application = async {
1935 futures::try_join!(
1936 finish_actor_error(
1937 task_actor::task_actor(new_task_rx, &connection)
1938 .inspect(|result| sources
1939 .record(TerminationSource::Handler, result),),
1940 &connection,
1941 ),
1942 finish_actor_error(
1943 runner
1944 .run_with_connection_to(connection.clone())
1945 .inspect(|result| sources
1946 .record(TerminationSource::Handler, result),),
1947 &connection,
1948 ),
1949 )?;
1950 Ok(())
1951 };
1952 let result = run_until_connection_close(
1953 application,
1954 async {
1955 let result = main_fn(connection.clone()).await;
1956 sources.record(TerminationSource::Foreground, &result);
1957 connection.request_shutdown();
1958 if result.is_ok() {
1959 // Stop new incoming delivery immediately,
1960 // including during the callback cleanup phase.
1961 let _ = foreground_succeeded_tx.send(());
1962 }
1963 // Shutdown cancels local consumers, not remote
1964 // requests. Do not add cancellation traffic while
1965 // dropping those consumers before the drain.
1966 connection.pending_replies.disarm_cancellations();
1967 // The application actor (including actual scoped
1968 // runners) remains polled while supervisors finish.
1969 // Only then may ordinary application tasks drop.
1970 connection.wait_protected_operations().await;
1971 result
1972 },
1973 connection.incoming_closed.clone(),
1974 )
1975 .await?;
1976 let _ = foreground_done_tx.send(());
1977 let drained = connection
1978 .drain_outgoing(transport_finish, wait_owned_transport)
1979 .await;
1980 sources.record(TerminationSource::Transport, &drained);
1981 drained?;
1982 Ok(result)
1983 },
1984 connection.incoming_closed.clone(),
1985 )
1986 .await
1987 };
1988 // Every actor, handler, and task has completed or been
1989 // dropped by the time `driver` resolves.
1990 let result = driver.await;
1991 termination_guard.finish(match &result {
1992 // A foreground that finishes after observing EOF still
1993 // ended at a clean EOF boundary.
1994 Ok(_) if connection.incoming_closed.is_closing() => {
1995 ConnectionTermination::IncomingClosed
1996 }
1997 Ok(_) => ConnectionTermination::LocalShutdown,
1998 Err(error) => sources.classify(error.clone()),
1999 });
2000 result
2001 }
2002 });
2003
2004 (connection, future)
2005 }
2006}
2007
2008/// Defer an actor error without dropping the other actors that drive owned
2009/// cleanup or an underway close callback. Physical output drain stays separate.
2010async fn finish_actor_error<R: Role>(
2011 actor: impl Future<Output = Result<(), crate::Error>>,
2012 connection: &ConnectionTo<R>,
2013) -> Result<(), crate::Error> {
2014 let result = actor.await;
2015 if result.is_err() {
2016 connection.request_shutdown();
2017 if connection.incoming_closed.is_closing() {
2018 connection.incoming_closed.closed().await;
2019 }
2020 connection.wait_protected_operations().await;
2021 }
2022 result
2023}
2024
2025#[cfg(feature = "unstable_mcp_over_acp")]
2026impl<
2027 Host: Role,
2028 Handler: HandleDispatchFrom<Host::Counterpart>,
2029 Runner: RunWithConnectionTo<Host::Counterpart>,
2030 Close: HandleConnectionClose<Host::Counterpart>,
2031> Builder<Host, Handler, Runner, Close, V1>
2032{
2033 /// Add an MCP server to protocol v1 session setup requests proxied through
2034 /// this connection.
2035 ///
2036 /// The same native MCP server declaration is added to new, load, and resume
2037 /// requests, plus fork requests when `unstable_session_fork` is enabled.
2038 /// Unrelated request fields are preserved exactly.
2039 ///
2040 /// Only applicable to proxies. Use the same method on `v2::Builder` to
2041 /// attach the server to protocol v2 setup requests.
2042 ///
2043 /// The declaration is an `acp` transport (`McpServer::Acp`). The agent must
2044 /// advertise `agentCapabilities.mcpCapabilities.acp`, or a compatibility
2045 /// proxy such as `McpOverAcpPolyfill` must sit between this proxy and the
2046 /// agent; otherwise a conforming agent rejects the setup request with
2047 /// `-32602`. This method does not check the agent's capabilities.
2048 pub fn with_mcp_server(
2049 self,
2050 mcp_server: McpServer<Host::Counterpart, impl RunWithConnectionTo<Host::Counterpart>>,
2051 ) -> Builder<
2052 Host,
2053 impl HandleDispatchFrom<Host::Counterpart>,
2054 impl RunWithConnectionTo<Host::Counterpart>,
2055 Close,
2056 V1,
2057 >
2058 where
2059 Host::Counterpart: HasPeer<Agent> + HasPeer<Client>,
2060 {
2061 let (handler, runner) = mcp_server.into_handler_and_runner();
2062 self.with_handler(handler).with_runner(runner)
2063 }
2064}
2065
2066#[cfg(all(feature = "unstable_mcp_over_acp", feature = "unstable_protocol_v2"))]
2067impl<
2068 Host: Role,
2069 Handler: HandleDispatchFrom<Host::Counterpart>,
2070 Runner: RunWithConnectionTo<Host::Counterpart>,
2071 Close: HandleConnectionClose<Host::Counterpart>,
2072> Builder<Host, Handler, Runner, Close, V2>
2073{
2074 /// Add an MCP server to protocol v2 session setup requests proxied through
2075 /// this connection.
2076 ///
2077 /// The same native MCP server declaration is added to new and resume
2078 /// requests, plus fork requests when `unstable_session_fork` is enabled.
2079 /// Unrelated request fields are preserved exactly.
2080 ///
2081 /// MCP server names must be unique within `mcpServers`. If a client's
2082 /// setup request already declares a server with this server's name, the
2083 /// proxy answers that request with `-32602` naming the conflicting server
2084 /// and does not forward it. The client's servers are never renamed or
2085 /// dropped.
2086 ///
2087 /// Only applicable to proxies.
2088 ///
2089 /// The declaration is an `acp` transport (`McpServer::Acp`). The downstream
2090 /// agent must advertise `session.mcp.acp`, or a compatibility proxy such as
2091 /// `McpOverAcpPolyfill` must sit between this proxy and the agent;
2092 /// otherwise a conforming agent rejects the setup request with `-32602`.
2093 /// This method does not check the agent's capabilities.
2094 pub fn with_mcp_server(
2095 self,
2096 mcp_server: McpServer<Host::Counterpart, impl RunWithConnectionTo<Host::Counterpart>>,
2097 ) -> Builder<
2098 Host,
2099 impl HandleDispatchFrom<Host::Counterpart>,
2100 impl RunWithConnectionTo<Host::Counterpart>,
2101 Close,
2102 V2,
2103 >
2104 where
2105 Host::Counterpart: HasPeer<Agent> + HasPeer<Client>,
2106 {
2107 let (handler, runner) = mcp_server.into_v2_handler_and_runner();
2108 self.with_handler(handler).with_runner(runner)
2109 }
2110}
2111
2112impl<R, H, Run, Close, P> ConnectTo<R::Counterpart> for Builder<R, H, Run, Close, P>
2113where
2114 R: Role,
2115 H: HandleDispatchFrom<R::Counterpart> + 'static,
2116 Run: RunWithConnectionTo<R::Counterpart> + 'static,
2117 Close: HandleConnectionClose<R::Counterpart> + 'static,
2118 P: Protocol,
2119{
2120 async fn connect_to(self, client: impl ConnectTo<R>) -> Result<(), crate::Error> {
2121 Builder::connect_to(self, client).await
2122 }
2123}
2124
2125/// The payload sent through the response oneshot channel.
2126///
2127/// Includes the response value and an optional ack channel for dispatch loop
2128/// synchronization.
2129pub(crate) struct ResponsePayload {
2130 /// The response result - either the JSON value or an error.
2131 pub(crate) result: Result<serde_json::Value, crate::Error>,
2132
2133 /// Optional acknowledgment channel for dispatch loop synchronization.
2134 ///
2135 /// When present, the receiver must send on this channel to signal that
2136 /// response processing is complete, allowing the dispatch loop to continue
2137 /// to the next message.
2138 ///
2139 /// This is present when ordered response consumption was selected before
2140 /// the response was routed during its original dispatch. Public callback
2141 /// consumption and framework-owned ordered blocking transforms can hold
2142 /// the dispatch loop; ordinary blocking consumers, local error paths, and
2143 /// responses routed later do not.
2144 pub(crate) ack_tx: Option<oneshot::Sender<()>>,
2145}
2146
2147type ResponseRouteHook =
2148 Box<dyn FnOnce(&str, &serde_json::Value) -> Result<(), crate::Error> + Send>;
2149
2150/// A prerequisite that must complete before an outgoing request is published
2151/// to the transport.
2152struct RequestReadiness {
2153 future: BoxFuture<'static, Result<(), crate::Error>>,
2154}
2155
2156impl RequestReadiness {
2157 fn new(future: impl Future<Output = Result<(), crate::Error>> + Send + 'static) -> Self {
2158 Self {
2159 future: future.boxed(),
2160 }
2161 }
2162}
2163
2164impl Future for RequestReadiness {
2165 type Output = Result<(), crate::Error>;
2166
2167 fn poll(
2168 mut self: std::pin::Pin<&mut Self>,
2169 cx: &mut std::task::Context<'_>,
2170 ) -> std::task::Poll<Self::Output> {
2171 self.future.as_mut().poll(cx)
2172 }
2173}
2174
2175impl Debug for RequestReadiness {
2176 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2177 formatter
2178 .debug_struct("RequestReadiness")
2179 .finish_non_exhaustive()
2180 }
2181}
2182
2183impl std::fmt::Debug for ResponsePayload {
2184 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2185 f.debug_struct("ResponsePayload")
2186 .field("result", &self.result)
2187 .field("ack_tx", &self.ack_tx.as_ref().map(|_| "..."))
2188 .finish()
2189 }
2190}
2191
2192#[derive(Clone, Debug, Default)]
2193struct ResponseOrdering {
2194 ordered: Arc<AtomicBool>,
2195}
2196
2197impl ResponseOrdering {
2198 fn mark_ordered(&self) {
2199 self.ordered.store(true, Ordering::Release);
2200 }
2201
2202 fn is_ordered(&self) -> bool {
2203 self.ordered.load(Ordering::Acquire)
2204 }
2205}
2206
2207struct PendingReply {
2208 id: RawJsonRpcId,
2209 method: String,
2210 role_id: RoleId,
2211 sender: oneshot::Sender<ResponsePayload>,
2212 cancellation_disarm: SentRequestCancellationDisarm,
2213 ordering: ResponseOrdering,
2214 response_route_hook: Option<ResponseRouteHook>,
2215 forwarded_from: Option<RequestOrigin>,
2216 /// Set only by `v2::ConnectionTo::send_initialize`, whose typed outcome
2217 /// reports a lower-version initialize response as a success.
2218 accepts_lower_initialize_version: bool,
2219}
2220
2221impl PendingReply {
2222 fn fail(self, error: crate::Error) {
2223 self.cancellation_disarm.disarm();
2224 if self
2225 .sender
2226 .send(ResponsePayload {
2227 result: Err(error),
2228 ack_tx: None,
2229 })
2230 .is_err()
2231 {
2232 tracing::trace!(method = %self.method, "Pending request was already dropped");
2233 }
2234 }
2235
2236 fn fail_incoming_closed(self) {
2237 let error = incoming_transport_closed_error(&self.method);
2238 self.fail(error);
2239 }
2240}
2241
2242#[derive(Default)]
2243struct PendingRepliesInner {
2244 incoming_closed: bool,
2245 termination: Option<ConnectionTermination>,
2246 replies: HashMap<RawJsonRpcId, PendingReply>,
2247}
2248
2249#[derive(Clone, Default)]
2250struct PendingReplies {
2251 inner: Arc<Mutex<PendingRepliesInner>>,
2252}
2253
2254impl PendingReplies {
2255 fn registrar(&self) -> PendingRepliesRegistrar {
2256 PendingRepliesRegistrar {
2257 inner: Arc::downgrade(&self.inner),
2258 }
2259 }
2260
2261 fn contains(&self, id: &RawJsonRpcId) -> bool {
2262 self.inner
2263 .lock()
2264 .expect("pending replies mutex poisoned")
2265 .replies
2266 .contains_key(id)
2267 }
2268
2269 fn remove(&self, id: &RawJsonRpcId) -> Option<PendingReply> {
2270 self.inner
2271 .lock()
2272 .expect("pending replies mutex poisoned")
2273 .replies
2274 .remove(id)
2275 }
2276
2277 /// Atomically reject new subscriptions and fail every existing one.
2278 fn close_incoming(&self) -> usize {
2279 let replies = {
2280 let mut inner = self.inner.lock().expect("pending replies mutex poisoned");
2281 inner.incoming_closed = true;
2282 std::mem::take(&mut inner.replies)
2283 };
2284 let count = replies.len();
2285 for (_, reply) in replies {
2286 reply.fail_incoming_closed();
2287 }
2288 count
2289 }
2290
2291 /// Atomically reject new subscriptions and fail every remaining one
2292 /// because the driver has terminated.
2293 fn terminate(&self, termination: &ConnectionTermination) -> usize {
2294 let replies = {
2295 let mut inner = self.inner.lock().expect("pending replies mutex poisoned");
2296 inner.termination = Some(termination.clone());
2297 std::mem::take(&mut inner.replies)
2298 };
2299 let count = replies.len();
2300 for (_, reply) in replies {
2301 let error = connection_terminated_error(&reply.method, termination);
2302 reply.fail(error);
2303 }
2304 count
2305 }
2306}
2307
2308/// A non-owning handle used to register a request before it enters the
2309/// outgoing queue. Keeping this weak prevents escaped [`ConnectionTo`] clones
2310/// from extending the lifetime of response senders after the driver stops.
2311#[derive(Clone)]
2312struct PendingRepliesRegistrar {
2313 inner: Weak<Mutex<PendingRepliesInner>>,
2314}
2315
2316impl PendingRepliesRegistrar {
2317 fn disarm_cancellations(&self) {
2318 if let Some(inner) = self.inner.upgrade() {
2319 let inner = inner.lock().expect("pending replies mutex poisoned");
2320 for reply in inner.replies.values() {
2321 reply.cancellation_disarm.disarm();
2322 }
2323 }
2324 }
2325
2326 /// Register a response destination before the request becomes observable.
2327 ///
2328 /// Returns an error after failing `reply` when EOF has already made a
2329 /// response impossible or the connection driver is no longer running.
2330 fn subscribe(
2331 &self,
2332 id: RawJsonRpcId,
2333 reply: PendingReply,
2334 incoming_closed: &IncomingClosed,
2335 ) -> Result<(), crate::Error> {
2336 let Some(inner) = self.inner.upgrade() else {
2337 let error = if incoming_closed.is_closing() {
2338 incoming_transport_closed_error(&reply.method)
2339 } else if let Some(termination) = incoming_closed.termination() {
2340 connection_terminated_error(&reply.method, &termination)
2341 } else {
2342 crate::util::internal_error(format!(
2343 "failed to send outgoing request `{}`: connection is no longer running",
2344 reply.method
2345 ))
2346 };
2347 reply.fail(error.clone());
2348 return Err(error);
2349 };
2350
2351 let result = {
2352 let mut inner = inner.lock().expect("pending replies mutex poisoned");
2353 if inner.incoming_closed {
2354 Err((reply, None))
2355 } else if let Some(termination) = &inner.termination {
2356 Err((reply, Some(termination.clone())))
2357 } else {
2358 Ok(inner.replies.insert(id, reply))
2359 }
2360 };
2361
2362 match result {
2363 Err((rejected, termination)) => {
2364 let error = match termination {
2365 Some(termination) => {
2366 connection_terminated_error(&rejected.method, &termination)
2367 }
2368 None => incoming_transport_closed_error(&rejected.method),
2369 };
2370 rejected.fail(error.clone());
2371 Err(error)
2372 }
2373 Ok(replaced) => {
2374 if let Some(replaced) = replaced {
2375 replaced.fail(
2376 crate::Error::internal_error()
2377 .data("outgoing request ID was reused before its response arrived"),
2378 );
2379 }
2380 Ok(())
2381 }
2382 }
2383 }
2384
2385 fn set_origin(&self, id: &RawJsonRpcId, origin: RequestOrigin) {
2386 if let Some(inner) = self.inner.upgrade()
2387 && let Some(reply) = inner
2388 .lock()
2389 .expect("pending replies mutex poisoned")
2390 .replies
2391 .get_mut(id)
2392 {
2393 reply.forwarded_from = Some(origin);
2394 }
2395 }
2396
2397 fn forwarded_origin(&self, peer: RoleId, id: &RawJsonRpcId) -> Option<RequestOrigin> {
2398 let inner = self.inner.upgrade()?;
2399 let inner = inner.lock().expect("pending replies mutex poisoned");
2400 let reply = inner.replies.get(id)?;
2401 // A conductor sends requests to the same physical proxy in both
2402 // directions. The explicit successor envelope is a request *from*
2403 // its successor, not a client request the proxy can elicit against.
2404 if reply.role_id != peer
2405 || reply.method == crate::v1::schema::PROXY_METHOD_NAMES.proxy_successor
2406 || reply.cancellation_disarm.is_disarmed()
2407 {
2408 return None;
2409 }
2410 reply.forwarded_from.clone()
2411 }
2412
2413 /// Rewrite only the ACP request-scope field. Don't deserialize the whole
2414 /// request: proxies must preserve fields their SDK doesn't know.
2415 fn translate_elicitation(
2416 &self,
2417 peer: RoleId,
2418 request: &mut UntypedMessage,
2419 accepts_origin: impl FnOnce(&RequestOrigin) -> bool,
2420 ) -> Result<(), crate::Error> {
2421 if !crate::v1::schema::CreateElicitationRequest::matches_method(request.method()) {
2422 return Ok(());
2423 }
2424 let has_session_scope = request.params.get("sessionId").is_some();
2425 let Some(reference) = request.params.get_mut("requestId") else {
2426 return Ok(());
2427 };
2428 // V1 and v2 parsers can interpret a double scope differently. Never
2429 // pass an unresolved requestId through on the strength of a sessionId.
2430 if has_session_scope {
2431 return Err(crate::Error::invalid_params().data("Ambiguous elicitation scope"));
2432 }
2433 let id =
2434 RawJsonRpcId::deserialize(&*reference).map_err(|_| crate::Error::invalid_params())?;
2435 let id = self
2436 .forwarded_origin(peer, &id)
2437 .filter(accepts_origin)
2438 .and_then(RequestOrigin::live_id)
2439 .ok_or_else(|| crate::Error::invalid_params().data("Unknown forwarded request ID"))?;
2440 *reference = serde_json::to_value(id).expect("a JSON-RPC ID is JSON serializable");
2441 Ok(())
2442 }
2443
2444 fn remove(&self, id: &RawJsonRpcId) -> Option<PendingReply> {
2445 self.inner
2446 .upgrade()?
2447 .lock()
2448 .expect("pending replies mutex poisoned")
2449 .replies
2450 .remove(id)
2451 }
2452}
2453
2454impl Debug for PendingRepliesRegistrar {
2455 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2456 formatter
2457 .debug_struct("PendingRepliesRegistrar")
2458 .field("is_connected", &(self.inner.strong_count() > 0))
2459 .finish()
2460 }
2461}
2462
2463/// A request-local marker that is set when the peer asks to cancel the request.
2464///
2465/// Request handlers can get this handle from [`Responder::cancellation`] and
2466/// use it from spawned work to stop long-running request processing
2467/// cooperatively.
2468#[derive(Clone)]
2469pub struct RequestCancellation {
2470 state: Arc<RequestCancellationState>,
2471}
2472
2473struct RequestCancellationState {
2474 cancelled: AtomicBool,
2475 signal_tx: Mutex<Option<oneshot::Sender<()>>>,
2476 signal_rx: future::Shared<BoxFuture<'static, ()>>,
2477}
2478
2479impl RequestCancellation {
2480 fn new() -> Self {
2481 let (signal_tx, signal_rx) = oneshot::channel();
2482 let signal_rx = signal_rx.map(|_| ()).boxed().shared();
2483 Self {
2484 state: Arc::new(RequestCancellationState {
2485 cancelled: AtomicBool::new(false),
2486 signal_tx: Mutex::new(Some(signal_tx)),
2487 signal_rx,
2488 }),
2489 }
2490 }
2491
2492 /// Wait until the peer sends `$/cancel_request` for this request.
2493 ///
2494 /// If cancellation was already requested, this returns immediately.
2495 pub async fn cancelled(&self) {
2496 self.state.signal_rx.clone().await;
2497 }
2498
2499 /// Run request work until it completes or the peer asks to cancel it.
2500 ///
2501 /// When cancellation wins, `future` is dropped: work stops at its next
2502 /// await point, partial results are lost, and any cleanup must happen in
2503 /// `Drop` implementations. Handlers that need to flush partial results or
2504 /// run async cleanup should instead watch [`cancelled`](Self::cancelled)
2505 /// or poll [`is_cancelled`](Self::is_cancelled) from inside the work.
2506 ///
2507 /// # Errors
2508 ///
2509 /// Returns [`Error::request_cancelled`] if cancellation wins, or the
2510 /// future's own error if it finishes first.
2511 ///
2512 /// [`Error::request_cancelled`]: crate::Error::request_cancelled
2513 pub async fn run_until_cancelled<T>(
2514 &self,
2515 future: impl std::future::Future<Output = Result<T, crate::Error>>,
2516 ) -> Result<T, crate::Error> {
2517 if self.is_cancelled() {
2518 return Err(crate::Error::request_cancelled());
2519 }
2520
2521 match future::select(pin!(future), pin!(self.cancelled())).await {
2522 Either::Left((result, _)) => result,
2523 Either::Right(((), _)) => Err(crate::Error::request_cancelled()),
2524 }
2525 }
2526
2527 /// Returns whether the peer has already requested cancellation.
2528 #[must_use]
2529 pub fn is_cancelled(&self) -> bool {
2530 self.state.cancelled.load(Ordering::Acquire)
2531 }
2532
2533 fn cancel(&self) {
2534 if self.state.cancelled.swap(true, Ordering::AcqRel) {
2535 return;
2536 }
2537
2538 let signal_tx = self
2539 .state
2540 .signal_tx
2541 .lock()
2542 .expect("request cancellation signal mutex poisoned")
2543 .take();
2544
2545 // Complete the oneshot outside the lock: it wakes waiters, and
2546 // arbitrary waker code must not observe the lock held.
2547 if let Some(signal_tx) = signal_tx {
2548 let _ = signal_tx.send(());
2549 }
2550 }
2551}
2552
2553impl Debug for RequestCancellation {
2554 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2555 formatter
2556 .debug_struct("RequestCancellation")
2557 .field("is_cancelled", &self.is_cancelled())
2558 .finish_non_exhaustive()
2559 }
2560}
2561
2562/// Per-request cancellation state tracked by [`RequestCancellationRegistry`].
2563///
2564/// The full [`RequestCancellation`] marker (with its wakeup machinery) is only
2565/// allocated once a handler asks for it via [`Responder::cancellation`]; until
2566/// then an incoming `$/cancel_request` just flips the entry to `Cancelled`.
2567/// This keeps the per-request cost of the registry to a single map entry.
2568#[derive(Debug)]
2569enum RequestCancellationEntry {
2570 /// The request is in flight; no marker handed out, no cancellation yet.
2571 Armed,
2572 /// `$/cancel_request` arrived before a marker was handed out.
2573 Cancelled,
2574 /// A marker was handed out via [`Responder::cancellation`].
2575 Marker(RequestCancellation),
2576}
2577
2578/// A registered request's cancellation state, tagged with the generation of
2579/// its registration.
2580///
2581/// The generation distinguishes a registration from earlier ones that used
2582/// the same request ID, so that when a (protocol-violating) peer reuses the
2583/// ID of a request that is still in flight, the stale request's responder can
2584/// neither remove nor observe the cancellation state of the newer request.
2585#[derive(Debug)]
2586struct RequestCancellationSlot {
2587 generation: u64,
2588 entry: RequestCancellationEntry,
2589}
2590
2591#[derive(Debug, Default)]
2592struct RequestCancellationRegistryInner {
2593 slots: HashMap<RawJsonRpcId, RequestCancellationSlot>,
2594 next_generation: u64,
2595}
2596
2597#[derive(Clone, Debug, Default)]
2598struct RequestCancellationRegistry {
2599 inner: Arc<Mutex<RequestCancellationRegistryInner>>,
2600}
2601
2602#[derive(Debug)]
2603struct ResponderCancellation {
2604 id: RawJsonRpcId,
2605 generation: u64,
2606 registry: RequestCancellationRegistry,
2607}
2608
2609/// A non-owning reference to one incoming request, not just its wire ID.
2610/// Reusing an upstream ID must never transfer an old callback to its new owner.
2611#[derive(Clone)]
2612struct RequestOrigin {
2613 id: RawJsonRpcId,
2614 generation: u64,
2615 registry: Weak<Mutex<RequestCancellationRegistryInner>>,
2616 /// For a proxy forwarding on the same connection, which logical peer
2617 /// supplied the request. `None` for requests from another connection.
2618 local_peer: Option<RemoteStyle>,
2619}
2620
2621impl RequestOrigin {
2622 fn live_id(self) -> Option<RawJsonRpcId> {
2623 let registry = self.registry.upgrade()?;
2624 let inner = registry
2625 .lock()
2626 .expect("request cancellation registry mutex poisoned");
2627 let slot = inner.slots.get(&self.id)?;
2628 (slot.generation == self.generation && !slot.entry.is_cancelled()).then_some(self.id)
2629 }
2630}
2631
2632impl RequestCancellationEntry {
2633 fn is_cancelled(&self) -> bool {
2634 match self {
2635 Self::Armed => false,
2636 Self::Cancelled => true,
2637 Self::Marker(marker) => marker.is_cancelled(),
2638 }
2639 }
2640}
2641
2642impl RequestCancellationRegistry {
2643 fn new() -> Self {
2644 Self::default()
2645 }
2646
2647 fn register(&self, id: &RawJsonRpcId) -> ResponderCancellation {
2648 let generation = {
2649 let mut inner = self
2650 .inner
2651 .lock()
2652 .expect("request cancellation registry mutex poisoned");
2653 let generation = inner.next_generation;
2654 inner.next_generation += 1;
2655 if inner
2656 .slots
2657 .insert(
2658 id.clone(),
2659 RequestCancellationSlot {
2660 generation,
2661 entry: RequestCancellationEntry::Armed,
2662 },
2663 )
2664 .is_some()
2665 {
2666 tracing::debug!(
2667 ?id,
2668 "peer reused the ID of a request that is still in flight"
2669 );
2670 }
2671 generation
2672 };
2673 ResponderCancellation {
2674 id: id.clone(),
2675 generation,
2676 registry: self.clone(),
2677 }
2678 }
2679
2680 /// Get the cancellation marker for a registered request, creating it on
2681 /// first use. Repeated calls return markers that share the same state.
2682 ///
2683 /// Exception: when the registration is stale (a protocol-violating peer
2684 /// reused this request ID and the slot now belongs to a newer request, or
2685 /// was already removed by it), every call returns a fresh *detached*
2686 /// marker. Detached markers can never fire, and detached markers from
2687 /// repeated calls do not share state with each other.
2688 fn marker(&self, id: &RawJsonRpcId, generation: u64) -> RequestCancellation {
2689 let mut inner = self
2690 .inner
2691 .lock()
2692 .expect("request cancellation registry mutex poisoned");
2693 let Some(slot) = inner.slots.get_mut(id) else {
2694 // The slot lives as long as the responder that owns it, so this
2695 // is only reachable if the peer reused this request ID and the
2696 // newer request's responder already removed the replacement slot.
2697 // Hand out a detached marker rather than panicking.
2698 return RequestCancellation::new();
2699 };
2700 if slot.generation != generation {
2701 // The peer reused this request ID while the request was still in
2702 // flight, and the slot now belongs to the newer request. Hand the
2703 // stale responder a detached marker instead of cross-wiring the
2704 // two requests' cancellation states.
2705 return RequestCancellation::new();
2706 }
2707 let entry = &mut slot.entry;
2708 match entry {
2709 RequestCancellationEntry::Marker(marker) => marker.clone(),
2710 RequestCancellationEntry::Armed => {
2711 let marker = RequestCancellation::new();
2712 *entry = RequestCancellationEntry::Marker(marker.clone());
2713 marker
2714 }
2715 RequestCancellationEntry::Cancelled => {
2716 // No one can be waiting on a marker that did not exist yet,
2717 // so firing it while holding the registry lock is fine.
2718 let marker = RequestCancellation::new();
2719 marker.cancel();
2720 *entry = RequestCancellationEntry::Marker(marker.clone());
2721 marker
2722 }
2723 }
2724 }
2725
2726 fn cancel_if_requested(&self, dispatch: &Dispatch) -> Result<bool, crate::Error> {
2727 let Some(request_id) = cancellation_request_id(dispatch)? else {
2728 return Ok(false);
2729 };
2730 Ok(self.cancel(&request_id))
2731 }
2732
2733 /// Mark whichever request currently owns `request_id` as cancelled.
2734 fn cancel(&self, request_id: &RawJsonRpcId) -> bool {
2735 let marker = {
2736 let mut inner = self
2737 .inner
2738 .lock()
2739 .expect("request cancellation registry mutex poisoned");
2740 let Some(slot) = inner.slots.get_mut(request_id) else {
2741 return false;
2742 };
2743 let entry = &mut slot.entry;
2744 match entry {
2745 RequestCancellationEntry::Marker(marker) => marker.clone(),
2746 RequestCancellationEntry::Cancelled => return true,
2747 RequestCancellationEntry::Armed => {
2748 *entry = RequestCancellationEntry::Cancelled;
2749 return true;
2750 }
2751 }
2752 };
2753
2754 // Fire the marker outside the registry lock: waking waiters runs
2755 // arbitrary waker code that must not observe the lock held.
2756 marker.cancel();
2757 true
2758 }
2759
2760 /// Remove the slot for `request_id`, but only if it still belongs to the
2761 /// registration identified by `generation`.
2762 fn remove(&self, request_id: &RawJsonRpcId, generation: u64) {
2763 let mut inner = self
2764 .inner
2765 .lock()
2766 .expect("request cancellation registry mutex poisoned");
2767 if inner
2768 .slots
2769 .get(request_id)
2770 .is_some_and(|slot| slot.generation == generation)
2771 {
2772 inner.slots.remove(request_id);
2773 }
2774 }
2775}
2776
2777impl ResponderCancellation {
2778 fn cancellation(&self) -> RequestCancellation {
2779 self.registry.marker(&self.id, self.generation)
2780 }
2781
2782 /// Whether the peer has cancelled this request, without allocating a
2783 /// marker.
2784 fn is_cancelled(&self) -> bool {
2785 let inner = self
2786 .registry
2787 .inner
2788 .lock()
2789 .expect("request cancellation registry mutex poisoned");
2790 let Some(slot) = inner.slots.get(&self.id) else {
2791 return false;
2792 };
2793 if slot.generation != self.generation {
2794 return false;
2795 }
2796 slot.entry.is_cancelled()
2797 }
2798}
2799
2800impl Drop for ResponderCancellation {
2801 fn drop(&mut self) {
2802 self.registry.remove(&self.id, self.generation);
2803 }
2804}
2805
2806fn cancellation_request_id(dispatch: &Dispatch) -> Result<Option<RawJsonRpcId>, crate::Error> {
2807 let Dispatch::Notification(message) = dispatch else {
2808 return Ok(None);
2809 };
2810 cancellation_request_id_from_message(message)
2811}
2812
2813fn cancellation_request_id_from_message(
2814 message: &UntypedMessage,
2815) -> Result<Option<RawJsonRpcId>, crate::Error> {
2816 let (method, params) = peel_successor_envelopes(&message.method, &message.params);
2817 if !crate::v1::schema::CancelRequestNotification::matches_method(method) {
2818 return Ok(None);
2819 }
2820
2821 let notification = crate::v1::schema::CancelRequestNotification::parse_message(method, params)?;
2822 Ok(Some(notification.request_id.into()))
2823}
2824
2825/// Peel any [`SuccessorMessage`] envelopes off a notification by reference,
2826/// returning the innermost method and params.
2827///
2828/// This only peeks at the envelope's `method`/`params` fields instead of
2829/// deserializing the envelope, for two reasons:
2830///
2831/// - It avoids deep-cloning the params of every wrapped notification on the
2832/// hot dispatch path just to inspect the inner method name.
2833/// - It is deliberately lenient: a malformed envelope is left as-is here and
2834/// flows on to the handler chain, which is responsible for reporting it.
2835///
2836/// [`SuccessorMessage`]: crate::schema::SuccessorMessage
2837fn peel_successor_envelopes<'message>(
2838 mut method: &'message str,
2839 mut params: &'message serde_json::Value,
2840) -> (&'message str, &'message serde_json::Value) {
2841 while crate::schema::SuccessorMessage::<UntypedMessage>::matches_method(method) {
2842 let Some(inner_method) = params.get("method").and_then(serde_json::Value::as_str) else {
2843 break;
2844 };
2845 method = inner_method;
2846 params = params.get("params").unwrap_or(&serde_json::Value::Null);
2847 }
2848 (method, params)
2849}
2850
2851/// Whether a notification is a `$/cancel_request`, even when it is still
2852/// wrapped in `proxy/successor` envelopes.
2853///
2854/// `$/cancel_request` is connection-scoped: its `requestId` was allocated on
2855/// the connection the notification arrived over and means nothing on any
2856/// other connection. Generic forwarding code (such as
2857/// [`ConnectionTo::send_proxied_message_to`]) uses this check to drop the raw
2858/// notification instead of tunneling it across a hop; the cancellation still
2859/// propagates because [`forward_response_to`](SentRequest::forward_response_to)
2860/// re-issues it with the forwarded request's own ID.
2861///
2862/// Checking a notification whose method is not the successor envelope is a
2863/// plain method-name comparison. Only successor-wrapped notifications pay for
2864/// a serialization to peel the envelope.
2865#[must_use]
2866pub fn is_cancel_request_notification<N: JsonRpcNotification>(notification: &N) -> bool {
2867 let method = notification.method();
2868 if crate::v1::schema::CancelRequestNotification::matches_method(method) {
2869 return true;
2870 }
2871 if !crate::schema::SuccessorMessage::<UntypedMessage>::matches_method(method) {
2872 return false;
2873 }
2874
2875 match notification.to_untyped_message() {
2876 Ok(untyped) => {
2877 let (method, _params) = peel_successor_envelopes(&untyped.method, &untyped.params);
2878 crate::v1::schema::CancelRequestNotification::matches_method(method)
2879 }
2880 Err(error) => {
2881 tracing::debug!(
2882 error = ?crate::util::redacted_error(error.code),
2883 "failed to inspect successor-wrapped notification for cancellation"
2884 );
2885 false
2886 }
2887 }
2888}
2889
2890/// Where the response to an incoming request is sent.
2891///
2892/// A request is answered at most once; a duplicate completion is ignored.
2893///
2894/// While a handler attempt for the request is running (see
2895/// [`begin_handler_attempt`](Self::begin_handler_attempt)), the automatic
2896/// error for a dropped [`Responder`] is held back: if the handler then
2897/// returns an error, that error is the response, not the generic fallback.
2898#[derive(Clone, Debug, Default)]
2899struct ResponseDestination {
2900 state: Arc<ResponseDestinationState>,
2901}
2902
2903#[derive(Debug, Default)]
2904struct ResponseDestinationState {
2905 completed: AtomicBool,
2906 attempts: Mutex<HandlerAttempts>,
2907}
2908
2909#[derive(Debug, Default)]
2910struct HandlerAttempts {
2911 active: usize,
2912 deferred: Option<AbandonedResponse>,
2913}
2914
2915/// The automatic error response for a [`Responder`] dropped without replying.
2916#[derive(Debug)]
2917struct AbandonedResponse {
2918 message_tx: OutgoingMessageTx,
2919 connection_state: IncomingClosed,
2920 message: OutgoingMessage,
2921}
2922
2923impl AbandonedResponse {
2924 fn send(self) {
2925 // Re-check: shutdown may have begun while the response was deferred.
2926 if self.connection_state.is_shutting_down() {
2927 tracing::debug!("not answering dropped responder: connection is shutting down");
2928 return;
2929 }
2930 if let Err(error) = send_raw_message(&self.message_tx, self.message) {
2931 tracing::debug!(
2932 error = ?crate::util::redacted_error(error.code),
2933 "could not answer request whose responder was dropped"
2934 );
2935 }
2936 }
2937}
2938
2939/// A running handler attempt for one request; see [`ResponseDestination`].
2940struct HandlerAttempt {
2941 destination: ResponseDestination,
2942}
2943
2944impl Drop for HandlerAttempt {
2945 fn drop(&mut self) {
2946 let deferred = {
2947 let mut attempts = self.destination.attempts();
2948 attempts.active -= 1;
2949 if attempts.active == 0 {
2950 attempts.deferred.take()
2951 } else {
2952 None
2953 }
2954 };
2955 if let Some(deferred) = deferred {
2956 deferred.send();
2957 }
2958 }
2959}
2960
2961impl ResponseDestination {
2962 fn individual() -> Self {
2963 Self::default()
2964 }
2965
2966 fn attempts(&self) -> std::sync::MutexGuard<'_, HandlerAttempts> {
2967 self.state
2968 .attempts
2969 .lock()
2970 .expect("response destination mutex poisoned")
2971 }
2972
2973 fn is_completed(&self) -> bool {
2974 self.state.completed.load(Ordering::Acquire)
2975 }
2976
2977 fn complete(self, response: RawJsonRpcMessage) -> Option<TransportFrame> {
2978 if self.state.completed.swap(true, Ordering::AcqRel) {
2979 tracing::warn!("Ignoring duplicate completion of JSON-RPC request");
2980 return None;
2981 }
2982
2983 Some(TransportFrame::Single(response))
2984 }
2985
2986 fn begin_handler_attempt(&self) -> HandlerAttempt {
2987 self.attempts().active += 1;
2988 HandlerAttempt {
2989 destination: self.clone(),
2990 }
2991 }
2992
2993 /// Send, or defer until the running handler attempt ends, the automatic
2994 /// error for a dropped responder.
2995 fn abandon(&self, response: AbandonedResponse) {
2996 {
2997 let mut attempts = self.attempts();
2998 if attempts.active > 0 {
2999 attempts.deferred = Some(response);
3000 return;
3001 }
3002 }
3003 response.send();
3004 }
3005
3006 /// A handler error answers the request; drop any deferred fallback.
3007 fn discard_abandoned(&self) {
3008 self.attempts().deferred = None;
3009 }
3010}
3011
3012#[derive(Clone, Debug)]
3013struct RequestReplyTarget {
3014 id: RawJsonRpcId,
3015 method: String,
3016 destination: ResponseDestination,
3017}
3018
3019#[derive(Clone)]
3020struct ResponseReplyTarget {
3021 id: RawJsonRpcId,
3022 method: String,
3023 sender: Arc<Mutex<Option<oneshot::Sender<ResponsePayload>>>>,
3024 ordering: ResponseOrdering,
3025 dispatch: ResponseDispatch,
3026}
3027
3028impl ResponseReplyTarget {
3029 fn route(self, result: Result<serde_json::Value, crate::Error>) {
3030 let sender = self
3031 .sender
3032 .lock()
3033 .expect("response reply mutex poisoned")
3034 .take();
3035 let Some(sender) = sender else {
3036 tracing::debug!(
3037 method = %self.method,
3038 id = ?self.id,
3039 "response was already routed to its local awaiter"
3040 );
3041 return;
3042 };
3043
3044 let ack_tx = self.dispatch.acknowledgment(&self.ordering);
3045 if sender.send(ResponsePayload { result, ack_tx }).is_err() {
3046 tracing::debug!(
3047 method = %self.method,
3048 id = ?self.id,
3049 "dropped response because local receiver was gone"
3050 );
3051 }
3052 }
3053}
3054
3055#[derive(Clone, Default)]
3056struct ResponseDispatch {
3057 state: Arc<Mutex<ResponseDispatchState>>,
3058}
3059
3060#[derive(Default)]
3061struct ResponseDispatchState {
3062 complete: bool,
3063 ack_rx: Option<oneshot::Receiver<()>>,
3064}
3065
3066impl ResponseDispatch {
3067 fn acknowledgment(&self, ordering: &ResponseOrdering) -> Option<oneshot::Sender<()>> {
3068 if !ordering.is_ordered() {
3069 return None;
3070 }
3071
3072 let mut state = self.state.lock().expect("response dispatch mutex poisoned");
3073 if state.complete {
3074 return None;
3075 }
3076
3077 let (ack_tx, ack_rx) = oneshot::channel();
3078 let previous_ack = state.ack_rx.replace(ack_rx);
3079 debug_assert!(
3080 previous_ack.is_none(),
3081 "a response dispatch can only be routed once"
3082 );
3083 Some(ack_tx)
3084 }
3085
3086 fn complete(&self) -> Option<oneshot::Receiver<()>> {
3087 let mut state = self.state.lock().expect("response dispatch mutex poisoned");
3088 state.complete = true;
3089 state.ack_rx.take()
3090 }
3091}
3092
3093enum HandlerErrorTarget {
3094 Request(RequestReplyTarget),
3095 Response(ResponseReplyTarget),
3096}
3097
3098impl HandlerErrorTarget {
3099 fn begin_handler_attempt(&self) -> Option<HandlerAttempt> {
3100 match self {
3101 Self::Request(target) => Some(target.destination.begin_handler_attempt()),
3102 Self::Response(_) => None,
3103 }
3104 }
3105}
3106
3107#[derive(Debug)]
3108enum OutgoingMessage {
3109 /// Close the outgoing application queue and acknowledge after every
3110 /// already-accepted message has entered the raw transport queue.
3111 CloseAfterDraining { done: oneshot::Sender<()> },
3112
3113 /// Send a request to the server.
3114 Request {
3115 /// id assigned to this request (generated by sender)
3116 id: RawJsonRpcId,
3117
3118 /// the original method
3119 method: String,
3120
3121 /// The logical message before peer-direction wrapping.
3122 untyped: UntypedMessage,
3123
3124 /// How to transform the logical message for its target peer.
3125 remote_style: crate::role::RemoteStyle,
3126
3127 /// Optional prerequisite that must finish before the request becomes
3128 /// visible on the transport.
3129 readiness: Option<RequestReadiness>,
3130 },
3131
3132 /// Send a notification to the server.
3133 Notification {
3134 /// the message to send; this may have a distinct method
3135 /// depending on the peer
3136 untyped: UntypedMessage,
3137 },
3138
3139 /// Send a response to a message from the server
3140 Response {
3141 id: RawJsonRpcId,
3142
3143 /// Method of the incoming request this response completes.
3144 method: String,
3145
3146 response: Result<serde_json::Value, crate::Error>,
3147
3148 destination: ResponseDestination,
3149 },
3150
3151 /// Send an Error Response that cannot be correlated to a request ID.
3152 UncorrelatedErrorResponse {
3153 error: crate::Error,
3154 destination: ResponseDestination,
3155 },
3156}
3157
3158impl OutgoingMessage {
3159 /// Kind, method, and ID only; params, results, and errors can carry
3160 /// credentials and must not appear in ordinary logs.
3161 fn log_summary(&self) -> (&'static str, Option<&str>, Option<&RawJsonRpcId>) {
3162 match self {
3163 Self::CloseAfterDraining { .. } => ("close_after_draining", None, None),
3164 Self::Request { id, method, .. } => ("request", Some(method), Some(id)),
3165 Self::Notification { untyped } => ("notification", Some(&untyped.method), None),
3166 Self::Response { id, method, .. } => ("response", Some(method), Some(id)),
3167 Self::UncorrelatedErrorResponse { .. } => ("uncorrelated_error_response", None, None),
3168 }
3169 }
3170}
3171
3172/// Whether a dispatch handler handled a message or passed it on.
3173#[must_use]
3174#[derive(Debug)]
3175pub enum Handled<T> {
3176 /// The message was handled
3177 Yes,
3178
3179 /// The message was not handled; returns the original value.
3180 ///
3181 /// If `retry` is true,
3182 No {
3183 /// The message to be passed to subsequent handlers
3184 /// (typically the original message, but it may have been
3185 /// mutated.)
3186 message: T,
3187
3188 /// If true, request the message to be queued and retried with
3189 /// dynamic handlers as they are added.
3190 ///
3191 /// This is used for managing session updates since the dynamic
3192 /// handler for a session cannot be added until the response to the
3193 /// new session request has been processed and there may be updates
3194 /// that get processed at the same time.
3195 retry: bool,
3196 },
3197}
3198
3199/// Trait for converting handler return values into [`Handled`].
3200///
3201/// This trait allows handlers to return either `()` (which becomes `Handled::Yes`)
3202/// or an explicit `Handled<T>` value for more control over handler propagation.
3203pub trait IntoHandled<T> {
3204 /// Convert this value into a `Handled<T>`.
3205 fn into_handled(self) -> Handled<T>;
3206}
3207
3208impl<T> IntoHandled<T> for () {
3209 fn into_handled(self) -> Handled<T> {
3210 Handled::Yes
3211 }
3212}
3213
3214impl<T> IntoHandled<T> for Handled<T> {
3215 fn into_handled(self) -> Handled<T> {
3216 self
3217 }
3218}
3219
3220/// Connection context for sending messages and spawning tasks.
3221///
3222/// This is the primary handle for interacting with the JSON-RPC connection from
3223/// within handler callbacks. You can use it to:
3224///
3225/// * Send requests and notifications to the other side
3226/// * Spawn concurrent tasks that run alongside the connection
3227/// * Respond to requests (via [`Responder`] which wraps this)
3228///
3229/// # Cloning
3230///
3231/// `ConnectionTo` is cheaply cloneable - all clones refer to the same underlying connection.
3232/// This makes it easy to share across async tasks.
3233///
3234/// # Event Loop and Concurrency
3235///
3236/// Handler callbacks run on the event loop, which means the connection cannot process new
3237/// messages while your handler is running. Use [`spawn`](Self::spawn) to offload any
3238/// expensive or blocking work to concurrent tasks.
3239///
3240/// See the [Event Loop and Concurrency](Builder#event-loop-and-concurrency) section
3241/// for more details.
3242#[derive(Clone, Debug)]
3243pub struct ConnectionTo<Counterpart: Role> {
3244 counterpart: Counterpart,
3245 message_tx: OutgoingMessageTx,
3246 task_tx: TaskTx,
3247 dynamic_handler_tx: mpsc::UnboundedSender<DynamicHandlerMessage<Counterpart>>,
3248 transport_completion: SharedTransportCompletion,
3249 pending_replies: PendingRepliesRegistrar,
3250 protocol_mode: ProtocolMode,
3251 incoming_closed: IncomingClosed,
3252 protected_operations: Arc<Mutex<ProtectedOperations>>,
3253 runner_error_scope: Option<run::RunnerErrorScope>,
3254}
3255
3256type SharedTransportCompletion = future::Shared<BoxFuture<'static, Result<(), crate::Error>>>;
3257
3258type SharedCompletionSignal = future::Shared<BoxFuture<'static, ()>>;
3259
3260#[derive(Default)]
3261struct ProtectedOperations {
3262 pending: Vec<oneshot::Receiver<()>>,
3263 joining: Option<SharedCompletionSignal>,
3264}
3265
3266impl Debug for ProtectedOperations {
3267 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3268 formatter
3269 .debug_struct("ProtectedOperations")
3270 .field("pending", &self.pending.len())
3271 .field("joining", &self.joining.is_some())
3272 .finish_non_exhaustive()
3273 }
3274}
3275
3276fn completion_signal() -> (oneshot::Sender<()>, SharedCompletionSignal) {
3277 let (tx, rx) = oneshot::channel();
3278 let signal = async move {
3279 // Dropping a sender (e.g. foreground failure) is not success.
3280 if rx.await.is_err() {
3281 future::pending::<()>().await;
3282 }
3283 }
3284 .boxed()
3285 .shared();
3286 (tx, signal)
3287}
3288
3289#[derive(Clone)]
3290struct IncomingClosed {
3291 state: Arc<IncomingClosedState>,
3292}
3293
3294struct IncomingClosedState {
3295 closing: AtomicBool,
3296 closed: AtomicBool,
3297 signal_tx: Mutex<Option<oneshot::Sender<()>>>,
3298 signal_rx: future::Shared<BoxFuture<'static, ()>>,
3299 shutdown_tx: Mutex<Option<oneshot::Sender<()>>>,
3300 #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3301 shutdown_rx: SharedCompletionSignal,
3302 termination: Mutex<Option<ConnectionTermination>>,
3303 terminated_tx: Mutex<Option<oneshot::Sender<()>>>,
3304 terminated_rx: SharedCompletionSignal,
3305}
3306
3307impl IncomingClosed {
3308 fn new() -> Self {
3309 let (signal_tx, signal_rx) = oneshot::channel();
3310 let (shutdown_tx, shutdown_rx) = oneshot::channel();
3311 #[cfg(not(any(feature = "unstable_mcp_over_acp", test)))]
3312 drop(shutdown_rx);
3313 let (terminated_tx, terminated_rx) = oneshot::channel();
3314 Self {
3315 state: Arc::new(IncomingClosedState {
3316 closing: AtomicBool::new(false),
3317 closed: AtomicBool::new(false),
3318 signal_tx: Mutex::new(Some(signal_tx)),
3319 signal_rx: signal_rx.map(|_| ()).boxed().shared(),
3320 shutdown_tx: Mutex::new(Some(shutdown_tx)),
3321 #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3322 shutdown_rx: shutdown_rx.map(|_| ()).boxed().shared(),
3323 termination: Mutex::new(None),
3324 terminated_tx: Mutex::new(Some(terminated_tx)),
3325 terminated_rx: terminated_rx.map(|_| ()).boxed().shared(),
3326 }),
3327 }
3328 }
3329
3330 fn begin_close(&self) {
3331 self.state.closing.store(true, Ordering::Release);
3332 self.request_shutdown();
3333 }
3334
3335 fn request_shutdown(&self) {
3336 if let Some(tx) = self
3337 .state
3338 .shutdown_tx
3339 .lock()
3340 .expect("shutdown signal mutex poisoned")
3341 .take()
3342 {
3343 let _ = tx.send(());
3344 }
3345 }
3346
3347 /// Whether the connection has begun shutting down (incoming EOF, a
3348 /// finished foreground, an actor error) or has already terminated.
3349 fn is_shutting_down(&self) -> bool {
3350 self.state
3351 .shutdown_tx
3352 .lock()
3353 .expect("shutdown signal mutex poisoned")
3354 .is_none()
3355 || self.termination().is_some()
3356 }
3357
3358 fn finish_close(&self) {
3359 self.state.closed.store(true, Ordering::Release);
3360 let signal_tx = self
3361 .state
3362 .signal_tx
3363 .lock()
3364 .expect("incoming-close signal mutex poisoned")
3365 .take();
3366
3367 if let Some(signal_tx) = signal_tx {
3368 let _ = signal_tx.send(());
3369 }
3370 }
3371
3372 async fn closed(&self) {
3373 self.state.signal_rx.clone().await;
3374 }
3375
3376 fn is_closed(&self) -> bool {
3377 self.state.closed.load(Ordering::Acquire)
3378 }
3379
3380 fn is_closing(&self) -> bool {
3381 self.state.closing.load(Ordering::Acquire)
3382 }
3383
3384 /// Record the termination reason. Returns `false` if one was already set.
3385 fn set_termination(&self, termination: ConnectionTermination) -> bool {
3386 let mut slot = self
3387 .state
3388 .termination
3389 .lock()
3390 .expect("termination mutex poisoned");
3391 if slot.is_some() {
3392 return false;
3393 }
3394 *slot = Some(termination);
3395 true
3396 }
3397
3398 fn signal_terminated(&self) {
3399 if let Some(tx) = self
3400 .state
3401 .terminated_tx
3402 .lock()
3403 .expect("terminated signal mutex poisoned")
3404 .take()
3405 {
3406 let _ = tx.send(());
3407 }
3408 }
3409
3410 fn termination(&self) -> Option<ConnectionTermination> {
3411 self.state
3412 .termination
3413 .lock()
3414 .expect("termination mutex poisoned")
3415 .clone()
3416 }
3417
3418 async fn terminated(&self) -> ConnectionTermination {
3419 self.state.terminated_rx.clone().await;
3420 self.termination()
3421 .expect("termination is recorded before it is signalled")
3422 }
3423}
3424
3425/// Publishes the connection's termination exactly once: when the driver
3426/// completes via [`Self::finish`], or synchronously when the driver future is
3427/// dropped first.
3428struct TerminationGuard {
3429 incoming_closed: IncomingClosed,
3430 pending_replies: PendingReplies,
3431}
3432
3433impl TerminationGuard {
3434 fn finish(self, termination: ConnectionTermination) {
3435 self.publish(termination);
3436 }
3437
3438 fn publish(&self, termination: ConnectionTermination) {
3439 if !self.incoming_closed.set_termination(termination.clone()) {
3440 return;
3441 }
3442 // Record first, so a requester woken by its failure observes the
3443 // termination; then fail requests before waking `terminated()`.
3444 let pending_reply_count = self.pending_replies.terminate(&termination);
3445 tracing::debug!(
3446 termination = termination.kind(),
3447 pending_reply_count,
3448 "Connection terminated"
3449 );
3450 self.incoming_closed.signal_terminated();
3451 }
3452}
3453
3454impl Drop for TerminationGuard {
3455 fn drop(&mut self) {
3456 // No-op after `finish`.
3457 self.publish(ConnectionTermination::Dropped);
3458 }
3459}
3460
3461impl Debug for IncomingClosed {
3462 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3463 formatter
3464 .debug_struct("IncomingClosed")
3465 .field("is_closing", &self.is_closing())
3466 .field("is_closed", &self.is_closed())
3467 .finish_non_exhaustive()
3468 }
3469}
3470
3471/// Stable discriminator stored in the `data.reason` field of errors produced
3472/// when the incoming transport reaches clean EOF before a request receives its
3473/// response.
3474///
3475/// The `data` field is informational. Use [`is_incoming_transport_closed`] to
3476/// detect these errors: a peer can send this value in its own error data.
3477pub const INCOMING_TRANSPORT_CLOSED_REASON: &str = "incoming_transport_closed";
3478
3479/// Return whether `error` reports that the incoming transport reached clean
3480/// EOF before a request received its response.
3481///
3482/// Only errors the SDK produced for its own connection match. An error
3483/// response received from a peer never does, even when its `data.reason` is
3484/// [`INCOMING_TRANSPORT_CLOSED_REASON`], and neither does an error built from
3485/// the same code, message, and data.
3486#[must_use]
3487pub fn is_incoming_transport_closed(error: &crate::Error) -> bool {
3488 error.origin == crate::error::ErrorOrigin::IncomingTransportClosed
3489}
3490
3491fn incoming_transport_closed_error(method: &str) -> crate::Error {
3492 let mut error = crate::Error::internal_error();
3493 error.message = "Incoming transport closed".to_string();
3494 error.origin = crate::error::ErrorOrigin::IncomingTransportClosed;
3495 error.data(serde_json::json!({
3496 "reason": INCOMING_TRANSPORT_CLOSED_REASON,
3497 "method": method,
3498 }))
3499}
3500
3501/// Unlike the cleanup coordinator below, check success before polling delivery:
3502/// an already-ready success must not resume a message handler into another
3503/// dispatch.
3504fn run_incoming_until_foreground_succeeds(
3505 incoming: impl Future<Output = Result<(), crate::Error>>,
3506 foreground_succeeded: SharedCompletionSignal,
3507 incoming_closed: IncomingClosed,
3508) -> impl Future<Output = Result<(), crate::Error>> {
3509 let mut incoming = Box::pin(incoming);
3510 future::poll_fn(move |cx| {
3511 if foreground_succeeded.clone().poll_unpin(cx).is_ready() && !incoming_closed.is_closing() {
3512 return std::task::Poll::Ready(Ok(()));
3513 }
3514 // A close callback already underway is protected. Its result is polled
3515 // before stopping, so callback errors retain their existing precedence.
3516 incoming.as_mut().poll(cx)
3517 })
3518}
3519
3520/// Run the connection background alongside its foreground while ensuring that
3521/// a foreground woken by incoming EOF cannot cancel close callbacks midway.
3522fn run_until_connection_close<R>(
3523 background: impl Future<Output = Result<(), crate::Error>>,
3524 foreground: impl Future<Output = Result<R, crate::Error>>,
3525 incoming_closed: IncomingClosed,
3526) -> impl Future<Output = Result<R, crate::Error>> {
3527 // Box these before constructing the returned future. Keeping the generic
3528 // connection actors directly in this async state would substantially grow
3529 // every `connect_*` future.
3530 let background = Box::pin(background);
3531 let foreground = Box::pin(foreground);
3532
3533 async move {
3534 match future::select(background, foreground).await {
3535 Either::Left((background_result, foreground)) => {
3536 background_result?;
3537 foreground.await
3538 }
3539 Either::Right((foreground_result, background)) => {
3540 if !incoming_closed.is_closing() {
3541 return foreground_result;
3542 }
3543
3544 match future::select(background, Box::pin(incoming_closed.closed())).await {
3545 Either::Left((background_result, _)) => {
3546 background_result?;
3547 foreground_result
3548 }
3549 Either::Right(((), background)) => {
3550 // Poll the background first once more so an error returned
3551 // by the just-finished close callback wins over the ready
3552 // foreground result.
3553 crate::util::run_until(background, future::ready(foreground_result)).await
3554 }
3555 }
3556 }
3557 }
3558 }
3559}
3560
3561impl<Counterpart: Role> ConnectionTo<Counterpart> {
3562 fn new(
3563 counterpart: Counterpart,
3564 message_tx: mpsc::UnboundedSender<OutgoingMessage>,
3565 task_tx: mpsc::UnboundedSender<Task>,
3566 dynamic_handler_tx: mpsc::UnboundedSender<DynamicHandlerMessage<Counterpart>>,
3567 transport_completion: SharedTransportCompletion,
3568 pending_replies: PendingRepliesRegistrar,
3569 protocol_mode: ProtocolMode,
3570 ) -> Self {
3571 Self {
3572 counterpart,
3573 message_tx,
3574 task_tx,
3575 dynamic_handler_tx,
3576 transport_completion,
3577 pending_replies,
3578 protocol_mode,
3579 incoming_closed: IncomingClosed::new(),
3580 protected_operations: Arc::default(),
3581 runner_error_scope: None,
3582 }
3583 }
3584
3585 pub(crate) fn with_runner_error_scope(mut self, scope: run::RunnerErrorScope) -> Self {
3586 self.runner_error_scope = Some(scope);
3587 self
3588 }
3589
3590 pub(crate) fn finish_runner_error(
3591 &self,
3592 error: crate::Error,
3593 ) -> impl Future<Output = ()> + Send + '_ {
3594 if let Some(scope) = &self.runner_error_scope {
3595 Either::Left(scope.finish(error))
3596 } else {
3597 // Unscoped runners belong to the connection itself.
3598 self.request_shutdown();
3599 Either::Right(self.wait_protected_operations())
3600 }
3601 }
3602
3603 /// Spawn only a connection-owned supervisor whose async cleanup must finish
3604 /// before the driver returns. Ordinary application work must use `spawn`.
3605 #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3606 #[track_caller]
3607 pub(crate) fn spawn_protected(
3608 &self,
3609 task: impl IntoFuture<Output = Result<(), crate::Error>, IntoFuture: Send + 'static>,
3610 ) -> Result<(), crate::Error> {
3611 let mut state = self
3612 .protected_operations
3613 .lock()
3614 .expect("protected operations mutex poisoned");
3615 if state.joining.is_some() {
3616 return Err(crate::Error::request_cancelled());
3617 }
3618 // Reap completed acknowledgments at admission, rather than retaining
3619 // every operation for the entire lifetime of the connection.
3620 state
3621 .pending
3622 .retain_mut(|done| matches!(done.try_recv(), Ok(None)));
3623 let (done_tx, done_rx) = oneshot::channel();
3624 let task = task.into_future();
3625 self.spawn(async move {
3626 let result = task.await;
3627 let _ = done_tx.send(());
3628 result
3629 })?;
3630 state.pending.push(done_rx);
3631 Ok(())
3632 }
3633
3634 pub(crate) async fn wait_protected_operations(&self) {
3635 let joining = {
3636 let mut state = self
3637 .protected_operations
3638 .lock()
3639 .expect("protected operations mutex poisoned");
3640 if state.joining.is_none() {
3641 let operations = std::mem::take(&mut state.pending);
3642 state.joining = Some(
3643 async move {
3644 for operation in operations {
3645 let _ = operation.await;
3646 }
3647 }
3648 .boxed()
3649 .shared(),
3650 );
3651 }
3652 state.joining.as_ref().expect("join initialized").clone()
3653 };
3654 joining.await;
3655 }
3656
3657 pub(crate) fn request_shutdown(&self) {
3658 self.incoming_closed.request_shutdown();
3659 }
3660
3661 /// Early cancellation for owned native work, before close callbacks or drain.
3662 #[cfg(any(feature = "unstable_mcp_over_acp", test))]
3663 pub(crate) async fn shutdown_requested(&self) {
3664 self.incoming_closed.state.shutdown_rx.clone().await;
3665 }
3666
3667 /// Return the counterpart role this connection is talking to.
3668 pub fn counterpart(&self) -> Counterpart {
3669 self.counterpart.clone()
3670 }
3671
3672 /// Wait until the incoming transport reaches clean EOF.
3673 ///
3674 /// Transport closure means that no more messages or responses can arrive.
3675 /// Pending requests are failed first; this completes after registered
3676 /// [`Builder::on_close`] callbacks finish.
3677 /// It does not automatically cancel the future passed to
3678 /// [`Builder::connect_with`]; use [`Builder::on_close`] when the connection
3679 /// should run application-specific cleanup or terminate that future.
3680 ///
3681 /// This never completes if the connection ends some other way; use
3682 /// [`terminated`](Self::terminated) to observe every termination.
3683 pub async fn incoming_closed(&self) {
3684 self.incoming_closed.closed().await;
3685 }
3686
3687 /// Return whether clean incoming-EOF processing has completed.
3688 ///
3689 /// This remains `false` while [`Builder::on_close`] callbacks are running.
3690 #[must_use]
3691 pub fn is_incoming_closed(&self) -> bool {
3692 self.incoming_closed.is_closed()
3693 }
3694
3695 /// Wait until the connection driver has terminated, for any reason.
3696 ///
3697 /// This is the universal terminal event for a connection driven by
3698 /// [`Builder::connect_to`] or [`Builder::connect_with`]. Unlike
3699 /// [`incoming_closed`](Self::incoming_closed), it also completes after
3700 /// transport errors, handler or close-callback errors, foreground
3701 /// completion, and a dropped driver future.
3702 ///
3703 /// The termination is published once, synchronously, as the driver future
3704 /// returns (or is dropped). At that point:
3705 ///
3706 /// - No further handler, close callback, runner, or
3707 /// [`spawn`](Self::spawn)ed task of this connection will run; each has
3708 /// completed or been dropped.
3709 /// - Every request still awaiting a response has been failed. Requests
3710 /// failed earlier by clean incoming EOF satisfy
3711 /// [`is_incoming_transport_closed`](crate::is_incoming_transport_closed);
3712 /// the rest satisfy [`is_connection_terminated`](crate::is_connection_terminated),
3713 /// as do requests sent afterwards.
3714 ///
3715 /// Do not await this from inside the connection's own handlers, close
3716 /// callbacks, or tasks: termination happens only after they finish.
3717 ///
3718 /// Termination does not reap child processes owned by the transport, nor
3719 /// drain application-owned queues.
3720 pub async fn terminated(&self) -> ConnectionTermination {
3721 self.incoming_closed.terminated().await
3722 }
3723
3724 /// Return the termination reason if the connection driver has terminated.
3725 ///
3726 /// See [`terminated`](Self::terminated).
3727 #[must_use]
3728 pub fn termination(&self) -> Option<ConnectionTermination> {
3729 self.incoming_closed.termination()
3730 }
3731
3732 /// Stop accepting outgoing messages, drain routable output through the
3733 /// protocol actor, and finish cooperative physical sinks. Reactive serving also
3734 /// joins owned transport work after incoming EOF.
3735 async fn drain_outgoing(
3736 &self,
3737 finish: Option<crate::component::FinishControl>,
3738 wait_owned_transport: bool,
3739 ) -> Result<(), crate::Error> {
3740 let (done_tx, done_rx) = oneshot::channel();
3741 let marker_result = send_raw_message(
3742 &self.message_tx,
3743 OutgoingMessage::CloseAfterDraining { done: done_tx },
3744 );
3745 let marker_result = match marker_result {
3746 Ok(()) => done_rx.await.map_err(|error| {
3747 crate::util::internal_error(format!(
3748 "outgoing drain marker was dropped before completion: {error}"
3749 ))
3750 }),
3751 Err(error) => Err(error),
3752 };
3753
3754 let physical_finish = finish.is_some();
3755 if let Some(mut finish) = finish {
3756 // Only finish the physical sink after the protocol actor has handed
3757 // off its accepted output. Closing it earlier races the drain.
3758 finish.request();
3759 }
3760 if physical_finish || wait_owned_transport {
3761 // Cooperative completion proves physical sink drain. Reactive serving
3762 // also waits for owned work after EOF (e.g. child exit status).
3763 self.transport_completion.clone().await?;
3764 }
3765 // Opaque application drivers have no physical finish contract. Keep
3766 // polling their errors in the background, but do not globally join work
3767 // which may intentionally run forever after the foreground returns.
3768 marker_result
3769 }
3770
3771 fn is_incoming_closing(&self) -> bool {
3772 self.incoming_closed.is_closing()
3773 }
3774
3775 pub(super) fn begin_incoming_close(&self) {
3776 self.incoming_closed.begin_close();
3777 }
3778
3779 pub(super) fn finish_incoming_close(&self) {
3780 self.incoming_closed.finish_close();
3781 }
3782
3783 /// Spawns a task that will run so long as the JSON-RPC connection is being served.
3784 ///
3785 /// This is the primary mechanism for offloading expensive work from handler callbacks
3786 /// to avoid blocking the event loop. Spawned tasks run concurrently with the connection,
3787 /// allowing the server to continue processing messages.
3788 ///
3789 /// # Event Loop
3790 ///
3791 /// Handler callbacks run on the event loop, which cannot process new messages while
3792 /// your handler is running. Use `spawn` for any expensive operations:
3793 ///
3794 /// ```no_run
3795 /// # use agent_client_protocol_test::*;
3796 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
3797 /// # let connection = mock_connection();
3798 /// connection.on_receive_request(async |req: ProcessRequest, responder, cx| {
3799 /// // Clone cx for the spawned task
3800 /// cx.spawn({
3801 /// let connection = cx.clone();
3802 /// async move {
3803 /// let result = expensive_operation(&req.data).await?;
3804 /// connection.send_notification(ProcessComplete { result })?;
3805 /// Ok(())
3806 /// }
3807 /// })?;
3808 ///
3809 /// // Respond immediately
3810 /// responder.respond(ProcessResponse { result: "started".into() })
3811 /// }, agent_client_protocol::on_receive_request!())
3812 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
3813 /// # Ok(())
3814 /// # }
3815 /// ```
3816 ///
3817 /// # Errors
3818 ///
3819 /// Returns an error if the connection's task queue is closed. An error
3820 /// returned later by the spawned task shuts down the connection.
3821 #[track_caller]
3822 pub fn spawn(
3823 &self,
3824 task: impl IntoFuture<Output = Result<(), crate::Error>, IntoFuture: Send + 'static>,
3825 ) -> Result<(), crate::Error> {
3826 let location = std::panic::Location::caller();
3827 let task = task.into_future();
3828 Task::new(location, task).spawn(&self.task_tx)
3829 }
3830
3831 /// Spawn a JSON-RPC connection in the background and return the
3832 /// connection context its builder selects.
3833 ///
3834 /// This is useful for creating multiple connections that communicate with each other,
3835 /// such as implementing proxy patterns or connecting to multiple backend services.
3836 ///
3837 /// # Arguments
3838 ///
3839 /// - `builder`: The connection builder with handlers configured
3840 /// - `transport`: The transport component to connect to
3841 ///
3842 /// # Returns
3843 ///
3844 /// The connection type that `builder`'s callbacks receive: a raw
3845 /// [`ConnectionTo`] for a [`Raw`] builder such as [`Builder::new`], a
3846 /// [`v1::ConnectionTo`](crate::v1::ConnectionTo) for
3847 /// [`Client.v1()`](crate::Client::v1), and a `v2::ConnectionTo` for
3848 /// `Client.v2()`. Convert a typed connection back with `into_raw`.
3849 ///
3850 /// # Errors
3851 ///
3852 /// Returns an error if the parent connection cannot queue the child
3853 /// connection's task. It does not wait for the child to connect.
3854 ///
3855 /// # Example: Proxying to a backend connection
3856 ///
3857 /// ```
3858 /// # use agent_client_protocol::UntypedRole;
3859 /// # use agent_client_protocol::{Builder, ConnectionTo};
3860 /// # use agent_client_protocol_test::*;
3861 /// # async fn example(cx: ConnectionTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
3862 /// // Set up a backend connection builder
3863 /// let backend = UntypedRole.builder()
3864 /// .on_receive_request(async |req: MyRequest, responder, _cx| {
3865 /// responder.respond(MyResponse { status: "ok".into() })
3866 /// }, agent_client_protocol::on_receive_request!());
3867 ///
3868 /// // Spawn it and get a context to send requests to it
3869 /// let backend_connection = cx.spawn_connection(backend, MockTransport)?;
3870 ///
3871 /// // Now you can forward requests to the backend
3872 /// let response = backend_connection.send_request(MyRequest {}).block_task().await?;
3873 /// # Ok(())
3874 /// # }
3875 /// ```
3876 ///
3877 /// # Example: Spawning a v1 client
3878 ///
3879 /// ```no_run
3880 /// # use agent_client_protocol::{
3881 /// # Agent, Client, ConnectTo, ConnectionTo, Error, UntypedRole, v1,
3882 /// # };
3883 /// # fn example(
3884 /// # connection: ConnectionTo<UntypedRole>,
3885 /// # transport: impl ConnectTo<Client> + 'static,
3886 /// # ) -> Result<(), Error> {
3887 /// let child: v1::ConnectionTo<Agent> = connection.spawn_connection(Client.v1(), transport)?;
3888 /// # drop(child);
3889 /// # Ok(())
3890 /// # }
3891 /// ```
3892 #[track_caller]
3893 pub fn spawn_connection<R: Role, P: Protocol>(
3894 &self,
3895 builder: Builder<
3896 R,
3897 impl HandleDispatchFrom<R::Counterpart> + 'static,
3898 impl RunWithConnectionTo<R::Counterpart> + 'static,
3899 impl HandleConnectionClose<R::Counterpart> + 'static,
3900 P,
3901 >,
3902 transport: impl ConnectTo<R> + 'static,
3903 ) -> Result<P::Connection<R::Counterpart>, crate::Error> {
3904 let (connection, future) =
3905 builder.into_connection_and_future(transport, false, |_| std::future::pending());
3906 Task::new(std::panic::Location::caller(), future).spawn(&self.task_tx)?;
3907 Ok(protocol::connection_from_raw::<P, _>(connection))
3908 }
3909
3910 /// The ACP protocol version of this connection's wire guard, or `None`
3911 /// when its builder applies no guard, as with [`Builder::new`].
3912 ///
3913 /// `Client.v1()`, `Agent.v1()` and `Proxy.v1()` connections report
3914 /// [`ProtocolVersion::V1`](crate::schema::ProtocolVersion::V1), and the
3915 /// `v2()` entry points report `ProtocolVersion::V2`.
3916 #[must_use]
3917 pub fn protocol_version(&self) -> Option<crate::schema::ProtocolVersion> {
3918 self.protocol_mode.api_protocol_version()
3919 }
3920
3921 /// The same connection, typed for protocol `P`.
3922 ///
3923 /// `into_protocol::<V1>()` returns a [`v1::ConnectionTo`](crate::v1::ConnectionTo)
3924 /// (and, with `unstable_protocol_v2`, `into_protocol::<V2>()` a
3925 /// `v2::ConnectionTo`), whose sends return request handles typed for that
3926 /// version and which carries that version's session helpers. Only the
3927 /// Rust API changes: the connection's wire guard is the one its builder
3928 /// selected. The versioned connections convert back with `into_raw`.
3929 ///
3930 /// # Errors
3931 ///
3932 /// Returns an Internal error (`-32603`) when the builder's guard selected
3933 /// a different version than `P`, for example `into_protocol::<V2>()` on a
3934 /// connection from `Client.v1()`. The mismatch is a local programming
3935 /// error, not a malformed message from the peer. A
3936 /// connection whose builder applies no guard (see
3937 /// [`protocol_version`](Self::protocol_version)) converts to every
3938 /// protocol, and `into_protocol::<Raw>()` never fails.
3939 ///
3940 /// ```
3941 /// # use agent_client_protocol::{Agent, ConnectionTo, Error, V1, v1};
3942 /// fn sessions(connection: ConnectionTo<Agent>) -> Result<v1::ConnectionTo<Agent>, Error> {
3943 /// connection.into_protocol::<V1>()
3944 /// }
3945 /// ```
3946 pub fn into_protocol<P: Protocol>(self) -> Result<P::Connection<Counterpart>, crate::Error> {
3947 if let (Some(guard), Some(requested)) =
3948 (self.protocol_version(), protocol::protocol_version::<P>())
3949 && guard != requested
3950 {
3951 return Err(crate::Error::internal_error().data(format!(
3952 "cannot use a connection guarded for ACP protocol version {guard} \
3953 as a protocol version {requested} connection",
3954 )));
3955 }
3956 Ok(protocol::connection_from_raw::<P, _>(self))
3957 }
3958
3959 /// Send a request/notification and forward the response appropriately.
3960 ///
3961 /// The request context's response type matches the request's response type,
3962 /// enabling type-safe message forwarding.
3963 ///
3964 /// # Errors
3965 ///
3966 /// Returns the forwarding error from [`send_proxied_message_to`](Self::send_proxied_message_to).
3967 pub fn send_proxied_message<
3968 Req: JsonRpcRequest<Response: Send>,
3969 Notif: JsonRpcNotification,
3970 Q: Protocol,
3971 >(
3972 &self,
3973 message: Dispatch<Req, Notif, Q>,
3974 ) -> Result<(), crate::Error>
3975 where
3976 Counterpart: HasPeer<Counterpart>,
3977 {
3978 self.send_proxied_message_to(self.counterpart(), message)
3979 }
3980
3981 /// Send a request/notification and forward the response appropriately.
3982 ///
3983 /// The request context's response type matches the request's response type,
3984 /// enabling type-safe message forwarding.
3985 ///
3986 /// `$/cancel_request` notifications are *not* forwarded: their `requestId`
3987 /// refers to a request on the connection they arrived over and would be
3988 /// meaningless to `peer`. Cancellation instead propagates hop by hop,
3989 /// because the responders passed to
3990 /// [`forward_response_to`](SentRequest::forward_response_to) observe it
3991 /// and re-issue the cancellation with the forwarded request's own ID.
3992 /// A proxy forwarding an `elicitation/create` from its successor to its
3993 /// client also translates `params.requestId` back to that client's ID.
3994 ///
3995 /// # Errors
3996 ///
3997 /// Returns an error if a notification cannot be encoded or queued, or if
3998 /// response forwarding cannot be scheduled for a request. A downstream
3999 /// request error is sent to the upstream responder, not returned here.
4000 pub fn send_proxied_message_to<
4001 Peer: Role,
4002 Req: JsonRpcRequest<Response: Send>,
4003 Notif: JsonRpcNotification,
4004 Q: Protocol,
4005 >(
4006 &self,
4007 peer: Peer,
4008 message: Dispatch<Req, Notif, Q>,
4009 ) -> Result<(), crate::Error>
4010 where
4011 Counterpart: HasPeer<Peer>,
4012 {
4013 match message {
4014 Dispatch::Request(request, responder) => self
4015 .prepare_request_to(peer, request)
4016 .forward_response_to(responder),
4017 Dispatch::Notification(notification) => {
4018 // `$/cancel_request` is connection-scoped: its `requestId` was
4019 // allocated on the connection the notification arrived over
4020 // and means nothing to `peer`. The cancellation has already
4021 // been recorded on this connection's responder markers, and
4022 // `forward_response_to` re-issues it for the forwarded request
4023 // with the correct per-hop ID, so drop the raw notification
4024 // instead of tunneling a meaningless ID across the hop.
4025 if is_cancel_request_notification(¬ification) {
4026 tracing::debug!(
4027 "not forwarding hop-scoped `$/cancel_request` notification across proxy hop"
4028 );
4029 return Ok(());
4030 }
4031 self.send_notification_to(peer, notification)
4032 }
4033 Dispatch::Response(result, router) => {
4034 // Responses are forwarded directly to their destination
4035 router.route_with_result(result)
4036 }
4037 }
4038 }
4039
4040 /// Restore the originator's ID in a request-scoped elicitation received from this peer.
4041 ///
4042 /// Used by the conductor on ingress, before enqueueing a dispatch for its
4043 /// fixed predecessor. Reading a later response can retire the association.
4044 /// A reference that cannot be resolved on this hop is invalid. Forwarding
4045 /// it unchanged could accidentally match an unrelated upstream request.
4046 #[doc(hidden)]
4047 pub fn translate_elicitation_request_id<Peer: Role>(
4048 &self,
4049 peer: Peer,
4050 message: &mut Dispatch,
4051 ) -> Result<(), crate::Error>
4052 where
4053 Counterpart: HasPeer<Peer>,
4054 {
4055 let Dispatch::Request(request, _) = message else {
4056 return Ok(());
4057 };
4058 // The conductor owns these routes: each component has a fixed predecessor.
4059 self.pending_replies
4060 .translate_elicitation(peer.role_id(), request, |_| true)
4061 }
4062
4063 /// Send an outgoing request and return a [`SentRequest`] for handling the reply.
4064 ///
4065 /// The returned [`SentRequest`] makes the response-consumption mode explicit:
4066 ///
4067 /// * [`on_receiving_result`](SentRequest::on_receiving_result) - Register a callback and
4068 /// return immediately. If registered before the response is routed during its original
4069 /// dispatch, the loop waits for the callback to complete.
4070 /// * [`block_task`](SentRequest::block_task) - Wait on the current task until the response
4071 /// arrives. This is only safe when that task already runs outside the dispatch loop.
4072 ///
4073 /// For callback ordering selected before publication, use
4074 /// [`prepare_request`](Self::prepare_request) instead. Even an immediately
4075 /// chained callback can race with a fast response on a concurrent connection.
4076 ///
4077 /// # Anti-Footgun Design
4078 ///
4079 /// The API intentionally makes it difficult to block on the result directly to prevent
4080 /// the common mistake of blocking the event loop while waiting for a response:
4081 ///
4082 /// ```compile_fail
4083 /// # use agent_client_protocol_test::*;
4084 /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
4085 /// // ❌ This doesn't compile - prevents blocking the event loop
4086 /// let response = cx.send_request(MyRequest {}).await?;
4087 /// # Ok(())
4088 /// # }
4089 /// ```
4090 ///
4091 /// ```no_run
4092 /// # use agent_client_protocol_test::*;
4093 /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
4094 /// // ✅ Option 1: Register an ordered callback (safe in handlers)
4095 /// cx.send_request(MyRequest {})
4096 /// .on_receiving_result(async |result| {
4097 /// // Handle the response
4098 /// Ok(())
4099 /// })?;
4100 ///
4101 /// // ✅ Option 2: Block in spawned task (safe because task is concurrent)
4102 /// cx.spawn({
4103 /// let cx = cx.clone();
4104 /// async move {
4105 /// let response = cx.send_request(MyRequest {})
4106 /// .block_task()
4107 /// .await?;
4108 /// // Process response...
4109 /// Ok(())
4110 /// }
4111 /// })?;
4112 /// # Ok(())
4113 /// # }
4114 /// ```
4115 /// Send an outgoing request to the default counterpart peer.
4116 ///
4117 /// This is a convenience method that sends to the counterpart role `R`.
4118 /// For explicit control over the target peer, use [`send_request_to`](Self::send_request_to).
4119 pub fn send_request<Req: JsonRpcRequest>(&self, request: Req) -> SentRequest<Req::Response>
4120 where
4121 Counterpart: HasPeer<Counterpart>,
4122 {
4123 self.send_request_to(self.counterpart.clone(), request)
4124 }
4125
4126 /// Send an outgoing request to a specific peer.
4127 ///
4128 /// The message will be transformed according to the [`HasPeer`](crate::role::HasPeer)
4129 /// implementation before being sent.
4130 pub fn send_request_to<Peer: Role, Req: JsonRpcRequest>(
4131 &self,
4132 peer: Peer,
4133 request: Req,
4134 ) -> SentRequest<Req::Response>
4135 where
4136 Counterpart: HasPeer<Peer>,
4137 {
4138 self.send_request_to_with_options(peer, request, false, None, None)
4139 }
4140
4141 /// Prepare a request without sending it until response handling is selected.
4142 ///
4143 /// Unlike [`send_request`](Self::send_request), this does not register a
4144 /// pending reply or enqueue the request. A consuming method on the returned
4145 /// [`PreparedRequest`] publishes it synchronously. Callback-style methods
4146 /// select ordered consumption before publication, closing the race with a
4147 /// fast peer response even when the connection runs on another task.
4148 ///
4149 /// Dropping the prepared request sends nothing. See [`PreparedRequest`] for
4150 /// the available consumption modes and their error and cancellation behavior.
4151 ///
4152 /// # Examples
4153 ///
4154 /// ```no_run
4155 /// # use agent_client_protocol::{ConnectionTo, Error, UntypedRole};
4156 /// # use agent_client_protocol_test::MyRequest;
4157 /// # fn example(connection: ConnectionTo<UntypedRole>) -> Result<(), Error> {
4158 /// connection.prepare_request(MyRequest {}).on_receiving_result(async |result| {
4159 /// let response = result?;
4160 /// // Apply bounded response work before later inbound messages.
4161 /// Ok(())
4162 /// })?;
4163 /// # Ok(())
4164 /// # }
4165 /// ```
4166 pub fn prepare_request<Req: JsonRpcRequest>(
4167 &self,
4168 request: Req,
4169 ) -> PreparedRequest<Req::Response>
4170 where
4171 Counterpart: HasPeer<Counterpart>,
4172 {
4173 self.prepare_request_to(self.counterpart.clone(), request)
4174 }
4175
4176 /// Prepare a request to a specific peer without sending it.
4177 ///
4178 /// The request is serialized now. A consuming method synchronously registers
4179 /// its pending reply and enqueues the request; peer transformation and
4180 /// transmission happen later in the connection driver.
4181 /// See [`prepare_request`](Self::prepare_request).
4182 pub fn prepare_request_to<Peer: Role, Req: JsonRpcRequest>(
4183 &self,
4184 peer: Peer,
4185 request: Req,
4186 ) -> PreparedRequest<Req::Response>
4187 where
4188 Counterpart: HasPeer<Peer>,
4189 {
4190 self.prepare_request_to_with_options(peer, request, None, None)
4191 }
4192
4193 /// Prepare a request and run a synchronous side effect when its valid success
4194 /// response is routed, after `before_send` completes and independently
4195 /// from how the returned request is eventually consumed.
4196 #[cfg(feature = "unstable_protocol_v2")]
4197 pub(crate) fn prepare_request_to_with_response_hook_after<
4198 P: Protocol,
4199 Peer: Role,
4200 Req: JsonRpcRequest,
4201 BeforeSend: Future<Output = Result<(), crate::Error>> + Send + 'static,
4202 >(
4203 &self,
4204 peer: Peer,
4205 request: Req,
4206 before_send: BeforeSend,
4207 response_hook: impl FnOnce(&Req::Response) -> Result<(), crate::Error> + Send + 'static,
4208 ) -> PreparedRequest<Req::Response, P>
4209 where
4210 Counterpart: HasPeer<Peer>,
4211 {
4212 let hook: ResponseRouteHook = Box::new(move |method, value| {
4213 let response = Req::Response::from_json(method, value.clone())?;
4214 response_hook(&response)
4215 });
4216 self.prepare_request_to_with_options(
4217 peer,
4218 request,
4219 Some(RequestReadiness::new(before_send)),
4220 Some(hook),
4221 )
4222 }
4223
4224 /// Send a request whose callback must run before later inbound messages.
4225 ///
4226 /// The ordering marker is installed before the request enters the outgoing
4227 /// queue, closing the race between a fast peer response and the immediate
4228 /// [`SentRequest::on_receiving_result`] call. Callers must consume the
4229 /// returned request with a callback-style method without yielding.
4230 pub(crate) fn send_ordered_request_to<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4231 &self,
4232 peer: Peer,
4233 request: Req,
4234 ) -> SentRequest<Req::Response, P>
4235 where
4236 Counterpart: HasPeer<Peer>,
4237 {
4238 self.send_request_to_with_options(peer, request, true, None, None)
4239 }
4240
4241 /// Send an ordered request after `before_send` completes successfully.
4242 ///
4243 /// The ordering marker and readiness prerequisite are both registered
4244 /// before the request enters the outgoing queue. This is used by framework
4245 /// setup paths that must acknowledge local routing before the peer can
4246 /// observe the request.
4247 pub(crate) fn send_ordered_request_to_after<
4248 P: Protocol,
4249 Peer: Role,
4250 Req: JsonRpcRequest,
4251 BeforeSend: Future<Output = Result<(), crate::Error>> + Send + 'static,
4252 >(
4253 &self,
4254 peer: Peer,
4255 request: Req,
4256 before_send: BeforeSend,
4257 ) -> SentRequest<Req::Response, P>
4258 where
4259 Counterpart: HasPeer<Peer>,
4260 {
4261 self.send_request_to_with_options(
4262 peer,
4263 request,
4264 true,
4265 Some(RequestReadiness::new(before_send)),
4266 None,
4267 )
4268 }
4269
4270 fn send_request_to_with_options<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4271 &self,
4272 peer: Peer,
4273 request: Req,
4274 ordered: bool,
4275 readiness: Option<RequestReadiness>,
4276 response_route_hook: Option<ResponseRouteHook>,
4277 ) -> SentRequest<Req::Response, P>
4278 where
4279 Counterpart: HasPeer<Peer>,
4280 {
4281 self.prepare_request_to_with_options(peer, request, readiness, response_route_hook)
4282 .into_sent_request(ordered)
4283 }
4284
4285 fn prepare_request_to_with_options<P: Protocol, Peer: Role, Req: JsonRpcRequest>(
4286 &self,
4287 peer: Peer,
4288 request: Req,
4289 readiness: Option<RequestReadiness>,
4290 response_route_hook: Option<ResponseRouteHook>,
4291 ) -> PreparedRequest<Req::Response, P>
4292 where
4293 Counterpart: HasPeer<Peer>,
4294 {
4295 let method = request.method().to_string();
4296 let id = HandleId::<P>::generated(Uuid::new_v4().to_string());
4297 let (response_tx, response_rx) = oneshot::channel();
4298 let response_ordering = ResponseOrdering::default();
4299 let role_id = peer.role_id();
4300 let remote_style = self.counterpart.remote_style(peer);
4301 let cancellation = SentRequestCancellation::new(self.message_tx.clone(), id.raw().clone());
4302 let pending_reply = PendingReply {
4303 id: id.raw().clone(),
4304 method: method.clone(),
4305 role_id,
4306 sender: response_tx,
4307 cancellation_disarm: cancellation.disarm_handle(),
4308 ordering: response_ordering.clone(),
4309 response_route_hook,
4310 forwarded_from: None,
4311 accepts_lower_initialize_version: false,
4312 };
4313 let message = if self.is_incoming_closing() {
4314 Err(incoming_transport_closed_error(&method))
4315 } else {
4316 request
4317 .to_untyped_message()
4318 .map(|untyped| OutgoingMessage::Request {
4319 id: id.raw().clone(),
4320 method: method.clone(),
4321 untyped,
4322 remote_style,
4323 readiness,
4324 })
4325 .map_err(|error| {
4326 crate::util::internal_error(format!(
4327 "failed to create untyped request for `{method}`: {error}"
4328 ))
4329 })
4330 };
4331 let sent = SentRequest::new(
4332 id,
4333 method.clone(),
4334 self.task_tx.clone(),
4335 self.pending_replies.clone(),
4336 response_rx,
4337 cancellation,
4338 response_ordering,
4339 )
4340 .map(move |json| <Req::Response>::from_json(&method, json));
4341 PreparedRequest {
4342 sent,
4343 publication: RequestPublication {
4344 message,
4345 pending_reply,
4346 message_tx: self.message_tx.clone(),
4347 pending_replies: self.pending_replies.clone(),
4348 incoming_closed: self.incoming_closed.clone(),
4349 },
4350 }
4351 }
4352
4353 /// Send an outgoing notification to the default counterpart peer (no reply expected).
4354 ///
4355 /// Notifications are fire-and-forget messages that don't have IDs and don't expect responses.
4356 /// This method sends the notification immediately and returns.
4357 ///
4358 /// This is a convenience method that sends to the counterpart role `R`.
4359 /// For explicit control over the target peer, use [`send_notification_to`](Self::send_notification_to).
4360 ///
4361 /// # Errors
4362 ///
4363 /// Returns an error if the notification cannot be encoded or queued.
4364 ///
4365 /// ```no_run
4366 /// # use agent_client_protocol_test::*;
4367 /// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::Agent>) -> Result<(), agent_client_protocol::Error> {
4368 /// cx.send_notification(StatusUpdate {
4369 /// message: "Processing...".into(),
4370 /// })?;
4371 /// # Ok(())
4372 /// # }
4373 /// ```
4374 pub fn send_notification<N: JsonRpcNotification>(
4375 &self,
4376 notification: N,
4377 ) -> Result<(), crate::Error>
4378 where
4379 Counterpart: HasPeer<Counterpart>,
4380 {
4381 self.send_notification_to(self.counterpart.clone(), notification)
4382 }
4383
4384 /// Send an outgoing notification to a specific peer (no reply expected).
4385 ///
4386 /// The message will be transformed according to the [`HasPeer`](crate::role::HasPeer)
4387 /// implementation before being sent.
4388 ///
4389 /// # Errors
4390 ///
4391 /// Returns an error if the notification cannot be encoded for the peer or
4392 /// the outgoing queue is closed. This does not wait for wire delivery.
4393 pub fn send_notification_to<Peer: Role, N: JsonRpcNotification>(
4394 &self,
4395 peer: Peer,
4396 notification: N,
4397 ) -> Result<(), crate::Error>
4398 where
4399 Counterpart: HasPeer<Peer>,
4400 {
4401 let remote_style = self.counterpart.remote_style(peer);
4402 tracing::debug!(
4403 role = std::any::type_name::<Counterpart>(),
4404 peer = std::any::type_name::<Peer>(),
4405 notification_type = std::any::type_name::<N>(),
4406 ?remote_style,
4407 original_method = notification.method(),
4408 "send_notification_to"
4409 );
4410 let transformed = remote_style.transform_outgoing_message(notification)?;
4411 tracing::debug!(
4412 transformed_method = %transformed.method,
4413 "send_notification_to transformed"
4414 );
4415 send_raw_message(
4416 &self.message_tx,
4417 OutgoingMessage::Notification {
4418 untyped: transformed,
4419 },
4420 )
4421 }
4422
4423 /// Send a `$/cancel_request` notification for an arbitrary request ID to
4424 /// the default counterpart peer.
4425 ///
4426 /// Prefer [`SentRequest::cancel`] when you have the request handle: it
4427 /// already knows the correct request ID. Use this low-level method only
4428 /// when implementing custom routing with a request ID that is valid on
4429 /// this connection.
4430 ///
4431 /// # Errors
4432 ///
4433 /// Returns an error if the cancellation notification cannot be encoded or queued.
4434 pub fn send_cancel_request(
4435 &self,
4436 request_id: impl Into<RawJsonRpcId>,
4437 ) -> Result<(), crate::Error>
4438 where
4439 Counterpart: HasPeer<Counterpart>,
4440 {
4441 self.send_cancel_request_to(self.counterpart.clone(), request_id)
4442 }
4443
4444 /// Send a `$/cancel_request` notification for an arbitrary request ID to a
4445 /// specific peer.
4446 ///
4447 /// `$/cancel_request` is hop-local, so the notification is always sent
4448 /// plain, never wrapped in `proxy/successor`, even to a proxy's
4449 /// successor. To cancel a request sent to a successor, pass the ID of the
4450 /// `proxy/successor` request on this connection.
4451 ///
4452 /// Prefer [`SentRequest::cancel`] when you have the request handle: it
4453 /// already knows the correct request ID. Use this low-level method only
4454 /// when implementing custom routing with a request ID that is valid on
4455 /// this connection.
4456 ///
4457 /// # Errors
4458 ///
4459 /// Returns an error if the cancellation notification cannot be encoded or queued.
4460 /// It does not check whether the peer still has a pending request with this ID.
4461 pub fn send_cancel_request_to<Peer: Role>(
4462 &self,
4463 _peer: Peer,
4464 request_id: impl Into<RawJsonRpcId>,
4465 ) -> Result<(), crate::Error>
4466 where
4467 Counterpart: HasPeer<Peer>,
4468 {
4469 let untyped = crate::v1::schema::CancelRequestNotification::new(
4470 crate::v1::schema::RequestId::from(request_id.into()),
4471 )
4472 .to_untyped_message()?;
4473 send_raw_message(&self.message_tx, OutgoingMessage::Notification { untyped })
4474 }
4475
4476 /// Register a dynamic message handler, used to intercept messages specific to a particular session
4477 /// or some similar modal thing.
4478 ///
4479 /// Dynamic message handlers run after the handlers registered on [`Builder`] and before the
4480 /// role's default handler. They receive messages that the builder handlers decline.
4481 ///
4482 /// The handler will stay registered until the returned registration guard is dropped.
4483 ///
4484 /// # Errors
4485 ///
4486 /// Returns an error if the connection no longer accepts handler registrations.
4487 pub fn add_dynamic_handler(
4488 &self,
4489 handler: impl HandleDispatchFrom<Counterpart> + 'static,
4490 ) -> Result<DynamicHandlerGuard<Counterpart>, crate::Error> {
4491 let uuid = Uuid::new_v4();
4492 let active = Arc::new(AtomicBool::new(true));
4493 self.dynamic_handler_tx
4494 .unbounded_send(DynamicHandlerMessage::AddDynamicHandler(
4495 uuid,
4496 Box::new(GuardedDynamicHandler {
4497 active: active.clone(),
4498 handler,
4499 }),
4500 active.clone(),
4501 ))
4502 .map_err(crate::util::internal_error)?;
4503
4504 Ok(DynamicHandlerGuard::new(uuid, active, self.clone()))
4505 }
4506
4507 /// Wait until every dynamic-handler update queued before this call has
4508 /// been applied by the incoming protocol actor.
4509 pub(crate) fn dynamic_handler_barrier(&self) -> BoxFuture<'static, Result<(), crate::Error>> {
4510 let (acknowledgment_tx, acknowledgment_rx) = oneshot::channel();
4511 if let Err(error) =
4512 self.dynamic_handler_tx
4513 .unbounded_send(DynamicHandlerMessage::AcknowledgedBarrier(
4514 acknowledgment_tx,
4515 ))
4516 {
4517 return future::ready(Err(crate::Error::into_internal_error(error))).boxed();
4518 }
4519
4520 async move {
4521 acknowledgment_rx.await.map_err(|error| {
4522 crate::util::internal_error(format!(
4523 "dynamic-handler barrier was dropped before acknowledgment: {error}"
4524 ))
4525 })
4526 }
4527 .boxed()
4528 }
4529
4530 fn remove_dynamic_handler(&self, uuid: Uuid) {
4531 // Ignore errors
4532 drop(
4533 self.dynamic_handler_tx
4534 .unbounded_send(DynamicHandlerMessage::RemoveDynamicHandler(uuid)),
4535 );
4536 }
4537}
4538
4539struct GuardedDynamicHandler<Handler> {
4540 active: Arc<AtomicBool>,
4541 handler: Handler,
4542}
4543
4544impl<Counterpart, Handler> HandleDispatchFrom<Counterpart> for GuardedDynamicHandler<Handler>
4545where
4546 Counterpart: Role,
4547 Handler: HandleDispatchFrom<Counterpart>,
4548{
4549 async fn handle_dispatch_from(
4550 &mut self,
4551 message: Dispatch,
4552 connection: ConnectionTo<Counterpart>,
4553 ) -> Result<Handled<Dispatch>, crate::Error> {
4554 if !self.active.load(Ordering::Acquire) {
4555 return Ok(Handled::No {
4556 message,
4557 retry: false,
4558 });
4559 }
4560 self.handler.handle_dispatch_from(message, connection).await
4561 }
4562
4563 fn describe_chain(&self) -> impl Debug {
4564 self.handler.describe_chain()
4565 }
4566}
4567
4568/// A guard that keeps a dynamic message handler registered.
4569///
4570/// Dropping the guard immediately deactivates the handler and queues its
4571/// removal from the connection. Use [`detach`](Self::detach) to keep the
4572/// handler registered for the remaining lifetime of the connection.
4573#[must_use = "dropping this guard unregisters the dynamic handler"]
4574#[derive(Debug)]
4575pub struct DynamicHandlerGuard<R: Role> {
4576 uuid: Option<Uuid>,
4577 active: Arc<AtomicBool>,
4578 cx: ConnectionTo<R>,
4579 cleanup: Option<Arc<dyn DynamicHandlerCleanup>>,
4580}
4581
4582/// Private registration-local cleanup, independent of connection task admission.
4583pub(crate) trait DynamicHandlerCleanup: std::fmt::Debug + Send + Sync {
4584 fn close(&self);
4585 fn wait(&self) -> futures::future::BoxFuture<'static, ()>;
4586}
4587
4588impl<R: Role> DynamicHandlerGuard<R> {
4589 fn new(uuid: Uuid, active: Arc<AtomicBool>, cx: ConnectionTo<R>) -> Self {
4590 Self {
4591 uuid: Some(uuid),
4592 active,
4593 cx,
4594 cleanup: None,
4595 }
4596 }
4597
4598 #[cfg(feature = "unstable_mcp_over_acp")]
4599 pub(crate) fn with_cleanup(mut self, cleanup: Arc<dyn DynamicHandlerCleanup>) -> Self {
4600 self.cleanup = Some(cleanup);
4601 self
4602 }
4603
4604 pub(crate) fn cleanup(&self) -> Option<Arc<dyn DynamicHandlerCleanup>> {
4605 self.cleanup.clone()
4606 }
4607
4608 /// Stop the handler from claiming messages without queuing its removal.
4609 ///
4610 /// Until the guard is dropped, the incoming actor keeps unclaimed session
4611 /// requests parked for a replacement handler.
4612 pub(crate) fn deactivate(&self) {
4613 self.active.store(false, Ordering::Release);
4614 }
4615
4616 /// Keep the dynamic handler registered after this guard is dropped.
4617 ///
4618 /// The handler remains registered until the connection itself shuts down.
4619 /// Unlike leaking the guard, detaching does not retain an extra
4620 /// [`ConnectionTo`] handle.
4621 pub fn detach(mut self) {
4622 self.uuid = None;
4623 }
4624}
4625
4626impl<R: Role> Drop for DynamicHandlerGuard<R> {
4627 fn drop(&mut self) {
4628 if let Some(uuid) = self.uuid {
4629 self.active.store(false, Ordering::Release);
4630 if let Some(cleanup) = &self.cleanup {
4631 cleanup.close();
4632 }
4633 self.cx.remove_dynamic_handler(uuid);
4634 }
4635 }
4636}
4637
4638/// The context to respond to an incoming request.
4639///
4640/// This context is provided to request handlers and serves a dual role:
4641///
4642/// 1. **Respond to the request** - Use [`respond`](Self::respond) or
4643/// [`respond_with_result`](Self::respond_with_result) to send the response
4644/// 2. **Send other messages** - Use the [`ConnectionTo`] parameter passed to your
4645/// handler, which provides [`send_request`](`ConnectionTo::send_request`),
4646/// [`send_notification`](`ConnectionTo::send_notification`), and
4647/// [`spawn`](`ConnectionTo::spawn`)
4648///
4649/// # Example
4650///
4651/// ```no_run
4652/// # use agent_client_protocol_test::*;
4653/// # async fn example() -> Result<(), agent_client_protocol::Error> {
4654/// # let connection = mock_connection();
4655/// connection.on_receive_request(async |req: ProcessRequest, responder, cx| {
4656/// // Send a notification while processing
4657/// cx.send_notification(StatusUpdate {
4658/// message: "processing".into(),
4659/// })?;
4660///
4661/// // Do some work...
4662/// let result = process(&req.data)?;
4663///
4664/// // Respond to the request
4665/// responder.respond(ProcessResponse { result })
4666/// }, agent_client_protocol::on_receive_request!())
4667/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
4668/// # Ok(())
4669/// # }
4670/// ```
4671///
4672/// # Event Loop Considerations
4673///
4674/// Like all handlers, request handlers run on the event loop. Use
4675/// [`spawn`](ConnectionTo::spawn) for expensive operations to avoid blocking
4676/// the connection.
4677///
4678/// See the [Event Loop and Concurrency](Builder#event-loop-and-concurrency)
4679/// section for more details.
4680///
4681/// # Drop behavior
4682///
4683/// A request must be answered. If a responder for a request is dropped
4684/// without a response having been sent through it, the SDK answers the
4685/// request itself with an error, so the peer is never left waiting:
4686///
4687/// - `-32800` ([`Error::request_cancelled`]) if the peer had cancelled the
4688/// request with `$/cancel_request`;
4689/// - otherwise `-32603` ([`Error::internal_error`]), with data naming the
4690/// method whose responder was dropped.
4691///
4692/// No automatic response is sent when:
4693///
4694/// - a response was already sent through the responder (any of the
4695/// `respond*` methods), or the responder was handed to something that
4696/// answers through it (such as
4697/// [`SentRequest::forward_response_to`]) — only dropping the responder
4698/// itself without responding triggers the fallback;
4699/// - the responder was moved into another owner (another task, a wrapped
4700/// responder from [`cast`](Self::cast) or [`wrap_params`](Self::wrap_params),
4701/// a retried [`Dispatch`]); that owner's eventual drop is what counts;
4702/// - the connection is shutting down or has terminated.
4703///
4704/// When a handler drops the responder and then returns an error, that error
4705/// is the response instead of the generic fallback.
4706///
4707/// The automatic error is an ordinary error response: for example, a dropped
4708/// `initialize` responder fails initialization just as an explicit error
4709/// would.
4710///
4711/// # Protocol version
4712///
4713/// `P` is the [`Protocol`] marker and selects the type [`id`](Self::id)
4714/// returns. Typed handlers on `Client.v1()`, `Agent.v1()` and
4715/// `Proxy.v1()` receive [`V1`] responders and those on the v2 builders
4716/// receive `V2` responders. The version-neutral raw dispatch layer
4717/// ([`HandleDispatchFrom`], [`MatchDispatch`](crate::util::MatchDispatch))
4718/// uses the default, [`Raw`]. [`raw_id`](Self::raw_id) returns the wire ID
4719/// whatever the marker; [`into_protocol`](Responder::into_protocol) and
4720/// [`into_raw`](Self::into_raw) convert between markers.
4721///
4722/// [`Error::request_cancelled`]: crate::Error::request_cancelled
4723/// [`Error::internal_error`]: crate::Error::internal_error
4724#[must_use]
4725pub struct Responder<T: JsonRpcResponse = serde_json::Value, P: Protocol = Raw> {
4726 /// The method of the request.
4727 method: String,
4728
4729 /// The `id` of the message we are replying to.
4730 id: HandleId<P>,
4731
4732 /// Where the response is sent; it is completed at most once.
4733 destination: ResponseDestination,
4734
4735 /// Function to send the response to its destination.
4736 ///
4737 /// For incoming requests: serializes to JSON and sends over the wire.
4738 /// For incoming responses: sends to the waiting oneshot channel.
4739 send_fn: ResponseFn<T, ()>,
4740
4741 /// Answers the request with an error if no response is sent. Owns the
4742 /// request-local cancellation state, so it can still observe a
4743 /// cancellation when it fires.
4744 drop_guard: ResponderDropGuard,
4745}
4746
4747type ResponseFn<T, U> = Box<dyn FnOnce(crate::Result<T>) -> crate::Result<U> + Send>;
4748
4749pub(crate) type RequestWithResponder<R> = (R, Responder<<R as JsonRpcRequest>::Response>);
4750
4751/// Sends the automatic error for a [`Responder`] dropped without responding.
4752struct ResponderDropGuard {
4753 message_tx: OutgoingMessageTx,
4754 connection_state: IncomingClosed,
4755 /// The method of the request as received, used to route the response.
4756 wire_method: String,
4757 id: RawJsonRpcId,
4758 destination: ResponseDestination,
4759 /// Request-local cancellation state.
4760 cancellation: ResponderCancellation,
4761 armed: bool,
4762}
4763
4764impl ResponderDropGuard {
4765 fn disarm(&mut self) {
4766 self.armed = false;
4767 }
4768}
4769
4770impl Drop for ResponderDropGuard {
4771 fn drop(&mut self) {
4772 if !self.armed || self.destination.is_completed() {
4773 return;
4774 }
4775 if self.connection_state.is_shutting_down() {
4776 tracing::debug!(
4777 id = ?self.id,
4778 method = %self.wire_method,
4779 "responder dropped while the connection is shutting down; not answering"
4780 );
4781 return;
4782 }
4783
4784 let error = if self.cancellation.is_cancelled() {
4785 crate::Error::request_cancelled()
4786 } else {
4787 crate::Error::internal_error().data(format!(
4788 "request handler dropped its responder for `{}` without responding",
4789 self.wire_method
4790 ))
4791 };
4792 tracing::warn!(
4793 id = ?self.id,
4794 method = %self.wire_method,
4795 code = ?error.code,
4796 "Responder dropped without responding; answering with an error"
4797 );
4798 self.destination.abandon(AbandonedResponse {
4799 message_tx: self.message_tx.clone(),
4800 connection_state: self.connection_state.clone(),
4801 message: OutgoingMessage::Response {
4802 id: self.id.clone(),
4803 method: self.wire_method.clone(),
4804 response: Err(error),
4805 destination: self.destination.clone(),
4806 },
4807 });
4808 }
4809}
4810
4811impl<T: JsonRpcResponse, P: Protocol> std::fmt::Debug for Responder<T, P> {
4812 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4813 f.debug_struct("Responder")
4814 .field("method", &self.method)
4815 .field("id", &self.id)
4816 .field("response_type", &std::any::type_name::<T>())
4817 .finish_non_exhaustive()
4818 }
4819}
4820
4821impl Responder<serde_json::Value, Raw> {
4822 /// Create a new request context for an incoming request.
4823 ///
4824 /// The response will be serialized to JSON and sent over the wire.
4825 fn new(
4826 message_tx: OutgoingMessageTx,
4827 connection_state: IncomingClosed,
4828 method: String,
4829 id: RawJsonRpcId,
4830 cancellation_registry: &RequestCancellationRegistry,
4831 destination: ResponseDestination,
4832 ) -> Self {
4833 let id_clone = id.clone();
4834 let method_clone = method.clone();
4835 let cancellation = cancellation_registry.register(&id);
4836 let send_destination = destination.clone();
4837 let drop_guard = ResponderDropGuard {
4838 message_tx: message_tx.clone(),
4839 connection_state,
4840 wire_method: method.clone(),
4841 id: id.clone(),
4842 destination: destination.clone(),
4843 cancellation,
4844 armed: true,
4845 };
4846 Self {
4847 method,
4848 id: HandleId::raw_layer(id),
4849 destination,
4850 send_fn: Box::new(move |response: Result<serde_json::Value, crate::Error>| {
4851 send_raw_message(
4852 &message_tx,
4853 OutgoingMessage::Response {
4854 id: id_clone,
4855 method: method_clone,
4856 response,
4857 destination: send_destination,
4858 },
4859 )
4860 }),
4861 drop_guard,
4862 }
4863 }
4864}
4865
4866impl<P: Protocol> Responder<serde_json::Value, P> {
4867 /// Cast this request context to a different response type.
4868 ///
4869 /// The provided type `T` will be serialized to JSON before sending.
4870 pub fn cast<T: JsonRpcResponse>(self) -> Responder<T, P> {
4871 self.wrap_params(move |method, value| match value {
4872 Ok(value) => T::into_json(value, method),
4873 Err(e) => Err(e),
4874 })
4875 }
4876}
4877
4878impl<T: JsonRpcResponse, P: Protocol> Responder<T, P> {
4879 fn origin_for_forwarding(&self, outgoing: &OutgoingMessageTx) -> RequestOrigin {
4880 let guard = &self.drop_guard;
4881 RequestOrigin {
4882 id: self.raw_id().clone(),
4883 generation: guard.cancellation.generation,
4884 registry: Arc::downgrade(&guard.cancellation.registry.inner),
4885 local_peer: outgoing.same_receiver(&guard.message_tx).then(|| {
4886 if guard.wire_method == crate::v1::schema::PROXY_METHOD_NAMES.proxy_successor {
4887 RemoteStyle::Successor
4888 } else {
4889 RemoteStyle::Predecessor
4890 }
4891 }),
4892 }
4893 }
4894
4895 /// Method of the incoming request
4896 #[must_use]
4897 pub fn method(&self) -> &str {
4898 &self.method
4899 }
4900
4901 /// ID of the incoming request, as this responder's protocol version
4902 /// types it.
4903 ///
4904 /// On a [`V2`](crate::Protocol) responder this is never `null`: the SDK
4905 /// rejects v2 requests with a `null` ID before dispatch.
4906 #[must_use]
4907 pub fn id(&self) -> &P::RequestId {
4908 self.id.typed()
4909 }
4910
4911 /// ID of the incoming request exactly as it appeared on the wire.
4912 ///
4913 /// This is the same ID as [`id`](Self::id), in the version-neutral form
4914 /// used by routers, forwarders and tracing.
4915 #[must_use]
4916 pub fn raw_id(&self) -> &RawJsonRpcId {
4917 self.id.raw()
4918 }
4919
4920 /// Returns the cancellation marker for this request.
4921 ///
4922 /// The marker is set when the peer sends `$/cancel_request` for this
4923 /// request's JSON-RPC ID. Cancellation is cooperative: handlers should use
4924 /// the marker to stop long-running work and then respond. Unless the
4925 /// method defines a successful response for cancellation (for example a
4926 /// permission request's `cancelled` outcome), that response is
4927 /// [`Error::request_cancelled`] (`-32800`) rather than partial data.
4928 /// Dropping the responder of a cancelled request sends that error
4929 /// automatically.
4930 ///
4931 /// [`Error::request_cancelled`]: crate::Error::request_cancelled
4932 #[must_use]
4933 pub fn cancellation(&self) -> RequestCancellation {
4934 self.drop_guard.cancellation.cancellation()
4935 }
4936
4937 /// Convert to a `Responder` that expects a JSON value
4938 /// and which checks (dynamically) that the JSON value it receives
4939 /// can be converted to `T`.
4940 pub fn erase_to_json(self) -> Responder<serde_json::Value, P> {
4941 self.wrap_params(|method, value| T::from_json(method, value?))
4942 }
4943
4944 /// Return a new Responder with a different method name.
4945 pub fn wrap_method(self, method: String) -> Responder<T, P> {
4946 Responder {
4947 method,
4948 id: self.id,
4949 destination: self.destination,
4950 send_fn: self.send_fn,
4951 drop_guard: self.drop_guard,
4952 }
4953 }
4954
4955 /// Return a new Responder that expects a response of type U.
4956 ///
4957 /// `wrap_fn` will be invoked with the method name and the result to transform
4958 /// type `U` into type `T` before sending.
4959 pub fn wrap_params<U: JsonRpcResponse>(
4960 self,
4961 wrap_fn: impl FnOnce(&str, Result<U, crate::Error>) -> Result<T, crate::Error> + Send + 'static,
4962 ) -> Responder<U, P> {
4963 let method = self.method.clone();
4964 let send_fn = self.send_fn;
4965 Responder {
4966 method: self.method,
4967 id: self.id,
4968 destination: self.destination,
4969 send_fn: Box::new(move |input: Result<U, crate::Error>| {
4970 let t_value = wrap_fn(&method, input);
4971 send_fn(t_value)
4972 }),
4973 drop_guard: self.drop_guard,
4974 }
4975 }
4976
4977 /// Respond to the JSON-RPC request with either a value (`Ok`) or an error (`Err`).
4978 ///
4979 /// # Errors
4980 ///
4981 /// Returns an error if the response cannot be queued. An `Err` in
4982 /// `response`, including a conversion error from a wrapped responder,
4983 /// is sent to the peer rather than returned here.
4984 pub fn respond_with_result(
4985 mut self,
4986 response: Result<T, crate::Error>,
4987 ) -> Result<(), crate::Error> {
4988 tracing::debug!(id = ?self.id, "respond called");
4989 self.drop_guard.disarm();
4990 (self.send_fn)(response)
4991 }
4992
4993 /// Respond to the JSON-RPC request with a value.
4994 ///
4995 /// # Errors
4996 ///
4997 /// Returns an error if the response cannot be queued.
4998 pub fn respond(self, response: T) -> Result<(), crate::Error> {
4999 self.respond_with_result(Ok(response))
5000 }
5001
5002 /// Respond to the JSON-RPC request with an internal error containing a message.
5003 ///
5004 /// # Errors
5005 ///
5006 /// Returns an error if the error response cannot be queued.
5007 pub fn respond_with_internal_error(self, message: impl ToString) -> Result<(), crate::Error> {
5008 self.respond_with_error(crate::util::internal_error(message))
5009 }
5010
5011 /// Respond to the JSON-RPC request with an error.
5012 ///
5013 /// # Errors
5014 ///
5015 /// Returns an error if the error response cannot be queued. `error` is
5016 /// the payload for the peer, not the return value.
5017 pub fn respond_with_error(self, error: crate::Error) -> Result<(), crate::Error> {
5018 tracing::debug!(id = ?self.id, error = ?crate::util::redacted_error(error.code), "respond_with_error called");
5019 self.respond_with_result(Err(error))
5020 }
5021
5022 /// The same responder for protocol `Q`. Fails only if the request ID is
5023 /// `null` and `Q` does not allow it, which cannot happen for requests
5024 /// received on a connection that speaks `Q`.
5025 pub(crate) fn retag<Q: Protocol>(self) -> Result<Responder<T, Q>, crate::Error> {
5026 Ok(Responder {
5027 method: self.method,
5028 id: self.id.into_protocol()?,
5029 destination: self.destination,
5030 send_fn: self.send_fn,
5031 drop_guard: self.drop_guard,
5032 })
5033 }
5034
5035 /// The same responder with a version-neutral [`Raw`] request ID, for
5036 /// code that is not tied to one protocol version, such as a
5037 /// [`HandleDispatchFrom`] implementation. This never fails.
5038 pub fn into_raw(self) -> Responder<T, Raw> {
5039 Responder {
5040 method: self.method,
5041 id: self.id.into_raw(),
5042 destination: self.destination,
5043 send_fn: self.send_fn,
5044 drop_guard: self.drop_guard,
5045 }
5046 }
5047
5048 fn reply_target(&self) -> RequestReplyTarget {
5049 RequestReplyTarget {
5050 id: self.id.raw().clone(),
5051 method: self.method.clone(),
5052 destination: self.destination.clone(),
5053 }
5054 }
5055}
5056
5057impl<T: JsonRpcResponse> Responder<T, Raw> {
5058 /// Convert this version-neutral responder to protocol `Q`'s responder,
5059 /// for example to pass a responder from a [`HandleDispatchFrom`] or
5060 /// [`MatchDispatch`](crate::util::MatchDispatch) handler to a v2 session
5061 /// helper.
5062 ///
5063 /// Only the request ID's type changes.
5064 ///
5065 /// # Errors
5066 ///
5067 /// Returns Invalid request (`-32600`) if the ID is `null` and `Q` is v2.
5068 /// A v2 connection rejects such requests before dispatch. On conversion
5069 /// failure the responder is dropped, which answers the request with an error.
5070 ///
5071 /// ```
5072 /// # use agent_client_protocol::{Error, Responder, V1, v1::schema};
5073 /// # fn example(responder: Responder<schema::PromptResponse>) -> Result<(), Error> {
5074 /// let responder: agent_client_protocol::v1::Responder<schema::PromptResponse> =
5075 /// responder.into_protocol::<V1>()?;
5076 /// let id: &schema::RequestId = responder.id();
5077 /// # let _ = id;
5078 /// # Ok(())
5079 /// # }
5080 /// ```
5081 pub fn into_protocol<Q: Protocol>(self) -> Result<Responder<T, Q>, crate::Error> {
5082 self.retag()
5083 }
5084}
5085
5086/// Context for handling an incoming JSON-RPC response.
5087///
5088/// This is the response-side counterpart to [`Responder`]. While `Responder` handles
5089/// incoming requests (where you send a response over the wire), `ResponseRouter` handles
5090/// incoming responses (where you route the response to a local task waiting for it).
5091///
5092/// Both are fundamentally "sinks" that push the message through a `send_fn`, but they
5093/// represent different points in the message lifecycle and carry different metadata.
5094///
5095/// # Drop Behavior
5096///
5097/// Dropping a `ResponseRouter` without routing the response (for example, from a
5098/// dispatch handler that claims a [`Dispatch::Response`]) discards the
5099/// response: the local awaiter observes the response as never received. The
5100/// request still counts as settled: routing a response this far disarms the
5101/// originating [`SentRequest`]'s drop-time auto-cancellation even if the router
5102/// is never invoked, since the peer has already answered.
5103///
5104/// `P` is the [`Protocol`] marker that types [`id`](Self::id); see
5105/// [`Responder`].
5106#[must_use]
5107pub struct ResponseRouter<T: JsonRpcResponse = serde_json::Value, P: Protocol = Raw> {
5108 /// The method of the original request.
5109 method: String,
5110
5111 /// The `id` of the original request.
5112 id: HandleId<P>,
5113
5114 /// The [`RoleId`] to which the original request was sent
5115 /// (and hence from which the reply is expected).
5116 role_id: RoleId,
5117
5118 /// Function to send the response to the waiting task.
5119 send_fn: ResponseFn<T, ()>,
5120
5121 /// Shared route used to deliver a dispatch-handler error to the same waiter.
5122 reply_target: ResponseReplyTarget,
5123}
5124
5125impl<T: JsonRpcResponse, P: Protocol> std::fmt::Debug for ResponseRouter<T, P> {
5126 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
5127 f.debug_struct("ResponseRouter")
5128 .field("method", &self.method)
5129 .field("id", &self.id)
5130 .field("response_type", &std::any::type_name::<T>())
5131 .finish_non_exhaustive()
5132 }
5133}
5134
5135impl ResponseRouter<serde_json::Value> {
5136 /// Create a new response context for routing a response to a local awaiter.
5137 ///
5138 /// When [`route_with_result`](Self::route_with_result) is called, the response is sent through the oneshot
5139 /// channel to the code that originally sent the request. If that receiver was
5140 /// dropped, the response is discarded because there is no local awaiter left.
5141 fn new(pending_reply: PendingReply, dispatch: ResponseDispatch) -> Self {
5142 let PendingReply {
5143 id,
5144 method,
5145 role_id,
5146 sender,
5147 cancellation_disarm,
5148 ordering,
5149 response_route_hook,
5150 forwarded_from: _,
5151 accepts_lower_initialize_version: _,
5152 } = pending_reply;
5153 let reply_target = ResponseReplyTarget {
5154 id: id.clone(),
5155 method: method.clone(),
5156 sender: Arc::new(Mutex::new(Some(sender))),
5157 ordering,
5158 dispatch,
5159 };
5160 let send_target = reply_target.clone();
5161 // A response for the request reached this router, so the request is
5162 // settled from the peer's perspective and a `$/cancel_request` could
5163 // only ever be redundant. Disarm immediately so handlers may retain
5164 // the router without leaving auto-cancellation armed.
5165 cancellation_disarm.disarm();
5166 let hook_method = method.clone();
5167 Self {
5168 method,
5169 id: HandleId::raw_layer(id),
5170 role_id,
5171 send_fn: Box::new(move |response: Result<serde_json::Value, crate::Error>| {
5172 let response = match response {
5173 Ok(value) => match response_route_hook {
5174 Some(hook) => hook(&hook_method, &value).map(|()| value),
5175 None => Ok(value),
5176 },
5177 Err(error) => Err(error),
5178 };
5179 send_target.route(response);
5180 Ok(())
5181 }),
5182 reply_target,
5183 }
5184 }
5185}
5186
5187impl<P: Protocol> ResponseRouter<serde_json::Value, P> {
5188 /// Cast this response context to a different response type.
5189 ///
5190 /// The provided type `T` will be serialized to JSON before sending.
5191 pub fn cast<T: JsonRpcResponse>(self) -> ResponseRouter<T, P> {
5192 self.wrap_params(move |method, value| match value {
5193 Ok(value) => T::into_json(value, method),
5194 Err(e) => Err(e),
5195 })
5196 }
5197}
5198
5199impl<T: JsonRpcResponse, P: Protocol> ResponseRouter<T, P> {
5200 /// Method of the original request
5201 #[must_use]
5202 pub fn method(&self) -> &str {
5203 &self.method
5204 }
5205
5206 /// ID of the original request, as this router's protocol version types
5207 /// it.
5208 #[must_use]
5209 pub fn id(&self) -> &P::RequestId {
5210 self.id.typed()
5211 }
5212
5213 /// ID of the original request exactly as it was sent on the wire.
5214 ///
5215 /// This is the same ID as [`id`](Self::id), in the version-neutral form
5216 /// used by routers, forwarders and tracing.
5217 #[must_use]
5218 pub fn raw_id(&self) -> &RawJsonRpcId {
5219 self.id.raw()
5220 }
5221
5222 /// The peer to which the original request was sent.
5223 ///
5224 /// This is the peer from which we expect to receive the response.
5225 #[must_use]
5226 pub fn role_id(&self) -> RoleId {
5227 self.role_id.clone()
5228 }
5229
5230 /// Convert to a `ResponseRouter` that expects a JSON value
5231 /// and which checks (dynamically) that the JSON value it receives
5232 /// can be converted to `T`.
5233 pub fn erase_to_json(self) -> ResponseRouter<serde_json::Value, P> {
5234 self.wrap_params(|method, value| T::from_json(method, value?))
5235 }
5236
5237 /// The same router for protocol `Q`. Fails only if the request ID is not
5238 /// allowed by `Q`, which cannot happen because the SDK never assigns
5239 /// `null` to requests it sends.
5240 pub(crate) fn retag<Q: Protocol>(self) -> Result<ResponseRouter<T, Q>, crate::Error> {
5241 Ok(ResponseRouter {
5242 method: self.method,
5243 id: self.id.into_protocol()?,
5244 role_id: self.role_id,
5245 send_fn: self.send_fn,
5246 reply_target: self.reply_target,
5247 })
5248 }
5249
5250 /// The same router with a version-neutral [`Raw`] request ID. This never
5251 /// fails.
5252 pub fn into_raw(self) -> ResponseRouter<T, Raw> {
5253 ResponseRouter {
5254 method: self.method,
5255 id: self.id.into_raw(),
5256 role_id: self.role_id,
5257 send_fn: self.send_fn,
5258 reply_target: self.reply_target,
5259 }
5260 }
5261
5262 /// Return a new [`ResponseRouter`] that expects a response of type `U`.
5263 ///
5264 /// `wrap_fn` will be invoked with the method name and the result to transform
5265 /// type `U` into type `T` before sending.
5266 fn wrap_params<U: JsonRpcResponse>(
5267 self,
5268 wrap_fn: impl FnOnce(&str, Result<U, crate::Error>) -> Result<T, crate::Error> + Send + 'static,
5269 ) -> ResponseRouter<U, P> {
5270 let method = self.method.clone();
5271 ResponseRouter {
5272 method: self.method,
5273 id: self.id,
5274 role_id: self.role_id,
5275 send_fn: Box::new(move |input: Result<U, crate::Error>| {
5276 let t_value = wrap_fn(&method, input);
5277 (self.send_fn)(t_value)
5278 }),
5279 reply_target: self.reply_target,
5280 }
5281 }
5282
5283 /// Route the response result to the waiting task.
5284 ///
5285 /// # Errors
5286 ///
5287 /// Response and conversion errors are delivered to the waiter. Routing
5288 /// itself currently returns `Ok(())`, even if the waiter has been dropped.
5289 pub fn route_with_result(self, response: Result<T, crate::Error>) -> Result<(), crate::Error> {
5290 tracing::debug!(id = ?self.id, "response routed to awaiter");
5291 (self.send_fn)(response)
5292 }
5293
5294 /// Route a successful response value to the waiting task.
5295 ///
5296 /// # Errors
5297 ///
5298 /// Conversion errors go to the waiter, as in [`route_with_result`](Self::route_with_result).
5299 pub fn route(self, response: T) -> Result<(), crate::Error> {
5300 self.route_with_result(Ok(response))
5301 }
5302
5303 /// Route an internal error to the waiting task.
5304 ///
5305 /// # Errors
5306 ///
5307 /// The internal error goes to the waiter, not to the caller of this method.
5308 pub fn route_with_internal_error(self, message: impl ToString) -> Result<(), crate::Error> {
5309 self.route_with_error(crate::util::internal_error(message))
5310 }
5311
5312 /// Route an error response to the waiting task.
5313 ///
5314 /// # Errors
5315 ///
5316 /// The supplied error goes to the waiter, not to the caller of this method.
5317 pub fn route_with_error(self, error: crate::Error) -> Result<(), crate::Error> {
5318 tracing::debug!(id = ?self.id, error = ?crate::util::redacted_error(error.code), "error routed to awaiter");
5319 self.route_with_result(Err(error))
5320 }
5321}
5322
5323impl<T: JsonRpcResponse> ResponseRouter<T, Raw> {
5324 /// Convert this version-neutral router to protocol `Q`'s router.
5325 ///
5326 /// # Errors
5327 ///
5328 /// Fails only for an ID that `Q` rejects. The SDK never assigns `null`
5329 /// to outgoing requests, so its routers convert to every protocol marker.
5330 pub fn into_protocol<Q: Protocol>(self) -> Result<ResponseRouter<T, Q>, crate::Error> {
5331 self.retag()
5332 }
5333}
5334
5335/// Common bounds for any JSON-RPC message.
5336///
5337/// # Derive Macro
5338///
5339/// For simple message types, you can use the `JsonRpcRequest` or `JsonRpcNotification` derive macros
5340/// which will implement both `JsonRpcMessage` and the respective trait. See [`JsonRpcRequest`] and
5341/// [`JsonRpcNotification`] for examples.
5342pub trait JsonRpcMessage: 'static + Debug + Sized + Send + Clone {
5343 /// Check if this message type matches the given method name.
5344 fn matches_method(method: &str) -> bool;
5345
5346 /// The method name for the message.
5347 fn method(&self) -> &str;
5348
5349 /// Convert this message into an untyped message.
5350 ///
5351 /// # Errors
5352 ///
5353 /// Returns an error if the message's params cannot be encoded as JSON.
5354 fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error>;
5355
5356 /// Parse this type from a method name and the message's JSON `params`.
5357 ///
5358 /// Callers should use `matches_method` first to check if this type handles the method.
5359 /// A message without `params` is parsed from [`serde_json::Value::Null`].
5360 ///
5361 /// # Errors
5362 ///
5363 /// Returns an error if the method doesn't match or its params cannot be decoded.
5364 fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error>;
5365}
5366
5367/// Defines the "payload" of a successful response to a JSON-RPC request.
5368///
5369/// # Derive Macro
5370///
5371/// Use `#[derive(JsonRpcResponse)]` to automatically implement this trait:
5372///
5373/// ```ignore
5374/// use agent_client_protocol::JsonRpcResponse;
5375/// use serde::{Serialize, Deserialize};
5376///
5377/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
5378/// struct HelloResponse {
5379/// greeting: String,
5380/// }
5381/// ```
5382pub trait JsonRpcResponse: 'static + Debug + Sized + Send + Clone {
5383 /// Convert this message into a JSON value.
5384 ///
5385 /// # Errors
5386 ///
5387 /// Returns an error if the response cannot be encoded for `method`.
5388 fn into_json(self, method: &str) -> Result<serde_json::Value, crate::Error>;
5389
5390 /// Parse a JSON value into the response type.
5391 ///
5392 /// # Errors
5393 ///
5394 /// Returns an error if `value` cannot be decoded as the response to `method`.
5395 fn from_json(method: &str, value: serde_json::Value) -> Result<Self, crate::Error>;
5396}
5397
5398impl JsonRpcResponse for serde_json::Value {
5399 fn from_json(_method: &str, value: serde_json::Value) -> Result<Self, crate::Error> {
5400 Ok(value)
5401 }
5402
5403 fn into_json(self, _method: &str) -> Result<serde_json::Value, crate::Error> {
5404 Ok(self)
5405 }
5406}
5407
5408/// A struct that represents a notification (JSON-RPC message that does not expect a response).
5409///
5410/// # Derive Macro
5411///
5412/// Use `#[derive(JsonRpcNotification)]` to automatically implement both `JsonRpcMessage` and `JsonRpcNotification`:
5413///
5414/// ```ignore
5415/// use agent_client_protocol::JsonRpcNotification;
5416/// use serde::{Serialize, Deserialize};
5417///
5418/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcNotification)]
5419/// #[notification(method = "_ping")]
5420/// struct PingNotification {
5421/// timestamp: u64,
5422/// }
5423/// ```
5424pub trait JsonRpcNotification: JsonRpcMessage {}
5425
5426/// A struct that represents a request (JSON-RPC message expecting a response).
5427///
5428/// # Derive Macro
5429///
5430/// Use `#[derive(JsonRpcRequest)]` to automatically implement both `JsonRpcMessage` and `JsonRpcRequest`:
5431///
5432/// ```ignore
5433/// use agent_client_protocol::{JsonRpcRequest, JsonRpcResponse};
5434/// use serde::{Serialize, Deserialize};
5435///
5436/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcRequest)]
5437/// #[request(method = "_hello", response = HelloResponse)]
5438/// struct HelloRequest {
5439/// name: String,
5440/// }
5441///
5442/// #[derive(Debug, Clone, Serialize, Deserialize, JsonRpcResponse)]
5443/// struct HelloResponse {
5444/// greeting: String,
5445/// }
5446/// ```
5447pub trait JsonRpcRequest: JsonRpcMessage {
5448 /// The type of data expected in response.
5449 type Response: JsonRpcResponse;
5450}
5451
5452/// An incoming request, notification, or response being dispatched through handlers.
5453/// Requests include the context used to answer them; responses include the context
5454/// used to route them to the local requester.
5455///
5456/// Type parameters allow specifying the concrete request and notification types.
5457/// By default, both are `UntypedMessage` for dynamic dispatch.
5458/// The request context's response type matches the request's response type.
5459///
5460/// `P` is the [`Protocol`] marker of the request handles. Typed handlers on
5461/// v1 builders receive `Dispatch<Req, Notif, V1>` and those on v2 builders
5462/// `Dispatch<Req, Notif, V2>`. The version-neutral [`HandleDispatchFrom`]
5463/// layer uses the default, [`Raw`], whose `id()` is the wire ID.
5464#[derive(Debug)]
5465pub enum Dispatch<
5466 Req: JsonRpcRequest = UntypedMessage,
5467 Notif: JsonRpcNotification = UntypedMessage,
5468 P: Protocol = Raw,
5469> {
5470 /// Incoming request and the context where the response should be sent.
5471 Request(Req, Responder<Req::Response, P>),
5472
5473 /// Incoming notification.
5474 Notification(Notif),
5475
5476 /// Incoming response to a request we sent.
5477 ///
5478 /// The first field is the response result (success or error from the remote).
5479 /// The second field is the context for forwarding the response to its destination
5480 /// (typically a waiting oneshot channel).
5481 Response(
5482 Result<Req::Response, crate::Error>,
5483 ResponseRouter<Req::Response, P>,
5484 ),
5485}
5486
5487impl<Req: JsonRpcRequest, Notif: JsonRpcNotification, P: Protocol> Dispatch<Req, Notif, P> {
5488 /// Map the request and notification types to new types.
5489 ///
5490 /// Note: Response variants are passed through unchanged since they don't
5491 /// contain a parseable message payload.
5492 pub fn map<Req1, Notif1>(
5493 self,
5494 map_request: impl FnOnce(
5495 Req,
5496 Responder<Req::Response, P>,
5497 ) -> (Req1, Responder<Req1::Response, P>),
5498 map_notification: impl FnOnce(Notif) -> Notif1,
5499 ) -> Dispatch<Req1, Notif1, P>
5500 where
5501 Req1: JsonRpcRequest<Response = Req::Response>,
5502 Notif1: JsonRpcNotification,
5503 {
5504 match self {
5505 Dispatch::Request(request, responder) => {
5506 let (new_request, new_responder) = map_request(request, responder);
5507 Dispatch::Request(new_request, new_responder)
5508 }
5509 Dispatch::Notification(notification) => {
5510 let new_notification = map_notification(notification);
5511 Dispatch::Notification(new_notification)
5512 }
5513 Dispatch::Response(result, router) => Dispatch::Response(result, router),
5514 }
5515 }
5516
5517 /// Convert the request or notification to an untyped message.
5518 ///
5519 /// # Errors
5520 ///
5521 /// Returns an error for a response, which has no method params, or if
5522 /// the request or notification cannot encode its params.
5523 pub fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error> {
5524 match self {
5525 Dispatch::Request(request, _) => request.to_untyped_message(),
5526 Dispatch::Notification(notification) => notification.to_untyped_message(),
5527 Dispatch::Response(_, _) => Err(crate::util::internal_error(
5528 "Response variant has no untyped message representation",
5529 )),
5530 }
5531 }
5532
5533 /// Convert self to an untyped message context.
5534 ///
5535 /// # Errors
5536 ///
5537 /// Returns an error for a response, or if the request or notification
5538 /// cannot encode its params.
5539 pub fn into_untyped_dispatch(
5540 self,
5541 ) -> Result<Dispatch<UntypedMessage, UntypedMessage, P>, crate::Error> {
5542 match self {
5543 Dispatch::Request(request, responder) => Ok(Dispatch::Request(
5544 request.to_untyped_message()?,
5545 responder.erase_to_json(),
5546 )),
5547 Dispatch::Notification(notification) => {
5548 Ok(Dispatch::Notification(notification.to_untyped_message()?))
5549 }
5550 Dispatch::Response(_, _) => Err(crate::util::internal_error(
5551 "cannot convert Response variant to untyped message context",
5552 )),
5553 }
5554 }
5555
5556 /// Returns the request ID if this is a request or response, None if notification.
5557 ///
5558 /// See [`Responder::id`] and [`ResponseRouter::id`].
5559 pub fn id(&self) -> Option<&P::RequestId> {
5560 match self {
5561 Dispatch::Request(_, cx) => Some(cx.id()),
5562 Dispatch::Notification(_) => None,
5563 Dispatch::Response(_, cx) => Some(cx.id()),
5564 }
5565 }
5566
5567 /// Returns the request ID exactly as it appears on the wire if this is a
5568 /// request or response, None if notification.
5569 ///
5570 /// See [`Responder::raw_id`] and [`ResponseRouter::raw_id`].
5571 #[must_use]
5572 pub fn raw_id(&self) -> Option<&RawJsonRpcId> {
5573 match self {
5574 Dispatch::Request(_, cx) => Some(cx.raw_id()),
5575 Dispatch::Notification(_) => None,
5576 Dispatch::Response(_, cx) => Some(cx.raw_id()),
5577 }
5578 }
5579
5580 /// The same dispatch with request handles for protocol `Q`.
5581 ///
5582 /// Fails only for a request whose `null` ID `Q` does not allow, which
5583 /// cannot happen for a message received on a connection that speaks `Q`.
5584 pub(crate) fn retag<Q: Protocol>(self) -> Result<Dispatch<Req, Notif, Q>, crate::Error> {
5585 Ok(match self {
5586 Dispatch::Request(request, responder) => Dispatch::Request(request, responder.retag()?),
5587 Dispatch::Notification(notification) => Dispatch::Notification(notification),
5588 Dispatch::Response(result, router) => Dispatch::Response(result, router.retag()?),
5589 })
5590 }
5591
5592 /// The same dispatch with version-neutral [`Raw`] request handles, for
5593 /// example to hand a typed dispatch to a [`HandleDispatchFrom`]
5594 /// implementation. This never fails.
5595 pub fn into_raw(self) -> Dispatch<Req, Notif, Raw> {
5596 match self {
5597 Dispatch::Request(request, responder) => {
5598 Dispatch::Request(request, responder.into_raw())
5599 }
5600 Dispatch::Notification(notification) => Dispatch::Notification(notification),
5601 Dispatch::Response(result, router) => Dispatch::Response(result, router.into_raw()),
5602 }
5603 }
5604
5605 fn handler_error_target(&self) -> Option<HandlerErrorTarget> {
5606 match self {
5607 Dispatch::Request(_, responder) => {
5608 Some(HandlerErrorTarget::Request(responder.reply_target()))
5609 }
5610 Dispatch::Notification(_) => None,
5611 Dispatch::Response(_, router) => {
5612 Some(HandlerErrorTarget::Response(router.reply_target.clone()))
5613 }
5614 }
5615 }
5616
5617 /// Returns the method of the message.
5618 ///
5619 /// For requests and notifications, this is the method from the message payload.
5620 /// For responses, this is the method of the original request.
5621 pub fn method(&self) -> &str {
5622 match self {
5623 Dispatch::Request(msg, _) => msg.method(),
5624 Dispatch::Notification(msg) => msg.method(),
5625 Dispatch::Response(_, cx) => cx.method(),
5626 }
5627 }
5628}
5629
5630impl<Req: JsonRpcRequest, Notif: JsonRpcNotification> Dispatch<Req, Notif, Raw> {
5631 /// Convert this version-neutral dispatch to protocol `Q`'s request
5632 /// handles.
5633 ///
5634 /// # Errors
5635 ///
5636 /// See [`Responder::into_protocol`]: this fails only for a request whose
5637 /// `null` ID `Q` does not allow, with the Invalid Request error
5638 /// (`-32600`).
5639 pub fn into_protocol<Q: Protocol>(self) -> Result<Dispatch<Req, Notif, Q>, crate::Error> {
5640 self.retag()
5641 }
5642}
5643
5644impl Dispatch {
5645 /// Attempts to parse `self` into a typed message context.
5646 ///
5647 /// # Returns
5648 ///
5649 /// * `Ok(Ok(typed))` if this dispatch matches the requested type for its variant
5650 /// * `Ok(Err(self))` if it does not match the requested type for its variant
5651 /// * `Err` if its method matches the requested type but parsing fails
5652 #[tracing::instrument(skip(self), fields(Request = ?std::any::type_name::<Req>(), Notif = ?std::any::type_name::<Notif>()), level = "trace", ret)]
5653 pub(crate) fn into_typed_dispatch<Req: JsonRpcRequest, Notif: JsonRpcNotification>(
5654 self,
5655 ) -> Result<Result<Dispatch<Req, Notif>, Dispatch>, crate::Error> {
5656 tracing::debug!(
5657 method = self.method(),
5658 id = ?self.raw_id(),
5659 "into_typed_dispatch"
5660 );
5661 match self {
5662 Dispatch::Request(message, responder) => {
5663 if Req::matches_method(&message.method) {
5664 match Req::parse_message(&message.method, &message.params) {
5665 Ok(req) => {
5666 tracing::trace!("parsed ok");
5667 Ok(Ok(Dispatch::Request(req, responder.cast())))
5668 }
5669 Err(err) => {
5670 tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5671 Err(err)
5672 }
5673 }
5674 } else {
5675 tracing::trace!("method doesn't match");
5676 Ok(Err(Dispatch::Request(message, responder)))
5677 }
5678 }
5679
5680 Dispatch::Notification(message) => {
5681 if Notif::matches_method(&message.method) {
5682 match Notif::parse_message(&message.method, &message.params) {
5683 Ok(notif) => {
5684 tracing::trace!("parse ok");
5685 Ok(Ok(Dispatch::Notification(notif)))
5686 }
5687 Err(err) => {
5688 tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5689 Err(err)
5690 }
5691 }
5692 } else {
5693 tracing::trace!("method doesn't match");
5694 Ok(Err(Dispatch::Notification(message)))
5695 }
5696 }
5697
5698 Dispatch::Response(result, cx) => {
5699 let method = cx.method();
5700 if Req::matches_method(method) {
5701 // Parse the response result
5702 let typed_result = match result {
5703 Ok(value) => {
5704 match <Req::Response as JsonRpcResponse>::from_json(method, value) {
5705 Ok(parsed) => {
5706 tracing::trace!("parse ok");
5707 Ok(parsed)
5708 }
5709 Err(err) => {
5710 tracing::trace!(err = ?crate::util::redacted_error(err.code), "parse error");
5711 return Err(err);
5712 }
5713 }
5714 }
5715 Err(err) => {
5716 tracing::trace!("error, passthrough");
5717 Err(err)
5718 }
5719 };
5720 Ok(Ok(Dispatch::Response(typed_result, cx.cast())))
5721 } else {
5722 tracing::trace!("method doesn't match");
5723 Ok(Err(Dispatch::Response(result, cx)))
5724 }
5725 }
5726 }
5727 }
5728
5729 /// True if this message has a field with the given name.
5730 ///
5731 /// Returns `false` for Response variants.
5732 #[must_use]
5733 pub fn has_field(&self, field_name: &str) -> bool {
5734 self.message()
5735 .and_then(|m| m.params().get(field_name))
5736 .is_some()
5737 }
5738
5739 /// Returns true if this message has a session-id field.
5740 ///
5741 /// Returns `false` for Response variants.
5742 pub(crate) fn has_session_id(&self) -> bool {
5743 self.has_field("sessionId")
5744 }
5745
5746 /// Extract the ACP session-id from this message (if any).
5747 ///
5748 /// Returns `Ok(None)` for Response variants.
5749 pub(crate) fn get_session_id(&self) -> Result<Option<SessionId>, crate::Error> {
5750 let Some(message) = self.message() else {
5751 return Ok(None);
5752 };
5753 let Some(value) = message.params().get("sessionId") else {
5754 return Ok(None);
5755 };
5756 let session_id = serde_json::from_value(value.clone())?;
5757 Ok(Some(session_id))
5758 }
5759
5760 /// Try to parse this as a notification of the given type.
5761 ///
5762 /// # Returns
5763 ///
5764 /// * `Ok(Ok(typed))` if this is a notification of the requested type
5765 /// * `Ok(Err(self))` if this is not a matching notification
5766 ///
5767 /// # Errors
5768 ///
5769 /// Returns the parsing error if the method matches but its params cannot be decoded.
5770 pub fn into_notification<N: JsonRpcNotification>(
5771 self,
5772 ) -> Result<Result<N, Dispatch>, crate::Error> {
5773 match self {
5774 Dispatch::Notification(msg) => {
5775 if !N::matches_method(&msg.method) {
5776 return Ok(Err(Dispatch::Notification(msg)));
5777 }
5778 match N::parse_message(&msg.method, &msg.params) {
5779 Ok(n) => Ok(Ok(n)),
5780 Err(err) => Err(err),
5781 }
5782 }
5783 Dispatch::Request(..) | Dispatch::Response(..) => Ok(Err(self)),
5784 }
5785 }
5786
5787 /// Try to parse this as a request of the given type.
5788 ///
5789 /// # Returns
5790 ///
5791 /// * `Ok(Ok(typed))` if this is a request of the requested type
5792 /// * `Ok(Err(self))` if this is not a matching request
5793 ///
5794 /// # Errors
5795 ///
5796 /// Returns the parsing error if the method matches but its params cannot be decoded.
5797 pub fn into_request<Req: JsonRpcRequest>(
5798 self,
5799 ) -> crate::Result<Result<RequestWithResponder<Req>, Dispatch>> {
5800 match self {
5801 Dispatch::Request(msg, responder) => {
5802 if !Req::matches_method(&msg.method) {
5803 return Ok(Err(Dispatch::Request(msg, responder)));
5804 }
5805 match Req::parse_message(&msg.method, &msg.params) {
5806 Ok(req) => Ok(Ok((req, responder.cast()))),
5807 Err(err) => Err(err),
5808 }
5809 }
5810 Dispatch::Notification(..) | Dispatch::Response(..) => Ok(Err(self)),
5811 }
5812 }
5813}
5814
5815impl<M: JsonRpcRequest + JsonRpcNotification> Dispatch<M, M> {
5816 /// Returns the message payload for requests and notifications.
5817 ///
5818 /// Returns `None` for Response variants since they don't contain a message payload.
5819 pub fn message(&self) -> Option<&M> {
5820 match self {
5821 Dispatch::Request(msg, _) | Dispatch::Notification(msg) => Some(msg),
5822 Dispatch::Response(_, _) => None,
5823 }
5824 }
5825
5826 /// Map the request/notification message.
5827 ///
5828 /// Response variants pass through unchanged.
5829 pub(crate) fn try_map_message(
5830 self,
5831 map_message: impl FnOnce(M) -> Result<M, crate::Error>,
5832 ) -> Result<Dispatch<M, M>, crate::Error> {
5833 match self {
5834 Dispatch::Request(request, cx) => Ok(Dispatch::Request(map_message(request)?, cx)),
5835 Dispatch::Notification(notification) => {
5836 Ok(Dispatch::<M, M>::Notification(map_message(notification)?))
5837 }
5838 Dispatch::Response(result, cx) => Ok(Dispatch::Response(result, cx)),
5839 }
5840 }
5841}
5842
5843/// An incoming JSON message without any typing. Can be a request or a notification.
5844#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
5845pub struct UntypedMessage {
5846 /// The JSON-RPC method name
5847 pub method: String,
5848 /// The JSON-RPC parameters as a raw JSON value
5849 pub params: serde_json::Value,
5850}
5851
5852impl UntypedMessage {
5853 /// Returns an untyped message with the given method and parameters.
5854 ///
5855 /// # Errors
5856 ///
5857 /// Returns an error if `params` cannot be serialized as JSON.
5858 pub fn new(method: &str, params: impl Serialize) -> Result<Self, crate::Error> {
5859 let params = serde_json::to_value(params)?;
5860 Ok(Self {
5861 method: method.to_string(),
5862 params,
5863 })
5864 }
5865
5866 /// Returns the method name
5867 #[must_use]
5868 pub fn method(&self) -> &str {
5869 &self.method
5870 }
5871
5872 /// Returns the parameters as a JSON value
5873 #[must_use]
5874 pub fn params(&self) -> &serde_json::Value {
5875 &self.params
5876 }
5877
5878 /// Consumes this message and returns the method and params
5879 #[must_use]
5880 pub fn into_parts(self) -> (String, serde_json::Value) {
5881 (self.method, self.params)
5882 }
5883
5884 /// Convert `self` to a raw JSON-RPC message.
5885 pub(crate) fn into_raw_jsonrpc_message(
5886 self,
5887 id: Option<RawJsonRpcId>,
5888 ) -> Result<RawJsonRpcMessage, crate::Error> {
5889 let Self { method, params } = self;
5890 match id {
5891 Some(id) => RawJsonRpcMessage::request(method, params, id),
5892 None => RawJsonRpcMessage::notification(method, params),
5893 }
5894 }
5895}
5896
5897impl JsonRpcMessage for UntypedMessage {
5898 fn matches_method(_method: &str) -> bool {
5899 // UntypedMessage matches any method - it's the untyped fallback
5900 true
5901 }
5902
5903 fn method(&self) -> &str {
5904 &self.method
5905 }
5906
5907 fn to_untyped_message(&self) -> Result<UntypedMessage, crate::Error> {
5908 Ok(self.clone())
5909 }
5910
5911 fn parse_message(method: &str, params: &serde_json::Value) -> Result<Self, crate::Error> {
5912 UntypedMessage::new(method, params)
5913 }
5914}
5915
5916impl JsonRpcRequest for UntypedMessage {
5917 type Response = serde_json::Value;
5918}
5919
5920impl JsonRpcNotification for UntypedMessage {}
5921
5922/// Represents a pending response of type `R` from an outgoing request.
5923///
5924/// Returned by [`ConnectionTo::send_request`], this type provides explicit response-consumption
5925/// modes. The API is intentionally designed to make it difficult to accidentally wait for a
5926/// response inside the dispatch loop.
5927///
5928/// # Anti-Footgun Design
5929///
5930/// You cannot directly `.await` a `SentRequest`. Instead, you must choose how to handle
5931/// the response:
5932///
5933/// ## Option 1: Register an Ordered Callback (Safe in Handlers)
5934///
5935/// Calling [`on_receiving_result`](Self::on_receiving_result) registers the callback and returns
5936/// immediately. When ordered consumption is selected before the response is routed during its
5937/// original dispatch, the loop waits for the callback to complete before processing the next
5938/// message:
5939///
5940/// ```no_run
5941/// # use agent_client_protocol_test::*;
5942/// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
5943/// cx.send_request(MyRequest {})
5944/// .on_receiving_result(async |result| {
5945/// match result {
5946/// Ok(response) => {
5947/// // Handle successful response
5948/// Ok(())
5949/// }
5950/// Err(error) => {
5951/// // Handle error
5952/// Err(error)
5953/// }
5954/// }
5955/// })?;
5956/// # Ok(())
5957/// # }
5958/// ```
5959///
5960/// ## Option 2: Wait Outside the Dispatch Loop
5961///
5962/// Use [`block_task`](Self::block_task) only when the current task already runs outside the
5963/// dispatch loop—for example, in the foreground future passed to `connect_with` or in a task
5964/// created with [`ConnectionTo::spawn`]. Never await it in a handler:
5965///
5966/// ```no_run
5967/// # use agent_client_protocol_test::*;
5968/// # async fn example(cx: agent_client_protocol::ConnectionTo<agent_client_protocol::UntypedRole>) -> Result<(), agent_client_protocol::Error> {
5969/// // ✅ Safe: Spawned task runs concurrently
5970/// cx.spawn({
5971/// let cx = cx.clone();
5972/// async move {
5973/// let response = cx.send_request(MyRequest {})
5974/// .block_task()
5975/// .await?;
5976/// // Process response...
5977/// Ok(())
5978/// }
5979/// })?;
5980/// # Ok(())
5981/// # }
5982/// ```
5983///
5984/// ```no_run
5985/// # use agent_client_protocol_test::*;
5986/// # async fn example() -> Result<(), agent_client_protocol::Error> {
5987/// # let connection = mock_connection();
5988/// // ❌ NEVER do this in a handler - blocks the event loop!
5989/// connection.on_receive_request(async |req: MyRequest, responder, cx| {
5990/// let response = cx.send_request(MyRequest {})
5991/// .block_task() // This will deadlock!
5992/// .await?;
5993/// responder.respond(response)
5994/// }, agent_client_protocol::on_receive_request!())
5995/// # .connect_to(agent_client_protocol_test::MockTransport).await?;
5996/// # Ok(())
5997/// # }
5998/// ```
5999///
6000/// # Why This Design?
6001///
6002/// If you block the event loop while waiting for a response, the connection cannot process
6003/// the incoming response message, creating a deadlock. This API design prevents that footgun
6004/// by making blocking explicit and encouraging non-blocking patterns.
6005///
6006/// # Drop Behavior
6007///
6008/// By default, dropping a `SentRequest` before the SDK has received the
6009/// response sends a `$/cancel_request` notification asking the peer to cancel
6010/// the request, then discards the response when it arrives. Requests whose
6011/// eventual response should be ignored, but which should keep running on the
6012/// peer, should use [`detach`](Self::detach) instead.
6013///
6014/// # Incoming Transport EOF
6015///
6016/// If the incoming transport reaches clean EOF before the response arrives, every
6017/// consumption mode receives an error with the message `Incoming transport
6018/// closed` and data containing
6019/// `{"reason":"incoming_transport_closed","method":"..."}`. Requests made
6020/// after incoming EOF fail immediately with the same error. Use
6021/// [`is_incoming_transport_closed`] to identify it.
6022///
6023/// # Protocol version
6024///
6025/// `P` is the [`Protocol`] marker of the connection handle that sent the
6026/// request: [`Raw`] for the version-neutral [`ConnectionTo`], `V2` for
6027/// `v2::ConnectionTo`. It selects the type [`id`](Self::id) returns.
6028#[must_use = "dropping a SentRequest asks the peer to cancel the request and \
6029 discards the response; consume it with `block_task`, \
6030 `on_receiving_result`, `forward_response_to`, or `detach`"]
6031pub struct SentRequest<T, P: Protocol = Raw> {
6032 id: HandleId<P>,
6033 method: String,
6034 task_tx: TaskTx,
6035 pending_replies: PendingRepliesRegistrar,
6036 response_rx: oneshot::Receiver<ResponsePayload>,
6037 /// Converts the raw response into the typed result. It receives error
6038 /// responses too, so [`SentRequest::recover_error`] can map an error to a
6039 /// success.
6040 to_result: ResponseFn<serde_json::Value, T>,
6041 cancellation: SentRequestCancellation,
6042 response_ordering: ResponseOrdering,
6043 /// Cancellation markers of other (incoming) requests whose cancellation
6044 /// should be forwarded to this request. See
6045 /// [`forward_cancellation_from`](Self::forward_cancellation_from).
6046 cancellation_sources: Vec<RequestCancellation>,
6047}
6048
6049/// A request that has not been published to its connection.
6050///
6051/// Created by [`ConnectionTo::prepare_request`] or
6052/// [`ConnectionTo::prepare_request_to`]. Preparation serializes the request but
6053/// does not register a pending reply or enqueue outgoing traffic. Dropping this
6054/// value sends neither the request nor a cancellation notification.
6055///
6056/// A consuming method publishes the request synchronously:
6057///
6058/// - [`on_receiving_result`](Self::on_receiving_result),
6059/// [`on_receiving_ok_result`](Self::on_receiving_ok_result), and
6060/// [`forward_response_to`](Self::forward_response_to) register ordered response
6061/// handling before publication. When a peer response is routed during its
6062/// original dispatch, later inbound messages wait for that handling to finish.
6063/// - [`block_task`](Self::block_task) publishes immediately and returns an
6064/// unordered response future. Publication does not wait for its first poll.
6065/// - [`detach`](Self::detach) publishes immediately and discards the response.
6066///
6067/// Ordered callbacks must do bounded work and must not await later inbound
6068/// traffic on the same connection. EOF failures and responses routed through a
6069/// retained [`ResponseRouter`] after their original dispatch have no ordering
6070/// barrier. See [`crate::concepts::ordering`].
6071///
6072/// # Errors
6073///
6074/// Preparation and publication failures are delivered to the selected response
6075/// consumer. Callback-style methods return an error if their task cannot be
6076/// registered; in that case the request is not published. [`detach`](Self::detach)
6077/// returns preparation or publication errors directly because it has no response
6078/// consumer. A callback returning an error terminates the connection.
6079///
6080/// `P` is the [`Protocol`] marker that types [`id`](Self::id); see
6081/// [`SentRequest`].
6082#[must_use = "a prepared request is not sent until consumed with `block_task`, \
6083 `on_receiving_result`, `forward_response_to`, or `detach`"]
6084pub struct PreparedRequest<T, P: Protocol = Raw> {
6085 sent: SentRequest<T, P>,
6086 publication: RequestPublication,
6087}
6088
6089struct RequestPublication {
6090 message: Result<OutgoingMessage, crate::Error>,
6091 pending_reply: PendingReply,
6092 message_tx: OutgoingMessageTx,
6093 pending_replies: PendingRepliesRegistrar,
6094 incoming_closed: IncomingClosed,
6095}
6096
6097impl RequestPublication {
6098 /// Both logical peers of an SDK proxy share a connection. When forwarding
6099 /// a callback, translate its parent ID exactly once, at publication.
6100 fn translate_proxied_elicitation(&mut self) -> Result<(), crate::Error> {
6101 let Some(callback) = &self.pending_reply.forwarded_from else {
6102 // A locally authored request is already in the destination's namespace.
6103 return Ok(());
6104 };
6105 let Ok(OutgoingMessage::Request {
6106 remote_style: RemoteStyle::Predecessor,
6107 untyped,
6108 ..
6109 }) = &mut self.message
6110 else {
6111 return Ok(());
6112 };
6113 if self.pending_reply.role_id != crate::Client.role_id() {
6114 return Ok(());
6115 }
6116 self.pending_replies
6117 .translate_elicitation(Agent.role_id(), untyped, |origin| {
6118 callback.local_peer == Some(RemoteStyle::Successor)
6119 && origin.local_peer == Some(RemoteStyle::Predecessor)
6120 })
6121 }
6122
6123 fn publish(mut self) -> Result<(), crate::Error> {
6124 let message = if self.incoming_closed.is_closing() {
6125 Err(incoming_transport_closed_error(&self.pending_reply.method))
6126 } else {
6127 self.translate_proxied_elicitation().and(self.message)
6128 };
6129 let message = match message {
6130 Ok(message) => message,
6131 Err(error) => {
6132 self.pending_reply.fail(error.clone());
6133 return Err(error);
6134 }
6135 };
6136 let OutgoingMessage::Request { id, method, .. } = &message else {
6137 unreachable!();
6138 };
6139 let id = id.clone();
6140 let method = method.clone();
6141 let cancellation_disarm = self.pending_reply.cancellation_disarm.clone();
6142 // Register before enqueueing so incoming EOF can fail every observable
6143 // request before close callbacks begin. The outgoing actor checks that
6144 // the registration still exists before sending the request.
6145 self.pending_replies
6146 .subscribe(id.clone(), self.pending_reply, &self.incoming_closed)?;
6147 if self.message_tx.unbounded_send(message).is_err() {
6148 let error = if self.incoming_closed.is_closing() {
6149 incoming_transport_closed_error(&method)
6150 } else {
6151 crate::util::internal_error(format!("failed to send outgoing request `{method}`"))
6152 };
6153 if let Some(pending_reply) = self.pending_replies.remove(&id) {
6154 pending_reply.fail(error.clone());
6155 }
6156 return Err(error);
6157 }
6158 // An escaped cancellation handle must not enqueue cancellation before
6159 // the request. A fast response or EOF may already have disarmed it.
6160 cancellation_disarm.arm();
6161 Ok(())
6162 }
6163}
6164
6165impl<T: Debug, P: Protocol> Debug for PreparedRequest<T, P> {
6166 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6167 formatter
6168 .debug_struct("PreparedRequest")
6169 .field("request", &self.sent)
6170 .finish_non_exhaustive()
6171 }
6172}
6173
6174impl<T, P: Protocol> PreparedRequest<T, P> {
6175 /// The same prepared request with a version-neutral [`Raw`] request ID,
6176 /// for code that is not tied to one protocol version. This never fails
6177 /// and does not publish the request.
6178 pub fn into_raw(self) -> PreparedRequest<T, Raw> {
6179 PreparedRequest {
6180 sent: self.sent.into_raw(),
6181 publication: self.publication,
6182 }
6183 }
6184}
6185
6186impl<T> PreparedRequest<T, Raw> {
6187 /// Convert this version-neutral prepared request to protocol `Q`'s
6188 /// handle without publishing it.
6189 ///
6190 /// # Errors
6191 ///
6192 /// Fails only for an ID that `Q` rejects. IDs reserved by the SDK are
6193 /// never `null` and convert to every protocol marker.
6194 pub fn into_protocol<Q: Protocol>(self) -> Result<PreparedRequest<T, Q>, crate::Error> {
6195 Ok(PreparedRequest {
6196 sent: self.sent.into_protocol()?,
6197 publication: self.publication,
6198 })
6199 }
6200}
6201
6202impl<T, P: Protocol> PreparedRequest<T, P> {
6203 /// The ID reserved for this request, which has not been sent yet, as
6204 /// this request's protocol version types it.
6205 ///
6206 /// It is the ID written to the wire when the request is published. The
6207 /// SDK never assigns `null`.
6208 #[must_use]
6209 pub fn id(&self) -> &P::RequestId {
6210 self.sent.id()
6211 }
6212
6213 /// The ID reserved for this request in the version-neutral form used by
6214 /// routers, forwarders and tracing. It is the same ID as
6215 /// [`id`](Self::id).
6216 #[must_use]
6217 pub fn raw_id(&self) -> &RawJsonRpcId {
6218 self.sent.raw_id()
6219 }
6220
6221 /// The method of the prepared request.
6222 #[must_use]
6223 pub fn method(&self) -> &str {
6224 self.sent.method()
6225 }
6226
6227 /// Retain explicit cancellation control without publishing this request.
6228 ///
6229 /// The handle can outlive consumption of this request by an ordered callback
6230 /// or response future. Calling it before publication is a no-op, not a
6231 /// cancellation to apply when the request is later published. Dropping the
6232 /// handle does not cancel. See [`RequestCancellationHandle`].
6233 #[must_use]
6234 pub fn cancellation_handle(&self) -> RequestCancellationHandle {
6235 self.sent.cancellation_handle()
6236 }
6237
6238 /// Map a successful response without publishing the request.
6239 ///
6240 /// The mapper has the same contract as [`SentRequest::map`].
6241 pub fn map<U>(
6242 self,
6243 map_fn: impl FnOnce(T) -> Result<U, crate::Error> + 'static + Send,
6244 ) -> PreparedRequest<U, P>
6245 where
6246 T: 'static,
6247 {
6248 PreparedRequest {
6249 sent: self.sent.map(map_fn),
6250 publication: self.publication,
6251 }
6252 }
6253
6254 /// Register a cancellation source without publishing the request.
6255 ///
6256 /// After publication, cancellation is forwarded while awaiting the response,
6257 /// as described by [`SentRequest::forward_cancellation_from`].
6258 pub fn forward_cancellation_from(mut self, source: RequestCancellation) -> Self {
6259 self.sent = self.sent.forward_cancellation_from(source);
6260 self
6261 }
6262
6263 /// Associate this outgoing request with the incoming request being forwarded.
6264 ///
6265 /// Use this when transforming the response in a custom proxy callback.
6266 /// The association lets default ACP forwarding translate request-scoped
6267 /// elicitations and propagates cancellation from `responder`. Merely
6268 /// sharing a cancellation source does not establish request identity.
6269 /// If this request is itself an elicitation forwarded to the client,
6270 /// its request-scope ID is translated before sending.
6271 /// [`forward_response_to`](Self::forward_response_to) does this automatically.
6272 pub fn forwarded_from<Q: Protocol>(mut self, responder: &Responder<T, Q>) -> Self
6273 where
6274 T: JsonRpcResponse,
6275 {
6276 self.publication.pending_reply.forwarded_from =
6277 Some(responder.origin_for_forwarding(&self.publication.message_tx));
6278 self.forward_cancellation_from(responder.cancellation())
6279 }
6280
6281 /// Publish now and return an unordered future for the response.
6282 ///
6283 /// The request is enqueued during this call, not when the future is first
6284 /// polled. Dropping that future asks the peer to cancel a still-outstanding
6285 /// request. Await it only outside the dispatch loop; awaiting it in an
6286 /// incoming handler deadlocks just like [`SentRequest::block_task`].
6287 ///
6288 /// # Errors
6289 ///
6290 /// The returned future delivers preparation, publication, and response errors.
6291 pub fn block_task(self) -> impl Future<Output = Result<T, crate::Error>> {
6292 self.into_sent_request(false).block_task()
6293 }
6294
6295 /// Publish now and discard the eventual response without cancelling.
6296 ///
6297 /// # Errors
6298 ///
6299 /// Returns immediate preparation or enqueue failures. Later local
6300 /// transformation errors and peer response errors are discarded along with
6301 /// successful responses. Transport failures still propagate through the
6302 /// connection future. Retained [`RequestCancellationHandle`] values can
6303 /// still explicitly cancel the request while it remains pending.
6304 pub fn detach(self) -> Result<(), crate::Error> {
6305 let result = self.publication.publish();
6306 self.sent.detach();
6307 result
6308 }
6309
6310 /// Register an ordered callback, then publish the request.
6311 ///
6312 /// Ordering is selected before publication, even when the connection runs
6313 /// concurrently. See [`PreparedRequest`] for barrier limits and deadlock risks.
6314 ///
6315 /// # Errors
6316 ///
6317 /// Returns an error if the callback task cannot be registered, without
6318 /// publishing the request. Preparation and publication errors are delivered
6319 /// to the callback. Returning an error from the callback ends the connection.
6320 #[track_caller]
6321 pub fn on_receiving_result<F>(
6322 self,
6323 task: impl FnOnce(Result<T, crate::Error>) -> F + 'static + Send,
6324 ) -> Result<(), crate::Error>
6325 where
6326 T: 'static,
6327 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6328 {
6329 self.consume_with(move |response| match response {
6330 Ok(result) => Either::Left(task(result)),
6331 Err(error) => Either::Right(future::ready(Err(error))),
6332 })
6333 }
6334
6335 /// Register an ordered success callback, then publish the request.
6336 ///
6337 /// Errors are forwarded to `responder`, as with
6338 /// [`SentRequest::on_receiving_ok_result`].
6339 ///
6340 /// # Errors
6341 ///
6342 /// Returns a task-registration error without publishing the request.
6343 /// Preparation, publication, and response errors are forwarded to `responder`.
6344 /// Returning an error from the callback ends the connection.
6345 #[track_caller]
6346 pub fn on_receiving_ok_result<F, Q: Protocol>(
6347 self,
6348 responder: Responder<T, Q>,
6349 task: impl FnOnce(T, Responder<T, Q>) -> F + 'static + Send,
6350 ) -> Result<(), crate::Error>
6351 where
6352 T: JsonRpcResponse,
6353 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6354 {
6355 self.on_receiving_result(async move |result| match result {
6356 Ok(value) => task(value, responder).await,
6357 Err(error) => responder.respond_with_error(error),
6358 })
6359 }
6360
6361 /// Register ordered response forwarding, then publish the request.
6362 ///
6363 /// The upstream request ID is recorded before publication, so even an
6364 /// immediate request-scoped elicitation can be translated on its way back.
6365 /// Cancellation and response errors propagate as with [`SentRequest::forward_response_to`].
6366 ///
6367 /// # Errors
6368 ///
6369 /// Returns a task-registration error without publishing the request.
6370 /// Preparation, publication, and response errors are forwarded to `responder`.
6371 #[track_caller]
6372 pub fn forward_response_to<Q: Protocol>(
6373 self,
6374 responder: Responder<T, Q>,
6375 ) -> Result<(), crate::Error>
6376 where
6377 T: JsonRpcResponse,
6378 {
6379 self.forwarded_from(&responder)
6380 .consume_with(async move |response| {
6381 responder.respond_with_result(response.unwrap_or_else(Err))
6382 })
6383 }
6384
6385 pub(crate) fn into_sent_request(self, ordered: bool) -> SentRequest<T, P> {
6386 if ordered {
6387 self.sent.response_ordering.mark_ordered();
6388 }
6389 // Publication errors also settle the response channel.
6390 drop(self.publication.publish());
6391 self.sent
6392 }
6393
6394 #[track_caller]
6395 fn consume_with<F>(
6396 self,
6397 handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
6398 ) -> Result<(), crate::Error>
6399 where
6400 T: 'static,
6401 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6402 {
6403 let published_tx = self.register_consumer(handle)?;
6404 drop(self.publication.publish());
6405 // Keep the cancellation guard here until publication completes. Even
6406 // destruction of the registered task cannot cancel before enqueueing.
6407 drop(published_tx.send(self.sent));
6408 Ok(())
6409 }
6410
6411 #[track_caller]
6412 fn register_consumer<F>(
6413 &self,
6414 handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
6415 ) -> Result<oneshot::Sender<SentRequest<T, P>>, crate::Error>
6416 where
6417 T: 'static,
6418 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
6419 {
6420 self.sent.response_ordering.mark_ordered();
6421 let (published_tx, published_rx) = oneshot::channel::<SentRequest<T, P>>();
6422 Task::new(Location::caller(), async move {
6423 match published_rx.await {
6424 Ok(sent) => sent.handle_response(handle).await,
6425 // Publication was abandoned before the consumer took ownership.
6426 Err(_) => Ok(()),
6427 }
6428 })
6429 .spawn(&self.sent.task_tx)?;
6430 Ok(published_tx)
6431 }
6432}
6433
6434#[derive(Clone, Debug)]
6435pub(crate) struct SentRequestCancellationDisarm {
6436 state: Arc<AtomicU8>,
6437}
6438
6439#[repr(u8)]
6440enum OutgoingCancellationState {
6441 Unpublished,
6442 Armed,
6443 Disarmed,
6444}
6445
6446impl SentRequestCancellationDisarm {
6447 fn new() -> Self {
6448 Self {
6449 state: Arc::new(AtomicU8::new(OutgoingCancellationState::Unpublished as u8)),
6450 }
6451 }
6452
6453 fn disarm(&self) {
6454 self.state
6455 .store(OutgoingCancellationState::Disarmed as u8, Ordering::Release);
6456 }
6457
6458 fn arm(&self) -> bool {
6459 self.state
6460 .compare_exchange(
6461 OutgoingCancellationState::Unpublished as u8,
6462 OutgoingCancellationState::Armed as u8,
6463 Ordering::AcqRel,
6464 Ordering::Acquire,
6465 )
6466 .is_ok()
6467 }
6468
6469 fn take_armed(&self) -> bool {
6470 self.state
6471 .compare_exchange(
6472 OutgoingCancellationState::Armed as u8,
6473 OutgoingCancellationState::Disarmed as u8,
6474 Ordering::AcqRel,
6475 Ordering::Acquire,
6476 )
6477 .is_ok()
6478 }
6479
6480 fn is_armed(&self) -> bool {
6481 self.state.load(Ordering::Acquire) == OutgoingCancellationState::Armed as u8
6482 }
6483
6484 fn is_disarmed(&self) -> bool {
6485 self.state.load(Ordering::Acquire) == OutgoingCancellationState::Disarmed as u8
6486 }
6487}
6488
6489/// Explicit cancellation control for one outgoing request.
6490///
6491/// Obtain this handle from [`PreparedRequest::cancellation_handle`] or
6492/// [`SentRequest::cancellation_handle`] before consuming the request. It retains
6493/// neither the response consumer nor application callback, so cancellation can
6494/// be requested without discarding the eventual response. It does not keep the
6495/// connection driver or response consumer alive, or abort local callback work.
6496///
6497/// Clones share the request's cancellation state with [`SentRequest::cancel`],
6498/// forwarded cancellation, and request-drop automatic cancellation. At most one
6499/// cancellation notification is attempted, on the original request's
6500/// connection. It is a plain `$/cancel_request`, even for a request sent to a
6501/// successor in a `proxy/successor` envelope. Dropping this handle neither cancels the request nor disables its
6502/// automatic cancellation.
6503///
6504/// Cancellation before publication is a no-op and is not remembered for later
6505/// publication. A call racing publication may also be a no-op; call after the
6506/// publishing method returns to target a pending request. Once the SDK routes a
6507/// response or fails the request, subsequent cancellation calls are no-ops,
6508/// even if its callback has not yet run. Detaching the request suppresses only
6509/// automatic cancellation; retained handles can still explicitly cancel it.
6510///
6511/// This controls outgoing requests, unlike [`RequestCancellation`], which
6512/// observes a peer's cancellation of an incoming request.
6513#[derive(Clone)]
6514pub struct RequestCancellationHandle {
6515 message_tx: OutgoingMessageTx,
6516 request_id: RawJsonRpcId,
6517 disarm: SentRequestCancellationDisarm,
6518}
6519
6520impl RequestCancellationHandle {
6521 /// Ask the peer to cancel this request without discarding its response.
6522 ///
6523 /// Cancellation is cooperative: the peer may respond normally or with a
6524 /// cancellation error. Repeated calls, including calls through other clones
6525 /// or the original request, return `Ok(())` without sending another
6526 /// notification. Calls before publication or after settlement are no-ops.
6527 /// An attempt begun before settlement may still enqueue afterward.
6528 ///
6529 /// `Ok(())` means this call encountered no immediate error, not that a
6530 /// notification was sent or the peer stopped work. This method does not
6531 /// wait for transmission or acknowledgment.
6532 ///
6533 /// # Errors
6534 ///
6535 /// Only the call that attempts to send reports serialization or enqueue
6536 /// failure. A failed send is not retried by later cancellation calls.
6537 pub fn cancel(&self) -> Result<(), crate::Error> {
6538 if !self.disarm.take_armed() {
6539 return Ok(());
6540 }
6541
6542 // Build the notification lazily: most requests are never cancelled,
6543 // so this avoids serializing a notification per outgoing request.
6544 //
6545 // `$/cancel_request` is hop-local and always sent plain, even for a
6546 // request sent to a successor: its `requestId` names the
6547 // `proxy/successor` request on this connection.
6548 let untyped = crate::v1::schema::CancelRequestNotification::new(self.request_id.clone())
6549 .to_untyped_message()?;
6550
6551 send_raw_message(&self.message_tx, OutgoingMessage::Notification { untyped })
6552 }
6553}
6554
6555impl Debug for RequestCancellationHandle {
6556 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6557 formatter
6558 .debug_struct("RequestCancellationHandle")
6559 .field("request_id", &self.request_id)
6560 .field("armed", &self.disarm.is_armed())
6561 .finish_non_exhaustive()
6562 }
6563}
6564
6565#[derive(Debug)]
6566struct SentRequestCancellation {
6567 handle: RequestCancellationHandle,
6568 cancel_on_drop: bool,
6569}
6570
6571impl SentRequestCancellation {
6572 fn new(message_tx: OutgoingMessageTx, request_id: RawJsonRpcId) -> Self {
6573 Self {
6574 handle: RequestCancellationHandle {
6575 message_tx,
6576 request_id,
6577 disarm: SentRequestCancellationDisarm::new(),
6578 },
6579 cancel_on_drop: true,
6580 }
6581 }
6582
6583 fn disarm(&self) {
6584 self.handle.disarm.disarm();
6585 }
6586
6587 fn disarm_handle(&self) -> SentRequestCancellationDisarm {
6588 self.handle.disarm.clone()
6589 }
6590
6591 fn send(&self) -> Result<(), crate::Error> {
6592 self.handle.cancel()
6593 }
6594}
6595
6596impl Drop for SentRequestCancellation {
6597 fn drop(&mut self) {
6598 if !self.cancel_on_drop {
6599 return;
6600 }
6601 if let Err(error) = self.send() {
6602 tracing::debug!(
6603 error = ?crate::util::redacted_error(error.code),
6604 "failed to auto-cancel dropped request"
6605 );
6606 }
6607 }
6608}
6609
6610/// Await the response payload for an outgoing request, watching `sources` for
6611/// cancellation of the upstream requests it was registered with.
6612///
6613/// When any source reports cancellation, a `$/cancel_request` is forwarded to
6614/// the outgoing request (at most once, shared with [`SentRequest::cancel`] and
6615/// drop-time auto-cancellation), and the response is *still* awaited: the peer
6616/// always answers, with normal data or a cancellation error.
6617///
6618/// Watching is deliberately bounded by response arrival so that completed
6619/// requests do not leak waiters on markers that will never fire.
6620async fn await_response_forwarding_cancellation(
6621 response_rx: oneshot::Receiver<ResponsePayload>,
6622 cancellation: &SentRequestCancellation,
6623 sources: &[RequestCancellation],
6624) -> Result<ResponsePayload, oneshot::Canceled> {
6625 // Failing to forward the cancellation must not abort the wait: the
6626 // response (normal data or a cancellation error) may still arrive and
6627 // must still be processed.
6628 let forward_cancellation = || {
6629 if let Err(error) = cancellation.send() {
6630 tracing::debug!(
6631 error = ?crate::util::redacted_error(error.code),
6632 "failed to forward cancellation to downstream request"
6633 );
6634 }
6635 };
6636
6637 let response = if sources.is_empty() {
6638 response_rx.await
6639 } else if sources.iter().any(RequestCancellation::is_cancelled) {
6640 forward_cancellation();
6641 response_rx.await
6642 } else {
6643 let cancelled = sources.iter().map(|source| source.state.signal_rx.clone());
6644 match future::select(future::select_all(cancelled), response_rx).await {
6645 Either::Left((_, response_rx)) => {
6646 forward_cancellation();
6647 response_rx.await
6648 }
6649 Either::Right((response, _)) => response,
6650 }
6651 };
6652
6653 cancellation.disarm();
6654 response
6655}
6656
6657impl<T: Debug, P: Protocol> Debug for SentRequest<T, P> {
6658 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
6659 let mut debug = f.debug_struct("SentRequest");
6660 debug
6661 .field("id", &self.id)
6662 .field("method", &self.method)
6663 .field("task_tx", &self.task_tx)
6664 .field("response_rx", &self.response_rx);
6665 debug
6666 .field("cancellation", &self.cancellation)
6667 .field("cancellation_sources", &self.cancellation_sources);
6668 debug.finish_non_exhaustive()
6669 }
6670}
6671
6672impl<P: Protocol> SentRequest<serde_json::Value, P> {
6673 fn new(
6674 id: HandleId<P>,
6675 method: String,
6676 task_tx: mpsc::UnboundedSender<Task>,
6677 pending_replies: PendingRepliesRegistrar,
6678 response_rx: oneshot::Receiver<ResponsePayload>,
6679 cancellation: SentRequestCancellation,
6680 response_ordering: ResponseOrdering,
6681 ) -> Self {
6682 Self {
6683 id,
6684 method,
6685 response_rx,
6686 task_tx,
6687 pending_replies,
6688 to_result: Box::new(|result| result),
6689 cancellation,
6690 response_ordering,
6691 cancellation_sources: Vec::new(),
6692 }
6693 }
6694}
6695
6696impl<T, P: Protocol> SentRequest<T, P> {
6697 /// Detach this request handle without waiting for its response.
6698 ///
6699 /// The response will be discarded when it arrives. This also disables the
6700 /// drop-time automatic cancellation described in
6701 /// [Drop Behavior](Self#drop-behavior), so use it for requests whose
6702 /// eventual response should be ignored, but which should keep running on
6703 /// the peer. The peer is still expected to answer the JSON-RPC request
6704 /// eventually; use a notification instead when no response is expected at
6705 /// all.
6706 ///
6707 /// To ask the peer to stop the request, call `cancel` instead, or drop the
6708 /// handle while automatic cancellation is enabled. A retained
6709 /// [`RequestCancellationHandle`] can still explicitly cancel the detached
6710 /// request until the SDK receives its response or fails it.
6711 pub fn detach(mut self) {
6712 self.cancellation.cancel_on_drop = false;
6713 }
6714
6715 /// Send a `$/cancel_request` notification for this outgoing request.
6716 ///
6717 /// The notification goes over the connection the original request used,
6718 /// with that request's ID, so this is the preferred way to cancel a
6719 /// [`SentRequest`] when the request handle is still available. It is sent
6720 /// plain, never wrapped in `proxy/successor`: for a request sent to a
6721 /// successor, the ID names the `proxy/successor` request on this
6722 /// connection, as the proxy chains RFD specifies.
6723 ///
6724 /// At most one cancellation attempt is made per request, shared with
6725 /// retained handles, forwarded cancellation, and automatic cancellation
6726 /// described in [Drop Behavior](Self#drop-behavior). Later calls return
6727 /// `Ok(())` without another attempt, including when the first attempt failed.
6728 /// Once the SDK has routed the response, a new call is a no-op; an attempt
6729 /// begun before settlement may still enqueue afterward.
6730 ///
6731 /// `Ok(())` means this call encountered no immediate error, not that a
6732 /// notification was sent or the peer stopped work.
6733 ///
6734 /// # Errors
6735 ///
6736 /// Only the call that attempts to send reports a failure to encode or
6737 /// queue the notification. See [`RequestCancellationHandle::cancel`].
6738 pub fn cancel(&self) -> Result<(), crate::Error> {
6739 self.cancellation.send()
6740 }
6741
6742 /// Obtain a handle that remains usable after this request is consumed.
6743 ///
6744 /// The handle shares the once-only cancellation state used by
6745 /// [`cancel`](Self::cancel), response routing, and automatic request-drop
6746 /// cancellation, but has no cancel-on-drop behavior of its own.
6747 #[must_use]
6748 pub fn cancellation_handle(&self) -> RequestCancellationHandle {
6749 self.cancellation.handle.clone()
6750 }
6751
6752 /// Forward cancellation of another request to this one.
6753 ///
6754 /// When the request that `source` belongs to is cancelled by its peer,
6755 /// a `$/cancel_request` for *this* request is sent to its peer, plain and
6756 /// with this request's ID, as [`cancel`](Self::cancel) sends it. The response is still awaited
6757 /// and delivered as usual (normal data or a cancellation error), so this
6758 /// composes with [`block_task`](Self::block_task) and
6759 /// [`on_receiving_result`](Self::on_receiving_result).
6760 ///
6761 /// This is the building block for proxies that forward a request with
6762 /// custom logic instead of [`forward_response_to`](Self::forward_response_to)
6763 /// (which wires this up automatically from its responder). Without it,
6764 /// custom forwarding *absorbs* cancellation: the upstream marker is still
6765 /// set, but nothing is sent downstream.
6766 ///
6767 /// ```
6768 /// # use agent_client_protocol::{ConnectionTo, Error, Responder, UntypedRole};
6769 /// # use agent_client_protocol_test::{MyRequest, MyResponse};
6770 /// # async fn example(request: MyRequest, responder: Responder<MyResponse>, backend: ConnectionTo<UntypedRole>) -> Result<(), Error> {
6771 /// backend
6772 /// .send_request(request)
6773 /// .forward_cancellation_from(responder.cancellation())
6774 /// .on_receiving_result(async move |result| {
6775 /// // Custom result handling, e.g. bookkeeping or rewriting.
6776 /// responder.respond_with_result(result)
6777 /// })?;
6778 /// # Ok(())
6779 /// # }
6780 /// ```
6781 ///
6782 /// May be called multiple times; cancellation of any registered source
6783 /// triggers the forwarding (at most one `$/cancel_request` is ever sent
6784 /// per request). Sources are observed while the response is being
6785 /// awaited — that is, once the handle is consumed with
6786 /// [`block_task`](Self::block_task),
6787 /// [`on_receiving_result`](Self::on_receiving_result), or
6788 /// [`forward_response_to`](Self::forward_response_to); a source that was
6789 /// already cancelled by then is honored immediately.
6790 pub fn forward_cancellation_from(mut self, source: RequestCancellation) -> Self {
6791 self.cancellation_sources.push(source);
6792 self
6793 }
6794}
6795
6796impl<T, P: Protocol> SentRequest<T, P> {
6797 /// The same request handle with a version-neutral [`Raw`] request ID, for
6798 /// code that is not tied to one protocol version. This never fails.
6799 pub fn into_raw(self) -> SentRequest<T, Raw> {
6800 self.retag_id(HandleId::into_raw)
6801 }
6802
6803 fn retag_id<Q: Protocol>(
6804 self,
6805 retag: impl FnOnce(HandleId<P>) -> HandleId<Q>,
6806 ) -> SentRequest<T, Q> {
6807 SentRequest {
6808 id: retag(self.id),
6809 method: self.method,
6810 task_tx: self.task_tx,
6811 pending_replies: self.pending_replies,
6812 response_rx: self.response_rx,
6813 to_result: self.to_result,
6814 cancellation: self.cancellation,
6815 response_ordering: self.response_ordering,
6816 cancellation_sources: self.cancellation_sources,
6817 }
6818 }
6819}
6820
6821impl<T> SentRequest<T, Raw> {
6822 /// Convert this version-neutral request handle to protocol `Q`'s handle.
6823 ///
6824 /// # Errors
6825 ///
6826 /// Fails only for an ID that `Q` rejects. The SDK never assigns `null`
6827 /// to outgoing requests, so its request handles convert to every marker.
6828 pub fn into_protocol<Q: Protocol>(self) -> Result<SentRequest<T, Q>, crate::Error> {
6829 let id = self.id.clone().into_protocol()?;
6830 Ok(self.retag_id(|_| id))
6831 }
6832}
6833
6834impl<T, P: Protocol> SentRequest<T, P> {
6835 /// The id of the outgoing request, as this request's protocol version
6836 /// types it. It is the ID written to the wire; the SDK never assigns
6837 /// `null`.
6838 #[must_use]
6839 pub fn id(&self) -> &P::RequestId {
6840 self.id.typed()
6841 }
6842
6843 /// The id of the outgoing request in the version-neutral form used by
6844 /// routers, forwarders and tracing. It is the same ID as
6845 /// [`id`](Self::id).
6846 #[must_use]
6847 pub fn raw_id(&self) -> &RawJsonRpcId {
6848 self.id.raw()
6849 }
6850
6851 /// The method of the request this is in response to.
6852 #[must_use]
6853 pub fn method(&self) -> &str {
6854 &self.method
6855 }
6856
6857 /// Map a JSON-RPC error response to a result of the same type.
6858 ///
6859 /// The recovery function only sees error responses from the peer, not
6860 /// local failures to decode a successful response. Return `Ok` to treat
6861 /// the error as success, or `Err` to keep failing.
6862 #[cfg_attr(not(feature = "unstable_protocol_v2"), allow(dead_code))]
6863 pub(crate) fn recover_error(
6864 self,
6865 recover: impl FnOnce(crate::Error) -> Result<T, crate::Error> + 'static + Send,
6866 ) -> SentRequest<T, P>
6867 where
6868 T: 'static,
6869 {
6870 let to_result = self.to_result;
6871 SentRequest {
6872 to_result: Box::new(move |result| match result {
6873 Ok(value) => to_result(Ok(value)),
6874 Err(error) => recover(error),
6875 }),
6876 ..self
6877 }
6878 }
6879
6880 /// Map a successful JSON-RPC response into an application type.
6881 ///
6882 /// The mapped type does not need to implement [`JsonRpcResponse`]. The
6883 /// mapper runs at most once and may consume captured state. JSON-RPC error
6884 /// responses bypass the mapper. The mapped type may carry a non-`'static`
6885 /// lifetime when it is consumed with [`block_task`](Self::block_task);
6886 /// callback-style consumption still requires a `'static` mapped type
6887 /// because its work is spawned onto the connection.
6888 pub fn map<U>(
6889 self,
6890 map_fn: impl FnOnce(T) -> Result<U, crate::Error> + 'static + Send,
6891 ) -> SentRequest<U, P>
6892 where
6893 T: 'static,
6894 {
6895 SentRequest {
6896 id: self.id,
6897 method: self.method,
6898 response_rx: self.response_rx,
6899 task_tx: self.task_tx,
6900 pending_replies: self.pending_replies,
6901 to_result: Box::new(move |result| map_fn((self.to_result)(result)?)),
6902 cancellation: self.cancellation,
6903 response_ordering: self.response_ordering,
6904 cancellation_sources: self.cancellation_sources,
6905 }
6906 }
6907
6908 /// Forward the response (success or error) to a request context when it arrives.
6909 ///
6910 /// This is a convenience method for proxying messages between connections. When the
6911 /// response arrives, it will be automatically sent to the provided request context,
6912 /// whether it's a successful response or an error.
6913 ///
6914 /// This also records the upstream ID for request-scoped elicitations.
6915 /// When the peer can run concurrently, use [`PreparedRequest::forward_response_to`]
6916 /// to install that association before the outgoing request is observable.
6917 /// Use the prepared form when relaying an elicitation back to the client:
6918 /// an eager send can no longer change the callback's `params.requestId`.
6919 ///
6920 /// # Example: Proxying requests
6921 ///
6922 /// ```
6923 /// # use agent_client_protocol::UntypedRole;
6924 /// # use agent_client_protocol::{Builder, ConnectionTo};
6925 /// # use agent_client_protocol_test::*;
6926 /// # async fn example(cx: ConnectionTo<UntypedRole>) -> Result<(), agent_client_protocol::Error> {
6927 /// // Set up backend connection builder
6928 /// let backend = UntypedRole.builder()
6929 /// .on_receive_request(async |req: MyRequest, responder, cx| {
6930 /// responder.respond(MyResponse { status: "ok".into() })
6931 /// }, agent_client_protocol::on_receive_request!());
6932 ///
6933 /// // Spawn backend and get a context to send to it
6934 /// let backend_connection = cx.spawn_connection(backend, MockTransport)?;
6935 ///
6936 /// // Set up proxy that forwards requests to backend
6937 /// UntypedRole.builder()
6938 /// .on_receive_request({
6939 /// let backend_connection = backend_connection.clone();
6940 /// async move |req: MyRequest, responder, cx| {
6941 /// // Forward the request to backend and proxy the response back
6942 /// backend_connection.send_request(req)
6943 /// .forward_response_to(responder)?;
6944 /// Ok(())
6945 /// }
6946 /// }, agent_client_protocol::on_receive_request!());
6947 /// # Ok(())
6948 /// # }
6949 /// ```
6950 ///
6951 /// # Type Safety
6952 ///
6953 /// The request context's response type must match the request's response type,
6954 /// ensuring type-safe message forwarding.
6955 ///
6956 /// # When to Use
6957 ///
6958 /// Use this when:
6959 /// - You're implementing a proxy or gateway pattern
6960 /// - You want to forward responses without processing them
6961 /// - The response types match between the outgoing request and incoming request
6962 ///
6963 /// This is equivalent to calling `on_receiving_result` and manually forwarding
6964 /// the result, with two proxy-specific additions:
6965 ///
6966 /// - If the pending response cannot be delivered, the incoming request is
6967 /// answered with an internal error instead of being left unanswered.
6968 /// Known clean incoming EOF is delivered like any other response
6969 /// error; an unexpected response-channel loss is forwarded as an outer
6970 /// consumption error.
6971 /// - When the peer cancels the incoming request, the cancellation is
6972 /// forwarded to the outgoing request, and the downstream response
6973 /// (normal data or a cancellation error) is still forwarded back. This is
6974 /// equivalent to registering the responder's marker with
6975 /// `forward_cancellation_from`.
6976 ///
6977 /// # Errors
6978 ///
6979 /// Returns an error if the connection cannot queue the forwarding task.
6980 /// A failure to receive or decode the response is forwarded to `responder`.
6981 #[track_caller]
6982 pub fn forward_response_to<Q: Protocol>(
6983 self,
6984 responder: Responder<T, Q>,
6985 ) -> Result<(), crate::Error>
6986 where
6987 T: JsonRpcResponse,
6988 {
6989 self.pending_replies.set_origin(
6990 self.raw_id(),
6991 responder.origin_for_forwarding(&self.cancellation.handle.message_tx),
6992 );
6993 let this = self.forward_cancellation_from(responder.cancellation());
6994
6995 this.consume_with(async move |response| {
6996 // An unexpected response-channel loss (outer `Err`) is forwarded
6997 // as an error: the incoming request must not be left unanswered.
6998 responder.respond_with_result(response.unwrap_or_else(Err))
6999 })
7000 }
7001
7002 /// Spawn the response-consumption task shared by
7003 /// [`on_receiving_result`](Self::on_receiving_result) and
7004 /// [`forward_response_to`](Self::forward_response_to).
7005 ///
7006 /// The task awaits the response (forwarding cancellation from registered
7007 /// sources while waiting, converts the payload, and invokes `handle` with
7008 /// the typed result (`Ok(Result<T, _>)`). The dispatch loop's ack, if any,
7009 /// is sent after `handle` completes.
7010 ///
7011 /// Clean incoming EOF is delivered as `Ok(Err(error))`, just like
7012 /// a peer response error, so callback-style consumers still run. If the
7013 /// response channel disappears for another reason, `handle` receives an
7014 /// outer `Err` describing that unexpected loss; there is no ack then.
7015 #[track_caller]
7016 fn consume_with<F>(
7017 self,
7018 handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
7019 ) -> Result<(), crate::Error>
7020 where
7021 T: 'static,
7022 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7023 {
7024 self.response_ordering.mark_ordered();
7025 let task_tx = self.task_tx.clone();
7026 Task::new(Location::caller(), self.handle_response(handle)).spawn(&task_tx)
7027 }
7028
7029 fn handle_response<F>(
7030 self,
7031 handle: impl FnOnce(Result<Result<T, crate::Error>, crate::Error>) -> F + 'static + Send,
7032 ) -> impl Future<Output = Result<(), crate::Error>> + Send
7033 where
7034 T: 'static,
7035 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7036 {
7037 let method = self.method;
7038 let response_rx = self.response_rx;
7039 let to_result = self.to_result;
7040 let cancellation = self.cancellation;
7041 let cancellation_sources = self.cancellation_sources;
7042 async move {
7043 let response = await_response_forwarding_cancellation(
7044 response_rx,
7045 &cancellation,
7046 &cancellation_sources,
7047 )
7048 .await;
7049
7050 match response {
7051 Ok(ResponsePayload { result, ack_tx }) => {
7052 let typed_result = to_result(result);
7053
7054 let outcome = handle(Ok(typed_result)).await;
7055
7056 // Ack AFTER the handler completes - this is the key
7057 // difference from block_task. The dispatch loop waits for
7058 // this ack.
7059 if let Some(tx) = ack_tx {
7060 let _ = tx.send(());
7061 }
7062
7063 outcome
7064 }
7065 Err(err) => {
7066 handle(Err(crate::util::internal_error(format!(
7067 "response to `{method}` never received: {err}"
7068 ))))
7069 .await
7070 }
7071 }
7072 }
7073 }
7074
7075 /// Block the current task until the response is received.
7076 ///
7077 /// **Warning:** This method blocks the current async task. It is safe only when that task
7078 /// already runs outside the dispatch loop, such as the foreground future passed to
7079 /// `connect_with` or a task created with [`ConnectionTo::spawn`]. Using it directly in a
7080 /// handler callback will deadlock the connection.
7081 ///
7082 /// # Safe Usage (outside the dispatch loop)
7083 ///
7084 /// ```no_run
7085 /// # use agent_client_protocol_test::*;
7086 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7087 /// # let connection = mock_connection();
7088 /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7089 /// // Spawn a task to handle the request
7090 /// cx.spawn({
7091 /// let connection = cx.clone();
7092 /// async move {
7093 /// // Safe: We're in a spawned task, not blocking the event loop
7094 /// let response = connection.send_request(OtherRequest {})
7095 /// .block_task()
7096 /// .await?;
7097 ///
7098 /// // Process the response...
7099 /// Ok(())
7100 /// }
7101 /// })?;
7102 ///
7103 /// // Respond immediately
7104 /// responder.respond(MyResponse { status: "ok".into() })
7105 /// }, agent_client_protocol::on_receive_request!())
7106 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7107 /// # Ok(())
7108 /// # }
7109 /// ```
7110 ///
7111 /// # Unsafe Usage (in handlers - will deadlock!)
7112 ///
7113 /// ```no_run
7114 /// # use agent_client_protocol_test::*;
7115 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7116 /// # let connection = mock_connection();
7117 /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7118 /// // ❌ DEADLOCK: Handler blocks event loop, which can't process the response
7119 /// let response = cx.send_request(OtherRequest {})
7120 /// .block_task()
7121 /// .await?;
7122 ///
7123 /// responder.respond(MyResponse { status: response.value })
7124 /// }, agent_client_protocol::on_receive_request!())
7125 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7126 /// # Ok(())
7127 /// # }
7128 /// ```
7129 ///
7130 /// # When to Use
7131 ///
7132 /// Use this method when:
7133 /// - Your current task already runs outside the dispatch loop
7134 /// - You need the response value to proceed with your logic
7135 /// - Linear control flow is more natural than callbacks
7136 ///
7137 /// For handler callbacks, use [`on_receiving_result`](Self::on_receiving_result) instead.
7138 ///
7139 /// # Errors
7140 ///
7141 /// Returns a request or peer response error, an error decoding or mapping
7142 /// the response, or an error if the connection closes before the reply arrives.
7143 pub async fn block_task(self) -> Result<T, crate::Error> {
7144 let response = await_response_forwarding_cancellation(
7145 self.response_rx,
7146 &self.cancellation,
7147 &self.cancellation_sources,
7148 )
7149 .await;
7150
7151 match response {
7152 Ok(ResponsePayload { result, ack_tx }) => {
7153 // Blocking consumers ack before converting or returning the
7154 // value, so dispatch can continue while the caller processes it.
7155 if let Some(tx) = ack_tx {
7156 let _ = tx.send(());
7157 }
7158 (self.to_result)(result)
7159 }
7160 Err(err) => Err(crate::util::internal_error(format!(
7161 "response to `{}` never received: {}",
7162 self.method, err
7163 ))),
7164 }
7165 }
7166
7167 /// Block the current task and transform the typed result before releasing
7168 /// the ordered-response barrier.
7169 ///
7170 /// Framework lifecycle code uses this when success transfers local state
7171 /// to the returned value while an error must drop that state before later
7172 /// messages from the same transport frame are dispatched. The synchronous
7173 /// transform must not wait for additional connection traffic.
7174 pub(crate) async fn block_task_with_ordered_result<U>(
7175 self,
7176 transform: impl FnOnce(Result<T, crate::Error>) -> Result<U, crate::Error>,
7177 ) -> Result<U, crate::Error> {
7178 let response = await_response_forwarding_cancellation(
7179 self.response_rx,
7180 &self.cancellation,
7181 &self.cancellation_sources,
7182 )
7183 .await;
7184
7185 let (result, ack_tx) = match response {
7186 Ok(ResponsePayload { result, ack_tx }) => ((self.to_result)(result), ack_tx),
7187 Err(error) => (
7188 Err(crate::util::internal_error(format!(
7189 "response to `{}` never received: {error}",
7190 self.method
7191 ))),
7192 None,
7193 ),
7194 };
7195
7196 let outcome = transform(result);
7197 if let Some(acknowledgment) = ack_tx {
7198 let _ = acknowledgment.send(());
7199 }
7200 outcome
7201 }
7202
7203 /// Schedule an async task to run when a successful response is received.
7204 ///
7205 /// This is a convenience wrapper around [`on_receiving_result`](Self::on_receiving_result)
7206 /// for the common pattern of forwarding errors to a request context while only processing
7207 /// successful responses.
7208 ///
7209 /// # Behavior
7210 ///
7211 /// - If the response is `Ok(value)`, your task receives the value and the request context
7212 /// - If the response is `Err(error)`, the error is automatically sent to `responder`
7213 /// and your task is not called
7214 ///
7215 /// # Example: Chaining requests
7216 ///
7217 /// ```no_run
7218 /// # use agent_client_protocol_test::*;
7219 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7220 /// # let connection = mock_connection();
7221 /// connection.on_receive_request(async |req: ValidateRequest, responder, cx| {
7222 /// // Send initial request
7223 /// cx.send_request(ValidateRequest { data: req.data.clone() })
7224 /// .on_receiving_ok_result(responder, async |validation, responder| {
7225 /// // Only runs if validation succeeded
7226 /// if validation.is_valid {
7227 /// // Respond to original request
7228 /// responder.respond(ValidateResponse { is_valid: true, error: None })
7229 /// } else {
7230 /// responder.respond_with_error(agent_client_protocol::Error::internal_error().data("validation failed"))
7231 /// }
7232 /// })?;
7233 ///
7234 /// Ok(())
7235 /// }, agent_client_protocol::on_receive_request!())
7236 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7237 /// # Ok(())
7238 /// # }
7239 /// ```
7240 ///
7241 /// # Ordering
7242 ///
7243 /// Like [`on_receiving_result`](Self::on_receiving_result), response handling holds the
7244 /// dispatch loop through callback completion when ordered consumption is selected before a
7245 /// peer response is routed during its original dispatch. Pending-request failures delivered
7246 /// without an incoming response and delayed routes do not carry that barrier. The callback
7247 /// must not await later inbound traffic on the same connection. See the
7248 /// [`ordering`](crate::concepts::ordering) module for details.
7249 ///
7250 /// # When to Use
7251 ///
7252 /// Use this when:
7253 /// - You need to respond to a request based on another request's result
7254 /// - You want errors to automatically propagate to the request context
7255 /// - You only care about the success case
7256 ///
7257 /// For more control over error handling, use [`on_receiving_result`](Self::on_receiving_result).
7258 ///
7259 /// # Errors
7260 ///
7261 /// Returns an error if the callback task cannot be queued. A request
7262 /// error is sent to `responder` instead of invoking the success callback.
7263 #[track_caller]
7264 pub fn on_receiving_ok_result<F, Q: Protocol>(
7265 self,
7266 responder: Responder<T, Q>,
7267 task: impl FnOnce(T, Responder<T, Q>) -> F + 'static + Send,
7268 ) -> Result<(), crate::Error>
7269 where
7270 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7271 T: JsonRpcResponse,
7272 {
7273 self.on_receiving_result(async move |result| match result {
7274 Ok(value) => task(value, responder).await,
7275 Err(err) => responder.respond_with_error(err),
7276 })
7277 }
7278
7279 /// Register an async callback to run when the response is received.
7280 ///
7281 /// This is the recommended way to select response handling from inside a handler because
7282 /// registration returns immediately. The response-consumption task waits concurrently for
7283 /// the response; once the response is dispatched, the ordered callback may hold the dispatch
7284 /// loop until it completes.
7285 ///
7286 /// # Example: Handle response in callback
7287 ///
7288 /// ```no_run
7289 /// # use agent_client_protocol_test::*;
7290 /// # async fn example() -> Result<(), agent_client_protocol::Error> {
7291 /// # let connection = mock_connection();
7292 /// connection.on_receive_request(async |req: MyRequest, responder, cx| {
7293 /// // Send a request and schedule a callback for the response
7294 /// cx.send_request(QueryRequest { id: 22 })
7295 /// .on_receiving_result({
7296 /// let connection = cx.clone();
7297 /// async move |result| {
7298 /// match result {
7299 /// Ok(response) => {
7300 /// println!("Got response: {:?}", response);
7301 /// // Can send more messages here
7302 /// connection.send_notification(QueryComplete {})?;
7303 /// Ok(())
7304 /// }
7305 /// Err(error) => {
7306 /// eprintln!("Request failed: {}", error);
7307 /// Err(error)
7308 /// }
7309 /// }
7310 /// }
7311 /// })?;
7312 ///
7313 /// // Handler continues immediately after registering the callback
7314 /// responder.respond(MyResponse { status: "processing".into() })
7315 /// }, agent_client_protocol::on_receive_request!())
7316 /// # .connect_to(agent_client_protocol_test::MockTransport).await?;
7317 /// # Ok(())
7318 /// # }
7319 /// ```
7320 ///
7321 /// # Ordering
7322 ///
7323 /// When ordered consumption is selected before a peer response is routed during its original
7324 /// dispatch, the callback runs in a connection-managed task and the dispatch loop waits for
7325 /// it to complete before processing the next message.
7326 ///
7327 /// The barrier does not apply when the pending request is failed without an incoming response,
7328 /// such as on EOF. If the response was already routed, or an interceptor routes a retained
7329 /// [`ResponseRouter`] after its original dispatch, the callback still runs but cannot
7330 /// retroactively block messages that were already released.
7331 ///
7332 /// While the barrier is held, the callback must not await a later response, notification, or
7333 /// other inbound traffic on the same connection: that traffic cannot be dispatched until the
7334 /// callback completes. Spawn follow-up work with [`ConnectionTo::spawn`] and return, or use
7335 /// [`block_task`](Self::block_task) from a task already outside the dispatch loop.
7336 ///
7337 /// This differs from [`block_task`](Self::block_task), which does not select ordered
7338 /// consumption: dispatch remains free while the caller processes the delivered response.
7339 ///
7340 /// See the [`ordering`](crate::concepts::ordering) module for details on ordering guarantees
7341 /// and how to avoid deadlocks.
7342 ///
7343 /// # Errors
7344 ///
7345 /// Returns an error if the callback task cannot be queued. Peer errors
7346 /// and response decoding errors are passed to the callback. An error
7347 /// returned by the callback shuts down the connection.
7348 ///
7349 /// # When to Use
7350 ///
7351 /// Use this method when:
7352 /// - You need to register response handling from a handler callback
7353 /// - You want a peer response callback to complete before later messages are dispatched
7354 /// - The callback performs bounded work that does not depend on later inbound traffic
7355 ///
7356 /// When already outside the dispatch loop and you do not need ordering guarantees, consider
7357 /// [`block_task`](Self::block_task).
7358 #[track_caller]
7359 pub fn on_receiving_result<F>(
7360 self,
7361 task: impl FnOnce(Result<T, crate::Error>) -> F + 'static + Send,
7362 ) -> Result<(), crate::Error>
7363 where
7364 T: 'static,
7365 F: Future<Output = Result<(), crate::Error>> + 'static + Send,
7366 {
7367 self.consume_with(move |response| match response {
7368 // Invoke the callback before constructing its future so the
7369 // response value does not need to be `Send` across an await.
7370 Ok(result) => Either::Left(task(result)),
7371 // A response that was never delivered fails the consuming
7372 // task instead of invoking the callback.
7373 Err(err) => Either::Right(future::ready(Err(err))),
7374 })
7375 }
7376}
7377
7378// ============================================================================
7379// IntoJrConnectionTransport Implementations
7380// ============================================================================
7381
7382/// A component that communicates over line streams.
7383///
7384/// `Lines` implements the [`ConnectTo`] trait for any pair of line-based streams
7385/// (a `Stream<Item = io::Result<String>>` for incoming and a `Sink<String>` for outgoing),
7386/// handling serialization of JSON-RPC messages to/from newline-delimited JSON.
7387/// Each line carries one JSON-RPC message. JSON-RPC batch arrays are not supported: an
7388/// incoming array is answered with a single invalid-request (`-32600`) error with `id: null`.
7389///
7390/// This is a lower-level primitive than [`ByteStreams`] that enables interception and
7391/// transformation of individual lines before they are parsed or after they are serialized.
7392/// This is particularly useful for debugging, logging, or implementing custom line-based
7393/// protocols.
7394///
7395/// An `Err` from the incoming stream ends the connection. A stream that decodes bytes itself
7396/// should replace invalid UTF-8, as [`ByteStreams`] does, instead of yielding an error for it.
7397///
7398/// # Use Cases
7399///
7400/// - **Line-by-line logging**: Intercept and log each line before parsing
7401/// - **Custom protocols**: Transform lines before/after JSON-RPC processing
7402/// - **Debugging**: Inspect raw message strings
7403/// - **Line filtering**: Skip or modify specific messages
7404///
7405/// Most users should use [`ByteStreams`] instead, which provides a simpler interface
7406/// for byte-based I/O.
7407///
7408/// [`ConnectTo`]: crate::ConnectTo
7409#[derive(Debug)]
7410pub struct Lines<OutgoingSink, IncomingStream> {
7411 outgoing: OutgoingSink,
7412 incoming: IncomingStream,
7413}
7414
7415impl<OutgoingSink, IncomingStream> Lines<OutgoingSink, IncomingStream>
7416where
7417 OutgoingSink: futures::Sink<String, Error = std::io::Error> + Send + 'static,
7418 IncomingStream: futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7419{
7420 /// Create a new line stream transport.
7421 pub fn new(outgoing: OutgoingSink, incoming: IncomingStream) -> Self {
7422 Self { outgoing, incoming }
7423 }
7424
7425 fn into_channel_transport(self) -> (Channel, crate::ConnectionDriver) {
7426 let Self { outgoing, incoming } = self;
7427 let (channel_for_caller, channel_for_lines) = Channel::duplex();
7428 let Channel { mut rx, tx } = channel_for_lines;
7429 let (finish_tx, finish_rx) = oneshot::channel();
7430 let finish = async move {
7431 // Losing a finish handle is not a shutdown request.
7432 if finish_rx.await.is_err() {
7433 future::pending::<()>().await;
7434 }
7435 }
7436 .boxed()
7437 .shared();
7438 let outgoing_frames = futures::stream::poll_fn({
7439 let mut finish = finish.clone();
7440 let mut finishing = false;
7441 move |cx| {
7442 if !finishing && std::pin::Pin::new(&mut finish).poll(cx).is_ready() {
7443 rx.close();
7444 finishing = true;
7445 }
7446 rx.poll_next_unpin(cx)
7447 }
7448 });
7449 let discard_incoming = Arc::new(AtomicBool::new(false));
7450 let incoming = incoming.filter_map({
7451 let discard_incoming = discard_incoming.clone();
7452 move |item| {
7453 let discard = discard_incoming.load(Ordering::Acquire);
7454 future::ready((!discard || item.is_err()).then_some(item))
7455 }
7456 });
7457 let outgoing = transport_actor::transport_outgoing_lines_actor(outgoing_frames, outgoing)
7458 .boxed()
7459 .shared();
7460 let serve_self = Box::pin({
7461 let outgoing = outgoing.clone();
7462 async move {
7463 futures::try_join!(
7464 outgoing,
7465 transport_actor::transport_incoming_lines_actor(incoming, tx),
7466 )?;
7467 Ok(())
7468 }
7469 });
7470 let server_future = crate::ConnectionDriver::with_finish(
7471 async move {
7472 match future::select(finish, serve_self).await {
7473 Either::Left(((), serve_self)) => {
7474 discard_incoming.store(true, Ordering::Release);
7475 // Keep reading while flushing, but do not require remote
7476 // read EOF. Poll incoming errors before clean sink drain.
7477 match future::select(serve_self, outgoing).await {
7478 Either::Left((result, _)) | Either::Right((result, _)) => result,
7479 }
7480 }
7481 Either::Right((result, _)) => result,
7482 }
7483 },
7484 move || {
7485 let _ = finish_tx.send(());
7486 },
7487 );
7488
7489 (channel_for_caller, server_future)
7490 }
7491}
7492
7493impl<OutgoingSink, IncomingStream, R: Role> ConnectTo<R> for Lines<OutgoingSink, IncomingStream>
7494where
7495 OutgoingSink: futures::Sink<String, Error = std::io::Error> + Send + 'static,
7496 IncomingStream: futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7497{
7498 async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7499 let (channel, mut serve_self) = self.into_channel_transport();
7500 let mut finish = serve_self
7501 .take_finish()
7502 .expect("built-in Lines transport supports explicit finishing");
7503 let client_future = Box::pin(ConnectTo::<R>::connect_to(channel, client));
7504
7505 match futures::future::select(client_future, serve_self).await {
7506 Either::Left((result, serve_self)) => {
7507 result?;
7508 // The local bridge has transferred all accepted client output.
7509 // Finish the physical sink without waiting for remote read EOF.
7510 finish.request();
7511 serve_self.await
7512 }
7513 Either::Right((result, _)) => result,
7514 }
7515 }
7516
7517 fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7518 let (channel, driver) = self.into_channel_transport();
7519 (channel, Some(driver))
7520 }
7521}
7522
7523/// A component that communicates over byte streams (stdin/stdout, sockets, pipes, etc.).
7524///
7525/// `ByteStreams` implements the [`ConnectTo`] trait for any pair of `AsyncRead` and `AsyncWrite`
7526/// streams, handling serialization of JSON-RPC messages to/from newline-delimited JSON.
7527/// This is the standard way to communicate with external processes or network connections.
7528///
7529/// Incoming bytes that are not valid UTF-8 are replaced with U+FFFD, so a line that contains
7530/// them is parsed like any other and does not end the connection.
7531///
7532/// # Use Cases
7533///
7534/// - **Stdio communication**: Connect to agents or proxies via stdin/stdout
7535/// - **Network sockets**: TCP, Unix domain sockets, or other stream-based protocols
7536/// - **Named pipes**: Cross-process communication on the same machine
7537/// - **File I/O**: Reading from and writing to file descriptors
7538///
7539/// # Example
7540///
7541/// Connecting to an agent via stdio:
7542///
7543/// ```no_run
7544/// use agent_client_protocol::UntypedRole;
7545/// # use agent_client_protocol::{ByteStreams};
7546/// use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
7547///
7548/// # async fn example() -> Result<(), agent_client_protocol::Error> {
7549/// let component = ByteStreams::new(
7550/// tokio::io::stdout().compat_write(),
7551/// tokio::io::stdin().compat(),
7552/// );
7553///
7554/// // Use as a component in a connection
7555/// agent_client_protocol::UntypedRole.builder()
7556/// .name("my-client")
7557/// .connect_to(component)
7558/// .await?;
7559/// # Ok(())
7560/// # }
7561/// ```
7562///
7563/// [`ConnectTo`]: crate::ConnectTo
7564#[derive(Debug)]
7565pub struct ByteStreams<OB, IB> {
7566 outgoing: OB,
7567 incoming: IB,
7568}
7569
7570impl<OB, IB> ByteStreams<OB, IB>
7571where
7572 OB: AsyncWrite + Send + 'static,
7573 IB: AsyncRead + Send + 'static,
7574{
7575 /// Create a new byte stream transport.
7576 pub fn new(outgoing: OB, incoming: IB) -> Self {
7577 Self { outgoing, incoming }
7578 }
7579
7580 fn into_lines(
7581 self,
7582 ) -> Lines<
7583 impl futures::Sink<String, Error = std::io::Error> + Send + 'static,
7584 impl futures::Stream<Item = std::io::Result<String>> + Send + 'static,
7585 > {
7586 let Self { outgoing, incoming } = self;
7587
7588 let incoming_lines = Box::pin(lossy_lines(incoming));
7589 let outgoing_lines = transport_actor::LineWriter::new(outgoing);
7590
7591 Lines::new(outgoing_lines, incoming_lines)
7592 }
7593}
7594
7595/// Splits `reader` into lines, without their `\n` or `\r\n` endings.
7596///
7597/// Bytes that are not valid UTF-8 are replaced with U+FFFD. Reporting them as
7598/// a read error would end the connection over one message. A line that is
7599/// JSON after the replacement is delivered, for example one with such a byte
7600/// inside a string. Any other line is a [`TransportFrame::Malformed`].
7601pub(crate) fn lossy_lines<R>(
7602 reader: R,
7603) -> impl futures::Stream<Item = std::io::Result<String>> + Send + 'static
7604where
7605 R: AsyncRead + Send + 'static,
7606{
7607 use futures::AsyncBufReadExt as _;
7608
7609 let reader = Box::pin(futures::io::BufReader::new(reader));
7610 futures::stream::try_unfold(reader, async |mut reader| {
7611 let mut line = Vec::new();
7612 if reader.read_until(b'\n', &mut line).await? == 0 {
7613 return Ok::<_, std::io::Error>(None);
7614 }
7615 if line.ends_with(b"\n") {
7616 line.pop();
7617 if line.ends_with(b"\r") {
7618 line.pop();
7619 }
7620 }
7621 let line = String::from_utf8(line).unwrap_or_else(|error| {
7622 // The line's content may be private, so it is not logged.
7623 tracing::debug!("Replaced invalid UTF-8 in an incoming line");
7624 String::from_utf8_lossy(error.as_bytes()).into_owned()
7625 });
7626 Ok(Some((line, reader)))
7627 })
7628}
7629
7630#[cfg(any(
7631 all(
7632 any(feature = "process", feature = "stdio"),
7633 not(target_family = "wasm")
7634 ),
7635 test
7636))]
7637pub(crate) async fn write_line<W>(writer: &mut W, line: String) -> std::io::Result<()>
7638where
7639 W: AsyncWrite + Unpin + ?Sized,
7640{
7641 use futures::AsyncWriteExt as _;
7642
7643 let mut bytes = line.into_bytes();
7644 bytes.push(b'\n');
7645 writer.write_all(&bytes).await?;
7646 writer.flush().await
7647}
7648
7649impl<OB, IB, R: Role> ConnectTo<R> for ByteStreams<OB, IB>
7650where
7651 OB: AsyncWrite + Send + 'static,
7652 IB: AsyncRead + Send + 'static,
7653{
7654 async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7655 ConnectTo::<R>::connect_to(self.into_lines(), client).await
7656 }
7657
7658 fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7659 ConnectTo::<R>::into_channel_and_future(self.into_lines())
7660 }
7661}
7662
7663/// A channel endpoint representing one side of a bidirectional JSON-RPC transport.
7664///
7665/// A channel carries complete [`TransportFrame`] values across in-process components and
7666/// transport adapters. Malformed wire input is an
7667/// explicit frame; failures while driving a physical transport are returned by that
7668/// transport's future.
7669///
7670/// The unbounded [`futures::channel::mpsc`] pair is the intended contract:
7671/// frames are never dropped and sends never wait, so the transport or
7672/// component on each side applies its own backpressure. Build a channel from
7673/// an existing pair with [`Channel::new`] and take it apart with
7674/// [`Channel::into_parts`] or by destructuring with `..`.
7675///
7676/// # Example
7677///
7678/// ```no_run
7679/// # use agent_client_protocol::UntypedRole;
7680/// # use agent_client_protocol::Channel;
7681/// # async fn example() -> Result<(), agent_client_protocol::Error> {
7682/// let (channel_a, _channel_b) = Channel::duplex();
7683///
7684/// UntypedRole.builder()
7685/// .name("connection-a")
7686/// .connect_to(channel_a)
7687/// .await?;
7688/// # Ok(())
7689/// # }
7690/// ```
7691#[derive(Debug)]
7692#[non_exhaustive]
7693pub struct Channel {
7694 /// Receives frames from the counterpart.
7695 pub rx: mpsc::UnboundedReceiver<TransportFrame>,
7696 /// Sends frames to the counterpart.
7697 pub tx: mpsc::UnboundedSender<TransportFrame>,
7698}
7699
7700impl Channel {
7701 /// Create a channel endpoint that receives frames on `rx` and sends them
7702 /// on `tx`.
7703 #[must_use]
7704 pub fn new(
7705 rx: mpsc::UnboundedReceiver<TransportFrame>,
7706 tx: mpsc::UnboundedSender<TransportFrame>,
7707 ) -> Self {
7708 Self { rx, tx }
7709 }
7710
7711 /// Split this endpoint into its receiving and sending halves, `(rx, tx)`.
7712 #[must_use]
7713 pub fn into_parts(
7714 self,
7715 ) -> (
7716 mpsc::UnboundedReceiver<TransportFrame>,
7717 mpsc::UnboundedSender<TransportFrame>,
7718 ) {
7719 (self.rx, self.tx)
7720 }
7721
7722 /// Create a pair of connected channel endpoints.
7723 ///
7724 /// Frames sent through either endpoint are received by the other endpoint.
7725 #[must_use]
7726 pub fn duplex() -> (Self, Self) {
7727 let (a_tx, b_rx) = mpsc::unbounded();
7728 let (b_tx, a_rx) = mpsc::unbounded();
7729
7730 (Self { rx: a_rx, tx: a_tx }, Self { rx: b_rx, tx: b_tx })
7731 }
7732
7733 /// Copy frames from `rx` to `tx` until the input closes.
7734 ///
7735 /// # Errors
7736 ///
7737 /// Returns an error if the receiving endpoint closes before the input.
7738 pub(crate) async fn copy(mut self) -> Result<(), crate::Error> {
7739 while let Some(frame) = self.rx.next().await {
7740 self.tx
7741 .unbounded_send(frame)
7742 .map_err(crate::util::internal_error)?;
7743 }
7744 Ok(())
7745 }
7746
7747 /// Copy output concurrently with its owning driver, then drain accepted frames.
7748 /// Passive endpoints instead retain the channel's independent half-close lifetime.
7749 pub(crate) async fn copy_with_driver(
7750 self,
7751 driver: Option<crate::ConnectionDriver>,
7752 ) -> Result<(), crate::Error> {
7753 self.copy_with_driver_until(driver, future::pending()).await
7754 }
7755
7756 /// After the destination's owned foreground finishes, keep driving source
7757 /// errors and sink work, but never deliver queued or new input to it.
7758 pub(crate) async fn copy_with_driver_until(
7759 mut self,
7760 mut driver: Option<crate::ConnectionDriver>,
7761 stop_delivery: impl Future<Output = ()>,
7762 ) -> Result<(), crate::Error> {
7763 let mut stop_delivery = pin!(stop_delivery);
7764 let mut delivering = true;
7765 let mut done = false;
7766 loop {
7767 let event = future::poll_fn(|cx| {
7768 if delivering && stop_delivery.as_mut().poll(cx).is_ready() {
7769 delivering = false;
7770 }
7771 // Driver errors remain authoritative even when stop or EOF is ready.
7772 if !done
7773 && let Some(driver) = driver.as_mut()
7774 && let std::task::Poll::Ready(result) = std::pin::Pin::new(driver).poll(cx)
7775 {
7776 return std::task::Poll::Ready(Either::Left(result));
7777 }
7778 if !delivering && driver.is_none() {
7779 return std::task::Poll::Ready(Either::Right(None));
7780 }
7781 self.rx.poll_next_unpin(cx).map(Either::Right)
7782 })
7783 .await;
7784 let frame = match event {
7785 Either::Left(result) => {
7786 result?;
7787 done = true;
7788 self.rx.close();
7789 continue;
7790 }
7791 Either::Right(frame) => frame,
7792 };
7793 let Some(frame) = frame else {
7794 break;
7795 };
7796 if delivering {
7797 self.tx
7798 .unbounded_send(frame)
7799 .map_err(crate::util::internal_error)?;
7800 }
7801 }
7802 // Propagate this half-close before waiting for a still-running driver.
7803 drop(self);
7804 if !done && let Some(driver) = driver {
7805 driver.await?;
7806 }
7807 Ok(())
7808 }
7809
7810 /// Bridge two endpoints while inspecting every valid message.
7811 ///
7812 /// Observers are invoked in source order for each valid message. The
7813 /// original frame is forwarded unchanged after inspection.
7814 ///
7815 /// # Errors
7816 ///
7817 /// Returns an observer error or an error if a destination closes before its
7818 /// source.
7819 pub async fn bridge_with_inspection(
7820 left: Self,
7821 right: Self,
7822 mut left_to_right: impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error> + Send,
7823 mut right_to_left: impl FnMut(&RawJsonRpcMessage) -> Result<(), crate::Error> + Send,
7824 ) -> Result<(), crate::Error> {
7825 let Self {
7826 rx: mut left_rx,
7827 tx: left_tx,
7828 } = left;
7829 let Self {
7830 rx: mut right_rx,
7831 tx: right_tx,
7832 } = right;
7833
7834 let left_to_right = async move {
7835 while let Some(frame) = left_rx.next().await {
7836 frame.inspect_messages(&mut left_to_right)?;
7837 right_tx
7838 .unbounded_send(frame)
7839 .map_err(crate::util::internal_error)?;
7840 }
7841 Ok::<(), crate::Error>(())
7842 };
7843 let right_to_left = async move {
7844 while let Some(frame) = right_rx.next().await {
7845 frame.inspect_messages(&mut right_to_left)?;
7846 left_tx
7847 .unbounded_send(frame)
7848 .map_err(crate::util::internal_error)?;
7849 }
7850 Ok::<(), crate::Error>(())
7851 };
7852
7853 futures::try_join!(left_to_right, right_to_left)?;
7854 Ok(())
7855 }
7856}
7857
7858impl<R: Role> ConnectTo<R> for Channel {
7859 async fn connect_to(self, client: impl ConnectTo<R::Counterpart>) -> Result<(), crate::Error> {
7860 let (client_channel, client_future) = client.into_channel_and_future();
7861
7862 let passive = client_future.is_none();
7863 let outgoing = Box::pin(
7864 Channel {
7865 rx: client_channel.rx,
7866 tx: self.tx,
7867 }
7868 .copy_with_driver(client_future),
7869 );
7870 let incoming = Box::pin(
7871 Channel {
7872 rx: self.rx,
7873 tx: client_channel.tx,
7874 }
7875 .copy(),
7876 );
7877 if passive {
7878 futures::try_join!(outgoing, incoming)?;
7879 return Ok(());
7880 }
7881
7882 match future::select(outgoing, incoming).await {
7883 Either::Left((result, _)) => result,
7884 Either::Right((result, outgoing)) => {
7885 result?;
7886 outgoing.await
7887 }
7888 }
7889 }
7890
7891 fn into_channel_and_future(self) -> (Channel, Option<crate::ConnectionDriver>) {
7892 (self, None)
7893 }
7894}
7895
7896#[cfg(test)]
7897mod tests {
7898 use super::*;
7899 use crate::Client;
7900 #[cfg(feature = "unstable_protocol_v2")]
7901 use crate::Proxy;
7902
7903 #[test]
7904 fn raw_notification_round_trips_and_drops_unknown_envelope_members() {
7905 let message: RawJsonRpcMessage = serde_json::from_value(serde_json::json!({
7906 "jsonrpc": "2.0",
7907 "method": "_vendor/ping",
7908 "params": { "n": 1 },
7909 "extra": true,
7910 }))
7911 .unwrap();
7912 let mut params = serde_json::Map::new();
7913 params.insert("n".into(), 1.into());
7914 assert_eq!(
7915 message,
7916 RawJsonRpcMessage::Notification(RawJsonRpcNotification {
7917 method: "_vendor/ping".into(),
7918 params: Some(RawJsonRpcParams::Object(params)),
7919 })
7920 );
7921 assert_eq!(
7922 serde_json::to_value(&message).unwrap(),
7923 serde_json::json!({
7924 "jsonrpc": "2.0",
7925 "method": "_vendor/ping",
7926 "params": { "n": 1 },
7927 })
7928 );
7929
7930 let without_params =
7931 RawJsonRpcMessage::notification("ping".into(), serde_json::Value::Null).unwrap();
7932 assert_eq!(
7933 serde_json::to_value(&without_params).unwrap(),
7934 serde_json::json!({ "jsonrpc": "2.0", "method": "ping" })
7935 );
7936 }
7937
7938 #[test]
7939 fn protected_cleanup_keeps_scoped_runners_polled_on_every_shutdown_path() {
7940 #[derive(Clone, Copy, Debug)]
7941 enum Stop {
7942 ForegroundSuccess,
7943 ForegroundError,
7944 InputEof,
7945 TransportError,
7946 TaskError,
7947 RunnerError,
7948 SupervisorError,
7949 }
7950
7951 struct Dropped(Arc<AtomicBool>);
7952 impl Drop for Dropped {
7953 fn drop(&mut self) {
7954 self.0.store(true, Ordering::Release);
7955 }
7956 }
7957
7958 for stop in [
7959 Stop::ForegroundSuccess,
7960 Stop::ForegroundError,
7961 Stop::InputEof,
7962 Stop::TransportError,
7963 Stop::TaskError,
7964 Stop::RunnerError,
7965 Stop::SupervisorError,
7966 ] {
7967 let cleaned = Arc::new(AtomicBool::new(false));
7968 let disposable_dropped = Arc::new(AtomicBool::new(false));
7969 let close_finished = Arc::new(AtomicBool::new(false));
7970 let (cleanup_tx, cleanup_rx) = oneshot::channel::<()>();
7971 let (scoped_done_tx, scoped_done_rx) = completion_signal();
7972 let (stop_tx, stop_rx) = oneshot::channel::<()>();
7973 let stop_signal = stop_rx.map(|_| ()).boxed().shared();
7974 let (incoming_tx, incoming_rx) = mpsc::unbounded();
7975 let outgoing = futures::sink::unfold((), |(), _line: String| {
7976 future::ready(Ok::<_, std::io::Error>(()))
7977 });
7978 let builder = Client
7979 .v1()
7980 .with_spawned({
7981 let cleaned = cleaned.clone();
7982 async move |cx: crate::v1::ConnectionTo<Agent>| {
7983 cx.raw_connection().shutdown_requested().await;
7984 // This stands in for the actual scoped native operation:
7985 // its async cleanup only advances if this runner is polled.
7986 cleanup_rx.await.unwrap();
7987 cleaned.store(true, Ordering::Release);
7988 let _ = scoped_done_tx.send(());
7989 Ok(())
7990 }
7991 })
7992 .with_spawned({
7993 let stop_signal = stop_signal.clone();
7994 async move |_cx| {
7995 stop_signal.await;
7996 if matches!(stop, Stop::RunnerError) {
7997 Err(crate::Error::internal_error().data("runner failure"))
7998 } else {
7999 future::pending().await
8000 }
8001 }
8002 })
8003 .on_close({
8004 let close_finished = close_finished.clone();
8005 let scoped_done = scoped_done_rx.clone();
8006 async move |cx: crate::v1::ConnectionTo<Agent>| {
8007 // EOF cancellation must precede, not await, close callbacks.
8008 cx.raw_connection().shutdown_requested().await;
8009 assert!(!cx.is_incoming_closed());
8010 scoped_done.await;
8011 close_finished.store(true, Ordering::Release);
8012 Ok(())
8013 }
8014 });
8015 let (connection, driver) =
8016 builder.into_connection_and_future(Lines::new(outgoing, incoming_rx), false, {
8017 let stop_signal = stop_signal.clone();
8018 async move |cx| {
8019 if matches!(stop, Stop::InputEof) {
8020 cx.incoming_closed().await;
8021 return Ok(());
8022 }
8023 stop_signal.await;
8024 match stop {
8025 Stop::ForegroundSuccess | Stop::SupervisorError => Ok(()),
8026 Stop::ForegroundError => {
8027 Err(crate::Error::internal_error().data("foreground failure"))
8028 }
8029 _ => future::pending().await,
8030 }
8031 }
8032 });
8033 let disposable = Dropped(disposable_dropped.clone());
8034 connection
8035 .spawn(async move {
8036 let _disposable = disposable;
8037 future::pending().await
8038 })
8039 .unwrap();
8040 connection
8041 .spawn({
8042 let stop_signal = stop_signal.clone();
8043 async move {
8044 stop_signal.await;
8045 if matches!(stop, Stop::TaskError) {
8046 Err(crate::Error::internal_error().data("task failure"))
8047 } else {
8048 future::pending().await
8049 }
8050 }
8051 })
8052 .unwrap();
8053 connection
8054 .spawn_protected({
8055 let connection = connection.clone();
8056 async move {
8057 connection.shutdown_requested().await;
8058 scoped_done_rx.await;
8059 if matches!(stop, Stop::SupervisorError) {
8060 Err(crate::Error::internal_error().data("supervisor failure"))
8061 } else {
8062 Ok(())
8063 }
8064 }
8065 })
8066 .unwrap();
8067 let mut driver = Box::pin(driver);
8068 assert!(driver.as_mut().now_or_never().is_none(), "{stop:?}");
8069 assert!(connection.shutdown_requested().now_or_never().is_none());
8070 let _ = stop_tx.send(());
8071 let incoming_tx = match stop {
8072 Stop::InputEof => {
8073 drop(incoming_tx);
8074 None
8075 }
8076 Stop::TransportError => {
8077 incoming_tx
8078 .unbounded_send(Err(std::io::Error::other("transport failure")))
8079 .unwrap();
8080 Some(incoming_tx)
8081 }
8082 _ => Some(incoming_tx),
8083 };
8084 for _ in 0..10 {
8085 assert!(driver.as_mut().now_or_never().is_none(), "{stop:?}");
8086 if connection.shutdown_requested().now_or_never().is_some() {
8087 break;
8088 }
8089 }
8090 assert!(
8091 connection.shutdown_requested().now_or_never().is_some(),
8092 "{stop:?}"
8093 );
8094 assert!(!cleaned.load(Ordering::Acquire), "{stop:?}");
8095 assert!(!disposable_dropped.load(Ordering::Acquire), "{stop:?}");
8096 cleanup_tx.send(()).unwrap();
8097 // Task acknowledgments may wake an actor already polled in this turn.
8098 // Bound the probe so a broken scoped-runner join fails, not hangs.
8099 let mut result = None;
8100 for _ in 0..10 {
8101 result = driver.as_mut().now_or_never();
8102 if result.is_some() {
8103 break;
8104 }
8105 }
8106 let result =
8107 result.unwrap_or_else(|| panic!("driver did not finish owned cleanup: {stop:?}"));
8108 match stop {
8109 Stop::ForegroundSuccess | Stop::InputEof => result.unwrap(),
8110 _ => {
8111 let error = result.expect_err("shutdown must preserve the first error");
8112 let expected = match stop {
8113 Stop::ForegroundError => "foreground failure",
8114 Stop::TransportError => "transport failure",
8115 Stop::TaskError => "task failure",
8116 Stop::RunnerError => "runner failure",
8117 Stop::SupervisorError => "supervisor failure",
8118 _ => unreachable!(),
8119 };
8120 assert!(
8121 error.data.unwrap().to_string().contains(expected),
8122 "{stop:?}"
8123 );
8124 }
8125 }
8126 assert!(cleaned.load(Ordering::Acquire), "{stop:?}");
8127 assert!(disposable_dropped.load(Ordering::Acquire), "{stop:?}");
8128 assert_eq!(
8129 close_finished.load(Ordering::Acquire),
8130 matches!(stop, Stop::InputEof),
8131 "{stop:?}",
8132 );
8133 assert!(connection.spawn_protected(async { Ok(()) }).is_err());
8134 drop(incoming_tx);
8135 }
8136 }
8137
8138 #[test]
8139 fn protected_operation_acknowledgments_are_reaped_and_join_seals_registration() {
8140 let (connection, _message_rx, _pending_replies) = connection_for_response_hook_tests();
8141 // The helper drops its task receiver, so use a live receiver for this probe.
8142 let (task_tx, mut task_rx) = mpsc::unbounded();
8143 let connection = ConnectionTo {
8144 task_tx,
8145 ..connection
8146 };
8147 for _ in 0..100 {
8148 connection.spawn_protected(async { Ok(()) }).unwrap();
8149 assert_eq!(
8150 connection
8151 .protected_operations
8152 .lock()
8153 .unwrap()
8154 .pending
8155 .len(),
8156 1
8157 );
8158 let task = task_rx.next().now_or_never().unwrap().unwrap();
8159 futures::executor::block_on(task.run_for_test()).unwrap();
8160 }
8161 assert!(
8162 connection
8163 .wait_protected_operations()
8164 .now_or_never()
8165 .is_some()
8166 );
8167 assert!(
8168 connection
8169 .wait_protected_operations()
8170 .now_or_never()
8171 .is_some()
8172 );
8173 assert!(
8174 connection
8175 .protected_operations
8176 .lock()
8177 .unwrap()
8178 .pending
8179 .is_empty()
8180 );
8181 assert!(connection.spawn_protected(async { Ok(()) }).is_err());
8182 assert!(task_rx.next().now_or_never().is_none());
8183 }
8184
8185 #[test]
8186 fn dropping_unused_finish_signal_preserves_physical_half_closes() {
8187 let outgoing = futures::sink::unfold((), |(), _line: String| {
8188 future::ready(Ok::<_, std::io::Error>(()))
8189 });
8190 let (incoming_tx, incoming_rx) = mpsc::unbounded();
8191 let (Channel { mut rx, tx }, mut driver) =
8192 Lines::new(outgoing, incoming_rx).into_channel_transport();
8193
8194 drop(
8195 driver
8196 .take_finish()
8197 .expect("built-in Lines driver is finishable"),
8198 );
8199 drop(tx);
8200 assert!((&mut driver).now_or_never().is_none());
8201 incoming_tx
8202 .unbounded_send(Ok(
8203 r#"{"jsonrpc":"2.0","method":"test/after-output-eof"}"#.into()
8204 ))
8205 .unwrap();
8206 assert!((&mut driver).now_or_never().is_none());
8207 assert!(rx.next().now_or_never().unwrap().is_some());
8208
8209 drop(incoming_tx);
8210 futures::executor::block_on(driver).unwrap();
8211 assert!(rx.next().now_or_never().unwrap().is_none());
8212 }
8213
8214 #[test]
8215 fn explicit_physical_finish_does_not_hide_a_ready_read_error() {
8216 let outgoing = futures::sink::unfold((), |(), _line: String| {
8217 future::ready(Ok::<_, std::io::Error>(()))
8218 });
8219 let incoming = futures::stream::iter([Err(std::io::Error::other("finish read failed"))]);
8220 let (_channel, mut driver) = Lines::new(outgoing, incoming).into_channel_transport();
8221 assert!(driver.request_finish());
8222
8223 let error = futures::executor::block_on(driver).unwrap_err();
8224 assert_eq!(
8225 error
8226 .data
8227 .and_then(|value| value.as_str().map(str::to_owned)),
8228 Some("finish read failed".into())
8229 );
8230 }
8231
8232 #[cfg(feature = "unstable_protocol_v2")]
8233 fn connection_with_task_receiver() -> (
8234 ConnectionTo<crate::role::UntypedRole>,
8235 mpsc::UnboundedReceiver<Task>,
8236 ) {
8237 let (message_tx, _message_rx) = mpsc::unbounded();
8238 let (task_tx, task_rx) = mpsc::unbounded();
8239 let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8240 let transport_completion: SharedTransportCompletion =
8241 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8242 let pending_replies = PendingReplies::default();
8243
8244 (
8245 ConnectionTo::new(
8246 crate::role::UntypedRole,
8247 message_tx,
8248 task_tx,
8249 dynamic_handler_tx,
8250 transport_completion,
8251 pending_replies.registrar(),
8252 ProtocolMode::disabled(),
8253 ),
8254 task_rx,
8255 )
8256 }
8257
8258 #[cfg(feature = "unstable_protocol_v2")]
8259 #[test]
8260 fn v2_builder_exposes_typed_context_to_user_callbacks() {
8261 fn assert_v2_context(_connection: &crate::v2::ConnectionTo<Agent>) {}
8262
8263 let _builder = Client
8264 .v2()
8265 .on_receive_request(
8266 async |_request: UntypedMessage, _responder, connection| {
8267 assert_v2_context(&connection);
8268 Ok(())
8269 },
8270 crate::on_receive_request!(),
8271 )
8272 .on_receive_notification(
8273 async |_notification: UntypedMessage, connection| {
8274 assert_v2_context(&connection);
8275 Ok(())
8276 },
8277 crate::on_receive_notification!(),
8278 )
8279 .on_receive_dispatch(
8280 async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8281 assert_v2_context(&connection);
8282 Ok(())
8283 },
8284 crate::on_receive_dispatch!(),
8285 )
8286 .on_receive_request_from(
8287 Agent,
8288 async |_request: UntypedMessage, _responder, connection| {
8289 assert_v2_context(&connection);
8290 Ok(())
8291 },
8292 crate::on_receive_request!(),
8293 )
8294 .on_receive_notification_from(
8295 Agent,
8296 async |_notification: UntypedMessage, connection| {
8297 assert_v2_context(&connection);
8298 Ok(())
8299 },
8300 crate::on_receive_notification!(),
8301 )
8302 .on_receive_dispatch_from(
8303 Agent,
8304 async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8305 assert_v2_context(&connection);
8306 Ok(())
8307 },
8308 crate::on_receive_dispatch!(),
8309 )
8310 .with_spawned(async |connection| {
8311 assert_v2_context(&connection);
8312 Ok(())
8313 })
8314 .on_close(async |connection| {
8315 assert_v2_context(&connection);
8316 Ok(())
8317 });
8318 }
8319
8320 #[cfg(feature = "unstable_protocol_v2")]
8321 #[test]
8322 fn proxy_builders_negotiate_proxy_initialize_like_agents() -> Result<(), crate::Error> {
8323 use crate::schema::ProtocolVersion;
8324
8325 // A v1 proxy selects v1 for a newer request.
8326 let mode = Proxy.v1().protocol_mode;
8327 assert_eq!(mode.api_protocol_version(), Some(ProtocolVersion::V1));
8328 let request = ProtocolCompat::new(mode).incoming_message(UntypedMessage::new(
8329 "proxy/initialize",
8330 serde_json::json!({ "protocolVersion": ProtocolVersion::V2 }),
8331 )?)?;
8332 assert_eq!(request.params()["protocolVersion"], serde_json::json!(1));
8333
8334 // A v2 proxy supports no version at or below v1.
8335 let mode = Proxy.v2().protocol_mode;
8336 assert_eq!(mode.api_protocol_version(), Some(ProtocolVersion::V2));
8337 let error = ProtocolCompat::new(mode)
8338 .incoming_message(UntypedMessage::new(
8339 "proxy/initialize",
8340 serde_json::json!({ "protocolVersion": ProtocolVersion::V1 }),
8341 )?)
8342 .expect_err("a v2 proxy builder must reject v1");
8343 assert_eq!(i32::from(error.code), -32022);
8344
8345 Ok(())
8346 }
8347
8348 #[cfg(feature = "unstable_protocol_v2")]
8349 #[test]
8350 fn v2_proxy_rejects_explicitly_prewrapped_initialize_request() {
8351 let (message_tx, message_rx) = mpsc::unbounded();
8352 let (task_tx, _task_rx) = mpsc::unbounded();
8353 let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8354 let transport_completion: SharedTransportCompletion =
8355 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8356 let pending_replies = PendingReplies::default();
8357 let connection = ConnectionTo::new(
8358 crate::Conductor,
8359 message_tx,
8360 task_tx,
8361 dynamic_handler_tx,
8362 transport_completion,
8363 pending_replies.registrar(),
8364 ProtocolMode::v2_proxy(),
8365 );
8366
8367 let request = crate::schema::SuccessorMessage::new(
8368 UntypedMessage::new(
8369 "initialize",
8370 serde_json::json!({ "protocolVersion": crate::schema::ProtocolVersion::V1 }),
8371 )
8372 .expect("test initialize request should serialize"),
8373 );
8374 let sent = connection.send_request_to(Agent, request);
8375
8376 let (transport_tx, mut transport_rx) = mpsc::unbounded();
8377 let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8378 message_rx,
8379 pending_replies,
8380 transport_tx,
8381 ProtocolCompat::new(ProtocolMode::v2_proxy()),
8382 future::pending::<()>().boxed().shared(),
8383 ));
8384 assert!(
8385 actor.as_mut().now_or_never().is_none(),
8386 "the outgoing actor should continue after rejecting the request"
8387 );
8388 assert!(
8389 transport_rx.next().now_or_never().is_none(),
8390 "an explicitly prewrapped initialize must not reach the transport"
8391 );
8392
8393 let error = futures::executor::block_on(sent.block_task())
8394 .expect_err("connection routing must own successor wrapping");
8395 let data = error
8396 .data
8397 .as_ref()
8398 .and_then(|data| data.as_str())
8399 .unwrap_or_default();
8400 assert!(data.contains("logical `initialize`"), "{error:?}");
8401 assert!(data.contains("proxy/successor"), "{error:?}");
8402 }
8403
8404 #[cfg(feature = "unstable_protocol_v2")]
8405 #[test]
8406 fn v2_proxy_builder_exposes_typed_context_to_user_callbacks() {
8407 fn assert_v2_context(_connection: &crate::v2::ConnectionTo<crate::Conductor>) {}
8408
8409 let _builder = Proxy
8410 .v2()
8411 .on_receive_request_from(
8412 Client,
8413 async |_request: UntypedMessage, _responder, connection| {
8414 assert_v2_context(&connection);
8415 Ok(())
8416 },
8417 crate::on_receive_request!(),
8418 )
8419 .on_receive_notification_from(
8420 Agent,
8421 async |_notification: UntypedMessage, connection| {
8422 assert_v2_context(&connection);
8423 Ok(())
8424 },
8425 crate::on_receive_notification!(),
8426 )
8427 .on_receive_dispatch_from(
8428 Client,
8429 async |_dispatch: Dispatch<UntypedMessage, UntypedMessage, V2>, connection| {
8430 assert_v2_context(&connection);
8431 Ok(())
8432 },
8433 crate::on_receive_dispatch!(),
8434 )
8435 .with_spawned(async |connection| {
8436 assert_v2_context(&connection);
8437 Ok(())
8438 })
8439 .on_close(async |connection| {
8440 assert_v2_context(&connection);
8441 Ok(())
8442 });
8443 }
8444
8445 #[cfg(feature = "unstable_protocol_v2")]
8446 #[test]
8447 fn raw_connection_spawns_v2_builder_with_typed_child_callback() {
8448 let (parent, mut task_rx) = connection_with_task_receiver();
8449 let (transport, _peer) = Channel::duplex();
8450 let (callback_tx, callback_rx) = oneshot::channel();
8451
8452 let child: crate::v2::ConnectionTo<Agent> = parent
8453 .spawn_connection(
8454 Client.v2().with_spawned(
8455 async move |_connection: crate::v2::ConnectionTo<Agent>| {
8456 callback_tx.send(()).map_err(|()| {
8457 crate::util::internal_error("typed child callback receiver was dropped")
8458 })
8459 },
8460 ),
8461 transport,
8462 )
8463 .expect("v2 child connection should be spawned");
8464
8465 let task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
8466 .expect("child connection task should already be queued")
8467 .expect("parent task queue should remain open");
8468 futures::executor::block_on(async {
8469 match future::select(Box::pin(task.run_for_test()), Box::pin(callback_rx)).await {
8470 Either::Right((Ok(()), child_task)) => drop(child_task),
8471 Either::Right((Err(error), _)) => {
8472 panic!("typed child callback sender was dropped: {error}")
8473 }
8474 Either::Left((result, _)) => {
8475 panic!("child connection stopped before its typed callback ran: {result:?}")
8476 }
8477 }
8478 });
8479
8480 drop(child);
8481 }
8482
8483 #[cfg(feature = "unstable_protocol_v2")]
8484 #[test]
8485 fn raw_connection_returns_raw_context_for_raw_builder() {
8486 let (parent, mut task_rx) = connection_with_task_receiver();
8487 let (transport, _peer) = Channel::duplex();
8488
8489 let child: ConnectionTo<Agent> = parent
8490 .spawn_connection(Builder::new(Client), transport)
8491 .expect("raw child connection should be spawned");
8492 assert_eq!(child.protocol_version(), None);
8493
8494 let child_task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
8495 .expect("child connection task should already be queued")
8496 .expect("parent task queue should remain open");
8497
8498 drop((child, child_task));
8499 }
8500
8501 fn connection_with_dynamic_handler_receiver() -> (
8502 ConnectionTo<crate::role::UntypedRole>,
8503 mpsc::UnboundedReceiver<DynamicHandlerMessage<crate::role::UntypedRole>>,
8504 ) {
8505 let (message_tx, _message_rx) = mpsc::unbounded();
8506 let (task_tx, _task_rx) = mpsc::unbounded();
8507 let (dynamic_handler_tx, dynamic_handler_rx) = mpsc::unbounded();
8508 let transport_completion: SharedTransportCompletion =
8509 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8510 let pending_replies = PendingReplies::default();
8511
8512 (
8513 ConnectionTo::new(
8514 crate::role::UntypedRole,
8515 message_tx,
8516 task_tx,
8517 dynamic_handler_tx,
8518 transport_completion,
8519 pending_replies.registrar(),
8520 ProtocolMode::disabled(),
8521 ),
8522 dynamic_handler_rx,
8523 )
8524 }
8525
8526 struct ClaimingDynamicHandler;
8527
8528 impl HandleDispatchFrom<crate::role::UntypedRole> for ClaimingDynamicHandler {
8529 fn handle_dispatch_from(
8530 &mut self,
8531 _message: Dispatch,
8532 _connection: ConnectionTo<crate::role::UntypedRole>,
8533 ) -> impl Future<Output = Result<Handled<Dispatch>, crate::Error>> + Send {
8534 future::ready(Ok(Handled::Yes))
8535 }
8536
8537 fn describe_chain(&self) -> impl Debug {
8538 "ClaimingDynamicHandler"
8539 }
8540 }
8541
8542 fn connection_for_response_hook_tests() -> (
8543 ConnectionTo<crate::role::UntypedRole>,
8544 mpsc::UnboundedReceiver<OutgoingMessage>,
8545 PendingReplies,
8546 ) {
8547 let (message_tx, message_rx) = mpsc::unbounded();
8548 let (task_tx, _task_rx) = mpsc::unbounded();
8549 let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8550 let transport_completion: SharedTransportCompletion =
8551 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8552 let pending_replies = PendingReplies::default();
8553
8554 (
8555 ConnectionTo::new(
8556 crate::role::UntypedRole,
8557 message_tx,
8558 task_tx,
8559 dynamic_handler_tx,
8560 transport_completion,
8561 pending_replies.registrar(),
8562 ProtocolMode::disabled(),
8563 ),
8564 message_rx,
8565 pending_replies,
8566 )
8567 }
8568
8569 #[cfg(feature = "unstable_protocol_v2")]
8570 fn route_test_response(
8571 request_id: RawJsonRpcId,
8572 pending_replies: &PendingReplies,
8573 result: Result<serde_json::Value, crate::Error>,
8574 ) {
8575 let pending_reply = pending_replies
8576 .remove(&request_id)
8577 .expect("the request should have a pending reply");
8578 let (dispatch, _) = incoming_actor::dispatch_from_response(pending_reply, result);
8579 let Dispatch::Response(result, router) = dispatch else {
8580 panic!("expected a response dispatch");
8581 };
8582 router
8583 .route_with_result(result)
8584 .expect("response should route to the pending request");
8585 }
8586
8587 #[cfg(feature = "unstable_protocol_v2")]
8588 #[test]
8589 fn handle_ids_are_typed_by_protocol_and_match_the_wire_id() {
8590 let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8591 let raw_sent = connection.send_request_to(
8592 crate::role::UntypedRole,
8593 UntypedMessage::new("probe", serde_json::json!({}))
8594 .expect("test request should serialize"),
8595 );
8596 let raw_sent_id: &RawJsonRpcId = raw_sent.id();
8597 assert_eq!(raw_sent_id, raw_sent.raw_id());
8598 raw_sent.detach();
8599
8600 let v2_connection = crate::v2::ConnectionTo { inner: connection };
8601 let sent = v2_connection.send_request_to(
8602 crate::role::UntypedRole,
8603 UntypedMessage::new("probe", serde_json::json!({}))
8604 .expect("test request should serialize"),
8605 );
8606 let v2_id: crate::v2::schema::RequestId = sent.id().clone();
8607 let raw_id = sent.raw_id().clone();
8608 assert_eq!(
8609 serde_json::to_value(&v2_id).expect("v2 id should serialize"),
8610 serde_json::to_value(&raw_id).expect("raw id should serialize"),
8611 );
8612
8613 let pending_reply = pending_replies
8614 .remove(&raw_id)
8615 .expect("the request should have a pending reply");
8616 let (dispatch, _) =
8617 incoming_actor::dispatch_from_response(pending_reply, Ok(serde_json::json!({})));
8618 assert_eq!(dispatch.raw_id(), Some(&raw_id));
8619 let dispatch = dispatch
8620 .into_protocol::<V2>()
8621 .expect("SDK-assigned ids are valid v2 ids");
8622 assert_eq!(dispatch.id(), Some(&v2_id));
8623 let Dispatch::Response(_, router) = dispatch else {
8624 panic!("expected a response dispatch");
8625 };
8626 assert_eq!(router.id(), &v2_id);
8627 assert_eq!(router.raw_id(), &raw_id);
8628 sent.detach();
8629 }
8630
8631 #[cfg(feature = "unstable_protocol_v2")]
8632 #[test]
8633 fn response_hook_runs_when_success_is_routed_before_consumption() {
8634 let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8635 let hook_ran = Arc::new(AtomicBool::new(false));
8636 let sent = connection
8637 .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8638 crate::role::UntypedRole,
8639 UntypedMessage::new("hooked", serde_json::json!({}))
8640 .expect("test request should serialize"),
8641 future::ready(Ok(())),
8642 {
8643 let hook_ran = hook_ran.clone();
8644 move |response| {
8645 assert_eq!(response, &serde_json::json!({"ok": true}));
8646 hook_ran.store(true, Ordering::Release);
8647 Ok(())
8648 }
8649 },
8650 )
8651 .into_sent_request(false);
8652 let request_id = sent.raw_id().clone();
8653
8654 route_test_response(
8655 request_id,
8656 &pending_replies,
8657 Ok(serde_json::json!({"ok": true})),
8658 );
8659
8660 assert!(hook_ran.load(Ordering::Acquire));
8661 assert_eq!(
8662 futures::executor::block_on(sent.block_task())
8663 .expect("routed response should remain consumable"),
8664 serde_json::json!({"ok": true})
8665 );
8666 }
8667
8668 #[cfg(feature = "unstable_protocol_v2")]
8669 #[test]
8670 fn response_hook_skips_errors_but_outlives_a_dropped_consumer() {
8671 let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8672 let peer_error_hook_ran = Arc::new(AtomicBool::new(false));
8673 let peer_error = connection
8674 .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8675 crate::role::UntypedRole,
8676 UntypedMessage::new("peer-error", serde_json::json!({}))
8677 .expect("test request should serialize"),
8678 future::ready(Ok(())),
8679 {
8680 let hook_ran = peer_error_hook_ran.clone();
8681 move |_| {
8682 hook_ran.store(true, Ordering::Release);
8683 Ok(())
8684 }
8685 },
8686 )
8687 .into_sent_request(false);
8688 let peer_error_id = peer_error.raw_id().clone();
8689 route_test_response(
8690 peer_error_id,
8691 &pending_replies,
8692 Err(crate::Error::invalid_request()),
8693 );
8694 assert!(
8695 futures::executor::block_on(peer_error.block_task()).is_err(),
8696 "the peer error should reach the consumer"
8697 );
8698 assert!(!peer_error_hook_ran.load(Ordering::Acquire));
8699
8700 let dropped_hook_ran = Arc::new(AtomicBool::new(false));
8701 let dropped = connection
8702 .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8703 crate::role::UntypedRole,
8704 UntypedMessage::new("dropped", serde_json::json!({}))
8705 .expect("test request should serialize"),
8706 future::ready(Ok(())),
8707 {
8708 let hook_ran = dropped_hook_ran.clone();
8709 move |_| {
8710 hook_ran.store(true, Ordering::Release);
8711 Ok(())
8712 }
8713 },
8714 )
8715 .into_sent_request(false);
8716 let dropped_id = dropped.raw_id().clone();
8717 drop(dropped);
8718 route_test_response(
8719 dropped_id,
8720 &pending_replies,
8721 Ok(serde_json::json!({"ok": true})),
8722 );
8723 assert!(dropped_hook_ran.load(Ordering::Acquire));
8724 }
8725
8726 #[cfg(feature = "unstable_protocol_v2")]
8727 #[test]
8728 fn response_hook_failure_replaces_the_success_result() {
8729 let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8730 let sent = connection
8731 .prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8732 crate::role::UntypedRole,
8733 UntypedMessage::new("hook-failure", serde_json::json!({}))
8734 .expect("test request should serialize"),
8735 future::ready(Ok(())),
8736 |_| Err(crate::Error::internal_error().data("response hook failed")),
8737 )
8738 .into_sent_request(false);
8739 let request_id = sent.raw_id().clone();
8740 route_test_response(
8741 request_id,
8742 &pending_replies,
8743 Ok(serde_json::json!({"ok": true})),
8744 );
8745
8746 let error = futures::executor::block_on(sent.block_task())
8747 .expect_err("the hook failure should replace the successful response");
8748 assert_eq!(error.code, crate::ErrorCode::INTERNAL_ERROR);
8749 assert_eq!(error.data, Some(serde_json::json!("response hook failed")));
8750 }
8751
8752 #[test]
8753 fn ordered_request_waits_for_readiness_before_publication() {
8754 let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8755 let (ready_tx, ready_rx) = oneshot::channel();
8756 let sent = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8757 crate::role::UntypedRole,
8758 UntypedMessage::new("after-ready", serde_json::json!({}))
8759 .expect("test request should serialize"),
8760 async move { ready_rx.await.map_err(crate::Error::into_internal_error) },
8761 );
8762
8763 let (transport_tx, mut transport_rx) = mpsc::unbounded();
8764 let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8765 message_rx,
8766 pending_replies,
8767 transport_tx,
8768 ProtocolCompat::new(ProtocolMode::disabled()),
8769 future::pending::<()>().boxed().shared(),
8770 ));
8771
8772 assert!(
8773 actor.as_mut().now_or_never().is_none(),
8774 "the outgoing actor should wait for readiness"
8775 );
8776 assert!(
8777 transport_rx.next().now_or_never().is_none(),
8778 "the request must not be published before readiness"
8779 );
8780
8781 ready_tx
8782 .send(())
8783 .expect("the readiness receiver should remain active");
8784 assert!(
8785 actor.as_mut().now_or_never().is_none(),
8786 "the outgoing actor should continue serving after publication"
8787 );
8788 let frame = transport_rx
8789 .next()
8790 .now_or_never()
8791 .expect("the ready request should be published")
8792 .expect("the transport queue should remain open");
8793 assert!(matches!(
8794 frame,
8795 TransportFrame::Single(RawJsonRpcMessage::Request(_))
8796 ));
8797
8798 drop(sent);
8799 }
8800
8801 #[test]
8802 fn foreground_finish_settles_unready_requests_and_preserves_ready_output_fifo() {
8803 let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8804 let unready = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8805 crate::role::UntypedRole,
8806 UntypedMessage::new("unready", serde_json::json!({})).unwrap(),
8807 future::pending(),
8808 );
8809 let unready_id = unready.raw_id().clone();
8810 send_raw_message(
8811 &connection.message_tx,
8812 OutgoingMessage::Notification {
8813 untyped: UntypedMessage::new("first", serde_json::json!({})).unwrap(),
8814 },
8815 )
8816 .unwrap();
8817 let ready = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8818 crate::role::UntypedRole,
8819 UntypedMessage::new("ready", serde_json::json!({})).unwrap(),
8820 future::ready(Ok(())),
8821 );
8822 let unready_after = connection.send_ordered_request_to_after::<Raw, _, _, _>(
8823 crate::role::UntypedRole,
8824 UntypedMessage::new("unready-after", serde_json::json!({})).unwrap(),
8825 future::pending(),
8826 );
8827 let unready_after_id = unready_after.raw_id().clone();
8828 send_raw_message(
8829 &connection.message_tx,
8830 OutgoingMessage::Notification {
8831 untyped: UntypedMessage::new("last", serde_json::json!({})).unwrap(),
8832 },
8833 )
8834 .unwrap();
8835 let (done_tx, done_rx) = oneshot::channel();
8836 send_raw_message(
8837 &connection.message_tx,
8838 OutgoingMessage::CloseAfterDraining { done: done_tx },
8839 )
8840 .unwrap();
8841 let (transport_tx, transport_rx) = mpsc::unbounded();
8842 futures::executor::block_on(outgoing_actor::outgoing_protocol_actor(
8843 message_rx,
8844 pending_replies.clone(),
8845 transport_tx,
8846 ProtocolCompat::new(ProtocolMode::disabled()),
8847 future::ready(()).boxed().shared(),
8848 ))
8849 .unwrap();
8850 futures::executor::block_on(done_rx).unwrap();
8851 let error = futures::executor::block_on(unready.block_task())
8852 .expect_err("an unresolved gate must explicitly fail its consumer");
8853 assert!(
8854 error
8855 .data
8856 .unwrap()
8857 .to_string()
8858 .contains("foreground completed before outgoing request readiness")
8859 );
8860 assert!(!pending_replies.contains(&unready_id));
8861 let error = futures::executor::block_on(unready_after.block_task())
8862 .expect_err("each unresolved gate must fail without repolling a consumed signal");
8863 assert!(
8864 error
8865 .data
8866 .unwrap()
8867 .to_string()
8868 .contains("foreground completed before outgoing request readiness")
8869 );
8870 assert!(!pending_replies.contains(&unready_after_id));
8871 assert!(pending_replies.contains(ready.raw_id()));
8872 let frames = futures::executor::block_on(transport_rx.collect::<Vec<_>>());
8873 let methods = frames
8874 .into_iter()
8875 .map(|frame| match frame {
8876 TransportFrame::Single(RawJsonRpcMessage::Notification(message)) => {
8877 message.method.to_string()
8878 }
8879 TransportFrame::Single(RawJsonRpcMessage::Request(message)) => {
8880 message.method.to_string()
8881 }
8882 _ => panic!("expected ready request/notification output"),
8883 })
8884 .collect::<Vec<_>>();
8885 assert_eq!(methods, ["first", "ready", "last"]);
8886 }
8887
8888 #[test]
8889 fn ordered_blocking_transform_precedes_response_acknowledgment() {
8890 let (connection, _message_rx, pending_replies) = connection_for_response_hook_tests();
8891 let sent = connection.send_ordered_request_to::<Raw, _, _>(
8892 crate::role::UntypedRole,
8893 UntypedMessage::new("ordered-transform", serde_json::json!({}))
8894 .expect("test request should serialize"),
8895 );
8896 let request_id = sent.raw_id().clone();
8897 let pending_reply = pending_replies
8898 .remove(&request_id)
8899 .expect("the request should have a pending reply");
8900 let (dispatch, response_dispatch) = incoming_actor::dispatch_from_response(
8901 pending_reply,
8902 Err(crate::Error::invalid_params()),
8903 );
8904 let Dispatch::Response(result, router) = dispatch else {
8905 panic!("expected a response dispatch");
8906 };
8907 router
8908 .route_with_result(result)
8909 .expect("response should route to the pending request");
8910 let acknowledgment = response_dispatch
8911 .complete()
8912 .expect("an ordered response should wait for acknowledgment");
8913 let acknowledgment = Arc::new(Mutex::new(Some(acknowledgment)));
8914 let acknowledgment_probe = acknowledgment.clone();
8915
8916 let error =
8917 futures::executor::block_on(sent.block_task_with_ordered_result(move |result| {
8918 assert_eq!(
8919 acknowledgment_probe
8920 .lock()
8921 .expect("acknowledgment mutex poisoned")
8922 .as_mut()
8923 .expect("acknowledgment receiver should remain available")
8924 .try_recv()
8925 .expect("acknowledgment sender should remain open"),
8926 None,
8927 "the ordered response was acknowledged before its transform"
8928 );
8929 result
8930 }))
8931 .expect_err("the peer error should survive the ordered transform");
8932 assert_eq!(error.code, crate::ErrorCode::INVALID_PARAMS);
8933
8934 let acknowledgment = acknowledgment
8935 .lock()
8936 .expect("acknowledgment mutex poisoned")
8937 .take()
8938 .expect("acknowledgment receiver should remain available");
8939 futures::executor::block_on(acknowledgment)
8940 .expect("the transform should release the ordered response");
8941 }
8942
8943 #[cfg(feature = "unstable_protocol_v2")]
8944 #[test]
8945 fn outgoing_request_readiness_failure_rejects_without_publication() {
8946 let (connection, message_rx, pending_replies) = connection_for_response_hook_tests();
8947 let hook_ran = Arc::new(AtomicBool::new(false));
8948 let sent = connection.prepare_request_to_with_response_hook_after::<Raw, _, _, _>(
8949 crate::role::UntypedRole,
8950 UntypedMessage::new("never-published", serde_json::json!({}))
8951 .expect("test request should serialize"),
8952 future::ready(Err(crate::Error::internal_error().data("readiness failed"))),
8953 {
8954 let hook_ran = hook_ran.clone();
8955 move |_| {
8956 hook_ran.store(true, Ordering::Release);
8957 Ok(())
8958 }
8959 },
8960 );
8961 let sent = sent.into_sent_request(false);
8962
8963 let (transport_tx, mut transport_rx) = mpsc::unbounded();
8964 let mut actor = Box::pin(outgoing_actor::outgoing_protocol_actor(
8965 message_rx,
8966 pending_replies,
8967 transport_tx,
8968 ProtocolCompat::new(ProtocolMode::disabled()),
8969 future::pending::<()>().boxed().shared(),
8970 ));
8971
8972 assert!(
8973 actor.as_mut().now_or_never().is_none(),
8974 "the outgoing actor should continue serving after rejecting the request"
8975 );
8976 assert!(
8977 transport_rx.next().now_or_never().is_none(),
8978 "a request whose readiness failed must not be published"
8979 );
8980 let error = futures::executor::block_on(sent.block_task())
8981 .expect_err("the readiness error should reach the request consumer");
8982 assert_eq!(error.code, crate::ErrorCode::INTERNAL_ERROR);
8983 assert_eq!(error.data, Some(serde_json::json!("readiness failed")));
8984 assert!(!hook_ran.load(Ordering::Acquire));
8985 }
8986
8987 #[test]
8988 fn ordered_request_is_marked_before_entering_outgoing_queue() {
8989 let (message_tx, mut message_rx) = mpsc::unbounded();
8990 let (task_tx, mut task_rx) = mpsc::unbounded();
8991 let (dynamic_handler_tx, _dynamic_handler_rx) = mpsc::unbounded();
8992 let transport_completion: SharedTransportCompletion =
8993 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
8994 let pending_replies = PendingReplies::default();
8995 let connection = ConnectionTo::new(
8996 crate::role::UntypedRole,
8997 message_tx,
8998 task_tx,
8999 dynamic_handler_tx,
9000 transport_completion,
9001 pending_replies.registrar(),
9002 ProtocolMode::disabled(),
9003 );
9004
9005 let sent = connection.send_ordered_request_to::<Raw, _, _>(
9006 crate::role::UntypedRole,
9007 UntypedMessage::new("ordered", serde_json::json!({}))
9008 .expect("test request should serialize"),
9009 );
9010 let request_id = sent.raw_id().clone();
9011 let message = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut message_rx))
9012 .expect("outgoing request should already be queued")
9013 .expect("outgoing request queue should remain open");
9014 let OutgoingMessage::Request { id, .. } = message else {
9015 panic!("expected an outgoing request");
9016 };
9017 assert_eq!(id, request_id);
9018
9019 let pending_reply = pending_replies
9020 .remove(&request_id)
9021 .expect("the request should have a pending reply");
9022 assert!(
9023 pending_reply.ordering.is_ordered(),
9024 "the response ordering barrier must be installed before publication"
9025 );
9026
9027 // Route the response before the callback is registered. The pre-set
9028 // ordering marker must hold dispatch until the callback task is
9029 // subsequently installed and completes.
9030 let (dispatch, response_dispatch) = incoming_actor::dispatch_from_response(
9031 pending_reply,
9032 Ok(serde_json::json!({"ok": true})),
9033 );
9034 let Dispatch::Response(result, router) = dispatch else {
9035 panic!("expected a response dispatch");
9036 };
9037 router
9038 .route_with_result(result)
9039 .expect("response should route to the pending request");
9040 let acknowledgment = response_dispatch
9041 .complete()
9042 .expect("an ordered response should require acknowledgment");
9043
9044 let callback_ran = Arc::new(AtomicBool::new(false));
9045 sent.on_receiving_result({
9046 let callback_ran = callback_ran.clone();
9047 async move |result| {
9048 assert_eq!(result?, serde_json::json!({"ok": true}));
9049 callback_ran.store(true, Ordering::Release);
9050 Ok(())
9051 }
9052 })
9053 .expect("ordered callback should be scheduled");
9054
9055 let task = futures::FutureExt::now_or_never(futures::StreamExt::next(&mut task_rx))
9056 .expect("callback task should already be queued")
9057 .expect("callback task queue should remain open");
9058 futures::executor::block_on(task.run_for_test()).expect("callback task should succeed");
9059 futures::executor::block_on(acknowledgment)
9060 .expect("callback completion should acknowledge dispatch");
9061 assert!(callback_ran.load(Ordering::Acquire));
9062 }
9063
9064 fn next_dynamic_handler_message<Counterpart: Role>(
9065 receiver: &mut mpsc::UnboundedReceiver<DynamicHandlerMessage<Counterpart>>,
9066 ) -> Option<DynamicHandlerMessage<Counterpart>> {
9067 futures::FutureExt::now_or_never(futures::StreamExt::next(receiver))
9068 .expect("dynamic-handler receiver should be ready")
9069 }
9070
9071 #[cfg(feature = "unstable_protocol_v2")]
9072 #[test]
9073 fn v2_dynamic_handler_guard_registers_and_removes_handler() {
9074 let (message_tx, _message_rx) = mpsc::unbounded();
9075 let (task_tx, _task_rx) = mpsc::unbounded();
9076 let (dynamic_handler_tx, mut dynamic_handler_rx) = mpsc::unbounded();
9077 let transport_completion: SharedTransportCompletion =
9078 future::ready(Ok::<(), crate::Error>(())).boxed().shared();
9079 let pending_replies = PendingReplies::default();
9080 let connection = crate::v2::ConnectionTo {
9081 inner: ConnectionTo::new(
9082 Agent,
9083 message_tx,
9084 task_tx,
9085 dynamic_handler_tx,
9086 transport_completion,
9087 pending_replies.registrar(),
9088 ProtocolMode::v2_client(),
9089 ),
9090 };
9091
9092 let guard = connection
9093 .add_dynamic_handler(NullHandler)
9094 .expect("v2 dynamic handler should register");
9095 let added_uuid = match next_dynamic_handler_message(&mut dynamic_handler_rx) {
9096 Some(DynamicHandlerMessage::AddDynamicHandler(uuid, _, _)) => uuid,
9097 other => panic!("expected v2 handler registration, got {other:?}"),
9098 };
9099
9100 drop(guard);
9101
9102 match next_dynamic_handler_message(&mut dynamic_handler_rx) {
9103 Some(DynamicHandlerMessage::RemoveDynamicHandler(uuid)) => {
9104 assert_eq!(uuid, added_uuid);
9105 }
9106 other => panic!("expected v2 handler removal, got {other:?}"),
9107 }
9108 }
9109
9110 #[test]
9111 fn dropping_dynamic_handler_guard_unregisters_handler() {
9112 let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9113 let guard = connection.add_dynamic_handler(NullHandler).unwrap();
9114
9115 let added_uuid = match next_dynamic_handler_message(&mut receiver) {
9116 Some(DynamicHandlerMessage::AddDynamicHandler(uuid, _, _)) => uuid,
9117 other => panic!("expected handler registration, got {other:?}"),
9118 };
9119
9120 drop(guard);
9121
9122 match next_dynamic_handler_message(&mut receiver) {
9123 Some(DynamicHandlerMessage::RemoveDynamicHandler(uuid)) => {
9124 assert_eq!(uuid, added_uuid);
9125 }
9126 other => panic!("expected handler removal, got {other:?}"),
9127 }
9128 }
9129
9130 #[test]
9131 fn dropping_dynamic_handler_guard_deactivates_queued_handler_immediately() {
9132 let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9133 let guard = connection
9134 .add_dynamic_handler(ClaimingDynamicHandler)
9135 .expect("dynamic handler should register");
9136 let mut handler = match next_dynamic_handler_message(&mut receiver) {
9137 Some(DynamicHandlerMessage::AddDynamicHandler(_, handler, _)) => handler,
9138 other => panic!("expected handler registration, got {other:?}"),
9139 };
9140
9141 drop(guard);
9142
9143 let message = Dispatch::Notification(
9144 UntypedMessage::new("stale", serde_json::json!({}))
9145 .expect("test notification should serialize"),
9146 );
9147 let outcome =
9148 futures::executor::block_on(handler.dyn_handle_dispatch_from(message, connection))
9149 .expect("inactive handler should decline cleanly");
9150 assert!(matches!(outcome, Handled::No { retry: false, .. }));
9151 }
9152
9153 #[test]
9154 fn dynamic_handler_barrier_acknowledges_prior_messages() {
9155 let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9156 let _guard = connection.add_dynamic_handler(NullHandler).unwrap();
9157 let mut barrier = Box::pin(connection.dynamic_handler_barrier());
9158
9159 assert!(matches!(
9160 next_dynamic_handler_message(&mut receiver),
9161 Some(DynamicHandlerMessage::AddDynamicHandler(_, _, _))
9162 ));
9163 assert!(
9164 barrier.as_mut().now_or_never().is_none(),
9165 "the barrier must wait for the incoming actor"
9166 );
9167
9168 let acknowledgment = match next_dynamic_handler_message(&mut receiver) {
9169 Some(DynamicHandlerMessage::AcknowledgedBarrier(acknowledgment)) => acknowledgment,
9170 other => panic!("expected acknowledged barrier, got {other:?}"),
9171 };
9172 acknowledgment
9173 .send(())
9174 .expect("the barrier receiver should remain active");
9175 futures::executor::block_on(barrier)
9176 .expect("the acknowledged dynamic-handler barrier should complete");
9177 }
9178
9179 #[test]
9180 fn detaching_dynamic_handler_guard_does_not_leak_connection() {
9181 let (connection, mut receiver) = connection_with_dynamic_handler_receiver();
9182 let guard = connection.add_dynamic_handler(NullHandler).unwrap();
9183
9184 assert!(matches!(
9185 next_dynamic_handler_message(&mut receiver),
9186 Some(DynamicHandlerMessage::AddDynamicHandler(_, _, _))
9187 ));
9188
9189 drop(connection);
9190 guard.detach();
9191
9192 assert!(
9193 next_dynamic_handler_message(&mut receiver).is_none(),
9194 "detach should retain the handler without retaining a connection sender"
9195 );
9196 }
9197
9198 #[tokio::test]
9199 async fn write_line_flushes_buffered_writers() {
9200 let mut writer =
9201 futures::io::BufWriter::with_capacity(4096, futures::io::Cursor::new(Vec::new()));
9202
9203 write_line(&mut writer, "message".into()).await.unwrap();
9204
9205 assert_eq!(writer.into_inner().into_inner(), b"message\n");
9206 }
9207
9208 #[tokio::test]
9209 async fn lossy_lines_strip_line_endings_and_replace_invalid_utf8() {
9210 use futures::TryStreamExt as _;
9211
9212 let reader = futures::io::Cursor::new(b"crlf\r\n\ninva\xfflid\nno ending".to_vec());
9213
9214 let lines: Vec<String> = lossy_lines(reader).try_collect().await.unwrap();
9215
9216 assert_eq!(lines, ["crlf", "", "inva\u{FFFD}lid", "no ending"]);
9217 }
9218
9219 #[test]
9220 fn peel_successor_envelopes_returns_plain_messages_unchanged() {
9221 let params = serde_json::json!({ "key": "value" });
9222 let (method, peeled) = peel_successor_envelopes("session/update", ¶ms);
9223 assert_eq!(method, "session/update");
9224 assert_eq!(peeled, ¶ms);
9225 }
9226
9227 #[test]
9228 fn peel_successor_envelopes_unwraps_nested_envelopes() {
9229 let params = serde_json::json!({
9230 "method": "proxy/successor",
9231 "params": {
9232 "method": "$/cancel_request",
9233 "params": { "requestId": "req-1" }
9234 }
9235 });
9236 let (method, peeled) = peel_successor_envelopes("proxy/successor", ¶ms);
9237 assert_eq!(method, "$/cancel_request");
9238 assert_eq!(peeled, &serde_json::json!({ "requestId": "req-1" }));
9239 }
9240
9241 #[test]
9242 fn peel_successor_envelopes_leaves_malformed_envelopes_intact() {
9243 // No string `method` field: the envelope cannot be peeled, so the
9244 // message is returned as-is for the handler chain to deal with.
9245 let params = serde_json::json!({ "unexpected": true });
9246 let (method, peeled) = peel_successor_envelopes("proxy/successor", ¶ms);
9247 assert_eq!(method, "proxy/successor");
9248 assert_eq!(peeled, ¶ms);
9249 }
9250
9251 mod cancel_request {
9252 use super::super::*;
9253
9254 fn notification(method: &str, params: serde_json::Value) -> UntypedMessage {
9255 UntypedMessage::new(method, params).expect("well-formed JSON")
9256 }
9257
9258 #[test]
9259 fn cancellation_request_id_is_extracted_from_wrapped_notifications() {
9260 let message = notification(
9261 "proxy/successor",
9262 serde_json::json!({
9263 "method": "$/cancel_request",
9264 "params": { "requestId": "req-1" }
9265 }),
9266 );
9267 let request_id = cancellation_request_id_from_message(&message)
9268 .expect("wrapped cancel should parse");
9269 assert_eq!(request_id, Some(RawJsonRpcId::Str("req-1".into())));
9270 }
9271
9272 #[test]
9273 fn malformed_successor_envelope_is_not_treated_as_cancellation() {
9274 // The envelope cannot be peeled; the message must flow on to the
9275 // handler chain instead of erroring the dispatch.
9276 let message = notification("proxy/successor", serde_json::json!({ "bogus": true }));
9277 let request_id = cancellation_request_id_from_message(&message)
9278 .expect("malformed envelope should be left to the handler chain");
9279 assert_eq!(request_id, None);
9280 }
9281
9282 #[test]
9283 fn cancel_request_notifications_are_detected_even_when_wrapped() {
9284 let plain = notification("$/cancel_request", serde_json::json!({ "requestId": 1 }));
9285 assert!(is_cancel_request_notification(&plain));
9286
9287 let wrapped = notification(
9288 "proxy/successor",
9289 serde_json::json!({
9290 "method": "$/cancel_request",
9291 "params": { "requestId": 1 }
9292 }),
9293 );
9294 assert!(is_cancel_request_notification(&wrapped));
9295
9296 let other_wrapped = notification(
9297 "proxy/successor",
9298 serde_json::json!({
9299 "method": "session/update",
9300 "params": {}
9301 }),
9302 );
9303 assert!(!is_cancel_request_notification(&other_wrapped));
9304
9305 let malformed_envelope =
9306 notification("proxy/successor", serde_json::json!({ "bogus": true }));
9307 assert!(!is_cancel_request_notification(&malformed_envelope));
9308 }
9309
9310 #[test]
9311 fn malformed_cancel_request_params_error() {
9312 let message = notification(
9313 "$/cancel_request",
9314 serde_json::json!({ "requestId": { "not": "an id" } }),
9315 );
9316 cancellation_request_id_from_message(&message)
9317 .expect_err("malformed cancel params should error");
9318 }
9319
9320 #[test]
9321 fn registry_marks_and_removes_requests() {
9322 let registry = RequestCancellationRegistry::new();
9323 let id = RawJsonRpcId::Str("req-1".into());
9324
9325 let responder_cancellation = registry.register(&id);
9326 let marker = responder_cancellation.cancellation();
9327 assert!(!marker.is_cancelled());
9328
9329 assert!(registry.cancel(&id));
9330 assert!(marker.is_cancelled());
9331 assert!(responder_cancellation.cancellation().is_cancelled());
9332
9333 drop(responder_cancellation);
9334 assert!(!registry.cancel(&id), "slot should be removed on drop");
9335 }
9336
9337 #[test]
9338 fn reused_request_id_does_not_cross_wire_cancellation_state() {
9339 let registry = RequestCancellationRegistry::new();
9340 let id = RawJsonRpcId::Str("dup".into());
9341
9342 // A protocol-violating peer reuses an in-flight request ID.
9343 let first = registry.register(&id);
9344 let first_marker = first.cancellation();
9345 let second = registry.register(&id);
9346 let second_marker = second.cancellation();
9347
9348 // A cancellation targets whichever request currently owns the ID.
9349 assert!(registry.cancel(&id));
9350 assert!(second_marker.is_cancelled());
9351 assert!(
9352 !first_marker.is_cancelled(),
9353 "the stale request must not observe the newer request's cancellation"
9354 );
9355
9356 // The stale responder must hand out detached markers, not the
9357 // newer request's marker.
9358 assert!(!first.cancellation().is_cancelled());
9359
9360 // Dropping the stale responder must not remove the newer
9361 // request's slot.
9362 drop(first);
9363 assert!(registry.cancel(&id), "newer slot should still be present");
9364
9365 drop(second);
9366 assert!(!registry.cancel(&id), "slot should be removed on drop");
9367 }
9368 }
9369}