AstrBot-Desktop/src-tauri/src/networking/astrbot_client.rs
YokiiroBW 5b518d1181
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
feat(chat): carry voice and other non-image attachments end to end
F-33. A voice reply produced nothing at all: no marker, no event, no
error. Four independent gates each dropped it, and fixing any one alone
would have changed nothing observable.

The mapper reached `map_media` for image, record, file and video alike,
but its only emitting branch was gated on the frame being an image, and
the `attachment_saved` fallback rejected every other type outright. Both
now carry whatever type arrived, with the frame type as the marker's alt
text so the renderer knows what to expect before any bytes exist.
`pending_media` was also a single slot, so a second attachment in one
reply overwrote the first before it was paired; it is a bounded queue
now, and an `attachment_saved` with no id no longer consumes the media
frame still waiting for one.

The download judged a candidate path successful only if the bytes sniffed
as an image — this server answers unknown paths with its own text under
HTTP 200, so sniffing is load-bearing and cannot simply be dropped.
Audio and video signatures are recognised now, and a declared
Content-Type is trusted when it names media rather than only images.
SILK is included deliberately: it is what AstrBot relays for QQ and
WeChat voice, no browser decodes it, and recognising it is what lets the
UI say so instead of rendering a player whose play button does nothing.

The CSP had no `media-src`, so it fell back to `default-src 'self'` and
an `<audio src="blob:">` was refused — in release builds only, since the
dev server serves no CSP at all. That is the same divergence as F-04 and
the inline-script trap in pet.html, so the policy now has a test of its
own that pins each directive the app depends on, including that
script-src still refuses inline.

The renderer chose `<img>` unconditionally. The element now follows the
media type of the bytes that actually arrived, falling back to the
marker's declared kind for the placeholder and the failure message.

`map_media` also kept a private copy of the message-id handling that
included the reopen-suffix overwrite fixed earlier in `adopt_message_id`;
it shares the one implementation now.

Protocol tests 22 -> 26, Rust client 99 -> 101, frontend 35 -> 43. All
six mutations of the new assertions were confirmed to fail.

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

