518 行
18 KiB
Rust
518 行
18 KiB
Rust
//! Real AstrBot OpenAPI/Dashboard wire types and SSE frame mapping.
|
|
//!
|
|
//! The provisional Desktop Gateway contract remains the internal normalized
|
|
//! model. This module translates observed AstrBot `/api/v1` chat SSE frames
|
|
//! into that model without claiming full product compatibility.
|
|
|
|
use serde::{Deserialize, Serialize};
|
|
use serde_json::Value;
|
|
use thiserror::Error;
|
|
|
|
use crate::{
|
|
EventMetadata, FinishReason, GatewayErrorPayload, GatewayEvent, GatewayEventBody,
|
|
HeartbeatPayload, MessageCompletedPayload, MessageDeltaPayload,
|
|
};
|
|
|
|
/// Wire transport used by a connection profile.
|
|
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
|
|
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
|
|
#[serde(rename_all = "kebab-case")]
|
|
pub enum TransportKind {
|
|
/// Provisional Mock / future Desktop Gateway (`/desktop/v1`).
|
|
#[default]
|
|
DesktopV1,
|
|
/// Real AstrBot OpenAPI surface (`/api/v1`).
|
|
AstrBotOpenApi,
|
|
}
|
|
|
|
impl TransportKind {
|
|
pub fn as_str(self) -> &'static str {
|
|
match self {
|
|
Self::DesktopV1 => "desktop-v1",
|
|
Self::AstrBotOpenApi => "astrbot-openapi",
|
|
}
|
|
}
|
|
|
|
pub fn parse(value: &str) -> Option<Self> {
|
|
match value {
|
|
"desktop-v1" => Some(Self::DesktopV1),
|
|
"astrbot-openapi" => Some(Self::AstrBotOpenApi),
|
|
_ => None,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// JSON envelope used by most AstrBot dashboard/OpenAPI JSON responses.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct AstrBotApiEnvelope<T> {
|
|
pub status: String,
|
|
#[serde(default)]
|
|
pub message: Option<String>,
|
|
#[serde(default)]
|
|
pub data: Option<T>,
|
|
}
|
|
|
|
impl<T> AstrBotApiEnvelope<T> {
|
|
pub fn is_ok(&self) -> bool {
|
|
self.status.eq_ignore_ascii_case("ok")
|
|
}
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotChatRequest {
|
|
pub message: Value,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub session_id: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub conversation_id: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub username: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub nickname: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub config_id: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub attachments: Option<Vec<AstrBotAttachment>>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub platform_id: Option<String>,
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub enable_streaming: Option<bool>,
|
|
}
|
|
|
|
/// A model/provider configuration exposed by AstrBot.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotModelOption {
|
|
pub id: String,
|
|
#[serde(default)]
|
|
pub name: Option<String>,
|
|
#[serde(default)]
|
|
pub is_default: Option<bool>,
|
|
}
|
|
|
|
/// Normalized attachment returned by the Rust upload boundary.
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct AstrBotAttachment {
|
|
pub attachment_id: String,
|
|
pub file_name: String,
|
|
pub mime_type: String,
|
|
pub size_bytes: u64,
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub url: Option<String>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct AstrBotCapabilitySnapshot {
|
|
pub transport: String,
|
|
pub text_chat: bool,
|
|
pub streaming: bool,
|
|
pub model_selection: bool,
|
|
pub file_upload: bool,
|
|
pub image_input: bool,
|
|
pub models: Vec<AstrBotModelOption>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotSessionListData {
|
|
#[serde(default)]
|
|
pub sessions: Vec<AstrBotSessionSummary>,
|
|
#[serde(default)]
|
|
pub page: Option<u64>,
|
|
#[serde(default)]
|
|
pub page_size: Option<u64>,
|
|
#[serde(default)]
|
|
pub total: Option<u64>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotSessionSummary {
|
|
pub session_id: String,
|
|
#[serde(default)]
|
|
pub platform_id: Option<String>,
|
|
#[serde(default)]
|
|
pub creator: Option<String>,
|
|
#[serde(default)]
|
|
pub display_name: Option<String>,
|
|
#[serde(default)]
|
|
pub is_group: Option<i64>,
|
|
#[serde(default)]
|
|
pub created_at: Option<String>,
|
|
#[serde(default)]
|
|
pub updated_at: Option<String>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotConfigListData {
|
|
#[serde(default)]
|
|
pub configs: Vec<AstrBotConfigSummary>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotConfigSummary {
|
|
pub id: String,
|
|
#[serde(default)]
|
|
pub name: Option<String>,
|
|
#[serde(default)]
|
|
pub path: Option<String>,
|
|
#[serde(default)]
|
|
pub is_default: Option<bool>,
|
|
}
|
|
|
|
/// One decoded SSE unit from an AstrBot chat stream.
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum AstrBotSseUnit {
|
|
HeartbeatComment,
|
|
Json(AstrBotStreamFrame),
|
|
Ignored,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
|
|
pub struct AstrBotStreamFrame {
|
|
#[serde(rename = "type")]
|
|
pub frame_type: String,
|
|
#[serde(default)]
|
|
pub data: Value,
|
|
#[serde(default)]
|
|
pub session_id: Option<String>,
|
|
#[serde(default)]
|
|
pub streaming: Option<bool>,
|
|
#[serde(default)]
|
|
pub chain_type: Option<Value>,
|
|
#[serde(default)]
|
|
pub message_id: Option<String>,
|
|
}
|
|
|
|
#[derive(Debug, Error)]
|
|
pub enum AstrBotMapError {
|
|
#[error("invalid astrbot sse json: {0}")]
|
|
Json(#[from] serde_json::Error),
|
|
}
|
|
|
|
/// Parses a single SSE line (not including the blank separator).
|
|
pub fn parse_astrbot_sse_line(line: &str) -> Result<AstrBotSseUnit, AstrBotMapError> {
|
|
let trimmed = line.trim_end_matches('\r');
|
|
if trimmed.is_empty() {
|
|
return Ok(AstrBotSseUnit::Ignored);
|
|
}
|
|
if trimmed.starts_with(':') {
|
|
// AstrBot heartbeats are comment frames: ": heartbeat"
|
|
return Ok(AstrBotSseUnit::HeartbeatComment);
|
|
}
|
|
if let Some(data) = trimmed.strip_prefix("data:") {
|
|
let payload = data.trim_start();
|
|
if payload.is_empty() {
|
|
return Ok(AstrBotSseUnit::Ignored);
|
|
}
|
|
let frame: AstrBotStreamFrame = serde_json::from_str(payload)?;
|
|
return Ok(AstrBotSseUnit::Json(frame));
|
|
}
|
|
// event:/id: fields are currently unused by AstrBot chat streams.
|
|
Ok(AstrBotSseUnit::Ignored)
|
|
}
|
|
|
|
/// Stateful mapper that turns AstrBot chat SSE frames into Desktop Gateway events.
|
|
#[derive(Debug, Default)]
|
|
pub struct AstrBotStreamMapper {
|
|
server_instance_id: String,
|
|
session_id: Option<String>,
|
|
active_message_id: Option<String>,
|
|
accumulated: String,
|
|
delta_index: u32,
|
|
sequence: u64,
|
|
saw_assistant_delta: bool,
|
|
}
|
|
|
|
impl AstrBotStreamMapper {
|
|
pub fn new(server_instance_id: impl Into<String>) -> Self {
|
|
Self {
|
|
server_instance_id: server_instance_id.into(),
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
pub fn session_id(&self) -> Option<&str> {
|
|
self.session_id.as_deref()
|
|
}
|
|
|
|
pub fn push_line(&mut self, line: &str) -> Result<Vec<GatewayEvent>, AstrBotMapError> {
|
|
match parse_astrbot_sse_line(line)? {
|
|
AstrBotSseUnit::Ignored => Ok(Vec::new()),
|
|
AstrBotSseUnit::HeartbeatComment => Ok(vec![self.heartbeat_event()]),
|
|
AstrBotSseUnit::Json(frame) => Ok(self.map_frame(frame)),
|
|
}
|
|
}
|
|
|
|
/// Call when the HTTP stream ends without a terminal server frame.
|
|
pub fn finish_stream(&mut self) -> Vec<GatewayEvent> {
|
|
self.complete_if_needed(FinishReason::Stop)
|
|
}
|
|
|
|
fn map_frame(&mut self, frame: AstrBotStreamFrame) -> Vec<GatewayEvent> {
|
|
match frame.frame_type.as_str() {
|
|
"session_id" => {
|
|
if let Some(session_id) = frame
|
|
.session_id
|
|
.clone()
|
|
.filter(|value| !value.trim().is_empty())
|
|
{
|
|
self.session_id = Some(session_id);
|
|
} else if let Some(session_id) = string_from_value(&frame.data) {
|
|
self.session_id = Some(session_id);
|
|
}
|
|
Vec::new()
|
|
}
|
|
"user_message_saved" => Vec::new(),
|
|
"plain" => self.map_plain(frame),
|
|
"agent_stats" => {
|
|
let detail = frame.data.to_string();
|
|
vec![self.event(
|
|
frame.message_id.clone(),
|
|
GatewayEventBody::AgentStatus(crate::AgentStatusPayload {
|
|
state: "running".into(),
|
|
detail: Some(detail),
|
|
}),
|
|
)]
|
|
}
|
|
"run_snapshot" => {
|
|
vec![self.event(
|
|
frame.message_id.clone(),
|
|
GatewayEventBody::AgentStatus(crate::AgentStatusPayload {
|
|
state: "snapshot".into(),
|
|
detail: Some(frame.data.to_string()),
|
|
}),
|
|
)]
|
|
}
|
|
"message_saved" | "end" => self.complete_if_needed(FinishReason::Stop),
|
|
"error" => {
|
|
let mut events = self.complete_if_needed(FinishReason::Error);
|
|
let message = string_from_value(&frame.data)
|
|
.unwrap_or_else(|| "AstrBot stream error".to_owned());
|
|
events.push(self.event(
|
|
frame.message_id,
|
|
GatewayEventBody::Error(GatewayErrorPayload {
|
|
code: "astrbotStreamError".into(),
|
|
message,
|
|
retryable: true,
|
|
}),
|
|
));
|
|
events
|
|
}
|
|
"attachment_saved" => Vec::new(),
|
|
_ => Vec::new(),
|
|
}
|
|
}
|
|
|
|
fn map_plain(&mut self, frame: AstrBotStreamFrame) -> Vec<GatewayEvent> {
|
|
let chunk = string_from_value(&frame.data).unwrap_or_default();
|
|
if chunk.is_empty() && frame.streaming.unwrap_or(false) {
|
|
// Keep empty streaming markers out of the UI unless they carry text.
|
|
return Vec::new();
|
|
}
|
|
if let Some(message_id) = frame.message_id.clone() {
|
|
if self
|
|
.active_message_id
|
|
.as_ref()
|
|
.is_some_and(|current| current != &message_id)
|
|
{
|
|
// New assistant message id: complete the previous accumulation first.
|
|
let mut events = self.complete_if_needed(FinishReason::Stop);
|
|
self.active_message_id = Some(message_id);
|
|
self.accumulated.clear();
|
|
self.delta_index = 0;
|
|
self.saw_assistant_delta = false;
|
|
events.extend(self.emit_delta(chunk));
|
|
return events;
|
|
}
|
|
self.active_message_id = Some(message_id);
|
|
}
|
|
self.emit_delta(chunk)
|
|
}
|
|
|
|
fn emit_delta(&mut self, chunk: String) -> Vec<GatewayEvent> {
|
|
if chunk.is_empty() {
|
|
return Vec::new();
|
|
}
|
|
self.accumulated.push_str(&chunk);
|
|
self.saw_assistant_delta = true;
|
|
let index = self.delta_index;
|
|
self.delta_index = self.delta_index.saturating_add(1);
|
|
vec![self.event(
|
|
self.active_message_id.clone(),
|
|
GatewayEventBody::MessageDelta(MessageDeltaPayload {
|
|
delta: chunk,
|
|
index,
|
|
}),
|
|
)]
|
|
}
|
|
|
|
fn complete_if_needed(&mut self, reason: FinishReason) -> Vec<GatewayEvent> {
|
|
if !self.saw_assistant_delta && self.accumulated.is_empty() {
|
|
return Vec::new();
|
|
}
|
|
let content = std::mem::take(&mut self.accumulated);
|
|
self.saw_assistant_delta = false;
|
|
self.delta_index = 0;
|
|
let message_id = self.active_message_id.clone();
|
|
vec![self.event(
|
|
message_id,
|
|
GatewayEventBody::MessageCompleted(MessageCompletedPayload {
|
|
finish_reason: reason,
|
|
content: Some(content),
|
|
}),
|
|
)]
|
|
}
|
|
|
|
fn heartbeat_event(&mut self) -> GatewayEvent {
|
|
self.event(
|
|
None,
|
|
GatewayEventBody::Heartbeat(HeartbeatPayload { interval_ms: 1_000 }),
|
|
)
|
|
}
|
|
|
|
fn event(&mut self, message_id: Option<String>, body: GatewayEventBody) -> GatewayEvent {
|
|
self.sequence = self.sequence.saturating_add(1);
|
|
let event_id = format!("astrbot-{}-{}", self.server_instance_id, self.sequence);
|
|
let mut metadata = EventMetadata::new(
|
|
event_id,
|
|
self.server_instance_id.clone(),
|
|
current_timestamp(),
|
|
self.sequence,
|
|
);
|
|
metadata.session_id = self.session_id.clone();
|
|
metadata.conversation_id = self.session_id.clone();
|
|
metadata.message_id = message_id.or_else(|| self.active_message_id.clone());
|
|
GatewayEvent { metadata, body }
|
|
}
|
|
}
|
|
|
|
fn string_from_value(value: &Value) -> Option<String> {
|
|
match value {
|
|
Value::Null => None,
|
|
Value::String(text) => Some(text.clone()),
|
|
Value::Number(number) => Some(number.to_string()),
|
|
Value::Bool(flag) => Some(flag.to_string()),
|
|
other => Some(other.to_string()),
|
|
}
|
|
}
|
|
|
|
fn current_timestamp() -> String {
|
|
// Protocol timestamps are opaque strings for consumers; keep a stable UTC-like form
|
|
// without adding a time dependency to the protocol crate.
|
|
"1970-01-01T00:00:00Z".into()
|
|
}
|
|
|
|
/// Derives a stable local server identity substitute when AstrBot has no server-info API.
|
|
pub fn derive_astrbot_server_instance_id(base_url: &str) -> String {
|
|
use std::hash::{Hash, Hasher};
|
|
let normalized = base_url.trim().trim_end_matches('/').to_ascii_lowercase();
|
|
let mut hasher = std::collections::hash_map::DefaultHasher::new();
|
|
normalized.hash(&mut hasher);
|
|
format!("astrbot-{:016x}", hasher.finish())
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn maps_live_probe_style_plain_stream() {
|
|
let mut mapper = AstrBotStreamMapper::new("astrbot-test");
|
|
let lines = [
|
|
r#"data: {"type": "session_id", "data": null, "session_id": "desktop-companion-s1"}"#,
|
|
r#"data: {"type": "user_message_saved", "data": {"id": 1}}"#,
|
|
": heartbeat",
|
|
r#"data: {"type": "plain", "data": "Hello", "streaming": true, "message_id": "m1"}"#,
|
|
r#"data: {"type": "plain", "data": "!", "streaming": true, "message_id": "m1"}"#,
|
|
];
|
|
|
|
let mut events = Vec::new();
|
|
for line in lines {
|
|
events.extend(mapper.push_line(line).expect("parse"));
|
|
}
|
|
events.extend(mapper.finish_stream());
|
|
|
|
assert_eq!(mapper.session_id(), Some("desktop-companion-s1"));
|
|
assert!(
|
|
events
|
|
.iter()
|
|
.any(|event| event.body.event_type() == "system.heartbeat")
|
|
);
|
|
let deltas: Vec<_> = events
|
|
.iter()
|
|
.filter_map(|event| match &event.body {
|
|
GatewayEventBody::MessageDelta(payload) => Some(payload.delta.as_str()),
|
|
_ => None,
|
|
})
|
|
.collect();
|
|
assert_eq!(deltas, ["Hello", "!"]);
|
|
let completed = events
|
|
.iter()
|
|
.find_map(|event| match &event.body {
|
|
GatewayEventBody::MessageCompleted(payload) => payload.content.clone(),
|
|
_ => None,
|
|
})
|
|
.expect("completed");
|
|
assert_eq!(completed, "Hello!");
|
|
assert_eq!(
|
|
events.last().map(|e| e.body.event_type()),
|
|
Some("message.completed")
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn maps_error_frames() {
|
|
let mut mapper = AstrBotStreamMapper::new("astrbot-test");
|
|
let events = mapper
|
|
.push_line(r#"data: {"type":"error","data":"provider missing"}"#)
|
|
.expect("parse");
|
|
assert_eq!(events.len(), 1);
|
|
match &events[0].body {
|
|
GatewayEventBody::Error(error) => {
|
|
assert_eq!(error.code, "astrbotStreamError");
|
|
assert!(error.message.contains("provider missing"));
|
|
}
|
|
other => panic!("unexpected {other:?}"),
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn derives_stable_instance_ids() {
|
|
let a = derive_astrbot_server_instance_id("http://192.168.31.210:26285/");
|
|
let b = derive_astrbot_server_instance_id("http://192.168.31.210:26285");
|
|
let c = derive_astrbot_server_instance_id("http://192.168.31.210:26286");
|
|
assert_eq!(a, b);
|
|
assert_ne!(a, c);
|
|
assert!(a.starts_with("astrbot-"));
|
|
}
|
|
|
|
#[test]
|
|
fn chat_request_serializes_model_and_attachment_options() {
|
|
let request = AstrBotChatRequest {
|
|
message: Value::String("hello".into()),
|
|
session_id: Some("session-a".into()),
|
|
conversation_id: None,
|
|
username: Some("desktop".into()),
|
|
nickname: None,
|
|
config_id: Some("model-a".into()),
|
|
attachments: Some(vec![AstrBotAttachment {
|
|
attachment_id: "file-a".into(),
|
|
file_name: "image.png".into(),
|
|
mime_type: "image/png".into(),
|
|
size_bytes: 12,
|
|
url: None,
|
|
}]),
|
|
platform_id: None,
|
|
enable_streaming: Some(true),
|
|
};
|
|
let value = serde_json::to_value(request).expect("request serializes");
|
|
assert_eq!(value["config_id"], "model-a");
|
|
assert_eq!(value["attachments"][0]["attachmentId"], "file-a");
|
|
}
|
|
|
|
#[test]
|
|
fn protocol_version_constant_is_unchanged_for_internal_model() {
|
|
assert_eq!(crate::PROTOCOL_VERSION, "desktop-v1alpha1");
|
|
}
|
|
}
|