Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions md/transport-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,8 @@ Output: mpsc::UnboundedSender<TransportFrame>
For byte streams:

- Read newline-delimited JSON from stream
- Replace bytes that are not valid UTF-8 with U+FFFD, so a line with such a
byte is one message to parse, not a read failure that ends the connection
- Parse a single message
- Retain malformed input, including JSON arrays, so relays can forward it
- Leave call/response-shape classification and Error Response decisions to the
Expand Down
17 changes: 9 additions & 8 deletions src/agent-client-protocol/src/acp_agent.rs
Original file line number Diff line number Diff line change
Expand Up @@ -820,8 +820,7 @@ impl AcpAgent {
),
crate::Error,
> {
use futures::io::BufReader;
use futures::{AsyncBufReadExt, StreamExt};
use futures::StreamExt;

let (child_stdin, child_stdout, child_stderr, child) = self.spawn_process()?;

Expand Down Expand Up @@ -859,13 +858,15 @@ impl AcpAgent {
let incoming_lines: std::pin::Pin<
Box<dyn futures::Stream<Item = std::io::Result<String>> + Send>,
> = if let Some(callback) = self.debug_callback.clone() {
Box::pin(BufReader::new(child_stdout).lines().inspect(move |result| {
if let Ok(line) = result {
callback(line, LineDirection::Stdout);
}
}))
Box::pin(
crate::jsonrpc::lossy_lines(child_stdout).inspect(move |result| {
if let Ok(line) = result {
callback(line, LineDirection::Stdout);
}
}),
)
} else {
Box::pin(BufReader::new(child_stdout).lines())
Box::pin(crate::jsonrpc::lossy_lines(child_stdout))
};

// The JSON-RPC transport keeps polling stdout while it drains stdin.
Expand Down
56 changes: 53 additions & 3 deletions src/agent-client-protocol/src/jsonrpc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7093,6 +7093,9 @@ impl<T, P: Protocol> SentRequest<T, P> {
/// This is particularly useful for debugging, logging, or implementing custom line-based
/// protocols.
///
/// An `Err` from the incoming stream ends the connection. A stream that decodes bytes itself
/// should replace invalid UTF-8, as [`ByteStreams`] does, instead of yielding an error for it.
///
/// # Use Cases
///
/// - **Line-by-line logging**: Intercept and log each line before parsing
Expand Down Expand Up @@ -7224,6 +7227,9 @@ where
/// streams, handling serialization of JSON-RPC messages to/from newline-delimited JSON.
/// This is the standard way to communicate with external processes or network connections.
///
/// Incoming bytes that are not valid UTF-8 are replaced with U+FFFD, so a line that contains
/// them is parsed like any other and does not end the connection.
///
/// # Use Cases
///
/// - **Stdio communication**: Connect to agents or proxies via stdin/stdout
Expand Down Expand Up @@ -7278,17 +7284,50 @@ where
impl futures::Sink<String, Error = std::io::Error> + Send + 'static,
impl futures::Stream<Item = std::io::Result<String>> + Send + 'static,
> {
use futures::AsyncBufReadExt;
use futures::io::BufReader;
let Self { outgoing, incoming } = self;

let incoming_lines = Box::pin(BufReader::new(incoming).lines());
let incoming_lines = Box::pin(lossy_lines(incoming));
let outgoing_lines = transport_actor::LineWriter::new(outgoing);

Lines::new(outgoing_lines, incoming_lines)
}
}

/// Splits `reader` into lines, without their `\n` or `\r\n` endings.
///
/// Bytes that are not valid UTF-8 are replaced with U+FFFD. Reporting them as
/// a read error would end the connection over one message. A line that is
/// JSON after the replacement is delivered, for example one with such a byte
/// inside a string. Any other line is a [`TransportFrame::Malformed`].
pub(crate) fn lossy_lines<R>(
reader: R,
) -> impl futures::Stream<Item = std::io::Result<String>> + Send + 'static
where
R: AsyncRead + Send + 'static,
{
use futures::AsyncBufReadExt as _;

let reader = Box::pin(futures::io::BufReader::new(reader));
futures::stream::try_unfold(reader, async |mut reader| {
let mut line = Vec::new();
if reader.read_until(b'\n', &mut line).await? == 0 {
return Ok::<_, std::io::Error>(None);
}
if line.ends_with(b"\n") {
line.pop();
if line.ends_with(b"\r") {
line.pop();
}
}
let line = String::from_utf8(line).unwrap_or_else(|error| {
// The line's content may be private, so it is not logged.
tracing::debug!("Replaced invalid UTF-8 in an incoming line");
String::from_utf8_lossy(error.as_bytes()).into_owned()
});
Ok(Some((line, reader)))
})
}

#[cfg(any(
all(
any(feature = "process", feature = "stdio"),
Expand Down Expand Up @@ -8858,6 +8897,17 @@ mod tests {
assert_eq!(writer.into_inner().into_inner(), b"message\n");
}

#[tokio::test]
async fn lossy_lines_strip_line_endings_and_replace_invalid_utf8() {
use futures::TryStreamExt as _;

let reader = futures::io::Cursor::new(b"crlf\r\n\ninva\xfflid\nno ending".to_vec());

let lines: Vec<String> = lossy_lines(reader).try_collect().await.unwrap();

assert_eq!(lines, ["crlf", "", "inva\u{FFFD}lid", "no ending"]);
}

#[test]
fn peel_successor_envelopes_returns_plain_messages_unchanged() {
let params = serde_json::json!({ "key": "value" });
Expand Down
18 changes: 10 additions & 8 deletions src/agent-client-protocol/src/stdio.rs
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +52,18 @@ impl<Counterpart: Role> ConnectTo<Counterpart> for Stdio {
let stdout = blocking::Unblock::new(std::io::stdout());

if let Some(callback) = self.debug_callback {
use futures::io::BufReader;
use futures::{AsyncBufReadExt, StreamExt};
use futures::StreamExt;

let incoming_callback = callback.clone();
let incoming_lines = Box::pin(BufReader::new(stdin).lines().inspect(move |result| {
if let Ok(line) = result {
incoming_callback(line, LineDirection::Stdin);
}
}))
as std::pin::Pin<Box<dyn futures::Stream<Item = std::io::Result<String>> + Send>>;
let incoming_lines =
Box::pin(crate::jsonrpc::lossy_lines(stdin).inspect(move |result| {
if let Ok(line) = result {
incoming_callback(line, LineDirection::Stdin);
}
}))
as std::pin::Pin<
Box<dyn futures::Stream<Item = std::io::Result<String>> + Send>,
>;

let outgoing_sink = Box::pin(futures::sink::unfold(
(stdout, callback),
Expand Down
71 changes: 71 additions & 0 deletions src/agent-client-protocol/tests/jsonrpc_error_handling.rs
Original file line number Diff line number Diff line change
Expand Up @@ -879,6 +879,77 @@ async fn test_bad_request_params_return_invalid_params_and_connection_stays_aliv
.await;
}

// ============================================================================
// Test 6b: Invalid UTF-8 is replaced and connection stays alive
// ============================================================================

#[tokio::test(flavor = "current_thread")]
async fn test_invalid_utf8_is_replaced_and_connection_stays_alive() {
use tokio::io::{AsyncWriteExt, BufReader};
use tokio::task::LocalSet;

let local = LocalSet::new();

local
.run_until(async {
let (mut client_writer, server_reader) = tokio::io::duplex(2048);
let (server_writer, client_reader) = tokio::io::duplex(2048);

let server_reader = server_reader.compat();
let server_writer = server_writer.compat_write();

let server_transport =
agent_client_protocol::ByteStreams::new(server_writer, server_reader);
let server = UntypedRole.builder().on_receive_request(
async |request: SimpleRequest,
responder: Responder<SimpleResponse>,
_connection: ConnectionTo<UntypedRole>| {
responder.respond(SimpleResponse {
result: format!("echo: {}", request.message),
})
},
agent_client_protocol::on_receive_request!(),
);

tokio::task::spawn_local(async move {
if let Err(err) = server.connect_to(server_transport).await {
panic!("server should stay alive: {err:?}");
}
});

let mut client_reader = BufReader::new(client_reader);

// Outside a string, the line is not JSON after the replacement either.
client_writer
.write_all(b"\xff{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"simple_method\"}\n")
.await
.unwrap();
client_writer.flush().await.unwrap();

let parse_error = read_jsonrpc_response_line(&mut client_reader).await;
assert_eq!(parse_error["id"], serde_json::Value::Null);
assert_eq!(parse_error["error"]["code"], -32700);
assert_eq!(
parse_error["error"]["data"]["line"],
"\u{FFFD}{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"simple_method\"}"
);

// Inside a string, the message is delivered with the replacement.
client_writer
.write_all(
b"{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"simple_method\",\"params\":{\"message\":\"a\xffb\"}}\n",
)
.await
.unwrap();
client_writer.flush().await.unwrap();

let ok_response = read_jsonrpc_response_line(&mut client_reader).await;
assert_eq!(ok_response["id"], 6);
assert_eq!(ok_response["result"]["result"], "echo: a\u{FFFD}b");
})
.await;
}

// ============================================================================
// Test 7: Notification errors
// ============================================================================
Expand Down
Loading