1945 行
77 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;
/// Ceiling on a single downloaded attachment.
///
/// Enforced while reading rather than after: the body used to be read to
/// completion with `bytes()` and only then measured, so a server that answered
/// an image request with gigabytes — by fault or by design — was held in memory
/// in full before anything rejected it. Audio replies make this reachable in
/// ordinary use rather than only under attack, since they are far larger than
/// the stickers this path was built for.
const MAX_ATTACHMENT_BYTES: usize = 16 * 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();
// Current AstrBot serves both forms under `/api/v1/files`. By name
// first, because that is what a media frame carries; by id second,
// because markers already stored in history hold the id from
// `attachment_saved`. The `/api/chat/*` pair is what older builds
// exposed, kept last so an un-upgraded server still works.
for path in [
format!("/api/v1/files/content?filename={encoded}"),
format!("/api/v1/files/{encoded}/content"),
format!("/api/chat/get_file?filename={encoded}"),
format!("/api/chat/get_attachment?attachment_id={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();
// Rejected on the declared length first, which costs nothing when the
// server is honest. The streaming loop below is what actually holds the
// bound, because Content-Length is a claim and chunked responses make
// none at all.
if let Some(declared) = response.content_length()
&& declared > MAX_ATTACHMENT_BYTES as u64
{
return Ok(Err(format!(
"attachment declares {declared} bytes, over the {MAX_ATTACHMENT_BYTES} byte limit"
)));
}
let mut response = response;
let mut bytes: Vec<u8> = Vec::new();
while let Some(chunk) = response.chunk().await? {
if bytes.len() + chunk.len() > MAX_ATTACHMENT_BYTES {
return Ok(Err(format!(
"attachment exceeded the {MAX_ATTACHMENT_BYTES} byte limit while downloading"
)));
}
bytes.extend_from_slice(&chunk);
}
if bytes.is_empty() {
return Ok(Err("attachment response was empty".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_media_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 recognised media>"),
bytes = bytes.len(),
server_note = server_note.as_str(),
"astrbot attachment download"
);
match (declares_media(&header_mime), 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: AstrBotChatRequest::compose_message(message, &attachments),
session_id: session_id.clone(),
conversation_id: None,
username: Some(self.config.remote_username.clone()),
config_id,
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.
/// Whether a Content-Type is a media type worth trusting over the bytes.
///
/// Deliberately not "anything that is not an error": this server serves its own
/// dashboard HTML with HTTP 200 for an unknown path, and `application/json` for
/// an error envelope, so only an explicit media type may short-circuit the
/// sniffing below.
fn declares_media(header_mime: &str) -> bool {
let header_mime = header_mime.trim().to_ascii_lowercase();
header_mime.starts_with("image/")
|| header_mime.starts_with("audio/")
|| header_mime.starts_with("video/")
}
/// Recognises the media formats an AstrBot attachment can arrive as.
///
/// Sniffing is not a nicety here: this server answers an unknown path with its
/// own "404 Not found" text under HTTP 200, so the bytes are the only reliable
/// evidence that a candidate path produced an attachment at all. Audio matters
/// as much as image now that voice replies arrive as `record` attachments.
fn sniff_media_mime(bytes: &[u8]) -> Option<&'static str> {
if let Some(image) = sniff_image_mime(bytes) {
return Some(image);
}
sniff_audio_mime(bytes)
}
fn sniff_audio_mime(bytes: &[u8]) -> Option<&'static str> {
// RIFF is shared with WEBP, so the form tag at byte 8 decides. Checked here
// as well as in the image sniffer because either may run first.
if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WAVE" {
return Some("audio/wav");
}
if bytes.starts_with(b"OggS") {
return Some("audio/ogg");
}
if bytes.starts_with(b"fLaC") {
return Some("audio/flac");
}
if bytes.starts_with(b"ID3") {
return Some("audio/mpeg");
}
// MPEG audio frame sync: eleven set bits, then a valid layer.
if bytes.len() >= 2 && bytes[0] == 0xFF && matches!(bytes[1] & 0xF6, 0xF2 | 0xF4 | 0xF6) {
return Some("audio/mpeg");
}
if bytes.starts_with(b"#!AMR") {
return Some("audio/amr");
}
// SILK, with and without the single-byte prefix the QQ and WeChat platforms
// put in front of it. AstrBot relays voice from those platforms, and a
// browser cannot decode it — recognising it is what lets the UI say so
// rather than showing an empty player.
if bytes.starts_with(b"#!SILK") || (bytes.len() > 6 && bytes[1..].starts_with(b"#!SILK")) {
return Some("audio/silk");
}
if bytes.len() >= 12 && &bytes[4..8] == b"ftyp" {
return match &bytes[8..12] {
b"M4A " | b"M4B " => Some("audio/mp4"),
_ => Some("video/mp4"),
};
}
None
}
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);
}
/// Audio has to be recognised for the same reason images do: this server
/// answers an unknown path with its own text under HTTP 200, so the bytes are
/// the only evidence a candidate path produced an attachment.
#[test]
fn audio_bytes_are_identified_when_the_server_names_no_type() {
assert_eq!(sniff_media_mime(b"RIFF\0\0\0\0WAVEfmt "), Some("audio/wav"));
assert_eq!(sniff_media_mime(b"OggS\0\x02"), Some("audio/ogg"));
assert_eq!(sniff_media_mime(b"fLaC\0\0"), Some("audio/flac"));
assert_eq!(sniff_media_mime(b"ID3\x03\0"), Some("audio/mpeg"));
assert_eq!(
sniff_media_mime(&[0xFF, 0xFB, 0x90, 0x00]),
Some("audio/mpeg")
);
assert_eq!(sniff_media_mime(b"#!AMR\n"), Some("audio/amr"));
assert_eq!(sniff_media_mime(b"\0\0\0\x18ftypM4A "), Some("audio/mp4"));
assert_eq!(sniff_media_mime(b"\0\0\0\x18ftypisom"), Some("video/mp4"));
// RIFF is shared with WEBP, so the form tag decides which it is.
assert_eq!(
sniff_media_mime(b"RIFF\0\0\0\0WEBPVP8 "),
Some("image/webp")
);
// SILK is what AstrBot relays for QQ and WeChat voice, with and without
// the platform's one-byte prefix. Recognising it is what lets the UI say
// no browser can play it instead of rendering a dead player.
assert_eq!(sniff_media_mime(b"#!SILK_V3"), Some("audio/silk"));
assert_eq!(sniff_media_mime(b"\x02#!SILK_V3"), Some("audio/silk"));
assert_eq!(sniff_media_mime(b"<!DOCTYPE html>"), None);
assert_eq!(sniff_media_mime(b""), None);
}
/// Only an explicit media type may skip the sniffing.
#[test]
fn a_declared_type_is_trusted_only_when_it_names_media() {
assert!(declares_media("image/png"));
assert!(declares_media("audio/wav"));
assert!(declares_media("AUDIO/OGG"));
assert!(declares_media("video/mp4"));
// The shapes this server actually returns for "not here".
assert!(!declares_media("text/html"));
assert!(!declares_media("application/json"));
assert!(!declares_media("application/octet-stream"));
assert!(!declares_media(""));
}
/// 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(());
}
}
}
/// Serves an attachment response of `chunks` 512 KiB frames, counting how
/// many it managed to write. A client that stops reading once its ceiling is
/// reached makes the later writes fail, so the count is the evidence that the
/// download was bounded while it ran rather than measured after the fact.
async fn spawn_oversized_attachment(
chunks: usize,
declared_length: Option<usize>,
) -> (String, Arc<AtomicUsize>) {
let listener = TcpListener::bind("127.0.0.1:0").await.expect("bind");
let port = listener.local_addr().expect("addr").port();
let written = Arc::new(AtomicUsize::new(0));
let counter = Arc::clone(&written);
tokio::spawn(async move {
loop {
let Ok((mut socket, _)) = listener.accept().await else {
return;
};
let counter = Arc::clone(&counter);
tokio::spawn(async move {
if read_request(&mut socket).await.is_none() {
return;
}
// `Connection: close` with no length at all: hyper reads the
// body until EOF. Chosen over chunked framing so the fake
// server has no framing of its own that could fail and be
// mistaken for the guard under test.
let header = match declared_length {
Some(length) => format!(
"HTTP/1.1 200 OK\r\nContent-Type: image/png\r\nContent-Length: {length}\r\n\r\n"
),
None => "HTTP/1.1 200 OK\r\nContent-Type: image/png\r\nConnection: close\r\n\r\n"
.to_owned(),
};
if socket.write_all(header.as_bytes()).await.is_err() {
return;
}
let block = vec![b'x'; 512 * 1024];
for _ in 0..chunks {
if socket.write_all(&block).await.is_err() || socket.flush().await.is_err()
{
return;
}
counter.fetch_add(1, Ordering::SeqCst);
}
let _ = socket.shutdown().await;
});
}
});
(format!("http://127.0.0.1:{port}"), written)
}
/// A body larger than the ceiling is refused without being held in full.
///
/// F-70. `bytes()` read the whole response before anything measured it, so a
/// server answering with gigabytes was buffered entirely first.
#[tokio::test]
async fn an_oversized_attachment_is_refused_while_it_downloads() {
// 48 MiB offered against a 16 MiB ceiling, chunked so no length is
// declared and only the reading loop can stop it.
let (base_url, written) = spawn_oversized_attachment(96, None).await;
let client = client_for(&base_url);
let error = client
.download_attachment("huge.png")
.await
.expect_err("must refuse");
assert!(
error.to_string().contains("while downloading"),
"expected the streaming guard to trip, got {error:?}"
);
// Four candidate paths are tried, so a client that read every response in
// full would have let the server write 4 * 96 frames.
let frames = written.load(Ordering::SeqCst);
assert!(
frames < 4 * 96,
"the client read every offered frame: {frames}"
);
}
/// A declared length over the ceiling is refused before the body is read.
#[tokio::test]
async fn an_attachment_declaring_an_oversized_length_is_refused_up_front() {
let (base_url, written) = spawn_oversized_attachment(96, Some(96 * 512 * 1024)).await;
let client = client_for(&base_url);
let error = client
.download_attachment("huge.png")
.await
.expect_err("must refuse");
assert!(
error.to_string().contains("declares"),
"expected the declared-length guard, got {error}"
);
// Nothing of the body should have been consumed, so the server's writes
// block or fail almost immediately.
assert!(
written.load(Ordering::SeqCst) < 4 * 96,
"{}",
written.load(Ordering::SeqCst)
);
}
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"
);
}
}