Skip to main content

acosmi/core/
sanitize_bridge.rs

1//! sanitize_bridge — 端口自 `acosmi-sdk-ts/src/core/sanitize-bridge.ts`
2//! (其本身端口自 `acosmi-sdk-go/sanitize_bridge.go`)。
3//!
4//! 主包与 sanitize 子包的胶水层。sanitize 子包定义了与 provider 无关的 block 处理工具,
5//! 不依赖主包;本文件把 [`ChatRequest`] 这种主包类型归一化为 sanitize 能处理的
6//! `Vec<Value>` 形态,并提供 Client 级别的可配置钩子([`Client::set_defensive_sanitize`] /
7//! [`Client::set_auto_strip_ephemeral_history`])。
8//!
9//! 调用时机:`build_chat_request` 开头(每次 chat/chat_stream/chat_messages*)。
10//! 未配置时零开销(`Client::apply_request_sanitizers`(内部)首行 early-return)。
11//!
12//! feature `sanitize` 门控(默认开)。
13
14use super::client::Client;
15use crate::models::types::ChatRequest;
16use crate::sanitize::{sanitize, strip_ephemeral, MinimalSanitizeConfig, SanitizeError};
17use crate::shared::Result;
18use serde_json::Value;
19
20impl Client {
21    /// 配置请求前的底线防御(体积 / deny-list / 深度)。传 `None`(或空 cfg `is_empty()`)
22    /// 关闭。并发安全,可在任意时间调用。对应 TS `setDefensiveSanitize`。
23    ///
24    /// TS 侧传 `{}`(全零字段)即关闭;Rust 侧将空 cfg 归一为 `None`(等价语义 + 维持
25    /// `apply_request_sanitizers` 的零开销 early-return)。
26    pub fn set_defensive_sanitize(&self, cfg: MinimalSanitizeConfig) {
27        let stored = if cfg.is_empty() { None } else { Some(cfg) };
28        *self.inner().defensive_cfg.write().unwrap() = stored;
29    }
30
31    /// 开启后,每次请求前 SDK 会从 `raw_messages` 中剥除带 `acosmi_ephemeral:true` 标记的 block,
32    /// 并联动剥除引用已剥 tool_use 的 tool_result,避免 provider 报 "tool_use_id 不存在"。
33    /// 对应 TS `setAutoStripEphemeralHistory`。
34    pub fn set_auto_strip_ephemeral_history(&self, on: bool) {
35        self.inner()
36            .auto_strip_ephemeral
37            .store(on, std::sync::atomic::Ordering::Relaxed);
38    }
39
40    /// 在 `build_chat_request` 开头调用,把配置化的防御策略应用到 `req`。未配置时立即返回,
41    /// 零开销。失败时返 `Err` —— 调用方应放弃本次请求。对应 TS `applyRequestSanitizers`。
42    pub(crate) fn apply_request_sanitizers(&self, req: &mut ChatRequest) -> Result<()> {
43        let cfg = self.inner().defensive_cfg.read().unwrap().clone();
44        let strip = self
45            .inner()
46            .auto_strip_ephemeral
47            .load(std::sync::atomic::Ordering::Relaxed);
48
49        if cfg.is_none() && !strip {
50            return Ok(());
51        }
52
53        // rawMessages 分支:归一化 → sanitize →(可选)strip → 写回。
54        if let Some(raw) = req.raw_messages.take() {
55            let mut msgs = normalize_raw_messages(raw).map_err(|e| {
56                crate::shared::Error::other(format!("sanitize: normalize raw messages: {e}"))
57            })?;
58            if let Some(c) = &cfg {
59                msgs = sanitize(msgs, c)?;
60            }
61            if strip {
62                msgs = strip_ephemeral(msgs);
63            }
64            req.raw_messages = Some(Value::Array(msgs));
65            return Ok(());
66        }
67
68        // 纯 messages 分支:block 级操作不适用,只做深度校验。
69        if let Some(c) = &cfg {
70            let max = c.max_messages_turns.unwrap_or(0);
71            let len = req.messages.as_ref().map(|m| m.len()).unwrap_or(0) as u64;
72            if max > 0 && len > max {
73                return Err(SanitizeError::HistoryTooDeep.into());
74            }
75        }
76
77        Ok(())
78    }
79}
80
81/// 把任意形态的 `raw_messages` 归一为 `Vec<Value>`。对应 TS `normalizeRawMessages`。
82///
83/// 已是 JSON 数组时直接拆出;其他形态报错("raw messages must be a JSON array")。
84/// `ChatRequest.raw_messages` 在 Rust 侧已是 `serde_json::Value`,故无需额外 JSON roundtrip。
85fn normalize_raw_messages(rm: Value) -> std::result::Result<Vec<Value>, String> {
86    match rm {
87        Value::Array(a) => Ok(a),
88        _ => Err("raw messages must be a JSON array".to_string()),
89    }
90}
91
92// SanitizeError → 顶层 Error(feature `sanitize` 下接通 `?` 链路)。
93impl From<SanitizeError> for crate::shared::Error {
94    fn from(e: SanitizeError) -> Self {
95        crate::shared::Error::other(e.to_string())
96    }
97}
98
99#[cfg(test)]
100mod tests {
101    use super::*;
102    use crate::core::{Client, Config};
103    use crate::sanitize::BlockType;
104    use serde_json::json;
105
106    fn client() -> Client {
107        struct NoNetwork;
108        #[async_trait::async_trait]
109        impl crate::HttpTransport for NoNetwork {
110            async fn execute(
111                &self,
112                _: crate::HttpRequest,
113                _: tokio_util::sync::CancellationToken,
114            ) -> std::result::Result<crate::HttpResponse, crate::TransportError> {
115                Err(crate::TransportError::Rejected)
116            }
117        }
118        Client::new_with_transport(Config::default(), std::sync::Arc::new(NoNetwork)).unwrap()
119    }
120
121    // ── 验收 apply_request_sanitizers 接通:未配置零开销 early-return ───────────────
122    #[test]
123    fn unconfigured_is_noop() {
124        let c = client();
125        let mut req = ChatRequest {
126            raw_messages: Some(json!([{ "role": "user", "content": [
127                { "type": "text", "text": "x", "acosmi_ephemeral": true }
128            ]}])),
129            ..Default::default()
130        };
131        let before = req.raw_messages.clone();
132        c.apply_request_sanitizers(&mut req).unwrap();
133        assert_eq!(req.raw_messages, before); // 未配置 → 原样不动。
134    }
135
136    // ── strip 分支:开启 auto-strip 剥 ephemeral,thinking 硬豁免 ──────────────────
137    #[test]
138    fn auto_strip_branch_applies() {
139        let c = client();
140        c.set_auto_strip_ephemeral_history(true);
141        let mut req = ChatRequest {
142            raw_messages: Some(json!([{ "role": "assistant", "content": [
143                { "type": "thinking", "thinking": "t", "acosmi_ephemeral": true },
144                { "type": "text", "text": "ephemeral", "acosmi_ephemeral": true },
145                { "type": "text", "text": "kept" }
146            ]}])),
147            ..Default::default()
148        };
149        c.apply_request_sanitizers(&mut req).unwrap();
150        let content = req.raw_messages.as_ref().unwrap()[0]["content"]
151            .as_array()
152            .unwrap();
153        let types: Vec<&str> = content
154            .iter()
155            .map(|b| b["type"].as_str().unwrap())
156            .collect();
157        assert_eq!(types, vec!["thinking", "text"]); // thinking 豁免、ephemeral text 剥、kept 留。
158    }
159
160    // ── defensive cfg 分支:媒体超限 → Err(放弃请求)────────────────────────────
161    #[test]
162    fn defensive_cfg_media_oversize_errors() {
163        let c = client();
164        c.set_defensive_sanitize(MinimalSanitizeConfig {
165            max_image_bytes: Some(2),
166            ..Default::default()
167        });
168        let mut req = ChatRequest {
169            raw_messages: Some(json!([{ "role": "user", "content": [
170                { "type": "image", "source": { "type": "base64", "data": "AAAA" } }
171            ]}])),
172            ..Default::default()
173        };
174        assert!(c.apply_request_sanitizers(&mut req).is_err());
175    }
176
177    // ── deny-list 分支生效 ──────────────────────────────────────────────────────
178    #[test]
179    fn defensive_cfg_deny_list_strips() {
180        let c = client();
181        c.set_defensive_sanitize(MinimalSanitizeConfig {
182            permanent_deny_blocks: vec![BlockType::Image],
183            ..Default::default()
184        });
185        let mut req = ChatRequest {
186            raw_messages: Some(json!([{ "role": "user", "content": [
187                { "type": "image", "source": { "type": "url", "url": "http://x/y" } },
188                { "type": "text", "text": "kept" }
189            ]}])),
190            ..Default::default()
191        };
192        c.apply_request_sanitizers(&mut req).unwrap();
193        let content = req.raw_messages.as_ref().unwrap()[0]["content"]
194            .as_array()
195            .unwrap();
196        assert_eq!(content.len(), 1);
197        assert_eq!(content[0]["type"], "text");
198    }
199
200    // ── 空 cfg 关闭(is_empty → None)等价语义 ───────────────────────────────────
201    #[test]
202    fn empty_cfg_disables() {
203        let c = client();
204        c.set_defensive_sanitize(MinimalSanitizeConfig::default()); // 空 = 关闭。
205        let mut req = ChatRequest {
206            raw_messages: Some(json!([{ "role": "user", "content": [
207                { "type": "text", "text": "x", "acosmi_ephemeral": true }
208            ]}])),
209            ..Default::default()
210        };
211        let before = req.raw_messages.clone();
212        c.apply_request_sanitizers(&mut req).unwrap();
213        assert_eq!(req.raw_messages, before);
214    }
215
216    // ── 纯 messages 分支:深度超限 HistoryTooDeep ───────────────────────────────
217    #[test]
218    fn pure_messages_depth_check() {
219        use crate::models::types::ChatMessage;
220        let c = client();
221        c.set_defensive_sanitize(MinimalSanitizeConfig {
222            max_messages_turns: Some(1),
223            ..Default::default()
224        });
225        let mut req = ChatRequest {
226            messages: Some(vec![ChatMessage::default(), ChatMessage::default()]),
227            ..Default::default()
228        };
229        assert!(c.apply_request_sanitizers(&mut req).is_err());
230    }
231
232    // ── normalize 失败(raw_messages 非数组)→ Err ──────────────────────────────
233    #[test]
234    fn normalize_non_array_errors() {
235        let c = client();
236        c.set_auto_strip_ephemeral_history(true);
237        let mut req = ChatRequest {
238            raw_messages: Some(json!({ "not": "an array" })),
239            ..Default::default()
240        };
241        assert!(c.apply_request_sanitizers(&mut req).is_err());
242    }
243}