AstrBot-Desktop/src-tauri/src/networking/astrbot_client.rs
YokiiroBW e01cb5a3ba feat(astrbot): trace sse frame shapes at debug level
Two reported defects cannot be diagnosed from the code alone. A reply
sometimes renders as two bubbles during generation, which happens when a
streaming frame carries no message_id — the client then keys it by
event_id, which is unique per event. And images sent by plugins never
appear, which happens when an image frame is not followed by the
attachment_saved frame the mapper waits for. Both depend on what the
server actually sends, and picking the wrong one would produce a fix
that looks right until another conversation path hits the other.

Log the shape of every SSE frame: its type, whether message_id and
session_id are present, the streaming flag, and the key names inside
data. No payload text is recorded, so this is safe to leave enabled in
the field. Off unless RUST_LOG selects debug, and gated on
tracing::enabled! so a disabled level costs one atomic read rather than
a JSON parse.

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

1254 行
48 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/file"))
.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),
})
}
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 response = self
.http
.get(self.url(&format!("/api/v1/files/{attachment_id}/content")))
.send()
.await?;
if response.status().as_u16() == 401 || response.status().as_u16() == 403 {
return Err(AstrBotClientError::HttpStatus(response.status()));
}
if !response.status().is_success() {
return Err(AstrBotClientError::HttpStatus(response.status()));
}
let mime_type = response
.headers()
.get(CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.split(';').next())
.filter(|value| !value.trim().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 Err(AstrBotClientError::InvalidConfig(
"attachment size is outside the supported range",
));
}
Ok((mime_type, bytes))
}
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);
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_frame_shape(&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_frame_shape(&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(())
}
}
/// Records the *shape* of one SSE frame at debug level.
///
/// Deliberately logs no payload text — only the frame type, which identity
/// fields are present, and the key names inside `data`. That is enough to
/// answer the two questions the mapper cannot answer on its own: whether every
/// streaming frame carries a `message_id` (if not, the client cannot key a
/// reply to a single message and splits it), and what shape a plugin's
/// attachment frames actually take.
///
/// Enable with `RUST_LOG=astrbot_desktop=debug`. Off by default.
fn trace_frame_shape(line: &str) {
if !tracing::enabled!(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 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());
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: "astrbot::frame",
frame_type,
has_message_id,
has_session_id,
?streaming,
data_keys = data_keys.as_str(),
"astrbot sse frame"
);
}
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::*;
#[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"
);
}
}