Skip to main content

ydp_core/
websocket.rs

1//! WebSocket 消息适配器;只连接明确 endpoint,不发现、重连或启动浏览器。
2#[cfg(feature = "rustls")]
3use std::sync::Arc;
4use std::time::Duration;
5
6use bytes::Bytes;
7use futures_util::{
8    SinkExt, StreamExt,
9    stream::{SplitSink, SplitStream},
10};
11use tokio::io::{AsyncRead, AsyncWrite};
12use tokio_tungstenite::{
13    WebSocketStream,
14    tungstenite::{
15        self, Message,
16        client::IntoClientRequest,
17        http::{HeaderName, HeaderValue},
18        protocol::WebSocketConfig,
19    },
20};
21
22use crate::{
23    Connection, Error, ErrorKind, MessageReader, MessageWriter, RawEventStream, Result,
24    RuntimeOptions, Transport, TransportError,
25};
26
27/// TLS 信任配置;默认使用固定依赖的 webpki 根,不修改全进程 provider。
28#[derive(Clone, Default)]
29pub struct TlsOptions {
30    /// 额外信任的 PEM 证书集合,可在一个字节数组中串联多个 CA。
31    /// 空数组表示只用默认根;无证书、损坏 PEM 或非法证书在联网前失败。
32    pub additional_ca_pem: Vec<u8>,
33}
34impl std::fmt::Debug for TlsOptions {
35    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
36        f.debug_struct("TlsOptions")
37            .field("additional_ca_bytes", &self.additional_ca_pem.len())
38            .finish()
39    }
40}
41
42/// 明确 WebSocket endpoint 的连接选项;不含重试、跳过证书验证或重定向设置。
43#[derive(Clone)]
44pub struct ConnectOptions {
45    /// 连接内资源、初始 All 订阅和关闭预算。
46    pub runtime: RuntimeOptions,
47    /// DNS、TCP、TLS 和 WebSocket 握手共享的总期限,默认 10 秒。
48    pub connect_timeout: Duration,
49    /// 保留输入顺序的附加 HTTP 头;值不能含 CR/LF,禁止覆盖握手保留头。
50    pub headers: Vec<(String, String)>,
51    /// 默认根与可选额外 CA;不保存客户端私钥或认证状态。
52    pub tls: TlsOptions,
53}
54impl Default for ConnectOptions {
55    fn default() -> Self {
56        Self {
57            runtime: RuntimeOptions::default(),
58            connect_timeout: Duration::from_secs(10),
59            headers: Vec::new(),
60            tls: TlsOptions::default(),
61        }
62    }
63}
64impl std::fmt::Debug for ConnectOptions {
65    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
66        f.debug_struct("ConnectOptions")
67            .field("runtime", &self.runtime)
68            .field("connect_timeout", &self.connect_timeout)
69            .field("header_count", &self.headers.len())
70            .field("tls", &self.tls)
71            .finish()
72    }
73}
74
75impl Connection {
76    /// 异步连接完整 ws/wss URL,成功返回连接和已经注册的初始 All 事件流。
77    /// 握手前校验选项、头字段和 CA;失败不重试、不跟随 HTTP 重定向。
78    /// 认证头只发给指定 endpoint,Debug 不输出头值或 URL。
79    /// 需要 Tokio runtime 启用 IO 与 time;缺 Handle 返回 NoRuntime,禁用 driver
80    /// 属调用方配置错误,Tokio 可能 panic。丢弃此 Future 会销毁尚未交付的传输。
81    /// 关闭 `rustls` feature 后只接受 ws,附加 CA 配置也会被拒绝。
82    /// ```no_run
83    /// # async fn example() -> ydp_core::Result<()> {
84    /// let (connection, events) = ydp_core::Connection::connect(
85    ///     "ws://127.0.0.1:9222/devtools/browser/example",
86    ///     ydp_core::ConnectOptions::default(),
87    /// ).await?;
88    /// drop(events);
89    /// let report = connection.close().await;
90    /// assert!(report.driver_resources_released);
91    /// # Ok(()) }
92    /// ```
93    pub async fn connect(
94        endpoint: &str,
95        options: ConnectOptions,
96    ) -> Result<(Self, RawEventStream)> {
97        if tokio::runtime::Handle::try_current().is_err() {
98            return Err(Error::new(ErrorKind::NoRuntime));
99        }
100        crate::runtime::validate_options(&options.runtime)?;
101        let deadline = tokio::time::Instant::now()
102            .checked_add(options.connect_timeout)
103            .ok_or_else(|| Error::new(ErrorKind::InvalidArgument))?;
104        if options.connect_timeout.is_zero() {
105            return Err(Error::new(ErrorKind::Timeout));
106        }
107        let request = prepare_request(endpoint, &options.headers)?;
108        #[cfg(feature = "rustls")]
109        let connector = Some(tokio_tungstenite::Connector::Rustls(tls_config(
110            &options.tls,
111        )?));
112        #[cfg(not(feature = "rustls"))]
113        if request.uri().scheme_str() == Some("wss") || !options.tls.additional_ca_pem.is_empty() {
114            return Err(Error::new(ErrorKind::InvalidArgument));
115        }
116        let limits = &options.runtime.limits;
117        let write_limit = limits
118            .normal
119            .max_command_bytes
120            .max(limits.control.max_command_bytes)
121            .checked_add(64 * 1024 + 1024)
122            .ok_or_else(|| Error::new(ErrorKind::InvalidArgument))?;
123        let config = WebSocketConfig::default()
124            .max_message_size(Some(limits.max_message_bytes))
125            .max_frame_size(Some(limits.max_message_bytes))
126            .write_buffer_size(64 * 1024)
127            .max_write_buffer_size(write_limit);
128        let handshake = async {
129            #[cfg(feature = "rustls")]
130            let result = tokio_tungstenite::connect_async_tls_with_config(
131                request,
132                Some(config),
133                false,
134                connector,
135            )
136            .await;
137            #[cfg(not(feature = "rustls"))]
138            let result =
139                tokio_tungstenite::connect_async_with_config(request, Some(config), false).await;
140            result.map_err(|error| Error::with_source(ErrorKind::Transport, error))
141        };
142        let (socket, _response) = tokio::time::timeout_at(deadline, handshake)
143            .await
144            .map_err(|_| Error::new(ErrorKind::Timeout))??;
145        Self::from_transport(SocketTransport(socket), options.runtime)
146    }
147}
148
149const HEADER_LIMIT: usize = 64 * 1024;
150fn prepare_request(
151    endpoint: &str,
152    headers: &[(String, String)],
153) -> Result<tungstenite::handshake::client::Request> {
154    let mut size = endpoint.len();
155    if size > HEADER_LIMIT {
156        return Err(Error::new(ErrorKind::ResourceLimit {
157            resource: "出站握手头字节",
158        }));
159    }
160    for (name, value) in headers {
161        size = size
162            .checked_add(name.len())
163            .and_then(|n| n.checked_add(value.len()))
164            .and_then(|n| n.checked_add(4))
165            .ok_or_else(|| {
166                Error::new(ErrorKind::ResourceLimit {
167                    resource: "出站握手头字节",
168                })
169            })?;
170        if size > HEADER_LIMIT {
171            return Err(Error::new(ErrorKind::ResourceLimit {
172                resource: "出站握手头字节",
173            }));
174        }
175        if value.bytes().any(|b| b == b'\r' || b == b'\n') {
176            return Err(Error::new(ErrorKind::InvalidArgument));
177        }
178        let lower = name.to_ascii_lowercase();
179        if [
180            "host",
181            "upgrade",
182            "connection",
183            "content-length",
184            "transfer-encoding",
185        ]
186        .contains(&lower.as_str())
187            || lower.starts_with("sec-websocket-")
188        {
189            return Err(Error::new(ErrorKind::InvalidArgument));
190        }
191    }
192    let mut request = endpoint
193        .into_client_request()
194        .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
195    if !matches!(request.uri().scheme_str(), Some("ws" | "wss")) || request.uri().host().is_none() {
196        return Err(Error::new(ErrorKind::InvalidArgument));
197    }
198    for (name, value) in headers {
199        let name = HeaderName::from_bytes(name.as_bytes())
200            .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
201        let mut value = HeaderValue::from_str(value)
202            .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
203        value.set_sensitive(true);
204        request.headers_mut().append(name, value);
205    }
206    // 精确校验库实际生成的请求大小;此额外编码仅发生在连接握手冷路径。
207    let (encoded, _) = tungstenite::handshake::client::generate_request(request.clone())
208        .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
209    if encoded.len() > HEADER_LIMIT {
210        return Err(Error::new(ErrorKind::ResourceLimit {
211            resource: "出站握手头字节",
212        }));
213    }
214    Ok(request)
215}
216
217#[cfg(feature = "rustls")]
218fn tls_config(options: &TlsOptions) -> Result<Arc<rustls::ClientConfig>> {
219    let mut roots = rustls::RootCertStore::empty();
220    roots.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
221    if !options.additional_ca_pem.is_empty() {
222        let mut input = options.additional_ca_pem.as_slice();
223        let certificates = rustls_pemfile::certs(&mut input)
224            .collect::<std::result::Result<Vec<_>, _>>()
225            .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
226        if certificates.is_empty() {
227            return Err(Error::new(ErrorKind::InvalidArgument));
228        }
229        for certificate in certificates {
230            roots
231                .add(certificate)
232                .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?;
233        }
234    }
235    let config = rustls::ClientConfig::builder_with_provider(Arc::new(
236        rustls::crypto::ring::default_provider(),
237    ))
238    .with_safe_default_protocol_versions()
239    .map_err(|e| Error::with_source(ErrorKind::InvalidArgument, e))?
240    .with_root_certificates(roots)
241    .with_no_client_auth();
242    Ok(Arc::new(config))
243}
244
245struct SocketTransport<S>(WebSocketStream<S>);
246struct SocketReader<S> {
247    stream: SplitStream<WebSocketStream<S>>,
248}
249struct SocketWriter<S> {
250    sink: SplitSink<WebSocketStream<S>, Message>,
251}
252impl<S: AsyncRead + AsyncWrite + Send + Unpin + 'static> Transport for SocketTransport<S> {
253    type Reader = SocketReader<S>;
254    type Writer = SocketWriter<S>;
255    fn split(self) -> (Self::Reader, Self::Writer) {
256        let (sink, stream) = self.0.split();
257        (SocketReader { stream }, SocketWriter { sink })
258    }
259}
260impl<S: AsyncRead + AsyncWrite + Send + Unpin + 'static> MessageReader for SocketReader<S> {
261    async fn recv(&mut self) -> std::result::Result<Option<Bytes>, TransportError> {
262        let mut controls = 0usize;
263        loop {
264            match self.stream.next().await {
265                Some(Ok(Message::Text(text))) => return Ok(Some(text.into())),
266                Some(Ok(Message::Binary(_))) => {
267                    return Err(TransportError::new(std::io::Error::new(
268                        std::io::ErrorKind::InvalidData,
269                        "不支持 WebSocket binary 消息",
270                    )));
271                }
272                Some(Ok(Message::Close(_))) | None => return Ok(None),
273                Some(Ok(Message::Ping(_) | Message::Pong(_))) => {
274                    // 持续读 poll 复用依赖的有界 Pong 槽;不手动发送第二个 Pong。
275                    controls += 1;
276                    if controls == 256 {
277                        controls = 0;
278                        tokio::task::yield_now().await;
279                    }
280                }
281                Some(Ok(Message::Frame(_))) => {
282                    return Err(TransportError::new(std::io::Error::new(
283                        std::io::ErrorKind::InvalidData,
284                        "适配器收到未组装 frame",
285                    )));
286                }
287                Some(Err(
288                    tungstenite::Error::ConnectionClosed | tungstenite::Error::AlreadyClosed,
289                )) => return Ok(None),
290                Some(Err(error)) => return Err(TransportError::new(error)),
291            }
292        }
293    }
294}
295impl<S: AsyncRead + AsyncWrite + Send + Unpin + 'static> MessageWriter for SocketWriter<S> {
296    async fn send(&mut self, bytes: Bytes) -> std::result::Result<(), TransportError> {
297        let text = tungstenite::Utf8Bytes::try_from(bytes).map_err(TransportError::new)?;
298        self.sink
299            .feed(Message::Text(text))
300            .await
301            .map_err(TransportError::new)
302    }
303    async fn flush(&mut self) -> std::result::Result<(), TransportError> {
304        self.sink.flush().await.map_err(TransportError::new)
305    }
306    async fn close(&mut self) -> std::result::Result<(), TransportError> {
307        match self.sink.close().await {
308            Ok(())
309            | Err(tungstenite::Error::ConnectionClosed | tungstenite::Error::AlreadyClosed) => {
310                Ok(())
311            }
312            Err(error) => Err(TransportError::new(error)),
313        }
314    }
315}
316
317#[cfg(test)]
318mod tests {
319    use super::*;
320    use tungstenite::protocol::Role;
321
322    #[tokio::test]
323    async fn blocked_framed_writer_keeps_reader_and_pong_progress() {
324        tokio::time::timeout(Duration::from_secs(5), async {
325            // 小容量双向字节管道强制部分帧写入 Pending,仍运行真实 WebSocket 编解码。
326            let (client_io, server_io) = tokio::io::duplex(128);
327            let client = WebSocketStream::from_raw_socket(client_io, Role::Client, None).await;
328            let mut server = WebSocketStream::from_raw_socket(server_io, Role::Server, None).await;
329            let (mut reader, mut writer) = SocketTransport(client).split();
330            let payload = Bytes::from(vec![b'x'; 256 * 1024]);
331            let write = async {
332                writer.send(payload).await?;
333                writer.flush().await
334            };
335            tokio::pin!(write);
336            assert!(futures_util::poll!(write.as_mut()).is_pending());
337            server
338                .send(Message::Ping(Bytes::from_static(b"ping")))
339                .await
340                .unwrap();
341            server
342                .send(Message::Text("response while blocked".into()))
343                .await
344                .unwrap();
345            let received = reader.recv().await.unwrap().unwrap();
346            assert_eq!(&received[..], b"response while blocked");
347            assert!(futures_util::poll!(write.as_mut()).is_pending());
348            let receive = async {
349                let mut pong = false;
350                let mut data = false;
351                while !(pong && data) {
352                    match server.next().await.unwrap().unwrap() {
353                        Message::Pong(bytes) => {
354                            assert_eq!(&bytes[..], b"ping");
355                            pong = true;
356                        }
357                        Message::Text(text) => {
358                            assert_eq!(text.len(), 256 * 1024);
359                            data = true;
360                        }
361                        other => panic!("非预期测试消息:{other:?}"),
362                    }
363                }
364            };
365            // 释放读取背压后,原 write Future 与自动 Pong 均必须完成,无重发。
366            let (_, result) = tokio::join!(receive, write);
367            result.unwrap();
368        })
369        .await
370        .unwrap();
371    }
372
373    #[tokio::test(start_paused = true)]
374    async fn connection_close_destroys_partial_frame_after_total_budget() {
375        use tokio::io::AsyncReadExt;
376        let (client_io, mut peer_io) = tokio::io::duplex(128);
377        let client = WebSocketStream::from_raw_socket(client_io, Role::Client, None).await;
378        let options = RuntimeOptions {
379            close_timeout: Duration::from_millis(10),
380            ..Default::default()
381        };
382        let (connection, events) =
383            Connection::from_transport(SocketTransport(client), options).unwrap();
384        drop(events);
385        let params = crate::RawJson::from_bytes(Bytes::from(format!(
386            "{{\"text\":\"{}\"}}",
387            "x".repeat(256 * 1024)
388        )))
389        .unwrap();
390        let request = connection.root_session().send_raw(
391            crate::MethodName::new("Echo.large".into()).unwrap(),
392            params,
393            Default::default(),
394        );
395        tokio::pin!(request);
396        assert!(futures_util::poll!(request.as_mut()).is_pending());
397        let mut first = [0; 1];
398        peer_io.read_exact(&mut first).await.unwrap();
399        // 已观察到帧首字节后停止读取,强制关闭面对部分写入。
400        let close = connection.close();
401        tokio::pin!(close);
402        assert!(futures_util::poll!(close.as_mut()).is_pending());
403        tokio::time::advance(Duration::from_millis(11)).await;
404        let report = close.await;
405        assert!(report.driver_resources_released);
406        assert_eq!(report.transport_end, crate::TransportEnd::Aborted);
407        assert!(request.await.is_err());
408        let mut remaining = Vec::new();
409        peer_io.read_to_end(&mut remaining).await.unwrap();
410        assert!(remaining.len() <= 128);
411    }
412
413    #[test]
414    fn exact_outbound_header_boundary_and_utf8_sharing() {
415        let request = prepare_request("ws://127.0.0.1/", &[]).unwrap();
416        let base = tungstenite::handshake::client::generate_request(request)
417            .unwrap()
418            .0
419            .len();
420        let name = "x-boundary";
421        let value = "x".repeat(HEADER_LIMIT - base - name.len() - 4);
422        assert!(prepare_request("ws://127.0.0.1/", &[(name.into(), value.clone())]).is_ok());
423        assert!(prepare_request("ws://127.0.0.1/", &[(name.into(), value + "x")]).is_err());
424        let bytes = Bytes::from(String::from("UTF8 中文"));
425        let ptr = bytes.as_ptr();
426        let text = tungstenite::Utf8Bytes::try_from(bytes).unwrap();
427        let back: Bytes = text.into();
428        assert_eq!(back.as_ptr(), ptr);
429    }
430}