Skip to main content

acosmi/notifications/
ws.rs

1//! WebSocket 长连接 —— `Client` 扩展。端口自 `notifications/ws.ts`(其端口自 `acosmi-sdk-go/ws.go`)。
2//!
3//! Go 用 gorilla/websocket,TS 用全局 WebSocket constructor,Rust 用 [`tokio_tungstenite`]
4//! (与 reqwest 同 rustls/webpki-roots backend)。
5//!
6//! **鉴权 = 一次性 stream-ticket 流程(v2.6.0 根因修复)**:网关 `/ws` 守卫为
7//! `StreamTicketOr(...)`,优先消费 `?ticket=`。每次(重)连接前用已鉴权客户端 POST
8//! `/ws/stream-ticket` 换一张短时一次性 ticket(~30-60s TTL,单次使用)放入 `?ticket=`,
9//! 取代旧的 `?token=` long-JWT(既对浏览器失效又把长效凭证暴露在 access log)。重连必须重铸 ticket。
10//!
11//! **重复 connect 防泄漏(ws-reconnect-leak)**:新 connect 前先 `disconnect` 旧连接,
12//! 否则旧 wsLoop 的后台自动重连定时器会与新连接并存 → 多个 socket + 多个 loop 泄漏。
13
14use super::types::WSEvent;
15use crate::core::client::Client;
16use crate::core::http::DEFAULT_JSON_TIMEOUT_MS;
17use crate::shared::{ApiResponse, Error, Result};
18use futures_util::{SinkExt, StreamExt};
19use serde::Deserialize;
20use std::sync::atomic::{AtomicBool, Ordering};
21use std::sync::Arc;
22use std::time::Duration;
23use tokio::sync::Notify;
24use tokio_tungstenite::tungstenite::Message;
25use tokio_util::sync::CancellationToken;
26
27/// 握手超时(30s,对应 TS handshakeTimer)。
28const HANDSHAKE_TIMEOUT_MS: u64 = 30_000;
29/// disconnect 等待读循环退出上限(5s,对应 TS Promise.race)。
30const DISCONNECT_DRAIN_MS: u64 = 5_000;
31
32type EventCb = Arc<dyn Fn(WSEvent) + Send + Sync>;
33type ConnectCb = Arc<dyn Fn() + Send + Sync>;
34type DisconnectCb = Arc<dyn Fn(String) + Send + Sync>;
35
36/// WebSocket 长连接配置。对应 TS `WSConfig`。
37#[derive(Clone, Default)]
38pub struct WSConfig {
39    /// 收到服务端事件回调。
40    pub on_event: Option<EventCb>,
41    /// 连接建立回调。
42    pub on_connect: Option<ConnectCb>,
43    /// 断线回调(携带原因字符串)。
44    pub on_disconnect: Option<DisconnectCb>,
45    /// 自动订阅的主题。
46    pub topics: Vec<String>,
47    /// 最小重连间隔(ms,默认 2000)。
48    pub reconnect_min_ms: Option<u64>,
49    /// 最大重连间隔(ms,默认 60000)。
50    pub reconnect_max_ms: Option<u64>,
51    /// 是否自动重连(默认 true)。
52    pub auto_reconnect: Option<bool>,
53}
54
55/// 填好缺省值的配置(对应 TS `Required<WSConfig>`)。
56#[derive(Clone)]
57struct FilledCfg {
58    on_event: EventCb,
59    on_connect: ConnectCb,
60    on_disconnect: DisconnectCb,
61    topics: Vec<String>,
62    reconnect_min_ms: u64,
63    reconnect_max_ms: u64,
64    auto_reconnect: bool,
65}
66
67impl FilledCfg {
68    fn from(cfg: WSConfig) -> Self {
69        FilledCfg {
70            on_event: cfg.on_event.unwrap_or_else(|| Arc::new(|_| {})),
71            on_connect: cfg.on_connect.unwrap_or_else(|| Arc::new(|| {})),
72            on_disconnect: cfg.on_disconnect.unwrap_or_else(|| Arc::new(|_| {})),
73            topics: cfg.topics,
74            reconnect_min_ms: cfg.reconnect_min_ms.unwrap_or(2000),
75            reconnect_max_ms: cfg.reconnect_max_ms.unwrap_or(60_000),
76            auto_reconnect: cfg.auto_reconnect.unwrap_or(true),
77        }
78    }
79}
80
81/// 存入 `ClientInner.ws` 的 WS 状态句柄(对应 TS `WSStateImpl`,core 保留具体 struct)。
82pub struct WsHandle {
83    /// 控制整个 ws loop 生命周期;`disconnect` cancel 之。
84    abort: CancellationToken,
85    /// 已连接标志(对应 TS `connected`)。
86    connected: Arc<AtomicBool>,
87    /// 读循环退出信号(对应 TS `done`)。
88    done: Arc<Notify>,
89}
90
91/// stream-ticket 响应载荷。
92#[derive(Deserialize)]
93struct StreamTicket {
94    ticket: String,
95    #[serde(rename = "expiresIn", default)]
96    #[allow(dead_code)]
97    expires_in: i64,
98}
99
100impl Client {
101    /// 建立 WebSocket 长连接 —— 等待首次连接成功或 abort。对应 TS `connect`。
102    pub async fn connect(&self, cfg: WSConfig, signal: Option<CancellationToken>) -> Result<()> {
103        if self.http().is_custom() {
104            return Err(crate::core::transport::TransportError::UnsupportedWebSocket.into());
105        }
106        // 幂等化重复 connect:先优雅断开旧连接(防 ws-reconnect-leak)。
107        self.disconnect().await;
108
109        let filled = FilledCfg::from(cfg);
110
111        let abort = CancellationToken::new();
112        // parent signal 取消 → 联动 abort(对应 TS signal.addEventListener('abort', ...))。
113        if let Some(sig) = signal {
114            if sig.is_cancelled() {
115                abort.cancel();
116            } else {
117                let a = abort.clone();
118                tokio::spawn(async move {
119                    sig.cancelled().await;
120                    a.cancel();
121                });
122            }
123        }
124
125        let connected = Arc::new(AtomicBool::new(false));
126        let done = Arc::new(Notify::new());
127
128        // 首次连接 —— 失败抛出。
129        let conn = self.ws_connect_once(&filled, &abort, &connected).await?;
130
131        // 安装句柄。
132        *self.ws_slot().lock().await = Some(WsHandle {
133            abort: abort.clone(),
134            connected: connected.clone(),
135            done: done.clone(),
136        });
137
138        // 后台读循环 + 自动重连。
139        let client = self.clone();
140        tokio::spawn(async move {
141            ws_loop(client, filled, abort, connected, done, conn).await;
142        });
143
144        Ok(())
145    }
146
147    /// 优雅断开 WebSocket 连接。对应 TS `disconnect`。
148    pub async fn disconnect(&self) {
149        let handle = self.ws_slot().lock().await.take();
150        let handle = match handle {
151            Some(h) => h,
152            None => return,
153        };
154        handle.abort.cancel();
155        handle.connected.store(false, Ordering::SeqCst);
156
157        // 等待读循环退出(最多 5s)。
158        let drain = handle.done.notified();
159        tokio::select! {
160            _ = drain => {}
161            _ = tokio::time::sleep(Duration::from_millis(DISCONNECT_DRAIN_MS)) => {}
162        }
163    }
164
165    /// WebSocket 是否已连接。对应 TS `isConnected`。
166    pub async fn is_connected(&self) -> bool {
167        match self.ws_slot().lock().await.as_ref() {
168            Some(h) => h.connected.load(Ordering::SeqCst),
169            None => false,
170        }
171    }
172
173    /// 单次连接(铸 ticket → 拨号 → 等 welcome → 自动订阅)。对应 TS `wsConnectOnce`。
174    /// 返回已就绪的 WS 流(已读掉 welcome,已发完订阅)。
175    async fn ws_connect_once(
176        &self,
177        cfg: &FilledCfg,
178        abort: &CancellationToken,
179        connected: &Arc<AtomicBool>,
180    ) -> Result<WsStream> {
181        let url = ws_url(self);
182
183        // 鉴权 —— 一次性 stream ticket 流程。
184        let (bytes, _) = self
185            .do_json_full_raw(
186                http::Method::POST,
187                "/ws/stream-ticket",
188                None,
189                Some(abort.clone()),
190                DEFAULT_JSON_TIMEOUT_MS,
191                None,
192            )
193            .await?;
194        let env: ApiResponse<StreamTicket> = serde_json::from_slice(&bytes)
195            .map_err(|e| Error::other(format!("/ws/stream-ticket: decode: {e}")))?;
196        if let Some(err) = env.business_error() {
197            return Err(err);
198        }
199        let ticket = env.data.ticket;
200
201        let full_url = append_ticket(&url, &ticket);
202
203        // 拨号(带握手超时 + abort 联动)。
204        let dial = tokio_tungstenite::connect_async(&full_url);
205        let (mut conn, _resp) = tokio::select! {
206            r = dial => r.map_err(|e| Error::other(format!("dial: {e}")))?,
207            _ = abort.cancelled() => return Err(Error::other("dial: aborted")),
208            _ = tokio::time::sleep(Duration::from_millis(HANDSHAKE_TIMEOUT_MS)) => {
209                return Err(Error::other("dial: handshake timeout"));
210            }
211        };
212
213        // 等待首条 message(应为 welcome),带握手超时。
214        let welcome = tokio::select! {
215            msg = next_text(&mut conn) => msg?,
216            _ = abort.cancelled() => {
217                let _ = conn.close(None).await;
218                return Err(Error::other("dial: aborted"));
219            }
220            _ = tokio::time::sleep(Duration::from_millis(HANDSHAKE_TIMEOUT_MS)) => {
221                let _ = conn.close(None).await;
222                return Err(Error::other("dial: handshake timeout"));
223            }
224        };
225        let welcome: WSEvent = serde_json::from_str(&welcome)
226            .map_err(|e| Error::other(format!("parse welcome: {e}")))?;
227        if welcome.r#type != "welcome" {
228            let _ = conn.close(None).await;
229            return Err(Error::other(format!(
230                "unexpected first message: {}",
231                welcome.r#type
232            )));
233        }
234
235        connected.store(true, Ordering::SeqCst);
236
237        // 自动订阅主题。
238        if !cfg.topics.is_empty() {
239            let sub = serde_json::json!({ "type": "subscribe", "topics": cfg.topics }).to_string();
240            if let Err(e) = conn.send(Message::Text(sub)).await {
241                connected.store(false, Ordering::SeqCst);
242                let _ = conn.close(None).await;
243                return Err(Error::other(format!("send subscribe: {e}")));
244            }
245        }
246
247        (cfg.on_connect)();
248        Ok(conn)
249    }
250}
251
252/// WS 流类型别名(tungstenite over MaybeTlsStream)。
253type WsStream =
254    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;
255
256/// 读取下一条文本 message(忽略 ping/pong/binary,遇 close/错误抛 Err)。
257async fn next_text(conn: &mut WsStream) -> Result<String> {
258    loop {
259        match conn.next().await {
260            Some(Ok(Message::Text(t))) => return Ok(t),
261            Some(Ok(Message::Binary(b))) => return Ok(String::from_utf8_lossy(&b).into_owned()),
262            Some(Ok(Message::Close(_))) => return Err(Error::other("closed")),
263            Some(Ok(_)) => continue, // ping/pong/frame → 跳过。
264            Some(Err(e)) => return Err(Error::other(format!("read: {e}"))),
265            None => return Err(Error::other("closed")),
266        }
267    }
268}
269
270/// 后台读循环 + 自动重连(指数退避)。对应 TS `wsLoop`。
271async fn ws_loop(
272    client: Client,
273    cfg: FilledCfg,
274    abort: CancellationToken,
275    connected: Arc<AtomicBool>,
276    done: Arc<Notify>,
277    mut conn: WsStream,
278) {
279    loop {
280        // 读循环:阻塞直到连接关闭/出错/abort。
281        ws_read_loop(&cfg, &abort, &connected, &mut conn).await;
282
283        if abort.is_cancelled() {
284            break;
285        }
286
287        // 关闭旧连接,防 FD 泄漏。
288        let _ = conn.close(None).await;
289        connected.store(false, Ordering::SeqCst);
290
291        if !cfg.auto_reconnect {
292            break;
293        }
294
295        // 自动重连(指数退避)。
296        let mut delay = cfg.reconnect_min_ms;
297        let reconnected = loop {
298            if abort.is_cancelled() {
299                break None;
300            }
301            tokio::select! {
302                _ = tokio::time::sleep(Duration::from_millis(delay)) => {}
303                _ = abort.cancelled() => break None,
304            }
305            if abort.is_cancelled() {
306                break None;
307            }
308            match client.ws_connect_once(&cfg, &abort, &connected).await {
309                Ok(c) => break Some(c),
310                Err(_) => {
311                    delay = (delay * 2).min(cfg.reconnect_max_ms);
312                }
313            }
314        };
315        match reconnected {
316            Some(c) => conn = c,
317            None => break,
318        }
319    }
320    done.notify_waiters();
321}
322
323/// 单连接读循环(对应 TS `wsReadLoop`)。message → on_event;close/error/abort → 退出 + on_disconnect。
324async fn ws_read_loop(
325    cfg: &FilledCfg,
326    abort: &CancellationToken,
327    connected: &Arc<AtomicBool>,
328    conn: &mut WsStream,
329) {
330    loop {
331        tokio::select! {
332            _ = abort.cancelled() => {
333                let _ = conn.close(None).await;
334                connected.store(false, Ordering::SeqCst);
335                return;
336            }
337            next = conn.next() => {
338                match next {
339                    Some(Ok(Message::Text(t))) => {
340                        if let Ok(ev) = serde_json::from_str::<WSEvent>(&t) {
341                            (cfg.on_event)(ev);
342                        }
343                        // 解析失败忽略(对应 TS catch)。
344                    }
345                    Some(Ok(Message::Binary(b))) => {
346                        if let Ok(ev) = serde_json::from_slice::<WSEvent>(&b) {
347                            (cfg.on_event)(ev);
348                        }
349                    }
350                    Some(Ok(Message::Close(frame))) => {
351                        connected.store(false, Ordering::SeqCst);
352                        let reason = frame
353                            .map(|f| format!("closed: code={} reason={}", u16::from(f.code), f.reason))
354                            .unwrap_or_else(|| "closed".to_string());
355                        (cfg.on_disconnect)(reason);
356                        return;
357                    }
358                    Some(Ok(_)) => { /* ping/pong/frame:tungstenite 自动回 pong,跳过。 */ }
359                    Some(Err(e)) => {
360                        connected.store(false, Ordering::SeqCst);
361                        (cfg.on_disconnect)(format!("error: {e}"));
362                        return;
363                    }
364                    None => {
365                        connected.store(false, Ordering::SeqCst);
366                        (cfg.on_disconnect)("closed".to_string());
367                        return;
368                    }
369                }
370            }
371        }
372    }
373}
374
375/// `{api}/ws` → ws://wss:// scheme(对应 TS `wsURL`)。
376fn ws_url(c: &Client) -> String {
377    let base = c.api_url("/ws");
378    if let Some(rest) = base.strip_prefix("https://") {
379        format!("wss://{rest}")
380    } else if let Some(rest) = base.strip_prefix("http://") {
381        format!("ws://{rest}")
382    } else {
383        base
384    }
385}
386
387/// 追加 `?ticket=`/`&ticket=`(对应 TS `u.searchParams.set('ticket', ...)`)。
388fn append_ticket(url: &str, ticket: &str) -> String {
389    let sep = if url.contains('?') { '&' } else { '?' };
390    format!(
391        "{url}{sep}ticket={}",
392        crate::billing::entitlements::urlencoding(ticket)
393    )
394}
395
396#[cfg(test)]
397mod tests {
398    use super::*;
399
400    #[test]
401    fn ws_url_scheme_swap() {
402        // api_url 拼接逻辑由 Client::api_url 负责;这里仅验 scheme 替换函数。
403        assert_eq!(
404            append_ticket("wss://h/api/v4/ws", "T1"),
405            "wss://h/api/v4/ws?ticket=T1"
406        );
407        assert_eq!(
408            append_ticket("wss://h/api/v4/ws?x=1", "T2"),
409            "wss://h/api/v4/ws?x=1&ticket=T2"
410        );
411    }
412}