AstrBot-Desktop/src-tauri/src/networking/astrbot_client.rs
YokiiroBW 4063215b0a
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
fix(astrbot): let one rejected attachment path fall through to the next
The candidate search returned on the first 401, so only the first of the
three addresses was ever tried — the log shows ten requests to
/api/chat/get_file and not a single download record.

A rejection is per-endpoint here rather than per-connection.
/api/chat/* is the dashboard's own API and wants a dashboard JWT, while
/api/v1/* accepts the API key the connection already holds, so a 401
from one says nothing about the others.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-27 03:28:34 +08:00

1693 行
66 KiB
Rust

use std::{collections::VecDeque, sync::Arc, time::Duration};
use desktop_protocol::{
AstrBotApiEnvelope, AstrBotAttachment, AstrBotCapabilitySnapshot, AstrBotChatRequest,
AstrBotConfigListData, AstrBotModelOption, AstrBotSessionListData, AstrBotStreamMapper,
AuthenticationType, BoundGatewayEvent, ConnectionState, FinishReason, GatewayEvent,
PROTOCOL_VERSION, derive_astrbot_server_instance_id,
};
use futures_util::StreamExt;
use reqwest::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE, HeaderMap, HeaderValue};
use secrecy::{ExposeSecret, SecretString};
use serde_json::{Value, json};
use thiserror::Error;
use tokio::sync::{Mutex, mpsc, watch};
use tokio_util::sync::CancellationToken;
use super::{GatewayError, SlotKind};
#[derive(Debug, Clone)]
pub struct AstrBotClientConfig {
pub profile_id: String,
pub slot: SlotKind,
pub base_url: String,
pub api_key: SecretString,
/// Remote WebChat username used as session owner identity.
pub remote_username: String,
pub remote_display_name: Option<String>,
pub authentication_type: AuthenticationType,
/// Optional sticky session id. When absent, the first chat response supplies one.
pub session_id: Option<String>,
/// Expected server identity substitute. Empty means accept first observed identity.
pub expected_server_instance_id: Option<String>,
}
#[derive(Debug, Error)]
pub enum AstrBotClientError {
#[error("astrbot request failed")]
Request(#[from] reqwest::Error),
#[error("astrbot returned HTTP {0}")]
HttpStatus(reqwest::StatusCode),
#[error("astrbot api status error: {0}")]
ApiStatus(String),
#[error("invalid astrbot payload")]
Json(#[from] serde_json::Error),
#[error("astrbot stream mapping failed: {0}")]
Map(String),
/// The response body broke after the server had already started answering.
///
/// Distinct from [`AstrBotClientError::Request`] on purpose: `/api/v1/chat`
/// has no idempotency key, so re-POSTing a message whose response had
/// already begun duplicates it in the remote conversation. Only the caller
/// (i.e. the user) may retry this.
#[error("astrbot stream interrupted after the response started")]
StreamInterrupted,
#[error("server identity changed")]
ServerIdentityChanged,
#[error("astrbot event channel closed")]
ChannelClosed,
#[error("invalid configuration: {0}")]
InvalidConfig(&'static str),
#[error("astrbot credential expired")]
CredentialExpired,
}
impl From<AstrBotClientError> for GatewayError {
fn from(value: AstrBotClientError) -> Self {
match value {
AstrBotClientError::Request(error) => GatewayError::Request(error),
AstrBotClientError::HttpStatus(status) => GatewayError::HttpStatus(status),
AstrBotClientError::Json(error) => GatewayError::Json(error),
AstrBotClientError::ServerIdentityChanged => GatewayError::ServerIdentityChanged,
AstrBotClientError::ChannelClosed => GatewayError::ChannelClosed,
AstrBotClientError::ApiStatus(message) => GatewayError::Adapter(message),
AstrBotClientError::Map(message) => GatewayError::Adapter(message),
AstrBotClientError::StreamInterrupted => GatewayError::Adapter(
"AstrBot stream interrupted after the response started".into(),
),
AstrBotClientError::InvalidConfig(message) => GatewayError::Adapter(message.to_owned()),
AstrBotClientError::CredentialExpired => {
GatewayError::Adapter("AstrBot authentication has expired".into())
}
}
}
}
const MAX_DEDUPLICATED_EVENTS: usize = 4_096;
/// Guards against a hostile or broken server streaming an unbounded single line.
const MAX_SSE_LINE_BYTES: usize = 1024 * 1024;
/// Ceiling on the total size of one chat response.
///
/// Removing `Client::timeout` from the streaming client (so a slow reply is no
/// longer cut off) also removed the only bound on how much a server could send
/// in one response. `read_timeout` cannot replace it: it measures the gap
/// between successful reads, so a server that keeps trickling bytes keeps the
/// stream alive forever, and both this buffer and the mapper's accumulated
/// message text would grow without limit. A real reply is far below this.
const MAX_STREAM_BYTES: u64 = 64 * 1024 * 1024;
/// Splits an SSE byte stream into lines at the byte level.
///
/// TCP chunk boundaries fall on arbitrary byte offsets, so decoding each chunk
/// with `String::from_utf8_lossy` corrupts any multi-byte character that
/// straddles two chunks — for CJK text (3 bytes per character) that is a
/// frequent, user-visible `U+FFFD`. Buffering raw bytes and only decoding
/// complete `\n`-delimited lines keeps every character intact, because SSE
/// guarantees `\n` (0x0A) never appears inside a UTF-8 multi-byte sequence.
#[derive(Debug, Default)]
struct SseLineBuffer {
bytes: Vec<u8>,
/// Offset of the first unconsumed byte.
///
/// Consuming a line by draining from the front would memmove the entire
/// remainder once per line, which is quadratic in the chunk size — and a
/// single `bytes_stream()` item from hyper can be several hundred KiB of
/// short delta frames. Advancing a cursor instead makes reading a line O(1)
/// and leaves one memmove per chunk, in `push_chunk`.
cursor: usize,
total: u64,
}
impl SseLineBuffer {
fn push_chunk(&mut self, chunk: &[u8]) {
if self.cursor > 0 {
self.bytes.drain(..self.cursor);
self.cursor = 0;
}
self.total = self.total.saturating_add(chunk.len() as u64);
self.bytes.extend_from_slice(chunk);
}
/// Pops the next complete line, or `None` when the buffer holds no `\n` yet.
///
/// Invalid UTF-8 within a single complete line is replaced rather than
/// rejected: a lossy line is still parseable SSE, and dropping the whole
/// stream over one bad byte would lose the surrounding reply.
fn next_line(&mut self) -> Option<String> {
let pending = &self.bytes[self.cursor..];
let index = pending.iter().position(|byte| *byte == b'\n')?;
let mut line = &pending[..index];
if line.last() == Some(&b'\r') {
line = &line[..line.len() - 1];
}
let text = String::from_utf8_lossy(line).into_owned();
self.cursor += index + 1;
Some(text)
}
/// Consumes whatever is left once the stream ends without a trailing `\n`.
fn take_remainder(&mut self) -> Option<String> {
let mut line = &self.bytes[self.cursor..];
if line.is_empty() {
return None;
}
if line.last() == Some(&b'\r') {
line = &line[..line.len() - 1];
}
let text = String::from_utf8_lossy(line).into_owned();
self.cursor = self.bytes.len();
(!text.trim().is_empty()).then_some(text)
}
/// True when one line, or the whole response, has outgrown its limit.
fn is_overflowing(&self) -> bool {
self.bytes.len() - self.cursor > MAX_SSE_LINE_BYTES || self.total > MAX_STREAM_BYTES
}
}
#[derive(Default)]
struct EventDeduplicator {
ids: std::collections::HashSet<String>,
order: VecDeque<String>,
}
impl EventDeduplicator {
fn insert(&mut self, event_id: String) -> bool {
if !self.ids.insert(event_id.clone()) {
return false;
}
self.order.push_back(event_id);
if self.order.len() > MAX_DEDUPLICATED_EVENTS
&& let Some(expired) = self.order.pop_front()
{
self.ids.remove(&expired);
}
true
}
}
/// Total budget for a short request/response exchange (probe, sessions, upload).
const REST_TOTAL_TIMEOUT: Duration = Duration::from_secs(120);
/// How long the chat stream may stay completely silent before it is abandoned.
///
/// This is deliberately *not* a total timeout. `Client::timeout` counts from the
/// start of the request until the body has finished, and it keeps running while
/// `bytes_stream()` is being consumed, so any generation longer than the budget
/// was cut off mid-reply. `read_timeout` resets after every successful read, so
/// a reply may take arbitrarily long as long as it keeps producing bytes.
const STREAM_IDLE_TIMEOUT: Duration = Duration::from_secs(120);
const CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
#[derive(Clone)]
pub struct AstrBotClient {
config: AstrBotClientConfig,
/// Short request/response endpoints; keeps a total deadline.
http: reqwest::Client,
/// `/api/v1/chat` only; no total deadline, idle detection via `read_timeout`.
stream_http: reqwest::Client,
seen_event_ids: Arc<Mutex<EventDeduplicator>>,
session_id: Arc<Mutex<Option<String>>>,
server_instance_id: Arc<Mutex<String>>,
state_tx: watch::Sender<ConnectionState>,
}
impl AstrBotClient {
pub fn new(config: AstrBotClientConfig) -> Result<Self, AstrBotClientError> {
if config.base_url.trim().is_empty() {
return Err(AstrBotClientError::InvalidConfig("base_url is required"));
}
if config.remote_username.trim().is_empty() {
return Err(AstrBotClientError::InvalidConfig(
"remote_username is required",
));
}
if config.api_key.expose_secret().trim().is_empty() {
return Err(AstrBotClientError::InvalidConfig("api_key is required"));
}
if config.authentication_type == AuthenticationType::Jwt
&& jwt_is_expired(config.api_key.expose_secret())
{
return Err(AstrBotClientError::CredentialExpired);
}
let base = config.base_url.trim_end_matches('/').to_owned();
let derived = derive_astrbot_server_instance_id(&base);
let initial_identity = config
.expected_server_instance_id
.clone()
.filter(|value| !value.trim().is_empty())
.unwrap_or(derived);
let mut headers = HeaderMap::new();
let auth_value = format!("Bearer {}", config.api_key.expose_secret());
headers.insert(
AUTHORIZATION,
HeaderValue::from_str(&auth_value).map_err(|_| {
AstrBotClientError::InvalidConfig("api_key has invalid header chars")
})?,
);
let http = reqwest::Client::builder()
.default_headers(headers.clone())
.redirect(reqwest::redirect::Policy::none())
.connect_timeout(CONNECT_TIMEOUT)
.timeout(REST_TOTAL_TIMEOUT)
.build()?;
let stream_http = reqwest::Client::builder()
.default_headers(headers)
.redirect(reqwest::redirect::Policy::none())
.connect_timeout(CONNECT_TIMEOUT)
.read_timeout(STREAM_IDLE_TIMEOUT)
.tcp_keepalive(Duration::from_secs(60))
.build()?;
let (state_tx, _) = watch::channel(ConnectionState::Disconnected);
let initial_session = config.session_id.clone();
Ok(Self {
config: AstrBotClientConfig {
base_url: base,
..config
},
http,
stream_http,
seen_event_ids: Arc::new(Mutex::new(EventDeduplicator::default())),
session_id: Arc::new(Mutex::new(initial_session)),
server_instance_id: Arc::new(Mutex::new(initial_identity)),
state_tx,
})
}
pub fn state_receiver(&self) -> watch::Receiver<ConnectionState> {
self.state_tx.subscribe()
}
pub fn server_instance_id_blocking(&self) -> String {
self.server_instance_id
.try_lock()
.map(|guard| guard.clone())
.unwrap_or_else(|_| derive_astrbot_server_instance_id(&self.config.base_url))
}
fn set_state(&self, state: ConnectionState) {
self.state_tx.send_replace(state);
}
fn url(&self, path: &str) -> String {
format!("{}{}", self.config.base_url, path)
}
pub async fn probe(&self) -> Result<Value, AstrBotClientError> {
self.set_state(ConnectionState::Connecting);
let response = self
.http
.get(self.url(&format!(
"/api/v1/chat/sessions?username={}&page=1&page_size=1",
urlencoding_username(&self.config.remote_username)
)))
.send()
.await?;
if response.status().as_u16() == 401 || response.status().as_u16() == 403 {
self.set_state(ConnectionState::AuthExpired);
return Err(AstrBotClientError::HttpStatus(response.status()));
}
if !response.status().is_success() {
self.set_state(ConnectionState::ServerUnavailable);
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let envelope: AstrBotApiEnvelope<AstrBotSessionListData> = response.json().await?;
if !envelope.is_ok() {
self.set_state(ConnectionState::FatalError);
return Err(AstrBotClientError::ApiStatus(
envelope
.message
.unwrap_or_else(|| "chat sessions probe failed".into()),
));
}
self.set_state(ConnectionState::Connected);
Ok(json!({
"status": "ok",
"protocolVersion": PROTOCOL_VERSION,
"transport": "astrbot-openapi",
"serverInstanceId": self.server_instance_id.lock().await.clone(),
"remoteUsername": self.config.remote_username,
"sessionCount": envelope.data.map(|data| data.total.unwrap_or(0)).unwrap_or(0),
}))
}
pub async fn set_session_id(&self, session_id: String) -> Result<(), AstrBotClientError> {
if session_id.trim().is_empty() {
return Err(AstrBotClientError::InvalidConfig("session_id is required"));
}
*self.session_id.lock().await = Some(session_id);
Ok(())
}
pub async fn list_sessions(&self) -> Result<AstrBotSessionListData, AstrBotClientError> {
let response = self
.http
.get(self.url(&format!(
"/api/v1/chat/sessions?username={}&page=1&page_size=50",
urlencoding_username(&self.config.remote_username)
)))
.send()
.await?;
if !response.status().is_success() {
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let envelope: AstrBotApiEnvelope<AstrBotSessionListData> = response.json().await?;
if !envelope.is_ok() {
return Err(AstrBotClientError::ApiStatus(
envelope
.message
.unwrap_or_else(|| "list sessions failed".into()),
));
}
Ok(envelope.data.unwrap_or(AstrBotSessionListData {
sessions: Vec::new(),
page: Some(1),
page_size: Some(50),
total: Some(0),
}))
}
pub async fn list_configs(&self) -> Result<AstrBotConfigListData, AstrBotClientError> {
let response = self.http.get(self.url("/api/v1/configs")).send().await?;
if !response.status().is_success() {
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let envelope: AstrBotApiEnvelope<AstrBotConfigListData> = response.json().await?;
if !envelope.is_ok() {
return Err(AstrBotClientError::ApiStatus(
envelope
.message
.unwrap_or_else(|| "list configs failed".into()),
));
}
Ok(envelope.data.unwrap_or(AstrBotConfigListData {
configs: Vec::new(),
}))
}
pub async fn capabilities(&self) -> Result<AstrBotCapabilitySnapshot, AstrBotClientError> {
let configs = self.list_configs().await?;
let models = configs
.configs
.into_iter()
.map(|config| AstrBotModelOption {
id: config.id,
name: config.name,
is_default: config.is_default,
})
.collect::<Vec<_>>();
Ok(AstrBotCapabilitySnapshot {
transport: "astrbot-openapi".to_owned(),
text_chat: true,
streaming: true,
model_selection: !models.is_empty(),
file_upload: true,
image_input: true,
models,
})
}
pub async fn upload_file(
&self,
file_name: &str,
mime_type: &str,
bytes: Vec<u8>,
) -> Result<AstrBotAttachment, AstrBotClientError> {
if file_name.trim().is_empty() || mime_type.trim().is_empty() || bytes.is_empty() {
return Err(AstrBotClientError::InvalidConfig(
"file_name, mime_type, and file bytes are required",
));
}
let part = reqwest::multipart::Part::bytes(bytes.clone())
.file_name(file_name.to_owned())
.mime_str(mime_type)
.map_err(|_| AstrBotClientError::InvalidConfig("invalid attachment mime type"))?;
let form = reqwest::multipart::Form::new().part("file", part);
let response = self
.http
.post(self.url("/api/v1/files"))
.multipart(form)
.send()
.await?;
if !response.status().is_success() {
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let envelope: AstrBotApiEnvelope<Value> = response.json().await?;
if !envelope.is_ok() {
return Err(AstrBotClientError::ApiStatus(
envelope
.message
.unwrap_or_else(|| "file upload failed".into()),
));
}
let data = envelope.data.unwrap_or(Value::Null);
let attachment_id = data
.get("id")
.or_else(|| data.get("file_id"))
.or_else(|| data.get("attachment_id"))
.and_then(Value::as_str)
.ok_or_else(|| AstrBotClientError::Map("upload response has no attachment id".into()))?
.to_owned();
Ok(AstrBotAttachment {
attachment_id,
file_name: file_name.to_owned(),
mime_type: mime_type.to_owned(),
size_bytes: bytes.len() as u64,
url: data
.get("url")
.and_then(Value::as_str)
.map(ToOwned::to_owned),
})
}
/// Fetches a chat attachment, trying each way AstrBot addresses one.
///
/// The dashboard resolves an attachment by id when it has one and by file
/// name otherwise, and different AstrBot builds expose different paths for
/// it. The marker carries whichever the stream provided, so the candidates
/// are tried in turn.
///
/// Success cannot be judged by status: this server answers an unknown path
/// with its own "404 Not found" text under HTTP 200, so a candidate counts
/// only when the bytes are recognisably an image.
pub async fn download_attachment(
&self,
attachment_id: &str,
) -> Result<(String, Vec<u8>), AstrBotClientError> {
if attachment_id.is_empty()
|| attachment_id.len() > 200
|| !attachment_id
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'))
{
return Err(AstrBotClientError::InvalidConfig("invalid attachment id"));
}
let encoded = urlencoding_username(attachment_id);
let mut last_note = String::new();
for path in [
format!("/api/chat/get_file?filename={encoded}"),
format!("/api/chat/get_attachment?attachment_id={encoded}"),
format!("/api/v1/files/content?filename={encoded}"),
] {
match self.try_attachment(&path).await? {
Ok(found) => return Ok(found),
Err(note) => last_note = note,
}
}
Err(AstrBotClientError::ApiStatus(format!(
"服务器没有返回图片数据:{last_note}"
)))
}
/// One candidate path. `Ok(Err(note))` means "not here", with what the
/// server said instead.
async fn try_attachment(
&self,
path: &str,
) -> Result<Result<(String, Vec<u8>), String>, AstrBotClientError> {
let request_url = self.url(path);
let response = self.http.get(&request_url).send().await?;
let status = response.status();
// Logged before the status checks: a rejected request is exactly the
// case where the path being asked for is the thing in question. The URL
// holds a file name, not a credential; the bearer token is a header.
tracing::debug!(
target: FRAME_TRACE_TARGET,
url = request_url.as_str(),
status = status.as_u16(),
"astrbot attachment request"
);
// A rejection is per-endpoint, not per-connection: `/api/chat/*` is the
// dashboard's own API and wants a dashboard JWT, while `/api/v1/*`
// accepts the API key the connection already holds. Aborting the whole
// search on the first 401 meant the remaining candidates were never
// tried at all.
if !status.is_success() {
return Ok(Err(format!("HTTP {}", status.as_u16())));
}
let header_mime = response
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.split(';').next())
.map(str::trim)
.filter(|value| !value.is_empty())
.unwrap_or("application/octet-stream")
.to_owned();
let bytes = response.bytes().await?.to_vec();
if bytes.is_empty() || bytes.len() > 16 * 1024 * 1024 {
return Ok(Err("attachment size is outside the supported range".into()));
}
// A blob URL is decoded according to the blob's type, so handing the
// webview `application/octet-stream` makes `<img>` refuse bytes that are
// a perfectly good PNG. Prefer a concrete image type from the server,
// fall back to what the bytes themselves say.
let sniffed = sniff_image_mime(&bytes);
// When the body is not an image it is the server explaining why, which
// is diagnostic text rather than anything the user wrote.
let server_note = if sniffed.is_none() {
String::from_utf8_lossy(&bytes[..bytes.len().min(160)]).into_owned()
} else {
String::new()
};
tracing::debug!(
target: FRAME_TRACE_TARGET,
status = status.as_u16(),
header_mime = header_mime.as_str(),
sniffed = sniffed.unwrap_or("<not an image>"),
bytes = bytes.len(),
server_note = server_note.as_str(),
"astrbot attachment download"
);
match (header_mime.starts_with("image/"), sniffed) {
(true, _) => Ok(Ok((header_mime, bytes))),
(false, Some(sniffed)) => Ok(Ok((sniffed.to_owned(), bytes))),
(false, None) => Ok(Err(server_note)),
}
}
pub async fn send_chat_stream(
&self,
message: &str,
config_id: Option<String>,
attachments: Vec<AstrBotAttachment>,
sender: &mpsc::Sender<super::gateway_client::BoundGatewayEvent>,
cancellation: &CancellationToken,
) -> Result<Option<String>, AstrBotClientError> {
self.set_state(ConnectionState::Syncing);
let session_id = self.session_id.lock().await.clone();
let request = AstrBotChatRequest {
message: Value::String(message.to_owned()),
session_id: session_id.clone(),
conversation_id: None,
username: Some(self.config.remote_username.clone()),
nickname: self.config.remote_display_name.clone(),
config_id,
attachments: (!attachments.is_empty()).then_some(attachments),
platform_id: None,
enable_streaming: Some(true),
};
let response = self
.stream_http
.post(self.url("/api/v1/chat"))
.header(ACCEPT, HeaderValue::from_static("text/event-stream"))
.json(&request)
.send()
.await?;
if response.status().as_u16() == 401 || response.status().as_u16() == 403 {
self.set_state(ConnectionState::AuthExpired);
return Err(AstrBotClientError::HttpStatus(response.status()));
}
if !response.status().is_success() {
self.set_state(ConnectionState::ServerUnavailable);
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let server_instance_id = self.server_instance_id.lock().await.clone();
if let Some(expected) = &self.config.expected_server_instance_id
&& !expected.is_empty()
&& expected != &server_instance_id
{
self.set_state(ConnectionState::CertificateChanged);
return Err(AstrBotClientError::ServerIdentityChanged);
}
// Every request gets its own stream id: the mapper restarts its
// sequence counter per stream, and `seen_event_ids` outlives a single
// request, so reusing ids would make the deduplicator discard every
// event of the second and later messages on this connection.
let stream_id = uuid::Uuid::new_v4().to_string();
let mut mapper = AstrBotStreamMapper::new(server_instance_id.clone(), stream_id);
// Owned by this stream. It used to live in a thread_local, but the read
// loop is a tokio task that moves between worker threads across await
// points, so the accumulated text was split across several copies and the
// reported totals were a fraction of the real ones.
let mut trace = FrameTrace::default();
if let Some(existing) = session_id {
let seed = serde_json::json!({
"type": "session_id",
"data": null,
"session_id": existing,
});
let _ = mapper.push_line(&format!("data: {seed}"));
}
let mut stream = response.bytes_stream();
let mut buffer = SseLineBuffer::default();
self.set_state(ConnectionState::Connected);
// From here on the server has accepted and is answering this POST, so a
// failure must never be retried automatically — see `finish_and_fail`.
loop {
tokio::select! {
_ = cancellation.cancelled() => {
// Leave the connection state alone: the socket is still
// healthy and flipping to Disconnected only makes the tray
// and the slot badge flicker.
let events = mapper.finish_stream_with(FinishReason::Cancelled);
self.dispatch_events(events, sender).await?;
if let Some(session) = mapper.session_id() {
*self.session_id.lock().await = Some(session.to_owned());
}
self.set_state(ConnectionState::Connected);
return Ok(mapper.session_id().map(str::to_owned));
}
next = stream.next() => {
let Some(next) = next else { break; };
let chunk = match next {
Ok(chunk) => chunk,
Err(_) => {
return self
.finish_and_fail(&mut mapper, sender, AstrBotClientError::StreamInterrupted)
.await;
}
};
buffer.push_chunk(&chunk);
if buffer.is_overflowing() {
return self
.finish_and_fail(
&mut mapper,
sender,
AstrBotClientError::Map(
"astrbot response exceeded the supported size".into(),
),
)
.await;
}
while let Some(line) = buffer.next_line() {
trace.observe(&line);
match mapper.push_line(&line) {
Ok(events) => self.dispatch_events(events, sender).await?,
Err(error) => {
return self
.finish_and_fail(
&mut mapper,
sender,
AstrBotClientError::Map(error.to_string()),
)
.await;
}
}
}
}
}
}
if let Some(remainder) = buffer.take_remainder() {
trace.observe(&remainder);
match mapper.push_line(&remainder) {
Ok(events) => self.dispatch_events(events, sender).await?,
Err(error) => {
return self
.finish_and_fail(
&mut mapper,
sender,
AstrBotClientError::Map(error.to_string()),
)
.await;
}
}
}
let events = mapper.finish_stream();
self.dispatch_events(events, sender).await?;
if let Some(session) = mapper.session_id() {
*self.session_id.lock().await = Some(session.to_owned());
}
self.set_state(ConnectionState::Connected);
Ok(self.session_id.lock().await.clone())
}
/// Closes out a half-streamed message before surfacing a transport failure.
///
/// Every error path after the response headers arrive has to emit a
/// `MessageCompleted { finishReason: error }`; otherwise the partial reply
/// stays `streaming = 1` in the database and renders as "generating"
/// forever, including after a restart.
async fn finish_and_fail(
&self,
mapper: &mut AstrBotStreamMapper,
sender: &mpsc::Sender<super::gateway_client::BoundGatewayEvent>,
error: AstrBotClientError,
) -> Result<Option<String>, AstrBotClientError> {
let events = mapper.finish_stream_with(FinishReason::Error);
// Best effort: if the channel is already gone there is nothing left to
// finalize, and the original transport error is the more useful one.
let _ = self.dispatch_events(events, sender).await;
if let Some(session) = mapper.session_id() {
*self.session_id.lock().await = Some(session.to_owned());
}
self.set_state(ConnectionState::ServerUnavailable);
Err(error)
}
async fn dispatch_events(
&self,
events: Vec<GatewayEvent>,
sender: &mpsc::Sender<super::gateway_client::BoundGatewayEvent>,
) -> Result<(), AstrBotClientError> {
for event in events {
if let Some(session_id) = event.metadata.session_id.clone() {
*self.session_id.lock().await = Some(session_id);
}
let event_id = event.metadata.event_id.clone();
let mut seen = self.seen_event_ids.lock().await;
if !seen.insert(event_id.clone()) {
continue;
}
drop(seen);
let body = serde_json::to_value(&event.body)
.map_err(|error| AstrBotClientError::Map(error.to_string()))?;
let payload = body.get("payload").cloned().unwrap_or(body);
let bound = BoundGatewayEvent {
profile_id: self.config.profile_id.clone(),
slot: protocol_slot(self.config.slot),
event,
};
sender
.send(super::gateway_client::BoundGatewayEvent {
profile_id: bound.profile_id,
slot: self.config.slot,
event_id,
event_type: bound.event.event_type().to_owned(),
server_instance_id: bound.event.metadata.server_instance_id.clone(),
session_id: bound.event.metadata.session_id.clone(),
message_id: bound.event.metadata.message_id.clone(),
payload,
})
.await
.map_err(|_| AstrBotClientError::ChannelClosed)?;
}
Ok(())
}
}
/// Log target for the SSE frame trace. Named in the acceptance instructions, so
/// it must stay in sync with `docs/q9-local-acceptance.md`.
const FRAME_TRACE_TARGET: &str = "astrbot::frame";
/// Per-stream record of the SSE frames, at debug level.
///
/// Logs no payload text — only frame types, which identity fields are present,
/// the key names inside `data`, and lengths. Enable with
/// `RUST_LOG=astrbot::frame=debug`; off by default.
///
/// One instance belongs to one stream. It must not be a `thread_local`: the
/// read loop is a tokio task that moves between worker threads across await
/// points, so a thread-local split the accumulated text across several copies
/// and reported totals that were a fraction of the real ones.
///
/// Every `enabled!` guard here names the same target as the event it guards.
/// `enabled!` otherwise defaults to the module path, and a filter naming the
/// target would leave the guard returning false with nothing ever written.
///
/// AstrBot interleaves `plain` frames carrying incremental deltas
/// (`streaming: true`) with `plain` frames carrying a whole block
/// (`streaming: false`). Whether those blocks repeat text the delta stream also
/// delivers, or carry content of their own, decides opposite fixes: showing a
/// repeat as its own message duplicates it, while dropping distinct content
/// loses it. Lengths alone cannot tell them apart — one captured reply had a
/// 133-character block against 142 streamed characters, another had 915 against
/// 173.
///
/// Only lengths and containment booleans are logged. No text is recorded.
#[derive(Default)]
struct FrameTrace {
streamed: String,
blocks: Vec<String>,
}
impl FrameTrace {
/// Structural description of an attachment reference.
///
/// The media frame carries a string the client currently discards, and the
/// id taken from `attachment_saved` resolves to a web page. Whether that
/// string is a URL, a path, or a bare name decides how the attachment
/// should be fetched. Records the scheme, whether it looks like a path, and
/// the file extension — a format marker — but not the reference itself.
fn reference_shape(text: &str) -> String {
let scheme = if text.starts_with("http://") {
"http"
} else if text.starts_with("https://") {
"https"
} else if text.starts_with("file://") {
"file"
} else if text.starts_with('/') {
"absolute-path"
} else if text.starts_with('[') {
"bracketed"
} else {
"bare"
};
let extension = text
.rsplit_once('.')
.map(|(_, tail)| tail)
.filter(|tail| tail.len() <= 5 && tail.chars().all(|c| c.is_ascii_alphanumeric()))
.unwrap_or("<none>");
format!(
"scheme={scheme} has_separator={} extension={extension} len={}",
text.contains('/'),
text.chars().count()
)
}
fn observe(&mut self, line: &str) {
if !tracing::enabled!(target: FRAME_TRACE_TARGET, tracing::Level::DEBUG) {
return;
}
let Some(body) = line.strip_prefix("data:") else {
return;
};
let Ok(value) = serde_json::from_str::<Value>(body.trim()) else {
return;
};
let frame_type = value.get("type").and_then(|field| field.as_str());
let text = value.get("data").and_then(|field| field.as_str());
let streaming = value.get("streaming").and_then(|field| field.as_bool());
match (frame_type, text) {
(Some("session_id"), _) => *self = Self::default(),
(Some("plain"), Some(text)) if streaming == Some(true) => {
self.streamed.push_str(text);
}
(Some("plain"), Some(text)) if streaming == Some(false) => {
self.blocks.push(text.to_owned());
}
(Some("complete"), Some(final_text)) => self.report(final_text),
(Some("image" | "record" | "file" | "video"), Some(reference)) => {
tracing::debug!(
target: FRAME_TRACE_TARGET,
media_type = frame_type.unwrap_or("<absent>"),
reference = Self::reference_shape(reference).as_str(),
"astrbot media reference"
);
}
_ => {}
}
trace_frame_fields(&value);
}
/// Drops whitespace so a block differing only in line breaks still matches.
///
/// Exact containment could not separate "the same text formatted
/// differently" from "content the stream never carried": one capture had a
/// 278-character block against 286 streamed characters and reported no
/// containment either way.
fn squeezed(text: &str) -> String {
text.chars().filter(|c| !c.is_whitespace()).collect()
}
fn report(&self, final_text: &str) {
let repeated = self
.blocks
.iter()
.filter(|block| final_text.contains(block.as_str()))
.count();
let in_streamed = self
.blocks
.iter()
.filter(|block| self.streamed.contains(block.as_str()))
.count();
let squeezed_final = Self::squeezed(final_text);
let squeezed_repeated = self
.blocks
.iter()
.filter(|block| squeezed_final.contains(&Self::squeezed(block)))
.count();
let joined = self.blocks.concat();
tracing::debug!(
target: FRAME_TRACE_TARGET,
blocks = self.blocks.len(),
blocks_repeated_in_final = repeated,
blocks_repeated_in_stream = in_streamed,
blocks_repeated_ignoring_whitespace = squeezed_repeated,
streamed_len = self.streamed.chars().count(),
final_len = final_text.chars().count(),
blocks_len = joined.chars().count(),
final_is_last_block = self.blocks.last().is_some_and(|last| last == final_text),
"astrbot stream summary"
);
}
}
fn trace_frame_fields(value: &Value) {
let data = value.get("data");
let data_keys = match data {
Some(Value::Object(map)) => map.keys().cloned().collect::<Vec<_>>().join(","),
Some(Value::Array(_)) => "<array>".to_owned(),
Some(Value::String(_)) => "<string>".to_owned(),
Some(Value::Null) | None => "<none>".to_owned(),
Some(_) => "<scalar>".to_owned(),
};
let frame_type = value
.get("type")
.and_then(|field| field.as_str())
.unwrap_or("<absent>");
let has_message_id = value
.get("message_id")
.is_some_and(|field| !field.is_null());
// The *value* decides whether a reply that renders as two bubbles is one
// message the client split, or two messages the server sent. It is an
// opaque row identifier, not content.
let message_id = value
.get("message_id")
.and_then(|field| match field {
Value::String(text) => Some(text.clone()),
Value::Number(number) => Some(number.to_string()),
_ => None,
})
.unwrap_or_else(|| "<none>".to_owned());
// Length only. Distinguishes "the server streamed many small chunks" from
// "the server sent the whole reply at once" without recording any text.
let data_len = match value.get("data") {
Some(Value::String(text)) => text.chars().count(),
_ => 0,
};
let has_session_id = value
.get("session_id")
.is_some_and(|field| !field.is_null());
let streaming = value.get("streaming").and_then(|field| field.as_bool());
tracing::debug!(
target: FRAME_TRACE_TARGET,
frame_type,
has_message_id,
message_id = message_id.as_str(),
has_session_id,
?streaming,
data_keys = data_keys.as_str(),
data_len,
"astrbot sse frame"
);
}
/// Identifies an image from its leading bytes.
///
/// Only used when the server does not name a concrete image type. Every
/// signature here is a fixed format marker at a fixed offset, so this reads no
/// user content.
fn sniff_image_mime(bytes: &[u8]) -> Option<&'static str> {
const PNG: &[u8] = &[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A];
const JPEG: &[u8] = &[0xFF, 0xD8, 0xFF];
const GIF87: &[u8] = b"GIF87a";
const GIF89: &[u8] = b"GIF89a";
const BMP: &[u8] = b"BM";
if bytes.starts_with(PNG) {
return Some("image/png");
}
if bytes.starts_with(JPEG) {
return Some("image/jpeg");
}
if bytes.starts_with(GIF87) || bytes.starts_with(GIF89) {
return Some("image/gif");
}
if bytes.starts_with(BMP) {
return Some("image/bmp");
}
if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP" {
return Some("image/webp");
}
None
}
fn protocol_slot(slot: SlotKind) -> desktop_protocol::ActiveSlotKind {
match slot {
SlotKind::Companion => desktop_protocol::ActiveSlotKind::Companion,
SlotKind::Operations => desktop_protocol::ActiveSlotKind::Operations,
}
}
fn urlencoding_username(username: &str) -> String {
username
.chars()
.map(|ch| match ch {
'A'..='Z' | 'a'..='z' | '0'..='9' | '-' | '_' | '.' | '~' => ch.to_string(),
_ => format!("%{:02X}", ch as u8),
})
.collect()
}
fn jwt_is_expired(token: &str) -> bool {
let Some(payload) = token.split('.').nth(1).and_then(decode_base64url) else {
return false;
};
let Ok(value) = serde_json::from_slice::<Value>(&payload) else {
return false;
};
let Some(exp) = value.get("exp").and_then(Value::as_i64) else {
return false;
};
exp <= time::OffsetDateTime::now_utc().unix_timestamp()
}
fn decode_base64url(value: &str) -> Option<Vec<u8>> {
let mut output = Vec::with_capacity(value.len() * 3 / 4);
let mut buffer = 0u32;
let mut bits = 0u8;
for byte in value.bytes() {
let digit = match byte {
b'A'..=b'Z' => byte - b'A',
b'a'..=b'z' => byte - b'a' + 26,
b'0'..=b'9' => byte - b'0' + 52,
b'-' => 62,
b'_' => 63,
b'=' => break,
_ => return None,
};
buffer = (buffer << 6) | u32::from(digit);
bits += 6;
if bits >= 8 {
bits -= 8;
output.push((buffer >> bits) as u8);
buffer &= (1 << bits) - 1;
}
}
Some(output)
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Mutex;
#[derive(Clone, Default)]
struct CapturedLog(Arc<Mutex<Vec<u8>>>);
impl CapturedLog {
fn contents(&self) -> String {
String::from_utf8_lossy(&self.0.lock().expect("log lock")).into_owned()
}
}
impl std::io::Write for CapturedLog {
fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
self.0.lock().expect("log lock").extend_from_slice(buffer);
Ok(buffer.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl<'writer> tracing_subscriber::fmt::MakeWriter<'writer> for CapturedLog {
type Writer = CapturedLog;
fn make_writer(&'writer self) -> Self::Writer {
self.clone()
}
}
/// Guards the exact `RUST_LOG` value printed in the acceptance instructions.
///
/// The event sets an explicit target, so a filter naming the crate would not
/// reach it, and an `enabled!` guard using the default target would suppress
/// it even when the filter matched. Both are silent failures that would look
/// like "the app produced no logs".
#[test]
fn frame_trace_fires_under_the_documented_filter_and_leaks_no_payload() {
let sink = CapturedLog::default();
let subscriber = tracing_subscriber::fmt()
.without_time()
.with_ansi(false)
.with_env_filter(tracing_subscriber::EnvFilter::new("astrbot::frame=debug"))
.with_writer(sink.clone())
.finish();
let mut trace = FrameTrace::default();
tracing::subscriber::with_default(subscriber, || {
trace.observe(
r#"data: {"type":"plain","data":"你好","streaming":true,"message_id":"42"}"#,
);
trace.observe(r#"data: {"type":"image","data":{"url":"http://x/y.png"}}"#);
});
let output = sink.contents();
assert!(
output.contains("astrbot sse frame"),
"the documented filter must actually emit: {output}"
);
assert!(output.contains("frame_type=\"plain\""));
assert!(output.contains("has_message_id=true"));
// The value, and the chunk length, are what separate "one message the
// client split" from "two messages the server sent".
assert!(output.contains("message_id=\"42\""));
assert!(output.contains("data_len=2"));
assert!(output.contains("frame_type=\"image\""));
// The key names are what identify the plugin attachment shape.
assert!(output.contains("data_keys=\"url\""));
// No payload text, and no attachment URL, may reach the log.
assert!(!output.contains("\u{4f60}\u{597d}"), "payload text leaked");
assert!(!output.contains("y.png"), "attachment url leaked");
}
/// The summary must separate a block that repeats streamed text from one
/// that carries content of its own, because the two need opposite fixes.
#[test]
fn stream_summary_separates_repeated_blocks_from_distinct_ones() {
let sink = CapturedLog::default();
let subscriber = tracing_subscriber::fmt()
.without_time()
.with_ansi(false)
.with_env_filter(tracing_subscriber::EnvFilter::new("astrbot::frame=debug"))
.with_writer(sink.clone())
.finish();
let mut trace = FrameTrace::default();
tracing::subscriber::with_default(subscriber, || {
for line in [
r#"data: {"type":"session_id","session_id":"s1"}"#,
r#"data: {"type":"plain","data":"ALPHAWORD","streaming":true}"#,
// Repeats what the delta stream already carried.
r#"data: {"type":"plain","data":"ALPHAWORD","streaming":false}"#,
r#"data: {"type":"plain","data":"BETAWORD","streaming":true}"#,
// Carries content the stream never delivers.
r#"data: {"type":"plain","data":"GAMMAWORD","streaming":false}"#,
r#"data: {"type":"complete","data":"ALPHAWORDBETAWORD"}"#,
] {
trace.observe(line);
}
});
let output = sink.contents();
assert!(output.contains("astrbot stream summary"), "{output}");
assert!(output.contains("blocks=2"));
assert!(output.contains("blocks_repeated_in_final=1"));
assert!(output.contains("blocks_repeated_in_stream=1"));
assert!(output.contains("blocks_repeated_ignoring_whitespace=1"));
assert!(output.contains("streamed_len=17"));
assert!(output.contains("final_len=17"));
assert!(output.contains("blocks_len=18"));
for payload in ["ALPHAWORD", "BETAWORD", "GAMMAWORD"] {
assert!(
!output.contains(payload),
"payload {payload} leaked: {output}"
);
}
}
#[test]
fn image_bytes_are_identified_when_the_server_names_no_type() {
let png = [0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A, 0x00];
assert_eq!(sniff_image_mime(&png), Some("image/png"));
assert_eq!(
sniff_image_mime(&[0xFF, 0xD8, 0xFF, 0xE0]),
Some("image/jpeg")
);
assert_eq!(sniff_image_mime(b"GIF89a...."), Some("image/gif"));
assert_eq!(
sniff_image_mime(b"RIFF\0\0\0\0WEBPVP8 "),
Some("image/webp")
);
assert_eq!(sniff_image_mime(b"BM\0\0"), Some("image/bmp"));
// A JSON error body served with HTTP 200 must not be mistaken for one.
assert_eq!(sniff_image_mime(br#"{"status":"error"}"#), None);
assert_eq!(sniff_image_mime(b"<!DOCTYPE html>"), None);
assert_eq!(sniff_image_mime(b""), None);
}
/// A block that differs from the streamed text only in line breaks is the
/// same content, and must not be counted as content the stream never
/// carried. Exact containment says otherwise, which is why both are logged.
#[test]
fn stream_summary_sees_through_formatting_differences() {
let sink = CapturedLog::default();
let subscriber = tracing_subscriber::fmt()
.without_time()
.with_ansi(false)
.with_env_filter(tracing_subscriber::EnvFilter::new("astrbot::frame=debug"))
.with_writer(sink.clone())
.finish();
let mut trace = FrameTrace::default();
tracing::subscriber::with_default(subscriber, || {
for line in [
r#"data: {"type":"session_id","session_id":"s1"}"#,
r#"data: {"type":"plain","data":"ONE\nTWO","streaming":true}"#,
// Same words, different line breaks.
r#"data: {"type":"plain","data":"ONE TWO","streaming":false}"#,
r#"data: {"type":"complete","data":"ONE\nTWO"}"#,
] {
trace.observe(line);
}
});
let output = sink.contents();
assert!(output.contains("blocks_repeated_in_final=0"), "{output}");
assert!(
output.contains("blocks_repeated_ignoring_whitespace=1"),
"{output}"
);
}
#[test]
fn frame_trace_stays_silent_when_the_filter_excludes_it() {
let sink = CapturedLog::default();
let subscriber = tracing_subscriber::fmt()
.without_time()
.with_ansi(false)
.with_env_filter(tracing_subscriber::EnvFilter::new("info"))
.with_writer(sink.clone())
.finish();
let mut trace = FrameTrace::default();
tracing::subscriber::with_default(subscriber, || {
trace.observe(r#"data: {"type":"plain","message_id":"42"}"#);
});
assert!(sink.contents().is_empty());
}
#[test]
fn rejects_empty_api_key_and_username() {
let result = AstrBotClient::new(AstrBotClientConfig {
profile_id: "p".into(),
slot: SlotKind::Companion,
base_url: "http://127.0.0.1:1".into(),
api_key: SecretString::from(String::new()),
remote_username: "user".into(),
remote_display_name: None,
authentication_type: AuthenticationType::ApiKey,
session_id: None,
expected_server_instance_id: None,
});
assert!(matches!(result, Err(AstrBotClientError::InvalidConfig(_))));
}
#[test]
fn derives_identity_from_base_url() {
let client = AstrBotClient::new(AstrBotClientConfig {
profile_id: "p".into(),
slot: SlotKind::Companion,
base_url: "http://192.168.31.210:26285/".into(),
api_key: SecretString::from("abk_test".to_owned()),
remote_username: "desktop-companion".into(),
remote_display_name: Some("Desktop Companion".into()),
authentication_type: AuthenticationType::ApiKey,
session_id: Some("s1".into()),
expected_server_instance_id: None,
})
.expect("client");
assert!(client.server_instance_id_blocking().starts_with("astrbot-"));
}
#[test]
fn detects_expired_jwt_without_logging_or_exposing_the_token() {
assert!(jwt_is_expired("e30.eyJleHAiOjF9.signature"));
assert!(!jwt_is_expired("not-a-jwt"));
}
#[test]
fn line_buffer_keeps_multibyte_characters_split_across_chunks_intact() {
// "你好世界" is 12 UTF-8 bytes; cut in the middle of the second char.
let payload = "data: {\"type\":\"plain\",\"data\":\"你好世界\"}\n";
let bytes = payload.as_bytes();
let split = bytes
.iter()
.position(|byte| *byte == 0xE4)
.expect("payload contains a CJK lead byte")
+ 4;
assert!(
!payload.is_char_boundary(split),
"split must cut a character"
);
let mut buffer = SseLineBuffer::default();
buffer.push_chunk(&bytes[..split]);
assert!(
buffer.next_line().is_none(),
"an incomplete line must not be emitted"
);
buffer.push_chunk(&bytes[split..]);
let line = buffer
.next_line()
.expect("line completes on the second chunk");
assert!(!line.contains('\u{FFFD}'), "decoded line: {line}");
assert!(line.contains("你好世界"));
}
#[test]
fn line_buffer_strips_crlf_and_returns_the_trailing_line() {
let mut buffer = SseLineBuffer::default();
buffer.push_chunk(b"data: one\r\ndata: two\r\n");
assert_eq!(buffer.next_line().as_deref(), Some("data: one"));
assert_eq!(buffer.next_line().as_deref(), Some("data: two"));
assert_eq!(buffer.next_line(), None);
buffer.push_chunk(b"data: tail");
assert_eq!(buffer.next_line(), None);
assert_eq!(buffer.take_remainder().as_deref(), Some("data: tail"));
assert_eq!(buffer.take_remainder(), None);
}
#[test]
fn line_buffer_cursor_survives_interleaved_reads_and_writes() {
// The cursor is only compacted on push_chunk, so a partially drained
// buffer must still read correctly across the next chunk.
let mut buffer = SseLineBuffer::default();
buffer.push_chunk(b"a\nb\nc");
assert_eq!(buffer.next_line().as_deref(), Some("a"));
buffer.push_chunk(b"d\ne\n");
assert_eq!(buffer.next_line().as_deref(), Some("b"));
assert_eq!(buffer.next_line().as_deref(), Some("cd"));
assert_eq!(buffer.next_line().as_deref(), Some("e"));
assert_eq!(buffer.next_line(), None);
assert_eq!(buffer.take_remainder(), None);
}
#[test]
fn line_buffer_bounds_a_single_line_and_the_whole_response() {
let mut oversized_line = SseLineBuffer::default();
oversized_line.push_chunk(&vec![b'x'; MAX_SSE_LINE_BYTES + 1]);
assert!(oversized_line.is_overflowing());
// Consumed bytes still count towards the response ceiling, otherwise a
// server could stream forever in small well-formed lines: read_timeout
// never fires while bytes keep arriving, and there is no total timeout.
let mut long_response = SseLineBuffer::default();
let line = b"data: {}\n";
let repeats = (MAX_STREAM_BYTES as usize / line.len()) + 1;
for _ in 0..repeats {
long_response.push_chunk(line);
while long_response.next_line().is_some() {}
}
assert!(long_response.is_overflowing());
assert!(
long_response.bytes.len() < 1024,
"the buffer itself must stay small; only the counter grows"
);
}
}
/// End-to-end transport tests against a hand-rolled HTTP/1.1 SSE server.
///
/// A raw `TcpListener` is used instead of an HTTP framework on purpose: these
/// tests need byte-exact control over where the response body is split across
/// TCP writes, and the ability to drop the socket mid-body without sending the
/// terminal chunk. Neither is expressible through a normal server API.
#[cfg(test)]
mod stream_transport_tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
/// What the fake server does after it has written the scripted frames.
#[derive(Clone, Copy, PartialEq)]
enum Ending {
/// Send the terminal `0\r\n\r\n` chunk: a well-formed, complete body.
Complete,
/// Drop the socket without the terminal chunk, so the client sees a
/// truncated body rather than a clean end of stream.
Truncate,
/// Keep the connection open and silent, so only cancellation ends it.
HoldOpen,
}
struct FakeAstrBot {
base_url: String,
requests: Arc<AtomicUsize>,
}
/// Serves `chunks` as separate chunked-encoding frames with a pause between
/// them, which forces hyper to surface them as distinct stream items.
async fn spawn_fake(chunks: Vec<Vec<u8>>, ending: Ending) -> FakeAstrBot {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
let port = listener.local_addr().expect("addr").port();
let requests = Arc::new(AtomicUsize::new(0));
let counter = Arc::clone(&requests);
tokio::spawn(async move {
loop {
let Ok((mut socket, _)) = listener.accept().await else {
return;
};
let chunks = chunks.clone();
let counter = Arc::clone(&counter);
tokio::spawn(async move {
if read_request(&mut socket).await.is_none() {
return;
}
counter.fetch_add(1, Ordering::SeqCst);
let header = b"HTTP/1.1 200 OK\r\n\
Content-Type: text/event-stream\r\n\
Transfer-Encoding: chunked\r\n\r\n";
if socket.write_all(header).await.is_err() {
return;
}
for chunk in chunks {
let framed = format!("{:X}\r\n", chunk.len());
if socket.write_all(framed.as_bytes()).await.is_err()
|| socket.write_all(&chunk).await.is_err()
|| socket.write_all(b"\r\n").await.is_err()
|| socket.flush().await.is_err()
{
return;
}
// Guarantees the next frame lands in its own TCP read.
tokio::time::sleep(Duration::from_millis(60)).await;
}
match ending {
Ending::Complete => {
let _ = socket.write_all(b"0\r\n\r\n").await;
let _ = socket.flush().await;
}
Ending::Truncate => {
// Dropping without the terminal chunk makes hyper
// report an incomplete message.
let _ = socket.shutdown().await;
}
Ending::HoldOpen => {
tokio::time::sleep(Duration::from_secs(30)).await;
}
}
});
}
});
FakeAstrBot {
base_url: format!("http://127.0.0.1:{port}"),
requests,
}
}
/// Reads request headers plus any declared body so the client's write side
/// completes before the response is produced.
async fn read_request(socket: &mut tokio::net::TcpStream) -> Option<()> {
let mut raw = Vec::new();
let mut scratch = [0u8; 1024];
loop {
let read = socket.read(&mut scratch).await.ok()?;
if read == 0 {
return None;
}
raw.extend_from_slice(&scratch[..read]);
if let Some(index) = raw
.windows(4)
.position(|window| window == b"\r\n\r\n")
.map(|index| index + 4)
{
let headers = String::from_utf8_lossy(&raw[..index]).to_ascii_lowercase();
let length = headers
.lines()
.find_map(|line| line.strip_prefix("content-length:"))
.and_then(|value| value.trim().parse::<usize>().ok())
.unwrap_or(0);
let mut body = raw.len() - index;
while body < length {
let read = socket.read(&mut scratch).await.ok()?;
if read == 0 {
return None;
}
body += read;
}
return Some(());
}
}
}
fn client_for(base_url: &str) -> AstrBotClient {
AstrBotClient::new(AstrBotClientConfig {
profile_id: "profile-a".into(),
slot: SlotKind::Companion,
base_url: base_url.to_owned(),
api_key: SecretString::from("abk_test".to_owned()),
remote_username: "desktop-companion".into(),
remote_display_name: None,
authentication_type: AuthenticationType::ApiKey,
session_id: None,
expected_server_instance_id: None,
})
.expect("client")
}
fn drain(
receiver: &mut mpsc::Receiver<super::super::gateway_client::BoundGatewayEvent>,
) -> Vec<super::super::gateway_client::BoundGatewayEvent> {
let mut events = Vec::new();
while let Ok(event) = receiver.try_recv() {
events.push(event);
}
events
}
#[tokio::test]
async fn decodes_multibyte_text_split_across_tcp_chunks() {
// One SSE frame carrying CJK text, cut in the middle of a character.
let frame = "data: {\"type\":\"plain\",\"data\":\"你好,世界\"}\n\n";
let bytes = frame.as_bytes().to_vec();
let split = bytes
.iter()
.position(|byte| *byte == 0xE4)
.expect("CJK lead byte")
+ 1;
assert!(!frame.is_char_boundary(split), "split must cut a character");
let server = spawn_fake(
vec![bytes[..split].to_vec(), bytes[split..].to_vec()],
Ending::Complete,
)
.await;
let client = client_for(&server.base_url);
let (tx, mut rx) = mpsc::channel(64);
let cancellation = CancellationToken::new();
client
.send_chat_stream("hi", None, Vec::new(), &tx, &cancellation)
.await
.expect("stream completes");
let text = drain(&mut rx)
.iter()
.filter(|event| event.event_type == "message.completed")
.filter_map(|event| {
event
.payload
.get("content")
.and_then(Value::as_str)
.map(ToOwned::to_owned)
})
.collect::<String>();
assert!(!text.contains('\u{FFFD}'), "decoded content: {text}");
assert!(text.contains("你好,世界"), "decoded content: {text}");
}
#[tokio::test]
async fn truncated_body_reports_stream_interrupted_and_finalizes_the_message() {
let server = spawn_fake(
vec![b"data: {\"type\":\"plain\",\"data\":\"partial\"}\n\n".to_vec()],
Ending::Truncate,
)
.await;
let client = client_for(&server.base_url);
let (tx, mut rx) = mpsc::channel(64);
let cancellation = CancellationToken::new();
let error = client
.send_chat_stream("hi", None, Vec::new(), &tx, &cancellation)
.await
.expect_err("a truncated body must not look like success");
assert!(
matches!(error, AstrBotClientError::StreamInterrupted),
"the response had already started, so this must not be auto-retried: {error:?}"
);
let completed = drain(&mut rx)
.into_iter()
.find(|event| event.event_type == "message.completed")
.expect("the half-streamed message must be finalized, not left streaming");
assert_eq!(
completed
.payload
.get("finishReason")
.and_then(Value::as_str),
Some("error")
);
assert_eq!(
completed.payload.get("content").and_then(Value::as_str),
Some("partial"),
"text received before the break must be preserved"
);
}
/// A message whose reply had already started must never be re-sent:
/// `POST /api/v1/chat` carries no idempotency key, so a second attempt
/// appends the user's message to the remote conversation again.
#[tokio::test]
async fn a_broken_response_body_does_not_resend_the_chat_post() {
let server = spawn_fake(
vec![
b"data: {\"type\":\"plain\",\"data\":\"partial\"}
"
.to_vec(),
],
Ending::Truncate,
)
.await;
let client = client_for(&server.base_url);
let (tx, _rx) = mpsc::channel(64);
let cancellation = CancellationToken::new();
let _ = client
.send_chat_stream("hi", None, Vec::new(), &tx, &cancellation)
.await;
// Give any resend time to land before sampling.
tokio::time::sleep(Duration::from_millis(500)).await;
assert_eq!(server.requests.load(Ordering::SeqCst), 1);
}
#[tokio::test]
async fn cancellation_finalizes_the_message_as_cancelled() {
let server = spawn_fake(
vec![b"data: {\"type\":\"plain\",\"data\":\"half a rep\"}\n\n".to_vec()],
Ending::HoldOpen,
)
.await;
let client = client_for(&server.base_url);
let (tx, mut rx) = mpsc::channel(64);
let cancellation = CancellationToken::new();
let trigger = cancellation.clone();
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(400)).await;
trigger.cancel();
});
client
.send_chat_stream("hi", None, Vec::new(), &tx, &cancellation)
.await
.expect("cancellation is not a failure");
let completed = drain(&mut rx)
.into_iter()
.find(|event| event.event_type == "message.completed")
.expect("stopping generation must still finalize the message");
assert_eq!(
completed
.payload
.get("finishReason")
.and_then(Value::as_str),
Some("cancelled")
);
assert_eq!(
completed.payload.get("content").and_then(Value::as_str),
Some("half a rep"),
"content received before the stop must be kept"
);
}
}