//! 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 { 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 { pub status: String, #[serde(default)] pub message: Option, #[serde(default)] pub data: Option, } impl AstrBotApiEnvelope { 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, #[serde(skip_serializing_if = "Option::is_none")] pub conversation_id: Option, #[serde(skip_serializing_if = "Option::is_none")] pub username: Option, #[serde(skip_serializing_if = "Option::is_none")] pub config_id: Option, #[serde(skip_serializing_if = "Option::is_none")] pub platform_id: Option, #[serde(skip_serializing_if = "Option::is_none")] pub enable_streaming: Option, } #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] pub struct AstrBotSessionListData { #[serde(default)] pub sessions: Vec, #[serde(default)] pub page: Option, #[serde(default)] pub page_size: Option, #[serde(default)] pub total: Option, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct AstrBotSessionSummary { pub session_id: String, #[serde(default)] pub platform_id: Option, #[serde(default)] pub creator: Option, #[serde(default)] pub display_name: Option, #[serde(default)] pub is_group: Option, #[serde(default)] pub created_at: Option, #[serde(default)] pub updated_at: Option, } #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] pub struct AstrBotConfigListData { #[serde(default)] pub configs: Vec, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct AstrBotConfigSummary { pub id: String, #[serde(default)] pub name: Option, #[serde(default)] pub path: Option, #[serde(default)] pub is_default: Option, } /// 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, #[serde(default)] pub streaming: Option, #[serde(default)] pub chain_type: Option, #[serde(default)] pub message_id: Option, } #[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 { 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, active_message_id: Option, accumulated: String, delta_index: u32, sequence: u64, saw_assistant_delta: bool, } impl AstrBotStreamMapper { pub fn new(server_instance_id: impl Into) -> 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, 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 { self.complete_if_needed(FinishReason::Stop) } fn map_frame(&mut self, frame: AstrBotStreamFrame) -> Vec { 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 { 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 { 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 { 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, 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 { 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 protocol_version_constant_is_unchanged_for_internal_model() { assert_eq!(crate::PROTOCOL_VERSION, "desktop-v1alpha1"); } }